@nosslabs/iap 0.3.0

package/dist/index.d.ts

@@ -0,0 +1,1134 @@
+import { z } from 'zod';
+
+type LogLevel = 'silent' | 'error' | 'warn' | 'info' | 'debug';
+interface Logger {
+    error(message: string, ...args: unknown[]): void;
+    warn(message: string, ...args: unknown[]): void;
+    info(message: string, ...args: unknown[]): void;
+    debug(message: string, ...args: unknown[]): void;
+}
+
+interface HttpRequest {
+    method: 'GET' | 'POST';
+    /**
+     * Path appended to baseUrl. Leading slash is optional — both `'/foo'` and
+     * `'foo'` are normalized at request time, and any trailing slash on `baseUrl`
+     * is stripped, so all four corner cases produce the same joined URL.
+     */
+    path: string;
+    /** JSON-serializable body (for POST). */
+    body?: unknown;
+    /** Extra headers, merged on top of auth headers + Content-Type. */
+    headers?: Record<string, string>;
+}
+interface HttpClientOptions {
+    baseUrl: string;
+    /** Called before every request. Returns headers to merge in (e.g. `{ Authorization: 'Bearer ...' }`). */
+    getAuthHeaders: () => Record<string, string> | Promise<Record<string, string>>;
+    /** Per-attempt timeout in ms. */
+    timeoutMs: number;
+    /** Number of retry attempts on transient errors (5xx, 408, 429, network). */
+    retries: number;
+    /** Optional pre-send transform. Lets consumer rewrite path/body/headers. */
+    requestTransform?: (req: HttpRequest) => HttpRequest | Promise<HttpRequest>;
+    /** Optional response transform. Runs on the parsed JSON before validation. */
+    responseTransform?: (raw: unknown) => unknown | Promise<unknown>;
+    /** Override `globalThis.fetch` for tests. */
+    fetch?: typeof fetch;
+    logger: Logger;
+}
+/**
+ * Generic HTTP client for the consumer backend.
+ *
+ * - **Timeout**: per-attempt via `AbortController` (native fetch has no timeout option).
+ * - **Retry policy**: 5xx, 408, 429, and network errors retry with exponential backoff.
+ *   Other 4xx fail immediately (caller's responsibility to fix).
+ * - **Auth + transforms**: `getAuthHeaders()` runs once per request; `requestTransform`
+ *   and `responseTransform` are escape hatches for consumers whose backend uses a
+ *   different shape than the library's default.
+ * - **Logging**: requests are logged at debug level with sensitive headers redacted
+ *   via `redactHeaders()` (PLAN.md §13 — never log raw bearer tokens).
+ *
+ * Consumers don't construct this directly — `HttpBackendAdapter` wraps it.
+ */
+declare class HttpClient {
+    private readonly opts;
+    private readonly fetchImpl;
+    constructor(opts: HttpClientOptions);
+    /**
+     * Execute the request and parse the response with the given zod schema.
+     * Returns the validated, transformed result.
+     */
+    request<T>(req: HttpRequest, schema: z.ZodType<T>): Promise<T>;
+    private singleAttempt;
+    private fetchWithTimeout;
+}
+
+declare const backendConfigSchema: z.ZodEffects<z.ZodObject<{
+    /**
+     * Custom backend transport. If provided, all HTTP-specific fields below
+     * are ignored and the library uses this object directly for backend
+     * operations. Must implement `BackendAdapter`.
+     */
+    adapter: z.ZodOptional<z.ZodUnknown>;
+    baseUrl: z.ZodOptional<z.ZodString>;
+    endpoints: z.ZodOptional<z.ZodEffects<z.ZodObject<{
+        /**
+         * Optional. Set when the consumer supports iOS purchases. iOS-less
+         * (e.g. Android-only) configs may omit it; the HTTP adapter will throw
+         * `INVALID_CONFIG` at runtime if `verifyApple()` is invoked without this
+         * endpoint configured. At least one of `verifyApple` or `verifyGoogle`
+         * must be set.
+         */
+        verifyApple: z.ZodOptional<z.ZodString>;
+        /**
+         * Optional. Set when the consumer supports Android purchases.
+         * Android-less (e.g. iOS-only) configs may omit it; the HTTP adapter will
+         * throw `INVALID_CONFIG` at runtime if `verifyGoogle()` is invoked
+         * without this endpoint configured. At least one of `verifyApple` or
+         * `verifyGoogle` must be set.
+         */
+        verifyGoogle: z.ZodOptional<z.ZodString>;
+        entitlements: z.ZodString;
+        restore: z.ZodString;
+        /**
+         * Optional. When set, the library fetches the SKU manifest from this
+         * endpoint during `initialize()` if `products` is omitted from config.
+         * See `docs/guide/backend-contract.md` for the response shape.
+         */
+        products: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        entitlements: string;
+        restore: string;
+        verifyApple?: string | undefined;
+        verifyGoogle?: string | undefined;
+        products?: string | undefined;
+    }, {
+        entitlements: string;
+        restore: string;
+        verifyApple?: string | undefined;
+        verifyGoogle?: string | undefined;
+        products?: string | undefined;
+    }>, {
+        entitlements: string;
+        restore: string;
+        verifyApple?: string | undefined;
+        verifyGoogle?: string | undefined;
+        products?: string | undefined;
+    }, {
+        entitlements: string;
+        restore: string;
+        verifyApple?: string | undefined;
+        verifyGoogle?: string | undefined;
+        products?: string | undefined;
+    }>>;
+    /**
+     * Returns auth headers to merge into every backend request. Called fresh
+     * per request so token refresh works automatically. Type is checked at
+     * runtime via shape guard, not zod (zod can't validate function contracts).
+     */
+    getAuthHeaders: z.ZodOptional<z.ZodUnknown>;
+    /** Pre-send request transform. See {@link BackendConfig} for the typed shape. */
+    requestTransform: z.ZodOptional<z.ZodUnknown>;
+    /** Post-receive response transform. See {@link BackendConfig} for the typed shape. */
+    responseTransform: z.ZodOptional<z.ZodUnknown>;
+    entitlementSchema: z.ZodOptional<z.ZodUnknown>;
+    timeoutMs: z.ZodDefault<z.ZodNumber>;
+    retries: z.ZodDefault<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    timeoutMs: number;
+    retries: number;
+    adapter?: unknown;
+    baseUrl?: string | undefined;
+    endpoints?: {
+        entitlements: string;
+        restore: string;
+        verifyApple?: string | undefined;
+        verifyGoogle?: string | undefined;
+        products?: string | undefined;
+    } | undefined;
+    getAuthHeaders?: unknown;
+    requestTransform?: unknown;
+    responseTransform?: unknown;
+    entitlementSchema?: unknown;
+}, {
+    adapter?: unknown;
+    baseUrl?: string | undefined;
+    endpoints?: {
+        entitlements: string;
+        restore: string;
+        verifyApple?: string | undefined;
+        verifyGoogle?: string | undefined;
+        products?: string | undefined;
+    } | undefined;
+    getAuthHeaders?: unknown;
+    requestTransform?: unknown;
+    responseTransform?: unknown;
+    entitlementSchema?: unknown;
+    timeoutMs?: number | undefined;
+    retries?: number | undefined;
+}>, {
+    timeoutMs: number;
+    retries: number;
+    adapter?: unknown;
+    baseUrl?: string | undefined;
+    endpoints?: {
+        entitlements: string;
+        restore: string;
+        verifyApple?: string | undefined;
+        verifyGoogle?: string | undefined;
+        products?: string | undefined;
+    } | undefined;
+    getAuthHeaders?: unknown;
+    requestTransform?: unknown;
+    responseTransform?: unknown;
+    entitlementSchema?: unknown;
+}, {
+    adapter?: unknown;
+    baseUrl?: string | undefined;
+    endpoints?: {
+        entitlements: string;
+        restore: string;
+        verifyApple?: string | undefined;
+        verifyGoogle?: string | undefined;
+        products?: string | undefined;
+    } | undefined;
+    getAuthHeaders?: unknown;
+    requestTransform?: unknown;
+    responseTransform?: unknown;
+    entitlementSchema?: unknown;
+    timeoutMs?: number | undefined;
+    retries?: number | undefined;
+}>;
+declare const storageConfigSchema: z.ZodObject<{
+    type: z.ZodDefault<z.ZodEnum<["preferences", "memory", "custom"]>>;
+    namespace: z.ZodDefault<z.ZodString>;
+    adapter: z.ZodOptional<z.ZodUnknown>;
+}, "strip", z.ZodTypeAny, {
+    type: "preferences" | "memory" | "custom";
+    namespace: string;
+    adapter?: unknown;
+}, {
+    type?: "preferences" | "memory" | "custom" | undefined;
+    adapter?: unknown;
+    namespace?: string | undefined;
+}>;
+declare const optionsConfigSchema: z.ZodObject<{
+    refreshOnResume: z.ZodDefault<z.ZodBoolean>;
+    entitlementCacheTtlMs: z.ZodDefault<z.ZodNumber>;
+    recoverUnfinishedTransactions: z.ZodDefault<z.ZodBoolean>;
+    /**
+     * Cap on how many unfinished transactions recovery inspects per launch.
+     * Defends against pathological growth if the consumer's backend has been
+     * down for an extended period and the unfinished list keeps growing.
+     * Excess entries stay in storage and are processed on subsequent launches.
+     */
+    recoveryMaxBatch: z.ZodDefault<z.ZodNumber>;
+    productPriceCacheTtlMs: z.ZodDefault<z.ZodNumber>;
+    logLevel: z.ZodDefault<z.ZodEnum<["silent", "error", "warn", "info", "debug"]>>;
+    logger: z.ZodOptional<z.ZodUnknown>;
+}, "strip", z.ZodTypeAny, {
+    refreshOnResume: boolean;
+    entitlementCacheTtlMs: number;
+    recoverUnfinishedTransactions: boolean;
+    recoveryMaxBatch: number;
+    productPriceCacheTtlMs: number;
+    logLevel: "silent" | "error" | "warn" | "info" | "debug";
+    logger?: unknown;
+}, {
+    refreshOnResume?: boolean | undefined;
+    entitlementCacheTtlMs?: number | undefined;
+    recoverUnfinishedTransactions?: boolean | undefined;
+    recoveryMaxBatch?: number | undefined;
+    productPriceCacheTtlMs?: number | undefined;
+    logLevel?: "silent" | "error" | "warn" | "info" | "debug" | undefined;
+    logger?: unknown;
+}>;
+declare const iapConfigSchema: z.ZodEffects<z.ZodObject<{
+    /**
+     * Static SKU manifest. Optional: when omitted, the library calls
+     * `backend.adapter.listProducts()` (custom adapter) or GETs
+     * `backend.endpoints.products` (HTTP) during `initialize()`. Configs
+     * without either path throw `INVALID_CONFIG` at parse time.
+     */
+    products: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        type: z.ZodEnum<["subscription", "product", "consumable"]>;
+        /**
+         * Optional. Used only by the Android native adapter to disambiguate which
+         * base plan to purchase for multi-plan subscription products (Google Play
+         * Billing). iOS ignores it. When omitted on Android, the native adapter
+         * falls back to `native.getOffer()` (the default offer) — fine for
+         * single-plan subscriptions and for non-subscription products.
+         *
+         * Recommended to set explicitly when a single subscription product has
+         * multiple base plans (e.g. monthly + yearly under one product id).
+         */
+        androidPlanId: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        id: string;
+        type: "subscription" | "product" | "consumable";
+        androidPlanId?: string | undefined;
+    }, {
+        id: string;
+        type: "subscription" | "product" | "consumable";
+        androidPlanId?: string | undefined;
+    }>, "many">>;
+    backend: z.ZodEffects<z.ZodObject<{
+        /**
+         * Custom backend transport. If provided, all HTTP-specific fields below
+         * are ignored and the library uses this object directly for backend
+         * operations. Must implement `BackendAdapter`.
+         */
+        adapter: z.ZodOptional<z.ZodUnknown>;
+        baseUrl: z.ZodOptional<z.ZodString>;
+        endpoints: z.ZodOptional<z.ZodEffects<z.ZodObject<{
+            /**
+             * Optional. Set when the consumer supports iOS purchases. iOS-less
+             * (e.g. Android-only) configs may omit it; the HTTP adapter will throw
+             * `INVALID_CONFIG` at runtime if `verifyApple()` is invoked without this
+             * endpoint configured. At least one of `verifyApple` or `verifyGoogle`
+             * must be set.
+             */
+            verifyApple: z.ZodOptional<z.ZodString>;
+            /**
+             * Optional. Set when the consumer supports Android purchases.
+             * Android-less (e.g. iOS-only) configs may omit it; the HTTP adapter will
+             * throw `INVALID_CONFIG` at runtime if `verifyGoogle()` is invoked
+             * without this endpoint configured. At least one of `verifyApple` or
+             * `verifyGoogle` must be set.
+             */
+            verifyGoogle: z.ZodOptional<z.ZodString>;
+            entitlements: z.ZodString;
+            restore: z.ZodString;
+            /**
+             * Optional. When set, the library fetches the SKU manifest from this
+             * endpoint during `initialize()` if `products` is omitted from config.
+             * See `docs/guide/backend-contract.md` for the response shape.
+             */
+            products: z.ZodOptional<z.ZodString>;
+        }, "strip", z.ZodTypeAny, {
+            entitlements: string;
+            restore: string;
+            verifyApple?: string | undefined;
+            verifyGoogle?: string | undefined;
+            products?: string | undefined;
+        }, {
+            entitlements: string;
+            restore: string;
+            verifyApple?: string | undefined;
+            verifyGoogle?: string | undefined;
+            products?: string | undefined;
+        }>, {
+            entitlements: string;
+            restore: string;
+            verifyApple?: string | undefined;
+            verifyGoogle?: string | undefined;
+            products?: string | undefined;
+        }, {
+            entitlements: string;
+            restore: string;
+            verifyApple?: string | undefined;
+            verifyGoogle?: string | undefined;
+            products?: string | undefined;
+        }>>;
+        /**
+         * Returns auth headers to merge into every backend request. Called fresh
+         * per request so token refresh works automatically. Type is checked at
+         * runtime via shape guard, not zod (zod can't validate function contracts).
+         */
+        getAuthHeaders: z.ZodOptional<z.ZodUnknown>;
+        /** Pre-send request transform. See {@link BackendConfig} for the typed shape. */
+        requestTransform: z.ZodOptional<z.ZodUnknown>;
+        /** Post-receive response transform. See {@link BackendConfig} for the typed shape. */
+        responseTransform: z.ZodOptional<z.ZodUnknown>;
+        entitlementSchema: z.ZodOptional<z.ZodUnknown>;
+        timeoutMs: z.ZodDefault<z.ZodNumber>;
+        retries: z.ZodDefault<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        timeoutMs: number;
+        retries: number;
+        adapter?: unknown;
+        baseUrl?: string | undefined;
+        endpoints?: {
+            entitlements: string;
+            restore: string;
+            verifyApple?: string | undefined;
+            verifyGoogle?: string | undefined;
+            products?: string | undefined;
+        } | undefined;
+        getAuthHeaders?: unknown;
+        requestTransform?: unknown;
+        responseTransform?: unknown;
+        entitlementSchema?: unknown;
+    }, {
+        adapter?: unknown;
+        baseUrl?: string | undefined;
+        endpoints?: {
+            entitlements: string;
+            restore: string;
+            verifyApple?: string | undefined;
+            verifyGoogle?: string | undefined;
+            products?: string | undefined;
+        } | undefined;
+        getAuthHeaders?: unknown;
+        requestTransform?: unknown;
+        responseTransform?: unknown;
+        entitlementSchema?: unknown;
+        timeoutMs?: number | undefined;
+        retries?: number | undefined;
+    }>, {
+        timeoutMs: number;
+        retries: number;
+        adapter?: unknown;
+        baseUrl?: string | undefined;
+        endpoints?: {
+            entitlements: string;
+            restore: string;
+            verifyApple?: string | undefined;
+            verifyGoogle?: string | undefined;
+            products?: string | undefined;
+        } | undefined;
+        getAuthHeaders?: unknown;
+        requestTransform?: unknown;
+        responseTransform?: unknown;
+        entitlementSchema?: unknown;
+    }, {
+        adapter?: unknown;
+        baseUrl?: string | undefined;
+        endpoints?: {
+            entitlements: string;
+            restore: string;
+            verifyApple?: string | undefined;
+            verifyGoogle?: string | undefined;
+            products?: string | undefined;
+        } | undefined;
+        getAuthHeaders?: unknown;
+        requestTransform?: unknown;
+        responseTransform?: unknown;
+        entitlementSchema?: unknown;
+        timeoutMs?: number | undefined;
+        retries?: number | undefined;
+    }>;
+    storage: z.ZodDefault<z.ZodObject<{
+        type: z.ZodDefault<z.ZodEnum<["preferences", "memory", "custom"]>>;
+        namespace: z.ZodDefault<z.ZodString>;
+        adapter: z.ZodOptional<z.ZodUnknown>;
+    }, "strip", z.ZodTypeAny, {
+        type: "preferences" | "memory" | "custom";
+        namespace: string;
+        adapter?: unknown;
+    }, {
+        type?: "preferences" | "memory" | "custom" | undefined;
+        adapter?: unknown;
+        namespace?: string | undefined;
+    }>>;
+    options: z.ZodDefault<z.ZodObject<{
+        refreshOnResume: z.ZodDefault<z.ZodBoolean>;
+        entitlementCacheTtlMs: z.ZodDefault<z.ZodNumber>;
+        recoverUnfinishedTransactions: z.ZodDefault<z.ZodBoolean>;
+        /**
+         * Cap on how many unfinished transactions recovery inspects per launch.
+         * Defends against pathological growth if the consumer's backend has been
+         * down for an extended period and the unfinished list keeps growing.
+         * Excess entries stay in storage and are processed on subsequent launches.
+         */
+        recoveryMaxBatch: z.ZodDefault<z.ZodNumber>;
+        productPriceCacheTtlMs: z.ZodDefault<z.ZodNumber>;
+        logLevel: z.ZodDefault<z.ZodEnum<["silent", "error", "warn", "info", "debug"]>>;
+        logger: z.ZodOptional<z.ZodUnknown>;
+    }, "strip", z.ZodTypeAny, {
+        refreshOnResume: boolean;
+        entitlementCacheTtlMs: number;
+        recoverUnfinishedTransactions: boolean;
+        recoveryMaxBatch: number;
+        productPriceCacheTtlMs: number;
+        logLevel: "silent" | "error" | "warn" | "info" | "debug";
+        logger?: unknown;
+    }, {
+        refreshOnResume?: boolean | undefined;
+        entitlementCacheTtlMs?: number | undefined;
+        recoverUnfinishedTransactions?: boolean | undefined;
+        recoveryMaxBatch?: number | undefined;
+        productPriceCacheTtlMs?: number | undefined;
+        logLevel?: "silent" | "error" | "warn" | "info" | "debug" | undefined;
+        logger?: unknown;
+    }>>;
+}, "strip", z.ZodTypeAny, {
+    options: {
+        refreshOnResume: boolean;
+        entitlementCacheTtlMs: number;
+        recoverUnfinishedTransactions: boolean;
+        recoveryMaxBatch: number;
+        productPriceCacheTtlMs: number;
+        logLevel: "silent" | "error" | "warn" | "info" | "debug";
+        logger?: unknown;
+    };
+    backend: {
+        timeoutMs: number;
+        retries: number;
+        adapter?: unknown;
+        baseUrl?: string | undefined;
+        endpoints?: {
+            entitlements: string;
+            restore: string;
+            verifyApple?: string | undefined;
+            verifyGoogle?: string | undefined;
+            products?: string | undefined;
+        } | undefined;
+        getAuthHeaders?: unknown;
+        requestTransform?: unknown;
+        responseTransform?: unknown;
+        entitlementSchema?: unknown;
+    };
+    storage: {
+        type: "preferences" | "memory" | "custom";
+        namespace: string;
+        adapter?: unknown;
+    };
+    products?: {
+        id: string;
+        type: "subscription" | "product" | "consumable";
+        androidPlanId?: string | undefined;
+    }[] | undefined;
+}, {
+    backend: {
+        adapter?: unknown;
+        baseUrl?: string | undefined;
+        endpoints?: {
+            entitlements: string;
+            restore: string;
+            verifyApple?: string | undefined;
+            verifyGoogle?: string | undefined;
+            products?: string | undefined;
+        } | undefined;
+        getAuthHeaders?: unknown;
+        requestTransform?: unknown;
+        responseTransform?: unknown;
+        entitlementSchema?: unknown;
+        timeoutMs?: number | undefined;
+        retries?: number | undefined;
+    };
+    options?: {
+        refreshOnResume?: boolean | undefined;
+        entitlementCacheTtlMs?: number | undefined;
+        recoverUnfinishedTransactions?: boolean | undefined;
+        recoveryMaxBatch?: number | undefined;
+        productPriceCacheTtlMs?: number | undefined;
+        logLevel?: "silent" | "error" | "warn" | "info" | "debug" | undefined;
+        logger?: unknown;
+    } | undefined;
+    products?: {
+        id: string;
+        type: "subscription" | "product" | "consumable";
+        androidPlanId?: string | undefined;
+    }[] | undefined;
+    storage?: {
+        type?: "preferences" | "memory" | "custom" | undefined;
+        adapter?: unknown;
+        namespace?: string | undefined;
+    } | undefined;
+}>, {
+    options: {
+        refreshOnResume: boolean;
+        entitlementCacheTtlMs: number;
+        recoverUnfinishedTransactions: boolean;
+        recoveryMaxBatch: number;
+        productPriceCacheTtlMs: number;
+        logLevel: "silent" | "error" | "warn" | "info" | "debug";
+        logger?: unknown;
+    };
+    backend: {
+        timeoutMs: number;
+        retries: number;
+        adapter?: unknown;
+        baseUrl?: string | undefined;
+        endpoints?: {
+            entitlements: string;
+            restore: string;
+            verifyApple?: string | undefined;
+            verifyGoogle?: string | undefined;
+            products?: string | undefined;
+        } | undefined;
+        getAuthHeaders?: unknown;
+        requestTransform?: unknown;
+        responseTransform?: unknown;
+        entitlementSchema?: unknown;
+    };
+    storage: {
+        type: "preferences" | "memory" | "custom";
+        namespace: string;
+        adapter?: unknown;
+    };
+    products?: {
+        id: string;
+        type: "subscription" | "product" | "consumable";
+        androidPlanId?: string | undefined;
+    }[] | undefined;
+}, {
+    backend: {
+        adapter?: unknown;
+        baseUrl?: string | undefined;
+        endpoints?: {
+            entitlements: string;
+            restore: string;
+            verifyApple?: string | undefined;
+            verifyGoogle?: string | undefined;
+            products?: string | undefined;
+        } | undefined;
+        getAuthHeaders?: unknown;
+        requestTransform?: unknown;
+        responseTransform?: unknown;
+        entitlementSchema?: unknown;
+        timeoutMs?: number | undefined;
+        retries?: number | undefined;
+    };
+    options?: {
+        refreshOnResume?: boolean | undefined;
+        entitlementCacheTtlMs?: number | undefined;
+        recoverUnfinishedTransactions?: boolean | undefined;
+        recoveryMaxBatch?: number | undefined;
+        productPriceCacheTtlMs?: number | undefined;
+        logLevel?: "silent" | "error" | "warn" | "info" | "debug" | undefined;
+        logger?: unknown;
+    } | undefined;
+    products?: {
+        id: string;
+        type: "subscription" | "product" | "consumable";
+        androidPlanId?: string | undefined;
+    }[] | undefined;
+    storage?: {
+        type?: "preferences" | "memory" | "custom" | undefined;
+        adapter?: unknown;
+        namespace?: string | undefined;
+    } | undefined;
+}>;
+type RawBackendConfig = z.infer<typeof backendConfigSchema>;
+type RawBackendConfigInput = z.input<typeof backendConfigSchema>;
+/**
+ * Replace the schema's `unknown` typings for function-shaped fields with
+ * their precise TS contracts. The schema captures the *structural* shape
+ * and runtime validates "is a function" via `superRefine`; this overlay
+ * gives consumers proper IDE autocomplete and removes the need for
+ * `as never` casts inside the HTTP adapter.
+ *
+ * Zod's `z.function()` would type these as `(...args: unknown[]) => unknown`
+ * which is too wide, and zod can't validate a function *contract* at runtime
+ * anyway — only the existence of a function reference.
+ */
+type FunctionTypedBackendOverlay = {
+    getAuthHeaders?: () => Record<string, string> | Promise<Record<string, string>>;
+    requestTransform?: (req: HttpRequest) => HttpRequest | Promise<HttpRequest>;
+    responseTransform?: (raw: unknown) => unknown | Promise<unknown>;
+};
+type BackendConfig = Omit<RawBackendConfig, 'getAuthHeaders' | 'requestTransform' | 'responseTransform'> & FunctionTypedBackendOverlay;
+type BackendConfigInput = Omit<RawBackendConfigInput, 'getAuthHeaders' | 'requestTransform' | 'responseTransform'> & FunctionTypedBackendOverlay;
+type RawIAPConfig = z.infer<typeof iapConfigSchema>;
+type RawIAPConfigInput = z.input<typeof iapConfigSchema>;
+type IAPConfig = Omit<RawIAPConfig, 'backend'> & {
+    backend: BackendConfig;
+};
+type IAPConfigInput = Omit<RawIAPConfigInput, 'backend'> & {
+    backend: BackendConfigInput;
+};
+type StorageConfig = z.infer<typeof storageConfigSchema>;
+type OptionsConfig = z.infer<typeof optionsConfigSchema>;
+
+declare const entitlementBaseSchema: z.ZodObject<{
+    key: z.ZodString;
+    productId: z.ZodString;
+    expiresAt: z.ZodNullable<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    key: string;
+    productId: string;
+    expiresAt: string | null;
+}, {
+    key: string;
+    productId: string;
+    expiresAt: string | null;
+}>;
+/**
+ * Minimum shape every entitlement returned by the backend must satisfy.
+ * Consumer-defined fields pass through unvalidated unless the consumer
+ * supplies their own schema via `config.backend.entitlementSchema`.
+ */
+type EntitlementBase = z.infer<typeof entitlementBaseSchema>;
+/** Default shape used when no `TEntitlement` type parameter is given. */
+type DefaultEntitlement = EntitlementBase;
+
+declare const IAPErrorCode: {
+    readonly INVALID_CONFIG: "INVALID_CONFIG";
+    readonly NOT_INITIALIZED: "NOT_INITIALIZED";
+    readonly PLATFORM_NOT_SUPPORTED: "PLATFORM_NOT_SUPPORTED";
+    readonly BILLING_NOT_AVAILABLE: "BILLING_NOT_AVAILABLE";
+    readonly PRODUCT_NOT_FOUND: "PRODUCT_NOT_FOUND";
+    readonly USER_CANCELLED: "USER_CANCELLED";
+    readonly PURCHASE_PENDING: "PURCHASE_PENDING";
+    readonly ALREADY_PURCHASED: "ALREADY_PURCHASED";
+    readonly STORE_ERROR: "STORE_ERROR";
+    readonly UNACKNOWLEDGED_PENDING: "UNACKNOWLEDGED_PENDING";
+    readonly ALREADY_IN_PROGRESS: "ALREADY_IN_PROGRESS";
+    readonly BACKEND_UNAVAILABLE: "BACKEND_UNAVAILABLE";
+    readonly BACKEND_TIMEOUT: "BACKEND_TIMEOUT";
+    readonly BACKEND_AUTH_FAILED: "BACKEND_AUTH_FAILED";
+    /** Backend reachable but the response was rejected (non-transient 4xx other
+     *  than auth, malformed JSON, schema violation, 204 No Content on a JSON
+     *  endpoint). Fix the request shape or the backend; do not retry. */
+    readonly BACKEND_BAD_RESPONSE: "BACKEND_BAD_RESPONSE";
+    readonly VERIFICATION_REJECTED: "VERIFICATION_REJECTED";
+    readonly STORAGE_ERROR: "STORAGE_ERROR";
+    /**
+     * The supplied `appUserId` (literal or fetcher-returned) is not a valid
+     * UUID v4. Apple requires a UUID for `appAccountToken`; we enforce the
+     * same constraint cross-platform for a consistent contract.
+     */
+    readonly INVALID_APP_USER_ID: "INVALID_APP_USER_ID";
+    /**
+     * The async `appUserId` fetcher threw or rejected. Original error is
+     * attached as `cause` so the caller can introspect (network failure,
+     * backend 5xx, etc.).
+     */
+    readonly APP_USER_ID_FETCH_FAILED: "APP_USER_ID_FETCH_FAILED";
+};
+type IAPErrorCode = (typeof IAPErrorCode)[keyof typeof IAPErrorCode];
+/** Public accessor for the hint text — exported so docs / consumer error UIs can render it. */
+declare function errorHint(code: IAPErrorCode): string;
+interface IAPErrorOptions {
+    code: IAPErrorCode;
+    message: string;
+    cause?: unknown;
+    recoverable?: boolean;
+    /**
+     * Whether to append the per-code remediation hint to the message.
+     * Defaults to `true`. Set `false` only if the caller already includes a
+     * hint in `message` (avoids double-tagging).
+     */
+    includeHint?: boolean;
+}
+declare class IAPError extends Error {
+    readonly code: IAPErrorCode;
+    readonly recoverable: boolean;
+    readonly cause?: unknown;
+    constructor(options: IAPErrorOptions);
+}
+declare function isIAPError(error: unknown): error is IAPError;
+
+type ProductType = 'subscription' | 'product' | 'consumable';
+interface ConfiguredProduct {
+    id: string;
+    type: ProductType;
+    /**
+     * Required for Android subscriptions — the base plan identifier configured in
+     * Google Play Console. Ignored on iOS and for non-subscription products.
+     */
+    androidPlanId?: string;
+}
+/**
+ * Native product info merged with configured metadata.
+ * Library-public shape — kept stable across Capacitor versions.
+ */
+interface Product {
+    id: string;
+    type: ProductType;
+    title: string;
+    description: string;
+    /** Localized price string, e.g. "$4.99". Always render this — never hardcode. */
+    priceString: string;
+    /** BigInt as string to avoid precision loss, e.g. "4990000". */
+    priceMicros: string;
+    /** ISO 4217 code, e.g. "USD". */
+    currency: string;
+}
+
+/** Platform a transaction originated from. */
+type Platform = 'apple' | 'google';
+/**
+ * Normalized native transaction handed to core flows.
+ * Plugin-version differences are translated by the adapter so this shape
+ * stays stable across Capacitor majors.
+ */
+interface NativeTransaction {
+    platform: Platform;
+    productId: string;
+    /**
+     * Apple: the StoreKit `transactionId` (numeric string).
+     * Google: the `purchaseToken` from Play Billing.
+     */
+    token: string;
+    /** Google only — required by Attesto's `/v1/google/verify`. */
+    packageName?: string;
+    /** Product type the transaction was originally purchased as. */
+    productType: ProductType;
+    /** Optional pass-through of plugin-native fields for backend hints. */
+    raw?: unknown;
+}
+/**
+ * Verified transaction returned by the consumer backend after Attesto check.
+ * Generic over the backend-defined transaction shape.
+ */
+interface VerifiedTransaction<TExtra = Record<string, unknown>> {
+    id: string;
+    productId: string;
+    expiresAt: string | null;
+    verifiedAt: string;
+    raw?: TExtra;
+}
+
+/**
+ * Map of event name → payload. Used by the typed event emitter so consumer
+ * subscriptions are statically checked.
+ */
+interface EventMap<TEntitlement extends EntitlementBase = EntitlementBase> {
+    ready: undefined;
+    'purchase-started': {
+        productId: string;
+    };
+    'purchase-success': {
+        productId: string;
+        transaction: VerifiedTransaction;
+    };
+    'purchase-cancelled': {
+        productId: string;
+    };
+    'purchase-pending': {
+        productId: string;
+    };
+    'purchase-failed': {
+        productId: string;
+        error: IAPError;
+    };
+    'verification-failed': {
+        productId: string;
+        error: IAPError;
+    };
+    'restore-started': undefined;
+    'restore-completed': {
+        restored: number;
+        entitlements: TEntitlement[];
+    };
+    'entitlements-changed': {
+        entitlements: TEntitlement[];
+        previous: TEntitlement[];
+    };
+    'price-stale': {
+        productId: string;
+        lastFetchedAt: number;
+    };
+    error: {
+        error: IAPError;
+    };
+}
+type EventName<TEntitlement extends EntitlementBase = EntitlementBase> = keyof EventMap<TEntitlement>;
+type EventPayload<K extends EventName<TEntitlement>, TEntitlement extends EntitlementBase = EntitlementBase> = EventMap<TEntitlement>[K];
+type Unsubscribe = () => void;
+
+/**
+ * Value supplied to `iap.purchase({ appUserId })`. Either a UUID v4
+ * string the caller already has (e.g. from local cache / app state) or
+ * an async fetcher the library invokes once per purchase to retrieve
+ * the UUID from the caller's backend (typical pattern: backend mints +
+ * persists on first call, returns the existing UUID on later calls).
+ *
+ * The fetcher is invoked **fresh on every purchase** — iap caches
+ * nothing. The backend owns the mint-or-lookup idempotency. The
+ * fetcher closes over whatever auth state the caller needs (session
+ * token, JWT, cookie); iap passes no implicit context.
+ *
+ * Either form is validated as UUID v4 before being forwarded to
+ * StoreKit's `appAccountToken` (iOS) / Play Billing's
+ * `obfuscatedAccountId` (Android). Non-UUID values throw
+ * `IAPError(INVALID_APP_USER_ID)`. A throwing/rejecting fetcher
+ * surfaces as `IAPError(APP_USER_ID_FETCH_FAILED, cause: <original>)`.
+ */
+type AppUserId = string | (() => Promise<string>);
+/**
+ * Options accepted by `iap.purchase(...)`. `productId` is required;
+ * `appUserId` is optional — when omitted, no `applicationUsername` is
+ * passed to the native plugin (identical to behavior before v0.2).
+ */
+interface PurchaseOptions {
+    productId: string;
+    /**
+     * Pre-attach a user identifier so it travels through the StoreKit /
+     * Play Billing purchase and reaches your backend on both the verify
+     * response and the eventual webhook. Eliminates the verify/webhook
+     * race for purchases where you have a user identity at purchase time.
+     * See `AppUserId` for supplied-value semantics.
+     */
+    appUserId?: AppUserId;
+}
+type PurchaseResult<TEntitlement extends EntitlementBase = EntitlementBase> = {
+    status: 'success';
+    productId: string;
+    transaction: VerifiedTransaction;
+    entitlements: TEntitlement[];
+} | {
+    status: 'cancelled';
+    productId: string;
+} | {
+    status: 'pending';
+    productId: string;
+} | {
+    status: 'verification_failed';
+    productId: string;
+    error: IAPError;
+} | {
+    status: 'failed';
+    productId: string;
+    error: IAPError;
+};
+interface RestoreResult<TEntitlement extends EntitlementBase = EntitlementBase> {
+    restored: number;
+    entitlements: TEntitlement[];
+}
+
+interface IAP<TEntitlement extends EntitlementBase = EntitlementBase> {
+    initialize(): Promise<void>;
+    /**
+     * Refresh entitlements from the consumer backend.
+     *
+     * Fetches via the configured `BackendAdapter` (HTTP default or custom),
+     * freezes results, persists them via the storage adapter, and emits
+     * `entitlements-changed`.
+     */
+    refresh(): Promise<void>;
+    /**
+     * Tear down. Removes event listeners and disposes the native adapter
+     * (which clears its `pendingFinish` map and removes the long-lived
+     * `.approved()` listener on cdv).
+     *
+     * NOTE 1: persisted entitlement cache is NOT cleared. If you're handling
+     * a logout for a multi-user app, also call your storage adapter's
+     * `clear()` (or the consumer-supplied equivalent) before the next user
+     * logs in, otherwise their first read will see the previous user's
+     * cached entitlements until `refresh()` returns.
+     *
+     * NOTE 2: calling `destroy()` while a `purchase()` is in flight may
+     * leave the result in an inconsistent state — the backend may have
+     * recorded the entitlement but the native `acknowledge()` call will
+     * be a no-op (because cdv's `pendingFinish` was cleared mid-flow).
+     * On Android this means Google auto-refunds in 3 days. Avoid by
+     * awaiting the in-flight `purchase()` before calling `destroy()`.
+     */
+    destroy(): Promise<void>;
+    /**
+     * Start a purchase. Throws `IAPError` only on impossible states
+     * (NOT_INITIALIZED, ALREADY_IN_PROGRESS, PRODUCT_NOT_FOUND,
+     * INVALID_APP_USER_ID, APP_USER_ID_FETCH_FAILED); all other
+     * outcomes — user cancellation, backend rejection, native errors — are
+     * surfaced via the `PurchaseResult` discriminated union so the caller
+     * can render the right UI without try/catch gymnastics.
+     *
+     * `opts.appUserId` is optional. When provided (string or async fetcher
+     * returning a string), the resolved value is validated as a UUID v4
+     * and forwarded to StoreKit's `appAccountToken` (iOS) / Play
+     * Billing's `obfuscatedAccountId` (Android) — making it available on
+     * Attesto's verify response and outbound webhook payload as
+     * `appUserId` so backends can join on user identity directly. See
+     * `PurchaseOptions` and `AppUserId` for full semantics.
+     *
+     * Emits `purchase-started`, then exactly one of: `purchase-success`
+     * (+ `entitlements-changed`), `purchase-cancelled`, `purchase-pending`,
+     * `verification-failed`, or `purchase-failed`.
+     */
+    purchase(opts: PurchaseOptions): Promise<PurchaseResult<TEntitlement>>;
+    /**
+     * Re-verify every owned transaction with the consumer backend and
+     * refresh entitlements from the consolidated response. Wire this to a
+     * "Restore Purchases" button.
+     *
+     * Returns `{ restored, entitlements }` where `restored` is the number
+     * of native transactions submitted (0 on a fresh install with no
+     * purchases). Throws `IAPError` on backend rejection or transport
+     * failure — wrap the call in try/catch in the consumer's button
+     * handler.
+     *
+     * Emits `restore-started`, then on success `restore-completed` +
+     * `entitlements-changed` (the latter only when the entitlements list
+     * actually changed). On failure no completion event fires; the thrown
+     * error is the only signal.
+     *
+     * NOTE on the empty-owned-list case: when the platform store reports
+     * no owned transactions (fresh install, signed-out Apple ID, etc.),
+     * the library short-circuits — it does NOT call the backend and
+     * preserves whatever entitlements were already cached in memory. If
+     * you suspect cache staleness (e.g. user just signed in to a new
+     * Apple ID), call `iap.refresh()` afterward to reconcile against the
+     * backend's view of the user's entitlements.
+     */
+    restorePurchases(): Promise<RestoreResult<TEntitlement>>;
+    /**
+     * Get product info merged with native pricing. Returns one entry per
+     * product the platform store knows about; products configured but not
+     * yet ingested by the store are silently skipped (no error).
+     */
+    getProducts(): Promise<Product[]>;
+    hasEntitlement(key: string): boolean;
+    /** Returns a defensive shallow copy. Each entitlement is frozen. */
+    getEntitlements(): TEntitlement[];
+    /** Returns a frozen entitlement reference, or null if missing. */
+    getEntitlement(key: string): TEntitlement | null;
+    on<K extends EventName<TEntitlement>>(event: K, handler: (payload: EventPayload<K, TEntitlement>) => void): Unsubscribe;
+}
+declare function createIAP<TEntitlement extends EntitlementBase = EntitlementBase>(input: IAPConfigInput): IAP<TEntitlement>;
+
+/**
+ * Library version. Updated by the publish workflow to match `package.json`.
+ * Read at runtime by the logger so error reports include the version.
+ */
+declare const VERSION = "0.1.0";
+
+interface VerifyAppleRequest {
+    productId: string;
+    /** Apple StoreKit transaction id (numeric string). */
+    transactionId: string;
+    type: ProductType;
+}
+interface VerifyGoogleRequest {
+    productId: string;
+    /** Google Play `purchaseToken`. */
+    purchaseToken: string;
+    /** Application package name (e.g. `com.example.app`). */
+    packageName: string;
+    type: ProductType;
+}
+/** A single entry in a restore batch. Discriminated by `platform`. */
+type RestoreRequestTransaction = {
+    platform: 'apple';
+    productId: string;
+    transactionId: string;
+} | {
+    platform: 'google';
+    productId: string;
+    purchaseToken: string;
+    packageName: string;
+};
+interface RestoreRequest {
+    transactions: RestoreRequestTransaction[];
+}
+/** Public response type for `verifyApple` / `verifyGoogle`, generic over the consumer's entitlement shape. */
+type VerifyResponse<TEntitlement extends EntitlementBase = EntitlementBase> = {
+    valid: true;
+    entitlements: TEntitlement[];
+    transaction: {
+        id: string;
+        productId: string;
+        expiresAt?: string | null;
+    };
+} | {
+    valid: false;
+    error: string;
+    message?: string;
+};
+/**
+ * Restore response. Distinct from {@link VerifyResponse} because the
+ * orchestrator never reads `transaction` on the restore path — the schema
+ * accordingly omits any required transaction echo. Backends that include
+ * a `transaction` (or any other field) on the success branch ride through
+ * unmodified via top-level passthrough; consumers cast to read them.
+ */
+type RestoreResponse<TEntitlement extends EntitlementBase = EntitlementBase> = {
+    valid: true;
+    entitlements: TEntitlement[];
+} | {
+    valid: false;
+    error: string;
+    message?: string;
+};
+/**
+ * Abstracts the consumer's backend so the orchestrator (Phase 4+) doesn't
+ * depend on `fetch`. The default `HttpBackendAdapter` is HTTP/JSON via
+ * `fetch`; consumers on GraphQL, gRPC-web, Supabase, Firebase, etc. supply
+ * their own implementation via `config.backend.adapter`.
+ *
+ * All methods MUST validate response shape. Failures should throw IAPError
+ * (HTTP impl uses BACKEND_UNAVAILABLE / BACKEND_TIMEOUT / BACKEND_AUTH_FAILED
+ * / VERIFICATION_REJECTED depending on cause) — the orchestrator relies on
+ * `IAPError.recoverable` to decide whether to surface a transient error or
+ * abort the purchase flow.
+ */
+interface BackendAdapter<TEntitlement extends EntitlementBase = EntitlementBase> {
+    verifyApple(req: VerifyAppleRequest): Promise<VerifyResponse<TEntitlement>>;
+    verifyGoogle(req: VerifyGoogleRequest): Promise<VerifyResponse<TEntitlement>>;
+    /** GET current entitlements; library uses this for refresh + warm cache. */
+    getEntitlements(): Promise<TEntitlement[]>;
+    /**
+     * Batch re-verify. Backend returns consolidated entitlements.
+     *
+     * Returns {@link RestoreResponse} (not {@link VerifyResponse}) — the orchestrator
+     * does not consume any per-transaction echo on restore, so the response
+     * shape intentionally omits the required `transaction` field that verify
+     * has. Backends may still attach a `transaction` (or any other extras)
+     * — they ride through via the schema's top-level passthrough.
+     */
+    restore(req: RestoreRequest): Promise<RestoreResponse<TEntitlement>>;
+    /**
+     * Optional: return the SKU manifest the app should register.
+     *
+     * When implemented, the library calls this during `initialize()` if the
+     * consumer omitted `products` from `createIAP()` config — letting the
+     * backend curate which SKUs are surfaced (feature flags, A/B mixes,
+     * regional catalogs). Returned ids MUST still be pre-registered in App
+     * Store Connect / Google Play Console; the manifest is a curated subset,
+     * not a registration.
+     */
+    listProducts?(): Promise<ConfiguredProduct[]>;
+}
+
+interface HttpBackendAdapterOptions {
+    baseUrl: string;
+    endpoints: {
+        /**
+         * Optional. Required only when the consumer's app actually invokes
+         * `verifyApple` (iOS purchases). Android-only configs may omit it; the
+         * adapter throws `INVALID_CONFIG` if `verifyApple()` is called without
+         * this set. At least one of `verifyApple` or `verifyGoogle` must be set
+         * for any usable config.
+         */
+        verifyApple?: string;
+        /**
+         * Optional. Required only when the consumer's app actually invokes
+         * `verifyGoogle` (Android purchases). iOS-only configs may omit it; the
+         * adapter throws `INVALID_CONFIG` if `verifyGoogle()` is called without
+         * this set. At least one of `verifyApple` or `verifyGoogle` must be set
+         * for any usable config.
+         */
+        verifyGoogle?: string;
+        entitlements: string;
+        restore: string;
+        products?: string;
+    };
+    getAuthHeaders: () => Record<string, string> | Promise<Record<string, string>>;
+    requestTransform?: BackendConfig['requestTransform'];
+    responseTransform?: BackendConfig['responseTransform'];
+    timeoutMs: number;
+    retries: number;
+    fetch?: typeof fetch;
+    logger: Logger;
+}
+/**
+ * Default `BackendAdapter` implementation: HTTP/JSON via `fetch`.
+ *
+ * The four methods translate to HTTP calls against the consumer's backend:
+ * - `verifyApple` → POST `endpoints.verifyApple`
+ * - `verifyGoogle` → POST `endpoints.verifyGoogle`
+ * - `getEntitlements` → GET `endpoints.entitlements`
+ * - `restore` → POST `endpoints.restore`
+ *
+ * The recommended request/response shape mirrors Attesto's normalized
+ * transaction one hop downstream (see PLAN.md §5.8). Consumers whose
+ * backend uses a different shape can supply `requestTransform` /
+ * `responseTransform` to map between the library's defaults and theirs.
+ */
+declare class HttpBackendAdapter<TEntitlement extends EntitlementBase = EntitlementBase> implements BackendAdapter<TEntitlement> {
+    private readonly http;
+    private readonly endpoints;
+    constructor(opts: HttpBackendAdapterOptions);
+    verifyApple(req: VerifyAppleRequest): Promise<VerifyResponse<TEntitlement>>;
+    verifyGoogle(req: VerifyGoogleRequest): Promise<VerifyResponse<TEntitlement>>;
+    getEntitlements(): Promise<TEntitlement[]>;
+    restore(req: RestoreRequest): Promise<RestoreResponse<TEntitlement>>;
+    listProducts(): Promise<ConfiguredProduct[]>;
+}
+
+export { type AppUserId, type BackendAdapter, type BackendConfig, type BackendConfigInput, type ConfiguredProduct, type DefaultEntitlement, type EntitlementBase, type EventMap, type EventName, type EventPayload, HttpBackendAdapter, HttpClient, type HttpRequest, type IAP, type IAPConfig, type IAPConfigInput, IAPError, IAPErrorCode, type LogLevel, type Logger, type NativeTransaction, type OptionsConfig, type Platform, type Product, type ProductType, type PurchaseOptions, type PurchaseResult, type RestoreRequest, type RestoreRequestTransaction, type RestoreResponse, type RestoreResult, type StorageConfig, type Unsubscribe, VERSION, type VerifiedTransaction, type VerifyAppleRequest, type VerifyGoogleRequest, type VerifyResponse, createIAP, errorHint, isIAPError };