@ait-kit/sdk 0.2.0

package/dist/index.d.ts

@@ -0,0 +1,215 @@
+/**
+ * `@ait-kit/sdk` — shared frontend contracts for Apps in Toss mini apps.
+ *
+ * The root entry is runtime-neutral: common types and errors only, with no
+ * imports of any official runtime SDK. Runtime adapters live in subpaths —
+ * `@ait-kit/sdk/rn` for React Native (ads today; more domains later).
+ */
+/** Reward payload reported by rewarded ad flows. */
+export interface AdReward {
+    unitType: string;
+    unitAmount: number;
+}
+/**
+ * Terminal outcome of showing a full-screen ad.
+ *
+ * `rewarded` is only ever produced from the provider's actual reward event —
+ * loading, showing, or dismissing an ad never implies a reward. Server-side
+ * reward verification, session checks, and ledger updates stay with the
+ * consumer.
+ */
+export type AdShowResult = {
+    status: "rewarded";
+    reward: AdReward;
+} | {
+    status: "dismissed";
+} | {
+    status: "failed";
+    reason?: string;
+};
+/** Stable error codes for SDK adapter failures. */
+export type SdkErrorCode = "SDK_UNAVAILABLE" | "UNSUPPORTED" | "AD_NOT_LOADED" | "AD_ALREADY_SHOWING" | "AD_LOAD_FAILED" | "AD_LOAD_TIMEOUT" | "INVALID_LOGIN_RESULT" | "INVALID_ANONYMOUS_KEY" | "INVALID_SHARE_PATH";
+/** Terminal agreement outcomes delivered by the platform event. */
+export type SdkNotificationAgreementType = "newAgreement" | "alreadyAgreed" | "agreementRejected";
+/**
+ * Result of one notification agreement request. `templateCode` and the
+ * platform's raw event are preserved verbatim, and the outcome describes
+ * ONLY this single request — it is not the user's global notification
+ * setting, nor any server-persisted consent state (syncing those is the
+ * consumer's job).
+ */
+export type SdkNotificationAgreementResult = {
+    status: "agreed";
+    agreement: Exclude<SdkNotificationAgreementType, "agreementRejected">;
+    templateCode: string;
+    sourceEvent: {
+        type: string;
+    };
+} | {
+    status: "rejected";
+    templateCode: string;
+    sourceEvent: {
+        type: string;
+    };
+} | {
+    status: "failed";
+    templateCode: string;
+    code?: string;
+    reason?: string;
+} | {
+    status: "timeout";
+    templateCode: string;
+    reason?: string;
+};
+/**
+ * Result of opening the share UI. `closed` means the native share sheet
+ * flow ended normally — it does NOT prove the user actually shared, and it
+ * never grants share-reward eligibility on its own.
+ */
+export type SdkShareUiResult = {
+    status: "closed";
+} | {
+    status: "failed";
+    code?: string;
+    reason?: string;
+};
+export type SdkLoginReferrer = "DEFAULT" | "SANDBOX";
+/**
+ * Validated login result. Both values come from the platform SDK and pass
+ * through unchanged: exchange `authorizationCode` for tokens on YOUR server
+ * (see @ait-kit/api-core's login token endpoint) and create the application
+ * session there — the SDK adapter never performs the exchange.
+ */
+export interface SdkLoginResult {
+    authorizationCode: string;
+    referrer: SdkLoginReferrer;
+}
+/**
+ * Validated anonymous identity: the SDK-issued per-mini-app hash. The
+ * adapter never fabricates a key when the SDK cannot provide one — a
+ * missing or malformed result is an error, not a placeholder.
+ */
+export interface SdkAnonymousKey {
+    type: "HASH";
+    hash: string;
+}
+/** Minimal storage contract shared by the /rn and /web adapters. */
+export interface SdkStorage {
+    /** Resolves the stored string, or null when the key has no value. */
+    get(key: string): Promise<string | null>;
+    /** Persists a string; rejections propagate to the caller. */
+    set(key: string, value: string): Promise<void>;
+    /** Removes the value for a key; rejections propagate to the caller. */
+    remove(key: string): Promise<void>;
+}
+export type IapProductType = "CONSUMABLE" | "NON_CONSUMABLE" | "SUBSCRIPTION";
+export type IapSubscriptionRenewalCycle = "WEEKLY" | "MONTHLY" | "YEARLY";
+export interface IapSubscriptionOffer {
+    type: "FREE_TRIAL" | "NEW_SUBSCRIPTION" | "RETURNING";
+    offerId: string;
+    period: string;
+    displayAmount?: string;
+}
+export interface IapProduct {
+    sku: string;
+    type: IapProductType;
+    displayName: string;
+    displayAmount: string;
+    iconUrl: string;
+    description: string;
+    /** Subscription products only. */
+    renewalCycle?: IapSubscriptionRenewalCycle;
+    offers?: IapSubscriptionOffer[];
+}
+export interface IapPendingOrder {
+    orderId: string;
+    sku: string;
+    paymentCompletedDate: string;
+}
+/** Success payload delivered by the platform's purchase success event. */
+export interface IapPurchaseSuccessInfo {
+    orderId: string;
+    displayName: string;
+    displayAmount: string;
+    amount: number;
+    currency: string;
+    fraction: number;
+    miniAppIconUrl: string | null;
+}
+/**
+ * Consumer-injected server grant callback.
+ *
+ * Contract: resolve only AFTER your server has verified the order with the
+ * provider and persisted the grant. Resolving on the SDK event alone (or
+ * before persistence) breaks the purchase contract; rejecting or throwing
+ * marks the grant as failed and the purchase never reports completion.
+ * Server-side verification is the consumer's responsibility — SDK events
+ * are not payment verification.
+ */
+export type IapGrantCallback = (target: {
+    orderId: string;
+    sku: string;
+    subscriptionId?: string;
+}) => Promise<void>;
+/**
+ * Terminal outcome of a purchase flow. `completed` requires BOTH the
+ * platform's success event for the order AND your grant callback having
+ * resolved for that exact order — a grant for a different order never
+ * completes a purchase, and a success event alone never completes one.
+ */
+export type IapPurchaseResult = {
+    status: "completed";
+    orderId: string;
+    subscriptionId?: string;
+    success: IapPurchaseSuccessInfo;
+} | {
+    status: "canceled";
+} | {
+    status: "failed";
+    code?: string;
+    reason?: string;
+} | {
+    status: "grant_failed";
+    orderId: string;
+    reason?: string;
+} | {
+    status: "unknown";
+    orderId?: string;
+    subscriptionId?: string;
+    reason?: string;
+};
+export interface IapGrantOrderParams {
+    orderId: string;
+    subscriptionId?: string;
+}
+export interface IapOneTimePurchaseParams {
+    options: {
+        sku: string;
+        processProductGrant: (params: IapGrantOrderParams) => boolean | Promise<boolean>;
+    };
+    onEvent: (event: {
+        type: "success";
+        data: IapPurchaseSuccessInfo;
+    }) => void | Promise<void>;
+    onError: (error: unknown) => void | Promise<void>;
+}
+export interface IapSubscriptionPurchaseParams {
+    options: {
+        sku: string;
+        offerId?: string | null;
+        processProductGrant: (params: IapGrantOrderParams) => boolean | Promise<boolean>;
+    };
+    onEvent: (event: {
+        type: "success";
+        data: IapPurchaseSuccessInfo;
+    }) => void | Promise<void>;
+    onError: (error: unknown) => void | Promise<void>;
+}
+/** Typed error surfaced by the SDK adapters. */
+export declare class SdkError extends Error {
+    code: SdkErrorCode;
+    constructor(code: SdkErrorCode, message: string, options?: {
+        cause?: unknown;
+    });
+}
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -0,0 +1,16 @@
+/**
+ * `@ait-kit/sdk` — shared frontend contracts for Apps in Toss mini apps.
+ *
+ * The root entry is runtime-neutral: common types and errors only, with no
+ * imports of any official runtime SDK. Runtime adapters live in subpaths —
+ * `@ait-kit/sdk/rn` for React Native (ads today; more domains later).
+ */
+/** Typed error surfaced by the SDK adapters. */
+export class SdkError extends Error {
+    code;
+    constructor(code, message, options) {
+        super(message, options);
+        this.name = "SdkError";
+        this.code = code;
+    }
+}

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

