expo-iap 4.2.2 → 4.2.4

package/build/webhook-client.js

@@ -0,0 +1,176 @@
+// Transport-agnostic webhook client for the openiap kit SSE stream
+// (`GET /v1/webhooks/stream/{apiKey}`). Used by the JavaScript / TS
+// wrappers (react-native-iap, expo-iap) but written without React or
+// React-Native imports so it can also run in plain Node, browser, or
+// any other JS runtime.
+//
+// The wire format is documented in `packages/kit/server/api/v1/webhooks.ts`
+// and matches the GraphQL `WebhookEvent` shape from `webhook.graphql`.
+//
+// Parser logic is split out from the connection so it can be unit-
+// tested without a live server. See `webhook-client.test.ts`.
+export const WEBHOOK_EVENT_TYPES = [
+    'SubscriptionStarted',
+    'SubscriptionRenewed',
+    'SubscriptionExpired',
+    'SubscriptionInGracePeriod',
+    'SubscriptionInBillingRetry',
+    'SubscriptionRecovered',
+    'SubscriptionCanceled',
+    'SubscriptionUncanceled',
+    'SubscriptionRevoked',
+    'SubscriptionPriceChange',
+    'SubscriptionProductChanged',
+    'SubscriptionPaused',
+    'SubscriptionResumed',
+    'PurchaseRefunded',
+    'PurchaseConsumptionRequest',
+    'TestNotification',
+];
+const DEFAULT_BASE_URL = 'https://kit.openiap.dev';
+export function connectWebhookStream(options) {
+    const baseUrl = options.baseUrl ?? DEFAULT_BASE_URL;
+    const url = `${trimTrailingSlash(baseUrl)}/v1/webhooks/stream/${encodeURIComponent(options.apiKey)}`;
+    const factory = options.eventSourceFactory ?? defaultEventSourceFactory;
+    let stream;
+    try {
+        stream = factory(url, {});
+    }
+    catch (error) {
+        options.onError?.({
+            code: 'NO_EVENTSOURCE',
+            message: error instanceof Error
+                ? error.message
+                : 'EventSource constructor unavailable in this runtime',
+            cause: error,
+        });
+        return { close: () => { } };
+    }
+    const seenIds = new Set();
+    const seenOrder = [];
+    const markSeen = (id) => {
+        if (seenIds.has(id)) {
+            return true;
+        }
+        seenIds.add(id);
+        seenOrder.push(id);
+        if (seenOrder.length > 1024) {
+            const evicted = seenOrder.shift();
+            if (evicted !== undefined) {
+                seenIds.delete(evicted);
+            }
+        }
+        return false;
+    };
+    const handleData = (raw) => {
+        const parsed = parseWebhookEventData(raw);
+        if (parsed.kind === 'error') {
+            options.onError?.({
+                code: 'PARSE_ERROR',
+                message: parsed.message,
+            });
+            return;
+        }
+        if (parsed.kind === 'skip') {
+            return;
+        }
+        if (markSeen(parsed.event.id)) {
+            return;
+        }
+        options.onEvent(parsed.event);
+    };
+    if (typeof stream.addEventListener === 'function') {
+        stream.addEventListener('message', (event) => handleData(event.data));
+        // WHATWG EventSource dispatches frames with `event: Foo` only to
+        // listeners registered for `Foo`, not to `message` / `onmessage`.
+        // Kit emits webhook frames as typed SSE events, so subscribe to
+        // every known webhook type and keep `message` for older servers or
+        // polyfills that collapse typed frames into the generic channel.
+        for (const eventType of WEBHOOK_EVENT_TYPES) {
+            stream.addEventListener(eventType, (event) => handleData(event.data));
+        }
+    }
+    else {
+        stream.onmessage = (event) => handleData(event.data);
+    }
+    stream.onerror = (error) => {
+        options.onError?.({
+            code: 'TRANSPORT_ERROR',
+            message: 'SSE transport error (auto-reconnecting)',
+            cause: error,
+        });
+    };
+    return {
+        close: () => {
+            try {
+                stream.close();
+            }
+            catch {
+                // Closing an already-closed EventSource is a no-op in browsers
+                // but throws in some polyfills.
+            }
+        },
+    };
+}
+export function parseWebhookEventData(raw) {
+    if (!raw) {
+        return { kind: 'skip', reason: 'heartbeat' };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (error) {
+        return {
+            kind: 'error',
+            message: error instanceof Error
+                ? `Failed to parse SSE payload: ${error.message}`
+                : 'Failed to parse SSE payload',
+        };
+    }
+    if (typeof parsed !== 'object' ||
+        parsed === null ||
+        !('type' in parsed) ||
+        typeof parsed.type !== 'string') {
+        // Stream-control messages (the `ready`/`stream-error` envelopes
+        // emitted by the kit server) have no `type` and are surfaced as
+        // skips so consumers don't see them as events.
+        return { kind: 'skip', reason: 'stream-control' };
+    }
+    const event = parsed;
+    if (typeof event.id !== 'string' ||
+        typeof event.occurredAt !== 'number' ||
+        typeof event.receivedAt !== 'number') {
+        return {
+            kind: 'error',
+            message: `WebhookEvent missing required fields (id/occurredAt/receivedAt)`,
+        };
+    }
+    // purchaseToken is required for every event type *except*
+    // TestNotification — Apple ASN v2 / Google RTDN test payloads
+    // carry no transaction. Hard-rejecting here would surface valid
+    // test webhooks as MALFORMED_EVENT and never reach listeners.
+    if (event.type !== 'TestNotification' &&
+        typeof event.purchaseToken !== 'string') {
+        return {
+            kind: 'error',
+            message: `WebhookEvent missing required field purchaseToken`,
+        };
+    }
+    return { kind: 'ok', event };
+}
+function trimTrailingSlash(url) {
+    return url.endsWith('/') ? url.slice(0, -1) : url;
+}
+function defaultEventSourceFactory(url, _headers) {
+    // EventSource is part of the WHATWG spec and available in all
+    // browser environments and most JS runtimes (Bun, Node 22+, Deno).
+    // RN does not ship it natively — consumers must pass
+    // `eventSourceFactory` from `react-native-sse` or similar.
+    const ctor = globalThis.EventSource;
+    if (!ctor) {
+        throw new Error('EventSource is not defined. Pass `eventSourceFactory` for runtimes without a built-in EventSource.');
+    }
+    return new ctor(url);
+}
+//# sourceMappingURL=webhook-client.js.map

package/build/webhook-client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"webhook-client.js","sourceRoot":"","sources":["../src/webhook-client.ts"],"names":[],"mappings":"AAAA,mEAAmE;AACnE,oEAAoE;AACpE,qEAAqE;AACrE,qEAAqE;AACrE,wBAAwB;AACxB,EAAE;AACF,4EAA4E;AAC5E,uEAAuE;AACvE,EAAE;AACF,mEAAmE;AACnE,8DAA8D;AAoB9D,MAAM,CAAC,MAAM,mBAAmB,GAAG;IACjC,qBAAqB;IACrB,qBAAqB;IACrB,qBAAqB;IACrB,2BAA2B;IAC3B,4BAA4B;IAC5B,uBAAuB;IACvB,sBAAsB;IACtB,wBAAwB;IACxB,qBAAqB;IACrB,yBAAyB;IACzB,4BAA4B;IAC5B,oBAAoB;IACpB,qBAAqB;IACrB,kBAAkB;IAClB,4BAA4B;IAC5B,kBAAkB;CAC4B,CAAC;AAgFjD,MAAM,gBAAgB,GAAG,yBAAyB,CAAC;AAEnD,MAAM,UAAU,oBAAoB,CAClC,OAA+B;IAE/B,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,IAAI,gBAAgB,CAAC;IACpD,MAAM,GAAG,GAAG,GAAG,iBAAiB,CAC9B,OAAO,CACR,uBAAuB,kBAAkB,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;IAE7D,MAAM,OAAO,GAAG,OAAO,CAAC,kBAAkB,IAAI,yBAAyB,CAAC;IACxE,IAAI,MAA0B,CAAC;IAC/B,IAAI,CAAC;QACH,MAAM,GAAG,OAAO,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;IAC5B,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,OAAO,CAAC,OAAO,EAAE,CAAC;YAChB,IAAI,EAAE,gBAAgB;YACtB,OAAO,EACL,KAAK,YAAY,KAAK;gBACpB,CAAC,CAAC,KAAK,CAAC,OAAO;gBACf,CAAC,CAAC,qDAAqD;YAC3D,KAAK,EAAE,KAAK;SACb,CAAC,CAAC;QACH,OAAO,EAAC,KAAK,EAAE,GAAG,EAAE,GAAE,CAAC,EAAC,CAAC;IAC3B,CAAC;IAED,MAAM,OAAO,GAAG,IAAI,GAAG,EAAU,CAAC;IAClC,MAAM,SAAS,GAAa,EAAE,CAAC;IAC/B,MAAM,QAAQ,GAAG,CAAC,EAAU,EAAW,EAAE;QACvC,IAAI,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,CAAC;YACpB,OAAO,IAAI,CAAC;QACd,CAAC;QACD,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QAChB,SAAS,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACnB,IAAI,SAAS,CAAC,MAAM,GAAG,IAAI,EAAE,CAAC;YAC5B,MAAM,OAAO,GAAG,SAAS,CAAC,KAAK,EAAE,CAAC;YAClC,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;gBAC1B,OAAO,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;YAC1B,CAAC;QACH,CAAC;QACD,OAAO,KAAK,CAAC;IACf,CAAC,CAAC;IAEF,MAAM,UAAU,GAAG,CAAC,GAAW,EAAE,EAAE;QACjC,MAAM,MAAM,GAAG,qBAAqB,CAAC,GAAG,CAAC,CAAC;QAC1C,IAAI,MAAM,CAAC,IAAI,KAAK,OAAO,EAAE,CAAC;YAC5B,OAAO,CAAC,OAAO,EAAE,CAAC;gBAChB,IAAI,EAAE,aAAa;gBACnB,OAAO,EAAE,MAAM,CAAC,OAAO;aACxB,CAAC,CAAC;YACH,OAAO;QACT,CAAC;QACD,IAAI,MAAM,CAAC,IAAI,KAAK,MAAM,EAAE,CAAC;YAC3B,OAAO;QACT,CAAC;QACD,IAAI,QAAQ,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,EAAE,CAAC;YAC9B,OAAO;QACT,CAAC;QACD,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IAChC,CAAC,CAAC;IAEF,IAAI,OAAO,MAAM,CAAC,gBAAgB,KAAK,UAAU,EAAE,CAAC;QAClD,MAAM,CAAC,gBAAgB,CAAC,SAAS,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,UAAU,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC;QACtE,iEAAiE;QACjE,kEAAkE;QAClE,gEAAgE;QAChE,mEAAmE;QACnE,iEAAiE;QACjE,KAAK,MAAM,SAAS,IAAI,mBAAmB,EAAE,CAAC;YAC5C,MAAM,CAAC,gBAAgB,CAAC,SAAS,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,UAAU,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC;QACxE,CAAC;IACH,CAAC;SAAM,CAAC;QACN,MAAM,CAAC,SAAS,GAAG,CAAC,KAAK,EAAE,EAAE,CAAC,UAAU,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IACvD,CAAC;IAED,MAAM,CAAC,OAAO,GAAG,CAAC,KAAK,EAAE,EAAE;QACzB,OAAO,CAAC,OAAO,EAAE,CAAC;YAChB,IAAI,EAAE,iBAAiB;YACvB,OAAO,EAAE,yCAAyC;YAClD,KAAK,EAAE,KAAK;SACb,CAAC,CAAC;IACL,CAAC,CAAC;IAEF,OAAO;QACL,KAAK,EAAE,GAAG,EAAE;YACV,IAAI,CAAC;gBACH,MAAM,CAAC,KAAK,EAAE,CAAC;YACjB,CAAC;YAAC,MAAM,CAAC;gBACP,+DAA+D;gBAC/D,gCAAgC;YAClC,CAAC;QACH,CAAC;KACF,CAAC;AACJ,CAAC;AAWD,MAAM,UAAU,qBAAqB,CAAC,GAAW;IAC/C,IAAI,CAAC,GAAG,EAAE,CAAC;QACT,OAAO,EAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,EAAC,CAAC;IAC7C,CAAC;IAED,IAAI,MAAe,CAAC;IACpB,IAAI,CAAC;QACH,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAC3B,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,OAAO;YACL,IAAI,EAAE,OAAO;YACb,OAAO,EACL,KAAK,YAAY,KAAK;gBACpB,CAAC,CAAC,gCAAgC,KAAK,CAAC,OAAO,EAAE;gBACjD,CAAC,CAAC,6BAA6B;SACpC,CAAC;IACJ,CAAC;IAED,IACE,OAAO,MAAM,KAAK,QAAQ;QAC1B,MAAM,KAAK,IAAI;QACf,CAAC,CAAC,MAAM,IAAI,MAAM,CAAC;QACnB,OAAQ,MAAkC,CAAC,IAAI,KAAK,QAAQ,EAC5D,CAAC;QACD,gEAAgE;QAChE,gEAAgE;QAChE,+CAA+C;QAC/C,OAAO,EAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,gBAAgB,EAAC,CAAC;IAClD,CAAC;IAED,MAAM,KAAK,GAAG,MAA6B,CAAC;IAE5C,IACE,OAAO,KAAK,CAAC,EAAE,KAAK,QAAQ;QAC5B,OAAO,KAAK,CAAC,UAAU,KAAK,QAAQ;QACpC,OAAO,KAAK,CAAC,UAAU,KAAK,QAAQ,EACpC,CAAC;QACD,OAAO;YACL,IAAI,EAAE,OAAO;YACb,OAAO,EAAE,iEAAiE;SAC3E,CAAC;IACJ,CAAC;IACD,0DAA0D;IAC1D,8DAA8D;IAC9D,gEAAgE;IAChE,8DAA8D;IAC9D,IACE,KAAK,CAAC,IAAI,KAAK,kBAAkB;QACjC,OAAO,KAAK,CAAC,aAAa,KAAK,QAAQ,EACvC,CAAC;QACD,OAAO;YACL,IAAI,EAAE,OAAO;YACb,OAAO,EAAE,mDAAmD;SAC7D,CAAC;IACJ,CAAC;IAED,OAAO,EAAC,IAAI,EAAE,IAAI,EAAE,KAAK,EAAC,CAAC;AAC7B,CAAC;AAED,SAAS,iBAAiB,CAAC,GAAW;IACpC,OAAO,GAAG,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC;AACpD,CAAC;AAED,SAAS,yBAAyB,CAChC,GAAW,EACX,QAAgC;IAEhC,8DAA8D;IAC9D,mEAAmE;IACnE,qDAAqD;IACrD,2DAA2D;IAC3D,MAAM,IAAI,GACR,UAGD,CAAC,WAAW,CAAC;IACd,IAAI,CAAC,IAAI,EAAE,CAAC;QACV,MAAM,IAAI,KAAK,CACb,oGAAoG,CACrG,CAAC;IACJ,CAAC;IACD,OAAO,IAAI,IAAI,CAAC,GAAG,CAAC,CAAC;AACvB,CAAC","sourcesContent":["// Transport-agnostic webhook client for the openiap kit SSE stream\n// (`GET /v1/webhooks/stream/{apiKey}`). Used by the JavaScript / TS\n// wrappers (react-native-iap, expo-iap) but written without React or\n// React-Native imports so it can also run in plain Node, browser, or\n// any other JS runtime.\n//\n// The wire format is documented in `packages/kit/server/api/v1/webhooks.ts`\n// and matches the GraphQL `WebhookEvent` shape from `webhook.graphql`.\n//\n// Parser logic is split out from the connection so it can be unit-\n// tested without a live server. See `webhook-client.test.ts`.\n\nexport type WebhookEventType =\n  | 'SubscriptionStarted'\n  | 'SubscriptionRenewed'\n  | 'SubscriptionExpired'\n  | 'SubscriptionInGracePeriod'\n  | 'SubscriptionInBillingRetry'\n  | 'SubscriptionRecovered'\n  | 'SubscriptionCanceled'\n  | 'SubscriptionUncanceled'\n  | 'SubscriptionRevoked'\n  | 'SubscriptionPriceChange'\n  | 'SubscriptionProductChanged'\n  | 'SubscriptionPaused'\n  | 'SubscriptionResumed'\n  | 'PurchaseRefunded'\n  | 'PurchaseConsumptionRequest'\n  | 'TestNotification';\n\nexport const WEBHOOK_EVENT_TYPES = [\n  'SubscriptionStarted',\n  'SubscriptionRenewed',\n  'SubscriptionExpired',\n  'SubscriptionInGracePeriod',\n  'SubscriptionInBillingRetry',\n  'SubscriptionRecovered',\n  'SubscriptionCanceled',\n  'SubscriptionUncanceled',\n  'SubscriptionRevoked',\n  'SubscriptionPriceChange',\n  'SubscriptionProductChanged',\n  'SubscriptionPaused',\n  'SubscriptionResumed',\n  'PurchaseRefunded',\n  'PurchaseConsumptionRequest',\n  'TestNotification',\n] as const satisfies readonly WebhookEventType[];\n\nexport type WebhookEventPayload = {\n  id: string;\n  type: WebhookEventType;\n  source: string;\n  platform: 'IOS' | 'Android';\n  environment: 'Production' | 'Sandbox' | 'Xcode';\n  projectId: string;\n  occurredAt: number;\n  receivedAt: number;\n  // Optional because TestNotification frames carry no transaction;\n  // every other event type populates this.\n  purchaseToken?: string;\n  productId?: string;\n  subscriptionState?: string;\n  expiresAt?: number;\n  renewsAt?: number;\n  cancellationReason?: string;\n  currency?: string;\n  priceAmountMicros?: number;\n  rawSignedPayload?: string;\n};\n\nexport type WebhookListenerOptions = {\n  /**\n   * Project API key. Embedded in the URL path because Apple ASN\n   * registration cannot send custom headers; the same path is reused\n   * here for symmetry.\n   */\n  apiKey: string;\n  /**\n   * Override the kit base URL. Defaults to https://kit.openiap.dev.\n   * In tests, point this at a local server.\n   */\n  baseUrl?: string;\n  /** Called on every successfully-parsed webhook event. */\n  onEvent: (event: WebhookEventPayload) => void;\n  /**\n   * Called on transport errors. The connection auto-reconnects\n   * unconditionally; this callback exists for telemetry / surfacing\n   * to the host UI.\n   */\n  onError?: (error: WebhookListenerError) => void;\n  /**\n   * Optional injection of an EventSource constructor. Lets RN /\n   * Expo plug in `react-native-event-source` when running on a JS\n   * runtime that lacks the global, or vitest plug in a stub.\n   */\n  eventSourceFactory?: (\n    url: string,\n    headers: Record<string, string>,\n  ) => WebhookEventStream;\n};\n\nexport interface WebhookEventStream {\n  close(): void;\n  onmessage: ((event: {data: string; lastEventId?: string}) => void) | null;\n  onerror: ((error: unknown) => void) | null;\n  addEventListener?: (\n    type: string,\n    listener: (event: {data: string; lastEventId?: string}) => void,\n  ) => void;\n}\n\nexport type WebhookListener = {\n  /** Tear down the connection and stop receiving events. */\n  close(): void;\n};\n\nexport type WebhookListenerError = {\n  code:\n    | 'TRANSPORT_ERROR'\n    | 'PARSE_ERROR'\n    | 'MALFORMED_EVENT'\n    | 'NO_EVENTSOURCE';\n  message: string;\n  cause?: unknown;\n};\n\nconst DEFAULT_BASE_URL = 'https://kit.openiap.dev';\n\nexport function connectWebhookStream(\n  options: WebhookListenerOptions,\n): WebhookListener {\n  const baseUrl = options.baseUrl ?? DEFAULT_BASE_URL;\n  const url = `${trimTrailingSlash(\n    baseUrl,\n  )}/v1/webhooks/stream/${encodeURIComponent(options.apiKey)}`;\n\n  const factory = options.eventSourceFactory ?? defaultEventSourceFactory;\n  let stream: WebhookEventStream;\n  try {\n    stream = factory(url, {});\n  } catch (error) {\n    options.onError?.({\n      code: 'NO_EVENTSOURCE',\n      message:\n        error instanceof Error\n          ? error.message\n          : 'EventSource constructor unavailable in this runtime',\n      cause: error,\n    });\n    return {close: () => {}};\n  }\n\n  const seenIds = new Set<string>();\n  const seenOrder: string[] = [];\n  const markSeen = (id: string): boolean => {\n    if (seenIds.has(id)) {\n      return true;\n    }\n    seenIds.add(id);\n    seenOrder.push(id);\n    if (seenOrder.length > 1024) {\n      const evicted = seenOrder.shift();\n      if (evicted !== undefined) {\n        seenIds.delete(evicted);\n      }\n    }\n    return false;\n  };\n\n  const handleData = (raw: string) => {\n    const parsed = parseWebhookEventData(raw);\n    if (parsed.kind === 'error') {\n      options.onError?.({\n        code: 'PARSE_ERROR',\n        message: parsed.message,\n      });\n      return;\n    }\n    if (parsed.kind === 'skip') {\n      return;\n    }\n    if (markSeen(parsed.event.id)) {\n      return;\n    }\n    options.onEvent(parsed.event);\n  };\n\n  if (typeof stream.addEventListener === 'function') {\n    stream.addEventListener('message', (event) => handleData(event.data));\n    // WHATWG EventSource dispatches frames with `event: Foo` only to\n    // listeners registered for `Foo`, not to `message` / `onmessage`.\n    // Kit emits webhook frames as typed SSE events, so subscribe to\n    // every known webhook type and keep `message` for older servers or\n    // polyfills that collapse typed frames into the generic channel.\n    for (const eventType of WEBHOOK_EVENT_TYPES) {\n      stream.addEventListener(eventType, (event) => handleData(event.data));\n    }\n  } else {\n    stream.onmessage = (event) => handleData(event.data);\n  }\n\n  stream.onerror = (error) => {\n    options.onError?.({\n      code: 'TRANSPORT_ERROR',\n      message: 'SSE transport error (auto-reconnecting)',\n      cause: error,\n    });\n  };\n\n  return {\n    close: () => {\n      try {\n        stream.close();\n      } catch {\n        // Closing an already-closed EventSource is a no-op in browsers\n        // but throws in some polyfills.\n      }\n    },\n  };\n}\n\n// ---------------------------------------------------------------------------\n// Pure helpers (exported for testing).\n// ---------------------------------------------------------------------------\n\nexport type ParsedEventResult =\n  | {kind: 'ok'; event: WebhookEventPayload}\n  | {kind: 'skip'; reason: 'heartbeat' | 'stream-control'}\n  | {kind: 'error'; message: string};\n\nexport function parseWebhookEventData(raw: string): ParsedEventResult {\n  if (!raw) {\n    return {kind: 'skip', reason: 'heartbeat'};\n  }\n\n  let parsed: unknown;\n  try {\n    parsed = JSON.parse(raw);\n  } catch (error) {\n    return {\n      kind: 'error',\n      message:\n        error instanceof Error\n          ? `Failed to parse SSE payload: ${error.message}`\n          : 'Failed to parse SSE payload',\n    };\n  }\n\n  if (\n    typeof parsed !== 'object' ||\n    parsed === null ||\n    !('type' in parsed) ||\n    typeof (parsed as Record<string, unknown>).type !== 'string'\n  ) {\n    // Stream-control messages (the `ready`/`stream-error` envelopes\n    // emitted by the kit server) have no `type` and are surfaced as\n    // skips so consumers don't see them as events.\n    return {kind: 'skip', reason: 'stream-control'};\n  }\n\n  const event = parsed as WebhookEventPayload;\n\n  if (\n    typeof event.id !== 'string' ||\n    typeof event.occurredAt !== 'number' ||\n    typeof event.receivedAt !== 'number'\n  ) {\n    return {\n      kind: 'error',\n      message: `WebhookEvent missing required fields (id/occurredAt/receivedAt)`,\n    };\n  }\n  // purchaseToken is required for every event type *except*\n  // TestNotification — Apple ASN v2 / Google RTDN test payloads\n  // carry no transaction. Hard-rejecting here would surface valid\n  // test webhooks as MALFORMED_EVENT and never reach listeners.\n  if (\n    event.type !== 'TestNotification' &&\n    typeof event.purchaseToken !== 'string'\n  ) {\n    return {\n      kind: 'error',\n      message: `WebhookEvent missing required field purchaseToken`,\n    };\n  }\n\n  return {kind: 'ok', event};\n}\n\nfunction trimTrailingSlash(url: string): string {\n  return url.endsWith('/') ? url.slice(0, -1) : url;\n}\n\nfunction defaultEventSourceFactory(\n  url: string,\n  _headers: Record<string, string>,\n): WebhookEventStream {\n  // EventSource is part of the WHATWG spec and available in all\n  // browser environments and most JS runtimes (Bun, Node 22+, Deno).\n  // RN does not ship it natively — consumers must pass\n  // `eventSourceFactory` from `react-native-sse` or similar.\n  const ctor = (\n    globalThis as {\n      EventSource?: new (url: string) => WebhookEventStream;\n    }\n  ).EventSource;\n  if (!ctor) {\n    throw new Error(\n      'EventSource is not defined. Pass `eventSourceFactory` for runtimes without a built-in EventSource.',\n    );\n  }\n  return new ctor(url);\n}\n"]}

