@nosslabs/iap 8.1.0 → 8.2.0

package/CHANGELOG.md

@@ -3,6 +3,63 @@
 All notable changes to `@nosslabs/iap` will be documented here.
 Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); versions follow [Semantic Versioning](https://semver.org/).
 
+## [8.2.0] — 2026-10-27
+
+### Changed
+
+- **`@capacitor/preferences` is now an optional peer, loaded only when it is used.** It was a
+  required peer reached through a *static* import, so it ended up in the bundle's top-level
+  imports and every consumer shipped the native plugin — including one passing
+  `storage.type: 'custom'` with its own storage, which never calls Preferences at all.
+
+  `PreferencesAdapter` now reaches the plugin through `await import()`, memoised per instance,
+  the way the resume listener reaches `@capacitor/app`. Neither `dist/index.js` nor
+  `dist/index.cjs` names it at the top level any more, asserted on the built artifact by a new
+  `npm run verify:bundle` step in CI and before publish — a static import behaves identically
+  at runtime and differs only in what the bundler hoists, so no unit test can see it.
+
+  Choosing `storage.type: 'preferences'` (still the default) without the plugin installed now
+  fails at `initialize()` with `INVALID_CONFIG`, naming what to install and the two
+  alternatives that need no plugin. It is reported there, via the new optional
+  `StorageAdapter.ensureAvailable()`, rather than at the first cache read: that read treats any
+  failure as "nothing cached", so a missing plugin would have looked like a cold start while
+  iap silently persisted nothing.
+
+  **If you use `storage.type: 'preferences'`, keep the plugin installed** — but check it is in
+  your *own* `dependencies`. npm 7+ installs a required peer into the tree without listing it
+  in your `package.json`; now that it is optional, a fresh install or a regenerated lockfile
+  can drop it, and `npx cap sync` with it.
+
+  If you pass your own adapter or use `'memory'`, you can uninstall it — and then you must
+  **externalise it in your bundler**, because a dynamic `import()` is still resolved at build
+  time: without it Vite/Rollup fails with `failed to resolve import "@capacitor/preferences"`.
+  The installation guide has the one-line config. (This is not new to this release — the
+  optional `@capacitor/app` has always behaved the same way — but it is now worth stating.)
+
+- **Developed and tested against `@capgo/native-purchases@8.9.6`** (was `8.6.5`). The peer
+  range is unchanged at `^8.2.0`. Nothing in iap broke, and two of the plugin's documented
+  gaps closed — both caught by the inverted contract guards rather than by reading release
+  notes:
+
+  - **Purchase tokens no longer reach logcat.** Through `8.6.5` the Android plugin logged them
+    in the clear with no debug gate, which [the native-layer
+    page](https://iap.nossdev.com/guide/native-layer) warned about. Every Android log now goes
+    through a `NativePurchasesLog` wrapper gated on `BuildConfig.DEBUG` or an explicit
+    `debugLogging` config, and the purchase summary it emits carries no token. Verified by
+    asserting that no `android.util.Log` call survives outside the wrapper, so a regression
+    fails CI; the warning is off the page.
+  - **`purchaseProduct()` accepts an `offerToken`.** Choosing a specific offer within a base
+    plan is now possible at the native layer. iap does not forward one yet — `purchase()` has
+    no way to name an offer — so this is recorded as a feature to build rather than a gap to
+    live with.
+
+  The plugin also moved to **Play Billing Library 9.1.0** (from 8.3.0), a native major. It
+  changes nothing iap relies on, and that was checked against the 9.1.0 artifact rather than
+  assumed: `Purchase.PurchaseState` still reads `UNSPECIFIED_STATE = 0, PURCHASED = 1,
+  PENDING = 2`, and `consumeAsync`, `acknowledgePurchase` and `queryPurchasesAsync` keep their
+  signatures — the three facts the Android purchase-state check and the consumable path are
+  built on.
+
 ## [8.1.0] — 2026-10-27
 
 ### Changed

package/README.md

@@ -84,20 +84,41 @@ It does **not**: talk to Attesto directly, manage user auth, or ship paywall UI.
 
 | `@nosslabs/iap` | Capacitor | Native plugin | dist-tag | Status |
 |---|---|---|---|---|
-| 8.x | 8.x | `@capgo/native-purchases ^8` | `@latest`, `@latest-8` | **Current** — `8.0.0` |
+| 8.x | 8.x | `@capgo/native-purchases ^8.2` | `@latest`, `@latest-8` | **Current** — `8.2.0` |
 | 7.x | 7.x | `@capgo/native-purchases@lts-v7` | `@latest-7` (pin via `^7`) | Maintenance |
 | 5.x | 5.x | `cordova-plugin-purchase ^13.x` | `@latest-5` (pin via `^5`) | Maintenance |
 
-## Optional peer dependency
+## Optional peer dependencies
 
-If you want auto-refresh on app resume (default behavior):
+Both are reached through a lazy `import()`, so an app that does not use them never loads them
+and keeps them out of its bundle. If you *uninstall* one, externalise it in your bundler
+(`build.rollupOptions.external` in Vite) — a dynamic import is still resolved at build time.
+See the [installation guide](https://iap.nossdev.com/guide/installation).
+
+**`@capacitor/app`** — auto-refresh on app resume (the default behaviour):
 
 ```bash
 npm install @capacitor/app
 npx cap sync
 ```
 
-Or disable the listener with `options.refreshOnResume: false`. See [installation guide](https://iap.nossdev.com/guide/installation#optional-app-resume-listener).
+Or disable the listener with `options.refreshOnResume: false`.
+
+**`@capacitor/preferences`** — the entitlement cache and unfinished-transaction storage, under
+the default `storage.type: 'preferences'`:
+
+```bash
+npm install @capacitor/preferences
+npx cap sync
+```
+
+Skip it if you set `storage.type` to `'custom'` (your own adapter) or `'memory'`. Choosing
+`'preferences'` without it fails at `initialize()` with a message saying so, rather than
+silently persisting nothing.
+
+If you use the default `'preferences'` and never declared the package yourself, add it to your
+`dependencies` now: npm installed it for you while it was a *required* peer, and that will stop
+happening.
 
 ## Development
 

package/dist/index.cjs

@@ -3,7 +3,6 @@
 var core = require('@capacitor/core');
 var nativePurchases = require('@capgo/native-purchases');
 var zod = require('zod');
-var preferences = require('@capacitor/preferences');
 
 var __defProp = Object.defineProperty;
 var __getOwnPropNames = Object.getOwnPropertyNames;
@@ -1979,39 +1978,122 @@ init_errors();
 var PreferencesAdapter = class {
   prefix;
   knownKeys = /* @__PURE__ */ new Set();
+  /**
+   * Boxed, and that is not incidental — see {@link PreferencesAdapter.preferences}.
+   */
+  plugin = null;
   constructor(namespace) {
     this.prefix = `${namespace}.`;
   }
+  /**
+   * The plugin, inside a box.
+   *
+   * The box is load-bearing. `registerPlugin()` hands back a **Proxy** that
+   * answers any property, `then` included — so resolving a promise *with*
+   * the plugin makes it look like a thenable, and promise assimilation
+   * calls `Preferences.then()`. On web that rejects with
+   * `"Preferences.then()" is not implemented on web`, from inside
+   * `await this.preferences()`, for every storage operation.
+   *
+   * Wrapping it in a plain object means the promise resolves with something
+   * that has no `then`, so nothing is assimilated.
+   */
+  preferences() {
+    this.plugin ??= import('@capacitor/preferences').then((mod) => ({ preferences: mod.Preferences })).catch((cause) => {
+      if (isModuleNotFound(cause)) throw notInstalled(cause);
+      this.plugin = null;
+      throw new exports.IAPError({
+        code: exports.IAPErrorCode.STORAGE_ERROR,
+        message: "Could not load @capacitor/preferences. The package is installed, so this is most likely a chunk that failed to load; it is worth retrying.",
+        cause,
+        recoverable: true
+      });
+    });
+    return this.plugin;
+  }
+  /**
+   * Resolve the plugin now, so a missing one is reported at `initialize()`.
+   *
+   * See the note on lazy loading above for why this is not left to the first
+   * `get()`.
+   */
+  async ensureAvailable() {
+    await this.preferences();
+  }
   async get(key) {
+    const { preferences } = await this.preferences();
     try {
-      const result = await preferences.Preferences.get({ key: this.prefix + key });
+      const result = await preferences.get({ key: this.prefix + key });
       return result.value;
     } catch (cause) {
       throw wrap(cause, `Preferences.get failed for "${key}".`);
     }
   }
   async set(key, value) {
+    const { preferences } = await this.preferences();
     try {
-      await preferences.Preferences.set({ key: this.prefix + key, value });
+      await preferences.set({ key: this.prefix + key, value });
       this.knownKeys.add(key);
     } catch (cause) {
       throw wrap(cause, `Preferences.set failed for "${key}".`);
     }
   }
   async remove(key) {
+    const { preferences } = await this.preferences();
     try {
-      await preferences.Preferences.remove({ key: this.prefix + key });
+      await preferences.remove({ key: this.prefix + key });
       this.knownKeys.delete(key);
     } catch (cause) {
       throw wrap(cause, `Preferences.remove failed for "${key}".`);
     }
   }
   async clear() {
+    const { preferences } = await this.preferences();
     const keys = [...this.knownKeys];
-    this.knownKeys.clear();
-    await Promise.all(keys.map((k) => preferences.Preferences.remove({ key: this.prefix + k })));
+    const failed = [];
+    const errors = [];
+    await Promise.all(
+      keys.map(async (key) => {
+        try {
+          await preferences.remove({ key: this.prefix + key });
+          this.knownKeys.delete(key);
+        } catch (cause) {
+          failed.push(key);
+          errors.push(cause);
+        }
+      })
+    );
+    if (failed.length > 0) {
+      throw wrap(errors[0], `Preferences.clear failed for ${failed.length} key(s).`);
+    }
   }
 };
+function isModuleNotFound(cause) {
+  let current = cause;
+  for (let depth = 0; depth < 5 && current; depth += 1) {
+    const code = current.code;
+    if (code === "ERR_MODULE_NOT_FOUND" || code === "MODULE_NOT_FOUND") return true;
+    const message = current instanceof Error ? current.message : String(current);
+    if (/cannot find (module|package)|could not resolve|failed to resolve/i.test(message)) {
+      return true;
+    }
+    const next = current.cause;
+    if (next === current) break;
+    current = next;
+  }
+  return false;
+}
+function notInstalled(cause) {
+  return new exports.IAPError({
+    code: exports.IAPErrorCode.INVALID_CONFIG,
+    message: 'storage.type is "preferences" (the default) but @capacitor/preferences is not installed. Install it (npm i @capacitor/preferences && npx cap sync), or choose storage that needs no plugin: storage.type "memory", or "custom" with your own adapter.',
+    // The per-code hint for INVALID_CONFIG sends the reader to check field
+    // paths against the config schema. There are none to check, and no
+    // config change fixes this — the message above already says what to do.
+    includeHint: false,
+    cause
+  });
+}
 function wrap(cause, message) {
   return new exports.IAPError({
     code: exports.IAPErrorCode.STORAGE_ERROR,
@@ -2112,12 +2194,7 @@ var EntitlementCache = class {
     try {
       await this.storage.set(ENTITLEMENTS_KEY, JSON.stringify(envelope));
     } catch (cause) {
-      throw new exports.IAPError({
-        code: exports.IAPErrorCode.STORAGE_ERROR,
-        message: "Failed to persist entitlement cache.",
-        cause,
-        recoverable: true
-      });
+      throw toIAPError(cause, "Failed to persist entitlement cache.", exports.IAPErrorCode.STORAGE_ERROR);
     }
     return cachedAt;
   }
@@ -3064,6 +3141,7 @@ async function initializeIap(state, refreshEntitlements) {
     state.logger.debug("initialize() called more than once; ignoring.");
     return;
   }
+  await state.storage.ensureAvailable?.();
   const platform = getPlatform();
   if (!isNative()) {
     state.logger.info("Native purchases unavailable on web; entitlement queries still functional.");
@@ -3357,6 +3435,7 @@ async function resetIap(state) {
       recoverable: true
     });
   }
+  await state.storage.ensureAvailable?.();
   const previous = state.entitlements;
   state.entitlements = [];
   state.cachedAt = null;
@@ -3533,12 +3612,11 @@ var UnfinishedTransactionsStore = class {
     try {
       await this.storage.set(STORE_KEY2, JSON.stringify(entries));
     } catch (cause) {
-      throw new exports.IAPError({
-        code: exports.IAPErrorCode.STORAGE_ERROR,
-        message: "Failed to persist unfinished transactions list.",
+      throw toIAPError(
         cause,
-        recoverable: true
-      });
+        "Failed to persist unfinished transactions list.",
+        exports.IAPErrorCode.STORAGE_ERROR
+      );
     }
   }
   async safeClear() {
@@ -3801,7 +3879,7 @@ function resolveLogger(level, candidate) {
 init_errors();
 
 // src/version.ts
-var VERSION = "8.1.0";
+var VERSION = "8.2.0";
 
 exports.DEFAULT_PERMANENT_ERROR_CODES = DEFAULT_PERMANENT_ERROR_CODES;
 exports.HttpBackendAdapter = HttpBackendAdapter;