@nosslabs/iap 0.3.0 → 0.4.0

package/CHANGELOG.md

@@ -5,6 +5,108 @@ Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); version
 
 ## [Unreleased]
 
+## [0.4.0] — 2026-05-08
+
+### Added
+
+- **`options.permanentErrorCodes` config** — list of backend
+  `valid:false` error codes that recovery should treat as permanent.
+  Entries with a matching error are removed from
+  `unfinished_transactions` storage instead of being retried on every
+  app launch. Defaults to `['TRANSACTION_NOT_FOUND', 'PRODUCT_MISMATCH']`
+  per the documented recipe contract — the two codes that mean "the
+  backend looked and the answer is permanently no, this transaction is
+  not valid." When provided, the option REPLACES the default (no magic
+  merge); pass `[...DEFAULT_PERMANENT_ERROR_CODES, 'YOUR_CODE']` to
+  extend, or `[]` to disable the feature entirely (revert to
+  retry-forever behavior).
+
+  ```ts
+  import { createIAP, DEFAULT_PERMANENT_ERROR_CODES } from '@nosslabs/iap';
+
+  // Default: TRANSACTION_NOT_FOUND and PRODUCT_MISMATCH are dropped.
+  createIAP({ /* ... */ });
+
+  // Extend with your backend's custom permanent codes.
+  createIAP({
+    options: {
+      permanentErrorCodes: [...DEFAULT_PERMANENT_ERROR_CODES, 'MY_CUSTOM_CODE'],
+    },
+  });
+
+  // Opt out entirely — every valid:false retains the entry for retry.
+  createIAP({
+    options: { permanentErrorCodes: [] },
+  });
+  ```
+
+- **`'recovery-dropped-permanent'` event** — fires once per entry
+  removed by the new classifier. Payload:
+  `{ productId, token, error, message? }`. Useful for ops
+  observability when a stuck-loop self-heals.
+
+- **`DEFAULT_PERMANENT_ERROR_CODES` exported** from the package root
+  for the spread-then-extend pattern above.
+
+- **`RecoveryResult.droppedPermanent`** — new field on the recovery
+  result alongside `recovered` and `failures`. Counts how many
+  entries were removed during the current sweep.
+
+### Changed
+
+- **Recovery no longer retries `valid:false` responses with
+  permanently-invalid error codes** (default:
+  `TRANSACTION_NOT_FOUND`, `PRODUCT_MISMATCH`). Previous behavior is
+  preserved for any code not in the permanent set, and is
+  configurable via `options.permanentErrorCodes`. Strict improvement
+  for the cases it affects (stuck loops self-heal); other paths
+  unchanged. **Bumped to a minor version** because the behavior is
+  observable — consumers asserting on `RecoveryResult` shape or
+  intentionally depending on retry-forever semantics for a specific
+  code should opt out via `permanentErrorCodes: []`.
+
+  > **Backend assumption.** The default set assumes your backend
+  > queries Apple App Store Server API / Google Play Developer API
+  > with eventually-consistent reads (typical for Attesto's recipe
+  > pattern). If your backend reads from a replicated database with
+  > replication lag exceeding app-launch cadence, a `TRANSACTION_NOT_FOUND`
+  > response could be transient — in that case configure
+  > `permanentErrorCodes: []` (or a custom set) until you've reconciled
+  > the lag.
+
+## [0.3.1] — 2026-05-06
+
+### Added
+
+- **`appUserId` async fetcher may now accept an optional `ctx`
+  parameter.** The library passes `{ authHeaders }` populated from
+  `backend.getAuthHeaders()` (resolved fresh per purchase), letting
+  consumers reuse the same auth they configured for IAP-backend
+  requests when their UUID-minting endpoint uses that same auth.
+  The parameter is optional convenience, not contract — zero-arg
+  fetchers from 0.2.x continue to work unchanged. Ignore the
+  parameter when your UUID endpoint uses different auth and close
+  over your own auth state instead. For consumers using a custom
+  `BackendAdapter` (no `getAuthHeaders` configured), `ctx.authHeaders`
+  is `{}`.
+
+  ```ts
+  // before — still valid
+  appUserId: async () => {
+    const r = await fetch('/api/iap/uuid', { method: 'POST', headers: authHeaders() });
+    return (await r.json()).uuid;
+  }
+
+  // after — equivalent, no helper duplication
+  appUserId: async ({ authHeaders }) => {
+    const r = await fetch('/api/iap/uuid', { method: 'POST', headers: authHeaders });
+    return (await r.json()).uuid;
+  }
+  ```
+
+  See `docs/guide/getting-started.md` (Pre-attaching a user identifier)
+  and `docs/api/types.md` (`AppUserId`) for the updated reference.
+
 ## [0.3.0] — 2026-05-06
 
 ### Changed (BREAKING)

package/README.md

@@ -46,7 +46,7 @@ if (result.status === 'success') {
 await iap.purchase({
   productId: 'premium_monthly',
   appUserId: async () => {
-    const r = await fetch('/api/iap/uuid', { headers: authHeaders() });
+    const r = await fetch('/api/iap/uuid', { method: 'POST', headers: authHeaders() });
     return (await r.json()).uuid;
   },
 });

package/dist/index.cjs

@@ -730,6 +730,19 @@ var optionsConfigSchema = zod.z.object({
    * Excess entries stay in storage and are processed on subsequent launches.
    */
   recoveryMaxBatch: zod.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: zod.z.array(zod.z.string()).optional(),
   productPriceCacheTtlMs: zod.z.number().int().positive().default(24 * 60 * 60 * 1e3),
   logLevel: zod.z.enum(["silent", "error", "warn", "info", "debug"]).default("info"),
   logger: zod.z.unknown().optional()
@@ -1232,7 +1245,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 {
@@ -1349,11 +1366,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 exports.IAPError({
         code: exports.IAPErrorCode.APP_USER_ID_FETCH_FAILED,
@@ -1374,6 +1391,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;
@@ -1383,7 +1404,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) {
@@ -1396,6 +1417,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") {
@@ -1405,6 +1427,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;
       }
@@ -1413,19 +1437,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" };
       }
@@ -1851,6 +1903,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,
@@ -1864,7 +1918,8 @@ function createIAP(input) {
         },
         setCachePersisted: (cachedAt) => {
           state.cachedAt = cachedAt;
-        }
+        },
+        getAuthHeaders
       };
       state.orchestrator = new PurchaseOrchestrator({
         ...sharedDeps,
@@ -1873,7 +1928,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();
@@ -2064,6 +2122,7 @@ init_errors();
 // src/version.ts
 var VERSION = "0.1.0";
 
+exports.DEFAULT_PERMANENT_ERROR_CODES = DEFAULT_PERMANENT_ERROR_CODES;
 exports.HttpBackendAdapter = HttpBackendAdapter;
 exports.HttpClient = HttpClient;
 exports.VERSION = VERSION;