@livx.cc/native-kit 0.41.0 → 0.43.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@livx.cc/native-kit",
-  "version": "0.41.0",
-  "description": "Isomorphic native-capabilities kit for PWAs — same API in browser and in an appwrap native shell. Zero dependencies.",
+  "version": "0.43.0",
+  "description": "Isomorphic native-capabilities kit for PWAs \u2014 same API in browser and in an appwrap native shell. Zero dependencies.",
   "license": "MIT",
   "author": "Elya Livshitz",
   "homepage": "https://github.com/Livshitz/appwrap#readme",

package/src/core/NativeKit.ts

@@ -1,10 +1,11 @@
 import { AppwrapAdapter } from './appwrap-adapter';
 import { WebAdapter } from './web-adapter';
+import { ModuleRegistry } from './module-registry';
+import type { KitModuleRegistry } from './module-registry';
 import { Capability, Handshake, InvokeOptions, KIT_PROTOCOL, KitError, NativeKitAdapter, Platform, Unsubscribe } from './types';
 import { AppModule } from '../modules/app';
 import { AppleSignInModule } from '../modules/appleSignIn';
 import { BackgroundTaskModule } from '../modules/backgroundTask';
-import { BillingModule } from '../modules/billing/billing';
 import { BiometricsModule } from '../modules/biometrics';
 import { BrowserModule } from '../modules/browser';
 import { CalendarModule } from '../modules/calendar';
@@ -15,7 +16,6 @@ import { FsModule } from '../modules/fs';
 import { GeoModule } from '../modules/geo';
 import { HeadingModule } from '../modules/heading';
 import { HapticsModule } from '../modules/haptics';
-import { HealthModule } from '../modules/health';
 import { KeyboardModule } from '../modules/keyboard';
 import { LifecycleModule } from '../modules/lifecycle';
 import { MediaModule } from '../modules/media';
@@ -35,7 +35,6 @@ import { ToastModule } from '../modules/toast';
 import { TrackingModule } from '../modules/tracking';
 import { UiModule } from '../modules/ui';
 import { UpdatesModule } from '../modules/updates';
