@chatarmin/os 1.5.8 → 1.7.0

package/README.md

@@ -30,8 +30,8 @@
   - [Subscriptions & Tiers](#subscriptions--tiers)
   - [Links](#links)
   - [Onboarding](#onboarding)
+  - [Product Webhooks](#product-webhooks)
 - [Common Patterns](#common-patterns)
-- [Changelog](#changelog)
 - [TypeScript Support](#typescript-support)
 - [Configuration](#configuration)
 - [Error Handling](#error-handling)
@@ -75,7 +75,7 @@ const result = await os.onboard({
 })
 
 console.log(result.companyId) // Use this for all future API calls
-console.log(result.linkStatus) // 'created' | 'linked' | 'already_linked'
+console.log(result.linkStatus) // 'created' | 'already_linked'
 ```
 
 ---
@@ -86,12 +86,12 @@ console.log(result.linkStatus) // 'created' | 'linked' | 'already_linked'
 
 Manage customer companies and their links to your product.
 
-#### `companies.getByProductLink(input)`
+#### `companies.get(input)`
 
-Look up a company by your external organization ID.
+Look up a company by your external organization ID or ChatarminOS company ID.
 
 ```typescript
-const company = await os.companies.getByProductLink({
+const company = await os.companies.get({
   externalOrgId: "org_abc123",
 })
 
@@ -132,48 +132,6 @@ await os.companies.update({
 })
 ```
 
-#### `companies.smartLink(input)`
-
-Intelligently find and link a company using hints.
-
-```typescript
-const result = await os.companies.smartLink({
-  externalOrgId: "org_abc123",
-  label: "My Product", // Display label for the product link (required)
-  hints: {
-    companyName: "Acme Inc",
-    domain: "acme.com",
-    emails: ["john@acme.com", "jane@acme.com"],
-  },
-  minConfidence: 0.7, // Default: 0.8
-})
-
-switch (result.status) {
-  case "already_linked":
-    console.log("Already linked to your product")
-    break
-  case "linked":
-    console.log(
-      `Auto-linked to ${result.customerName} (${result.confidence}% confidence)`
-    )
-    break
-  case "suggestions":
-    console.log("Multiple matches found:", result.suggestions)
-    break
-  case "no_match":
-    console.log("No matching company found")
-    break
-}
-```
-
-**Matching priority:**
-
-1. Domain match → 95% confidence
-2. Name match → up to 80% confidence
-3. Email domain match → 70% confidence
-
----
-
 ### Contacts
 
 Manage people associated with companies.
@@ -276,17 +234,6 @@ 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**.
@@ -347,34 +294,6 @@ 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.
@@ -600,7 +519,7 @@ const result = await os.onboard({
 console.log({
   companyId: result.companyId,
   companyName: result.companyName,
-  linkStatus: result.linkStatus, // 'created' | 'linked' | 'already_linked'
+  linkStatus: result.linkStatus, // 'created' | 'already_linked'
   tierApplied: result.billingStatus?.tierApplied,
 })
 ```
@@ -672,9 +591,6 @@ switch (result.linkStatus) {
   case "already_linked":
     console.log("Welcome back!")
     break
-  case "linked":
-    console.log("Found existing company, linked!")
-    break
   case "created":
     console.log("New company created!")
     break
@@ -683,6 +599,36 @@ switch (result.linkStatus) {
 
 ---
 
+## Product Webhooks
+
+When ChatarminOS pushes company and product-link changes to your app, verify the request with the SDK before handling the payload.
+
+```typescript
+import { webhooks } from "@chatarmin/os/webhooks"
+
+export async function POST(request: Request) {
+  const rawBody = await request.text()
+
+  const event = webhooks.constructEvent(
+    rawBody,
+    request.headers,
+    process.env.OS_WEBHOOK_SIGNING_SECRET!,
+  )
+
+  switch (`${event.type}.${event.action}`) {
+    case "company.updated":
+      // event.data, event.webhookId, event.idempotency_key
+      break
+  }
+
+  return Response.json({ received: true })
+}
+```
+
+Use `ChatarminOS.webhooks.constructEvent` if you already import the main client. Dedupe on `event.webhookId` or `event.idempotency_key`.
+
+---
+
 ## Common Patterns
 
 ### Feature Gating
@@ -784,15 +730,9 @@ import { ChatarminOS } from "@chatarmin/os"
 import type {
   ChatarminOSConfig,
   CreateCompanyInput,
-  SmartLinkInput,
-  SmartLinkResult,
   ContactInput,
   FeatureCheckInput,
   FeatureSetAccessInput,
-  BillingDashboardContext,
-  GetBillingDashboardContextInput,
-  ListProductFeatureCatalogInput,
-  ProductFeatureCatalogItem,
   TrackUsageInput,
   OnboardInput,
   OnboardResult,
@@ -871,32 +811,6 @@ 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/companies/client.d.ts

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

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

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/companies/client.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAA;AAC/C,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAA;AACpD,OAAO,KAAK,EACV,eAAe,EAOhB,MAAM,SAAS,CAAA;AAEhB,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,qBAAqB,CACnC,MAAM,EAAE,SAAS,EACjB,IAAI,EAAE,OAAO,GACZ,eAAe,CAiBjB"}

package/dist/companies/client.js

@@ -0,0 +1,8 @@
+export function createCompaniesClient(client, call) {
+    return {
+        get: (input) => call('companies.get', () => client.companies.get.query(input)),
+        list: (input) => call('companies.list', () => client.companies.listForProduct.query(input ?? {})),
+        create: (input) => call('companies.create', () => client.companies.createWithLink.mutate(input)),
+        update: (input) => call('companies.update', () => client.companies.updateCompany.mutate(input)),
+    };
+}

package/dist/companies/index.d.ts

@@ -0,0 +1,3 @@
+export { createCompaniesClient } from './client';
+export type { CompaniesClient, CompanyAssignee, CompanyAssignees, CreateCompanyInput, CreateCompanyResult, GetCompanyInput, LinkedCompany, ListCompaniesInput, ListCompaniesResult, ListLinkedCompaniesInput, ListLinkedCompaniesResult, ProductCompany, UpdateCompanyResult, } from './types';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/companies/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,qBAAqB,EAAE,MAAM,UAAU,CAAA;AAChD,YAAY,EACV,eAAe,EACf,eAAe,EACf,gBAAgB,EAChB,kBAAkB,EAClB,mBAAmB,EACnB,eAAe,EACf,aAAa,EACb,kBAAkB,EAClB,mBAAmB,EACnB,wBAAwB,EACxB,yBAAyB,EACzB,cAAc,EACd,mBAAmB,GACpB,MAAM,SAAS,CAAA"}

package/dist/companies/index.js

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

package/dist/companies/types.d.ts

@@ -0,0 +1,66 @@
+export interface CreateCompanyInput {
+    name: string;
+    domain?: string;
+    externalOrgId: string;
+    externalUserId?: string;
+    label?: string;
+    contactEmail?: string;
+    contactName?: string;
+    createdAt?: string;
+}
+export interface CompanyAssignee {
+    memberId: string;
+    displayName: string | null;
+    email: string | null;
+}
+export interface CompanyAssignees {
+    csm: CompanyAssignee | null;
+    sales: CompanyAssignee | null;
+}
+export interface ProductCompany {
+    id: string;
+    name: string;
+    shortId: string | null;
+    domain: string | null;
+    externalOrgId: string;
+    label: string | null;
+    externalUserId: string | null;
+    assignees: CompanyAssignees;
+}
+/** @deprecated Use ProductCompany */
+export type LinkedCompany = ProductCompany;
+export interface GetCompanyInput {
+    externalOrgId?: string;
+    companyId?: string;
+}
+export interface ListCompaniesInput {
+    limit?: number;
+    cursor?: string;
+}
+export interface ListCompaniesResult {
+    companies: ProductCompany[];
+    nextCursor?: string;
+}
+/** @deprecated Use ListCompaniesInput */
+export type ListLinkedCompaniesInput = ListCompaniesInput;
+/** @deprecated Use ListCompaniesResult */
+export type ListLinkedCompaniesResult = ListCompaniesResult;
+export interface CreateCompanyResult {
+    id: string;
+    shortId: string | null;
+    name: string;
+    externalOrgId: string;
+}
+export interface UpdateCompanyResult {
+    updated: boolean;
+}
+export interface CompaniesClient {
+    get: (input: GetCompanyInput) => Promise<ProductCompany | null>;
+    list: (input?: ListCompaniesInput) => Promise<ListCompaniesResult>;
+    create: (input: CreateCompanyInput) => Promise<CreateCompanyResult>;
+    update: (input: {
+        companyId: string;
+        createdAt?: string;
+    }) => Promise<UpdateCompanyResult>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/companies/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/companies/types.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,MAAM,CAAA;IACZ,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,aAAa,EAAE,MAAM,CAAA;IACrB,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE,MAAM,CAAA;IAChB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAA;IAC1B,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;CACrB;AAED,MAAM,WAAW,gBAAgB;IAC/B,GAAG,EAAE,eAAe,GAAG,IAAI,CAAA;IAC3B,KAAK,EAAE,eAAe,GAAG,IAAI,CAAA;CAC9B;AAED,MAAM,WAAW,cAAc;IAC7B,EAAE,EAAE,MAAM,CAAA;IACV,IAAI,EAAE,MAAM,CAAA;IACZ,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;IACtB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAA;IACrB,aAAa,EAAE,MAAM,CAAA;IACrB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;IACpB,cAAc,EAAE,MAAM,GAAG,IAAI,CAAA;IAC7B,SAAS,EAAE,gBAAgB,CAAA;CAC5B;AAED,qCAAqC;AACrC,MAAM,MAAM,aAAa,GAAG,cAAc,CAAA;AAE1C,MAAM,WAAW,eAAe;IAC9B,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAED,MAAM,WAAW,kBAAkB;IACjC,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB;AAED,MAAM,WAAW,mBAAmB;IAClC,SAAS,EAAE,cAAc,EAAE,CAAA;IAC3B,UAAU,CAAC,EAAE,MAAM,CAAA;CACpB;AAED,yCAAyC;AACzC,MAAM,MAAM,wBAAwB,GAAG,kBAAkB,CAAA;AAEzD,0CAA0C;AAC1C,MAAM,MAAM,yBAAyB,GAAG,mBAAmB,CAAA;AAE3D,MAAM,WAAW,mBAAmB;IAClC,EAAE,EAAE,MAAM,CAAA;IACV,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;IACtB,IAAI,EAAE,MAAM,CAAA;IACZ,aAAa,EAAE,MAAM,CAAA;CACtB;AAED,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,OAAO,CAAA;CACjB;AAED,MAAM,WAAW,eAAe;IAC9B,GAAG,EAAE,CAAC,KAAK,EAAE,eAAe,KAAK,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC,CAAA;IAC/D,IAAI,EAAE,CAAC,KAAK,CAAC,EAAE,kBAAkB,KAAK,OAAO,CAAC,mBAAmB,CAAC,CAAA;IAClE,MAAM,EAAE,CAAC,KAAK,EAAE,kBAAkB,KAAK,OAAO,CAAC,mBAAmB,CAAC,CAAA;IACnE,MAAM,EAAE,CAAC,KAAK,EAAE;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,KAAK,OAAO,CAAC,mBAAmB,CAAC,CAAA;CAC3F"}