@ait-kit/sdk 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 imjlk
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,236 @@
+# @ait-kit/sdk
+
+Frontend SDK adapters for Apps in Toss mini apps: shared contracts plus
+per-runtime entry points.
+
+```bash
+npm install @ait-kit/sdk
+```
+
+## Entry points
+
+| Entry | Use it for |
+|---|---|
+| `@ait-kit/sdk` (root) | Runtime-neutral shared contracts: ad + IAP types, `SdkError`. Importable anywhere — plain Node, web, React Native — with no official SDK installed. |
+| `@ait-kit/sdk/rn` | React Native adapters (full-screen ads, IAP). Requires the official `@apps-in-toss/framework`, declared as an **optional peer** and imported lazily. Never requires the web SDK. |
+| `@ait-kit/sdk/web` | Web adapters (IAP). Requires the official `@apps-in-toss/web-framework`, declared as an **optional peer** and imported lazily. Never requires the React Native SDK. |
+
+The two platform entries share one internal engine but keep completely
+separate SDK connections — in JavaScript and in the shipped type
+declarations — so an `/rn` consumer never installs the web package and vice
+versa.
+
+## In-app purchases (RN + Web)
+
+Both entries expose the same IAP surface; only the loader differs:
+
+```ts
+import { createReactNativeIap } from "@ait-kit/sdk/rn";   // or:
+import { createWebIap } from "@ait-kit/sdk/web";
+
+const iap = createReactNativeIap({
+  // The ONLY place product delivery happens. Resolve only after YOUR
+  // server verified the order with the provider and persisted the grant
+  // (see @ait-kit/api-core's iapOrderStatus for server-side verification).
+  grant: async ({ orderId, sku }) => {
+    const response = await fetch("/api/iap/grant", {
+      method: "POST",
+      body: JSON.stringify({ orderId, sku })
+    });
+    if (!response.ok) {
+      // Resolve-only-on-success is part of the contract: never report a
+      // grant your server did not verify and persist.
+      throw new Error(`grant request failed: HTTP ${response.status}`);
+    }
+  }
+});
+
+// 1. Start a purchase.
+const result = await iap.purchaseOneTime("SKU_100_COINS");
+//    result.status: "completed" | "canceled" | "failed"
+//                | "grant_failed" | "unknown"
+
+// 2. Subscriptions work the same way.
+await iap.purchaseSubscription("SKU_PREMIUM", offerId);
+```
+
+`completed` requires **both** the platform's success event and your grant
+callback having resolved for the **same order**: a success event alone never
+completes a purchase, a grant for a different order ends as
+`failed`/`ORDER_MISMATCH`, and a failed server grant ends as `grant_failed`
+— never as purchase success. `unknown` (e.g. timeout) means the grant may
+still be in progress; the client timeout does not cancel it.
+
+### Duplicate grant control (client-side, scoped to one adapter)
+
+- Concurrent grants for the same order share one in-flight call — only for
+  identical targets (same `orderId` and `sku`; callers that do not know the
+  `subscriptionId`, like pending-order recovery, may join a cached
+  subscription grant). Explicitly conflicting duplicates reject.
+- A successfully granted order is reused within the adapter's scope for the
+  same target (a later recovery or duplicate success does not re-run your
+  server call).
+- Failed grants are not cached — the next attempt retries for real.
+- This only reduces duplicate client work: **server-side grant idempotency
+  is still mandatory** (verify the order, persist exactly once).
+
+### Pending-order recovery (never automatic)
+
+```ts
+const { orders } = await iap.getPendingOrders();
+for (const order of orders) {
+  // Runs (or reuses) the server grant FIRST; the platform's
+  // completeProductGrant notification is sent only after it confirms.
+  const outcome = await iap.recoverPendingOrder(order);
+  // outcome.status: "completed" | "grant_failed" | "notify_failed"
+}
+```
+
+SDK initialization never grants or completes pending orders by itself.
+
+### Feature matrix
+
+| Capability | `/rn` | `/web` | Notes |
+|---|---|---|---|
+| Product list | ✅ | ✅ | one-time + subscription together |
+| One-time purchase | ✅ | ✅ | grant callback contract applies |
+| Subscription purchase | ✅ | ✅ | `offerId` optional; `subscriptionId` surfaced on completion |
+| Pending orders | ✅ | ✅ | recovery is consumer-driven |
+| Grant completion notify | ✅ | ✅ | sent only after server grant confirms |
+| Full-screen ads | ✅ | ➖ | ads are RN-only today |
+| Notification agreement | ✅ | ✅ | event-based, one template per request |
+| Share link / share sheet | ✅ | ✅ | `intoss://` paths; `closed` ≠ shared |
+| Unsupported app version | `SdkError("UNSUPPORTED")` | same | per-function `isSupported` gates |
+
+Notification and sharing adapters ship in both entries (see below).
+
+## Login, anonymous identity, and storage (RN + Web)
+
+```ts
+import { createReactNativeIdentity, createReactNativeStorage } from "@ait-kit/sdk/rn";
+// or: import { createWebIdentity, createWebStorage } from "@ait-kit/sdk/web";
+
+const identity = createReactNativeIdentity();
+
+// 1. Login: the adapter validates and preserves authorizationCode/referrer.
+const login = await identity.login();
+//    Forward BOTH values to YOUR server for the token exchange
+//    (@ait-kit/api-core exposes the server-side endpoint) and create the
+//    application session there. The adapter never performs the exchange.
+
+// 2. Anonymous key: { type: "HASH", hash } or a typed error — never a
+//    fabricated key.
+const anon = await identity.getAnonymousKey();
+
+// 3. Storage: string values, verbatim keys.
+const storage = createReactNativeStorage();
+await storage.set("cart:items", "[]");
+const raw = await storage.get("cart:items"); // string | null
+await storage.remove("cart:items");
+```
+
+Contracts:
+
+- **Login** results are validated (`authorizationCode` non-empty, `referrer`
+  one of the documented values) and preserved verbatim. Malformed results
+  reject with `SdkError("INVALID_LOGIN_RESULT")`; unsupported environments
+  with `UNSUPPORTED`; SDK rejections propagate unchanged.
+- **Anonymous key** results must be the documented `{ type: "HASH", hash }`
+  shape. Anything else (including sentinel values) rejects with
+  `SdkError("INVALID_ANONYMOUS_KEY")` — the adapter never invents a key.
+- **Storage** keys and string values pass through byte-for-byte: no
+  namespace prefixing, no key transformation. Compose namespaced keys
+  yourself (e.g. `cart:items`). `get` resolves `null` for missing keys;
+  `set`/`remove` rejections propagate so failures stay observable.
+- **No environment guessing**: the defaults never substitute a fake login
+  or storage based on the runtime. For development, inject an explicit
+  replacement via the `framework` option.
+- Session invalidation when the anonymous identifier changes, migration of
+  previously stored keys, and bootstrap sequencing stay with the consumer.
+
+## Notification agreement and sharing (RN + Web)
+
+```ts
+import {
+  createReactNativeNotification,
+  createReactNativeShare
+} from "@ait-kit/sdk/rn";
+// or: import { createWebNotification, createWebShare } from "@ait-kit/sdk/web";
+
+// 1. Notification agreement: one template, one request.
+const notification = createReactNativeNotification();
+const result = await notification.requestAgreement("TEMPLATE_CODE");
+// result.status: "agreed" (newAgreement | alreadyAgreed) | "rejected"
+//              | "failed" | "timeout"
+// result.templateCode and result.sourceEvent are preserved verbatim. The
+// outcome describes ONLY this request — it is not the user's global
+// notification setting, nor any server-persisted consent state. Syncing
+// consent to your server (and any smart-message sending) is your job.
+
+// 2. Share links: intoss:// deeplink paths, optional OG image.
+const share = createReactNativeShare();
+const link = await share.createLink("intoss://my-app/about", "https://cdn/og.png");
+
+// 3. Share sheet: "closed" means the sheet flow ended — nothing more.
+const uiResult = await share.sendMessage(`check this out ${link}`);
+// uiResult.status: "closed" | "failed" — closed does NOT prove the user
+// shared and never grants share-reward eligibility.
+```
+
+Contracts:
+
+- **Agreement** runs on the shared event-flow base: settle-once, duplicate/
+  late-event immunity, single error-swallowing cleanup, registration-throw
+  recovery, one overall deadline (`timeoutMs`, default 60s). SDK errors keep
+  their `code`/`reason`; timeouts report `timeout` with the template.
+- **Share links** validate the documented `intoss://` path contract
+  (`INVALID_SHARE_PATH` otherwise) and pass the resolved link through
+  verbatim. OG image generation is the consumer's concern.
+- **Share sheet** resolution is `closed`, not "completed" — reward grants
+  and completion tracking stay with the consumer.
+- Unsupported surfaces/app versions reject with `SdkError("UNSUPPORTED")`.
+
+## React Native full-screen ads
+
+```ts
+import { createReactNativeAds } from "@ait-kit/sdk/rn";
+
+const ads = createReactNativeAds();
+await ads.loadFullScreenAd("AD_GROUP_ID"); // joins an in-flight duplicate load
+const result = await ads.showFullScreenAd("AD_GROUP_ID");
+
+if (result.status === "rewarded") {
+  // result.reward came from the provider's userEarnedReward event — nothing
+  // else (load success, show success, dismissal) ever grants a reward.
+  // Verify against YOUR server before crediting anything.
+}
+```
+
+Behavior:
+
+- Load state is tracked per ad type + ad unit. Concurrent duplicate loads
+  share one registration; failed loads clear the slot so the next attempt
+  retries instead of being blocked.
+- Showing requires a completed load (`AD_NOT_LOADED` otherwise). The same ad
+  group cannot be shown concurrently (`AD_ALREADY_SHOWING`). Full-screen ads
+  are single-use: after a show flow ends (rewarded, dismissed, failed,
+  timeout), a fresh load is required.
+- The whole show flow has one deadline (`showTimeoutMs`, default 60s);
+  `loadTimeoutMs` (default 30s) bounds loads.
+- Missing or failed-to-import framework → `SdkError("SDK_UNAVAILABLE")`;
+  unsupported app versions → `SdkError("UNSUPPORTED")`. Load failures are
+  never permanently cached — a later call retries the import.
+- By default the adapter never fabricates ad success or reward results:
+  outcomes come only from the provider's events.
+
+## Responsibility split
+
+The SDK provides ad behavior and outcomes. Your application owns server-side
+ad reward requests, user session checks, payout limits, and ledger updates.
+(Login/anonymous-key helpers and storage arrive in later entries, as do
+notification and sharing.)
+
+## Versioning
+
+`@ait-kit/sdk` is versioned independently from the server API packages
+(`@ait-kit/api-*`), which release in lockstep with each other.