package/openiap-versions.json

@@ -1,5 +1,5 @@
 {
   "spec": "2.0.1",
-  "google": "2.1.1",
-  "apple": "2.1.3"
+  "google": "2.1.2",
+  "apple": "2.1.5"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "expo-iap",
-  "version": "4.2.2",
+  "version": "4.2.4",
   "description": "In App Purchase module in Expo",
   "main": "build/index.js",
   "types": "build/index.d.ts",

package/src/index.ts

@@ -331,18 +331,58 @@ export const subscriptionBillingIssueListener = (
   );
 };
 
+/**
+ * Initialize the store connection. Must be called before any other IAP API.
+ *
+ * @param config Optional connection config. Use `enableBillingProgramAndroid` (Android,
+ *   Play Billing 8.2.0+) to opt into External Payments etc. iOS ignores Android-specific fields.
+ * @returns Promise resolving to `true` when the platform billing client is connected.
+ * @throws When the platform billing client fails to initialize.
+ *
+ * @example
+ * ```ts
+ * await initConnection();
+ * await initConnection({ enableBillingProgramAndroid: 'external-offer' });
+ * ```
+ *
+ * @remarks When using `useIAP()`, connection is auto-managed on mount/unmount —
+ *   pass options to the hook instead of calling this directly.
+ *
+ * @see {@link https://www.openiap.dev/docs/apis/init-connection}
+ */
 export const initConnection: MutationField<'initConnection'> = async (config) =>
   ExpoIapModule.initConnection(config ?? null);
 
