@bradford-tech/asc-sdk

Auto-generated TypeScript SDK for Apple's App Store Connect API -- 1055 tree-shakeable operations, with date-time fields converted to native Date objects.

Generated against App Store Connect API spec 4.3.1.

Install

npm install @bradford-tech/asc-sdk

Also available on jsr:

deno add jsr:@bradford-tech/asc-sdk   # Deno
npx jsr add @bradford-tech/asc-sdk    # npm via jsr

Usage

The SDK exports flat functions for every API operation and a client singleton for configuration. Auth is a callback that returns a JWT string -- pair it with @bradford-tech/asc-auth or bring your own.

import { client, appsGetCollection } from "@bradford-tech/asc-sdk";
import { createASCAuth } from "@bradford-tech/asc-auth";

const auth = createASCAuth({
  issuerId: "57246542-96fe-1a63-e053-0824d011072a",
  keyId: "2X9R4HXF34",
  privateKey: process.env.ASC_PRIVATE_KEY!,
});

client.setConfig({ auth });

const { data } = await appsGetCollection();
console.log(data?.data.map((app) => app.attributes?.name));
// => ["My App", "Another App"]

Bring your own auth

If you already have a JWT source, pass it directly:

client.setConfig({
  auth: () => myExistingTokenFunction(),
});

Filtering and including related resources

Operations accept the same query parameters as Apple's REST API:

const { data } = await appsGetCollection({
  query: {
    "filter[bundleId]": ["com.example.myapp"],
    include: ["appStoreVersions"],
  },
});

Features

• Flat, tree-shakeable exports -- each operation is a standalone function. Import only what you use; bundlers drop the rest.
• Date transforms -- 261 of 1055 endpoints auto-convert date-time response fields to native Date objects via @hey-api/transformers.
• Typed request and response -- full TypeScript types generated from Apple's OpenAPI spec, including query parameters, request bodies, and response shapes.
• Daily spec updates -- a GitHub Actions workflow downloads Apple's latest OpenAPI spec and opens a PR when it changes. The SDK stays current without manual intervention.
• ESM-only -- "type": "module" with explicit .js extensions for Node.js ESM resolution. No CJS dual-publish overhead.

Date handling

Dates in API responses are automatically converted from ISO 8601 strings to native Date objects for endpoints whose schemas contain date-time fields. This includes fields like createdDate, expirationDate, startDate, and earliestReleaseDate.

Exceptions:

• included arrays -- dates inside JSON:API included arrays remain as ISO strings. Apple's included uses oneOf unions for polymorphic resources, and the transformer plugin does not process union types.
• Top-level schemas without dates -- some endpoints' top-level response schemas have no date-time fields. Dates live on related sub-resources accessed via separate relationship endpoints. appsGetCollection, appsGetInstance, and buildsGetCollection are examples. Access dates via the dedicated relationship endpoints (e.g., appsAppStoreVersionsGetToManyRelated) or parse included items manually.

For either case, parse manually:

const createdDate = new Date(includedItem.attributes.createdDate);

int64 fields

Fields marked as int64 in Apple's spec (file sizes, disk metrics, upload offsets) are returned as number, not BigInt. All observed ASC int64 values are well within Number.MAX_SAFE_INTEGER (~9 petabytes for file sizes). If you have a use case requiring BigInt precision, file an issue.

Error handling

Every operation returns { data, error, request, response }. On success, data is populated and error is undefined. On failure, data is undefined and error contains Apple's ErrorResponse body:

const { data, error } = await appsGetCollection();

if (error) {
  // error.errors is Apple's array of { status, code, title, detail }
  console.error(error.errors?.[0]?.detail);
} else {
  console.log(data.data.map((app) => app.attributes?.name));
}

To throw on errors instead of returning them:

client.setConfig({ auth, throwOnError: true });

Configuration

client.setConfig() accepts standard fetch options alongside SDK-specific ones:

client.setConfig({
  auth,
  baseUrl: "https://api.appstoreconnect.apple.com/", // default
  fetch: customFetchImpl, // custom fetch (useful for logging or retries)
  throwOnError: false, // true to throw instead of returning { error }
});

The base URL is set automatically. Override it only if you're routing through a proxy.

Generation

All code in src/client/ is auto-generated by @hey-api/openapi-ts from spec/openapi.oas.json. Do not edit generated files directly -- configure the generator in openapi-ts.config.ts and run:

npm run generate

Contributing

Bug reports and pull requests are welcome on GitHub.

License

MIT