@nosslabs/iap 0.3.1 → 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;
     };
@@ -995,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). */
@@ -1098,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: {
@@ -1154,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;
     };
@@ -995,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). */
@@ -1098,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: {
@@ -1154,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()
@@ -1376,6 +1389,10 @@ async function resolveAppUserId(supply, ctx) {
 }
 
 // src/core/recovery-flow.ts
+var DEFAULT_PERMANENT_ERROR_CODES = [
+  "TRANSACTION_NOT_FOUND",
+  "PRODUCT_MISMATCH"
+];
 var RecoveryOrchestrator = class {
   constructor(deps) {
     this.deps = deps;
@@ -1385,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) {
@@ -1398,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") {
@@ -1407,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;
       }
@@ -1415,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" };
       }
@@ -1878,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();
@@ -2069,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