+/**
+ * Close the store connection and release resources.
+ *
+ * @see {@link https://www.openiap.dev/docs/apis/end-connection}
+ */
 export const endConnection: MutationField<'endConnection'> = async () =>
   ExpoIapModule.endConnection();
 
 /**
- * Fetch products with unified API (v2.7.0+)
+ * Retrieve products or subscriptions from the store by SKU.
+ *
+ * @param request `ProductRequest` — `skus` (string[]) and optional `type`
+ *   (`'in-app' | 'subs' | 'all'`, defaults to `'in-app'`).
+ * @returns Promise resolving to a `FetchProductsResult` union — `Product[]` for `'in-app'`,
+ *   `ProductSubscription[]` for `'subs'`, or a mixed array for `'all'`.
+ * @throws When the store rejects the request (empty `skus`, not connected,
+ *   network/store error). Unknown SKUs are simply omitted from the result, not thrown.
  *
- * @param request - Product fetch configuration
- * @param request.skus - Array of product SKUs to fetch
- * @param request.type - Product query type: 'in-app', 'subs', or 'all'
+ * @example
+ * ```ts
+ * const products = await fetchProducts({
+ *   skus: ['com.app.coins_100', 'com.app.premium'],
+ *   type: 'in-app',
+ * });
+ * ```
+ *
+ * @remarks This is a regular promise-based call. Don't confuse with `request*` APIs
+ *   (`requestPurchase`), which are event-based.
+ *
+ * @see {@link https://www.openiap.dev/docs/apis/fetch-products}
  */
 export const fetchProducts: QueryField<'fetchProducts'> = async (request) => {
   ExpoIapConsole.debug('fetchProducts called with:', request);
@@ -413,6 +453,25 @@ export const fetchProducts: QueryField<'fetchProducts'> = async (request) => {
   throw new Error('Unsupported platform');
 };
 
+/**
+ * List the user's unfinished purchases — non-consumables, active subscriptions, and any
+ * pending transactions not yet finished.
+ *
+ * @param options Optional `PurchaseOptions`. iOS-only flags:
+ *   `alsoPublishToEventListenerIOS`, `onlyIncludeActiveItemsIOS`.
+ * @returns Promise resolving to an array of `Purchase` currently held by the store.
+ * @throws When the platform query fails.
+ *
+ * @example
+ * ```ts
+ * const purchases = await getAvailablePurchases();
+ * for (const p of purchases) {
+ *   if (await verifyOnServer(p)) await finishTransaction({ purchase: p, isConsumable: false });
+ * }
+ * ```
+ *
+ * @see {@link https://www.openiap.dev/docs/apis/get-available-purchases}
+ */
 export const getAvailablePurchases: QueryField<
   'getAvailablePurchases'
 > = async (options) => {
@@ -467,6 +526,8 @@ export const getAvailablePurchases: QueryField<
  *   }
  * });
  * ```
+ *
+ * @see {@link https://www.openiap.dev/docs/apis/get-active-subscriptions}
  */
 export const getActiveSubscriptions: QueryField<
   'getActiveSubscriptions'
@@ -491,6 +552,8 @@ export const getActiveSubscriptions: QueryField<
  * // Check specific subscriptions
  * const hasPremium = await hasActiveSubscriptions(['premium', 'premium_year']);
  * ```
