expo-iap 4.2.2 → 4.2.4

package/src/useWebhookEvents.ts

@@ -0,0 +1,155 @@
+import {useEffect, useRef, useState} from 'react';
+
+import {
+  connectWebhookStream,
+  type WebhookEventPayload,
+  type WebhookEventStream,
+  type WebhookListener,
+  type WebhookListenerError,
+} from './webhook-client';
+
+export type UseWebhookEventsOptions = {
+  apiKey: string | null | undefined;
+  baseUrl?: string;
+  eventSourceFactory?: (
+    url: string,
+    headers: Record<string, string>,
+  ) => WebhookEventStream;
+  bufferSize?: number;
+  onEvent?: (event: WebhookEventPayload) => void;
+  onError?: (error: WebhookListenerError) => void;
+};
+
+export type UseWebhookEventsResult = {
+  /** Most recent N events (most-recent-first). Capped at bufferSize. */
+  events: WebhookEventPayload[];
+  /** Last error reported by the underlying stream. Null when healthy. */
+  lastError: WebhookListenerError | null;
+  /**
+   * True once the first webhook event has been received from the
+   * stream. Remains false if the connection is open but idle (the
+   * underlying SSE bridge doesn't surface a "stream opened"
+   * lifecycle event we can hook into; isConnected is therefore an
+   * activity indicator, not a raw socket-state flag). Reset to
+   * false on cleanup / apiKey change.
+   */
+  isConnected: boolean;
+};
+
+// React hook wrapping the kit SSE webhook stream. See
+// `libraries/react-native-iap/src/hooks/useWebhookEvents.ts` for the
+// canonical version — this file mirrors it 1:1 because expo-iap and
+// react-native-iap share the JS/TS SSE wire format. The intentional
+// duplication keeps each library self-contained (no cross-package
+// runtime dep) at the cost of a coordinated edit when the surface
+// changes; that's checked by the SDK Parity Checklist in
+// `knowledge/internal/04-platform-packages.md`.
+export function useWebhookEvents({
+  apiKey,
+  baseUrl,
+  eventSourceFactory,
+  bufferSize = 50,
+  onEvent,
+  onError,
+}: UseWebhookEventsOptions): UseWebhookEventsResult {
+  const [events, setEvents] = useState<WebhookEventPayload[]>([]);
+  const [lastError, setLastError] = useState<WebhookListenerError | null>(null);
+  const [isConnected, setIsConnected] = useState(false);
+
+  const onEventRef = useRef(onEvent);
+  const onErrorRef = useRef(onError);
+  // Hold `eventSourceFactory` in a ref too so a caller passing an
+  // anonymous function literal (the common React pitfall) doesn't
+  // tear down the SSE connection on every render. We still capture
+  // the latest factory so a runtime-config swap (e.g. apiKey changes
+  // and a new EventSource constructor is needed) is honored on the
+  // next connect, but the *identity* of the factory no longer drives
+  // useEffect.
+  const eventSourceFactoryRef = useRef(eventSourceFactory);
+  // Holding bufferSize in a ref so adjusting it from the host
+  // component doesn't tear down the SSE connection. Same reasoning
+  // as onEvent / onError: a re-render with a new bufferSize would
+  // otherwise re-fire useEffect, close the stream, and reconnect
+  // (losing in-flight events the SSE handler had already buffered).
+  const bufferSizeRef = useRef(bufferSize);
+  onEventRef.current = onEvent;
+  onErrorRef.current = onError;
+  eventSourceFactoryRef.current = eventSourceFactory;
+  bufferSizeRef.current = bufferSize;
+
+  // Trim the existing buffer when the host lowers `bufferSize`
+  // mid-stream. The ref-based update only takes effect on the next
+  // event arrival, which can leave the visible buffer above the new
+  // cap until traffic resumes — this effect enforces the cap
+  // immediately on the change instead.
+  useEffect(() => {
+    setEvents((prev) => (bufferSize > 0 ? prev.slice(0, bufferSize) : []));
+  }, [bufferSize]);
+
+  useEffect(() => {
+    // Reset surfaced state on every (re)connect target so a stale
+    // event from the prior stream can't briefly leak into a new
+    // apiKey/baseUrl context. Matches the SSE convention of
+    // "fresh stream → fresh history."
+    setEvents([]);
+    setLastError(null);
+
+    if (!apiKey) {
+      return;
+    }
+
+    let listener: WebhookListener | null = null;
+    let mounted = true;
+
+    try {
+      listener = connectWebhookStream({
+        apiKey,
+        baseUrl,
+        eventSourceFactory: eventSourceFactoryRef.current,
+        onEvent: (event) => {
+          if (!mounted) {
+            return;
+          }
+          setIsConnected(true);
+          const cap = bufferSizeRef.current;
+          if (cap > 0) {
+            setEvents((prev) => [event, ...prev].slice(0, cap));
+          }
+          onEventRef.current?.(event);
+        },
+        onError: (error) => {
+          if (!mounted) {
+            return;
+          }
+          setLastError(error);
+          onErrorRef.current?.(error);
+        },
+      });
+    } catch (error) {
+      const wrapped: WebhookListenerError = {
+        code: 'TRANSPORT_ERROR',
+        message:
+          error instanceof Error
+            ? error.message
+            : 'Failed to open webhook stream',
+        cause: error,
+      };
+      setLastError(wrapped);
+      onErrorRef.current?.(wrapped);
+    }
+
+    return () => {
+      mounted = false;
+      listener?.close();
+      setIsConnected(false);
+    };
+    // `eventSourceFactory` deliberately omitted from deps — held in a
+    // ref above so anonymous-function callers don't trigger reconnects
+    // on every render. The connection is only re-opened when apiKey or
+    // baseUrl changes; a runtime factory swap is picked up on that
+    // next reconnect via the ref.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [apiKey, baseUrl]);
+
+  return {events, lastError, isConnected};
+}

package/src/webhook-client.ts

@@ -0,0 +1,314 @@
+// 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 type WebhookEventType =
+  | 'SubscriptionStarted'
+  | 'SubscriptionRenewed'
+  | 'SubscriptionExpired'
+  | 'SubscriptionInGracePeriod'
+  | 'SubscriptionInBillingRetry'
+  | 'SubscriptionRecovered'
+  | 'SubscriptionCanceled'
+  | 'SubscriptionUncanceled'
+  | 'SubscriptionRevoked'
+  | 'SubscriptionPriceChange'
+  | 'SubscriptionProductChanged'
+  | 'SubscriptionPaused'
+  | 'SubscriptionResumed'
+  | 'PurchaseRefunded'
+  | 'PurchaseConsumptionRequest'
+  | 'TestNotification';
+
+export const WEBHOOK_EVENT_TYPES = [
+  'SubscriptionStarted',
+  'SubscriptionRenewed',
+  'SubscriptionExpired',
+  'SubscriptionInGracePeriod',
+  'SubscriptionInBillingRetry',
+  'SubscriptionRecovered',
+  'SubscriptionCanceled',
+  'SubscriptionUncanceled',
+  'SubscriptionRevoked',
+  'SubscriptionPriceChange',
+  'SubscriptionProductChanged',
+  'SubscriptionPaused',
+  'SubscriptionResumed',
+  'PurchaseRefunded',
+  'PurchaseConsumptionRequest',
+  'TestNotification',
+] as const satisfies readonly WebhookEventType[];
+
+export type WebhookEventPayload = {
+  id: string;
+  type: WebhookEventType;
+  source: string;
+  platform: 'IOS' | 'Android';
+  environment: 'Production' | 'Sandbox' | 'Xcode';
+  projectId: string;
+  occurredAt: number;
+  receivedAt: number;
+  // Optional because TestNotification frames carry no transaction;
+  // every other event type populates this.
+  purchaseToken?: string;
+  productId?: string;
+  subscriptionState?: string;
+  expiresAt?: number;
+  renewsAt?: number;
+  cancellationReason?: string;
+  currency?: string;
+  priceAmountMicros?: number;
+  rawSignedPayload?: string;
+};
+
+export type WebhookListenerOptions = {
+  /**
+   * Project API key. Embedded in the URL path because Apple ASN
+   * registration cannot send custom headers; the same path is reused
+   * here for symmetry.
+   */
+  apiKey: string;
+  /**
+   * Override the kit base URL. Defaults to https://kit.openiap.dev.
+   * In tests, point this at a local server.
+   */
+  baseUrl?: string;
+  /** Called on every successfully-parsed webhook event. */
+  onEvent: (event: WebhookEventPayload) => void;
+  /**
+   * Called on transport errors. The connection auto-reconnects
+   * unconditionally; this callback exists for telemetry / surfacing
+   * to the host UI.
+   */
+  onError?: (error: WebhookListenerError) => void;
+  /**
+   * Optional injection of an EventSource constructor. Lets RN /
+   * Expo plug in `react-native-event-source` when running on a JS
+   * runtime that lacks the global, or vitest plug in a stub.
+   */
+  eventSourceFactory?: (
+    url: string,
+    headers: Record<string, string>,
+  ) => WebhookEventStream;
+};
+
+export interface WebhookEventStream {
+  close(): void;
+  onmessage: ((event: {data: string; lastEventId?: string}) => void) | null;
+  onerror: ((error: unknown) => void) | null;
+  addEventListener?: (
+    type: string,
+    listener: (event: {data: string; lastEventId?: string}) => void,
+  ) => void;
+}
+
+export type WebhookListener = {
+  /** Tear down the connection and stop receiving events. */
+  close(): void;
+};
+
+export type WebhookListenerError = {
+  code:
+    | 'TRANSPORT_ERROR'
+    | 'PARSE_ERROR'
+    | 'MALFORMED_EVENT'
+    | 'NO_EVENTSOURCE';
+  message: string;
+  cause?: unknown;
+};
+
+const DEFAULT_BASE_URL = 'https://kit.openiap.dev';
+
+export function connectWebhookStream(
+  options: WebhookListenerOptions,
+): WebhookListener {
+  const baseUrl = options.baseUrl ?? DEFAULT_BASE_URL;
+  const url = `${trimTrailingSlash(
+    baseUrl,
+  )}/v1/webhooks/stream/${encodeURIComponent(options.apiKey)}`;
+
+  const factory = options.eventSourceFactory ?? defaultEventSourceFactory;
+  let stream: WebhookEventStream;
+  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<string>();
+  const seenOrder: string[] = [];
+  const markSeen = (id: string): boolean => {
+    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: string) => {
+    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.
+      }
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Pure helpers (exported for testing).
+// ---------------------------------------------------------------------------
+
+export type ParsedEventResult =
+  | {kind: 'ok'; event: WebhookEventPayload}
+  | {kind: 'skip'; reason: 'heartbeat' | 'stream-control'}
+  | {kind: 'error'; message: string};
+
+export function parseWebhookEventData(raw: string): ParsedEventResult {
+  if (!raw) {
+    return {kind: 'skip', reason: 'heartbeat'};
+  }
+
+  let parsed: unknown;
+  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 as Record<string, unknown>).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 as WebhookEventPayload;
+
+  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: string): string {
+  return url.endsWith('/') ? url.slice(0, -1) : url;
+}
+
+function defaultEventSourceFactory(
+  url: string,
+  _headers: Record<string, string>,
+): WebhookEventStream {
+  // 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 as {
+      EventSource?: new (url: string) => WebhookEventStream;
+    }
+  ).EventSource;
+  if (!ctor) {
+    throw new Error(
+      'EventSource is not defined. Pass `eventSourceFactory` for runtimes without a built-in EventSource.',
+    );
+  }
+  return new ctor(url);
+}