@@ -0,0 +1,43 @@
+import type { SdkNotificationAgreementResult } from "../index.js";
+/**
+ * Internal platform contract for the notification-agreement adapter,
+ * shared by /rn and /web (never exported from a public subpath).
+ */
+export interface NotificationAgreementParams {
+    options: {
+        templateCode: string;
+    };
+    onEvent: (result: {
+        type: string;
+    }) => void | Promise<void>;
+    onError: (error: unknown) => void | Promise<void>;
+}
+type FunctionWithSupport<F> = F & {
+    isSupported?: () => boolean;
+};
+export interface NotificationLike {
+    requestAgreement: FunctionWithSupport<(params: NotificationAgreementParams) => () => void> | undefined;
+}
+export interface NotificationPlatformSdk {
+    Notification?: NotificationLike;
+}
+export type NotificationPlatformLoader = () => Promise<{
+    available: true;
+    module: NotificationPlatformSdk;
+} | {
+    available: false;
+    reason: string;
+}>;
+/**
+ * Runs one agreement request on the shared event-flow base: settle-once,
+ * duplicate/late-event immunity, cleanup exactly once with exceptions
+ * swallowed away from the result, registration-throw recovery, and one
+ * overall deadline. The templateCode and the platform's raw event are
+ * preserved verbatim in every outcome; the result describes only this
+ * request, never a global notification setting or server consent state.
+ */
+export declare function runRequestAgreement(platform: NotificationPlatformSdk, templateCode: string, timeoutMs: number): Promise<SdkNotificationAgreementResult>;
+export declare function readErrorCode(error: unknown): string | undefined;
+export declare function readErrorMessage(error: unknown): string;
+export {};
+//# sourceMappingURL=platform-contract.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"platform-contract.d.ts","sourceRoot":"","sources":["../../src/notification/platform-contract.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,8BAA8B,EAAE,MAAM,aAAa,CAAC;AAElE;;;GAGG;AAEH,MAAM,WAAW,2BAA2B;IAC1C,OAAO,EAAE;QAAE,YAAY,EAAE,MAAM,CAAA;KAAE,CAAC;IAClC,OAAO,EAAE,CAAC,MAAM,EAAE;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5D,OAAO,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACnD;AAED,KAAK,mBAAmB,CAAC,CAAC,IAAI,CAAC,GAAG;IAAE,WAAW,CAAC,EAAE,MAAM,OAAO,CAAA;CAAE,CAAC;AAElE,MAAM,WAAW,gBAAgB;IAC/B,gBAAgB,EACZ,mBAAmB,CAAC,CAAC,MAAM,EAAE,2BAA2B,KAAK,MAAM,IAAI,CAAC,GACxE,SAAS,CAAC;CACf;AAED,MAAM,WAAW,uBAAuB;IACtC,YAAY,CAAC,EAAE,gBAAgB,CAAC;CACjC;AAED,MAAM,MAAM,0BAA0B,GAAG,MAAM,OAAO,CACpD;IAAE,SAAS,EAAE,IAAI,CAAC;IAAC,MAAM,EAAE,uBAAuB,CAAA;CAAE,GAAG;IAAE,SAAS,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAC5F,CAAC;AAQF;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CACjC,QAAQ,EAAE,uBAAuB,EACjC,YAAY,EAAE,MAAM,EACpB,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,8BAA8B,CAAC,CA6DzC;AAED,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAMhE;AAED,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAOvD"}

