storekit

package
v1.261010.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Oct 10, 2026 License: MIT Imports: 25 Imported by: 0

Documentation

Overview

Package storekit implements Apple's In-App Purchase and StoreKit server APIs: the App Store Server API and the Retention Messaging API.

StoreKit API credentials are intentionally separate from App Store Connect API credentials. The client signs a fresh JWT for every request.

Index

Constants

View Source 
const (
	ProductionBaseURL = "https://api.storekit.apple.com"
	SandboxBaseURL    = "https://api.storekit-sandbox.apple.com"
)
View Source 
const (
	StatePending  = "PENDING"
	StateApproved = "APPROVED"
	StateRejected = "REJECTED"
)

Variables

View Source 
var (
	// SignedTransactionPages covers Get Transaction History and Get Refund History.
	SignedTransactionPages   = PageCursor{ItemsKey: "signedTransactions", TokenKey: "revision"}
	NotificationHistoryPages = PageCursor{ItemsKey: "notificationHistory", TokenKey: "paginationToken"}
	GroupMemberPages         = PageCursor{ItemsKey: "members", TokenKey: "paginationToken"}
)

Functions

func AddDecodedJWSPayloads 

func AddDecodedJWSPayloads(raw json.RawMessage) (json.RawMessage, error)

AddDecodedJWSPayloads returns raw with a "<field>Decoded" sibling next to every signed* string or string-array field, holding the unverified payload. Signed fields inside decoded payloads are decoded too. Existing fields are never changed.

func CollectPages 

func CollectPages(first json.RawMessage, cursor PageCursor, next func(token string) (json.RawMessage, error)) (json.RawMessage, error)

CollectPages follows hasMore and the continuation token from first, and returns the final page's envelope with every page's items concatenated. The final page keeps Apple's last token, which callers can store to resume.

func DecodeJWSPayloadUnverified 

func DecodeJWSPayloadUnverified(token string) (json.RawMessage, error)

DecodeJWSPayloadUnverified returns the JSON payload of an Apple-signed compact JWS. It does NOT verify the signature or certificate chain, so the result must not be trusted as proof of a purchase.

func RemoveAllCredentials 

func RemoveAllCredentials() error

func RemoveCredentials 

func RemoveCredentials(name string) error

func SetDefaultCredentials 

func SetDefaultCredentials(name string) error

func ShouldBypassKeychain 

func ShouldBypassKeychain() bool

ShouldBypassKeychain reports whether StoreKit keychain access is disabled.

func StoreCredentials 

func StoreCredentials(name string, credentials Credentials) error

StoreCredentials stores a credential in the system keychain when available.

func StoreCredentialsConfig 

func StoreCredentialsConfig(name string, credentials Credentials) error

func StoreCredentialsConfigAt 

func StoreCredentialsConfigAt(name string, credentials Credentials, path string) error

func ValidateMessage 

func ValidateMessage(message Message) error

ValidateMessage checks documented Retention Messaging limits before upload.

func ValidateRealtimeURL 

func ValidateRealtimeURL(value string) error

Types

type APIError 

type APIError struct {
	StatusCode int
	Code       string
	Message    string
	RetryAfter time.Time
	Body       string
}

APIError describes an error returned by the Retention Messaging API.

func (*APIError) Error 

func (e *APIError) Error() string

func (*APIError) HTTPStatusCode added in v1.260713.0 

func (e *APIError) HTTPStatusCode() int

type Client 

type Client struct {
	// contains filtered or unexported fields
}

func NewClient 

func NewClient(credentials Credentials, environment Environment, opts ...ClientOption) (*Client, error)

func (*Client) DeleteDefault 

func (c *Client) DeleteDefault(ctx context.Context, productID, locale string) error

func (*Client) DeleteImage 

func (c *Client) DeleteImage(ctx context.Context, identifier string) error

func (*Client) DeleteMessage 

func (c *Client) DeleteMessage(ctx context.Context, identifier string) error

func (*Client) DeleteRealtimeURL 

func (c *Client) DeleteRealtimeURL(ctx context.Context) error

func (*Client) GetAllSubscriptionStatuses 

func (c *Client) GetAllSubscriptionStatuses(ctx context.Context, transactionID string, statuses []int) (json.RawMessage, error)

GetAllSubscriptionStatuses calls Get All Subscription Statuses.

func (*Client) GetCustomerGroups 

func (c *Client) GetCustomerGroups(ctx context.Context, transactionID string) (json.RawMessage, error)

GetCustomerGroups calls Get Customer Groups.

func (*Client) GetDefault 

func (c *Client) GetDefault(ctx context.Context, productID, locale string) (*DefaultMessageResponse, error)

func (*Client) GetGroupMembers 

func (c *Client) GetGroupMembers(ctx context.Context, groupID string, limit int, paginationToken string) (json.RawMessage, error)

GetGroupMembers calls Get Group Members. A zero limit uses Apple's default.

