@nosslabs/iap 0.3.0 → 0.4.0

package/dist/index.d.cts

@@ -224,6 +224,19 @@ declare const optionsConfigSchema: z.ZodObject<{
      * Excess entries stay in storage and are processed on subsequent launches.
      */
     recoveryMaxBatch: z.ZodDefault<z.ZodNumber>;
+    /**
+     * List of backend `valid:false` error codes that recovery should treat as
+     * permanent — entries with a matching error are removed from storage
+     * instead of retried on every launch. When omitted (the default), iap
+     * uses `DEFAULT_PERMANENT_ERROR_CODES` (`['TRANSACTION_NOT_FOUND',
+     * 'PRODUCT_MISMATCH']`).
+     *
+     * REPLACES the default when provided — pass `[...DEFAULT_PERMANENT_ERROR_CODES,
+     * 'YOUR_CODE']` to extend, or `[]` to disable the feature entirely
+     * (revert to retry-forever behavior). Export the constant from
+     * `@nosslabs/iap` for the spread form.
+     */
+    permanentErrorCodes: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
     productPriceCacheTtlMs: z.ZodDefault<z.ZodNumber>;
     logLevel: z.ZodDefault<z.ZodEnum<["silent", "error", "warn", "info", "debug"]>>;
     logger: z.ZodOptional<z.ZodUnknown>;
@@ -234,12 +247,14 @@ declare const optionsConfigSchema: z.ZodObject<{
     recoveryMaxBatch: number;
     productPriceCacheTtlMs: number;
     logLevel: "silent" | "error" | "warn" | "info" | "debug";
+    permanentErrorCodes?: string[] | undefined;
     logger?: unknown;
 }, {
     refreshOnResume?: boolean | undefined;
     entitlementCacheTtlMs?: number | undefined;
     recoverUnfinishedTransactions?: boolean | undefined;
     recoveryMaxBatch?: number | undefined;
+    permanentErrorCodes?: string[] | undefined;
     productPriceCacheTtlMs?: number | undefined;
     logLevel?: "silent" | "error" | "warn" | "info" | "debug" | undefined;
     logger?: unknown;
@@ -434,6 +449,19 @@ declare const iapConfigSchema: z.ZodEffects<z.ZodObject<{
          * Excess entries stay in storage and are processed on subsequent launches.
          */
         recoveryMaxBatch: z.ZodDefault<z.ZodNumber>;
+        /**
+         * List of backend `valid:false` error codes that recovery should treat as
+         * permanent — entries with a matching error are removed from storage
+         * instead of retried on every launch. When omitted (the default), iap
+         * uses `DEFAULT_PERMANENT_ERROR_CODES` (`['TRANSACTION_NOT_FOUND',
+         * 'PRODUCT_MISMATCH']`).
+         *
+         * REPLACES the default when provided — pass `[...DEFAULT_PERMANENT_ERROR_CODES,
+         * 'YOUR_CODE']` to extend, or `[]` to disable the feature entirely
+         * (revert to retry-forever behavior). Export the constant from
+         * `@nosslabs/iap` for the spread form.
+         */
+        permanentErrorCodes: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
         productPriceCacheTtlMs: z.ZodDefault<z.ZodNumber>;
         logLevel: z.ZodDefault<z.ZodEnum<["silent", "error", "warn", "info", "debug"]>>;
         logger: z.ZodOptional<z.ZodUnknown>;
@@ -444,12 +472,14 @@ declare const iapConfigSchema: z.ZodEffects<z.ZodObject<{
         recoveryMaxBatch: number;
         productPriceCacheTtlMs: number;
         logLevel: "silent" | "error" | "warn" | "info" | "debug";
+        permanentErrorCodes?: string[] | undefined;
         logger?: unknown;
     }, {
         refreshOnResume?: boolean | undefined;
         entitlementCacheTtlMs?: number | undefined;
         recoverUnfinishedTransactions?: boolean | undefined;
         recoveryMaxBatch?: number | undefined;
+        permanentErrorCodes?: string[] | undefined;
         productPriceCacheTtlMs?: number | undefined;
         logLevel?: "silent" | "error" | "warn" | "info" | "debug" | undefined;
         logger?: unknown;
@@ -462,6 +492,7 @@ declare const iapConfigSchema: z.ZodEffects<z.ZodObject<{
         recoveryMaxBatch: number;
         productPriceCacheTtlMs: number;
         logLevel: "silent" | "error" | "warn" | "info" | "debug";
+        permanentErrorCodes?: string[] | undefined;
         logger?: unknown;
     };
     backend: {
@@ -514,6 +545,7 @@ declare const iapConfigSchema: z.ZodEffects<z.ZodObject<{
         entitlementCacheTtlMs?: number | undefined;
         recoverUnfinishedTransactions?: boolean | undefined;
         recoveryMaxBatch?: number | undefined;
+        permanentErrorCodes?: string[] | undefined;
         productPriceCacheTtlMs?: number | undefined;
         logLevel?: "silent" | "error" | "warn" | "info" | "debug" | undefined;
         logger?: unknown;
@@ -536,6 +568,7 @@ declare const iapConfigSchema: z.ZodEffects<z.ZodObject<{
         recoveryMaxBatch: number;
         productPriceCacheTtlMs: number;
         logLevel: "silent" | "error" | "warn" | "info" | "debug";
+        permanentErrorCodes?: string[] | undefined;
         logger?: unknown;
     };
     backend: {
@@ -588,6 +621,7 @@ declare const iapConfigSchema: z.ZodEffects<z.ZodObject<{
         entitlementCacheTtlMs?: number | undefined;
         recoverUnfinishedTransactions?: boolean | undefined;
         recoveryMaxBatch?: number | undefined;
+        permanentErrorCodes?: string[] | undefined;
         productPriceCacheTtlMs?: number | undefined;
         logLevel?: "silent" | "error" | "warn" | "info" | "debug" | undefined;
         logger?: unknown;
@@ -814,6 +848,24 @@ interface EventMap<TEntitlement extends EntitlementBase = EntitlementBase> {
         productId: string;
         lastFetchedAt: number;
     };
+    /**
+     * Recovery classified an `unfinished_transactions` entry as permanently
+     * invalid (per `options.permanentErrorCodes`) and removed it from
+     * storage. Will not be retried on subsequent launches. Useful for ops
+     * logging / alerting on stuck-loop self-heal events.
+     *
+     * **Token is unmasked.** Receipt tokens (Apple `transactionId` /
+     * Google `purchaseToken`) are useful for correlation in debugging
+     * but are receipts you don't want to leak — treat as sensitive. Mask
+     * before forwarding to external analytics / logging services. iap's
+     * own internal logs use a masked form (see `lib/redact.ts`).
+     */
+    'recovery-dropped-permanent': {
+        productId: string;
+        token: string;
+        error: string;
+        message?: string;
+    };
     error: {
         error: IAPError;
     };
@@ -822,6 +874,24 @@ type EventName<TEntitlement extends EntitlementBase = EntitlementBase> = keyof E
 type EventPayload<K extends EventName<TEntitlement>, TEntitlement extends EntitlementBase = EntitlementBase> = EventMap<TEntitlement>[K];
 type Unsubscribe = () => void;
 
+/**
+ * Convenience context the library passes to a function-form
+ * {@link AppUserId} fetcher. `authHeaders` is the result of awaiting
+ * `backend.getAuthHeaders()` — the same headers the library will use
+ * for its own backend requests. Resolved fresh per purchase so token
+ * refresh keeps working.
+ *
+ * It's a convenience, not a contract: fetchers may legitimately ignore
+ * the parameter. Use it when your UUID-minting endpoint shares auth
+ * with your IAP backend; ignore it (and close over your own auth
+ * state) when it doesn't.
+ *
+ * For consumers using a custom `BackendAdapter` (no `getAuthHeaders`
+ * configured), `authHeaders` is `{}`.
+ */
+interface AppUserIdFetcherContext {
+    authHeaders: Record<string, string>;
+}
 /**
  * Value supplied to `iap.purchase({ appUserId })`. Either a UUID v4
  * string the caller already has (e.g. from local cache / app state) or
@@ -830,9 +900,14 @@ type Unsubscribe = () => void;
  * 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.
+ * nothing. The backend owns the mint-or-lookup idempotency.
+ *
+ * Two fetcher shapes are supported:
+ * - `() => Promise<string>` — closes over its own auth state.
+ * - `(ctx) => Promise<string>` — receives `ctx.authHeaders` populated
+ *   from `backend.getAuthHeaders()` so the auth wired up for IAP
+ *   requests can be reused without redefining a helper. See
+ *   {@link AppUserIdFetcherContext}.
  *
  * Either form is validated as UUID v4 before being forwarded to
  * StoreKit's `appAccountToken` (iOS) / Play Billing's
@@ -840,7 +915,7 @@ type Unsubscribe = () => void;
  * `IAPError(INVALID_APP_USER_ID)`. A throwing/rejecting fetcher
  * surfaces as `IAPError(APP_USER_ID_FETCH_FAILED, cause: <original>)`.
  */
-type AppUserId = string | (() => Promise<string>);
+type AppUserId = string | (() => Promise<string>) | ((ctx: AppUserIdFetcherContext) => Promise<string>);
 /**
  * Options accepted by `iap.purchase(...)`. `productId` is required;
  * `appUserId` is optional — when omitted, no `applicationUsername` is
@@ -972,12 +1047,6 @@ interface IAP<TEntitlement extends EntitlementBase = EntitlementBase> {
 }
 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). */
@@ -1075,6 +1144,28 @@ interface BackendAdapter<TEntitlement extends EntitlementBase = EntitlementBase>
     listProducts?(): Promise<ConfiguredProduct[]>;
 }
 
+/**
+ * Backend `valid:false` error codes that are treated as permanent by default
+ * (entry removed from `unfinished_transactions` instead of retried forever).
+ *
+ * Conservative on purpose: only the two codes the documented recipe
+ * contract identifies as unambiguous "domain-not-found" answers. Consumers
+ * with custom backend error vocabularies extend via
+ * `options.permanentErrorCodes`.
+ *
+ * Distinct from the `RECOVERABLE_CODES` set in `lib/errors.ts`: that one
+ * classifies iap-internal `IAPErrorCode`s for transport/storage retry
+ * semantics; this one classifies opaque error strings the consumer's
+ * backend returns in `valid:false` responses.
+ */
+declare const DEFAULT_PERMANENT_ERROR_CODES: readonly string[];
+
+/**
+ * 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 HttpBackendAdapterOptions {
     baseUrl: string;
     endpoints: {
@@ -1131,4 +1222,4 @@ declare class HttpBackendAdapter<TEntitlement extends EntitlementBase = Entitlem
     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 };
+export { type AppUserId, type BackendAdapter, type BackendConfig, type BackendConfigInput, type ConfiguredProduct, DEFAULT_PERMANENT_ERROR_CODES, 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 };

package/dist/index.d.ts

@@ -224,6 +224,19 @@ declare const optionsConfigSchema: z.ZodObject<{
      * Excess entries stay in storage and are processed on subsequent launches.
      */
     recoveryMaxBatch: z.ZodDefault<z.ZodNumber>;
+    /**
+     * List of backend `valid:false` error codes that recovery should treat as
+     * permanent — entries with a matching error are removed from storage
+     * instead of retried on every launch. When omitted (the default), iap
+     * uses `DEFAULT_PERMANENT_ERROR_CODES` (`['TRANSACTION_NOT_FOUND',
+     * 'PRODUCT_MISMATCH']`).
+     *
+     * REPLACES the default when provided — pass `[...DEFAULT_PERMANENT_ERROR_CODES,
+     * 'YOUR_CODE']` to extend, or `[]` to disable the feature entirely
+     * (revert to retry-forever behavior). Export the constant from
+     * `@nosslabs/iap` for the spread form.
+     */
+    permanentErrorCodes: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
     productPriceCacheTtlMs: z.ZodDefault<z.ZodNumber>;
     logLevel: z.ZodDefault<z.ZodEnum<["silent", "error", "warn", "info", "debug"]>>;
     logger: z.ZodOptional<z.ZodUnknown>;
@@ -234,12 +247,14 @@ declare const optionsConfigSchema: z.ZodObject<{
     recoveryMaxBatch: number;
     productPriceCacheTtlMs: number;
     logLevel: "silent" | "error" | "warn" | "info" | "debug";
+    permanentErrorCodes?: string[] | undefined;
     logger?: unknown;
 }, {
     refreshOnResume?: boolean | undefined;
     entitlementCacheTtlMs?: number | undefined;
     recoverUnfinishedTransactions?: boolean | undefined;
     recoveryMaxBatch?: number | undefined;
+    permanentErrorCodes?: string[] | undefined;
     productPriceCacheTtlMs?: number | undefined;
     logLevel?: "silent" | "error" | "warn" | "info" | "debug" | undefined;
     logger?: unknown;
@@ -434,6 +449,19 @@ declare const iapConfigSchema: z.ZodEffects<z.ZodObject<{
          * Excess entries stay in storage and are processed on subsequent launches.
          */
         recoveryMaxBatch: z.ZodDefault<z.ZodNumber>;
+        /**
+         * List of backend `valid:false` error codes that recovery should treat as
+         * permanent — entries with a matching error are removed from storage
+         * instead of retried on every launch. When omitted (the default), iap
+         * uses `DEFAULT_PERMANENT_ERROR_CODES` (`['TRANSACTION_NOT_FOUND',
+         * 'PRODUCT_MISMATCH']`).
+         *
+         * REPLACES the default when provided — pass `[...DEFAULT_PERMANENT_ERROR_CODES,
+         * 'YOUR_CODE']` to extend, or `[]` to disable the feature entirely
+         * (revert to retry-forever behavior). Export the constant from
+         * `@nosslabs/iap` for the spread form.
+         */
+        permanentErrorCodes: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
         productPriceCacheTtlMs: z.ZodDefault<z.ZodNumber>;
         logLevel: z.ZodDefault<z.ZodEnum<["silent", "error", "warn", "info", "debug"]>>;
         logger: z.ZodOptional<z.ZodUnknown>;
@@ -444,12 +472,14 @@ declare const iapConfigSchema: z.ZodEffects<z.ZodObject<{
         recoveryMaxBatch: number;
         productPriceCacheTtlMs: number;
         logLevel: "silent" | "error" | "warn" | "info" | "debug";
+        permanentErrorCodes?: string[] | undefined;
         logger?: unknown;
     }, {
         refreshOnResume?: boolean | undefined;
         entitlementCacheTtlMs?: number | undefined;
         recoverUnfinishedTransactions?: boolean | undefined;
         recoveryMaxBatch?: number | undefined;
+        permanentErrorCodes?: string[] | undefined;
         productPriceCacheTtlMs?: number | undefined;
         logLevel?: "silent" | "error" | "warn" | "info" | "debug" | undefined;
         logger?: unknown;
@@ -462,6 +492,7 @@ declare const iapConfigSchema: z.ZodEffects<z.ZodObject<{
         recoveryMaxBatch: number;
         productPriceCacheTtlMs: number;
         logLevel: "silent" | "error" | "warn" | "info" | "debug";
+        permanentErrorCodes?: string[] | undefined;
         logger?: unknown;
     };
     backend: {
@@ -514,6 +545,7 @@ declare const iapConfigSchema: z.ZodEffects<z.ZodObject<{
         entitlementCacheTtlMs?: number | undefined;
         recoverUnfinishedTransactions?: boolean | undefined;
         recoveryMaxBatch?: number | undefined;
+        permanentErrorCodes?: string[] | undefined;
         productPriceCacheTtlMs?: number | undefined;
         logLevel?: "silent" | "error" | "warn" | "info" | "debug" | undefined;
         logger?: unknown;
@@ -536,6 +568,7 @@ declare const iapConfigSchema: z.ZodEffects<z.ZodObject<{
         recoveryMaxBatch: number;
         productPriceCacheTtlMs: number;
         logLevel: "silent" | "error" | "warn" | "info" | "debug";
+        permanentErrorCodes?: string[] | undefined;
         logger?: unknown;
     };
     backend: {
@@ -588,6 +621,7 @@ declare const iapConfigSchema: z.ZodEffects<z.ZodObject<{
         entitlementCacheTtlMs?: number | undefined;
         recoverUnfinishedTransactions?: boolean | undefined;
         recoveryMaxBatch?: number | undefined;
+        permanentErrorCodes?: string[] | undefined;
         productPriceCacheTtlMs?: number | undefined;
         logLevel?: "silent" | "error" | "warn" | "info" | "debug" | undefined;
         logger?: unknown;
@@ -814,6 +848,24 @@ interface EventMap<TEntitlement extends EntitlementBase = EntitlementBase> {
         productId: string;
         lastFetchedAt: number;
     };
+    /**
+     * Recovery classified an `unfinished_transactions` entry as permanently
+     * invalid (per `options.permanentErrorCodes`) and removed it from
+     * storage. Will not be retried on subsequent launches. Useful for ops
+     * logging / alerting on stuck-loop self-heal events.
+     *
+     * **Token is unmasked.** Receipt tokens (Apple `transactionId` /
+     * Google `purchaseToken`) are useful for correlation in debugging
+     * but are receipts you don't want to leak — treat as sensitive. Mask
+     * before forwarding to external analytics / logging services. iap's
+     * own internal logs use a masked form (see `lib/redact.ts`).
+     */
+    'recovery-dropped-permanent': {
+        productId: string;
+        token: string;
+        error: string;
+        message?: string;
+    };
     error: {
         error: IAPError;
     };
@@ -822,6 +874,24 @@ type EventName<TEntitlement extends EntitlementBase = EntitlementBase> = keyof E
 type EventPayload<K extends EventName<TEntitlement>, TEntitlement extends EntitlementBase = EntitlementBase> = EventMap<TEntitlement>[K];
 type Unsubscribe = () => void;
 
+/**
+ * Convenience context the library passes to a function-form
+ * {@link AppUserId} fetcher. `authHeaders` is the result of awaiting
+ * `backend.getAuthHeaders()` — the same headers the library will use
+ * for its own backend requests. Resolved fresh per purchase so token
+ * refresh keeps working.
+ *
+ * It's a convenience, not a contract: fetchers may legitimately ignore
+ * the parameter. Use it when your UUID-minting endpoint shares auth
+ * with your IAP backend; ignore it (and close over your own auth
+ * state) when it doesn't.
+ *
+ * For consumers using a custom `BackendAdapter` (no `getAuthHeaders`
+ * configured), `authHeaders` is `{}`.
+ */
+interface AppUserIdFetcherContext {
+    authHeaders: Record<string, string>;
+}
 /**
  * Value supplied to `iap.purchase({ appUserId })`. Either a UUID v4
  * string the caller already has (e.g. from local cache / app state) or
@@ -830,9 +900,14 @@ type Unsubscribe = () => void;
  * 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.
+ * nothing. The backend owns the mint-or-lookup idempotency.
+ *
+ * Two fetcher shapes are supported:
+ * - `() => Promise<string>` — closes over its own auth state.
+ * - `(ctx) => Promise<string>` — receives `ctx.authHeaders` populated
+ *   from `backend.getAuthHeaders()` so the auth wired up for IAP
+ *   requests can be reused without redefining a helper. See
+ *   {@link AppUserIdFetcherContext}.
  *
  * Either form is validated as UUID v4 before being forwarded to
  * StoreKit's `appAccountToken` (iOS) / Play Billing's
@@ -840,7 +915,7 @@ type Unsubscribe = () => void;
  * `IAPError(INVALID_APP_USER_ID)`. A throwing/rejecting fetcher
  * surfaces as `IAPError(APP_USER_ID_FETCH_FAILED, cause: <original>)`.
  */
-type AppUserId = string | (() => Promise<string>);
+type AppUserId = string | (() => Promise<string>) | ((ctx: AppUserIdFetcherContext) => Promise<string>);
 /**
  * Options accepted by `iap.purchase(...)`. `productId` is required;
  * `appUserId` is optional — when omitted, no `applicationUsername` is
@@ -972,12 +1047,6 @@ interface IAP<TEntitlement extends EntitlementBase = EntitlementBase> {
 }
 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). */
@@ -1075,6 +1144,28 @@ interface BackendAdapter<TEntitlement extends EntitlementBase = EntitlementBase>
     listProducts?(): Promise<ConfiguredProduct[]>;
 }
 
+/**
+ * Backend `valid:false` error codes that are treated as permanent by default
+ * (entry removed from `unfinished_transactions` instead of retried forever).
+ *
+ * Conservative on purpose: only the two codes the documented recipe
+ * contract identifies as unambiguous "domain-not-found" answers. Consumers
+ * with custom backend error vocabularies extend via
+ * `options.permanentErrorCodes`.
+ *
+ * Distinct from the `RECOVERABLE_CODES` set in `lib/errors.ts`: that one
+ * classifies iap-internal `IAPErrorCode`s for transport/storage retry
+ * semantics; this one classifies opaque error strings the consumer's
+ * backend returns in `valid:false` responses.
+ */
+declare const DEFAULT_PERMANENT_ERROR_CODES: readonly string[];
+
+/**
+ * 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 HttpBackendAdapterOptions {
     baseUrl: string;
     endpoints: {
@@ -1131,4 +1222,4 @@ declare class HttpBackendAdapter<TEntitlement extends EntitlementBase = Entitlem
     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 };
+export { type AppUserId, type BackendAdapter, type BackendConfig, type BackendConfigInput, type ConfiguredProduct, DEFAULT_PERMANENT_ERROR_CODES, 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 };

package/dist/index.js

@@ -728,6 +728,19 @@ var optionsConfigSchema = z.object({
    * Excess entries stay in storage and are processed on subsequent launches.
    */
   recoveryMaxBatch: z.number().int().positive().default(50),
+  /**
+   * List of backend `valid:false` error codes that recovery should treat as
+   * permanent — entries with a matching error are removed from storage
+   * instead of retried on every launch. When omitted (the default), iap
+   * uses `DEFAULT_PERMANENT_ERROR_CODES` (`['TRANSACTION_NOT_FOUND',
+   * 'PRODUCT_MISMATCH']`).
+   *
+   * REPLACES the default when provided — pass `[...DEFAULT_PERMANENT_ERROR_CODES,
+   * 'YOUR_CODE']` to extend, or `[]` to disable the feature entirely
+   * (revert to retry-forever behavior). Export the constant from
+   * `@nosslabs/iap` for the spread form.
+   */
+  permanentErrorCodes: z.array(z.string()).optional(),
   productPriceCacheTtlMs: z.number().int().positive().default(24 * 60 * 60 * 1e3),
   logLevel: z.enum(["silent", "error", "warn", "info", "debug"]).default("info"),
   logger: z.unknown().optional()
@@ -1230,7 +1243,11 @@ var PurchaseOrchestrator = class {
         message: `Product "${productId}" is not in the configured catalog.`
       });
     }
-    const resolvedAppUserId = appUserId !== void 0 ? await resolveAppUserId(appUserId) : void 0;
+    let resolvedAppUserId;
+    if (appUserId !== void 0) {
+      const ctx = typeof appUserId === "function" ? { authHeaders: await this.deps.getAuthHeaders() } : { authHeaders: {} };
+      resolvedAppUserId = await resolveAppUserId(appUserId, ctx);
+    }
     this.inFlight.add(productId);
     this.deps.emitter.emit("purchase-started", { productId });
     try {
@@ -1347,11 +1364,11 @@ var PurchaseOrchestrator = class {
     return { status: "verification_failed", productId, error: iapError };
   }
 };
-async function resolveAppUserId(supply) {
+async function resolveAppUserId(supply, ctx) {
   let resolved;
   if (typeof supply === "function") {
     try {
-      resolved = await supply();
+      resolved = await supply(ctx);
     } catch (cause) {
       throw new IAPError({
         code: IAPErrorCode.APP_USER_ID_FETCH_FAILED,
@@ -1372,6 +1389,10 @@ async function resolveAppUserId(supply) {
 }
 
 // src/core/recovery-flow.ts
+var DEFAULT_PERMANENT_ERROR_CODES = [
+  "TRANSACTION_NOT_FOUND",
+  "PRODUCT_MISMATCH"
+];
 var RecoveryOrchestrator = class {
   constructor(deps) {
     this.deps = deps;
@@ -1381,7 +1402,7 @@ var RecoveryOrchestrator = class {
     const { unfinished, logger, maxBatch } = this.deps;
     const allEntries = await unfinished.list();
     if (allEntries.length === 0) {
-      return { recovered: 0, failures: 0, inspected: 0 };
+      return { recovered: 0, failures: 0, droppedPermanent: 0, inspected: 0 };
     }
     const entries = allEntries.slice(0, maxBatch);
     if (allEntries.length > maxBatch) {
@@ -1394,6 +1415,7 @@ var RecoveryOrchestrator = class {
     const settled = await Promise.allSettled(entries.map((entry) => this.processEntry(entry)));
     let recovered = 0;
     let failures = 0;
+    let droppedPermanent = 0;
     let latestEntitlements = null;
     for (const result of settled) {
       if (result.status === "rejected") {
@@ -1403,6 +1425,8 @@ var RecoveryOrchestrator = class {
       if (result.value.kind === "recovered") {
         recovered += 1;
         latestEntitlements = result.value.entitlements;
+      } else if (result.value.kind === "dropped-permanent") {
+        droppedPermanent += 1;
       } else {
         failures += 1;
       }
@@ -1411,19 +1435,47 @@ var RecoveryOrchestrator = class {
       await this.applyEntitlements(latestEntitlements);
     }
     logger.debug(
-      `Recovery: ${recovered} recovered, ${failures} left in list (will retry next launch).`
+      `Recovery: ${recovered} recovered, ${droppedPermanent} dropped (permanent), ${failures} left in list (will retry next launch).`
     );
-    return { recovered, failures, inspected: entries.length };
+    return { recovered, failures, droppedPermanent, inspected: entries.length };
   }
   async processEntry(entry) {
-    const { nativeAdapter, unfinished, logger } = this.deps;
+    const { nativeAdapter, unfinished, logger, emitter, permanentErrorCodes } = this.deps;
     const tx = entryToNativeTransaction(entry);
     const tokenLabel = maskToken(entry.token);
     try {
       const response = await verifyNativeTransaction(this.deps.backend, tx);
       if (!response.valid) {
+        if (permanentErrorCodes.has(response.error)) {
+          logger.info(
+            `Recovery: dropping permanently-invalid token=${tokenLabel} productId=${entry.productId} (${response.error}).`
+          );
+          try {
+            await nativeAdapter.acknowledge(tx);
+          } catch (error) {
+            logger.warn(
+              `Recovery: best-effort acknowledge() failed for productId=${entry.productId}; proceeding with removal anyway.`,
+              error
+            );
+          }
+          try {
+            await unfinished.remove(entry.token);
+          } catch (error) {
+            logger.warn(
+              `Recovery: unfinished.remove() failed for productId=${entry.productId} after permanent classification; will dedupe on next launch.`,
+              error
+            );
+          }
+          emitter.emit("recovery-dropped-permanent", {
+            productId: entry.productId,
+            token: entry.token,
+            error: response.error,
+            ...response.message !== void 0 ? { message: response.message } : {}
+          });
+          return { kind: "dropped-permanent" };
+        }
         logger.debug(
-          `Recovery: backend rejected token=${tokenLabel} productId=${entry.productId} (${response.error}); leaving in list.`
+          `Recovery: backend rejected token=${tokenLabel} productId=${entry.productId} (${response.error}); leaving in list for retry.`
         );
         return { kind: "failed" };
       }
@@ -1849,6 +1901,8 @@ function createIAP(input) {
         state.logger.debug(`Resolved ${validated.data.length} product(s) from backend manifest.`);
       }
       state.adapter = await selectNativeAdapter({ products: state.products });
+      const configGetAuthHeaders = state.config.backend.getAuthHeaders;
+      const getAuthHeaders = configGetAuthHeaders ? async () => configGetAuthHeaders() : async () => ({});
       const sharedDeps = {
         nativeAdapter: state.adapter,
         backend: state.backend,
@@ -1862,7 +1916,8 @@ function createIAP(input) {
         },
         setCachePersisted: (cachedAt) => {
           state.cachedAt = cachedAt;
-        }
+        },
+        getAuthHeaders
       };
       state.orchestrator = new PurchaseOrchestrator({
         ...sharedDeps,
@@ -1871,7 +1926,10 @@ function createIAP(input) {
       state.restorer = new RestoreOrchestrator(sharedDeps);
       state.recoverer = new RecoveryOrchestrator({
         ...sharedDeps,
-        maxBatch: state.config.options.recoveryMaxBatch
+        maxBatch: state.config.options.recoveryMaxBatch,
+        permanentErrorCodes: new Set(
+          state.config.options.permanentErrorCodes ?? DEFAULT_PERMANENT_ERROR_CODES
+        )
       });
       try {
         await state.adapter.isAvailable();
@@ -2062,6 +2120,6 @@ init_errors();
 // src/version.ts
 var VERSION = "0.1.0";
 
-export { HttpBackendAdapter, HttpClient, IAPError, IAPErrorCode, VERSION, createIAP, errorHint, isIAPError };
+export { DEFAULT_PERMANENT_ERROR_CODES, HttpBackendAdapter, HttpClient, IAPError, IAPErrorCode, VERSION, createIAP, errorHint, isIAPError };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map