package/dist/event-flow.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Internal, runtime-neutral event flow used by the ad adapters (and later
+ * IAP flows). Not exported from any public subpath.
+ *
+ * Guarantees:
+ * - The promise settles exactly once: success, failure, timeout, or
+ *   cancellation are terminal and later events are ignored.
+ * - Cleanup runs at most once. Cleanup exceptions never block settlement
+ *   and never change an already-decided result.
+ * - SDK registration functions that invoke a callback synchronously and
+ *   then return the cleanup function are supported: the registration
+ *   wrapper defers cleanup attachment until register returns.
+ * - If the registration function itself throws, timers and any partially
+ *   registered resources are cleaned up and the flow rejects.
+ */
+export type EventFlowResolution<TEvent, TResult> = {
+    done: true;
+    result: TResult;
+} | {
+    done: false;
+} | undefined;
+export interface EventFlowOptions<TEvent, TResult> {
+    /** Registers SDK listeners; receives the flow's emit function. Returns an optional cleanup. */
+    register: (emit: (event: TEvent) => void) => (() => void) | void;
+    /** Maps an emitted event to a terminal result; anything else keeps the flow running. */
+    reduce: (event: TEvent) => EventFlowResolution<TEvent, TResult>;
+    /** Produces the terminal result when timeoutMs elapses without a resolution. */
+    onTimeout: () => TResult;
+    /** Overall deadline; omit or pass 0 to disable. */
+    timeoutMs?: number;
+    /** Hooks for tests: scheduling and clock injection. */
+    schedule?: typeof setTimeout;
+    cancelSchedule?: typeof clearTimeout;
+}
+export declare function runEventFlow<TEvent, TResult>(options: EventFlowOptions<TEvent, TResult>): Promise<TResult>;
+//# sourceMappingURL=event-flow.d.ts.map

