@entitlehub/sdk 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -2,30 +2,42 @@
 
 All notable changes to `@entitlehub/sdk`. Adheres to [Semantic Versioning](https://semver.org/).
 
-## 0.2.0 — 2026-07-18
+## 0.3.0 (2026-09-19)
 
 ### Added
-- Client `EntitleHub.reportPurchase(...)` — report a **validated** purchase (Apple JWS / Google
+- Catalog API on `EntitleHubServer`: `eh.entitlements`, `eh.products`, `eh.offerings`. Create,
+  update, archive and delete entitlements, products and offerings; attach/detach mappings from
+  either side; manage paywall packages. Refs take ids or the key / SKU / identifier you already
+  have. See [the Catalog API docs](https://entitlehub.com/docs/catalog-api).
+- `ensure(...)` on entitlements and products: create, or return the existing row, so a catalog
+  setup script can run on every deploy.
+- `EntitleHubError.apiCode` and `.body`: the API's machine-readable error code (e.g.
+  `product_exists`, `ambiguous_product`, `rate_limited`) and the full error payload.
+
+## 0.2.0 (2026-07-18)
+
+### Added
+- Client `EntitleHub.reportPurchase(...)`: report a **validated** purchase (Apple JWS / Google
   token / Stripe subscription) directly from the app with your publishable key; updates the cache
   and notifies listeners. Validation makes a forged receipt impossible, so no secret key is needed
   on the client. (The trusted server-report mode still requires a secret key.)
 - Powers the new [`@entitlehub/react-native`](https://www.npmjs.com/package/@entitlehub/react-native)
   purchase SDK.
 
-## 0.1.3 — 2026-07-18
+## 0.1.3 (2026-07-18)
 
 ### Added
-- `reportPurchase` accepts `stripeSubscriptionId` — EntitleHub validates the subscription against
+- `reportPurchase` accepts `stripeSubscriptionId`, EntitleHub validates the subscription against
   your Stripe secret key (active/trialing → granted, current period end as the expiry).
 
-## 0.1.2 — 2026-07-18
+## 0.1.2 (2026-07-18)
 
 ### Changed
 - The SDK now lives in its own public repository:
   [github.com/DanCue44/entitlehub-sdk](https://github.com/DanCue44/entitlehub-sdk) (MIT). Open-source
   SDK, closed backend. `repository` / `bugs` metadata point there.
 
-## 0.1.1 — 2026-07-18
+## 0.1.1 (2026-07-18)
 
 ### Added
 - README badges (npm version, types, zero-deps, license) and docs links.
@@ -36,14 +48,14 @@ All notable changes to `@entitlehub/sdk`. Adheres to [Semantic Versioning](https
   + `isSubscription`), Apple StoreKit 2 (validated via `signedTransaction`), and trusted
   server-report.
 
-## 0.1.0 — 2026-07-18
+## 0.1.0 (2026-07-18)
 
 Initial release.
 
-- **`EntitleHub`** (client, publishable key) — `getCustomerInfo`, `isEntitled`,
+- **`EntitleHub`** (client, publishable key): `getCustomerInfo`, `isEntitled`,
   `checkEntitlement`, `getOfferings`, `logIn` / `logOut`, `addCustomerInfoUpdateListener`.
   Cached CustomerInfo; safe for browsers, React Native, and Expo.
-- **`EntitleHubServer`** (server, secret key) — `reportPurchase` (Apple JWS / Google Play
+- **`EntitleHubServer`** (server, secret key): `reportPurchase` (Apple JWS / Google Play
   token / trusted), `grantEntitlement`, `getCustomerInfo`, `check`.
 - **`CustomerInfo`** ergonomic wrapper; **`EntitleHubError`** with `.status` / `.code`.
 - Zero dependencies; ESM + CJS + bundled type declarations.

package/README.md

@@ -5,7 +5,7 @@
 [![zero dependencies](https://img.shields.io/badge/dependencies-0-brightgreen)](https://www.npmjs.com/package/@entitlehub/sdk)
 [![license MIT](https://img.shields.io/npm/l/@entitlehub/sdk)](./LICENSE)
 
-One entitlement API across **App Store, Google Play, Stripe, and web** — for browsers, React Native, Expo, and Node. Stop checking raw product IDs; ask *"what is this user entitled to right now?"*
+One entitlement API across **App Store, Google Play, Stripe, and web**, for browsers, React Native, Expo, and Node. Stop checking raw product IDs; ask *"what is this user entitled to right now?"*
 
 > Docs: **[entitlehub.com/docs](https://entitlehub.com/docs)** · [REST API](https://entitlehub.com/docs/api) · [Migrating from RevenueCat](https://entitlehub.com/docs/migrating-from-revenuecat)
 
@@ -15,7 +15,7 @@ npm install @entitlehub/sdk
 
 Zero dependencies. Uses the global `fetch` (Node 18+, all modern browsers, React Native, Expo).
 
-## Client (in your app) — publishable key
+## Client (in your app) (publishable key)
 
 Reads only. Safe to ship in your app. **Never put a secret (`sk_`) key here.**
 
@@ -66,7 +66,7 @@ eh.logOut();                 // forget cached info
 | `getOfferings()` | `Offerings` | Entitlements + products, for building a paywall. |
 | `addCustomerInfoUpdateListener(fn)` | `() => void` | Returns an unsubscribe. |
 
-## Server (in your backend) — secret key
+## Server (in your backend) (secret key)
 
 Report purchases and grant entitlements. **Server only.**
 
@@ -76,17 +76,17 @@ import { EntitleHubServer } from "@entitlehub/sdk";
 const eh = new EntitleHubServer({ apiKey: process.env.ENTITLEHUB_SECRET_KEY! });
 
 // After the store purchase is confirmed on-device, report it from your server.
-// Google Play — validated (EntitleHub verifies the token with your Play service account):
+// Google Play: validated (EntitleHub verifies the token with your Play service account):
 const info = await eh.reportPurchase(userId, {
   store: "play", storeProductId: "pro_monthly",
   purchaseToken: playToken, isSubscription: true,
 });
 info.isActive("pro"); // → true
 
-// Apple StoreKit 2 — validated (product / environment read from the signed JWS):
+// Apple StoreKit 2: validated (product / environment read from the signed JWS):
 await eh.reportPurchase(userId, { store: "app_store", storeProductId: "", signedTransaction: jws });
 
-// Trusted server-report (no store validation — only if you validated the receipt elsewhere):
+// Trusted server-report (no store validation, only if you validated the receipt elsewhere):
 await eh.reportPurchase(userId, { store: "app_store", storeProductId: "pro_monthly" });
 
 // Grant directly (promo / comp / support), no purchase:
@@ -99,6 +99,41 @@ await eh.grantEntitlement(userId, "pro", { durationDays: 30 });
 | `grantEntitlement(userId, id, { durationDays?, isSandbox? })` | `CustomerInfo` |
 | `getCustomerInfo(userId)` / `check(userId, id)` | `CustomerInfo` / `CheckResult` |
 
+### Catalog: entitlements, products, offerings
+
+Set up and change your catalog from code. Refs take the id **or** the key / SKU / identifier you
+already have. Every create has an `ensure` twin that returns the existing row instead of failing,
+so a setup script can run on every deploy.
+
+```ts
+await eh.entitlements.ensure({ key: "pro", name: "Pro" });
+
+await eh.products.ensure({
+  store: "stripe", storeProductId: "price_1Q...", type: "subscription", duration: "P1M",
+  priceMicros: 9_990_000, entitlements: ["pro"],
+});
+
+// Remap (future purchases only; access already granted is untouched):
+await eh.products.update({ store: "play", storeProductId: "pro_monthly" }, { entitlements: ["pro", "team"] });
+await eh.entitlements.attachProducts("team", ["price_1Q..."]);
+
+// Retire a SKU you no longer sell. Existing subscribers keep access and renewals:
+await eh.products.archive("price_old");
+
+await eh.offerings.create({
+  identifier: "default", isCurrent: true, metadata: { headline: "Go Pro" },
+  packages: [{ identifier: "monthly", product: "price_1Q..." }],
+});
+```
+
+| Namespace | Methods |
+|---|---|
+| `eh.entitlements` | `list` `get` `create` `ensure` `update` `delete` `products` `attachProducts` `detachProducts` `archive` `unarchive` |
+| `eh.products` | `list` `get` `create` `ensure` `update` `delete` `attachEntitlements` `detachEntitlements` `archive` `unarchive` |
+| `eh.offerings` | `list` `get` `create` `update` `delete` `archive` `unarchive` `packages` `addPackage` `updatePackage` `deletePackage` |
+
+Full reference: [entitlehub.com/docs/catalog-api](https://entitlehub.com/docs/catalog-api).
+
 ## Already have an IAP setup?
 
 Keep making the actual store purchase with your existing IAP flow (StoreKit / Play Billing /
@@ -108,6 +143,8 @@ with `getCustomerInfo()`. See the full guide at [entitlehub.com/docs](https://en
 ## Errors
 
 Every failure throws an `EntitleHubError` with `.status` and `.code` (`auth` | `http` | `network` | `config`).
+When the API sends its own machine-readable code it is on `.apiCode` (e.g. `product_exists`,
+`ambiguous_product`, `rate_limited`), with the full payload on `.body`.
 
 ```ts
 import { EntitleHubError } from "@entitlehub/sdk";

package/dist/index.cjs

@@ -1 +1 @@
-"use strict";var d=Object.defineProperty;var C=Object.getOwnPropertyDescriptor;var _=Object.getOwnPropertyNames;var k=Object.prototype.hasOwnProperty;var x=(n,t)=>{for(var e in t)d(n,e,{get:t[e],enumerable:!0})},P=(n,t,e,s)=>{if(t&&typeof t=="object"||typeof t=="function")for(let r of _(t))!k.call(n,r)&&r!==e&&d(n,r,{get:()=>t[r],enumerable:!(s=C(t,r))||s.enumerable});return n};var E=n=>P(d({},"__esModule",{value:!0}),n);var S={};x(S,{CustomerInfo:()=>o,EntitleHub:()=>l,EntitleHubError:()=>i,EntitleHubServer:()=>f});module.exports=E(S);var o=class{constructor(t){this.appUserId=t.app_user_id,this.entitlements=t.active_entitlements??[];let e={};for(let s of this.entitlements)e[s.entitlement]=s;this.active=e}isActive(t){return!!this.active[t]}get activeEntitlementIds(){return Object.keys(this.active)}expirationDate(t){let e=this.active[t];if(e)return e.expires_at?new Date(e.expires_at):null}};var i=class extends Error{constructor(t,e,s="error"){super(t),this.name="EntitleHubError",this.status=e,this.code=s}},T=n=>new Promise(t=>setTimeout(t,n));async function c(n,t,e,s){let r=n.fetchImpl??globalThis.fetch;if(!r)throw new i("No fetch implementation available. On Node <18, pass fetchImpl.",0,"no_fetch");let h=`${n.baseUrl.replace(/\/$/,"")}${e}`,b=t==="GET"?n.retries??2:0,m;for(let u=0;u<=b;u++){let y=new AbortController,g=n.timeoutMs?setTimeout(()=>y.abort(),n.timeoutMs):void 0;try{let a=await r(h,{method:t,headers:{Authorization:`Bearer ${n.apiKey}`,...s?{"Content-Type":"application/json"}:{}},body:s?JSON.stringify(s):void 0,signal:y.signal}),I=await a.text(),p=I?v(I):{};if(!a.ok){let w=`HTTP ${a.status}`;throw p&&typeof p=="object"&&"error"in p&&(w=String(p.error)),new i(w,a.status,a.status===401||a.status===403?"auth":"http")}return p}catch(a){if(m=a,a instanceof i)throw a;u<b&&await T(250*(u+1))}finally{g&&clearTimeout(g)}}throw new i(`Network request failed: ${String(m?.message??m)}`,0,"network")}function v(n){try{return JSON.parse(n)}catch{return{}}}var l=class{constructor(t){this.listeners=new Set;if(!t.apiKey)throw new i("apiKey is required.",0,"config");if(!t.appUserId)throw new i("appUserId is required.",0,"config");if(t.apiKey.startsWith("sk_"))throw new i("Never use a secret (sk_) key in the client SDK \u2014 use your publishable (pk_) key.",0,"config");this.appUserId=t.appUserId,this.cacheTtlMs=t.cacheTtlMs??5*6e4,this.http={baseUrl:t.baseUrl??"https://entitlehub.com/v1",apiKey:t.apiKey,fetchImpl:t.fetchImpl,timeoutMs:15e3}}get currentAppUserId(){return this.appUserId}async logIn(t){return this.appUserId=t,this.cached=void 0,this.getCustomerInfo({fetchPolicy:"network-only"})}logOut(){this.cached=void 0}async getCustomerInfo(t={}){if((t.fetchPolicy??"cache-first")==="cache-first"&&this.cached&&Date.now()-this.cached.at<this.cacheTtlMs)return this.cached.info;let s=await c(this.http,"GET",`/subscribers/${encodeURIComponent(this.appUserId)}`),r=new o(s);this.cached={info:r,at:Date.now()};for(let h of this.listeners)try{h(r)}catch{}return r}async isEntitled(t){return(await this.getCustomerInfo()).isActive(t)}async checkEntitlement(t,e={}){return c(this.http,"POST","/check",{app_user_id:this.appUserId,entitlement:t,sandbox:!!e.sandbox})}async getOfferings(){return c(this.http,"GET","/offerings")}async reportPurchase(t){let e=await c(this.http,"POST",`/subscribers/${encodeURIComponent(this.appUserId)}/purchases`,{store:t.store??"",store_product_id:t.storeProductId??"",is_sandbox:!!t.isSandbox,purchase_token:t.purchaseToken??"",is_subscription:!!t.isSubscription,signed_transaction:t.signedTransaction??"",stripe_subscription_id:t.stripeSubscriptionId??""}),s=new o(e);this.cached={info:s,at:Date.now()};for(let r of this.listeners)try{r(s)}catch{}return s}addCustomerInfoUpdateListener(t){return this.listeners.add(t),()=>this.listeners.delete(t)}};var f=class{constructor(t){if(!t.apiKey)throw new i("apiKey is required.",0,"config");if(!t.apiKey.startsWith("sk_"))throw new i("EntitleHubServer needs a secret (sk_) key. For client reads, use the EntitleHub class with a pk_ key.",0,"config");this.http={baseUrl:t.baseUrl??"https://entitlehub.com/v1",apiKey:t.apiKey,fetchImpl:t.fetchImpl,timeoutMs:15e3}}async reportPurchase(t,e){let s=await c(this.http,"POST",`/subscribers/${encodeURIComponent(t)}/purchases`,{store:e.store,store_product_id:e.storeProductId,is_sandbox:!!e.isSandbox,transaction_id:e.transactionId??"",purchase_token:e.purchaseToken??"",is_subscription:!!e.isSubscription,signed_transaction:e.signedTransaction??"",stripe_subscription_id:e.stripeSubscriptionId??""});return new o(s)}async grantEntitlement(t,e,s={}){let r=await c(this.http,"POST",`/subscribers/${encodeURIComponent(t)}/grant`,{entitlement:e,duration_days:s.durationDays??0,is_sandbox:!!s.isSandbox});return new o(r)}async getCustomerInfo(t){let e=await c(this.http,"GET",`/subscribers/${encodeURIComponent(t)}`);return new o(e)}async check(t,e,s={}){return c(this.http,"POST","/check",{app_user_id:t,entitlement:e,sandbox:!!s.sandbox})}};0&&(module.exports={CustomerInfo,EntitleHub,EntitleHubError,EntitleHubServer});
+"use strict";var I=Object.defineProperty;var R=Object.getOwnPropertyDescriptor;var H=Object.getOwnPropertyNames;var U=Object.prototype.hasOwnProperty;var A=(r,t)=>{for(var e in t)I(r,e,{get:t[e],enumerable:!0})},D=(r,t,e,n)=>{if(t&&typeof t=="object"||typeof t=="function")for(let s of H(t))!U.call(r,s)&&s!==e&&I(r,s,{get:()=>t[s],enumerable:!(n=R(t,s))||n.enumerable});return r};var q=r=>D(I({},"__esModule",{value:!0}),r);var j={};A(j,{CustomerInfo:()=>c,EntitleHub:()=>y,EntitleHubError:()=>a,EntitleHubServer:()=>b,EntitlementsApi:()=>l,OfferingsApi:()=>m,ProductsApi:()=>g});module.exports=q(j);var c=class{constructor(t){this.appUserId=t.app_user_id,this.entitlements=t.active_entitlements??[];let e={};for(let n of this.entitlements)e[n.entitlement]=n;this.active=e}isActive(t){return!!this.active[t]}get activeEntitlementIds(){return Object.keys(this.active)}expirationDate(t){let e=this.active[t];if(e)return e.expires_at?new Date(e.expires_at):null}};var S="0.3.0";var a=class extends Error{constructor(t,e,n="error",s){super(t),this.name="EntitleHubError",this.status=e,this.code=n,this.body=s,this.apiCode=typeof s?.code=="string"?s.code:void 0}},M=r=>new Promise(t=>setTimeout(t,r));async function i(r,t,e,n){let s=r.fetchImpl??globalThis.fetch;if(!s)throw new a("No fetch implementation available. On Node <18, pass fetchImpl.",0,"no_fetch");let C=`${r.baseUrl.replace(/\/$/,"")}${e}`,k=t==="GET"?r.retries??2:0,_;for(let f=0;f<=k;f++){let T=new AbortController,w=r.timeoutMs?setTimeout(()=>T.abort(),r.timeoutMs):void 0;try{let u=await s(C,{method:t,headers:{Authorization:`Bearer ${r.apiKey}`,"X-EntitleHub-Client":r.client??`${"js"}/${S}`,...n?{"Content-Type":"application/json"}:{}},body:n?JSON.stringify(n):void 0,signal:T.signal}),O=await u.text(),h=O?K(O):{};if(!u.ok){let v=`HTTP ${u.status}`,P=h&&typeof h=="object"?h:void 0;throw P&&"error"in P&&(v=String(P.error)),new a(v,u.status,u.status===401||u.status===403?"auth":"http",P)}return h}catch(u){if(_=u,u instanceof a)throw u;f<k&&await M(250*(f+1))}finally{w&&clearTimeout(w)}}throw new a(`Network request failed: ${String(_?.message??_)}`,0,"network")}function K(r){try{return JSON.parse(r)}catch{return{}}}var y=class{constructor(t){this.listeners=new Set;if(!t.apiKey)throw new a("apiKey is required.",0,"config");if(!t.appUserId)throw new a("appUserId is required.",0,"config");if(t.apiKey.startsWith("sk_"))throw new a("Never use a secret (sk_) key in the client SDK. Use your publishable (pk_) key.",0,"config");this.appUserId=t.appUserId,this.cacheTtlMs=t.cacheTtlMs??5*6e4,this.http={baseUrl:t.baseUrl??"https://entitlehub.com/v1",apiKey:t.apiKey,fetchImpl:t.fetchImpl,timeoutMs:15e3,client:t.client}}get currentAppUserId(){return this.appUserId}async logIn(t){return this.appUserId=t,this.cached=void 0,this.getCustomerInfo({fetchPolicy:"network-only"})}logOut(){this.cached=void 0}async getCustomerInfo(t={}){if((t.fetchPolicy??"cache-first")==="cache-first"&&this.cached&&Date.now()-this.cached.at<this.cacheTtlMs)return this.cached.info;let n=await i(this.http,"GET",`/subscribers/${encodeURIComponent(this.appUserId)}`),s=new c(n);this.cached={info:s,at:Date.now()};for(let C of this.listeners)try{C(s)}catch{}return s}async isEntitled(t){return(await this.getCustomerInfo()).isActive(t)}async checkEntitlement(t,e={}){return i(this.http,"POST","/check",{app_user_id:this.appUserId,entitlement:t,sandbox:!!e.sandbox})}async getOfferings(){return i(this.http,"GET","/offerings")}async reportPurchase(t){let e=await i(this.http,"POST",`/subscribers/${encodeURIComponent(this.appUserId)}/purchases`,{store:t.store??"",store_product_id:t.storeProductId??"",is_sandbox:!!t.isSandbox,purchase_token:t.purchaseToken??"",is_subscription:!!t.isSubscription,signed_transaction:t.signedTransaction??"",stripe_subscription_id:t.stripeSubscriptionId??""}),n=new c(e);this.cached={info:n,at:Date.now()};for(let s of this.listeners)try{s(n)}catch{}return n}addCustomerInfoUpdateListener(t){return this.listeners.add(t),()=>this.listeners.delete(t)}};var o=encodeURIComponent;function d(r){return typeof r=="string"?r:"id"in r?{id:r.id}:{store:r.store,store_product_id:r.storeProductId}}function p(r){return typeof r=="string"?{seg:o(r),qs:""}:"id"in r?{seg:o(r.id),qs:""}:{seg:o(r.storeProductId),qs:`?store=${o(r.store)}`}}var E=r=>r?.includeArchived?"include_archived=true":"";async function $(r,t){try{return await r()}catch(e){if(e instanceof a&&e.apiCode===t&&e.body?.existing)return e.body.existing;throw e}}var l=class{constructor(t){this.http=t}async list(t){let e=E(t);return(await i(this.http,"GET",`/entitlements${e?`?${e}`:""}`)).entitlements}get(t){return i(this.http,"GET",`/entitlements/${o(t)}`)}create(t){return i(this.http,"POST","/entitlements",{key:t.key,name:t.name,description:t.description,products:t.products?.map(d)})}ensure(t){return $(()=>this.create(t),"entitlement_exists")}update(t,e){return i(this.http,"PATCH",`/entitlements/${o(t)}`,{name:e.name,description:e.description,products:e.products?.map(d)})}delete(t){return i(this.http,"DELETE",`/entitlements/${o(t)}`)}async products(t,e){let n=E(e);return(await i(this.http,"GET",`/entitlements/${o(t)}/products${n?`?${n}`:""}`)).products}attachProducts(t,e){return i(this.http,"POST",`/entitlements/${o(t)}/attach_products`,{products:e.map(d)})}detachProducts(t,e){return i(this.http,"POST",`/entitlements/${o(t)}/detach_products`,{products:e.map(d)})}archive(t){return i(this.http,"POST",`/entitlements/${o(t)}/archive`)}unarchive(t){return i(this.http,"POST",`/entitlements/${o(t)}/unarchive`)}},g=class{constructor(t){this.http=t}async list(t){let e=new URLSearchParams;t?.store&&e.set("store",t.store),t?.entitlement&&e.set("entitlement",t.entitlement),t?.includeArchived&&e.set("include_archived","true");let n=e.toString();return(await i(this.http,"GET",`/products${n?`?${n}`:""}`)).products}get(t){let{seg:e,qs:n}=p(t);return i(this.http,"GET",`/products/${e}${n}`)}create(t){return i(this.http,"POST","/products",{store:t.store,store_product_id:t.storeProductId,type:t.type,duration:t.duration,display_name:t.displayName,price_micros:t.priceMicros,currency:t.currency,entitlements:t.entitlements})}ensure(t){return $(()=>this.create(t),"product_exists")}update(t,e){let{seg:n,qs:s}=p(t);return i(this.http,"PATCH",`/products/${n}${s}`,{display_name:e.displayName,price_micros:e.priceMicros,currency:e.currency,entitlements:e.entitlements})}delete(t){let{seg:e,qs:n}=p(t);return i(this.http,"DELETE",`/products/${e}${n}`)}attachEntitlements(t,e){let{seg:n,qs:s}=p(t);return i(this.http,"POST",`/products/${n}/attach_entitlements${s}`,{entitlements:e})}detachEntitlements(t,e){let{seg:n,qs:s}=p(t);return i(this.http,"POST",`/products/${n}/detach_entitlements${s}`,{entitlements:e})}archive(t){let{seg:e,qs:n}=p(t);return i(this.http,"POST",`/products/${e}/archive${n}`)}unarchive(t){let{seg:e,qs:n}=p(t);return i(this.http,"POST",`/products/${e}/unarchive${n}`)}},m=class{constructor(t){this.http=t}async list(t){let e=E(t);return(await i(this.http,"GET",`/offerings/all${e?`?${e}`:""}`)).offerings}get(t){return i(this.http,"GET",`/offerings/${o(t)}`)}create(t){return i(this.http,"POST","/offerings",{identifier:t.identifier,display_name:t.displayName,is_current:t.isCurrent,metadata:t.metadata,packages:t.packages?.map(x)})}update(t,e){return i(this.http,"PATCH",`/offerings/${o(t)}`,{display_name:e.displayName,is_current:e.isCurrent,metadata:e.metadata})}delete(t){return i(this.http,"DELETE",`/offerings/${o(t)}`)}archive(t){return i(this.http,"POST",`/offerings/${o(t)}/archive`)}unarchive(t){return i(this.http,"POST",`/offerings/${o(t)}/unarchive`)}async packages(t){return(await i(this.http,"GET",`/offerings/${o(t)}/packages`)).packages}addPackage(t,e){return i(this.http,"POST",`/offerings/${o(t)}/packages`,x(e))}updatePackage(t,e,n){return i(this.http,"PATCH",`/offerings/${o(t)}/packages/${o(e)}`,{display_name:n.displayName,position:n.position,product:n.product===void 0?void 0:d(n.product)})}deletePackage(t,e){return i(this.http,"DELETE",`/offerings/${o(t)}/packages/${o(e)}`)}};function x(r){return{identifier:r.identifier,product:d(r.product),position:r.position,display_name:r.displayName}}var b=class{constructor(t){if(!t.apiKey)throw new a("apiKey is required.",0,"config");if(!t.apiKey.startsWith("sk_"))throw new a("EntitleHubServer needs a secret (sk_) key. For client reads, use the EntitleHub class with a pk_ key.",0,"config");this.http={baseUrl:t.baseUrl??"https://entitlehub.com/v1",apiKey:t.apiKey,fetchImpl:t.fetchImpl,timeoutMs:15e3},this.entitlements=new l(this.http),this.products=new g(this.http),this.offerings=new m(this.http)}async reportPurchase(t,e){let n=await i(this.http,"POST",`/subscribers/${encodeURIComponent(t)}/purchases`,{store:e.store,store_product_id:e.storeProductId,is_sandbox:!!e.isSandbox,transaction_id:e.transactionId??"",purchase_token:e.purchaseToken??"",is_subscription:!!e.isSubscription,signed_transaction:e.signedTransaction??"",stripe_subscription_id:e.stripeSubscriptionId??""});return new c(n)}async grantEntitlement(t,e,n={}){let s=await i(this.http,"POST",`/subscribers/${encodeURIComponent(t)}/grant`,{entitlement:e,duration_days:n.durationDays??0,is_sandbox:!!n.isSandbox});return new c(s)}async getCustomerInfo(t){let e=await i(this.http,"GET",`/subscribers/${encodeURIComponent(t)}`);return new c(e)}async check(t,e,n={}){return i(this.http,"POST","/check",{app_user_id:t,entitlement:e,sandbox:!!n.sandbox})}};0&&(module.exports={CustomerInfo,EntitleHub,EntitleHubError,EntitleHubServer,EntitlementsApi,OfferingsApi,ProductsApi});

package/dist/index.d.cts

@@ -80,7 +80,7 @@ interface PurchaseInput {
 }
 
 /**
- * Ergonomic wrapper around a subscriber's active entitlements — the object your UI reads.
+ * Ergonomic wrapper around a subscriber's active entitlements, the object your UI reads.
  *
  *   const info = await eh.getCustomerInfo();
  *   if (info.isActive("pro")) showProFeatures();
@@ -112,11 +112,16 @@ interface EntitleHubOptions {
     fetchImpl?: typeof fetch;
     /** How long a cached CustomerInfo is considered fresh, ms (default 5 min). */
     cacheTtlMs?: number;
+    /**
+     * Identifies the calling SDK as `name/version`, e.g. "react-native/0.1.5". Wrapper SDKs set this
+     * so the dashboard can flag an out-of-date SDK. Defaults to this package's own name/version.
+     */
+    client?: string;
 }
 type CustomerInfoListener = (info: CustomerInfo) => void;
 type FetchPolicy = "cache-first" | "network-only";
 /**
- * The client-side EntitleHub SDK — configure once, then ask "what is this user entitled to?".
+ * The client-side EntitleHub SDK: configure once, then ask "what is this user entitled to?".
  * Safe for browsers, React Native, and Expo (publishable key only; never ship a secret key).
  *
  *   const eh = new EntitleHub({ apiKey: "pk_live_…", appUserId: user.id });
@@ -146,7 +151,7 @@ declare class EntitleHub {
     checkEntitlement(entitlementId: string, opts?: {
         sandbox?: boolean;
     }): Promise<CheckResult>;
-    /** The project's entitlements + products — for building a paywall. */
+    /** The project's entitlements + products: for building a paywall. */
     getOfferings(): Promise<Offerings>;
     /**
      * Report a VALIDATED store purchase for the current user and return the updated entitlements.
@@ -169,30 +174,273 @@ declare class EntitleHub {
     addCustomerInfoUpdateListener(listener: CustomerInfoListener): () => void;
 }
 
+declare class EntitleHubError extends Error {
+    readonly status: number;
+    /** SDK-level category: config | auth | http | network | no_fetch. */
+    readonly code: string;
+    /**
+     * The API's own machine-readable code, when it sent one (e.g. "entitlement_exists",
+     * "ambiguous_product", "rate_limited"). Branch on this, not on the message text.
+     */
+    readonly apiCode?: string;
+    /** The full error body, for context the API attaches: `existing`, `candidates`, `unknown`, `grants`… */
+    readonly body?: Record<string, unknown>;
+    constructor(message: string, status: number, code?: string, body?: Record<string, unknown>);
+}
+interface HttpOptions {
+    baseUrl: string;
+    apiKey: string;
+    /** Network-error retries for idempotent reads (default 2). */
+    retries?: number;
+    timeoutMs?: number;
+    fetchImpl?: typeof fetch;
+    /** Identifies the calling SDK, e.g. "react-native/0.1.5". Reported to the dashboard. */
+    client?: string;
+}
+
+type ProductType = "subscription" | "non_consumable" | "consumable";
+type Duration = "P1W" | "P1M" | "P3M" | "P6M" | "P1Y";
+/** A product by id, by SKU (when it is on one store), or by explicit store + SKU. */
+type ProductRef = string | {
+    id: string;
+} | {
+    store: Store;
+    storeProductId: string;
+};
+interface CatalogEntitlement {
+    object: "entitlement";
+    id: string;
+    key: string;
+    name: string;
+    description: string;
+    products: {
+        id: string;
+        store: Store;
+        store_product_id: string;
+    }[];
+    active_grants: number;
+    created_at: string | null;
+    archived_at: string | null;
+}
+interface CatalogProduct {
+    object: "product";
+    id: string;
+    store: Store;
+    store_product_id: string;
+    type: ProductType;
+    duration: Duration | null;
+    display_name: string;
+    price_micros: number;
+    currency: string;
+    entitlements: string[];
+    active_grants: number;
+    archived_at: string | null;
+}
+interface CatalogPackage {
+    object: "package";
+    id: string;
+    identifier: string;
+    display_name: string;
+    position: number;
+    store: Store;
+    store_product_id: string;
+    product: CatalogProduct | null;
+}
+interface CatalogOffering {
+    object: "offering";
+    id: string;
+    identifier: string;
+    display_name: string;
+    is_current: boolean;
+    metadata: Record<string, unknown> | null;
+    packages: CatalogPackage[];
+    created_at: string;
+    archived_at: string | null;
+}
+/** An offering as the SDK-facing /v1/offerings/all returns it: packages joined with their product. */
+interface ListedOffering {
+    id: string;
+    identifier: string;
+    display_name: string;
+    is_current: boolean;
+    metadata: Record<string, unknown> | null;
+    archived_at: string | null;
+    packages: {
+        id: string;
+        identifier: string;
+        display_name: string;
+        position: number;
+        store: Store;
+        store_product_id: string;
+        product: {
+            display_name: string;
+            type: string;
+            price_micros: number;
+            currency: string;
+            entitlements: string[];
+        } | null;
+    }[];
+}
+interface Deleted {
+    object: string;
+    id: string;
+    deleted: true;
+}
+interface CreateEntitlementInput {
+    /** The exact string your app checks with isEntitled(). Can't change later. */
+    key: string;
+    name?: string;
+    description?: string;
+    /** Products that grant it, attached in the same call. */
+    products?: ProductRef[];
+}
+interface CreateProductInput {
+    store: Store;
+    storeProductId: string;
+    type: ProductType;
+    /** Required for subscriptions. */
+    duration?: Duration;
+    displayName?: string;
+    /** Integer micros (4.99 → 4_990_000). */
+    priceMicros?: number;
+    currency?: string;
+    /** Entitlement keys this product grants. */
+    entitlements?: string[];
+}
+interface PackageInput {
+    identifier: string;
+    product: ProductRef;
+    position?: number;
+    displayName?: string;
+}
+declare class EntitlementsApi {
+    private http;
+    constructor(http: HttpOptions);
+    list(opts?: {
+        includeArchived?: boolean;
+    }): Promise<CatalogEntitlement[]>;
+    /** By id or key. */
+    get(ref: string): Promise<CatalogEntitlement>;
+    create(input: CreateEntitlementInput): Promise<CatalogEntitlement>;
+    /** Create, or return the entitlement that already has this key. */
+    ensure(input: CreateEntitlementInput): Promise<CatalogEntitlement>;
+    /** `products`, when given, REPLACES the set of products that grant it. */
+    update(ref: string, patch: {
+        name?: string;
+        description?: string;
+        products?: ProductRef[];
+    }): Promise<CatalogEntitlement>;
+    /** Refused (409 `entitlement_in_use`) once anyone has been granted it. Archive instead. */
+    delete(ref: string): Promise<Deleted>;
+    products(ref: string, opts?: {
+        includeArchived?: boolean;
+    }): Promise<CatalogProduct[]>;
+    attachProducts(ref: string, products: ProductRef[]): Promise<CatalogEntitlement>;
+    detachProducts(ref: string, products: ProductRef[]): Promise<CatalogEntitlement>;
+    /** Hide it from listings. Never takes access away from anyone who holds it. */
+    archive(ref: string): Promise<CatalogEntitlement>;
+    unarchive(ref: string): Promise<CatalogEntitlement>;
+}
+declare class ProductsApi {
+    private http;
+    constructor(http: HttpOptions);
+    list(opts?: {
+        store?: Store;
+        entitlement?: string;
+        includeArchived?: boolean;
+    }): Promise<CatalogProduct[]>;
+    get(ref: ProductRef): Promise<CatalogProduct>;
+    create(input: CreateProductInput): Promise<CatalogProduct>;
+    /** Create, or return the product that already has this store + SKU. */
+    ensure(input: CreateProductInput): Promise<CatalogProduct>;
+    /** `entitlements`, when given, REPLACES what it grants (future purchases only). */
+    update(ref: ProductRef, patch: {
+        displayName?: string;
+        priceMicros?: number;
+        currency?: string;
+        entitlements?: string[];
+    }): Promise<CatalogProduct>;
+    /** Refused (409 `product_in_use`) once anyone has bought it. Archive instead. */
+    delete(ref: ProductRef): Promise<Deleted>;
+    attachEntitlements(ref: ProductRef, entitlements: string[]): Promise<CatalogProduct>;
+    detachEntitlements(ref: ProductRef, entitlements: string[]): Promise<CatalogProduct>;
+    /** Retire a SKU: gone from listings and paywalls; existing subscribers keep access and renewals. */
+    archive(ref: ProductRef): Promise<CatalogProduct>;
+    unarchive(ref: ProductRef): Promise<CatalogProduct>;
+}
+declare class OfferingsApi {
+    private http;
+    constructor(http: HttpOptions);
+    /** Every offering. Archived ones only with includeArchived. */
+    list(opts?: {
+        includeArchived?: boolean;
+    }): Promise<ListedOffering[]>;
+    /** By id or identifier. */
+    get(ref: string): Promise<CatalogOffering>;
+    create(input: {
+        identifier: string;
+        displayName?: string;
+        isCurrent?: boolean;
+        metadata?: Record<string, unknown>;
+        packages?: PackageInput[];
+    }): Promise<CatalogOffering>;
+    /** `isCurrent: true` makes it the offering /current serves. `metadata: null` clears it. */
+    update(ref: string, patch: {
+        displayName?: string;
+        isCurrent?: true;
+        metadata?: Record<string, unknown> | null;
+    }): Promise<CatalogOffering>;
+    delete(ref: string): Promise<Deleted>;
+    archive(ref: string): Promise<CatalogOffering>;
+    unarchive(ref: string): Promise<CatalogOffering>;
+    packages(ref: string): Promise<CatalogPackage[]>;
+    addPackage(ref: string, input: PackageInput): Promise<CatalogPackage>;
+    /** `pkg` is the package id, or its identifier when that is used on one store only. */
+    updatePackage(ref: string, pkg: string, patch: {
+        displayName?: string;
+        position?: number;
+        product?: ProductRef;
+    }): Promise<CatalogPackage>;
+    deletePackage(ref: string, pkg: string): Promise<Deleted>;
+}
+
 interface EntitleHubServerOptions {
-    /** Your secret key (sk_live_… / sk_test_…). SERVER ONLY — never ship this to a client. */
+    /** Your secret key (sk_live_… / sk_test_…). SERVER ONLY, never ship this to a client. */
     apiKey: string;
     baseUrl?: string;
     fetchImpl?: typeof fetch;
 }
 /**
- * The server-side EntitleHub SDK — report purchases and grant entitlements from your backend.
+ * The server-side EntitleHub SDK: report purchases and grant entitlements from your backend.
  * Keep this on your server; it uses a secret key.
  *
  *   const eh = new EntitleHubServer({ apiKey: process.env.ENTITLEHUB_SECRET_KEY! });
  *   await eh.reportPurchase(userId, { store: "app_store", storeProductId: "pro_monthly" });
+ *
+ * Manage the catalog from code too (every create has an `ensure` twin that returns the existing
+ * row instead of failing, so a setup script can run on every deploy):
+ *
+ *   await eh.entitlements.ensure({ key: "pro", name: "Pro" });
+ *   await eh.products.ensure({ store: "stripe", storeProductId: "price_1Q…", type: "subscription",
+ *                              duration: "P1M", priceMicros: 9_990_000, entitlements: ["pro"] });
  */
 declare class EntitleHubServer {
     private http;
+    /** Catalog API: entitlements. */
+    readonly entitlements: EntitlementsApi;
+    /** Catalog API: products and their entitlement mappings. */
+    readonly products: ProductsApi;
+    /** Catalog API: paywall offerings and packages. */
+    readonly offerings: OfferingsApi;
     constructor(opts: EntitleHubServerOptions);
     /**
      * Report a completed store purchase → writes the mapped entitlement grant(s). Returns updated info.
      *
      * Three modes (pick one):
      *   • Google (validated): { store:"play", storeProductId, purchaseToken, isSubscription }
-     *   • Apple (validated):  { signedTransaction }   — store/product are read from the JWS
-     *   • Stripe (validated): { stripeSubscriptionId } — validated via your Stripe secret key
-     *   • Trusted server-report: { store, storeProductId } — no store validation; only when you've
+     *   • Apple (validated):  { signedTransaction }  , store/product are read from the JWS
+     *   • Stripe (validated): { stripeSubscriptionId }, validated via your Stripe secret key
+     *   • Trusted server-report: { store, storeProductId }, no store validation; only when you've
      *     already validated the receipt elsewhere.
      */
     reportPurchase(appUserId: string, purchase: PurchaseInput): Promise<CustomerInfo>;
@@ -209,10 +457,4 @@ declare class EntitleHubServer {
     }): Promise<CheckResult>;
 }
 
-declare class EntitleHubError extends Error {
-    readonly status: number;
-    readonly code: string;
-    constructor(message: string, status: number, code?: string);
-}
-
-export { type ActiveEntitlement, type CheckResult, CustomerInfo, type CustomerInfoListener, type CustomerInfoResponse, EntitleHub, EntitleHubError, type EntitleHubOptions, EntitleHubServer, type EntitleHubServerOptions, type EntitlementStatus, type FetchPolicy, type OfferingEntitlement, type OfferingProduct, type Offerings, type PurchaseInput, type Store };
+export { type ActiveEntitlement, type CatalogEntitlement, type CatalogOffering, type CatalogPackage, type CatalogProduct, type CheckResult, type CreateEntitlementInput, type CreateProductInput, CustomerInfo, type CustomerInfoListener, type CustomerInfoResponse, type Deleted, type Duration, EntitleHub, EntitleHubError, type EntitleHubOptions, EntitleHubServer, type EntitleHubServerOptions, type EntitlementStatus, EntitlementsApi, type FetchPolicy, type ListedOffering, type OfferingEntitlement, type OfferingProduct, type Offerings, OfferingsApi, type PackageInput, type ProductRef, type ProductType, ProductsApi, type PurchaseInput, type Store };

package/dist/index.d.ts

@@ -80,7 +80,7 @@ interface PurchaseInput {
 }
 
 /**
- * Ergonomic wrapper around a subscriber's active entitlements — the object your UI reads.
+ * Ergonomic wrapper around a subscriber's active entitlements, the object your UI reads.
  *
  *   const info = await eh.getCustomerInfo();
  *   if (info.isActive("pro")) showProFeatures();
@@ -112,11 +112,16 @@ interface EntitleHubOptions {
     fetchImpl?: typeof fetch;
     /** How long a cached CustomerInfo is considered fresh, ms (default 5 min). */
     cacheTtlMs?: number;
+    /**
+     * Identifies the calling SDK as `name/version`, e.g. "react-native/0.1.5". Wrapper SDKs set this
+     * so the dashboard can flag an out-of-date SDK. Defaults to this package's own name/version.
+     */
+    client?: string;
 }
 type CustomerInfoListener = (info: CustomerInfo) => void;
 type FetchPolicy = "cache-first" | "network-only";
 /**
- * The client-side EntitleHub SDK — configure once, then ask "what is this user entitled to?".
+ * The client-side EntitleHub SDK: configure once, then ask "what is this user entitled to?".
  * Safe for browsers, React Native, and Expo (publishable key only; never ship a secret key).
  *
  *   const eh = new EntitleHub({ apiKey: "pk_live_…", appUserId: user.id });
@@ -146,7 +151,7 @@ declare class EntitleHub {
     checkEntitlement(entitlementId: string, opts?: {
         sandbox?: boolean;
     }): Promise<CheckResult>;
-    /** The project's entitlements + products — for building a paywall. */
+    /** The project's entitlements + products: for building a paywall. */
     getOfferings(): Promise<Offerings>;
     /**
      * Report a VALIDATED store purchase for the current user and return the updated entitlements.
@@ -169,30 +174,273 @@ declare class EntitleHub {
     addCustomerInfoUpdateListener(listener: CustomerInfoListener): () => void;
 }
 
+declare class EntitleHubError extends Error {
+    readonly status: number;
+    /** SDK-level category: config | auth | http | network | no_fetch. */
+    readonly code: string;
+    /**
+     * The API's own machine-readable code, when it sent one (e.g. "entitlement_exists",
+     * "ambiguous_product", "rate_limited"). Branch on this, not on the message text.
+     */
+    readonly apiCode?: string;
+    /** The full error body, for context the API attaches: `existing`, `candidates`, `unknown`, `grants`… */
+    readonly body?: Record<string, unknown>;
+    constructor(message: string, status: number, code?: string, body?: Record<string, unknown>);
+}
+interface HttpOptions {
+    baseUrl: string;
+    apiKey: string;
+    /** Network-error retries for idempotent reads (default 2). */
+    retries?: number;
+    timeoutMs?: number;
+    fetchImpl?: typeof fetch;
+    /** Identifies the calling SDK, e.g. "react-native/0.1.5". Reported to the dashboard. */
+    client?: string;
+}
+
+type ProductType = "subscription" | "non_consumable" | "consumable";
+type Duration = "P1W" | "P1M" | "P3M" | "P6M" | "P1Y";
+/** A product by id, by SKU (when it is on one store), or by explicit store + SKU. */
+type ProductRef = string | {
+    id: string;
+} | {
+    store: Store;
+    storeProductId: string;
+};
+interface CatalogEntitlement {
+    object: "entitlement";
+    id: string;
+    key: string;
+    name: string;
+    description: string;
+    products: {
+        id: string;
+        store: Store;
+        store_product_id: string;
+    }[];
+    active_grants: number;
+    created_at: string | null;
+    archived_at: string | null;
+}
+interface CatalogProduct {
+    object: "product";
+    id: string;
+    store: Store;
+    store_product_id: string;
+    type: ProductType;
+    duration: Duration | null;
+    display_name: string;
+    price_micros: number;
+    currency: string;
+    entitlements: string[];
+    active_grants: number;
+    archived_at: string | null;
+}
+interface CatalogPackage {
+    object: "package";
+    id: string;
+    identifier: string;
+    display_name: string;
+    position: number;
+    store: Store;
+    store_product_id: string;
+    product: CatalogProduct | null;
+}
+interface CatalogOffering {
+    object: "offering";
+    id: string;
+    identifier: string;
+    display_name: string;
+    is_current: boolean;
+    metadata: Record<string, unknown> | null;
+    packages: CatalogPackage[];
+    created_at: string;
+    archived_at: string | null;
+}
+/** An offering as the SDK-facing /v1/offerings/all returns it: packages joined with their product. */
+interface ListedOffering {
+    id: string;
+    identifier: string;
+    display_name: string;
+    is_current: boolean;
+    metadata: Record<string, unknown> | null;
+    archived_at: string | null;
+    packages: {
+        id: string;
+        identifier: string;
+        display_name: string;
+        position: number;
+        store: Store;
+        store_product_id: string;
+        product: {
+            display_name: string;
+            type: string;
+            price_micros: number;
+            currency: string;
+            entitlements: string[];
+        } | null;
+    }[];
+}
+interface Deleted {
+    object: string;
+    id: string;
+    deleted: true;
+}
+interface CreateEntitlementInput {
+    /** The exact string your app checks with isEntitled(). Can't change later. */
+    key: string;
+    name?: string;
+    description?: string;
+    /** Products that grant it, attached in the same call. */
+    products?: ProductRef[];
+}
+interface CreateProductInput {
+    store: Store;
+    storeProductId: string;
+    type: ProductType;
+    /** Required for subscriptions. */
+    duration?: Duration;
+    displayName?: string;
+    /** Integer micros (4.99 → 4_990_000). */
+    priceMicros?: number;
+    currency?: string;
+    /** Entitlement keys this product grants. */
+    entitlements?: string[];
+}
+interface PackageInput {
+    identifier: string;
+    product: ProductRef;
+    position?: number;
+    displayName?: string;
+}
+declare class EntitlementsApi {
+    private http;
+    constructor(http: HttpOptions);
+    list(opts?: {
+        includeArchived?: boolean;
+    }): Promise<CatalogEntitlement[]>;
+    /** By id or key. */
+    get(ref: string): Promise<CatalogEntitlement>;
+    create(input: CreateEntitlementInput): Promise<CatalogEntitlement>;
+    /** Create, or return the entitlement that already has this key. */
+    ensure(input: CreateEntitlementInput): Promise<CatalogEntitlement>;
+    /** `products`, when given, REPLACES the set of products that grant it. */
+    update(ref: string, patch: {
+        name?: string;
+        description?: string;
+        products?: ProductRef[];
+    }): Promise<CatalogEntitlement>;
+    /** Refused (409 `entitlement_in_use`) once anyone has been granted it. Archive instead. */
+    delete(ref: string): Promise<Deleted>;
+    products(ref: string, opts?: {
+        includeArchived?: boolean;
+    }): Promise<CatalogProduct[]>;
+    attachProducts(ref: string, products: ProductRef[]): Promise<CatalogEntitlement>;
+    detachProducts(ref: string, products: ProductRef[]): Promise<CatalogEntitlement>;
+    /** Hide it from listings. Never takes access away from anyone who holds it. */
+    archive(ref: string): Promise<CatalogEntitlement>;
+    unarchive(ref: string): Promise<CatalogEntitlement>;
+}
+declare class ProductsApi {
+    private http;
+    constructor(http: HttpOptions);
+    list(opts?: {
+        store?: Store;
+        entitlement?: string;
+        includeArchived?: boolean;
+    }): Promise<CatalogProduct[]>;
+    get(ref: ProductRef): Promise<CatalogProduct>;
+    create(input: CreateProductInput): Promise<CatalogProduct>;
+    /** Create, or return the product that already has this store + SKU. */
+    ensure(input: CreateProductInput): Promise<CatalogProduct>;
+    /** `entitlements`, when given, REPLACES what it grants (future purchases only). */
+    update(ref: ProductRef, patch: {
+        displayName?: string;
+        priceMicros?: number;
+        currency?: string;
+        entitlements?: string[];
+    }): Promise<CatalogProduct>;
+    /** Refused (409 `product_in_use`) once anyone has bought it. Archive instead. */
+    delete(ref: ProductRef): Promise<Deleted>;
+    attachEntitlements(ref: ProductRef, entitlements: string[]): Promise<CatalogProduct>;
+    detachEntitlements(ref: ProductRef, entitlements: string[]): Promise<CatalogProduct>;
+    /** Retire a SKU: gone from listings and paywalls; existing subscribers keep access and renewals. */
+    archive(ref: ProductRef): Promise<CatalogProduct>;
+    unarchive(ref: ProductRef): Promise<CatalogProduct>;
+}
+declare class OfferingsApi {
+    private http;
+    constructor(http: HttpOptions);
+    /** Every offering. Archived ones only with includeArchived. */
+    list(opts?: {
+        includeArchived?: boolean;
+    }): Promise<ListedOffering[]>;
+    /** By id or identifier. */
+    get(ref: string): Promise<CatalogOffering>;
+    create(input: {
+        identifier: string;
+        displayName?: string;
+        isCurrent?: boolean;
+        metadata?: Record<string, unknown>;
+        packages?: PackageInput[];
+    }): Promise<CatalogOffering>;
+    /** `isCurrent: true` makes it the offering /current serves. `metadata: null` clears it. */
+    update(ref: string, patch: {
+        displayName?: string;
+        isCurrent?: true;
+        metadata?: Record<string, unknown> | null;
+    }): Promise<CatalogOffering>;
+    delete(ref: string): Promise<Deleted>;
+    archive(ref: string): Promise<CatalogOffering>;
+    unarchive(ref: string): Promise<CatalogOffering>;
+    packages(ref: string): Promise<CatalogPackage[]>;
+    addPackage(ref: string, input: PackageInput): Promise<CatalogPackage>;
+    /** `pkg` is the package id, or its identifier when that is used on one store only. */
+    updatePackage(ref: string, pkg: string, patch: {
+        displayName?: string;
+        position?: number;
+        product?: ProductRef;
+    }): Promise<CatalogPackage>;
+    deletePackage(ref: string, pkg: string): Promise<Deleted>;
+}
+
 interface EntitleHubServerOptions {
-    /** Your secret key (sk_live_… / sk_test_…). SERVER ONLY — never ship this to a client. */
+    /** Your secret key (sk_live_… / sk_test_…). SERVER ONLY, never ship this to a client. */
     apiKey: string;
     baseUrl?: string;
     fetchImpl?: typeof fetch;
 }
 /**
- * The server-side EntitleHub SDK — report purchases and grant entitlements from your backend.
+ * The server-side EntitleHub SDK: report purchases and grant entitlements from your backend.
  * Keep this on your server; it uses a secret key.
  *
  *   const eh = new EntitleHubServer({ apiKey: process.env.ENTITLEHUB_SECRET_KEY! });
  *   await eh.reportPurchase(userId, { store: "app_store", storeProductId: "pro_monthly" });
+ *
+ * Manage the catalog from code too (every create has an `ensure` twin that returns the existing
+ * row instead of failing, so a setup script can run on every deploy):
+ *
+ *   await eh.entitlements.ensure({ key: "pro", name: "Pro" });
+ *   await eh.products.ensure({ store: "stripe", storeProductId: "price_1Q…", type: "subscription",
+ *                              duration: "P1M", priceMicros: 9_990_000, entitlements: ["pro"] });
  */
 declare class EntitleHubServer {
     private http;
+    /** Catalog API: entitlements. */
+    readonly entitlements: EntitlementsApi;
+    /** Catalog API: products and their entitlement mappings. */
+    readonly products: ProductsApi;
+    /** Catalog API: paywall offerings and packages. */
+    readonly offerings: OfferingsApi;
     constructor(opts: EntitleHubServerOptions);
     /**
      * Report a completed store purchase → writes the mapped entitlement grant(s). Returns updated info.
      *
      * Three modes (pick one):
      *   • Google (validated): { store:"play", storeProductId, purchaseToken, isSubscription }
-     *   • Apple (validated):  { signedTransaction }   — store/product are read from the JWS
-     *   • Stripe (validated): { stripeSubscriptionId } — validated via your Stripe secret key
-     *   • Trusted server-report: { store, storeProductId } — no store validation; only when you've
+     *   • Apple (validated):  { signedTransaction }  , store/product are read from the JWS
+     *   • Stripe (validated): { stripeSubscriptionId }, validated via your Stripe secret key
+     *   • Trusted server-report: { store, storeProductId }, no store validation; only when you've
      *     already validated the receipt elsewhere.
      */
     reportPurchase(appUserId: string, purchase: PurchaseInput): Promise<CustomerInfo>;
@@ -209,10 +457,4 @@ declare class EntitleHubServer {
     }): Promise<CheckResult>;
 }
 
-declare class EntitleHubError extends Error {
-    readonly status: number;
-    readonly code: string;
-    constructor(message: string, status: number, code?: string);
-}
-
-export { type ActiveEntitlement, type CheckResult, CustomerInfo, type CustomerInfoListener, type CustomerInfoResponse, EntitleHub, EntitleHubError, type EntitleHubOptions, EntitleHubServer, type EntitleHubServerOptions, type EntitlementStatus, type FetchPolicy, type OfferingEntitlement, type OfferingProduct, type Offerings, type PurchaseInput, type Store };
+export { type ActiveEntitlement, type CatalogEntitlement, type CatalogOffering, type CatalogPackage, type CatalogProduct, type CheckResult, type CreateEntitlementInput, type CreateProductInput, CustomerInfo, type CustomerInfoListener, type CustomerInfoResponse, type Deleted, type Duration, EntitleHub, EntitleHubError, type EntitleHubOptions, EntitleHubServer, type EntitleHubServerOptions, type EntitlementStatus, EntitlementsApi, type FetchPolicy, type ListedOffering, type OfferingEntitlement, type OfferingProduct, type Offerings, OfferingsApi, type PackageInput, type ProductRef, type ProductType, ProductsApi, type PurchaseInput, type Store };

package/dist/index.js

@@ -1 +1 @@
-var a=class{constructor(t){this.appUserId=t.app_user_id,this.entitlements=t.active_entitlements??[];let e={};for(let s of this.entitlements)e[s.entitlement]=s;this.active=e}isActive(t){return!!this.active[t]}get activeEntitlementIds(){return Object.keys(this.active)}expirationDate(t){let e=this.active[t];if(e)return e.expires_at?new Date(e.expires_at):null}};var r=class extends Error{constructor(t,e,s="error"){super(t),this.name="EntitleHubError",this.status=e,this.code=s}},w=n=>new Promise(t=>setTimeout(t,n));async function c(n,t,e,s){let i=n.fetchImpl??globalThis.fetch;if(!i)throw new r("No fetch implementation available. On Node <18, pass fetchImpl.",0,"no_fetch");let l=`${n.baseUrl.replace(/\/$/,"")}${e}`,d=t==="GET"?n.retries??2:0,f;for(let u=0;u<=d;u++){let b=new AbortController,y=n.timeoutMs?setTimeout(()=>b.abort(),n.timeoutMs):void 0;try{let o=await i(l,{method:t,headers:{Authorization:`Bearer ${n.apiKey}`,...s?{"Content-Type":"application/json"}:{}},body:s?JSON.stringify(s):void 0,signal:b.signal}),g=await o.text(),p=g?C(g):{};if(!o.ok){let I=`HTTP ${o.status}`;throw p&&typeof p=="object"&&"error"in p&&(I=String(p.error)),new r(I,o.status,o.status===401||o.status===403?"auth":"http")}return p}catch(o){if(f=o,o instanceof r)throw o;u<d&&await w(250*(u+1))}finally{y&&clearTimeout(y)}}throw new r(`Network request failed: ${String(f?.message??f)}`,0,"network")}function C(n){try{return JSON.parse(n)}catch{return{}}}var h=class{constructor(t){this.listeners=new Set;if(!t.apiKey)throw new r("apiKey is required.",0,"config");if(!t.appUserId)throw new r("appUserId is required.",0,"config");if(t.apiKey.startsWith("sk_"))throw new r("Never use a secret (sk_) key in the client SDK \u2014 use your publishable (pk_) key.",0,"config");this.appUserId=t.appUserId,this.cacheTtlMs=t.cacheTtlMs??5*6e4,this.http={baseUrl:t.baseUrl??"https://entitlehub.com/v1",apiKey:t.apiKey,fetchImpl:t.fetchImpl,timeoutMs:15e3}}get currentAppUserId(){return this.appUserId}async logIn(t){return this.appUserId=t,this.cached=void 0,this.getCustomerInfo({fetchPolicy:"network-only"})}logOut(){this.cached=void 0}async getCustomerInfo(t={}){if((t.fetchPolicy??"cache-first")==="cache-first"&&this.cached&&Date.now()-this.cached.at<this.cacheTtlMs)return this.cached.info;let s=await c(this.http,"GET",`/subscribers/${encodeURIComponent(this.appUserId)}`),i=new a(s);this.cached={info:i,at:Date.now()};for(let l of this.listeners)try{l(i)}catch{}return i}async isEntitled(t){return(await this.getCustomerInfo()).isActive(t)}async checkEntitlement(t,e={}){return c(this.http,"POST","/check",{app_user_id:this.appUserId,entitlement:t,sandbox:!!e.sandbox})}async getOfferings(){return c(this.http,"GET","/offerings")}async reportPurchase(t){let e=await c(this.http,"POST",`/subscribers/${encodeURIComponent(this.appUserId)}/purchases`,{store:t.store??"",store_product_id:t.storeProductId??"",is_sandbox:!!t.isSandbox,purchase_token:t.purchaseToken??"",is_subscription:!!t.isSubscription,signed_transaction:t.signedTransaction??"",stripe_subscription_id:t.stripeSubscriptionId??""}),s=new a(e);this.cached={info:s,at:Date.now()};for(let i of this.listeners)try{i(s)}catch{}return s}addCustomerInfoUpdateListener(t){return this.listeners.add(t),()=>this.listeners.delete(t)}};var m=class{constructor(t){if(!t.apiKey)throw new r("apiKey is required.",0,"config");if(!t.apiKey.startsWith("sk_"))throw new r("EntitleHubServer needs a secret (sk_) key. For client reads, use the EntitleHub class with a pk_ key.",0,"config");this.http={baseUrl:t.baseUrl??"https://entitlehub.com/v1",apiKey:t.apiKey,fetchImpl:t.fetchImpl,timeoutMs:15e3}}async reportPurchase(t,e){let s=await c(this.http,"POST",`/subscribers/${encodeURIComponent(t)}/purchases`,{store:e.store,store_product_id:e.storeProductId,is_sandbox:!!e.isSandbox,transaction_id:e.transactionId??"",purchase_token:e.purchaseToken??"",is_subscription:!!e.isSubscription,signed_transaction:e.signedTransaction??"",stripe_subscription_id:e.stripeSubscriptionId??""});return new a(s)}async grantEntitlement(t,e,s={}){let i=await c(this.http,"POST",`/subscribers/${encodeURIComponent(t)}/grant`,{entitlement:e,duration_days:s.durationDays??0,is_sandbox:!!s.isSandbox});return new a(i)}async getCustomerInfo(t){let e=await c(this.http,"GET",`/subscribers/${encodeURIComponent(t)}`);return new a(e)}async check(t,e,s={}){return c(this.http,"POST","/check",{app_user_id:t,entitlement:e,sandbox:!!s.sandbox})}};export{a as CustomerInfo,h as EntitleHub,r as EntitleHubError,m as EntitleHubServer};
+var u=class{constructor(t){this.appUserId=t.app_user_id,this.entitlements=t.active_entitlements??[];let e={};for(let r of this.entitlements)e[r.entitlement]=r;this.active=e}isActive(t){return!!this.active[t]}get activeEntitlementIds(){return Object.keys(this.active)}expirationDate(t){let e=this.active[t];if(e)return e.expires_at?new Date(e.expires_at):null}};var v="0.3.0";var a=class extends Error{constructor(t,e,r="error",o){super(t),this.name="EntitleHubError",this.status=e,this.code=r,this.body=o,this.apiCode=typeof o?.code=="string"?o.code:void 0}},R=n=>new Promise(t=>setTimeout(t,n));async function i(n,t,e,r){let o=n.fetchImpl??globalThis.fetch;if(!o)throw new a("No fetch implementation available. On Node <18, pass fetchImpl.",0,"no_fetch");let y=`${n.baseUrl.replace(/\/$/,"")}${e}`,E=t==="GET"?n.retries??2:0,b;for(let f=0;f<=E;f++){let k=new AbortController,T=n.timeoutMs?setTimeout(()=>k.abort(),n.timeoutMs):void 0;try{let c=await o(y,{method:t,headers:{Authorization:`Bearer ${n.apiKey}`,"X-EntitleHub-Client":n.client??`${"js"}/${v}`,...r?{"Content-Type":"application/json"}:{}},body:r?JSON.stringify(r):void 0,signal:k.signal}),w=await c.text(),h=w?H(w):{};if(!c.ok){let O=`HTTP ${c.status}`,P=h&&typeof h=="object"?h:void 0;throw P&&"error"in P&&(O=String(P.error)),new a(O,c.status,c.status===401||c.status===403?"auth":"http",P)}return h}catch(c){if(b=c,c instanceof a)throw c;f<E&&await R(250*(f+1))}finally{T&&clearTimeout(T)}}throw new a(`Network request failed: ${String(b?.message??b)}`,0,"network")}function H(n){try{return JSON.parse(n)}catch{return{}}}var C=class{constructor(t){this.listeners=new Set;if(!t.apiKey)throw new a("apiKey is required.",0,"config");if(!t.appUserId)throw new a("appUserId is required.",0,"config");if(t.apiKey.startsWith("sk_"))throw new a("Never use a secret (sk_) key in the client SDK. Use your publishable (pk_) key.",0,"config");this.appUserId=t.appUserId,this.cacheTtlMs=t.cacheTtlMs??5*6e4,this.http={baseUrl:t.baseUrl??"https://entitlehub.com/v1",apiKey:t.apiKey,fetchImpl:t.fetchImpl,timeoutMs:15e3,client:t.client}}get currentAppUserId(){return this.appUserId}async logIn(t){return this.appUserId=t,this.cached=void 0,this.getCustomerInfo({fetchPolicy:"network-only"})}logOut(){this.cached=void 0}async getCustomerInfo(t={}){if((t.fetchPolicy??"cache-first")==="cache-first"&&this.cached&&Date.now()-this.cached.at<this.cacheTtlMs)return this.cached.info;let r=await i(this.http,"GET",`/subscribers/${encodeURIComponent(this.appUserId)}`),o=new u(r);this.cached={info:o,at:Date.now()};for(let y of this.listeners)try{y(o)}catch{}return o}async isEntitled(t){return(await this.getCustomerInfo()).isActive(t)}async checkEntitlement(t,e={}){return i(this.http,"POST","/check",{app_user_id:this.appUserId,entitlement:t,sandbox:!!e.sandbox})}async getOfferings(){return i(this.http,"GET","/offerings")}async reportPurchase(t){let e=await i(this.http,"POST",`/subscribers/${encodeURIComponent(this.appUserId)}/purchases`,{store:t.store??"",store_product_id:t.storeProductId??"",is_sandbox:!!t.isSandbox,purchase_token:t.purchaseToken??"",is_subscription:!!t.isSubscription,signed_transaction:t.signedTransaction??"",stripe_subscription_id:t.stripeSubscriptionId??""}),r=new u(e);this.cached={info:r,at:Date.now()};for(let o of this.listeners)try{o(r)}catch{}return r}addCustomerInfoUpdateListener(t){return this.listeners.add(t),()=>this.listeners.delete(t)}};var s=encodeURIComponent;function d(n){return typeof n=="string"?n:"id"in n?{id:n.id}:{store:n.store,store_product_id:n.storeProductId}}function p(n){return typeof n=="string"?{seg:s(n),qs:""}:"id"in n?{seg:s(n.id),qs:""}:{seg:s(n.storeProductId),qs:`?store=${s(n.store)}`}}var _=n=>n?.includeArchived?"include_archived=true":"";async function x(n,t){try{return await n()}catch(e){if(e instanceof a&&e.apiCode===t&&e.body?.existing)return e.body.existing;throw e}}var l=class{constructor(t){this.http=t}async list(t){let e=_(t);return(await i(this.http,"GET",`/entitlements${e?`?${e}`:""}`)).entitlements}get(t){return i(this.http,"GET",`/entitlements/${s(t)}`)}create(t){return i(this.http,"POST","/entitlements",{key:t.key,name:t.name,description:t.description,products:t.products?.map(d)})}ensure(t){return x(()=>this.create(t),"entitlement_exists")}update(t,e){return i(this.http,"PATCH",`/entitlements/${s(t)}`,{name:e.name,description:e.description,products:e.products?.map(d)})}delete(t){return i(this.http,"DELETE",`/entitlements/${s(t)}`)}async products(t,e){let r=_(e);return(await i(this.http,"GET",`/entitlements/${s(t)}/products${r?`?${r}`:""}`)).products}attachProducts(t,e){return i(this.http,"POST",`/entitlements/${s(t)}/attach_products`,{products:e.map(d)})}detachProducts(t,e){return i(this.http,"POST",`/entitlements/${s(t)}/detach_products`,{products:e.map(d)})}archive(t){return i(this.http,"POST",`/entitlements/${s(t)}/archive`)}unarchive(t){return i(this.http,"POST",`/entitlements/${s(t)}/unarchive`)}},g=class{constructor(t){this.http=t}async list(t){let e=new URLSearchParams;t?.store&&e.set("store",t.store),t?.entitlement&&e.set("entitlement",t.entitlement),t?.includeArchived&&e.set("include_archived","true");let r=e.toString();return(await i(this.http,"GET",`/products${r?`?${r}`:""}`)).products}get(t){let{seg:e,qs:r}=p(t);return i(this.http,"GET",`/products/${e}${r}`)}create(t){return i(this.http,"POST","/products",{store:t.store,store_product_id:t.storeProductId,type:t.type,duration:t.duration,display_name:t.displayName,price_micros:t.priceMicros,currency:t.currency,entitlements:t.entitlements})}ensure(t){return x(()=>this.create(t),"product_exists")}update(t,e){let{seg:r,qs:o}=p(t);return i(this.http,"PATCH",`/products/${r}${o}`,{display_name:e.displayName,price_micros:e.priceMicros,currency:e.currency,entitlements:e.entitlements})}delete(t){let{seg:e,qs:r}=p(t);return i(this.http,"DELETE",`/products/${e}${r}`)}attachEntitlements(t,e){let{seg:r,qs:o}=p(t);return i(this.http,"POST",`/products/${r}/attach_entitlements${o}`,{entitlements:e})}detachEntitlements(t,e){let{seg:r,qs:o}=p(t);return i(this.http,"POST",`/products/${r}/detach_entitlements${o}`,{entitlements:e})}archive(t){let{seg:e,qs:r}=p(t);return i(this.http,"POST",`/products/${e}/archive${r}`)}unarchive(t){let{seg:e,qs:r}=p(t);return i(this.http,"POST",`/products/${e}/unarchive${r}`)}},m=class{constructor(t){this.http=t}async list(t){let e=_(t);return(await i(this.http,"GET",`/offerings/all${e?`?${e}`:""}`)).offerings}get(t){return i(this.http,"GET",`/offerings/${s(t)}`)}create(t){return i(this.http,"POST","/offerings",{identifier:t.identifier,display_name:t.displayName,is_current:t.isCurrent,metadata:t.metadata,packages:t.packages?.map(S)})}update(t,e){return i(this.http,"PATCH",`/offerings/${s(t)}`,{display_name:e.displayName,is_current:e.isCurrent,metadata:e.metadata})}delete(t){return i(this.http,"DELETE",`/offerings/${s(t)}`)}archive(t){return i(this.http,"POST",`/offerings/${s(t)}/archive`)}unarchive(t){return i(this.http,"POST",`/offerings/${s(t)}/unarchive`)}async packages(t){return(await i(this.http,"GET",`/offerings/${s(t)}/packages`)).packages}addPackage(t,e){return i(this.http,"POST",`/offerings/${s(t)}/packages`,S(e))}updatePackage(t,e,r){return i(this.http,"PATCH",`/offerings/${s(t)}/packages/${s(e)}`,{display_name:r.displayName,position:r.position,product:r.product===void 0?void 0:d(r.product)})}deletePackage(t,e){return i(this.http,"DELETE",`/offerings/${s(t)}/packages/${s(e)}`)}};function S(n){return{identifier:n.identifier,product:d(n.product),position:n.position,display_name:n.displayName}}var I=class{constructor(t){if(!t.apiKey)throw new a("apiKey is required.",0,"config");if(!t.apiKey.startsWith("sk_"))throw new a("EntitleHubServer needs a secret (sk_) key. For client reads, use the EntitleHub class with a pk_ key.",0,"config");this.http={baseUrl:t.baseUrl??"https://entitlehub.com/v1",apiKey:t.apiKey,fetchImpl:t.fetchImpl,timeoutMs:15e3},this.entitlements=new l(this.http),this.products=new g(this.http),this.offerings=new m(this.http)}async reportPurchase(t,e){let r=await i(this.http,"POST",`/subscribers/${encodeURIComponent(t)}/purchases`,{store:e.store,store_product_id:e.storeProductId,is_sandbox:!!e.isSandbox,transaction_id:e.transactionId??"",purchase_token:e.purchaseToken??"",is_subscription:!!e.isSubscription,signed_transaction:e.signedTransaction??"",stripe_subscription_id:e.stripeSubscriptionId??""});return new u(r)}async grantEntitlement(t,e,r={}){let o=await i(this.http,"POST",`/subscribers/${encodeURIComponent(t)}/grant`,{entitlement:e,duration_days:r.durationDays??0,is_sandbox:!!r.isSandbox});return new u(o)}async getCustomerInfo(t){let e=await i(this.http,"GET",`/subscribers/${encodeURIComponent(t)}`);return new u(e)}async check(t,e,r={}){return i(this.http,"POST","/check",{app_user_id:t,entitlement:e,sandbox:!!r.sandbox})}};export{u as CustomerInfo,C as EntitleHub,a as EntitleHubError,I as EntitleHubServer,l as EntitlementsApi,m as OfferingsApi,g as ProductsApi};

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@entitlehub/sdk",
-  "version": "0.2.0",
-  "description": "EntitleHub SDK — one entitlement API across App Store, Google Play, Stripe, and web. Works in browsers, React Native, Expo, and Node.",
+  "version": "0.3.0",
+  "description": "EntitleHub SDK: one entitlement API across App Store, Google Play, Stripe, and web. Works in browsers, React Native, Expo, and Node.",
   "keywords": [
     "entitlehub",
     "entitlements",
@@ -37,7 +37,7 @@
   "scripts": {
     "build": "tsup src/index.ts --format esm,cjs --dts --clean --minify",
     "typecheck": "tsc --noEmit",
-    "test": "node --test",
+    "test": "node --test \"test/*.test.mjs\"",
     "prepublishOnly": "npm run build"
   },
   "engines": {