@omg-dev/billing 0.4.41 → 0.4.42

package/dist/catalog.mjs

@@ -74,10 +74,7 @@ function addOnPriceHash(addOn) {
 function toCatalog(billing) {
 	return {
 		version: 1,
-		provider: {
-			name: billing.provider.name,
-			useProviderMeters: false
-		},
+		provider: billing.provider,
 		credit: billing.credit,
 		features: billing.features.map((f) => ({
 			key: f.key,

package/dist/index.mjs

@@ -52,6 +52,13 @@ function polar() {
 		useProviderMeters: false
 	};
 }
+function appStore(input) {
+	return {
+		name: "app-store",
+		useProviderMeters: false,
+		...input
+	};
+}
 function plan(input) {
 	return {
 		__kind: "plan",
@@ -74,6 +81,18 @@ function defineBilling(config) {
 	const defaults = planKeys.filter((k) => config.plans[k].default);
 	if (defaults.length !== 1) throw new Error(`@omg-dev/billing: exactly one plan must be default:true (found ${defaults.length}: [${defaults.join(", ")}])`);
 	if (config.plans[defaults[0]].deprecated) throw new Error(`@omg-dev/billing: the default plan "${defaults[0]}" cannot be deprecated — new customers land on it`);
+	if (config.provider.name === "app-store") {
+		const provider = config.provider;
+		if (!provider.bundleId.trim()) throw new Error("@omg-dev/billing: app-store bundleId is required");
+		if (provider.environment === "Production" && (!Number.isSafeInteger(provider.appAppleId) || (provider.appAppleId ?? 0) <= 0)) throw new Error("@omg-dev/billing: app-store appAppleId is required in Production");
+		const productEntries = Object.entries(provider.products);
+		if (productEntries.length === 0) throw new Error("@omg-dev/billing: app-store products must not be empty");
+		for (const [productId, mapping] of productEntries) {
+			if (!productId.trim()) throw new Error("@omg-dev/billing: app-store productId must not be empty");
+			if (!config.plans[mapping.plan]) throw new Error(`@omg-dev/billing: app-store product "${productId}" maps to unknown plan "${mapping.plan}"`);
+			if (!Number.isSafeInteger(mapping.planVersion) || mapping.planVersion <= 0) throw new Error(`@omg-dev/billing: app-store product "${productId}" planVersion must be a positive integer`);
+		}
+	}
 	const rateCards = config.usage ?? {};
 	for (const fkey of Object.keys(rateCards)) {
 		const f = config.features[fkey];
@@ -151,4 +170,4 @@ function defineBilling(config) {
 	};
 }
 //#endregion
-export { MICROS_PER_UNIT, addOn, defineBilling, formatMoney, limit, money, overage, plan, polar, rateCard, stripe, usd };
+export { MICROS_PER_UNIT, addOn, appStore, defineBilling, formatMoney, limit, money, overage, plan, polar, rateCard, stripe, usd };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@omg-dev/billing",
-  "version": "0.4.41",
+  "version": "0.4.42",
   "type": "module",
   "exports": {
     ".": {

package/src/catalog.ts

@@ -11,6 +11,7 @@ import type {
   Money,
   NormalizedAddOn,
   NormalizedPlan,
+  ProviderDef,
   RateCard,
 } from "./index.ts";
 
@@ -60,7 +61,7 @@ export interface CatalogAddOn {
 
 export interface Catalog {
   version: 1;
-  provider: { name: string; useProviderMeters: false };
+  provider: ProviderDef;
   credit: { unit: string; peg: Money };
   features: Array<{ key: string; kind: string; label: string; unit?: string }>;
   rateCards: Record<string, RateCard>;
@@ -148,10 +149,7 @@ export function addOnPriceHash(addOn: NormalizedAddOn): string {
 export function toCatalog(billing: Billing): Catalog {
   return {
     version: 1,
-    provider: {
-      name: billing.provider.name,
-      useProviderMeters: false,
-    },
+    provider: billing.provider,
     credit: billing.credit,
     features: billing.features.map((f) => ({
       key: f.key,

package/src/index.ts

@@ -124,14 +124,40 @@ export function rateCard(models: Record<string, ModelRate>): RateCard {
 // Provider descriptors.
 // ---------------------------------------------------------------------------
 
-export type ProviderName = "stripe" | "polar";
+export type ProviderName = "stripe" | "polar" | "app-store";
 
-export interface ProviderDef {
-  name: ProviderName;
+export interface HostedProviderDef {
+  name: "stripe" | "polar";
   /** Use provider-side meters? We deliberately keep this false — our ledger meters. */
   useProviderMeters: false;
 }
 
+export interface AppStoreProductDef {
+  /** OMG plan key granted by this App Store product. */
+  plan: string;
+  /** Catalog plan version represented by this immutable App Store product. */
+  planVersion: number;
+}
+
+/**
+ * Native StoreKit configuration. Apple is not a hosted-checkout provider.
+ * The control-plane verifies signed transactions and notifications, then
+ * writes their normalized lifecycle state into the shared entitlement engine.
+ */
+export interface AppStoreProviderDef {
+  name: "app-store";
+  useProviderMeters: false;
+  bundleId: string;
+  /** Numeric App Store Connect app id. Required for Production verification. */
+  appAppleId?: number;
+  environment: "Sandbox" | "Production";
+  /** Also accept verified Sandbox transactions while Production is live. */
+  allowSandbox?: boolean;
+  products: Record<string, AppStoreProductDef>;
+}
+
+export type ProviderDef = HostedProviderDef | AppStoreProviderDef;
+
 export function stripe(): ProviderDef {
   return { name: "stripe", useProviderMeters: false };
 }
@@ -140,6 +166,10 @@ export function polar(): ProviderDef {
   return { name: "polar", useProviderMeters: false };
 }
 
+export function appStore(input: Omit<AppStoreProviderDef, "name" | "useProviderMeters">): AppStoreProviderDef {
+  return { name: "app-store", useProviderMeters: false, ...input };
+}
+
 // ---------------------------------------------------------------------------
 // Plan definition (authoring shape).
 // ---------------------------------------------------------------------------
@@ -329,6 +359,36 @@ export function defineBilling(config: BillingConfig): Billing {
     );
   }
 
+  if (config.provider.name === "app-store") {
+    const provider = config.provider;
+    if (!provider.bundleId.trim()) {
+      throw new Error("@omg-dev/billing: app-store bundleId is required");
+    }
+    if (provider.environment === "Production" &&
+        (!Number.isSafeInteger(provider.appAppleId) || (provider.appAppleId ?? 0) <= 0)) {
+      throw new Error("@omg-dev/billing: app-store appAppleId is required in Production");
+    }
+    const productEntries = Object.entries(provider.products);
+    if (productEntries.length === 0) {
+      throw new Error("@omg-dev/billing: app-store products must not be empty");
+    }
+    for (const [productId, mapping] of productEntries) {
+      if (!productId.trim()) {
+        throw new Error("@omg-dev/billing: app-store productId must not be empty");
+      }
+      if (!config.plans[mapping.plan]) {
+        throw new Error(
+          `@omg-dev/billing: app-store product "${productId}" maps to unknown plan "${mapping.plan}"`,
+        );
+      }
+      if (!Number.isSafeInteger(mapping.planVersion) || mapping.planVersion <= 0) {
+        throw new Error(
+          `@omg-dev/billing: app-store product "${productId}" planVersion must be a positive integer`,
+        );
+      }
+    }
+  }
+
   // rate cards may only reference declared metered features
   const rateCards = config.usage ?? {};
   for (const fkey of Object.keys(rateCards)) {

package/src/test/billing.test.ts

@@ -8,6 +8,7 @@ import {
   rateCard,
   stripe,
   polar,
+  appStore,
   usd,
   money,
   formatMoney,
@@ -155,6 +156,40 @@ describe("provider", () => {
     expect(stripe().useProviderMeters).toBe(false);
     expect(polar().useProviderMeters).toBe(false);
   });
+
+  it("keeps native StoreKit configuration separate from hosted checkout", () => {
+    const provider = appStore({
+      bundleId: "dev.omg.example",
+      appAppleId: 123456789,
+      environment: "Production",
+      products: { "dev.omg.example.pro": { plan: "pro", planVersion: 2 } },
+    });
+    expect(provider.name).toBe("app-store");
+    expect(provider.products["dev.omg.example.pro"]).toEqual({ plan: "pro", planVersion: 2 });
+  });
+
+  it("validates App Store identifiers and product mappings", () => {
+    const config = (provider: ReturnType<typeof appStore>) => ({
+      provider,
+      credit: { unit: "usd", peg: usd(1) },
+      features: { access: { kind: "boolean" as const } },
+      plans: {
+        free: plan({ price: usd(0), default: true, includes: { access: false } }),
+        pro: plan({ price: usd(10), interval: "month", includes: { access: true } }),
+      },
+    });
+
+    expect(() => defineBilling(config(appStore({
+      bundleId: "dev.omg.example",
+      environment: "Production",
+      products: { "dev.omg.example.pro": { plan: "pro", planVersion: 1 } },
+    })))).toThrow(/appAppleId is required/);
+    expect(() => defineBilling(config(appStore({
+      bundleId: "dev.omg.example",
+      environment: "Sandbox",
+      products: { "dev.omg.example.ghost": { plan: "ghost", planVersion: 1 } },
+    })))).toThrow(/maps to unknown plan/);
+  });
 });
 
 describe("catalog serialization", () => {
@@ -180,6 +215,29 @@ describe("catalog serialization", () => {
     }
   });
 
+  it("serializes the App Store verification and product mapping contract", () => {
+    const b = defineBilling({
+      provider: appStore({
+        bundleId: "dev.omg.example",
+        environment: "Sandbox",
+        products: { "dev.omg.example.pro": { plan: "pro", planVersion: 4 } },
+      }),
+      credit: { unit: "usd", peg: usd(1) },
+      features: { access: { kind: "boolean" } },
+      plans: {
+        free: plan({ price: usd(0), default: true, includes: { access: false } }),
+        pro: plan({ price: usd(10), interval: "month", includes: { access: true } }),
+      },
+    });
+    expect(toCatalog(b).provider).toEqual({
+      name: "app-store",
+      useProviderMeters: false,
+      bundleId: "dev.omg.example",
+      environment: "Sandbox",
+      products: { "dev.omg.example.pro": { plan: "pro", planVersion: 4 } },
+    });
+  });
+
   it("includes add-on hashes", () => {
     const cat = toCatalog(fixture());
     expect(cat.addOns).toHaveLength(1);