package/dist/event-flow.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"event-flow.d.ts","sourceRoot":"","sources":["../src/event-flow.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,MAAM,MAAM,mBAAmB,CAAC,MAAM,EAAE,OAAO,IAC3C;IAAE,IAAI,EAAE,IAAI,CAAC;IAAC,MAAM,EAAE,OAAO,CAAA;CAAE,GAC/B;IAAE,IAAI,EAAE,KAAK,CAAA;CAAE,GACf,SAAS,CAAC;AAEd,MAAM,WAAW,gBAAgB,CAAC,MAAM,EAAE,OAAO;IAC/C,+FAA+F;IAC/F,QAAQ,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,KAAK,CAAC,MAAM,IAAI,CAAC,GAAG,IAAI,CAAC;IACjE,wFAAwF;IACxF,MAAM,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,mBAAmB,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAChE,gFAAgF;IAChF,SAAS,EAAE,MAAM,OAAO,CAAC;IACzB,mDAAmD;IACnD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,uDAAuD;IACvD,QAAQ,CAAC,EAAE,OAAO,UAAU,CAAC;IAC7B,cAAc,CAAC,EAAE,OAAO,YAAY,CAAC;CACtC;AAED,wBAAgB,YAAY,CAAC,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,gBAAgB,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,OAAO,CAAC,CAqF1G"}