-import { WidgetModule } from '../modules/widget';
 
 export class NativeKitOptions {
   /** Priority order; first adapter whose detect() passes wins. */
@@ -43,22 +42,6 @@ export class NativeKitOptions {
   handshakeTimeoutMs = 3000;
 }
 
-/**
- * Method domains the web fallback must NEVER be retried against — deliberately NOT an option:
- * this is a policy invariant, not a knob a consumer should be able to switch off.
- *
- * `billing.`: purchases inside a native shell belong to the device store, full stop.
- *   - {@link BillingModule.capability} promises to "never silently fall back to web inside a
- *     native shell" — the generic retry here would bypass that contract behind its back.
- *   - The WebAdapter's only billing behaviour is a hardcoded throw ("use a web checkout"), so
- *     retrying billing can't succeed — it can only REPLACE the shell's real, actionable error
- *     (e.g. UNSUPPORTED "Purchases are disabled on this device" from a Screen-Time/MDM-restricted
- *     iPhone) with a false one claiming the user is on the web. Zero upside, only downside.
- *   - Steering an iOS user to an external checkout is App Store Guideline 3.1.1 territory. Today
- *     that string only reaches a `catch`; this keeps it from ever reaching a paywall.
- */
-const WEB_FALLBACK_EXCLUDED_DOMAINS = ['billing.'];
-
 /**
  * Flat, vendor-neutral analytics bag — spread straight into your analytics provider's
  * super-properties (e.g. `mixpanel.register(await kit.context())`). Native-only fields
@@ -112,7 +95,6 @@ export class NativeKit {
   public readonly lifecycle = new LifecycleModule(this);
   public readonly reviews = new ReviewsModule(this);
   public readonly motion = new MotionModule(this);
-  public readonly health = new HealthModule(this);
   public readonly media = new MediaModule(this);
   public readonly contacts = new ContactsModule(this);
   public readonly scanner = new ScannerModule(this);
@@ -121,12 +103,18 @@ export class NativeKit {
   public readonly app = new AppModule(this);
   public readonly browser = new BrowserModule(this);
   public readonly oauth = new OAuthModule(this);
-  public readonly billing = new BillingModule(this);
   public readonly updates = new UpdatesModule(this);
   public readonly backgroundTask = new BackgroundTaskModule(this);
   public readonly tracking = new TrackingModule(this);
   public readonly appleSignIn = new AppleSignInModule(this);
-  public readonly widget = new WidgetModule(this);
+
+  /**
+   * Additive, string-keyed registry mirroring the eager fields above (SAME instances) — a new
+   * capability-access path out-of-repo module packs register into (e.g. the billing/health/widget
+   * EE packs call `kit.modules.registerModule(...)`). For core modules `kit.getModule('haptics')
+   * === kit.haptics`. Fails loud on miss.
+   */
+  public readonly modules = new ModuleRegistry();
 
   public handshakeInfo: Handshake | null = null;
   public options: NativeKitOptions;
@@ -137,11 +125,48 @@ export class NativeKit {
    * for it. Capability keys the shell reports as 'none'/absent surface as 'web' when the
    * fallback can fulfil them. */
   private webFallback: NativeKitAdapter | null = null;
+  /**
+   * Method-name prefixes the web fallback must NEVER be retried against. Empty by default;
+   * a module pack declares its own policy via {@link excludeWebFallback} at registration.
+   * e.g. the billing pack excludes `billing.` — purchases inside a native shell belong to the
+   * device store, and retrying them on the WebAdapter would replace the shell's real, actionable
+   * error with a false "use a web checkout" one (App Store Guideline 3.1.1 territory).
+   */
+  private webFallbackExcludedDomains = new Set<string>();
   private readyPromise: Promise<Handshake> | null = null;
   private contextPromise: Promise<KitContext> | null = null;
 
   constructor(options?: Partial<NativeKitOptions>) {
     this.options = { ...new NativeKitOptions(), ...options };
+    // Mirror the eager CORE fields into the string-keyed registry (same instances, no behaviour
+    // change). Typed as a plain string map — not `Record<keyof KitModuleRegistry, unknown>` — because
+    // out-of-repo packs augment KitModuleRegistry with keys CE never mounts (billing/health/widget);
+    // those are registered by the pack's register<Name>Kit(), not here.
+    const eager: Record<string, unknown> = {
+      haptics: this.haptics, share: this.share, screen: this.screen, keyboard: this.keyboard,
+      storage: this.storage, fs: this.fs, toast: this.toast, ui: this.ui, device: this.device,
+      clipboard: this.clipboard, notifications: this.notifications, push: this.push,
+      biometrics: this.biometrics, geo: this.geo, heading: this.heading, photos: this.photos,
+      network: this.network, lifecycle: this.lifecycle, reviews: this.reviews, motion: this.motion,
+      media: this.media, contacts: this.contacts, scanner: this.scanner,
+      speech: this.speech, calendar: this.calendar, app: this.app, browser: this.browser,
+      oauth: this.oauth, updates: this.updates,
+      backgroundTask: this.backgroundTask, tracking: this.tracking, appleSignIn: this.appleSignIn,
+    };
+    for (const [name, inst] of Object.entries(eager)) this.modules.registerModule(name, inst);
+  }
+
+  /** Typed, string-keyed module lookup — delegates to {@link ModuleRegistry.getModule}.
+   * Throws (listing mounted modules) if the name isn't registered. */
+  getModule<K extends keyof KitModuleRegistry>(name: K): KitModuleRegistry[K] {
+    return this.modules.getModule(name);
+  }
+
+  /** Declare a method-name prefix the web fallback must never retry against (see
+   * {@link webFallbackExcludedDomains}). Module packs call this at registration to own their
+   * own policy — e.g. the billing pack excludes `billing.`. Idempotent. */
+  excludeWebFallback(prefix: string): void {
+    this.webFallbackExcludedDomains.add(prefix);
   }
 
   /** Resolve the environment and perform the handshake. Idempotent. */
@@ -285,7 +310,7 @@ export class NativeKit {
         this.webFallback &&
         e instanceof KitError &&
         e.code === 'UNSUPPORTED' &&
-        !WEB_FALLBACK_EXCLUDED_DOMAINS.some((d) => method.startsWith(d))
+        ![...this.webFallbackExcludedDomains].some((d) => method.startsWith(d))
       ) {
         return this.webFallback.invoke<T>(method, params, opts);
       }
@@ -317,5 +342,44 @@ export class NativeKit {
   }
 }
 
+/** Typed registry map — augment via declaration merging so `getModule(name)` returns the
+ * strongly-typed module. Out-of-repo packs augment this same interface to add their own. */
+declare module './module-registry' {
+  interface KitModuleRegistry {
+    haptics: HapticsModule;
+    share: ShareModule;
+    screen: ScreenModule;
+    keyboard: KeyboardModule;
+    storage: StorageModule;
+    fs: FsModule;
+    toast: ToastModule;
+    ui: UiModule;
+    device: DeviceModule;
+    clipboard: ClipboardModule;
+    notifications: NotificationsModule;
+    push: PushModule;
+    biometrics: BiometricsModule;
+    geo: GeoModule;
+    heading: HeadingModule;
+    photos: PhotosModule;
+    network: NetworkModule;
+    lifecycle: LifecycleModule;
+    reviews: ReviewsModule;
+    motion: MotionModule;
+    media: MediaModule;
+    contacts: ContactsModule;
+    scanner: ScannerModule;
+    speech: SpeechModule;
+    calendar: CalendarModule;
+    app: AppModule;
+    browser: BrowserModule;
+    oauth: OAuthModule;
+    updates: UpdatesModule;
+    backgroundTask: BackgroundTaskModule;
+    tracking: TrackingModule;
+    appleSignIn: AppleSignInModule;
+  }
+}
+
 /** Shared default instance — `import { kit } from '@livx.cc/native-kit'`. */
 export const kit = new NativeKit();

package/src/core/module-registry.ts

@@ -0,0 +1,76 @@
+/**
+ * Tiny, dependency-free, string-keyed registry for kit modules.
+ *
+ * Deliberately in-house (no di container): native-kit is bundled into consumer PWAs and
+ * must stay ZERO-dependency. Keys are explicit strings — never constructor/parameter names —
+ * because minification renames identifiers and would silently break name-based lookup.
+ *
+ * A future step lets out-of-repo "module packs" register their own client here; today it runs
+ * in parallel with the eager `NativeKit` fields (same instances, no behaviour change).
+ *
+ * Typed access is via TypeScript declaration merging: augment {@link KitModuleRegistry} with
+ * `name -> ModuleType` and {@link ModuleRegistry.getModule} returns the strongly-typed module.
+ */
+
+/** Augment via `declare module` to map a module name to its type (see NativeKit.ts). */
+// eslint-disable-next-line @typescript-eslint/no-empty-interface
+export interface KitModuleRegistry {}
+
+export type ModuleFactory<T = unknown> = () => T;
+
+export class ModuleRegistry {
+  private instances = new Map<string, unknown>();
+  private factories = new Map<string, ModuleFactory>();
+
+  /** Register a module by string name — either a ready instance or a lazy factory
+   * (called at most once, then memoized). Re-registering replaces the prior entry. */
+  registerModule(name: string, instanceOrFactory: unknown | ModuleFactory): void {
+    if (typeof instanceOrFactory === 'function') {
+      this.factories.set(name, instanceOrFactory as ModuleFactory);
+      this.instances.delete(name);
+    } else {
+      this.instances.set(name, instanceOrFactory);
+      this.factories.delete(name);
+    }
+  }
+
+  hasModule(name: string): boolean {
+    return this.instances.has(name) || this.factories.has(name);
+  }
+
+  /** Currently-mounted module names, sorted. */
+  moduleNames(): string[] {
+    return [...new Set([...this.instances.keys(), ...this.factories.keys()])].sort();
+  }
+
+  /**
+   * Typed, string-keyed lookup. STRICT by design: the ONLY public signature is keyed to
+   * `keyof KitModuleRegistry`, so `getModule('billing')` is a COMPILE ERROR unless the billing pack's
+   * kit client has been imported (its `declare module` augments the registry) — you get compile-time
+   * verification + autocomplete of exactly the modules you've wired, never a runtime surprise. For a
+   * genuinely dynamic name, use {@link getModuleUnsafe}.
+   */
+  getModule<K extends keyof KitModuleRegistry>(name: K): KitModuleRegistry[K];
+  getModule(name: string): unknown {
+    if (this.instances.has(name)) return this.instances.get(name);
+    const factory = this.factories.get(name);
+    if (factory) {
+      const inst = factory(); // memoize once, then drop the factory
+      this.instances.set(name, inst);
+      this.factories.delete(name);
+      return inst;
+    }
+    // Fail LOUD: a missing module must throw at the call site, never queue/return undefined.
+    throw new Error(
+      `[native-kit] module '${name}' is not registered. ` +
+        `Mounted modules: [${this.moduleNames().join(', ')}]. ` +
+        `Did you list its pack in modulePacks?`
+    );
+  }
+
+  /** Escape hatch for a genuinely DYNAMIC module name (not a compile-time literal) — bypasses the
+   * keyed check. Prefer {@link getModule}; reach for this only when the name isn't statically known. */
+  getModuleUnsafe<T = unknown>(name: string): T {
+    return (this.getModule as (n: string) => unknown)(name) as T;
+  }
+}

package/src/index.ts

@@ -1,5 +1,7 @@
 export { NativeKit, NativeKitOptions, kit } from './core/NativeKit';
 export type { KitContext } from './core/NativeKit';
+export { ModuleRegistry } from './core/module-registry';
+export type { KitModuleRegistry, ModuleFactory } from './core/module-registry';
 export type { AppEnvironment, AppShortcut, InstallSource } from './modules/app';
 export { AppwrapAdapter } from './core/appwrap-adapter';
 export { WebAdapter } from './core/web-adapter';
@@ -43,7 +45,6 @@ export type { CalendarEventOptions } from './modules/calendar';
 export type { BrowserOptions } from './modules/browser';
 export type { OAuthAuthorizeParams, OAuthResult } from './modules/oauth';
 export type { TrackingStatus } from './modules/tracking';
-export type { WidgetEntry, WidgetPayload, WidgetStat, WidgetPublishResult } from './modules/widget';
 export type {
   AppleSignInName,
   AppleSignInParams,
@@ -51,20 +52,5 @@ export type {
   AppleSignInCancelled,
 } from './modules/appleSignIn';
 export { isAppleSignInResult } from './modules/appleSignIn';
-export { ClientTrustedValidator, HttpValidator, HttpValidatorOptions } from './modules/billing/validators';
-export { HttpBillingProvider, HttpBillingProviderOptions } from './modules/billing/providers';
-export type { HeaderProvider } from './modules/billing/http';
-export { HealthModule } from './modules/health';
 export { BackgroundTaskModule } from './modules/backgroundTask';
 export type { BackgroundTaskHandler, ScheduleBackgroundTaskOptions } from './modules/backgroundTask';
-export type {
-  BillingProvider,
-  BillingValidator,
-  Entitlement,
-  Product,
-  ProductType,
-  PurchaseReceipt,
-  PurchaseResult,
-  ReceiptEntitlements,
-  ReceiptOutcome,
-} from './modules/billing/types';

package/src/modules/billing/billing.ts

@@ -1,176 +0,0 @@
-import type { NativeKit } from '../../core/NativeKit';
-import { KitError, type Capability, type Unsubscribe } from '../../core/types';
-import { ClientTrustedValidator } from './validators';
-import type {
-  BillingProvider,
-  BillingValidator,
-  Entitlement,
-  Product,
-  PurchaseReceipt,
-  PurchaseResult,
-  ReceiptEntitlements,
-  ReceiptOutcome,
-} from './types';
-
-/**
- * In-app purchases & subscriptions — ONE API across web and native.
- *
- * - On a native shell the kit drives the device store (iOS StoreKit 1, Android Play
- *   Billing) and a {@link BillingValidator} confirms the receipt (server-of-record).
- * - On the web there is no native store, so the app plugs in a {@link BillingProvider}
- *   (Stripe / Paddle / custom backend) and the SAME `kit.billing.*` calls dispatch to it.
- *
- * Wire both once via {@link configure}; the module picks the right path per platform.
- */
-export class BillingModule {
-  private validator: BillingValidator;
-  private webProvider?: BillingProvider;
-
-  constructor(private kit: NativeKit) {
-    this.validator = new ClientTrustedValidator(() => this.nativeEntitlements());
-  }
-
-  /** 'native' on a store-capable shell · 'web' when a web provider is wired · else 'none'. */
-  get capability(): Capability {
-    if (this.kit.is.native) return this.kit.capability('billing'); // native store (or 'none' if parked)
-    return this.webProvider ? 'web' : 'none'; // never silently fall back to web inside a native shell
-  }
-
-  /**
-   * @param opts.validator   server-of-record for entitlements (native receipt check; shared)
-   * @param opts.webProvider purchase mechanism on the web (Stripe/Paddle/custom)
-   */
-  configure(opts: { validator?: BillingValidator; webProvider?: BillingProvider }): void {
-    if (opts.validator) this.validator = opts.validator;
-    if (opts.webProvider) this.webProvider = opts.webProvider;
-  }
-
-  /** On the web the purchase mechanism is the provider; require one with an actionable error. */
-  private webProviderOrThrow(): BillingProvider {
-    if (!this.webProvider) {
-      throw new KitError(
-        'UNSUPPORTED',
-        'No web billing provider configured. On the web, wire one: ' +
-          "kit.billing.configure({ webProvider: new HttpBillingProvider({ baseUrl: '/api/billing' }) })"
-      );
-    }
-    return this.webProvider;
-  }
-
-  /** Localized product catalog — from the store (native) or the provider (web). */
-  async products(ids: string[]): Promise<Product[]> {
-    await this.kit.ready(); // routing depends on the resolved adapter — never decide pre-handshake
-    if (this.kit.is.web) return this.webProviderOrThrow().products(ids);
-    return this.kit.invoke('billing.products', { ids });
-  }
-
-  /** Buy a product. Native store flow + receipt validation, or web checkout via the provider. */
-  async purchase(productId: string): Promise<PurchaseResult> {
-    await this.kit.ready();
-    if (this.kit.is.web) {
-      const entitlements = await this.webProviderOrThrow().purchase(productId);
-      return { receipt: { platform: 'web', productId, raw: null }, entitlements };
-    }
-    const receipt = await this.kit.invoke<PurchaseReceipt>('billing.purchase', { productId }, { timeoutMs: 120_000 });
-    return { receipt, entitlements: await this.validator.validate(receipt) };
-  }
-
-  /** Restore/re-sync prior purchases. */
-  async restore(): Promise<Entitlement[]> {
-    await this.kit.ready();
-    if (this.kit.is.web) {
-      const p = this.webProviderOrThrow();
-      return (p.restore ?? p.entitlements).call(p); // web has no store "restore" → re-read entitlements
-    }
-    const receipts = await this.kit.invoke<PurchaseReceipt[]>('billing.restore', undefined, { timeoutMs: 60_000 });
-    const out: Entitlement[] = [];
-    for (const r of receipts) out.push(...(await this.validator.validate(r)));
-    return out;
-  }
-
-  /**
-   * Confirm entitlements **silently** from the on-device App Store receipt — no Apple-ID
-   * prompt and no `restore()` round-trip (unlike {@link restore}/{@link entitlements} on
-   * StoreKit 1). For an in-place update of the SAME bundle id the receipt already holds the
-   * user's active/grandfathered subscriptions, so this is the zero-user-action path for
-   * migrating existing subscribers into a new build.
-   *
-   * Native iOS only, and only meaningful with a **server validator** (the bare receipt has no
-   * product id — a client-trusted validator can't interpret it). Resolves `[]` on the web,
-   * on Android (no StoreKit-1 receipt), or when no receipt is present (e.g. a dev build).
-   *
-   * The `[]` is AMBIGUOUS by design-history: it means both "no entitlements" and "never even
-   * asked". Use {@link receiptEntitlements} to tell those apart.
-   */
-  async entitlementsFromReceipt(): Promise<Entitlement[]> {
-    return (await this.receiptEntitlements()).entitlements;
-  }
-
-  /**
-   * {@link entitlementsFromReceipt} plus **why** — the same check, but the three
-   * didn't-even-ask paths are reported instead of being flattened into `[]`. See
-   * {@link ReceiptOutcome}: only `'validated'` makes an empty list a real answer.
-   *
-   * A validator that errors (network, Apple status 21004, …) REJECTS rather than
-   * reporting an outcome — a failed check is not a verdict about the user.
-   */
-  async receiptEntitlements(): Promise<ReceiptEntitlements> {
-    await this.kit.ready();
-    if (this.capability !== 'native') return { entitlements: [], outcome: 'not-native' }; // web, or a shell with no native store handler (Android IS native now, but has no on-disk receipt → yields 'no-receipt' below)
-    if (this.validator instanceof ClientTrustedValidator) return { entitlements: [], outcome: 'no-validator' }; // bare receipt has no product id → would grant a bogus active entitlement; needs a server validator
-    const receipt = await this.kit.invoke<PurchaseReceipt>('billing.appReceipt');
-    if (!receipt?.appReceipt) return { entitlements: [], outcome: 'no-receipt' };
-    return { entitlements: await this.validator.validate(receipt), outcome: 'validated' }; // server-of-record turns the receipt into entitlements
-  }
-
-  /** Current entitlements from the configured server-of-record (web provider or validator). */
-  async entitlements(): Promise<Entitlement[]> {
-    await this.kit.ready();
-    if (this.kit.is.web) return this.webProviderOrThrow().entitlements();
-    return this.validator.entitlements();
-  }
-
-  /** Subscription management — OS surface (App Store / Play) or the provider's portal (Stripe). */
-  async manageSubscriptions(): Promise<void> {
-    await this.kit.ready();
-    if (this.kit.is.web) {
-      const p = this.webProviderOrThrow();
-      if (!p.manageSubscriptions) throw new KitError('UNSUPPORTED', 'This web billing provider has no subscription-management portal');
-      return p.manageSubscriptions();
-    }
-    return this.kit.invoke('billing.manageSubscriptions');
-  }
-
-  /**
-   * The in-app / native subscription-management surface. On iOS 15+ this presents StoreKit 2's
-   * **in-app** sheet (`AppStore.showManageSubscriptions(in:)`) — unlike {@link manageSubscriptions}
-   * (App Store account page, StoreKit 1), it stays inside the app AND shows sandbox / TestFlight
-   * subscriptions, so it's the path to verify/cancel a sub during testing. On Android (native billing
-   * enabled) there is no in-app sheet, so this dispatches to the same Play subscriptions deep link as
-   * {@link manageSubscriptions} (the native handler maps both). Opt-in on iOS: the default
-   * `manageSubscriptions()` deep-link is unchanged; call this explicitly to use the sheet.
-   *
-   * Throws `UNSUPPORTED` only on the web (no native store), and `NATIVE_ERROR` on iOS <15 / no
-   * presentable scene / a StoreKit error. Resolves once the user dismisses the sheet (iOS) or the
-   * deep link is opened (Android).
-   */
-  async showManageSubscriptionsSheet(): Promise<void> {
-    await this.kit.ready();
-    if (this.capability !== 'native') {
-      throw new KitError('UNSUPPORTED', 'The subscriptions sheet needs a native store. On the web, use manageSubscriptions() (your web billing provider portal).');
-    }
-    // Dismiss-bound: resolves only when the USER closes the sheet (no meaningful deadline).
-    // A watchdog could only false-timeout mid-sheet → spurious fallback, so disable it.
-    return this.kit.invoke('billing.manageSubscriptionsSheet', undefined, { timeoutMs: 'none' });
-  }
-
-  /** Out-of-band transactions (renewals, Ask-to-Buy, cross-device). Native streams only. */
-  onTransaction(cb: (receipt: PurchaseReceipt) => void): Unsubscribe {
-    return this.kit.on('billing.transaction', (p) => cb(p as PurchaseReceipt));
-  }
-
-  /** Raw device entitlements — StoreKit `currentEntitlements` / Play `queryPurchases`. */
-  private nativeEntitlements(): Promise<Entitlement[]> {
-    return this.kit.invoke('billing.entitlements');
-  }
-}

package/src/modules/billing/http.ts

@@ -1,28 +0,0 @@
-/** Shared HTTP helper for the backend-driven billing strategies (validator + web provider). */
-
-export type HeaderProvider =
-  | Record<string, string>
-  | (() => Record<string, string> | Promise<Record<string, string>>);
-
-export interface HttpJsonOptions {
-  url: string;
-  method: 'GET' | 'POST';
-  body?: unknown;
-  headers?: HeaderProvider;
-  /** Injected for tests / non-DOM runtimes. Defaults to global `fetch`. */
-  fetch?: typeof fetch;
-}
-
-/** POST/GET JSON, throwing on non-2xx. Keeps validators + providers DRY. */
-export async function httpJson(opts: HttpJsonOptions): Promise<unknown> {
-  const f = opts.fetch ?? globalThis.fetch;
-  if (!f) throw new Error('billing: no fetch available — pass one via options.fetch');
-  const h = typeof opts.headers === 'function' ? await opts.headers() : opts.headers;
-  const res = await f(opts.url, {
-    method: opts.method,
-    headers: { 'content-type': 'application/json', ...(h ?? {}) },
-    body: opts.method === 'POST' ? JSON.stringify(opts.body ?? {}) : undefined,
-  });
-  if (!res.ok) throw new Error(`billing: ${opts.method} ${opts.url} → ${res.status}`);
-  return res.json();
-}

package/src/modules/billing/providers.ts

@@ -1,72 +0,0 @@
-import { httpJson, type HeaderProvider } from './http';
-import type { BillingProvider, Entitlement, Product } from './types';
-
-export class HttpBillingProviderOptions {
-  /** Backend base URL exposing /products, /checkout, /entitlements, /portal. */
-  baseUrl = '';
-  /** Static headers or a thunk (e.g. a fresh session/bearer token). */
-  headers?: HeaderProvider;
-  /** Injected for tests / non-DOM runtimes. Defaults to global `fetch`. */
-  fetch?: typeof fetch;
-  /** How to send the user to a hosted checkout / portal URL. Defaults to a same-tab
-   *  navigation — override to open a tab, an in-app browser, etc. */
-  redirect: (url: string) => void = (url) => {
-    if (typeof window !== 'undefined') window.location.assign(url);
-  };
-  mapProducts: (json: unknown) => Product[] = (j) =>
-    ((j as { products?: Product[] } | null)?.products ?? (j as Product[] | null) ?? []);
-  mapEntitlements: (json: unknown) => Entitlement[] = (j) =>
-    ((j as { entitlements?: Entitlement[] } | null)?.entitlements ?? (j as Entitlement[] | null) ?? []);
-}
-
-/**
- * Web checkout via your backend — the symmetric counterpart to the native store.
- * `purchase()` POSTs to `/checkout`; if the backend returns a hosted-checkout `url`
- * (Stripe Checkout Session, Paddle, LemonSqueezy…), it redirects and entitlements
- * surface on the redirect back; if the backend returns `entitlements` inline, it
- * resolves immediately. One config covers any "backend mints a checkout URL" provider.
- * HTTP over SDK by design — no Stripe.js / vendor packages in the kit.
- */
-export class HttpBillingProvider implements BillingProvider {
-  public options: HttpBillingProviderOptions;
-  constructor(options?: Partial<HttpBillingProviderOptions>) {
-    this.options = { ...new HttpBillingProviderOptions(), ...options };
-    if (!this.options.baseUrl) throw new Error('HttpBillingProvider: baseUrl is required');
-  }
-
-  async products(ids: string[]): Promise<Product[]> {
-    const url = `${this.base()}/products?ids=${encodeURIComponent(ids.join(','))}`;
-    return this.options.mapProducts(await httpJson({ ...this.req(), url, method: 'GET' }));
-  }
-
-  async purchase(productId: string): Promise<Entitlement[]> {
-    const json = await httpJson({ ...this.req(), url: `${this.base()}/checkout`, method: 'POST', body: { productId } });
-    const url = (json as { url?: unknown } | null)?.url;
-    if (url) {
-      this.options.redirect(String(url)); // hosted checkout — page navigates away
-      return []; // entitlements arrive via entitlements() after redirect-back
-    }
-    return this.options.mapEntitlements(json); // backend completed inline
-  }
-
-  async entitlements(): Promise<Entitlement[]> {
-    return this.options.mapEntitlements(await httpJson({ ...this.req(), url: `${this.base()}/entitlements`, method: 'GET' }));
-  }
-
-  restore(): Promise<Entitlement[]> {
-    return this.entitlements(); // web has no store "restore" — re-read the server-of-record
-  }
-
-  async manageSubscriptions(): Promise<void> {
-    const json = await httpJson({ ...this.req(), url: `${this.base()}/portal`, method: 'POST', body: {} });
-    const url = (json as { url?: unknown } | null)?.url;
-    if (url) this.options.redirect(String(url)); // Stripe Billing Portal, etc.
-  }
-
-  private base() {
-    return this.options.baseUrl.replace(/\/$/, '');
-  }
-  private req() {
-    return { headers: this.options.headers, fetch: this.options.fetch };
-  }
-}

package/src/modules/billing/types.ts

@@ -1,135 +0,0 @@
-/** Billing / IAP contract — platform-neutral shapes shared by the module,
- *  the native handlers, and any pluggable validator (RevenueCat / IAPHUB / custom). */
-
-export type ProductType =
-  | 'consumable'
-  | 'nonConsumable'
-  | 'autoRenewable'
-  | 'nonRenewable'
-  | 'unknown';
-
-/** An introductory / free-trial phase that precedes the standard subscription price. */
-export interface IntroOffer {
-  /** Price during the intro phase in `currency`; 0 for a free trial. */
-  price: number;
-  /** Localized formatted intro price, e.g. "Free" / "$0.99" — show this to users. */
-  displayPrice: string;
-  /** ISO-8601 duration of the intro phase, e.g. "P1W", "P7D". */
-  period?: string;
-  /** True when `price === 0` (a free trial). */
-  isFreeTrial: boolean;
-}
-
-/** A purchasable product as the store describes it (localized). */
-export interface Product {
-  id: string;
-  title: string;
-  description: string;
-  /** Numeric price in `currency`, for math/sorting. */
-  price: number;
-  /** Localized formatted price, e.g. "$4.99" — show this to users. */
-  displayPrice: string;
-  currency: string;
-  type: ProductType;
-  /** ISO-8601 duration for auto-renewables, e.g. "P1M", "P1Y". */
-  subscriptionPeriod?: string;
-  /**
-   * Introductory / free-trial offer the CURRENT user is eligible for, when the store reports one.
-   * Populated on Android (Play Billing SubscriptionOfferDetails' zero-price phase). Not yet populated
-   * on iOS — StoreKit 1's `introductoryPrice` is unread by the current iOS mapper (parity follow-up);
-   * the trial still APPLIES at checkout because StoreKit/Play show trial terms in their own sheet.
-   */
-  introOffer?: IntroOffer;
-}
-
-/** A normalized entitlement — "this user owns/subscribes to X". */
-export interface Entitlement {
-  productId: string;
-  active: boolean;
-  /** Epoch ms; subscriptions only. */
-  expiresAt?: number;
-  /** Whether an auto-renewable will renew at period end. */
-  willRenew?: boolean;
-  /** Epoch ms of the original purchase. */
-  purchasedAt?: number;
-}
-
-/** The raw proof of a purchase, handed to the validator. Platform-specific fields
- *  are optional so one shape serves both stores AND a web checkout. */
-export interface PurchaseReceipt {
-  platform: 'ios' | 'android' | 'web';
-  productId: string;
-  transactionId?: string;
-  /** StoreKit 2 signed transaction (JWS) — verify against Apple's root certs. */
-  jws?: string;
-  /** Base64 StoreKit 1 app receipt — verify via App Store Server API / verifyReceipt. */
-  appReceipt?: string;
-  /** Google Play Billing purchase token — verify via Play Developer API. */
-  purchaseToken?: string;
-  /** Web checkout reference (e.g. Stripe Checkout Session / subscription id). */
-  providerRef?: string;
-  /** The untouched native/provider payload, for validators that want everything. */
-  raw: unknown;
-}
-
-export interface PurchaseResult {
-  receipt: PurchaseReceipt;
-  entitlements: Entitlement[];
-}
-
-/**
- * Why a receipt check produced what it did — the four outcomes that `Entitlement[]`
- * alone collapses into an indistinguishable `[]`.
- *
- * - `validated`   the server-of-record read the receipt; `entitlements` is its verdict
- *                 (still `[]` when the user genuinely owns nothing — the only outcome
- *                 where an empty list is an ANSWER rather than a non-answer).
- * - `not-native`  web, or a shell with no native store handler. (Android now HAS a native billing
- *                 handler, so it reports `native`/`no-receipt` here — not `not-native`; it just has
- *                 no StoreKit-1-style on-disk app receipt, so `receiptEntitlements` yields `no-receipt`.)
- * - `no-validator` only a {@link ClientTrustedValidator} is wired; a bare app receipt carries no
- *                 product id, so trusting it would grant a bogus entitlement. Wire a server validator.
- * - `no-receipt`  this build has no App Store receipt. StoreKit only issues one after a purchase or
- *                 restore, so locally-installed dev builds legitimately have none.
- */
-export type ReceiptOutcome = 'validated' | 'not-native' | 'no-validator' | 'no-receipt';
-
-/** The outcome-carrying result of {@link BillingModule.receiptEntitlements}. */
-export interface ReceiptEntitlements {
-  entitlements: Entitlement[];
-  outcome: ReceiptOutcome;
-}
-
-/**
- * The swappable seam. The kit owns the on-device purchase flow; *who decides the
- * user is actually entitled* is up to the app. Implement this (or configure the
- * bundled `HttpValidator`) to point at RevenueCat, IAPHUB, or your own backend.
- */
-export interface BillingValidator {
-  /** Validate a fresh purchase/restore receipt → the entitlements it grants. */
-  validate(receipt: PurchaseReceipt): Promise<Entitlement[]>;
-  /** Current entitlements from the server-of-record (or the device, for client-trusted). */
-  entitlements(): Promise<Entitlement[]>;
-}
-
-/**
- * The *purchase mechanism* on web — the symmetric counterpart to the native store.
- * On mobile the kit drives StoreKit/Play directly; on web there is no native store,
- * so the app plugs in a provider (Stripe / Paddle / LemonSqueezy / custom backend).
- * The same `kit.billing.*` calls dispatch here when running on the web. Implement this,
- * or configure the bundled `HttpBillingProvider` (backend-driven hosted checkout).
- */
-export interface BillingProvider {
-  /** Catalog with localized prices (typically from your backend / Stripe prices). */
-  products(ids: string[]): Promise<Product[]>;
-  /** Start checkout for a product. Resolves to the granted entitlements when known
-   *  synchronously; for redirect-based checkout (Stripe hosted page) it navigates away
-   *  and the entitlements surface via `entitlements()` after the redirect back. */
-  purchase(productId: string): Promise<Entitlement[]>;
-  /** Current entitlements from the server-of-record (Stripe webhooks → your backend). */
-  entitlements(): Promise<Entitlement[]>;
-  /** Re-sync entitlements (web has no "restore" — defaults to `entitlements()`). */
-  restore?(): Promise<Entitlement[]>;
-  /** Open the billing/subscription-management surface (e.g. Stripe Billing Portal). */
-  manageSubscriptions?(): Promise<void>;
-}

package/src/modules/billing/validators.ts

@@ -1,67 +0,0 @@
-import { httpJson, type HeaderProvider } from './http';
-import type { BillingValidator, Entitlement, PurchaseReceipt } from './types';
-
-export type { HeaderProvider } from './http';
-
-/**
- * Trusts the device. `validate` marks the purchased product active; `entitlements`
- * reads whatever the native layer reports (StoreKit `currentEntitlements` /
- * Play `queryPurchases`). Zero backend — spoofable on a compromised device, so
- * fine for demos/dev or low-stakes unlocks, NOT for real revenue. The default.
- */
-export class ClientTrustedValidator implements BillingValidator {
-  constructor(private readNative: () => Promise<Entitlement[]>) {}
-
-  async validate(receipt: PurchaseReceipt): Promise<Entitlement[]> {
-    // The native purchase already succeeded — grant that product directly. Do NOT
-    // read native entitlements here: on StoreKit 1 that means a restore, which pops
-    // an Apple ID prompt right after a buy. Call entitlements() explicitly for that.
-    return [{ productId: receipt.productId, active: true, purchasedAt: Date.now() }];
-  }
-
-  entitlements(): Promise<Entitlement[]> {
-    return this.readNative();
-  }
-}
-
-export class HttpValidatorOptions {
-  /** POST endpoint that receives a `PurchaseReceipt` and returns entitlements. */
-  validateUrl = '';
-  /** GET/POST endpoint for the current entitlements. Defaults to `validateUrl`. */
-  entitlementsUrl?: string;
-  /** Static headers or a thunk (e.g. to inject a fresh bearer token). */
-  headers?: HeaderProvider;
-  /** Map the provider's response JSON → `Entitlement[]`. Default expects `{ entitlements: [...] }`. */
-  mapResponse: (json: unknown) => Entitlement[] = (j) =>
-    ((j as { entitlements?: Entitlement[] } | null)?.entitlements ?? []);
-  /** Injected for tests / non-DOM runtimes. Defaults to global `fetch`. */
-  fetch?: typeof fetch;
-}
-
-/**
- * Generic server-validated strategy. One implementation covers RevenueCat,
- * IAPHUB, or any custom backend — they differ only by URL, auth header, and a small
- * response mapper. HTTP over SDK by design (no vendor packages).
- */
-export class HttpValidator implements BillingValidator {
-  public options: HttpValidatorOptions;
-  constructor(options?: Partial<HttpValidatorOptions>) {
-    this.options = { ...new HttpValidatorOptions(), ...options };
-    if (!this.options.validateUrl) throw new Error('HttpValidator: validateUrl is required');
-  }
-
-  async validate(receipt: PurchaseReceipt): Promise<Entitlement[]> {
-    const json = await httpJson({ ...this.req(), url: this.options.validateUrl, method: 'POST', body: receipt });
-    return this.options.mapResponse(json);
-  }
-
-  async entitlements(): Promise<Entitlement[]> {
-    const url = this.options.entitlementsUrl ?? this.options.validateUrl;
-    const method = this.options.entitlementsUrl ? 'GET' : 'POST';
-    return this.options.mapResponse(await httpJson({ ...this.req(), url, method }));
-  }
-
-  private req() {
-    return { headers: this.options.headers, fetch: this.options.fetch };
-  }
-}

package/src/modules/health.ts

@@ -1,70 +0,0 @@
-import type { NativeKit } from '../core/NativeKit';
-import type { Unsubscribe } from '../core/types';
-
-/**
- * Step counting. `count()` returns the day's step total; foreground updates come from polling it,
- * and background/while-killed steps are included automatically (the OS records them — no live JS
- * runs while suspended). Opt-in module — enable with `"modules": ["health"]` in appwrap.json.
- *
- * Platform reach:
- *  - **iOS** (HealthKit): today's total from the Health app — aggregates iPhone + Apple Watch + other
- *    sources, recorded by the OS regardless of the app, so it's global and survives an app kill. No
- *    `start()` needed. Requires the `com.apple.developer.healthkit` entitlement + `requestAccess()`.
- *  - **Android** (Health Connect): today's total from the system store — Wear-inclusive, survives a
- *    kill, mirrors iOS. Needs the `READ_STEPS` permission (granted via `requestAccess()`). Falls back
- *    to the `TYPE_STEP_COUNTER` sensor (since `start()`, no kill-survival) when Health Connect isn't
- *    installed.
- */
-export class HealthModule {
-  constructor(private kit: NativeKit) {}
-
-  get capability() {
-    return this.kit.capability('health');
-  }
-
-  /** Trigger the OS permission prompt (iOS motion usage · Android ACTIVITY_RECOGNITION).
-   * Interactive — generous timeout so it waits for the user to respond to the prompt. */
-  requestAccess(): Promise<boolean> {
-    return this.kit.invoke<boolean>('health.requestAccess', undefined, { timeoutMs: 60_000 });
-  }
-
-  /** Begin counting. Required on Android (registers the sensor listener); a no-op availability
-   * check on iOS (which reads history and needs no session). */
-  start(): Promise<void> {
-    return this.kit.invoke<void>('health.start');
-  }
-
-  /** End the counting session (Android: unregisters the listener). */
-  stop(): Promise<void> {
-    return this.kit.invoke<void>('health.stop');
-  }
-
-  /** The day's step count from the platform health store — iOS HealthKit / Android Health Connect
-   * (both Wear-inclusive, survive a kill). Android falls back to the step sensor (since `start()`). */
-  async count(): Promise<number> {
-    const r = await this.kit.invoke<{ steps: number }>('health.count');
-    return r?.steps ?? 0;
-  }
-
-  /** Start a session and stream the live count (foreground) by polling every `intervalMs`.
-   * Resolves an unsubscribe that stops both the poll and the session. */
-  async watch(cb: (steps: number) => void, intervalMs = 2000): Promise<Unsubscribe> {
-    await this.start();
-    const tick = async () => {
-      try {
-        cb(await this.count());
-      } catch (e) {
-        console.warn('[native-kit] health.count failed', e);
-      }
-    };
-    await tick();
-    const id = setInterval(tick, intervalMs);
-    let stopped = false;
-    return () => {
-      if (stopped) return;
-      stopped = true;
-      clearInterval(id);
-      this.stop().catch((e) => console.warn('[native-kit] health.stop failed', e));
-    };
-  }
-}

package/src/modules/widget.ts

@@ -1,65 +0,0 @@
-import type { NativeKit } from '../core/NativeKit';
-
-/** One tile/row in an icon-grid or list widget. `deepLink` is the full URL the tile opens (routed by
- *  the app's deep-link handling); `iconUrl` is fetched to a tile image on the device. */
-export interface WidgetEntry {
-  label: string;
-  sublabel?: string;
-  deepLink?: string;
-  iconUrl?: string;
-  /** unread/attention count drawn as a bubble on the tile (icon-grid); absent/0 = no badge. */
-  badge?: number;
-}
-
-/** A single big number for the `stat` template. */
-export interface WidgetStat {
-  value: string;
-  label?: string;
-  sublabel?: string;
-}
-
-/** Payload published to the home-screen widget. `template` picks the layout:
- *  - `icon-grid` — grid of {@link WidgetEntry} tiles (the app-launcher use)
- *  - `list`      — rows of {@link WidgetEntry}
- *  - `stat`      — one {@link WidgetStat} (optional whole-widget `deepLink`) */
-export interface WidgetPayload {
-  template: 'icon-grid' | 'list' | 'stat';
-  title?: string;
-  entries?: WidgetEntry[];
-  stat?: WidgetStat;
-  /** Whole-widget deep link (stat template, or the empty-state fallback). */
-  deepLink?: string;
-  /** Which home-screen widget kind this targets. `launcher` (default) = the app-launcher/icon-grid
-   *  widget; `data` = the separate data widget an in-app view can drive. Two kinds so a data publish
-   *  never clobbers the launcher (each renders from its own shared-store key). */
-  slot?: 'launcher' | 'data';
-}
-
-export interface WidgetPublishResult {
-  published: boolean;
-  reason?: 'unsupported';
-}
-
-/**
- * Publish content to the app's home-screen widget (iOS WidgetKit / Android AppWidget). The shell writes
- * the payload into a shared container the widget reads at render, fetching any `iconUrl` to a local
- * tile image, then reloads the widget. Web/unsupported builds resolve `{published:false}`. Branch on
- * {@link WidgetModule.capability}.
- */
-export class WidgetModule {
-  constructor(private kit: NativeKit) {}
-
-  /** 'native' where a home-screen widget surface exists (iOS 14+ / Android AppWidget) · else 'none'. */
-  get capability() {
-    return this.kit.capability('widget');
-  }
-
-  publish(payload: WidgetPayload): Promise<WidgetPublishResult> {
-    return this.kit.invoke('widget.publish', payload);
-  }
-
-  /** Clear the widget (renders its empty state). */
-  clear(): Promise<WidgetPublishResult> {
-    return this.kit.invoke('widget.publish', { template: 'icon-grid', entries: [] });
-  }
-}