@ait-kit/sdk 0.3.0 → 0.5.0

package/README.md

@@ -13,20 +13,20 @@ npm install @ait-kit/sdk
 |---|---|
 | `@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. |
+| `@ait-kit/sdk/webview` | WebView adapters for ads, banners, purchases, identity, storage, notifications, sharing, reviews, and promotions. 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)
+## In-app purchases (RN + WebView)
 
 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";
+import { createWebViewIap } from "@ait-kit/sdk/webview";
 
 const iap = createReactNativeIap({
   // The ONLY place product delivery happens. Resolve only after YOUR
@@ -90,25 +90,28 @@ SDK initialization never grants or completes pending orders by itself.
 
 ### Feature matrix
 
-| Capability | `/rn` | `/web` | Notes |
+| Capability | `/rn` | `/webview` | Notes |
 |---|---|---|---|
 | Product list | ✅ | ✅ | one-time + subscription together |
 | One-time purchase | ✅ | ✅ | grant callback contract applies |
 | Subscription purchase | ✅ | ✅ | `offerId` optional; `subscriptionId` surfaced on completion |
+| Subscription info | ✅ | ✅ | read-only provider status and access snapshot |
+| Completed/refunded orders | ✅ cursor | ✅ first page only | read-only; no automatic restore or refund actions |
 | Pending orders | ✅ | ✅ | recovery is consumer-driven |
 | Grant completion notify | ✅ | ✅ | sent only after server grant confirms |
-| Full-screen ads | ✅ | ➖ | ads are RN-only today |
+| Full-screen / rewarded ads | ✅ | ✅ | reward events only; reload after each show |
+| Banner lifecycle | ➖ | ✅ | initialize, attach, cancel, and destroy an owned handle |
 | Notification agreement | ✅ | ✅ | event-based, one template per request |
 | Share link / share sheet | ✅ | ✅ | `intoss://` paths; `completed` ≠ 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)
+## Login, anonymous identity, and storage (RN + WebView)
 
 ```ts
 import { createReactNativeIdentity, createReactNativeStorage } from "@ait-kit/sdk/rn";
-// or: import { createWebIdentity, createWebStorage } from "@ait-kit/sdk/web";
+// or: import { createWebViewIdentity, createWebViewStorage } from "@ait-kit/sdk/webview";
 
 const identity = createReactNativeIdentity();
 
@@ -153,14 +156,14 @@ Contracts:
 - 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)
+## Notification agreement and sharing (RN + WebView)
 
 ```ts
 import {
   createReactNativeNotification,
   createReactNativeShare
 } from "@ait-kit/sdk/rn";
-// or: import { createWebNotification, createWebShare } from "@ait-kit/sdk/web";
+// or: import { createWebViewNotification, createWebViewShare } from "@ait-kit/sdk/webview";
 
 // 1. Notification agreement: one template, one request.
 const notification = createReactNativeNotification();
@@ -197,11 +200,12 @@ Contracts:
   stay with the consumer. (Renamed from `closed` in 0.3.0; see Migrating.)
 - Unsupported surfaces/app versions reject with `SdkError("UNSUPPORTED")`.
 