package/dist/notification/platform-contract.js

@@ -0,0 +1,89 @@
+import { runEventFlow } from "../event-flow.js";
+const TERMINAL_AGREEMENTS = new Set(["newAgreement", "alreadyAgreed", "agreementRejected"]);
+/**
+ * Runs one agreement request on the shared event-flow base: settle-once,
+ * duplicate/late-event immunity, cleanup exactly once with exceptions
+ * swallowed away from the result, registration-throw recovery, and one
+ * overall deadline. The templateCode and the platform's raw event are
+ * preserved verbatim in every outcome; the result describes only this
+ * request, never a global notification setting or server consent state.
+ */
+export function runRequestAgreement(platform, templateCode, timeoutMs) {
+    return runEventFlow({
+        timeoutMs,
+        onTimeout: () => ({
+            status: "timeout",
+            templateCode,
+            reason: `agreement request timed out after ${timeoutMs}ms; the user may still act — resolve the state server-side before retrying`
+        }),
+        register: (emit) => platform.Notification.requestAgreement({
+            options: { templateCode },
+            onEvent: (result) => {
+                // Preserve the platform's raw event object verbatim (including
+                // any metadata beyond `type`) per the public contract.
+                emit({
+                    kind: "agreement",
+                    type: result.type,
+                    sourceEvent: result
+                });
+            },
+            onError: (error) => {
+                emit({ kind: "sdkError", error });
+            }
+        }),
+        reduce: (event) => {
+            switch (event.kind) {
+                case "agreement": {
+                    if (!TERMINAL_AGREEMENTS.has(event.type)) {
+                        return { done: false };
+                    }
+                    if (event.type === "agreementRejected") {
+                        return {
+                            done: true,
+                            result: { status: "rejected", templateCode, sourceEvent: event.sourceEvent }
+                        };
+                    }
+                    return {
+                        done: true,
+                        result: {
+                            status: "agreed",
+                            agreement: event.type,
+                            templateCode,
+                            sourceEvent: event.sourceEvent
+                        }
+                    };
+                }
+                case "sdkError": {
+                    const code = readErrorCode(event.error);
+                    return {
+                        done: true,
+                        result: {
+                            status: "failed",
+                            templateCode,
+                            ...(code !== undefined ? { code } : {}),
+                            reason: readErrorMessage(event.error)
+                        }
+                    };
+                }
+            }
+        }
+    });
+}
+export function readErrorCode(error) {
+    if (typeof error === "object" && error !== null) {
+        const code = error.code;
+        if (typeof code === "string" && code)
+            return code;
+    }
+    return undefined;
+}
+export function readErrorMessage(error) {
+    if (error instanceof Error)
+        return error.message;
+    if (typeof error === "object" && error !== null) {
+        const message = error.message;
+        if (typeof message === "string" && message)
+            return message;
+    }
+    return String(error);
+}