func (*Client) GetNotificationHistory 

func (c *Client) GetNotificationHistory(ctx context.Context, request NotificationHistoryRequest, paginationToken string) (json.RawMessage, error)

GetNotificationHistory calls Get Notification History. Apple transports this read as a POST, so it is marked as a read for read-only mode.

func (*Client) GetPerformanceTestResult 

func (c *Client) GetPerformanceTestResult(ctx context.Context, requestID string) (*PerformanceTestResult, error)

func (*Client) GetRealtimeURL 

func (c *Client) GetRealtimeURL(ctx context.Context) (*RealtimeURLResponse, error)

func (*Client) GetRefundHistory 

func (c *Client) GetRefundHistory(ctx context.Context, transactionID, revision string) (json.RawMessage, error)

GetRefundHistory calls Get Refund History (v2). revision is empty for the first page.

func (*Client) GetTestNotificationStatus 

func (c *Client) GetTestNotificationStatus(ctx context.Context, testNotificationToken string) (json.RawMessage, error)

GetTestNotificationStatus calls Get Test Notification Status.

func (*Client) GetTransactionHistory 

func (c *Client) GetTransactionHistory(ctx context.Context, transactionID string, query TransactionHistoryQuery, revision string) (json.RawMessage, error)

GetTransactionHistory calls Get Transaction History (v2). revision is empty for the first page.

func (*Client) GetTransactionInfo 

func (c *Client) GetTransactionInfo(ctx context.Context, transactionID string) (json.RawMessage, error)

GetTransactionInfo calls Get Transaction Info.

func (*Client) ListImages 

func (c *Client) ListImages(ctx context.Context) (*ImageListResponse, error)

func (*Client) ListMessages 

func (c *Client) ListMessages(ctx context.Context) (*MessageListResponse, error)

func (*Client) LookUpOrderID 

func (c *Client) LookUpOrderID(ctx context.Context, orderID string) (json.RawMessage, error)

LookUpOrderID calls Look Up Order ID.

func (*Client) RequestTestNotification 

func (c *Client) RequestTestNotification(ctx context.Context) (json.RawMessage, error)

RequestTestNotification calls Request a Test Notification, which asks the App Store to send a TEST notification to the configured server URL.

func (*Client) SetDefault 

func (c *Client) SetDefault(ctx context.Context, productID, locale, messageIdentifier string) (*DefaultMessageResponse, error)

func (*Client) SetRealtimeURL 

func (c *Client) SetRealtimeURL(ctx context.Context, realtimeURL string) (*RealtimeURLResponse, error)

func (*Client) StartPerformanceTest 

func (c *Client) StartPerformanceTest(ctx context.Context, originalTransactionID string) (*PerformanceTestStartResponse, error)

func (*Client) UploadImage 

func (c *Client) UploadImage(ctx context.Context, identifier string, size ImageSize, data []byte) error

func (*Client) UploadMessage 

func (c *Client) UploadMessage(ctx context.Context, identifier string, message Message) error

func (*Client) Validate 

func (c *Client) Validate() error

Validate signs a token and parses the configured private key without making a network request.

type ClientOption 

type ClientOption func(*Client)

func WithBaseURL 

func WithBaseURL(baseURL string) ClientOption

WithBaseURL overrides the StoreKit server API host URL that request paths such as /inApps/v1/... are appended to. It exists for tests and Apple-compatible proxies.

func WithHTTPClient 

func WithHTTPClient(httpClient *http.Client) ClientOption

func WithNow 

func WithNow(now func() time.Time) ClientOption

type Credentials 

type Credentials struct {
	KeyID          string
	IssuerID       string
	PrivateKeyPath string
	PrivateKeyPEM  string
	BundleID       string
	Profile        string
}

Credentials holds an In-App Purchase API key and its target app bundle ID.

func GetCredentialsWithSource 

func GetCredentialsWithSource(profile string) (Credentials, string, error)

type DefaultMessageResponse 

type DefaultMessageResponse struct {
	MessageIdentifier string `json:"messageIdentifier"`
}

type Environment 

type Environment string

Environment selects the StoreKit server environment. 

const (
	Production Environment = "production"
	Sandbox    Environment = "sandbox"
)

func ParseEnvironment 

func ParseEnvironment(value string) (Environment, error)

ParseEnvironment validates a StoreKit environment.

type HeaderPosition 

type HeaderPosition string

HeaderPosition controls where the header appears in a retention message. 

const (
	HeaderAboveBody  HeaderPosition = "ABOVE_BODY"
	HeaderAboveImage HeaderPosition = "ABOVE_IMAGE"
)

type ImageIdentifier 

type ImageIdentifier struct {
	ImageIdentifier string    `json:"imageIdentifier"`
	ImageSize       ImageSize `json:"imageSize"`
	ImageState      string    `json:"imageState"`
}

type ImageListResponse 

type ImageListResponse struct {
	ImageIdentifiers []ImageIdentifier `json:"imageIdentifiers"`
}