package/dist/event-flow.js

@@ -0,0 +1,101 @@
+/**
+ * Internal, runtime-neutral event flow used by the ad adapters (and later
+ * IAP flows). Not exported from any public subpath.
+ *
+ * Guarantees:
+ * - The promise settles exactly once: success, failure, timeout, or
+ *   cancellation are terminal and later events are ignored.
+ * - Cleanup runs at most once. Cleanup exceptions never block settlement
+ *   and never change an already-decided result.
+ * - SDK registration functions that invoke a callback synchronously and
+ *   then return the cleanup function are supported: the registration
+ *   wrapper defers cleanup attachment until register returns.
+ * - If the registration function itself throws, timers and any partially
+ *   registered resources are cleaned up and the flow rejects.
+ */
+export function runEventFlow(options) {
+    const { register, reduce, onTimeout, timeoutMs = 0 } = options;
+    const schedule = options.schedule ?? setTimeout;
+    const cancelSchedule = options.cancelSchedule ?? clearTimeout;
+    return new Promise((resolve, reject) => {
+        let settled = false;
+        let cleanedUp = false;
+        let timer;
+        let registeredCleanup;
+        const runCleanup = () => {
+            if (cleanedUp)
+                return;
+            cleanedUp = true;
+            if (timer !== undefined) {
+                cancelSchedule(timer);
+                timer = undefined;
+            }
+            if (registeredCleanup) {
+                const cleanup = registeredCleanup;
+                registeredCleanup = undefined;
+                try {
+                    cleanup();
+                }
+                catch {
+                    // Cleanup failures must never block or alter the settled result.
+                }
+            }
+        };
+        const settle = (result) => {
+            if (settled)
+                return;
+            settled = true;
+            runCleanup();
+            resolve(result);
+        };
+        const fail = (error) => {
+            if (settled)
+                return;
+            settled = true;
+            runCleanup();
+            reject(error);
+        };
+        const emit = (event) => {
+            if (settled)
+                return;
+            let resolution;
+            try {
+                resolution = reduce(event);
+            }
+            catch (error) {
+                // A throwing reducer must fail the flow instead of leaving it
+                // pending until the deadline (which may be disabled).
+                fail(error);
+                return;
+            }
+            if (resolution?.done) {
+                settle(resolution.result);
+            }
+        };
+        if (timeoutMs > 0) {
+            timer = schedule(() => {
+                settle(onTimeout());
+            }, timeoutMs);
+        }
+        try {
+            registeredCleanup = register(emit);
+        }
+        catch (error) {
+            fail(error);
+            return;
+        }
+        // register() may have emitted synchronously and settled the flow before
+        // its cleanup existed; runCleanup already fired without it, so invoke
+        // the returned cleanup here with the same error-swallowing guarantee.
+        if (settled && registeredCleanup) {
+            const cleanup = registeredCleanup;
+            registeredCleanup = undefined;
+            try {
+                cleanup();
+            }
+            catch {
+                // Same guarantee as runCleanup.
+            }
+        }
+    });
+}

package/dist/iap/adapter.d.ts

