appstore Golang Client Library

To use the library, you must initialize a StoreConfig and pass it to appstore.NewStoreClient.

Required configuration fields in StoreConfig:

• KeyContent: The byte slice of your private key (generated from App Store Connect).
• KeyID: Your API Key ID.
• BundleID: Your app's bundle identifier.
• Issuer: Your API Key Issuer ID.
• Sandbox: A boolean to toggle between the production and sandbox environments.

import(
	"github.com/richzw/appstore"
)

c := &appstore.StoreConfig{
    KeyContent: []byte(ACCOUNTPRIVATEKEY),
    KeyID:      "FAKEKEYID",
    BundleID:   "fake.bundle.id",
    Issuer:     "xxxxx-xx-xx-xx-xxxxxxxxxx",
    Sandbox:    false,
}
a := appstore.NewStoreClient(c)

Install the Apple App Store Server Golang library using go get.

go get github.com/richzw/appstore

The library uses a functional middleware pattern to decorate an HTTPClient. A DoFunc is a function type that matches the signature func(*http.Request) (*http.Response, error). You can chain multiple decorators (like adding headers, setting bodies, or adding retries) to build a complex request execution pipeline. The base HTTPClient must implement the Do(r *http.Request) (*http.Response, error) method.

// Example of how DoFunc works as a decorator
var client appstore.HTTPClient = // your implementation

// Create a decorated function
decoratedDo := appstore.SetHeader(client, "X-Custom-Header", "value")

// Use it to execute a request
resp, err := decoratedDo(req)

To interact with the Apple App Store Server API, you must create a StoreClient using a StoreConfig. The configuration requires credentials obtained from App Store Connect.

Key configuration fields:

• KeyContent: The raw bytes of your .p8 private key.
• KeyID: Your private key ID (e.g., 2X9R4HXF34).
• BundleID: Your app's bundle ID.
• Issuer: Your issuer ID from App Store Connect.
• Sandbox: Set to true to use the Sandbox environment (HostSandBox), otherwise defaults to Production (HostProduction).
• TrustedCertPool: An optional *x509.CertPool. Defaults to a pool containing only the Apple Root CA - G3.

config := &appstore.StoreConfig{
	KeyContent: []byte("..."),
	KeyID:      "2X9R4HXF34",
	BundleID:   "com.example.app",
	Issuer:     "57246542-96fe-1a63-e053-0824d011072a",
	Sandbox:    true,
}
client := appstore.NewStoreClient(config)

Environment Switching

The library handles the base URL based on the Sandbox flag in StoreConfig. If you are unsure which environment a transaction belongs to:

1. Attempt the call using the production URL.
2. If you receive error code 4040010 (TransactionIdNotFoundError), retry the call using the sandbox URL.

Rate Limiting

If you exceed the per-hour limit, the API returns an HTTP 429 with a RateLimitExceededError.

• Retry Logic: Check the Retry-After header, which contains a UNIX time in milliseconds indicating when you can next send a request.
• Best Practices: Throttle periodic requests and implement a queue to retry failed jobs after the specified delay.

Retrieve information about a specific transaction using its ID. After receiving the response, use ParseSignedTransactions to decode the signed transaction data for validation.

Validation Tip: To ensure a transaction is valid, check if the TransactionID in the parsed response matches the transactionId you requested.

// ... setup client 'a' ...
transactionId := "FAKETRANSACTIONID"
response, err := a.GetTransactionInfo(context.TODO(), transactionId)

transactions, err := a.ParseSignedTransactions([]string{response.SignedTransactionInfo})
if transactions[0].TransactionID == transactionId {
    // the transaction is valid
}

Retrieve orders associated with a specific invoice order ID using LookupOrderID. Use ParseSignedTransactions to decode the resulting signed transactions.

// ... setup client 'a' ...
invoiceOrderId := "FAKEORDERID"
rsp, err := a.LookupOrderID(context.TODO(), invoiceOrderId)

orders, err := a.ParseSignedTransactions(rsp.SignedTransactions)

Retrieve the transaction history for a given original transaction ID. You can filter results by setting productType in a url.Values query object (e.g., AUTO_RENEWABLE or NON_CONSUMABLE).

// ... setup client 'a' ...
originalTransactionId := "FAKEORDERID"
query := &url.Values{}
query.Set("productType", "AUTO_RENEWABLE")
query.Set("productType", "NON_CONSUMABLE")

gotRsp, err := a.GetTransactionHistory(context.TODO(), originalTransactionId, query)

for _, rsp := range gotRsp {
   trans, err := a.ParseSignedTransactions(rsp.SignedTransactions)
}

Retrieve the refund history for a specific original transaction ID using GetRefundHistory. Use ParseSignedTransactions to decode the signed transaction data.

// ... setup client 'a' ...
originalTransactionId := "FAKEORDERID"
gotRsp, err := a.GetRefundHistory(context.TODO(), originalTransactionId)

for _, rsp := range gotRsp {
   trans, err := a.ParseSignedTransactions(rsp.SignedTransactions)
}

The ParseJWSEncodeString(jwsEncode string) method can automatically detect and decode JWS strings into either a *JWSTransaction or a *JWSRenewalInfoDecodedPayload based on the payload content.

decoded, err := client.ParseJWSEncodeString(jwsString)
if err != nil {
	// handle error
}
// decoded will be either *JWSTransaction or *JWSRenewalInfoDecodedPayload

Use GetTransactionInfo to fetch details about a specific transaction using its transactionId.

ctx := context.Background()
transactionId := "12345678"
info, err := client.GetTransactionInfo(ctx, transactionId)
if err != nil {
	// handle error
}
// use info (*TransactionInfoResponse)