@chatarmin/os 1.5.2 → 1.5.5

package/CHANGELOG.md

@@ -0,0 +1,16 @@
+# Changelog
+
+All notable changes to `@chatarmin/os` are documented here. The format is loosely based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+
+## Unreleased
+
+### Added
+
+- **`billing.getDashboardContext({ externalOrgId })`** — Single-call billing/usage context for a tenant: `companyId`, `productLinkId`, ordered feature rows with `remaining`, `canUse`, optional Stripe `billing`, and `billingDegraded` when subscription item linkage is missing. See SDK README “Dashboard context migration”.
+- **`features.listForProduct(input?)`** — Feature definition catalog for the API key’s product (no `companyId`). Documented in SDK README.
+
+### Migration
+
+- For dashboards, prefer `billing.getDashboardContext` + `features.listForProduct` instead of chaining `companies.getByProductLink` + `features.listAccess` and hardcoding `featureCode` lists. Older methods remain available.
+
+Product PRD (repo): `docs/prds/2026-03-23-product-sdk-dashboard-context.md`.

package/README.md

@@ -31,6 +31,7 @@
   - [Links](#links)
   - [Onboarding](#onboarding)
 - [Common Patterns](#common-patterns)
+- [Changelog](#changelog)
 - [TypeScript Support](#typescript-support)
 - [Configuration](#configuration)
 - [Error Handling](#error-handling)
@@ -275,6 +276,17 @@ for (const f of features) {
 }
 ```
 
+#### `features.listForProduct(input?)`
+
+List **feature definitions** attached to your product (the API key’s product). No company id—use for catalog UI, empty states, or multi-feature shells. Inactive features are omitted unless you pass `{ includeInactive: true }`.
+
+```typescript
+const defs = await os.features.listForProduct()
+for (const f of defs) {
+  console.log(`${f.code}: ${f.name}${f.hasQuantity ? " (metered)" : ""}`)
+}
+```
+
 #### `features.setAccess(input)`
 
 Update feature access with **partial config merge**.
@@ -335,6 +347,34 @@ if (access.canUse) {
 
 Track usage, claim subscriptions, and manage billing.
 
+#### `billing.getDashboardContext(input)`
+
+**Recommended** for billing/usage dashboards when you only have your tenant’s `externalOrgId`. One round-trip returns `companyId`, `productLinkId`, and an ordered list of features with usage, limits, optional Stripe `billing`, and `billingDegraded` when usage exists without a linked subscription item.
+
+Ordering uses `config_values.dashboard_order` or `dashboardOrder` when set; otherwise feature `displayOrder`.
+
+```typescript
+const ctx = await os.billing.getDashboardContext({
+  externalOrgId: "org_abc123",
+})
+
+console.log(ctx.companyId, ctx.productLinkId)
+for (const f of ctx.features) {
+  console.log(
+    f.featureCode,
+    f.currentUsage,
+    f.remaining,
+    f.canUse,
+    f.billingDegraded ? "(no Stripe period)" : "",
+    f.billing?.currentPeriodEnd
+  )
+}
+```
+
+If the tenant is not linked, the call fails with `NOT_FOUND` (same message style as other `externalOrgId` flows).
+
+See [Changelog](#changelog) for migrating from `getByProductLink` + `listAccess` and hardcoded feature codes.
+
 #### `billing.trackUsage(input)`
 
 Track usage for a metered feature.
@@ -749,6 +789,10 @@ import type {
   ContactInput,
   FeatureCheckInput,
   FeatureSetAccessInput,
+  BillingDashboardContext,
+  GetBillingDashboardContextInput,
+  ListProductFeatureCatalogInput,
+  ProductFeatureCatalogItem,
   TrackUsageInput,
   OnboardInput,
   OnboardResult,
@@ -827,6 +871,32 @@ try {
 
 ---
 
+## Changelog
+
+Release notes live in **[CHANGELOG.md](./CHANGELOG.md)**.
+
+### Dashboard context migration (PRD #194)
+
+**Before:** Resolve the company, then list access and filter client-side:
+
+```typescript
+const company = await os.companies.getByProductLink({ externalOrgId })
+if (!company) {
+  /* onboarding */
+}
+const rows = await os.features.listAccess({
+  companyId: company.id,
+  includeBillingDetails: true,
+})
+// Often: pick one featureCode in code, merge catalog labels manually
+```
+
+**After:** Single product-key call keyed by tenant id; use `features.listForProduct()` for definition labels and `os.billing.getDashboardContext({ externalOrgId })` for per-tenant state. Server applies link disambiguation, row shape, optional `billing`, `billingDegraded`, and dashboard ordering from OS `config_values`.
+
+`features.listAccess` / `getAccessByExternalOrgId` remain supported; opt in when you need the new contract.
+
+---
+
 ## Related Documentation
 
 - **[QUICKSTART.md](./QUICKSTART.md)** — Quick publishing & installation guide

package/dist/billing-get-dashboard-context.d.ts

@@ -0,0 +1,16 @@
+import type { BillingDashboardContext, GetBillingDashboardContextInput } from './types/billing-dashboard-context.js';
+type DashboardCaller = <T>(operation: string, fn: () => Promise<T>) => Promise<T>;
+type MinimalBillingClient = {
+    billing: {
+        getDashboardContext: {
+            query: (input: GetBillingDashboardContextInput) => Promise<unknown>;
+        };
+    };
+};
+/**
+ * Bound as `ChatarminOS.billing.getDashboardContext`.
+ * One call: resolve link by `externalOrgId`, return feature rows with usage, optional billing, `billingDegraded`.
+ */
+export declare function bindBillingGetDashboardContext(call: DashboardCaller, client: MinimalBillingClient): (input: GetBillingDashboardContextInput) => Promise<BillingDashboardContext>;
+export {};
+//# sourceMappingURL=billing-get-dashboard-context.d.ts.map

package/dist/billing-get-dashboard-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"billing-get-dashboard-context.d.ts","sourceRoot":"","sources":["../src/billing-get-dashboard-context.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,uBAAuB,EACvB,+BAA+B,EAChC,MAAM,sCAAsC,CAAA;AAE7C,KAAK,eAAe,GAAG,CAAC,CAAC,EACvB,SAAS,EAAE,MAAM,EACjB,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,KACjB,OAAO,CAAC,CAAC,CAAC,CAAA;AAEf,KAAK,oBAAoB,GAAG;IAC1B,OAAO,EAAE;QACP,mBAAmB,EAAE;YACnB,KAAK,EAAE,CAAC,KAAK,EAAE,+BAA+B,KAAK,OAAO,CAAC,OAAO,CAAC,CAAA;SACpE,CAAA;KACF,CAAA;CACF,CAAA;AAED;;;GAGG;AACH,wBAAgB,8BAA8B,CAC5C,IAAI,EAAE,eAAe,EACrB,MAAM,EAAE,oBAAoB,GAC3B,CACD,KAAK,EAAE,+BAA+B,KACnC,OAAO,CAAC,uBAAuB,CAAC,CAOpC"}

package/dist/billing-get-dashboard-context.js

@@ -0,0 +1,7 @@
+/**
+ * Bound as `ChatarminOS.billing.getDashboardContext`.
+ * One call: resolve link by `externalOrgId`, return feature rows with usage, optional billing, `billingDegraded`.
+ */
+export function bindBillingGetDashboardContext(call, client) {
+    return (input) => call('billing.getDashboardContext', () => client.billing.getDashboardContext.query(input));
+}

package/dist/chatarmin-os-billing-namespace.d.ts

@@ -0,0 +1,122 @@
+import type { AppRouter } from '@chatarmin/api';
+import type { createTRPCClient } from '@trpc/client';
+import type { ClaimCheckoutInput, EnsureFeatureSubscriptionInput, EnsureFeatureSubscriptionResult, LinkSubscriptionInput, RelinkBillingProfileInput, SetUsageInput, SyncCompanyFromStripeInput, SyncCompanyFromStripeResult, UsageResult } from './types/chatarmin-os-billing-inputs.js';
+export type ChatarminOsBillingCall = <T>(operation: string, fn: () => Promise<T>) => Promise<T>;
+export type ChatarminOsTrpcClient = ReturnType<typeof createTRPCClient<AppRouter>>;
+/**
+ * Billing, usage tracking, and subscription management (`os.billing`).
+ */
+export declare function createChatarminOsBillingNamespace(call: ChatarminOsBillingCall, client: ChatarminOsTrpcClient): {
+    getDashboardContext: (input: import("./index.js").GetBillingDashboardContextInput) => Promise<import("./index.js").BillingDashboardContext>;
+    setUsage: (input: SetUsageInput) => Promise<UsageResult>;
+    getUsageHistory: (companyId: string, featureCode: string, options?: {
+        limit?: number;
+        includeDelivered?: boolean;
+        eventType?: "increment" | "set" | "adjustment";
+    }) => Promise<{
+        id: string;
+        created_at: Date;
+        metadata: unknown;
+        event_type: string;
+        source: string;
+        billing_profile_id: string | null;
+        idempotency_key: string;
+        subscription_item_id: string | null;
+        feature_access_id: string | null;
+        meter_code: string;
+        quantity: number;
+        stripe_price_id: string | null;
+        event_time: Date;
+        previous_value: number | null;
+        adjustment_reason: string | null;
+        adjusts_event_id: string | null;
+        stripe_delivery_status: string;
+        stripe_delivery_attempts: number;
+        stripe_last_delivery_attempt_at: Date | null;
+        stripe_event_id: string | null;
+        stripe_delivery_error: string | null;
+        delivered_at: Date | null;
+    }[]>;
+    claimCheckout: (input: ClaimCheckoutInput) => Promise<{
+        success: boolean;
+        subscriptionId: string;
+        alreadyClaimed: boolean;
+        status?: undefined;
+    } | {
+        success: boolean;
+        subscriptionId: string;
+        alreadyClaimed: boolean;
+        status: import("stripe").Stripe.Subscription.Status;
+    }>;
+    linkSubscription: (input: LinkSubscriptionInput) => Promise<{
+        success: boolean;
+        subscriptionId: string;
+        alreadyLinked: boolean;
+        status?: undefined;
+        tierApplied?: undefined;
+        featuresApplied?: undefined;
+    } | {
+        success: boolean;
+        subscriptionId: string;
+        alreadyLinked: boolean;
+        status: import("stripe").Stripe.Subscription.Status;
+        tierApplied: boolean;
+        featuresApplied: number;
+    }>;
+    getStatus: (companyId: string) => Promise<{
+        hasBillingProfile: boolean;
+        stripeCustomerId: string | null;
+        billingProfiles: {
+            id: string;
+            organization_id: string;
+            created_at: Date;
+            updated_at: Date;
+            short_id: string | null;
+            name: string;
+            metadata: unknown;
+            status: string;
+            mrr_cents: number;
+            mrr_committed_cents: number;
+            mrr_usage_cents: number;
+            contract_start_at: Date | null;
+            contract_end_at: Date | null;
+            subscription_status: string;
+            max_days_overdue: number;
+            company_id: string | null;
+            stripe_customer_id: string;
+            link_status: string;
+            default_currency: string;
+            has_payment_method: boolean;
+            open_invoices_count: number;
+            open_amount_cents: number;
+            past_due_invoices_count: number;
+            past_due_amount_cents: number;
+            last_synced_at: Date | null;
+            company_group_id: string | null;
+        }[];
+        activeSubscriptions: {
+            id: string;
+            billingProfileId: string;
+            status: string;
+            stripeSubscriptionId: string | null;
+            currentPeriodEnd: Date | null;
+            trialEnd: Date | null;
+            tier: {
+                code: string;
+                name: string | null;
+            } | null;
+        }[];
+        enabledFeaturesCount: number;
+    }>;
+    syncCompanyFromStripe: (input: SyncCompanyFromStripeInput) => Promise<SyncCompanyFromStripeResult>;
+    relinkBillingProfile: (input: RelinkBillingProfileInput) => Promise<{
+        billingProfileId: string;
+        stripeCustomerId: string;
+        subscriptionsSynced: number;
+        subscriptionItemsSynced: number;
+        featuresLinked: number;
+        matchedMeters: number;
+    }>;
+    ensureFeatureSubscription: (input: EnsureFeatureSubscriptionInput) => Promise<EnsureFeatureSubscriptionResult>;
+};
+//# sourceMappingURL=chatarmin-os-billing-namespace.d.ts.map

package/dist/chatarmin-os-billing-namespace.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chatarmin-os-billing-namespace.d.ts","sourceRoot":"","sources":["../src/chatarmin-os-billing-namespace.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAA;AAC/C,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAA;AAEpD,OAAO,KAAK,EACV,kBAAkB,EAClB,8BAA8B,EAC9B,+BAA+B,EAC/B,qBAAqB,EACrB,yBAAyB,EACzB,aAAa,EACb,0BAA0B,EAC1B,2BAA2B,EAC3B,WAAW,EACZ,MAAM,wCAAwC,CAAA;AAE/C,MAAM,MAAM,sBAAsB,GAAG,CAAC,CAAC,EACrC,SAAS,EAAE,MAAM,EACjB,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,KACjB,OAAO,CAAC,CAAC,CAAC,CAAA;AAEf,MAAM,MAAM,qBAAqB,GAAG,UAAU,CAAC,OAAO,gBAAgB,CAAC,SAAS,CAAC,CAAC,CAAA;AAElF;;GAEG;AACH,wBAAgB,iCAAiC,CAC/C,IAAI,EAAE,sBAAsB,EAC5B,MAAM,EAAE,qBAAqB;;sBAKT,aAAa,KAAG,OAAO,CAAC,WAAW,CAAC;iCAWzC,MAAM,eACJ,MAAM,YACT;QACR,KAAK,CAAC,EAAE,MAAM,CAAA;QACd,gBAAgB,CAAC,EAAE,OAAO,CAAA;QAC1B,SAAS,CAAC,EAAE,WAAW,GAAG,KAAK,GAAG,YAAY,CAAA;KAC/C;;;;;;;;;;;;;;;;;;;;;;;;2BAUoB,kBAAkB;;;;;;;;;;;8BAKf,qBAAqB;;;;;;;;;;;;;;;2BAKxB,MAAM;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;mCAMpB,0BAA0B,KAChC,OAAO,CAAC,2BAA2B,CAAC;kCAKT,yBAAyB;;;;;;;;uCAM9C,8BAA8B,KACpC,OAAO,CAAC,+BAA+B,CAAC;EAK9C"}

package/dist/chatarmin-os-billing-namespace.js

@@ -0,0 +1,24 @@
+import { bindBillingGetDashboardContext } from './billing-get-dashboard-context.js';
+/**
+ * Billing, usage tracking, and subscription management (`os.billing`).
+ */
+export function createChatarminOsBillingNamespace(call, client) {
+    return {
+        getDashboardContext: bindBillingGetDashboardContext(call, client),
+        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: (companyId) => call("billing.getStatus", () => client.billing.getStatus.query({ companyId })),
+        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/features-list-for-product.d.ts

@@ -0,0 +1,26 @@
+import type { ListProductFeatureCatalogInput, ProductFeatureCatalogItem } from './types/product-feature-catalog.js';
+type ListForProductCaller = <T>(operation: string, fn: () => Promise<T>) => Promise<T>;
+type MinimalFeaturesClient = {
+    features: {
+        listForProduct: {
+            query: (input: {
+                includeInactive: boolean;
+            }) => Promise<unknown>;
+        };
+    };
+};
+/**
+ * Bound as `ChatarminOSClient.features.listForProduct`.
+ * Lists feature definitions for the API key’s product (no company id).
+ *
+ * @example
+ * ```typescript
+ * const defs = await os.features.listForProduct()
+ * for (const f of defs) {
+ *   console.log(`${f.code}: ${f.name}${f.hasQuantity ? ' (metered)' : ''}`)
+ * }
+ * ```
+ */
+export declare function bindFeaturesListForProduct(call: ListForProductCaller, client: MinimalFeaturesClient): (input?: ListProductFeatureCatalogInput) => Promise<ProductFeatureCatalogItem[]>;
+export {};
+//# sourceMappingURL=features-list-for-product.d.ts.map

package/dist/features-list-for-product.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"features-list-for-product.d.ts","sourceRoot":"","sources":["../src/features-list-for-product.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,8BAA8B,EAC9B,yBAAyB,EAC1B,MAAM,oCAAoC,CAAA;AAE3C,KAAK,oBAAoB,GAAG,CAAC,CAAC,EAC5B,SAAS,EAAE,MAAM,EACjB,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,KACjB,OAAO,CAAC,CAAC,CAAC,CAAA;AAEf,KAAK,qBAAqB,GAAG;IAC3B,QAAQ,EAAE;QACR,cAAc,EAAE;YACd,KAAK,EAAE,CAAC,KAAK,EAAE;gBAAE,eAAe,EAAE,OAAO,CAAA;aAAE,KAAK,OAAO,CAAC,OAAO,CAAC,CAAA;SACjE,CAAA;KACF,CAAA;CACF,CAAA;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,0BAA0B,CACxC,IAAI,EAAE,oBAAoB,EAC1B,MAAM,EAAE,qBAAqB,GAC5B,CAAC,KAAK,CAAC,EAAE,8BAA8B,KAAK,OAAO,CAAC,yBAAyB,EAAE,CAAC,CAOlF"}

package/dist/features-list-for-product.js

@@ -0,0 +1,17 @@
+/**
+ * Bound as `ChatarminOSClient.features.listForProduct`.
+ * Lists feature definitions for the API key’s product (no company id).
+ *
+ * @example
+ * ```typescript
+ * const defs = await os.features.listForProduct()
+ * for (const f of defs) {
+ *   console.log(`${f.code}: ${f.name}${f.hasQuantity ? ' (metered)' : ''}`)
+ * }
+ * ```
+ */
+export function bindFeaturesListForProduct(call, client) {
+    return (input) => call('features.listForProduct', () => client.features.listForProduct.query({
+        includeInactive: input?.includeInactive ?? false,
+    }));
+}