@chatarmin/os 1.7.0 → 1.8.0

package/README.md

@@ -194,6 +194,8 @@ const [primary] = await os.contacts.list("comp_xxx", true)
 
 Check and manage feature access for companies.
 
+**Identifiers:** pass **`featureCode`** on input (e.g. `"ai_credit"`). Responses include `featureCode` and `featureAccessId`. Codes are set at feature create and are not renamed via the API — change display with `featureName`, or create a new feature and migrate for a real rename. See [`product-billing-api.md`](../../docs/engineering/product-billing-api.md#feature-identifiers-featurecode) for details.
+
 #### `features.check(input)`
 
 Check if a company has access to a specific feature.
@@ -294,6 +296,8 @@ if (access.canUse) {
 
 Track usage, claim subscriptions, and manage billing.
 
+> **API reference:** [`docs/engineering/product-billing-api.md`](../../docs/engineering/product-billing-api.md) — full request/response shapes for every `os.billing.*` method.
+
 #### `billing.trackUsage(input)`
 
 Track usage for a metered feature.
@@ -354,25 +358,398 @@ console.log({
 })
 ```
 
-#### `billing.getStatus(companyId)`
+#### `billing.getStatus(companyIdOrInput)`
+
+Quick Stripe subscription status for a company — `activeSubscriptions` (`active` / `trialing` / `past_due`), resolved billing profile, and enabled feature count. Scoped to the product link's billing profile when `externalOrgId` is provided.
 
-Get billing status overview for a company.
+See [Product-scoped billing profile — `getStatus` example](../../docs/engineering/product-billing-api.md#example-getstatus-for-subscription-health) for the full walkthrough + sample response.
 
 ```typescript
-const status = await os.billing.getStatus("comp_xxx")
+const status = await os.billing.getStatus('ee0f4a19-2b69-4969-8807-d0013f1670ee')
+
+const statusByOrg = await os.billing.getStatus({ externalOrgId: 'org_kKZHiUHBSjdu' })
+
+if (status.activeSubscriptions[0]?.status === 'past_due') {
+  // gate access for this external org
+}
 
 console.log({
-  hasBilling: status.hasBillingProfile,
-  subscriptions: status.activeSubscriptions.length,
+  stripeCustomer: status.billingProfile?.stripeCustomerId,
+  subscriptionStatus: status.activeSubscriptions[0]?.status,
   features: status.enabledFeaturesCount,
 })
+```
+
+#### `billing.getOverview(input)`
+
+Combined billing page payload: company, billing profile, primary subscription, and recent invoices.
+
+```typescript
+const overview = await os.billing.getOverview({
+  companyId: "comp_xxx",
+  invoiceLimit: 12,
+  includeUsage: true, // optional: embed usage rows
+})
+
+console.log({
+  plan: overview.subscription?.tier?.name,
+  status: overview.subscription?.status,
+  paymentMethod: overview.billingProfile?.primaryPaymentMethod,
+  invoices: overview.invoices.length,
+  usageRows: overview.usage?.length,
+})
+```
+
+#### `billing.getUsage(companyIdOrInput, options?)`
+
+Metronome-style usage aggregates. Returns `{ data: UsageRecord[] }` — feature-first nesting with per-feature billing cycles.
+
+**Company scope:** pass **`companyId`** as the first string argument, or pass an input object with **`companyId`** or **`externalOrgId`** (one required). Prefer `externalOrgId` when CX only knows the org slug — usage is scoped to that product link.
+
+```typescript
+// CX-native (single product link)
+const { data } = await os.billing.getUsage({
+  externalOrgId: 'org_FVCNOtEdpeeP',
+  windowSize: 'none',
+})
+
+// Or companyId as first arg
+const byCompany = await os.billing.getUsage('comp_xxx', { windowSize: 'none' })
+```
+
+- **`data[].featureCode`** — stable feature slug
+- **`data[].cycles[]`** — billing cycles for this feature (`periodOffset`, bounds, `usage[]`)
+
+`windowSize` controls whether `usage` points are period totals or time buckets. Filter with **`featureCode`** (stable slug), not `featureAccessId` — see [Feature identifiers](../../docs/engineering/product-billing-api.md#feature-identifiers-featurecode).
+
+**`periodOffsetRange`** (time scope for whole billing cycles):
+
+| Intent | `periodOffsetRange` |
+|--------|---------------------|
+| Current cycle (default) | omit or `{ from: 0, to: 0 }` |
+| Previous only | `{ from: -1, to: -1 }` |
+| Current + previous | `{ from: -1, to: 0 }` |
+| 12-cycle picker | `{ from: -11, to: 0 }` |
+
+Multi-cycle range requires `windowSize: 'none'` (max 12 cycles). Cannot combine with `startingOn`/`endingBefore`.
+
+Every `cycles[]` bucket includes `subscriptionItem` and `summary` when it has usage rows. `usage[]` stays thin (`value` + dates).
+
+**Response shape:**
+
+```typescript
+interface UsageQueryResult {
+  data: UsageRecord[]
+}
+
+interface UsageRecord {
+  featureCode: string
+  featureName: string
+  cycles: UsageCycleBucket[]
+}
+
+interface UsageCycleBucket {
+  periodOffset: number
+  startingOn: Date
+  endingBefore: Date
+  label: string
+  subscriptionItem?: UsageSubscriptionItem // present when cycle has usage rows
+  summary?: UsageCycleSummary // totals + projection; present when cycle has usage rows
+  usage: UsagePoint[] // thin: value + dates (+ optional identity/grouping)
+}
+
+interface UsagePoint {
+  value: number
+  startingOn: Date
+  endingBefore: Date
+  featureAccessId?: string
+  meterCode?: string
+  groupKey?: string | null // with groupBy: 'productLink'
+  groupValue?: string | null
+  productLinkId?: string | null // groupBy: 'productLink', or bucketed multi-link companyId
+  productLinkLabel?: string | null
+  externalOrgId?: string | null
+}
+```
+
+Read billing from `cycle.summary` and `cycle.subscriptionItem` — not from `usage[]` points.
+
+`productLinkId` (+ label, `externalOrgId`) appears on `usage[]` points when `groupBy: 'productLink'`, or on bucketed `companyId` queries when multiple product links share the company (without `groupKey`).
+
+| `windowSize` | `cycles[].usage` | Billing context |
+| ------------ | ---------------- | --------------- |
+| `'none'` | 1 point | `subscriptionItem` + `summary` (always) |
+| `'day'` / `'week'` / `'month'` | N thin points | Same — billing once per cycle, not per bucket |
+
+#### Examples by `windowSize`
+
+**`windowSize: 'none'`** — period totals:
+
+```json
+{
+  "data": [{
+    "featureCode": "messages",
+    "featureName": "Messages",
+    "cycles": [{
+      "periodOffset": 0,
+      "startingOn": "2026-07-01T00:00:00.000Z",
+      "endingBefore": "2026-08-01T00:00:00.000Z",
+      "label": "Jul 1, 2026 – Aug 1, 2026",
+      "subscriptionItem": {
+        "includedQuantity": 100,
+        "unitAmountCents": 500,
+        "currency": "eur"
+      },
+      "summary": {
+        "totalUsage": 120,
+        "billableQuantity": 20,
+        "estimatedOverageCents": 10000,
+        "projectedBillableQuantity": 240,
+        "projectedOverageCents": 70000
+      },
+      "usage": [{
+        "value": 120,
+        "startingOn": "2026-07-01T00:00:00.000Z",
+        "endingBefore": "2026-08-01T00:00:00.000Z"
+      }]
+    }]
+  }]
+}
+```
 
-// Check active tier
-if (status.activeSubscriptions[0]?.tier) {
-  console.log(`Current tier: ${status.activeSubscriptions[0].tier.name}`)
+**`windowSize: 'day'`** — daily chart buckets:
+
+```json
+{
+  "data": [{
+    "featureCode": "messages",
+    "featureName": "Messages",
+    "cycles": [{
+      "periodOffset": 0,
+      "subscriptionItem": { "includedQuantity": 100 },
+      "summary": { "totalUsage": 20, "billableQuantity": 0 },
+      "usage": [
+        { "value": 8,  "startingOn": "2026-07-01T00:00:00.000Z", "endingBefore": "2026-07-02T00:00:00.000Z" },
+        { "value": 12, "startingOn": "2026-07-02T00:00:00.000Z", "endingBefore": "2026-07-03T00:00:00.000Z" }
+      ]
+    }]
+  }]
 }
 ```
 
+**Multi-cycle** (`periodOffsetRange: { from: -1, to: 0 }`):
+
+```json
+{
+  "data": [{
+    "featureCode": "messages",
+    "featureName": "Messages",
+    "cycles": [
+      { "periodOffset": 0, "label": "Jul 1 – Aug 1", "summary": { "totalUsage": 120, "billableQuantity": 20 }, "usage": [{ "value": 120 }] },
+      { "periodOffset": -1, "label": "Jun 1 – Jul 1", "summary": { "totalUsage": 98, "billableQuantity": 0 }, "usage": [{ "value": 98 }] }
+    ]
+  }]
+}
+```
+
+Full examples: [`docs/engineering/product-billing-api.md#billinggetusage`](../../docs/engineering/product-billing-api.md#billinggetusage)
+
+```typescript
+const { data } = await os.billing.getUsage('comp_xxx', { windowSize: 'none' })
+const messages = data.find((r) => r.featureCode === 'messages')
+const cycle = messages?.cycles[0]
+const currentTotal = cycle?.usage[0]?.value
+const overage = cycle?.summary?.billableQuantity
+const cost = cycle?.summary?.estimatedOverageCents
+
+const daily = await os.billing.getUsage('comp_xxx', {
+  windowSize: 'day',
+  featureCode: 'messages',
+})
+const dailySeries = (daily.data[0]?.cycles[0]?.usage ?? []).map((point) => ({
+  day: point.startingOn.toISOString().slice(0, 10),
+  usage: point.value,
+}))
+
+// Previous billing period totals
+const lastMonth = await os.billing.getUsage('comp_xxx', {
+  windowSize: 'none',
+  periodOffsetRange: { from: -1, to: -1 },
+})
+
+// Last 12 billing cycles (cycle picker)
+const history = await os.billing.getUsage('comp_xxx', {
+  windowSize: 'none',
+  periodOffsetRange: { from: -11, to: 0 },
+})
+// history.data[0].cycles → one bucket per period; cycle.usage[0] → period total
+
+// Custom sub-range within the current billing period (both dates required)
+// usage[] points cover the sub-range; summary totals match it; projections use the full cycle
+const week = await os.billing.getUsage('comp_xxx', {
+  windowSize: 'day',
+  featureCode: 'messages',
+  startingOn: new Date('2026-07-10T00:00:00Z'),
+  endingBefore: new Date('2026-07-17T00:00:00Z'),
+})
+```
+
+| `windowSize` | Shape |
+| ------------ | ----- |
+| `'none'` | One point per feature (collapsed total when multiple product links share a company; use `groupBy: 'productLink'` for per-link rows) |
+| `'day'` / `'week'` / `'month'` | One point per feature per bucket; one per link per bucket when multiple product links share the company (`productLinkId` on each point) |
+
+| Time scope | When to use |
+| ---------- | ----------- |
+| omit | Current billing period (default) |
+| `periodOffsetRange: { from: -1, to: -1 }` | Whole previous billing period |
+| `periodOffsetRange: { from: -11, to: 0 }` | Last 12 billing cycles |
+| `startingOn` + `endingBefore` | Sub-range inside the **current** period (clamped; totals follow sub-range; projections use full cycle) |
+
+#### `billing.exportUsage(companyIdOrInput, options?)`
+
+Export usage aggregates as CSV. Accepts the same company scope and query options as `getUsage` (plus implicit `format: 'csv'`). CSV includes a `periodOffset` column (first column) for multi-cycle exports. Filename uses exported period bounds: `usage_{windowSize}_{companyId}_{periodStart}_{periodEnd}.csv`.
+
+```typescript
+const csv = await os.billing.exportUsage({
+  externalOrgId: 'org_FVCNOtEdpeeP',
+  windowSize: 'none',
+  periodOffsetRange: { from: -11, to: 0 },
+})
+// csv.filename → "usage_none_<companyId>_2026-06-01_2026-08-01.csv"
+// csv.content → first line:
+// periodOffset,featureCode,featureName,value,startingOn,endingBefore,groupKey,groupValue,productLinkId,productLinkLabel,externalOrgId,includedQuantity,billableQuantity,quantityLimit,remaining,percentUsed,unitAmountCents,currency,estimatedOverageCents,projectedBillableQuantity,projectedOverageCents
+```
+
+#### `billing.listInvoices(companyIdOrInput, options?)`
+
+List invoices for a company (excludes draft/void).
+
+```typescript
+const { invoices } = await os.billing.listInvoices("comp_xxx", { limit: 24 })
+```
+
+#### `billing.getPaymentMethod(companyIdOrInput)`
+
+Payment method summary for the resolved billing profile.
+
+```typescript
+const { billingProfile } = await os.billing.getPaymentMethod("comp_xxx")
+```
+
+#### `billing.createPortalSession(input)`
+
+Open Stripe Customer Portal for manage-billing flows. `returnUrl` must be on an allowed product host (`products.metadata.billing.returnUrlHosts`).
+
+```typescript
+const { url } = await os.billing.createPortalSession({
+  companyId: "comp_xxx",
+  returnUrl: "https://app.example.com/settings/billing",
+})
+
+// Redirect the user to url
+```
+
+#### `billing.resolveInvoicePaymentUrl(input)`
+
+Resolve a hosted invoice payment URL for a specific invoice.
+
+```typescript
+const { hostedInvoiceUrl } = await os.billing.resolveInvoicePaymentUrl({
+  companyId: "comp_xxx",
+  invoiceId: "inv_xxx",
+})
+```
+
+#### `billing.listPastDuePaymentUrls(companyIdOrInput)`
+
+List overdue invoices with payment URLs.
+
+```typescript
+const { items } = await os.billing.listPastDuePaymentUrls("comp_xxx")
+```
+
+#### `billing.sendPastDueInvoice(input)`
+
+Email a past-due invoice via Stripe (when collection method is `send_invoice`).
+
+```typescript
+await os.billing.sendPastDueInvoice({
+  companyId: "comp_xxx",
+  invoiceId: "inv_xxx",
+})
+```
+
+#### `billing.syncCompanyFromStripe(input)`
+
+Pull billing profile, subscriptions, and feature links from Stripe.
+
+```typescript
+const result = await os.billing.syncCompanyFromStripe({
+  companyId: "comp_xxx",
+  stripeCustomerId: "cus_xxx",
+})
+
+console.log({
+  subscriptionsSynced: result.subscriptionsSynced,
+  featuresLinked: result.featuresLinked,
+})
+```
+
+#### `billing.relinkBillingProfile(input)`
+
+Replace the company's billing profile with a new Stripe customer (destructive).
+
+```typescript
+await os.billing.relinkBillingProfile({
+  companyId: "comp_xxx",
+  stripeCustomerId: "cus_new_xxx",
+})
+```
+
+#### `billing.ensureFeatureSubscription(input)`
+
+Ensure a metered feature is linked to a Stripe subscription item.
+
+```typescript
+const result = await os.billing.ensureFeatureSubscription({
+  companyId: "comp_xxx",
+  featureCode: "ai_credit",
+})
+
+console.log(result.action) // 'already_linked' | 'linked_existing' | 'created_new' | 'failed'
+```
+
+#### `billing.setUsage(input)`
+
+Set absolute usage (corrections / admin). Requires a `reason` for audit.
+
+```typescript
+const result = await os.billing.setUsage({
+  companyId: "comp_xxx",
+  featureCode: "messages",
+  absoluteValue: 420,
+  reason: "Reconcile after import",
+})
+
+console.log({
+  previous: result.previousUsage,
+  current: result.currentUsage,
+  delta: result.delta,
+})
+```
+
+#### `billing.getUsageHistory(companyId, featureCode, options?)`
+
+Raw usage events for audit/debug (not aggregated rollups).
+
+```typescript
+const events = await os.billing.getUsageHistory("comp_xxx", "messages", {
+  limit: 50,
+  eventType: "increment",
+})
+```
+
 ---
 
 ### Subscriptions & Tiers
@@ -813,6 +1190,7 @@ try {
 
 ## Related Documentation
 
+- **[Product billing API](../../docs/engineering/product-billing-api.md)** — Billing read APIs, `externalOrgId` scoping, and preview test tenants
 - **[QUICKSTART.md](./QUICKSTART.md)** — Quick publishing & installation guide
 - **[PUBLISHING.md](./PUBLISHING.md)** — Detailed publishing instructions
 - **[test-sdk.ts](./test-sdk.ts)** — Complete usage examples

package/dist/billing/client.d.ts

@@ -0,0 +1,8 @@
+import type { AppRouter } from '@chatarmin/api/trpc-types';
+import type { createTRPCClient } from '@trpc/client';
+import type { BillingClient } from './types';
+type SdkClient = ReturnType<typeof createTRPCClient<AppRouter>>;
+type SdkCall = <T>(operation: string, action: () => Promise<T>) => Promise<T>;
+export declare function createBillingClient(client: SdkClient, call: SdkCall): BillingClient;
+export {};
+//# sourceMappingURL=client.d.ts.map

package/dist/billing/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/billing/client.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,2BAA2B,CAAA;AAC1D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAA;AACpD,OAAO,KAAK,EACV,aAAa,EAyBd,MAAM,SAAS,CAAA;AAsChB,KAAK,SAAS,GAAG,UAAU,CAAC,OAAO,gBAAgB,CAAC,SAAS,CAAC,CAAC,CAAA;AAC/D,KAAK,OAAO,GAAG,CAAC,CAAC,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,CAAA;AAE7E,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,SAAS,EAAE,IAAI,EAAE,OAAO,GAAG,aAAa,CAiHnF"}

package/dist/billing/client.js

@@ -0,0 +1,46 @@
+function mergeBillingInput(companyIdOrInput, maybeOptions) {
+    if (typeof companyIdOrInput === 'string') {
+        return { companyId: companyIdOrInput, ...(maybeOptions ?? {}) };
+    }
+    return { ...companyIdOrInput, ...(maybeOptions ?? {}) };
+}
+function resolveBillingCompanyScopeInput(companyIdOrInput, maybeOptions) {
+    return mergeBillingInput(companyIdOrInput, maybeOptions);
+}
+function resolveBillingUsageInput(companyIdOrInput, maybeOptions) {
+    return mergeBillingInput(companyIdOrInput, maybeOptions);
+}
+function resolveBillingExportInput(companyIdOrInput, maybeOptions) {
+    return {
+        ...mergeBillingInput(companyIdOrInput, maybeOptions),
+        format: 'csv',
+    };
+}
+export function createBillingClient(client, call) {
+    return {
+        setUsage: (input) => call('billing.setUsage', () => client.billing.setUsage.mutate({
+            ...input,
+            source: 'api',
+        })),
+        getUsageHistory: (companyId, featureCode, options) => call('billing.getUsageHistory', () => client.billing.getUsageHistory.query({
+            companyId,
+            featureCode,
+            ...options,
+        })),
+        claimCheckout: (input) => call('billing.claimCheckout', () => client.billing.claimCheckout.mutate(input)),
+        linkSubscription: (input) => call('billing.linkSubscription', () => client.billing.linkSubscription.mutate(input)),
+        getStatus: (companyIdOrInput) => call('billing.getStatus', () => client.billing.getStatus.query(resolveBillingCompanyScopeInput(companyIdOrInput))),
+        getOverview: (input) => call('billing.getOverview', () => client.billing.getOverview.query(input)),
+        getUsage: (companyIdOrInput, maybeOptions) => call('billing.getUsage', () => client.billing.getUsage.query(resolveBillingUsageInput(companyIdOrInput, maybeOptions))),
+        exportUsage: (companyIdOrInput, maybeOptions) => call('billing.exportUsage', () => client.billing.exportUsage.query(resolveBillingExportInput(companyIdOrInput, maybeOptions))),
+        listInvoices: (companyIdOrInput, options) => call('billing.listInvoices', () => client.billing.listInvoices.query(resolveBillingCompanyScopeInput(companyIdOrInput, options))),
+        getPaymentMethod: (companyIdOrInput) => call('billing.getPaymentMethod', () => client.billing.getPaymentMethod.query(resolveBillingCompanyScopeInput(companyIdOrInput))),
+        createPortalSession: (input) => call('billing.createPortalSession', () => client.billing.createPortalSession.mutate(input)),
+        resolveInvoicePaymentUrl: (input) => call('billing.resolveProductInvoicePaymentUrl', () => client.billing.resolveProductInvoicePaymentUrl.mutate(input)),
+        listPastDuePaymentUrls: (companyIdOrInput) => call('billing.listProductPastDuePaymentUrls', () => client.billing.listProductPastDuePaymentUrls.query(resolveBillingCompanyScopeInput(companyIdOrInput))),
+        sendPastDueInvoice: (input) => call('billing.sendProductPastDueInvoice', () => client.billing.sendProductPastDueInvoice.mutate(input)),
+        syncCompanyFromStripe: (input) => call('billing.syncCompanyFromStripe', () => client.billing.syncCompanyFromStripe.mutate(input)),
+        relinkBillingProfile: (input) => call('billing.relinkBillingProfile', () => client.billing.relinkBillingProfile.mutate(input)),
+        ensureFeatureSubscription: (input) => call('billing.ensureFeatureSubscription', () => client.billing.ensureFeatureSubscription.mutate(input)),
+    };
+}

package/dist/billing/index.d.ts

@@ -0,0 +1,3 @@
+export { createBillingClient } from './client';
+export type { BillingClient, BillingInvoiceSummary, BillingOverview, BillingProfileSummary, BillingStatus, BillingStatusSubscription, BillingSubscriptionSummary, BillingUsageItem, ClaimCheckoutInput, ClaimCheckoutResult, CreateBillingPortalSessionInput, EnsureFeatureSubscriptionInput, EnsureFeatureSubscriptionResult, ExportUsageInput, ExportUsageResult, GetBillingOverviewInput, GetUsageInput, LinkSubscriptionInput, LinkSubscriptionResult, ListBillingInvoicesOptions, ProductBillingCompanyScopeInput, PeriodOffsetRange, RelinkBillingProfileInput, ResolveInvoicePaymentUrlInput, SendPastDueInvoiceInput, SendPastDueInvoiceResult, SetUsageInput, SyncCompanyFromStripeInput, SyncCompanyFromStripeResult, UsageAggregate, UsageCycleBucket, UsageCycleSummary, UsageGroupBy, UsagePoint, UsageQueryResult, UsageRecord, UsageSubscriptionItem, UsageResult, UsageWindowSize, } from './types';
+//# sourceMappingURL=index.d.ts.map

package/dist/billing/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/billing/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,MAAM,UAAU,CAAA;AAC9C,YAAY,EACV,aAAa,EACb,qBAAqB,EACrB,eAAe,EACf,qBAAqB,EACrB,aAAa,EACb,yBAAyB,EACzB,0BAA0B,EAC1B,gBAAgB,EAChB,kBAAkB,EAClB,mBAAmB,EACnB,+BAA+B,EAC/B,8BAA8B,EAC9B,+BAA+B,EAC/B,gBAAgB,EAChB,iBAAiB,EACjB,uBAAuB,EACvB,aAAa,EACb,qBAAqB,EACrB,sBAAsB,EACtB,0BAA0B,EAC1B,+BAA+B,EAC/B,iBAAiB,EACjB,yBAAyB,EACzB,6BAA6B,EAC7B,uBAAuB,EACvB,wBAAwB,EACxB,aAAa,EACb,0BAA0B,EAC1B,2BAA2B,EAC3B,cAAc,EACd,gBAAgB,EAChB,iBAAiB,EACjB,YAAY,EACZ,UAAU,EACV,gBAAgB,EAChB,WAAW,EACX,qBAAqB,EACrB,WAAW,EACX,eAAe,GAChB,MAAM,SAAS,CAAA"}

package/dist/billing/index.js

@@ -0,0 +1 @@
+export { createBillingClient } from './client';