@livx.cc/appwrap 0.54.0 → 0.56.0

package/src/config.ts

@@ -308,6 +308,13 @@ export interface AppwrapConfig {
    * (the per-app `permissions{}` map only OVERRIDES the default usage copy). When ABSENT, every
    * capability is active and permissions come solely from `permissions{}` (pre-modules behavior). */
   modules?: string[];
+  /** Extra module packs layered on top of the built-in capabilities (see packs.ts). Each entry is a
+   * local directory OR an npm package name; a pack contributes `ModuleManifest[]` (+ handler files,
+   * native source, an optional kit client). Packs apply in order, LAST-WINS by module name, so a pack
+   * can add a NEW capability or wholesale-shadow a built-in one (e.g. swap the billing implementation).
+   * This is the single public extension seam — the same mechanism a host, consumer apps that vendor
+   * their own module, and community plugins all use. Absent → built-ins only (unchanged behavior). */
+  modulePacks?: string[];
   /** Permitted headless background-task identifiers (for the `backgroundTask` module). iOS REQUIRES
    * these declared at build time — they stamp into Info.plist `BGTaskSchedulerPermittedIdentifiers`
    * (without them `BGTaskScheduler.register` throws) plus `fetch`+`processing` into UIBackgroundModes.
@@ -366,7 +373,7 @@ export function defineConfig(config: AppwrapConfig): AppwrapConfig {
  */
 export const KNOWN_CONFIG_KEYS: ReadonlySet<string> = new Set([
   'androidAppLinks', 'appBoundDomains', 'backendOrigin', 'backgroundAudio', 'backgroundColor', 'backgroundTasks', 'buildNumber', 'debug',
-  'debugLog', 'desktop', 'devMenu', 'edgeToEdge', 'entry', 'icon', 'id', 'iosKeyboardExtraLift', 'loader', 'modules', 'name',
+  'debugLog', 'desktop', 'devMenu', 'edgeToEdge', 'entry', 'icon', 'id', 'iosKeyboardExtraLift', 'loader', 'modules', 'modulePacks', 'name',
   'envSwitcher', 'iosEntitlements', 'neutralizeServiceWorker', 'oauthRedirectSchemes', 'openNewWindowsInBrowser', 'orientation', 'overrides', 'permissions',
   'plugins', 'push', 'pwaDist', 'queryPackages', 'queryUrlSchemes', 'serverUrl', 'signing', 'signingProfiles', 'statusBarStyle',
   'splashIcon', 'storekitConfig', 'targetedDevices', 'teamId', 'themeColor', 'trackingDomains', 'urlScheme',

package/src/handlers.ts

@@ -1,7 +1,7 @@
 /**
  * `defineHandlers` — author custom native handlers for the appwrap DESKTOP shell, run as a Bun sidecar.
  *
- * The desktop shell (runtime-desktop) spawns `bun <yourFile>` when `desktop.handlers` is set, and routes
+ * The desktop shell spawns `bun <yourFile>` when `desktop.handlers` is set, and routes
  * any method your map advertises to this process over NDJSON on stdin/stdout (appwrap sidecar protocol v1).
  * The PWA calls them through the kit with a raw invoke: `kit.invoke('myapp.foo', { … })`.
  *

package/src/packs.ts

@@ -0,0 +1,174 @@
+/**
+ * Module-pack resolver — the single public extension seam of appwrap (CE/EE seam A2).
+ *
+ * A "pack" is a directory (local, or an npm package) that contributes capabilities to a wrapper build
+ * exactly like the built-in modules do: it exports `ModuleManifest[]` (the same contribution bags the
+ * built-ins use — permissions/entitlements/gradleDeps/nativeSrc/handler), plus the handler source and
+ * optional native source those manifests reference. The built-in modules are treated as *pack 0*; the
+ * config's `modulePacks` apply on top, in order.
+ *
+ * Merge policy (name-keyed):
+ *  - a pack module whose `name` is NEW → added;
+ *  - a pack module whose `name` already exists (from a different pack) → LAST-WINS, wholesale-shadowing
+ *    the earlier module (its whole manifest + handler + native source), with a provenance log line;
+ *  - a duplicate name WITHIN one pack → idempotent (later entry wins silently — a pack re-exporting its
+ *    own module is not an error).
+ *
+ * This one mechanism serves three audiences identically: a host layers its private packs, a consumer
+ * app vendors its own copy of a module, and the community ships plugins — none of them patch CE.
+ *
+ * PURE of CLI I/O: filesystem/npm resolution and pack import are injected ports (`resolvePack`/
+ * `importPack`), so the merge logic unit-tests against in-memory fakes. The CLI wires the real ports.
+ */
+import { existsSync } from 'node:fs';
+import { resolve } from 'node:path';
+import type { ModuleManifest } from '../../../runtime/app/shell/capabilities.manifest';
+
+/** Build-time context a pack's manifest may depend on (platform/env/CI). Manifest entries may be
+ * `(ctx) => ModuleManifest` so a pack can contribute different bags per platform/env without the
+ * downstream derivation (nativeReqs) knowing packs exist — thunks are resolved to plain values here. */
+export interface SyncContext {
+  /** The lane being generated. 'both' when a single sync stamps a cross-platform wrapper. */
+  platform: 'ios' | 'android' | 'both';
+  /** Resolved environment name (e.g. 'prod', 'lab', 'default'). */
+  env: string;
+  /** True in CI. */
+  ci: boolean;
+}
+
+/** A manifest entry as authored in a pack: a plain manifest, or a fn of the sync context. */
+export type ModuleEntry = ModuleManifest | ((ctx: SyncContext) => ModuleManifest);
+
+/** The shape a pack's manifest module must export (as `default` or named `pack`). `modules` may be a
+ * plain array, or a fn of the context (for a pack whose whole set is context-dependent). */
+export interface PackModule {
+  /** The manifest schema version this pack targets — checked against MANIFEST_SCHEMA_VERSION. */
+  manifestSchemaVersion: number;
+  /** The capabilities this pack contributes. */
+  modules: ModuleEntry[] | ((ctx: SyncContext) => ModuleEntry[]);
+}
+
+/** A merged module + where it came from (for provenance + to locate its handler/native source). */
+export interface ResolvedModule {
+  /** The module's contribution bags, with any context thunks resolved to plain values. */
+  manifest: ModuleManifest;
+  /** Provenance label: BUILTIN_SOURCE for a built-in, else the pack ref as written in `modulePacks`. */
+  source: string;
+  /** Absolute pack directory — the base for resolving this module's `handler.file` / `nativeSrc` /
+   * kit client. `null` for a built-in (those live under the runtime template, wired by the CLI). */
+  packDir: string | null;
+}
+
+/** Provenance label used for the built-in modules (pack 0). */
+export const BUILTIN_SOURCE = '(built-in)';
+
+export interface ResolvePacksOptions {
+  /** The built-in modules — pack 0. */
+  builtins: ModuleManifest[];
+  /** The manifest schema version the built-ins (and this CLI) speak. */
+  builtinSchemaVersion: number;
+  /** The config's `modulePacks` (local dirs or npm names), applied in order after the built-ins. */
+  packRefs: string[];
+  /** Build-time context passed to any manifest thunks. */
+  ctx: SyncContext;
+  /** Directory `modulePacks` refs resolve relative to (the app root). */
+  cwd: string;
+  /** Resolve a pack ref → absolute directory. Injected for tests; defaults to dir-or-npm resolution. */
+  resolvePack?: (ref: string, cwd: string) => string;
+  /** Import a pack's manifest module from its directory. Injected for tests; defaults to importing
+   * `<dir>/manifest.ts` and reading its `default` or named `pack` export. */
+  importPack?: (dir: string) => Promise<PackModule>;
+  /** Provenance sink. Defaults to console.log. */
+  log?: (msg: string) => void;
+}
+
+/** Default pack-ref resolution: an existing directory (relative to the app root) wins; otherwise the
+ * ref is treated as an npm package name and resolved via Bun's resolver (same path the plugin loader
+ * uses). Throws a clear error when a ref is neither. */
+export function defaultResolvePack(ref: string, cwd: string): string {
+  const asDir = resolve(cwd, ref);
+  if (existsSync(asDir)) return asDir;
+  try {
+    // Resolve the package's own manifest, then take its directory — the pack root.
+    const pkgJson = (Bun as unknown as { resolveSync(id: string, parent: string): string }).resolveSync(
+      `${ref}/package.json`,
+      cwd
+    );
+    return pkgJson.slice(0, pkgJson.length - '/package.json'.length);
+  } catch {
+    throw new Error(
+      `module pack "${ref}" not found — no such directory (relative to ${cwd}) and not resolvable as an npm package.`
+    );
+  }
+}
+
+/** Default pack import: load `<dir>/manifest.ts` and read its `default` or named `pack` export. */
+export async function defaultImportPack(dir: string): Promise<PackModule> {
+  const manifestPath = resolve(dir, 'manifest.ts');
+  if (!existsSync(manifestPath)) {
+    throw new Error(`module pack at "${dir}" is missing manifest.ts (must export the pack manifest).`);
+  }
+  const mod = (await import(manifestPath)) as { default?: PackModule; pack?: PackModule };
+  const pack = mod.default ?? mod.pack;
+  if (!pack || typeof pack.manifestSchemaVersion !== 'number' || !pack.modules) {
+    throw new Error(
+      `module pack at "${dir}" must export (default or \`pack\`) an object with { manifestSchemaVersion, modules }.`
+    );
+  }
+  return pack;
+}
+
+/** Resolve a manifest entry (plain or thunk) against the context to a plain manifest. */
+function resolveEntry(entry: ModuleEntry, ctx: SyncContext): ModuleManifest {
+  return typeof entry === 'function' ? entry(ctx) : entry;
+}
+
+/**
+ * Compose the built-in modules with the config's module packs into an ordered, name-keyed map. The
+ * insertion order is: built-ins first, then packs in `packRefs` order — and a shadow REPLACES in place
+ * (Map preserves the original key position), so a shadowing pack module keeps the built-in's slot. The
+ * returned map is what the generator derives the native requirements + handler barrel from.
+ */
+export async function resolveModulePacks(opts: ResolvePacksOptions): Promise<Map<string, ResolvedModule>> {
+  const {
+    builtins,
+    builtinSchemaVersion,
+    packRefs,
+    ctx,
+    cwd,
+    resolvePack = defaultResolvePack,
+    importPack = defaultImportPack,
+    log = console.log,
+  } = opts;
+
+  const map = new Map<string, ResolvedModule>();
+  for (const m of builtins) map.set(m.name, { manifest: m, source: BUILTIN_SOURCE, packDir: null });
+
+  for (const ref of packRefs) {
+    const dir = resolvePack(ref, cwd);
+    const pack = await importPack(dir);
+    if (pack.manifestSchemaVersion !== builtinSchemaVersion) {
+      throw new Error(
+        `module pack "${ref}" targets manifest schema v${pack.manifestSchemaVersion} but this appwrap ` +
+          `speaks v${builtinSchemaVersion}. Upgrade the pack or appwrap so the versions match.`
+      );
+    }
+    const entries = typeof pack.modules === 'function' ? pack.modules(ctx) : pack.modules;
+    const seenInThisPack = new Set<string>();
+    for (const entry of entries) {
+      const manifest = resolveEntry(entry, ctx);
+      const name = manifest.name;
+      const prior = map.get(name);
+      // A dup WITHIN this same pack is idempotent (later wins silently) — not a shadow event.
+      if (prior && prior.source !== ref && !seenInThisPack.has(name)) {
+        log(`  mod ← ${ref}  (${name} shadows ${prior.source})`);
+      } else if (!prior) {
+        log(`  mod ← ${ref}  (${name})`);
+      }
+      seenInThisPack.add(name);
+      map.set(name, { manifest, source: ref, packDir: dir });
+    }
+  }
+
+  return map;
+}

package/src/testing.ts

@@ -0,0 +1,173 @@
+/**
+ * Pack conformance validator — the public `@livx.cc/appwrap/testing` entry (CE/EE seam A8).
+ *
+ * A module pack (see packs.ts) is authored out-of-tree and staged into the shell at sync. Because a
+ * malformed pack fails LATE (mid-generate, on a device build), this gives pack authors a FAST, offline
+ * conformance check they can run in their own `bun test` — the same contract the CLI enforces, minus
+ * any NativeScript/CLI side effects, so it's import-safe as a library entry.
+ *
+ * It checks a pack DIRECTORY:
+ *   - manifest.ts exists and (default or named `pack`) exports { manifestSchemaVersion, modules }
+ *     (REUSES `defaultImportPack` from packs.ts — same loader the CLI uses);
+ *   - manifestSchemaVersion === MANIFEST_SCHEMA_VERSION (the version this appwrap speaks);
+ *   - every resolved module has a non-empty `name`, `group`, and a `capabilities` object;
+ *   - each module `handler.file` resolves to an existing file under the pack dir + `handler.fn` is set;
+ *   - each handler file imports ONLY sanctioned specifiers (no `../` escaping the pack, no bare deep
+ *     import into appwrap internals other than `@livx.cc/appwrap/runtime/app/shell/*`).
+ *
+ * ALL problems are collected (not fail-fast) so `errors[]` is a full report.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { extname, relative, resolve } from 'node:path';
+import { builtinModules } from 'node:module';
+import { defaultImportPack, type ModuleEntry, type SyncContext } from './packs';
+import { MANIFEST_SCHEMA_VERSION } from '../../../runtime/app/shell/capabilities.manifest';
+
+export interface ValidatePackResult {
+  ok: boolean;
+  errors: string[];
+}
+
+/** Node.js core module names (bare + `node:` forms). Allowed in a handler (they're externalized). */
+const NODE_BUILTIN_SET = new Set(builtinModules.flatMap((m) => [m, `node:${m}`]));
+
+/** The sanctioned shell-API specifier prefix a pack handler may deep-import (rewritten to relative on
+ * staging). Any OTHER `@livx.cc/appwrap/...` deep import reaches into CE internals → rejected. */
+const SANCTIONED_SHELL_PREFIX = '@livx.cc/appwrap/runtime/app/shell/';
+
+/** Map a handler file extension to the Bun.Transpiler loader for its dialect (mirrors cli.ts). */
+function loaderFor(file: string): 'ts' | 'tsx' | 'js' | 'jsx' {
+  const ext = extname(file).toLowerCase();
+  if (ext === '.tsx') return 'tsx';
+  if (ext === '.jsx') return 'jsx';
+  if (ext === '.js' || ext === '.mjs' || ext === '.cjs') return 'js';
+  return 'ts';
+}
+
+/** True if a bare specifier is an allowed non-relative import (shell API, @nativescript/core, node
+ * builtin). Anything else bare is treated as a normal npm dep the pack declares — NOT our concern here,
+ * so we only FLAG the one illegitimate class: a deep import into appwrap internals off the sanctioned
+ * path. */
+function bareImportError(spec: string): string | null {
+  // Sanctioned shell API — always fine.
+  if (spec === SANCTIONED_SHELL_PREFIX.slice(0, -1) || spec.startsWith(SANCTIONED_SHELL_PREFIX)) return null;
+  // Any OTHER appwrap deep import escapes the sanctioned seam into CE internals.
+  if (spec === '@livx.cc/appwrap' || spec.startsWith('@livx.cc/appwrap/')) {
+    return `imports appwrap internals via "${spec}" — a pack may only deep-import the sanctioned ` +
+      `"${SANCTIONED_SHELL_PREFIX}*" shell APIs.`;
+  }
+  // @nativescript/core (+ subpaths), node builtins, and any other npm dep are all acceptable.
+  return null;
+}
+
+/** Scan a handler file's imports; return an error string per illegal specifier (empty when clean).
+ * Uses Bun.Transpiler.scanImports (real import/require STATEMENTS only — never a string-literal match),
+ * the same primitive the CLI uses. */
+function scanHandlerImports(packDir: string, handlerFile: string): string[] {
+  const errors: string[] = [];
+  const src = readFileSync(handlerFile, 'utf8');
+  const rel = relative(packDir, handlerFile);
+  for (const { path: spec } of new Bun.Transpiler({ loader: loaderFor(handlerFile) }).scanImports(src)) {
+    if (spec.startsWith('.')) {
+      // Relative import — must resolve to somewhere INSIDE the pack dir.
+      const target = resolve(handlerFile, '..', spec);
+      const back = relative(packDir, target);
+      if (back.startsWith('..') || resolve(packDir, back) !== target) {
+        errors.push(`handler ${rel} imports "${spec}" which escapes the pack directory (${target}).`);
+      }
+      continue;
+    }
+    if (NODE_BUILTIN_SET.has(spec) || NODE_BUILTIN_SET.has(spec.replace(/^node:/, '').split('/')[0])) continue;
+    const bareErr = bareImportError(spec);
+    if (bareErr) errors.push(`handler ${rel} ${bareErr}`);
+  }
+  return errors;
+}
+
+/** A representative sync context for resolving context-dependent manifest thunks during validation. */
+const REPRESENTATIVE_CTX: SyncContext = { platform: 'both', env: 'default', ci: false };
+
+/**
+ * Validate that `dir` is a conformant module pack. Collects ALL errors; `ok` is `errors.length === 0`.
+ * Import-safe: no NativeScript globals, no CLI dispatch.
+ */
+export async function validatePack(dir: string): Promise<ValidatePackResult> {
+  const errors: string[] = [];
+  const packDir = resolve(dir);
+
+  // 1. Load the manifest via the SAME loader the CLI uses (throws a clear message if absent/malformed).
+  let pack: Awaited<ReturnType<typeof defaultImportPack>>;
+  try {
+    pack = await defaultImportPack(packDir);
+  } catch (e) {
+    errors.push((e as Error).message);
+    return { ok: false, errors };
+  }
+
+  // 2. Schema-version match.
+  if (pack.manifestSchemaVersion !== MANIFEST_SCHEMA_VERSION) {
+    errors.push(
+      `manifestSchemaVersion ${pack.manifestSchemaVersion} does not match this appwrap's ` +
+        `MANIFEST_SCHEMA_VERSION ${MANIFEST_SCHEMA_VERSION}.`
+    );
+  }
+
+  // 3. Resolve modules (may be a fn of the context) → plain manifests.
+  let entries: ModuleEntry[];
+  try {
+    entries = typeof pack.modules === 'function' ? pack.modules(REPRESENTATIVE_CTX) : pack.modules;
+  } catch (e) {
+    errors.push(`resolving \`modules\` threw: ${(e as Error).message}`);
+    return { ok: false, errors };
+  }
+  if (!Array.isArray(entries)) {
+    errors.push('`modules` must resolve to an array of module entries.');
+    return { ok: false, errors };
+  }
+
+  for (const [i, entry] of entries.entries()) {
+    let m;
+    try {
+      m = typeof entry === 'function' ? entry(REPRESENTATIVE_CTX) : entry;
+    } catch (e) {
+      errors.push(`module[${i}] entry thunk threw: ${(e as Error).message}`);
+      continue;
+    }
+    const label = m && m.name ? `module "${m.name}"` : `module[${i}]`;
+    if (!m || typeof m !== 'object') {
+      errors.push(`module[${i}] is not an object.`);
+      continue;
+    }
+    if (!m.name || typeof m.name !== 'string') errors.push(`${label} is missing a non-empty \`name\`.`);
+    if (!m.group || typeof m.group !== 'string') errors.push(`${label} is missing a non-empty \`group\`.`);
+    if (!m.capabilities || typeof m.capabilities !== 'object') {
+      errors.push(`${label} is missing a \`capabilities\` object.`);
+    }
+
+    // 4. Handler wiring (optional field, but if present must be complete + resolvable).
+    if (m.handler) {
+      if (!m.handler.fn || typeof m.handler.fn !== 'string') {
+        errors.push(`${label} handler is missing a non-empty \`fn\`.`);
+      }
+      if (!m.handler.file || typeof m.handler.file !== 'string') {
+        errors.push(`${label} handler is missing a \`file\`.`);
+      } else {
+        const handlerFile = resolve(packDir, m.handler.file);
+        if (!existsSync(handlerFile)) {
+          errors.push(`${label} handler.file "${m.handler.file}" does not exist (looked at ${handlerFile}).`);
+        } else {
+          // 5. Import legality scan.
+          errors.push(...scanHandlerImports(packDir, handlerFile));
+        }
+      }
+    }
+  }
+
+  return { ok: errors.length === 0, errors };
+}
+
+/** Convenience: throw with the joined errors if the pack is not conformant. */
+export async function assertValidPack(dir: string): Promise<void> {
+  const { ok, errors } = await validatePack(dir);
+  if (!ok) throw new Error(`invalid module pack at "${dir}":\n  - ${errors.join('\n  - ')}`);
+}

package/templates/module-pack/README.md

@@ -0,0 +1,44 @@
+# __MODULE_NAME__ — appwrap module pack
+
+A **module pack** is a self-contained directory that contributes native capabilities to an appwrap
+wrapper build, exactly like the built-in modules do — without patching appwrap itself.
+
+## Layout
+
+```
+__MODULE_NAME__/
+├── manifest.ts                 # default-exports { manifestSchemaVersion, modules } (a PackModule)
+├── handler.ts                  # exports register__MODULE_PASCAL__Handlers() — wires the bridge method(s)
+└── native-src/                 # optional module-owned native source (copied in ONLY when active)
+    └── __MODULE_NAME__/         # mirrors the App_Resources layout (App_Resources/iOS, /Android, …)
+```
+
+- **manifest.ts** declares the module: its `name`, `group`, `capabilities`, and the `handler`
+  ({ file, fn }) the shell calls at page load. Optionally `nativeSrc` (a `native-src/<name>/` dir),
+  `ios`/`android` blocks (permissions / entitlements / gradleDeps).
+- **handler.ts** imports shell APIs via the sanctioned `@livx.cc/appwrap/runtime/app/shell/<name>`
+  specifier (e.g. `bridge`). The generator rewrites these to relative `./` on staging. A handler may
+  also import `@nativescript/core`, node builtins, or pack-relative `./…` paths — but it must NOT reach
+  into appwrap internals via `../` escapes or other `@livx.cc/appwrap/…` deep imports.
+
+## Use it in an app
+
+In your app's `appwrap.config.ts`:
+
+```ts
+export default {
+  // …
+  modulePacks: ['./path/to/__MODULE_NAME__'],   // local dir, or an npm package name
+  modules: ['__MODULE_NAME__' /* , …other active modules */],
+};
+```
+
+Then `appwrap sync` stages the pack's handler + native source into the generated `native/` shell, and
+the capability is advertised to the web side in the handshake.
+
+## Validate
+
+```ts
+import { assertValidPack } from '@livx.cc/appwrap/testing';
+await assertValidPack(new URL('.', import.meta.url).pathname);
+```

package/templates/module-pack/handler.ts

@@ -0,0 +1,9 @@
+// Handler for the `__MODULE_NAME__` module. Imports the shell bridge via the sanctioned package
+// specifier (resolvable standalone — the npm package ships runtime/); the generator rewrites it to a
+// relative `./bridge` when staging this file beside the shell sources.
+import { bridge } from '@livx.cc/appwrap/runtime/app/shell/bridge';
+
+export function register__MODULE_PASCAL__Handlers(): void {
+  // One demo bridge method — call it from the web side via the kit's raw bridge.
+  bridge.register('__MODULE_NAME__.ping', () => ({ pong: true }));
+}

package/templates/module-pack/manifest.ts

@@ -0,0 +1,27 @@
+// Module pack manifest for `__MODULE_NAME__` — scaffolded by `appwrap create-module`.
+//
+// A pack contributes one or more capabilities to a wrapper build exactly like the built-in modules do.
+// This file default-exports { manifestSchemaVersion, modules } (a `PackModule`). The `handler` points
+// at ./handler.ts and names the register fn the shell barrel calls at page load. Reference this pack
+// from your app's appwrap.config.ts:
+//
+//   modulePacks: ['./path/to/__MODULE_NAME__'],   // this pack directory
+//   modules: ['__MODULE_NAME__', ...],            // activate the module by name
+//
+// No type import here on purpose, so the scaffold has zero unresolved imports out of the box. The shape
+// is validated by `@livx.cc/appwrap/testing`'s `validatePack` (and by the CLI at sync).
+const pack = {
+  manifestSchemaVersion: 1,
+  modules: [
+    {
+      name: '__MODULE_NAME__',
+      group: '__MODULE_NAME__',
+      capabilities: { __MODULE_NAME__: { ios: true, android: true } },
+      handler: { file: './handler.ts', fn: 'register__MODULE_PASCAL__Handlers' },
+      // Optional: module-owned native source mirroring the App_Resources layout, copied into native/
+      // ONLY when this module is active. Drop platform sources under ./native-src/__MODULE_NAME__/.
+      nativeSrc: '__MODULE_NAME__',
+    },
+  ],
+};
+export default pack;

package/runtime/app/shell/billing-offer.ts

@@ -1,54 +0,0 @@
-// Pure Play-Billing offer selection — NO NativeScript/native deps, so it is unit-testable in
-// isolation from com.android.billingclient.* objects. handlers-billing.ts adapts native
-// SubscriptionOfferDetails into these plain shapes and delegates the CHOICE here.
-//
-// WHY this exists (money/product-critical): getSubscriptionOfferDetails() returns EVERY offer the
-// user is eligible for, in NO guaranteed order. A trial-eligible (first-time) user's list carries
-// BOTH the base-plan offer (offerId==null, a single paid phase) AND a separate free-trial offer
-// (tag "freetrial", two phases: first priceAmountMicros==0, then the base price). A lapsed /
-// ineligible user gets ONLY the base-plan offer. Blindly taking offers.get(0) can drop the
-// MANDATORY free trial. We must pick the trial offer WHEN PRESENT, else the base plan.
-
-/** One pricing phase of an offer (only the fields the selection/pricing logic needs). */
-export interface OfferPhase {
-  /** Micros of `currency`; 0 marks a free-trial phase. */
-  priceAmountMicros: number;
-  /** ISO-8601 billing period, e.g. "P1W", "P1M". */
-  billingPeriod?: string;
-}
-
-/** A single subscription offer, flattened from Play's SubscriptionOfferDetails. */
-export interface OfferCandidate {
-  /** null/"" for the base-plan offer; a non-empty id for a promotional offer (trial). */
-  offerId: string | null;
-  phases: OfferPhase[];
-}
-
-/** True when the offer contains a zero-price (free-trial) phase. */
-export function hasFreeTrialPhase(offer: OfferCandidate): boolean {
-  return offer.phases.some((p) => p.priceAmountMicros === 0);
-}
-
-/**
- * Select the offer to purchase / price from. Prefers the free-trial offer (a zero-price phase) when
- * present, so a trial-eligible user actually gets the trial; otherwise falls back to the base-plan
- * offer (offerId==null), else the first offer. Returns null for an empty list.
- */
-export function selectSubscriptionOffer<T extends OfferCandidate>(offers: readonly T[]): T | null {
-  if (!offers || offers.length === 0) return null;
-  const trial = offers.find(hasFreeTrialPhase);
-  if (trial) return trial;
-  const base = offers.find((o) => o.offerId == null || o.offerId === '');
-  return base ?? offers[0];
-}
-
-/** The recurring paid phase to display (first phase with a price > 0), or the last phase as fallback. */
-export function recurringPhase(offer: OfferCandidate): OfferPhase | undefined {
-  const paid = offer.phases.find((p) => p.priceAmountMicros > 0);
-  return paid ?? offer.phases[offer.phases.length - 1];
-}
-
-/** The intro/free-trial phase (first zero-price phase), if any. */
-export function introPhase(offer: OfferCandidate): OfferPhase | undefined {
-  return offer.phases.find((p) => p.priceAmountMicros === 0);
-}