@livx.cc/native-kit 0.40.0 → 0.41.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@livx.cc/native-kit",
-  "version": "0.40.0",
+  "version": "0.41.0",
   "description": "Isomorphic native-capabilities kit for PWAs — same API in browser and in an appwrap native shell. Zero dependencies.",
   "license": "MIT",
   "author": "Elya Livshitz",

package/src/core/NativeKit.ts

@@ -43,6 +43,22 @@ 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
@@ -265,7 +281,12 @@ export class NativeKit {
     try {
       return await this.adapter!.invoke<T>(method, params, opts);
     } catch (e) {
-      if (this.webFallback && e instanceof KitError && e.code === 'UNSUPPORTED') {
+      if (
+        this.webFallback &&
+        e instanceof KitError &&
+        e.code === 'UNSUPPORTED' &&
+        !WEB_FALLBACK_EXCLUDED_DOMAINS.some((d) => method.startsWith(d))
+      ) {
         return this.webFallback.invoke<T>(method, params, opts);
       }
       throw e;

package/src/modules/billing/billing.ts

@@ -116,7 +116,7 @@ export class BillingModule {
    */
   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 today)
+    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' };
@@ -142,19 +142,22 @@ export class BillingModule {
   }
 
   /**
-   * iOS 15+ native-only: present StoreKit 2's **in-app** subscription-management sheet
-   * (`AppStore.showManageSubscriptions(in:)`). Unlike {@link manageSubscriptions} (which deep-links
-   * out to the App Store account page, StoreKit 1), this stays inside the app AND shows sandbox /
-   * TestFlight subscriptions — so it's the path to verify/cancel a sub during testing. Opt-in: the
-   * default `manageSubscriptions()` deep-link is unchanged; call this explicitly to use the sheet.
+   * 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` on the web or Android (no StoreKit), and `NATIVE_ERROR` on iOS <15 / no
-   * presentable scene / a StoreKit error. Resolves once the user dismisses 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 in-app subscriptions sheet is iOS-only (StoreKit 2). Use manageSubscriptions() on web/Android.');
+      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.

package/src/modules/billing/types.ts

@@ -8,6 +8,18 @@ export type ProductType =
   | '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;
@@ -21,6 +33,13 @@ export interface Product {
   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". */
@@ -65,7 +84,9 @@ export interface PurchaseResult {
  * - `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: no StoreKit-1 receipt).
+ * - `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