+ *
+ * @see {@link https://www.openiap.dev/docs/apis/has-active-subscriptions}
  */
 export const hasActiveSubscriptions: QueryField<
   'hasActiveSubscriptions'
@@ -500,6 +563,11 @@ export const hasActiveSubscriptions: QueryField<
   ));
 };
 
+/**
+ * Return the user's storefront country code.
+ *
+ * @see {@link https://www.openiap.dev/docs/apis/get-storefront}
+ */
 export const getStorefront: QueryField<'getStorefront'> = async () => {
   if (Platform.OS !== 'ios' && Platform.OS !== 'android') {
     return '';
@@ -541,44 +609,30 @@ function normalizeRequestProps(
 }
 
 /**
- * Request a purchase for products or subscriptions.
+ * Initiate a purchase or subscription flow. The result is delivered through
+ * `purchaseUpdatedListener` — NOT the return value.
  *
- * @param requestObj - Purchase request configuration
- * @param requestObj.request - Store-specific purchase parameters
- * @param requestObj.type - Type of purchase: 'in-app' for products (default) or 'subs' for subscriptions
+ * @param args `RequestPurchaseProps`, discriminated by `type`:
+ *   - `type: 'in-app'` — pass `request.apple.sku` (iOS) and/or `request.google.skus` (Android).
+ *   - `type: 'subs'`  — same shape, plus `request.google.subscriptionOffers: [{ sku, offerToken }]`.
+ * @returns The dispatched purchase payload. **Do not rely on it** for the actual outcome.
+ * @throws Synchronous rejection from the store (e.g. `E_NOT_PREPARED`, validation failure).
  *
  * @example
- * ```typescript
- * // Product purchase (recommended: use apple/google)
+ * ```ts
  * await requestPurchase({
  *   request: {
- *     apple: { sku: productId },
- *     google: { skus: [productId] }
+ *     apple: { sku: 'com.app.premium' },
+ *     google: { skus: ['com.app.premium'] },
  *   },
- *   type: 'in-app'
+ *   type: 'in-app',
  * });
+ * ```
  *
- * // Subscription purchase
- * await requestPurchase({
- *   request: {
- *     apple: { sku: subscriptionId },
- *     google: {
- *       skus: [subscriptionId],
- *       subscriptionOffers: [{ sku: subscriptionId, offerToken: 'token' }]
- *     }
- *   },
- *   type: 'subs'
- * });
+ * @remarks Event-based. Listen for the result via {@link purchaseUpdatedListener} /
+ *   {@link purchaseErrorListener}, or use `useIAP({ onPurchaseSuccess, onPurchaseError })`.
  *
- * // Legacy format (deprecated, but still supported)
- * await requestPurchase({
- *   request: {
- *     ios: { sku: productId },
- *     android: { skus: [productId] }
- *   },
- *   type: 'in-app'
- * });
- * ```
+ * @see {@link https://www.openiap.dev/docs/apis/request-purchase}
  */
 export const requestPurchase: MutationField<'requestPurchase'> = async (
   args,
@@ -739,6 +793,29 @@ export const requestPurchase: MutationField<'requestPurchase'> = async (
   throw new Error('Platform not supported');
 };
 
+/**
+ * Complete a purchase transaction. Call after server-side verification to remove it
+ * from the queue.
+ *
+ * @param args.purchase The `Purchase` to finalize.
+ * @param args.isConsumable `true` for consumables (consumes the token so the SKU can be
+ *   re-bought, e.g. coins); `false` (default) for non-consumables and subscriptions.
+ * @returns Promise that resolves once the platform finalizes the transaction.
+ * @throws When the platform finalize call fails.
+ *
+ * @example
+ * ```ts
+ * // Inside purchaseUpdatedListener:
+ * if (await verifyOnServer(purchase)) {
+ *   await finishTransaction({ purchase, isConsumable: false });
+ * }
+ * ```
+ *
+ * @remarks **Critical:** Android purchases must be finalized within 3 days or Google
+ *   auto-refunds. iOS unfinished transactions replay on every app launch.
+ *
+ * @see {@link https://www.openiap.dev/docs/apis/finish-transaction}
+ */
 export const finishTransaction: MutationField<'finishTransaction'> = async ({
   purchase,
   isConsumable = false,
@@ -781,6 +858,8 @@ export const finishTransaction: MutationField<'finishTransaction'> = async ({
  *
  * This helper triggers the refresh flows but does not return the purchases; consumers should
  * call `getAvailablePurchases` or rely on hook state to inspect the latest items.
+ *
+ * @see {@link https://www.openiap.dev/docs/apis/restore-purchases}
  */
 export const restorePurchases: MutationField<'restorePurchases'> = async () => {
   if (Platform.OS === 'ios') {
@@ -810,6 +889,8 @@ export const restorePurchases: MutationField<'restorePurchases'> = async () => {
  *   skuAndroid: 'your_subscription_sku',
  *   packageNameAndroid: 'com.example.app'
  * });
+ *
+ * @see {@link https://www.openiap.dev/docs/apis/deep-link-to-subscriptions}
  */
 export const deepLinkToSubscriptions: MutationField<
   'deepLinkToSubscriptions'
@@ -836,6 +917,8 @@ export const deepLinkToSubscriptions: MutationField<
  * - Android: Use Google Play Developer API with service account credentials
  *
  * @deprecated Use verifyPurchase instead
+ *
+ * @see {@link https://www.openiap.dev/docs/apis/validate-receipt}
  */
 export const validateReceipt: MutationField<'validateReceipt'> = async (
   options,
@@ -881,6 +964,8 @@ export const validateReceipt: MutationField<'validateReceipt'> = async (
  *
  * @param options - Receipt validation options containing the SKU
  * @returns Promise resolving to receipt validation result
+ *
+ * @see {@link https://www.openiap.dev/docs/features/validation#verify-purchase}
  */
 export const verifyPurchase: MutationField<'verifyPurchase'> = async (
   options,
@@ -916,6 +1001,8 @@ export const verifyPurchase: MutationField<'verifyPurchase'> = async (
  *   }
  * });
  * ```
+ *
+ * @see {@link https://www.openiap.dev/docs/features/validation#verify-purchase-with-provider}
  */
 export const verifyPurchaseWithProvider: MutationField<
   'verifyPurchaseWithProvider'
@@ -955,6 +1042,27 @@ export const verifyPurchaseWithProvider: MutationField<
 };
 
 export * from './useIAP';
+export {useWebhookEvents} from './useWebhookEvents';
+export type {
+  UseWebhookEventsOptions,
+  UseWebhookEventsResult,
+} from './useWebhookEvents';
+export {connectWebhookStream, parseWebhookEventData} from './webhook-client';
+export type {
+  WebhookEventPayload,
+  WebhookEventStream,
+  WebhookEventType as WebhookEventTypeName,
+  WebhookListener,
+  WebhookListenerError,
+  WebhookListenerOptions,
+} from './webhook-client';
+export {kitApi, KitApiError} from './kit-api';
+export type {
+  KitApiOptions,
+  KitSubscription,
+  EntitlementsResponse,
+  StatusResponse,
+} from './kit-api';
 export {
   ErrorCodeUtils,
   ErrorCodeMapping,