@@ -0,0 +1,47 @@
+import { type IapGrantCallback, type IapProduct } from "../index.js";
+import type { IapPendingOrder, IapPurchaseResult } from "../index.js";
+import { type IapPlatformLoader } from "./platform-contract.js";
+export interface IapAdapterOptions {
+    grant: IapGrantCallback;
+    /** Loader for the platform SDK module (already normalized per entry point). */
+    loader: IapPlatformLoader;
+    /** Overall deadline per purchase flow (default 180000ms; 0 disables). */
+    purchaseTimeoutMs?: number;
+}
+export interface IapRecoveryResult {
+    status: "completed" | "grant_failed" | "notify_failed";
+    orderId: string;
+    reason?: string;
+}
+export interface IapAdapter {
+    /** Lists purchasable products (one-time and subscription together). */
+    getProductItemList(): Promise<{
+        products: IapProduct[];
+    }>;
+    /**
+     * Starts a one-time purchase. Resolves `completed` only after the
+     * platform success event AND your grant callback confirmed the same
+     * order.
+     */
+    purchaseOneTime(sku: string): Promise<IapPurchaseResult>;
+    /** Starts a subscription purchase (optionally with a chosen offer). */
+    purchaseSubscription(sku: string, offerId?: string): Promise<IapPurchaseResult>;
+    /** Lists orders whose payment completed but whose grant was not finished. */
+    getPendingOrders(): Promise<{
+        orders: IapPendingOrder[];
+    }>;
+    /**
+     * Recovers one pending order: runs (or reuses) the server grant for the
+     * order first, and only after it confirms calls the platform's
+     * grant-completion notification. Never invoked automatically — the
+     * consumer drives recovery.
+     */
+    recoverPendingOrder(order: IapPendingOrder): Promise<IapRecoveryResult>;
+}
+/**
+ * Platform-neutral IAP adapter used by both entry points. The consumer's
+ * `grant` callback is the only place product delivery happens; the adapter
+ * contains no backend URLs, auth, or persistence.
+ */
+export declare function createIapAdapter(options: IapAdapterOptions): IapAdapter;
+//# sourceMappingURL=adapter.d.ts.map

package/dist/iap/adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../../src/iap/adapter.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,gBAAgB,EAErB,KAAK,UAAU,EAEhB,MAAM,aAAa,CAAC;AACrB,OAAO,KAAK,EACV,eAAe,EACf,iBAAiB,EAClB,MAAM,aAAa,CAAC;AAErB,OAAO,EAAE,KAAK,iBAAiB,EAA8B,MAAM,wBAAwB,CAAC;AAG5F,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE,gBAAgB,CAAC;IACxB,+EAA+E;IAC/E,MAAM,EAAE,iBAAiB,CAAC;IAC1B,yEAAyE;IACzE,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE,WAAW,GAAG,cAAc,GAAG,eAAe,CAAC;IACvD,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,UAAU;IACzB,uEAAuE;IACvE,kBAAkB,IAAI,OAAO,CAAC;QAAE,QAAQ,EAAE,UAAU,EAAE,CAAA;KAAE,CAAC,CAAC;IAC1D;;;;OAIG;IACH,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAAC;IACzD,uEAAuE;IACvE,oBAAoB,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAAC;IAChF,6EAA6E;IAC7E,gBAAgB,IAAI,OAAO,CAAC;QAAE,MAAM,EAAE,eAAe,EAAE,CAAA;KAAE,CAAC,CAAC;IAC3D;;;;;OAKG;IACH,mBAAmB,CAAC,KAAK,EAAE,eAAe,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAAC;CACzE;AAID;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,iBAAiB,GAAG,UAAU,CA0JvE"}

package/dist/iap/adapter.js

