@livx.cc/native-kit 0.38.0 → 0.39.0

package/README.md

@@ -26,7 +26,7 @@ mixpanel.register(await kit.context());
 
 The kit detects whether it's running inside the appwrap shell and routes each call to the native bridge or a web fallback, so a single web build works everywhere. Capabilities advertise their real backing (`native` / `web` / `none`) so your UI can be honest about what's available.
 
-Covers haptics, share, storage, notifications, OAuth, billing (IAP), health, geo, camera, photos, contacts, calendar, motion, reviews, tracking (iOS App Tracking Transparency), and more.
+Covers haptics, share, storage, notifications, OAuth, billing (IAP), health, geo, heading (compass), camera, photos, contacts, calendar, motion, reviews, tracking (iOS App Tracking Transparency), and more.
 
 **Full documentation, capability model, and the bridge protocol:** see the [appwrap README](https://github.com/Livshitz/appwrap#readme).
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@livx.cc/native-kit",
-  "version": "0.38.0",
+  "version": "0.39.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/index.ts

@@ -65,4 +65,6 @@ export type {
   ProductType,
   PurchaseReceipt,
   PurchaseResult,
+  ReceiptEntitlements,
+  ReceiptOutcome,
 } from './modules/billing/types';

package/src/modules/billing/billing.ts

@@ -1,7 +1,16 @@
 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 } from './types';
+import type {
+  BillingProvider,
+  BillingValidator,
+  Entitlement,
+  Product,
+  PurchaseReceipt,
+  PurchaseResult,
+  ReceiptEntitlements,
+  ReceiptOutcome,
+} from './types';
 
 /**
  * In-app purchases & subscriptions — ONE API across web and native.
@@ -89,14 +98,29 @@ export class BillingModule {
    * 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 []; // web, or a shell with no native store handler (Android today)
-    if (this.validator instanceof ClientTrustedValidator) return []; // bare receipt has no product id → would grant a bogus active entitlement; needs a server validator
+    if (this.capability !== 'native') return { entitlements: [], outcome: 'not-native' }; // web, or a shell with no native store handler (Android today)
+    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 [];
-    return this.validator.validate(receipt); // server-of-record turns the receipt into entitlements
+    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). */

package/src/modules/billing/types.ts

@@ -58,6 +58,27 @@ export interface PurchaseResult {
   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: no StoreKit-1 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