package/dist/rn/ads.d.ts

@@ -0,0 +1,39 @@
+import { type AdShowResult } from "../index.js";
+import type { FullScreenAdSupport } from "./framework-contract.js";
+import { type FrameworkLoader } from "./framework-loader.js";
+/** Ad kinds the SDK distinguishes; only full-screen ads exist today. */
+export type SdkAdType = "fullscreen";
+export interface ReactNativeAdsOptions {
+    /**
+     * Framework loader. Defaults to a lazy `import("@apps-in-toss/framework")`
+     * that retries after failures; tests and consumers can inject a loader or
+     * a module instance directly.
+     */
+    framework?: FrameworkLoader | FullScreenAdSupport;
+    /** 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 ReactNativeAds {
+    /** 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>;
+}
+/**
+ * React Native ad adapter over `@apps-in-toss/framework`. 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 createReactNativeAds(options?: ReactNativeAdsOptions): ReactNativeAds;
+//# sourceMappingURL=ads.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ads.d.ts","sourceRoot":"","sources":["../../src/rn/ads.ts"],"names":[],"mappings":"AAGA,OAAO,EAA2B,KAAK,YAAY,EAAE,MAAM,aAAa,CAAC;AAEzE,OAAO,KAAK,EAAyB,mBAAmB,EAAE,MAAM,yBAAyB,CAAC;AAC1F,OAAO,EAEL,KAAK,eAAe,EACrB,MAAM,uBAAuB,CAAC;AAE/B,wEAAwE;AACxE,MAAM,MAAM,SAAS,GAAG,YAAY,CAAC;AAErC,MAAM,WAAW,qBAAqB;IACpC;;;;OAIG;IACH,SAAS,CAAC,EAAE,eAAe,GAAG,mBAAmB,CAAC;IAClD,wEAAwE;IACxE,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,cAAc;IAC7B,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;AAWD;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,GAAE,qBAA0B,GAAG,cAAc,CAuLxF"}

package/dist/rn/ads.js

@@ -0,0 +1,226 @@
+// Relative import: the package ships per-file output (no bundling), so
+// the /rn entry and the root entry share one SdkError constructor and
+// `instanceof` holds for consumers importing either entry.
+import { SdkError } from "../index.js";
+import { runEventFlow } from "../event-flow.js";
+import { createDefaultFrameworkLoader } from "./framework-loader.js";
+const DEFAULT_SHOW_TIMEOUT_MS = 60_000;
+const DEFAULT_LOAD_TIMEOUT_MS = 30_000;
+/**
+ * React Native ad adapter over `@apps-in-toss/framework`. 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 createReactNativeAds(options = {}) {
+    const loader = normalizeLoader(options.framework);
+    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;
+        }
+        const request = (async () => {
+            // The deadline covers framework acquisition as well as the provider
+            // load flow, and a timed-out task must not register with the provider
+            // afterwards: a retried load would otherwise race a late registration.
+            let cancelled = false;
+            const task = (async () => {
+                const framework = await loadFramework();
+                if (cancelled) {
+                    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 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: loadTimeoutMs
+                });
+                if (outcome instanceof SdkError) {
+                    throw outcome;
+                }
+            })();
+            // If the deadline wins, the orphaned task rejects into this sink.
+            task.catch(() => { });
+            let timer;
+            const deadline = new Promise((_, reject) => {
+                if (loadTimeoutMs > 0) {
+                    timer = setTimeout(() => {
+                        cancelled = true;
+                        reject(new SdkError("AD_LOAD_TIMEOUT", "full-screen ad load timed out"));
+                    }, loadTimeoutMs);
+                }
+            });
+            try {
+                return await Promise.race([task, deadline]);
+            }
+            finally {
+                if (timer !== undefined)
+                    clearTimeout(timer);
+            }
+        })();
+        slots.set(id, { kind: "loading", promise: request });
+        request
+            .then(() => {
+            // Promote only when this exact request still owns the slot: a
+            // timed-out task resolving late must not mark a newer retry loaded.
+            const current = slots.get(id);
+            if (current?.kind === "loading" && current.promise === request) {
+                slots.set(id, { kind: "loaded" });
+            }
+        })
+            .catch(() => {
+            // A failed load frees the slot so the next attempt retries.
+            const current = slots.get(id);
+            if (current?.kind === "loading" && current.promise === request) {
+                slots.delete(id);
+            }
+        });
+        return request;
+    };
+    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 () => {
+            // The deadline covers framework acquisition as well as the show flow:
+            // a stalled loader must release the showing slot instead of wedging
+            // the ad group forever, and a late-resolving loader must not register
+            // a show the deadline already ended.
+            let reward;
+            let cancelled = false;
+            const timedOut = () => ({ status: "failed", reason: "ad show flow timed out" });
+            try {
+                let timer;
+                const deadline = new Promise((resolve) => {
+                    if (showTimeoutMs > 0) {
+                        timer = setTimeout(() => {
+                            cancelled = true;
+                            resolve(timedOut());
+                        }, showTimeoutMs);
+                    }
+                });
+                const task = (async () => {
+                    const framework = await loadFramework();
+                    if (cancelled) {
+                        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");
+                    }
+                    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: showTimeoutMs
+                    });
+                })();
+                try {
+                    return await Promise.race([task, deadline]);
+                }
+                finally {
+                    if (timer !== undefined)
+                        clearTimeout(timer);
+                }
+            }
+            finally {
+                showing.delete(id);
+            }
+        })();
+    };
+    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);
+}
+function normalizeLoader(framework) {
+    if (!framework) {
+        return createDefaultFrameworkLoader();
+    }
+    if (typeof framework === "function") {
+        return framework;
+    }
+    return async () => ({ available: true, module: framework });
+}