@@ -0,0 +1,175 @@
+import { SdkError } from "../index.js";
+import { IapGrantCoordinator } from "./grant-coordinator.js";
+import {} from "./platform-contract.js";
+import { runPurchaseFlow } from "./purchase-flow.js";
+const DEFAULT_PURCHASE_TIMEOUT_MS = 180_000;
+/**
+ * Platform-neutral IAP adapter used by both entry points. The consumer's
+ * `grant` callback is the only place product delivery happens; the adapter
+ * contains no backend URLs, auth, or persistence.
+ */
+export function createIapAdapter(options) {
+    const purchaseTimeoutMs = options.purchaseTimeoutMs ?? DEFAULT_PURCHASE_TIMEOUT_MS;
+    const coordinator = new IapGrantCoordinator(options.grant);
+    const load = async () => {
+        const result = await options.loader();
+        if (!result.available) {
+            throw new SdkError("SDK_UNAVAILABLE", result.reason);
+        }
+        return result.module;
+    };
+    /**
+     * Per-operation capability gate: an installed framework may expose some
+     * IAP functions but not others, so a missing function is UNSUPPORTED only
+     * when that specific operation is requested — never a blanket rejection.
+     */
+    const ensureOperation = (fn, label) => {
+        if (typeof fn !== "function") {
+            throw new SdkError("UNSUPPORTED", `the installed IAP SDK does not expose ${label}`);
+        }
+        const supported = fn;
+        if (typeof supported.isSupported === "function" && !supported.isSupported()) {
+            throw new SdkError("UNSUPPORTED", `${label} is not supported on this app version`);
+        }
+        return fn;
+    };
+    return {
+        async getProductItemList() {
+            const platform = await load();
+            ensureOperation(platform.getProductItemList, "getProductItemList");
+            // Called as a member so class-instance modules keep their receiver.
+            return platform.getProductItemList();
+        },
+        purchaseOneTime(sku) {
+            return purchaseWithDeadline(async (platform, remainingMs) => {
+                ensureOperation(platform.createOneTimePurchaseOrder, "one-time purchases");
+                return await runPurchaseFlow({
+                    startOrder: (params) => platform.createOneTimePurchaseOrder(params),
+                    coordinator,
+                    sku,
+                    subscription: false,
+                    timeoutMs: remainingMs
+                });
+            });
+        },
+        purchaseSubscription(sku, offerId) {
+            return purchaseWithDeadline(async (platform, remainingMs) => {
+                ensureOperation(platform.createSubscriptionPurchaseOrder, "subscription purchases");
+                return await runPurchaseFlow({
+                    startOrder: (params) => platform.createSubscriptionPurchaseOrder(params),
+                    coordinator,
+                    sku,
+                    ...(offerId !== undefined ? { offerId } : {}),
+                    subscription: true,
+                    timeoutMs: remainingMs
+                });
+            });
+        },
+        async getPendingOrders() {
+            const platform = await load();
+            ensureOperation(platform.getPendingOrders, "getPendingOrders");
+            return platform.getPendingOrders();
+        },
+        async recoverPendingOrder(order) {
+            const platform = await load();
+            ensureOperation(platform.completeProductGrant, "completeProductGrant");
+            try {
+                // Server grant confirmation first (deduped within this adapter's
+                // scope); the completion notification follows only after it.
+                await coordinator.run({ orderId: order.orderId, sku: order.sku });
+            }
+            catch (error) {
+                const reason = error instanceof Error ? error.message : String(error);
+                return { status: "grant_failed", orderId: order.orderId, reason };
+            }
+            const notified = await notifyGrantComplete(platform, order.orderId);
+            if (!notified.ok) {
+                return {
+                    status: "notify_failed",
+                    orderId: order.orderId,
+                    reason: notified.reason
+                };
+            }
+            return { status: "completed", orderId: order.orderId };
+        }
+    };
+    /**
+     * Runs a purchase under one overall deadline that also covers platform
+     * loading. Only the loading phase races the outer deadline — the purchase
+     * flow owns the remaining budget exclusively, so its order-aware timeout
+     * result is never preempted by a generic one. A stalled loader cannot
+     * wedge checkout, and a loader resolving after the deadline never
+     * registers the purchase.
+     */
+    async function purchaseWithDeadline(run) {
+        const timedOut = () => ({
+            status: "unknown",
+            reason: "purchase flow timed out; the server grant may still be in progress — verify the order server-side and recover it via pending orders"
+        });
+        if (!(purchaseTimeoutMs > 0)) {
+            return run(await load(), 0);
+        }
+        const startedAt = Date.now();
+        let cancelled = false;
+        let timer;
+        const loadDeadline = new Promise((resolve) => {
+            timer = setTimeout(() => {
+                cancelled = true;
+                resolve(null);
+            }, purchaseTimeoutMs);
+        });
+        let platform;
+        try {
+            platform = await Promise.race([
+                load().then((loaded) => (cancelled ? null : loaded)),
+                loadDeadline
+            ]);
+        }
+        finally {
+            if (timer !== undefined)
+                clearTimeout(timer);
+        }
+        if (!platform || cancelled || Date.now() - startedAt >= purchaseTimeoutMs) {
+            // The loader may resolve as an overdue microtask before the timer
+            // callback runs; a fresh clock comparison is authoritative.
+            return timedOut();
+        }
+        const remainingMs = Math.max(1, purchaseTimeoutMs - (Date.now() - startedAt));
+        const result = await run(platform, remainingMs);
+        if (Date.now() - startedAt >= purchaseTimeoutMs) {
+            // A synchronous startOrder can block past the deadline and settle the
+            // flow before the overdue timer callback runs. The deadline is the
+            // deadline: preserve any order identity the result already carries
+            // for server-side recovery.
+            const identified = result;
+            return {
+                ...timedOut(),
+                ...(identified.orderId !== undefined ? { orderId: identified.orderId } : {}),
+                ...(identified.subscriptionId !== undefined
+                    ? { subscriptionId: identified.subscriptionId }
+                    : {})
+            };
+        }
+        return result;
+    }
+}
+async function notifyGrantComplete(platform, orderId) {
+    let notified;
+    try {
+        notified = await platform.completeProductGrant({ params: { orderId } });
+    }
+    catch (error) {
+        const reason = error instanceof Error ? error.message : String(error);
+        return {
+            ok: false,
+            reason: `completeProductGrant rejected: ${reason}; retry — the server grant is already confirmed in this scope`
+        };
+    }
+    if (!notified) {
+        return {
+            ok: false,
+            reason: "completeProductGrant returned false; retry — the server grant is already confirmed in this scope"
+        };
+    }
+    return { ok: true };
+}

