@nosslabs/iap 0.3.1 → 5.0.0

package/CHANGELOG.md

@@ -5,6 +5,92 @@ Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); version
 
 ## [Unreleased]
 
+## [5.0.0] — 2026-05-14
+
+### Changed
+
+- **Renumbered the Capacitor 5 line from `0.x` to `5.x`** so the
+  library's major version tracks the Capacitor major it targets
+  (matching the convention `@capgo/native-purchases`, Ionic plugins,
+  and most platform-aligned ecosystems use). **No code changes vs
+  `0.4.0`** — the published tarball is functionally identical.
+  Consumers: bump your dependency `^0.4.0` → `^5.0.0`. Nothing else
+  needs to change.
+
+The Capacitor 7+ line is published on the `@next` dist-tag as `7.x`
+(currently `7.0.0-next.0` prerelease). See [Migration](https://iap.nossdev.com/migration/)
+when you're ready to move to Capacitor 7. The `5.x` line on this
+branch (`5.x`) continues to receive Capacitor-5 patches.
+
+## [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
@@ -24,13 +110,13 @@ Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); version
   ```ts
   // before — still valid
   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;
   }
 
   // after — equivalent, no helper duplication
   appUserId: async ({ authHeaders }) => {
-    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/README.md

@@ -2,7 +2,7 @@
 
 > Thin Capacitor IAP orchestrator. Server-side validation via [Attesto](https://attesto.nossdev.com).
 
-**Status: 0.2.0 — published.** API may have breaking changes through the 0.x line as it's exercised in production apps. Pin the minor version (`^0.2.0`) and watch the [CHANGELOG](./CHANGELOG.md).
+**Status: `5.x` — the Capacitor 5 maintenance line on the `@latest` dist-tag.** Renumbered from `0.4.x` to track the Capacitor major (same code, new number). The Capacitor 7+ line is `7.x` on the `@next` dist-tag (still prerelease — see [Migration](https://iap.nossdev.com/migration/)). Pin the minor (`^5.0.0`) and watch the [CHANGELOG](./CHANGELOG.md).
 
 ```bash
 npm install @nosslabs/iap cordova-plugin-purchase
@@ -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;
   },
 });
@@ -75,10 +75,10 @@ It does **not**: talk to Attesto directly, define entitlement business logic, ma
 
 ## Capacitor support matrix
 
-| `@nosslabs/iap` | Capacitor | Plugin | Status |
-|---|---|---|---|
-| 0.x | 5.x | `cordova-plugin-purchase ^13.x` | **Current** |
-| 1.x | 7.x | TBD (Capacitor-native plugin) | Roadmap |
+| `@nosslabs/iap` | Capacitor | Native plugin | dist-tag | Status |
+|---|---|---|---|---|
+| 5.x | 5.x | `cordova-plugin-purchase ^13.x` | `@latest` | **Current (this branch)** |
+| 7.x | 7.x (also runs on 8.x) | `@capgo/native-purchases` | `@next` | Prerelease |
 
 ## Optional peer dependency
 

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()
@@ -1378,6 +1391,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;
@@ -1387,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) {
@@ -1400,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") {
@@ -1409,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;
       }
@@ -1417,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" };
       }
@@ -1880,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();
@@ -2071,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;