-## React Native full-screen ads
+## React Native and WebView full-screen ads
 
 ```ts
 import { createReactNativeAds } from "@ait-kit/sdk/rn";
 
+// WebView: import { createWebViewAds } from "@ait-kit/sdk/webview";
 const ads = createReactNativeAds();
 await ads.loadFullScreenAd("AD_GROUP_ID"); // joins an in-flight duplicate load
 const result = await ads.showFullScreenAd("AD_GROUP_ID");
@@ -243,8 +247,7 @@ Behavior:
 
 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.)
+Identity, storage, notification, and sharing adapters are also available in both entries.
 
 ## Versioning
 
@@ -259,7 +262,7 @@ official releases (see `scripts/test-package-tarballs.mjs`):
 | Official package | Verified version | Peer range |
 |---|---|---|
 | `@apps-in-toss/framework` (RN) | 2.10.10 | `>=2.10.10` |
-| `@apps-in-toss/web-framework` (Web) | 3.4.0 | `>=3.4.0` |
+| `@apps-in-toss/web-framework` (WebView) | 3.4.0 | `>=3.4.0` |
 
 Older versions may work where the runtime surfaces match (every capability
 is checked per function and missing ones reject with `UNSUPPORTED`), but
@@ -293,3 +296,184 @@ resolving `undefined` (installed app below the feature's minimum version)
 now rejects with `SdkError("UNSUPPORTED")` instead of
 `INVALID_ANONYMOUS_KEY`; the `"ERROR"` sentinel still rejects with
 `INVALID_ANONYMOUS_KEY`.
+
+## Review requests
+
+```ts
+import { createReactNativeReview } from "@ait-kit/sdk/rn";
+// WebView: import { createWebViewReview } from "@ait-kit/sdk/webview";
+const review = createReactNativeReview(); // share one instance across screens
+if (await review.isSupported()) await review.request();
+```
+
+`ReviewAdapter` is a runtime-neutral root type. Factories accept `framework`
+(shared `Review.request` contract or async loader), like the existing adapters.
+RN translates the official `requestReview()` export; WebView calls `Review.request()`.
+The official SDK loads only on use. Missing features/support checkers return
+`false`; import failure throws `SDK_UNAVAILABLE`; support-check exceptions propagate.
+`request()` rechecks support and throws `UNSUPPORTED` when unavailable.
+Concurrent requests on one instance share one Promise, cleared after success or
+failure. There is no retry or timeout.
+
+`Promise<void>` completion does not establish whether UI appeared or a review
+was written. Never grant rewards, unlock features, or block navigation on review
+completion. Complete and persist the core action first, then start a separately
+error-handled review request without awaiting it in the core flow. The consumer
+owns request timing, session limits, cooldowns and storage. Do not log raw SDK
+errors by default.
+
+Official reference: [Review.request](https://developers-apps-in-toss.toss.im/documentation/sdk/domains-api/review/review.request.md)
+(Android/iOS Toss 5.253.0+, checked by the SDK). Verified package surfaces:
+RN 2.10.10 and WebView 3.4.0. Device UI behavior requires separate manual verification;
+unit/tarball tests use injected SDKs or a stubbed native bridge.
+
+## Explicit direct promotion rewards
+
+```ts
+import { createReactNativePromotion } from "@ait-kit/sdk/rn";
+// WebView: import { createWebViewPromotion } from "@ait-kit/sdk/webview";
+const promotion = createReactNativePromotion({ timeoutMs: 15_000 });
+const support = await promotion.getSupport();
+// RN 2.10.10 exposes no support checker: support is "unknown", not "supported".
+// Opt into direct grants explicitly, with app-specific eligibility/budget checks.
+```
+
+`PromotionAdapter`, `PromotionSupport`, `PromotionGrantInput` and
+`PromotionGrantResult` are runtime-neutral root types. Both factories accept
+`framework` (shared `Promotion.grantReward` contract or async loader).
+RN calls `grantPromotionReward({ params: { promotionCode, amount } })`;
+WebView calls only `Promotion.grantReward({ promotionCode, amount })`.
+There is no legacy WebView fallback or fallback to/from server payment flows.
+
+`getSupport()` reports `unsupported` for missing functions or an explicit false
+check, `supported` for a true check, and `unknown` when a function has no checker.
+Import failures throw `SDK_UNAVAILABLE`; support-check exceptions propagate.
+Every grant rechecks support. RN's documented `undefined` and the provider's
+`UNSUPPORTED_APP_VERSION` throw `UNSUPPORTED`; malformed WebView responses stay unknown.
+
+Input errors throw `INVALID_PROMOTION_INPUT` before loading/calling the SDK:
+`promotionCode` must be non-empty without surrounding whitespace (never trimmed
+into a different code), and `amount` must be a positive safe integer. Campaign
+eligibility, maximum amounts and budgets remain the consumer's responsibility.
+
+Results:
+
+- `granted` has a non-empty `rewardKey` and means only that the SDK reported success.
+- `rejected` carries an explicit documented refusal code: `4100`, `4104`, `4105`,
+  `4108`, `4109`, `4110`, `4112`, or `4114`.
+- `unknown` means confirmation is required: SDK exceptions/sentinels, malformed or
+  contradictory responses, deadlines, `UNKNOWN_ERROR`, `4113`, or new provider
+  codes. `4113` never becomes an inferred already-granted ledger state.
+
+Provider messages and raw errors are not included in grant results. Provider codes
+are retained only as bounded uppercase alphanumeric/underscore tokens; do not log
+reward keys, promotion codes or whole SDK responses.
+
+Share one adapter instance. A concurrent grant throws `PROMOTION_IN_PROGRESS`;
+completed results are never cached as idempotent payments. `timeoutMs` defaults to
+0 (disabled), accepts integers through 2147483647, and covers loading and the SDK
+call. Elapsed time is checked before dispatch and when the SDK settles, so delayed
+timer callbacks cannot start an overdue payment or turn a late result into success.
+After timeout the result is unknown, but the instance stays locked until the
+actual operation settles. A loader finishing after timeout never starts payment.
+A late success/failure cannot change the returned timeout result. There is no
+cancellation, automatic retry, or protection across instances/devices/restarts.
+
+Consumer UI pattern (all callbacks are supplied by the app):
+
+```ts
+async function grantOnce(input, ui) {
+  ui.disableGrantAction();
+  try {
+    const result = await promotion.grantReward(input);
+    if (result.status === "unknown") {
+      ui.showConfirmationRequired(); // keep disabled; never retry automatically
+      return;
+    }
+    ui.showSdkResult(result); // client report only; not a server ledger receipt
+  } catch {
+    ui.showConfirmationRequired(); // do not dump raw exceptions or auto-reenable
+  }
+}
+```
+
+Posting a client result to a server is not independent payment verification.
+Consumers requiring a server ledger must keep their existing three-stage server
+payment path. This API does not require client-side mTLS certificates/proxy tokens
+and does not replace TrailBase claims or owned-currency accounting.
+
+Official reference: [Promotion.grantReward](https://developers-apps-in-toss.toss.im/documentation/sdk/domains-api/promotion/promotion.grantreward.md).
+Contracts are checked against RN 2.10.10 and WebView 3.4.0 published types/code with
+synthetic bridge fixtures. Device checks and official test-promotion calls remain
+manual; no real promotion is invoked by tests.
+
+### WebView naming migration
+
+Use `@ait-kit/sdk/webview` and the `createWebView*` factories / `WebView*` types.
+The legacy `@ait-kit/sdk/web` entry, `createWeb*` factories, and `Web*` types remain
+available as deprecated aliases with identical behavior. The official peer package
+name remains `@apps-in-toss/web-framework`.
+
+WebView ads use the official flat `loadFullScreenAd` and `showFullScreenAd` exports.
+Create them with `createWebViewAds()` from `@ait-kit/sdk/webview`; the same
+load/show deadlines, single-use rules, and reward-event semantics described above apply.
+
+### Subscription status queries
+
+Both IAP adapters expose `getSubscriptionInfo(orderId)` and return `{ subscription }`
+with the provider's `catalogId`, `status`, `expiresAt`, `isAutoRenew`,
+`gracePeriodExpiresAt`, and `isAccessible` fields. Future status strings are preserved;
+access is never inferred from a status string. Treat this as a provider snapshot,
+not server-side entitlement verification. The query never calls `grant` or changes entitlements.
+
+Missing capabilities, unsupported host versions, and the RN unsupported `undefined`
+response throw `SdkError("UNSUPPORTED")`. Blank IDs throw `INVALID_IAP_INPUT`;
+malformed payloads throw `INVALID_IAP_RESULT`. Other provider errors remain observable.
+
+### Completed and refunded order history
+
+`iap.getCompletedOrRefundedOrders()` returns `{ orders, hasNext, nextKey?, pagination }`.
+Each order retains its provider `orderId`, `sku`, `status` (`COMPLETED` or `REFUNDED`),
+and `date`. This read-only query never grants goods or revokes entitlements.
+
+RN pages have `pagination: "cursor"`; pass `{ key: page.nextKey }` to explicitly
+request the next page when `hasNext` is true and a cursor is present. WebView pages
+have `pagination: "first_page_only"`: the current official WebView SDK accepts no
+cursor. `hasNext` may still be true, but passing a non-null key throws `UNSUPPORTED`
+before provider dispatch. Do not loop WebView page-one calls or treat them as a full restore.
+
+Missing/unsupported capabilities throw `UNSUPPORTED`, malformed inputs throw
+`INVALID_IAP_INPUT`, and malformed pages throw `INVALID_IAP_RESULT`. Other provider
+errors propagate without automatic retries.
+
+### WebView banner ads
+
+```ts
+import { createWebViewBannerAds } from "@ait-kit/sdk/webview";
+const ads = createWebViewBannerAds();
+const controller = new AbortController();
+const banner = await ads.attachBanner("AD_GROUP_ID", "#banner", {
+  theme: "auto", tone: "grey", variant: "card", signal: controller.signal,
+  callbacks: { onNoFill: () => console.log("No banner available") }
+});
+// On unmount: controller.abort() also cancels a pending attachment.
+banner.destroy(); // idempotent; only this handle is destroyed
+```
+
+Initialization is lazy, shared within an adapter, and bounded by `initializeTimeoutMs`
+(default 15 seconds; integer milliseconds from 1 to 2,147,483,647). A failed initialization can be retried.
+An attachment resolves when the provider returns its handle; it does not claim that an
+ad rendered or earned a reward. Render/view/click/impression/failure/no-fill callbacks
+are forwarded on a microtask and suppressed after destruction. Synchronous attachment
+failure rejects with `BANNER_ATTACH_FAILED`.
+
+Each live attachment must own a distinct DOM element. SDK instances reject duplicate
+targets with `BANNER_TARGET_IN_USE` until the previous handle is destroyed. Do not mix
+raw provider attachments and adapter attachments on the same element. No global
+`TossAds.destroyAll()` call is made. Use an `AbortSignal` when the target may unmount
+while initialization is pending; the pending call rejects after initialization settles
+and never attaches to an aborted target.
+
+If provider cleanup throws, the handle still becomes locally destroyed and releases its
+target claim; the provider exception remains observable. An attachment failure combined
+with a cleanup failure rejects with an `AggregateError` retaining both errors.

package/dist/ads/adapter.d.ts

@@ -0,0 +1,36 @@
+import { type AdShowResult } from "../index.js";
+import type { FullScreenAdSupport } from "./platform-contract.js";
+import type { PlatformLoader } from "../platform-loader.js";
+export type AdsPlatformLoader = PlatformLoader<FullScreenAdSupport>;
+/** Ad kinds the SDK distinguishes; only full-screen ads exist today. */
+export type SdkAdType = "fullscreen";
+export interface AdsOptions {
+    /** Resolved platform loader, supplied by the runtime-specific factory. */
+    loader: AdsPlatformLoader;
+    /** Overall deadline for the show flow (default 60000ms; 0 disables). */
+    showTimeoutMs?: number;
+    /**
+     * Overall deadline for each load, covering framework acquisition and the
+     * provider load flow (default 30000ms; 0 disables).
+     */
+    loadTimeoutMs?: number;
+}
+export interface AdsAdapter {
+    /** Loads (or joins an in-flight load of) the full-screen ad for adGroupId. */
+    loadFullScreenAd(adGroupId: string): Promise<void>;
+    /**
+     * Shows the full-screen ad whose load already completed and resolves with
+     * its terminal outcome. The ad is single-use and claimed synchronously:
+     * once a show starts, the unit needs a fresh load for the next attempt.
+     */
+    showFullScreenAd(adGroupId: string): Promise<AdShowResult>;
+}
+/**
+ * Shared full-screen ad adapter. Load state is
+ * tracked per ad type + ad unit, in-flight duplicate loads share one
+ * request, and rewards come only from the provider's `userEarnedReward`
+ * event. The adapter produces ad outcomes; server-side reward requests,
+ * session checks, and ledger handling belong to the consumer.
+ */
+export declare function createAdsAdapter(options: AdsOptions): AdsAdapter;
+//# sourceMappingURL=adapter.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../../src/ads/adapter.ts"],"names":[],"mappings":"AAAA,OAAO,EAA2B,KAAK,YAAY,EAAE,MAAM,aAAa,CAAC;AAEzE,OAAO,KAAK,EAAyB,mBAAmB,EAAE,MAAM,wBAAwB,CAAC;AACzF,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAC5D,MAAM,MAAM,iBAAiB,GAAG,cAAc,CAAC,mBAAmB,CAAC,CAAC;AAEpE,wEAAwE;AACxE,MAAM,MAAM,SAAS,GAAG,YAAY,CAAC;AAErC,MAAM,WAAW,UAAU;IACzB,0EAA0E;IAC1E,MAAM,EAAE,iBAAiB,CAAC;IAC1B,wEAAwE;IACxE,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,UAAU;IACzB,8EAA8E;IAC9E,gBAAgB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACnD;;;;OAIG;IACH,gBAAgB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC;CAC5D;AAmED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,UAAU,GAAG,UAAU,CAqKhE"}

package/dist/ads/adapter.js

@@ -0,0 +1,219 @@
+import { SdkError } from "../index.js";
+import { runEventFlow } from "../event-flow.js";
+const DEFAULT_SHOW_TIMEOUT_MS = 60_000;
+const DEFAULT_LOAD_TIMEOUT_MS = 30_000;
+function createAdDeadline(timeoutMs, now = monotonicNow) {
+    if (!(timeoutMs > 0)) {
+        return { remainingMs: () => undefined, race: (promise) => promise };
+    }
+    const startedAt = now();
+    return {
+        remainingMs: () => timeoutMs - (now() - startedAt),
+        race: (promise) => new Promise((resolve, reject) => {
+            const timer = setTimeout(() => resolve(undefined), timeoutMs);
+            // Attaching handlers also sinks a settlement that happens after the
+            // deadline already won; the no-op reject/resolve after settling is
+            // ignored by promise semantics.
+            promise.then((value) => {
+                clearTimeout(timer);
+                resolve(value);
+            }, (error) => {
+                clearTimeout(timer);
+                reject(error);
+            });
+        })
+    };
+}
+/**
+ * Monotonic elapsed time: a system wall-clock correction while the loader
+ * is pending must not shrink or stretch the remaining budget.
+ */
+function monotonicNow() {
+    return typeof performance !== "undefined" && typeof performance.now === "function"
+        ? performance.now()
+        : Date.now();
+}
+/**
+ * Shared full-screen ad adapter. Load state is
+ * tracked per ad type + ad unit, in-flight duplicate loads share one
+ * request, and rewards come only from the provider's `userEarnedReward`
+ * event. The adapter produces ad outcomes; server-side reward requests,
+ * session checks, and ledger handling belong to the consumer.
+ */
+export function createAdsAdapter(options) {
+    const loader = options.loader;
+    const showTimeoutMs = options.showTimeoutMs ?? DEFAULT_SHOW_TIMEOUT_MS;
+    const loadTimeoutMs = options.loadTimeoutMs ?? DEFAULT_LOAD_TIMEOUT_MS;
+    const slots = new Map();
+    const showing = new Set();
+    const adKey = (adType, adGroupId) => `${adType}:${adGroupId}`;
+    const load = (adGroupId) => {
+        const id = adKey("fullscreen", adGroupId);
+        const existing = slots.get(id);
+        // Duplicate loads join the in-flight request, and an already-completed
+        // load stays loaded until a show claims it - neither re-registers.
+        if (existing) {
+            return existing.kind === "loaded" ? Promise.resolve() : existing.promise;
+        }
+        // Slot updates run inside this promise's settlement — before the
+        // caller's await/catch continuation — so a caller that immediately
+        // retries after a failure starts a fresh registration, and a caller
+        // that immediately shows after a success finds the slot loaded. The
+        // identity check keeps a stale task from touching a newer task's slot.
+        const promise = new Promise((resolve, reject) => {
+            runLoad(adGroupId).then(() => {
+                const current = slots.get(id);
+                if (current?.kind === "loading" && current.promise === promise) {
+                    slots.set(id, { kind: "loaded" });
+                }
+                resolve();
+            }, (error) => {
+                const current = slots.get(id);
+                if (current?.kind === "loading" && current.promise === promise) {
+                    slots.delete(id);
+                }
+                reject(error);
+            });
+        });
+        slots.set(id, { kind: "loading", promise });
+        return promise;
+    };
+    const show = (adGroupId) => {
+        const id = adKey("fullscreen", adGroupId);
+        if (showing.has(id)) {
+            return Promise.reject(new SdkError("AD_ALREADY_SHOWING", `ad group ${adGroupId} is already being shown`));
+        }
+        const slot = slots.get(id);
+        if (!slot || slot.kind === "loading") {
+            return Promise.reject(new SdkError("AD_NOT_LOADED", `loadFullScreenAd must complete before showing ad group ${adGroupId}`));
+        }
+        // Claim synchronously: the loaded marker is consumed the moment the show
+        // starts, so a concurrent reload registers fresh instead of aliasing a
+        // marker this show will never own again.
+        slots.delete(id);
+        showing.add(id);
+        return (async () => {
+            const timedOut = () => ({ status: "failed", reason: "ad show flow timed out" });
+            try {
+                // The whole show shares one budget: the loader races it, the event
+                // flow gets what remains, and the flow's own deadline produces the
+                // timeout result — its subscription cleanup completes before this
+                // promise settles, so `showing` is only released after the
+                // subscription is gone.
+                const deadline = createAdDeadline(showTimeoutMs);
+                const framework = await deadline.race(loadFramework());
+                if (!framework) {
+                    return timedOut();
+                }
+                if (typeof framework.showFullScreenAd.isSupported === "function" &&
+                    !framework.showFullScreenAd.isSupported()) {
+                    throw new SdkError("UNSUPPORTED", "full-screen ads are not supported on this app version");
+                }
+                const remaining = deadline.remainingMs();
+                if (remaining !== undefined && remaining <= 0) {
+                    return timedOut();
+                }
+                let reward;
+                return await runEventFlow({
+                    register: (emit) => framework.showFullScreenAd({
+                        options: { adGroupId },
+                        onEvent: emit,
+                        onError: (error) => emit({ type: "sdkError", error })
+                    }),
+                    reduce: (event) => {
+                        if (event.type === "sdkError") {
+                            const message = errorMessage(event.error);
+                            return {
+                                done: true,
+                                result: { status: "failed", reason: `full-screen ad show failed: ${message}` }
+                            };
+                        }
+                        return reduceShowEvent(event, () => reward, (value) => (reward = value));
+                    },
+                    onTimeout: timedOut,
+                    timeoutMs: remaining ?? 0
+                });
+            }
+            finally {
+                showing.delete(id);
+            }
+        })();
+    };
+    async function runLoad(adGroupId) {
+        // One deadline covers framework acquisition AND the provider flow. A
+        // loader that wins the race only just — or too late — leaves no budget
+        // for the provider registration, which is then skipped entirely.
+        const deadline = createAdDeadline(loadTimeoutMs);
+        const framework = await deadline.race(loadFramework());
+        if (!framework) {
+            throw new SdkError("AD_LOAD_TIMEOUT", "full-screen ad load timed out");
+        }
+        if (typeof framework.loadFullScreenAd.isSupported === "function" &&
+            !framework.loadFullScreenAd.isSupported()) {
+            throw new SdkError("UNSUPPORTED", "full-screen ads are not supported on this app version");
+        }
+        const remaining = deadline.remainingMs();
+        if (remaining !== undefined && remaining <= 0) {
+            throw new SdkError("AD_LOAD_TIMEOUT", "full-screen ad load timed out");
+        }
+        const outcome = await runEventFlow({
+            register: (emit) => framework.loadFullScreenAd({
+                options: { adGroupId },
+                onEvent: emit,
+                onError: (error) => emit({ type: "sdkError", error })
+            }),
+            reduce: (event) => event.type === "loaded"
+                ? { done: true, result: undefined }
+                : { done: true, result: loadFailure(event.error) },
+            onTimeout: () => new SdkError("AD_LOAD_TIMEOUT", "full-screen ad load timed out"),
+            timeoutMs: remaining ?? 0
+        });
+        if (outcome instanceof SdkError) {
+            throw outcome;
+        }
+    }
+    async function loadFramework() {
+        const result = await loader();
+        if (!result.available) {
+            throw new SdkError("SDK_UNAVAILABLE", result.reason);
+        }
+        return result.module;
+    }
+    return { loadFullScreenAd: load, showFullScreenAd: show };
+}
+function reduceShowEvent(event, getReward, setReward) {
+    switch (event.type) {
+        case "userEarnedReward": {
+            // Runtime guard against payload-shape drift; the typed contract marks
+            // data as required.
+            if (event.data) {
+                setReward({ unitType: event.data.unitType, unitAmount: event.data.unitAmount });
+            }
+            return { done: false };
+        }
+        case "dismissed": {
+            const earned = getReward();
+            // Reward only when the provider actually emitted userEarnedReward;
+            // dismissal alone never grants anything.
+            return earned
+                ? { done: true, result: { status: "rewarded", reward: earned } }
+                : { done: true, result: { status: "dismissed" } };
+        }
+        case "failedToShow":
+            return { done: true, result: { status: "failed", reason: "failedToShow" } };
+        default:
+            // requested / show / impression / clicked keep the flow running.
+            return { done: false };
+    }
+}
+/** Transient provider failures are retryable and must not read as UNSUPPORTED. */
+function loadFailure(error) {
+    if (error instanceof SdkError)
+        return error;
+    return new SdkError("AD_LOAD_FAILED", `full-screen ad load failed: ${errorMessage(error)}`, {
+        cause: error
+    });
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/dist/ads/platform-contract.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Structural contract for the official React Native and WebView full-screen Ads APIs,
+ * declared from the published documentation so this package type-checks and
+ * ships without requiring the official SDK to be installed. The runtime
+ * module stays an optional peer dependency.
+ */
+export interface LoadFullScreenAdParams {
+    options: {
+        adGroupId: string;
+    };
+    onEvent: (event: {
+        type: "loaded";
+    }) => void;
+    onError: (error: unknown) => void;
+}
+/** Discriminated union per the provider contract: only userEarnedReward carries data. */
+export type FullScreenAdShowEvent = {
+    type: "requested" | "show" | "impression" | "clicked" | "dismissed" | "failedToShow";
+} | {
+    type: "userEarnedReward";
+    data: {
+        unitType: string;
+        unitAmount: number;
+    };
+};
+export interface ShowFullScreenAdParams {
+    options: {
+        adGroupId: string;
+    };
+    onEvent: (event: FullScreenAdShowEvent) => void;
+    onError: (error: unknown) => void;
+}
+export interface FullScreenAdFunctions {
+    loadFullScreenAd(params: LoadFullScreenAdParams): () => void;
+    showFullScreenAd(params: ShowFullScreenAdParams): () => void;
+}
+export interface FullScreenAdSupport {
+    loadFullScreenAd: FullScreenAdFunctions["loadFullScreenAd"] & {
+        isSupported?: () => boolean;
+    };
+    showFullScreenAd: FullScreenAdFunctions["showFullScreenAd"] & {
+        isSupported?: () => boolean;
+    };
+}
+//# sourceMappingURL=platform-contract.d.ts.map

package/dist/ads/platform-contract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"platform-contract.d.ts","sourceRoot":"","sources":["../../src/ads/platform-contract.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,MAAM,WAAW,sBAAsB;IACrC,OAAO,EAAE;QAAE,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC;IAC/B,OAAO,EAAE,CAAC,KAAK,EAAE;QAAE,IAAI,EAAE,QAAQ,CAAA;KAAE,KAAK,IAAI,CAAC;IAC7C,OAAO,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;CACnC;AAED,yFAAyF;AACzF,MAAM,MAAM,qBAAqB,GAC7B;IAAE,IAAI,EAAE,WAAW,GAAG,MAAM,GAAG,YAAY,GAAG,SAAS,GAAG,WAAW,GAAG,cAAc,CAAA;CAAE,GACxF;IAAE,IAAI,EAAE,kBAAkB,CAAC;IAAC,IAAI,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE,CAAA;CAAE,CAAC;AAEjF,MAAM,WAAW,sBAAsB;IACrC,OAAO,EAAE;QAAE,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC;IAC/B,OAAO,EAAE,CAAC,KAAK,EAAE,qBAAqB,KAAK,IAAI,CAAC;IAChD,OAAO,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;CACnC;AAED,MAAM,WAAW,qBAAqB;IACpC,gBAAgB,CAAC,MAAM,EAAE,sBAAsB,GAAG,MAAM,IAAI,CAAC;IAC7D,gBAAgB,CAAC,MAAM,EAAE,sBAAsB,GAAG,MAAM,IAAI,CAAC;CAC9D;AAED,MAAM,WAAW,mBAAmB;IAClC,gBAAgB,EAAE,qBAAqB,CAAC,kBAAkB,CAAC,GAAG;QAC5D,WAAW,CAAC,EAAE,MAAM,OAAO,CAAC;KAC7B,CAAC;IACF,gBAAgB,EAAE,qBAAqB,CAAC,kBAAkB,CAAC,GAAG;QAC5D,WAAW,CAAC,EAAE,MAAM,OAAO,CAAC;KAC7B,CAAC;CACH"}

package/dist/ads/platform-contract.js

@@ -0,0 +1,7 @@
+/**
+ * Structural contract for the official React Native and WebView full-screen Ads APIs,
+ * declared from the published documentation so this package type-checks and
+ * ships without requiring the official SDK to be installed. The runtime
+ * module stays an optional peer dependency.
+ */
+export {};

package/dist/iap/adapter.d.ts

@@ -1,7 +1,9 @@
-import { type IapGrantCallback, type IapProduct } from "../index.js";
+import { type IapGrantCallback, type IapProduct, type IapSubscriptionInfo, type IapOrderHistoryPage } from "../index.js";
 import type { IapPendingOrder, IapPurchaseResult } from "../index.js";
 import { type IapPlatformLoader } from "./platform-contract.js";
 export interface IapAdapterOptions {
+    /** Provider paging capability, fixed by the runtime factory. */
+    orderHistoryPagination: "cursor" | "first_page_only";
     grant: IapGrantCallback;
     /** Loader for the platform SDK module (already normalized per entry point). */
     loader: IapPlatformLoader;
@@ -14,6 +16,14 @@ export interface IapRecoveryResult {
     reason?: string;
 }
 export interface IapAdapter {
+    /** Read-only history; WebView rejects non-null cursors rather than repeating page one. */
+    getCompletedOrRefundedOrders(params?: {
+        key?: string | null;
+    }): Promise<IapOrderHistoryPage>;
+    /** Read-only provider snapshot; never grants or revokes entitlements. */
+    getSubscriptionInfo(orderId: string): Promise<{
+        subscription: IapSubscriptionInfo;
+    }>;
     /** Lists purchasable products (one-time and subscription together). */
     getProductItemList(): Promise<{
         products: IapProduct[];

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

@@ -1 +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"}
+{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../../src/iap/adapter.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,gBAAgB,EAErB,KAAK,UAAU,EACf,KAAK,mBAAmB,EACxB,KAAK,mBAAmB,EAEzB,MAAM,aAAa,CAAC;AACrB,OAAO,KAAK,EACV,eAAe,EACf,iBAAiB,EAClB,MAAM,aAAa,CAAC;AAErB,OAAO,EAAE,KAAK,iBAAiB,EAA8B,MAAM,wBAAwB,CAAC;AAK5F,MAAM,WAAW,iBAAiB;IAChC,gEAAgE;IAChE,sBAAsB,EAAE,QAAQ,GAAG,iBAAiB,CAAC;IACrD,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,0FAA0F;IAC1F,4BAA4B,CAAC,MAAM,CAAC,EAAE;QAAE,GAAG,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAAC;IAC7F,yEAAyE;IACzE,mBAAmB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,YAAY,EAAE,mBAAmB,CAAA;KAAE,CAAC,CAAC;IACrF,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,CAuKvE"}