package/dist/iap/grant-coordinator.d.ts

@@ -0,0 +1,36 @@
+import type { IapGrantTarget } from "./platform-contract.js";
+/**
+ * Client-side dedupe for server grant callbacks, scoped to one adapter
+ * instance (one "processing scope"):
+ *
+ * - Concurrent grants for the same order share the in-flight Promise, so a
+ *   duplicate callback never re-runs the server request.
+ * - A successfully granted order is reused within the same scope: later
+ *   flows (pending-order recovery, duplicate success events) resolve
+ *   immediately instead of re-granting.
+ * - Failed grants are never cached: the entry is removed when the attempt
+ *   rejects, so the next call retries for real.
+ *
+ * This only reduces duplicate client-side work. Server-side grant
+ * idempotency (verify the order, persist exactly once) is a separate,
+ * mandatory server responsibility.
+ */
+export declare class IapGrantCoordinator {
+    private readonly grant;
+    private readonly inFlight;
+    private readonly granted;
+    constructor(grant: (target: IapGrantTarget) => Promise<void>);
+    /**
+     * Runs (or joins) the grant for the target order. Resolves when the
+     * consumer's callback resolves; rejects with the callback's error when it
+     * fails, leaving the order retryable. A duplicate joins only when it
+     * describes the same target: orderId and sku must match, and a caller
+     * that does not know the subscriptionId (pending-order recovery) may join
+     * a cached subscription grant. Explicitly conflicting duplicates reject
+     * instead of silently inheriting another flow's grant.
+     */
+    run(target: IapGrantTarget): Promise<void>;
+    /** True when this scope already granted the order successfully. */
+    isGranted(orderId: string): boolean;
+}
+//# sourceMappingURL=grant-coordinator.d.ts.map

package/dist/iap/grant-coordinator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"grant-coordinator.d.ts","sourceRoot":"","sources":["../../src/iap/grant-coordinator.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAE7D;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,mBAAmB;IAIlB,OAAO,CAAC,QAAQ,CAAC,KAAK;IAHlC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAyE;IAClG,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAqC;IAE7D,YAA6B,KAAK,EAAE,CAAC,MAAM,EAAE,cAAc,KAAK,OAAO,CAAC,IAAI,CAAC,EAAI;IAEjF;;;;;;;;OAQG;IACH,GAAG,CAAC,MAAM,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC,CAoCzC;IAED,mEAAmE;IACnE,SAAS,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAElC;CACF"}