type ImageSize 

type ImageSize string

ImageSize is the placement for a Retention Messaging image. 

const (
	ImageSizeFull        ImageSize = "FULL_SIZE"
	ImageSizeBulletPoint ImageSize = "BULLET_POINT"
)

type ImageState 

type ImageState string

ImageState is Apple's review state for an uploaded image.

type Message 

type Message struct {
	Header         string               `json:"header"`
	Body           string               `json:"body"`
	Image          *MessageImage        `json:"image,omitempty"`
	BulletPoints   []MessageBulletPoint `json:"bulletPoints,omitempty"`
	HeaderPosition HeaderPosition       `json:"headerPosition,omitempty"`
}

type MessageBulletPoint 

type MessageBulletPoint struct {
	ImageIdentifier string `json:"imageIdentifier"`
	AltText         string `json:"altText"`
	Text            string `json:"text"`
}

type MessageIdentifier 

type MessageIdentifier struct {
	MessageIdentifier string `json:"messageIdentifier"`
	MessageState      string `json:"messageState"`
}

type MessageImage 

type MessageImage struct {
	ImageIdentifier string `json:"imageIdentifier"`
	AltText         string `json:"altText"`
}

type MessageListResponse 

type MessageListResponse struct {
	MessageIdentifiers []MessageIdentifier `json:"messageIdentifiers"`
}

type MutationResult 

type MutationResult struct {
	Resource    string      `json:"resource"`
	Identifier  string      `json:"identifier,omitempty"`
	Action      string      `json:"action"`
	Environment Environment `json:"environment"`
	Success     bool        `json:"success"`
}

MutationResult is the stable CLI response for an empty successful mutation.

type NotificationHistoryRequest 

type NotificationHistoryRequest struct {
	StartDate           int64  `json:"startDate"`
	EndDate             int64  `json:"endDate"`
	NotificationType    string `json:"notificationType,omitempty"`
	NotificationSubtype string `json:"notificationSubtype,omitempty"`
	TransactionID       string `json:"transactionId,omitempty"`
	OnlyFailures        bool   `json:"onlyFailures,omitempty"`
}

NotificationHistoryRequest is Apple's NotificationHistoryRequest body. Dates are UNIX time in milliseconds.

type PageCursor 

type PageCursor struct {
	ItemsKey string
	TokenKey string
}

PageCursor names the item array and continuation token of a paginated App Store Server API response that reports hasMore.

func (PageCursor) HasMore 

func (p PageCursor) HasMore(page json.RawMessage) (bool, string, error)

HasMore reports whether a page says more results exist, and its token.

type PerformanceResponseTimes 

type PerformanceResponseTimes struct {
	Average int64 `json:"average,omitempty"`
	P50     int64 `json:"p50,omitempty"`
	P90     int64 `json:"p90,omitempty"`
	P95     int64 `json:"p95,omitempty"`
	P99     int64 `json:"p99,omitempty"`
}

type PerformanceTestConfig 

type PerformanceTestConfig struct {
	MaxConcurrentRequests int64 `json:"maxConcurrentRequests"`
	ResponseTimeThreshold int64 `json:"responseTimeThreshold"`
	SuccessRateThreshold  int32 `json:"successRateThreshold"`
	TotalDuration         int64 `json:"totalDuration"`
	TotalRequests         int   `json:"totalRequests"`
}

type PerformanceTestResult 

type PerformanceTestResult struct {
	Config        PerformanceTestConfig    `json:"config"`
	Failures      map[string]int32         `json:"failures,omitempty"`
	NumPending    int                      `json:"numPending,omitempty"`
	RequestID     string                   `json:"requestId,omitempty"`
	ResponseTimes PerformanceResponseTimes `json:"responseTimes,omitempty"`
	Result        string                   `json:"result"`
	SuccessRate   int32                    `json:"successRate,omitempty"`
	Target        string                   `json:"target,omitempty"`
}

type PerformanceTestStartResponse 

type PerformanceTestStartResponse struct {
	Config    PerformanceTestConfig `json:"config"`
	RequestID string                `json:"requestId"`
}

type RealtimeURLResponse 

type RealtimeURLResponse struct {
	RealtimeURL string `json:"realtimeURL"`
}

type StoredCredential 

type StoredCredential struct {
	Credentials `json:"-"`
	Name        string `json:"name"`
	IsDefault   bool   `json:"default"`
	Source      string `json:"source"`
	SourcePath  string `json:"source_path,omitempty"`
}

func ListCredentials 

func ListCredentials() ([]StoredCredential, error)

type TransactionHistoryQuery 

type TransactionHistoryQuery struct {
	StartDate    time.Time
	EndDate      time.Time
	ProductIDs   []string
	ProductTypes []string
	Sort         string
	Revoked      *bool
}

TransactionHistoryQuery holds the optional Get Transaction History v2 filters. Zero values are omitted from the request.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.