@chatarmin/os 1.0.0 → 1.1.0

package/README.md

@@ -1,167 +1,837 @@
-# @chatarmin/os-sdk
+# @chatarmin/os
 
-Type-safe SDK for ChatarminOS - Customer & Subscription Management.
+> Type-safe SDK for ChatarminOS — the all-in-one platform for B2B SaaS to manage customers, subscriptions, feature access, and billing.
 
-## Installation
+[![npm version](https://img.shields.io/npm/v/@chatarmin/os.svg)](https://www.npmjs.com/package/@chatarmin/os)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-blue.svg)](https://www.typescriptlang.org/)
 
-> **Note**: This is a private npm package. You need authentication to install it.
+## Features
 
-### 1. Configure npm Authentication
+- 🏢 **Company Management** — Create, link, and manage customer companies
+- 🎫 **Subscription Tiers** — Define tiers with features and Stripe pricing
+- ✨ **Feature Access** — Check entitlements and enforce usage limits
+- 📊 **Usage Tracking** — Metered billing with idempotency support
+- 💳 **Stripe Integration** — Claim checkout sessions, link subscriptions
+- 🔗 **Smart Linking** — Intelligent company matching by domain/name/email
+- 👥 **Contact Sync** — Bulk upsert contacts for each company
+- 🚀 **Unified Onboarding** — Complete setup in a single API call
 
-Create a `.npmrc` file in your project root:
+---
 
-```bash
-# .npmrc
-@chatarmin:registry=https://registry.npmjs.org/
-//registry.npmjs.org/:_authToken=${NPM_TOKEN}
-```
+## Table of Contents
 
-Set your npm token as an environment variable:
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [API Reference](#api-reference)
+  - [Companies](#companies)
+  - [Contacts](#contacts)
+  - [Features](#features)
+  - [Billing](#billing)
+  - [Subscriptions & Tiers](#subscriptions--tiers)
+  - [Links](#links)
+  - [Onboarding](#onboarding)
+- [Common Patterns](#common-patterns)
+- [TypeScript Support](#typescript-support)
+- [Configuration](#configuration)
+- [Error Handling](#error-handling)
 
-```bash
-# .env (for local development)
-NPM_TOKEN=npm_yourtokenhere
+---
 
-# Or export it in your shell
-export NPM_TOKEN=npm_yourtokenhere
-```
-
-**For CI/CD**: Add `NPM_TOKEN` as a secret in your deployment platform (GitHub Actions, Vercel, etc.)
-
-### 2. Install the Package
+## Installation
 
 ```bash
-npm install @chatarmin/os-sdk
+pnpm add @chatarmin/os
 # or
-pnpm add @chatarmin/os-sdk
+npm install @chatarmin/os
 # or
-yarn add @chatarmin/os-sdk
+yarn add @chatarmin/os
 ```
 
-> See [PUBLISHING.md](./PUBLISHING.md) for detailed setup instructions.
+---
 
 ## Quick Start
 
 ```typescript
-import { ChatarminOS } from "@chatarmin/os-sdk"
+import { ChatarminOS } from "@chatarmin/os"
 
 const os = new ChatarminOS({
-  apiKey: process.env.CHATARMIN_OS_API_KEY!,
+  apiKey: process.env.OS_API_KEY!,
   // Optional: custom base URL for self-hosted
   // baseUrl: 'https://your-os.example.com/api/v1'
 })
+
+// Onboard a new customer (single call does everything!)
+const result = await os.onboard({
+  externalOrgId: "org_abc123", // Your product's org ID
+  hints: {
+    companyName: "Acme Inc",
+    domain: "acme.com",
+  },
+  tierCode: "free",
+  contactEmail: "admin@acme.com",
+  contactName: "John Doe",
+})
+
+console.log(result.companyId) // Use this for all future API calls
+console.log(result.linkStatus) // 'created' | 'linked' | 'already_linked'
 ```
 
-## Usage
+---
+
+## API Reference
 
 ### Companies
 
+Manage customer companies and their links to your product.
+
+#### `companies.getByProductLink(input)`
+
+Look up a company by your external organization ID.
+
 ```typescript
-// Find company by your external org ID
 const company = await os.companies.getByProductLink({
-  externalOrgId: "org_123",
+  externalOrgId: "org_abc123",
 })
 
-// Create a new company and link to your product
-const newCompany = await os.companies.create({
+if (company) {
+  console.log(`Found: ${company.name} (${company.id})`)
+} else {
+  console.log("Company not linked yet")
+}
+```
+
+#### `companies.create(input)`
+
+Create a new company and link it to your product.
+
+```typescript
+const company = await os.companies.create({
   name: "Acme Inc",
   domain: "acme.com",
-  externalOrgId: "org_456",
-  contactEmail: "billing@acme.com",
+  externalOrgId: "org_abc123",
+  contactEmail: "admin@acme.com",
   contactName: "John Doe",
+  createdAt: "2024-01-15T10:30:00.000Z", // Optional: historical date
+})
+
+console.log(company.id) // UUID
+console.log(company.shortId) // e.g., "acme-inc"
+```
+
+#### `companies.update(input)`
+
+Update company metadata (e.g., backfill historical dates).
+
+```typescript
+await os.companies.update({
+  companyId: "uuid-here",
+  createdAt: "2023-06-01T00:00:00.000Z",
 })
+```
+
+#### `companies.smartLink(input)`
 
-// Smart link - find existing company by hints
-const linked = await os.companies.smartLink({
-  externalOrgId: "org_789",
+Intelligently find and link a company using hints.
+
+```typescript
+const result = await os.companies.smartLink({
+  externalOrgId: "org_abc123",
   hints: {
-    companyName: "Acme",
+    companyName: "Acme Inc",
     domain: "acme.com",
     emails: ["john@acme.com", "jane@acme.com"],
   },
-  minConfidence: 0.8,
+  minConfidence: 0.7, // Default: 0.6
 })
+
+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
+}
 ```
 
-### Subscriptions & Tiers
+**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.
+
+#### `contacts.create(input)`
+
+Create or update a single contact.
 
 ```typescript
-// Apply a subscription tier to a company
-await os.subscriptions.create("pro", {
-  companyId: company.id,
+const contact = await os.contacts.create({
+  companyId: "comp_xxx",
+  email: "john@acme.com",
+  name: "John Doe",
+  role: "CEO",
+  isPrimary: true,
+  avatarUrl: "https://example.com/avatar.jpg",
+  metadata: { slackId: "U123" },
 })
 
-// With feature overrides
-await os.subscriptions.create("enterprise", {
-  companyId: company.id,
-  features: {
-    ai_credits: { included_quantity: 1000 },
-  },
+if (contact.isNew) {
+  console.log("Created new contact")
+} else {
+  console.log("Updated existing contact")
+}
+```
+
+#### `contacts.bulkUpsert(input)`
+
+Bulk create or update multiple contacts. **Recommended for onboarding.**
+
+```typescript
+const result = await os.contacts.bulkUpsert({
+  companyId: "comp_xxx",
+  contacts: [
+    { email: "ceo@acme.com", name: "Alice", role: "CEO", isPrimary: true },
+    { email: "cto@acme.com", name: "Bob", role: "CTO" },
+    { email: "dev@acme.com", name: "Charlie", role: "Engineer" },
+  ],
 })
 
-// List available tiers
-const tiers = await os.tiers.list()
+console.log(`Created: ${result.created}, Updated: ${result.updated}`)
+// result.contacts contains individual results with IDs
+```
+
+#### `contacts.list(companyId, primaryOnly?)`
 
-// Get tier details
-const proTier = await os.tiers.get("pro")
+List contacts for a company.
+
+```typescript
+// Get all contacts
+const contacts = await os.contacts.list("comp_xxx")
+
+// Get only the primary contact
+const [primary] = await os.contacts.list("comp_xxx", true)
 ```
 
-### Feature Access
+---
+
+### Features
+
+Check and manage feature access for companies.
+
+#### `features.check(input)`
+
+Check if a company has access to a specific feature.
 
 ```typescript
-// Check if company has access to a feature
 const access = await os.features.check({
-  companyId: company.id,
-  featureCode: "whatsapp_messages",
+  companyId: "comp_xxx",
+  featureCode: "ai_credit",
 })
 
-if (access.hasAccess) {
-  console.log(`Limit: ${access.limit}, Used: ${access.currentUsage}`)
+console.log({
+  enabled: access.isEnabled, // Feature is turned on
+  canUse: access.canUse, // Can use right now (not at limit)
+  hasQuantity: access.hasQuantity, // Is a quantity-based feature
+  usage: access.currentUsage, // Current usage count
+  limit: access.quantityLimit, // Max allowed (null = unlimited)
+  included: access.includedQuantity, // Free tier before billing
+  remaining: access.remaining, // How many left (null = unlimited)
+})
+
+if (!access.canUse) {
+  throw new Error("Upgrade required")
 }
+```
+
+#### `features.listAccess(companyId)`
+
+List all features and their access status for a company.
 
-// List all feature access for a company
-const allAccess = await os.features.listAccess(company.id)
+```typescript
+const features = await os.features.listAccess("comp_xxx")
+
+for (const f of features) {
+  console.log(`${f.featureName}: ${f.isEnabled ? "✓" : "✗"}`)
+  if (f.quantityLimit) {
+    console.log(`  Usage: ${f.currentUsage} / ${f.quantityLimit}`)
+  }
+}
 ```
 
-### Billing & Usage Tracking
+#### `features.setAccess(input)`
+
+Update feature access with **partial config merge**.
 
 ```typescript
-// Track usage for a feature
-await os.billing.trackUsage({
-  companyId: company.id,
-  featureCode: "ai_credits",
+// Update by company ID
+await os.features.setAccess({
+  companyId: "comp_xxx",
+  featureCode: "ai_credit",
+  isEnabled: true,
+  quantityLimit: 1000,
+  includedQuantity: 100,
+  config: {
+    model: "gpt-4",
+    maxTokens: 4096,
+  },
+  source: "manual", // 'subscription' | 'manual' | 'trial' | 'api'
+  validUntil: new Date("2025-12-31"), // null for no expiration
+})
+
+// Update by external org ID
+await os.features.setAccess({
+  externalOrgId: "org_abc123",
+  featureCode: "team_seats",
+  config: { maxSeats: 50 }, // Only updates maxSeats, preserves other config
+})
+```
+
+#### `features.getAccessByExternalOrgId(externalOrgId)`
+
+Get all features using your product's external org ID.
+
+```typescript
+const result = await os.features.getAccessByExternalOrgId("org_abc123")
+
+console.log(`Company: ${result.companyId}`)
+for (const f of result.features) {
+  console.log(`${f.featureCode}: ${f.isEnabled}`)
+  console.log("  Config:", f.configValues)
+}
+```
+
+#### `features.checkByExternalOrgId(externalOrgId, featureCode)`
+
+Check a specific feature using your external org ID.
+
+```typescript
+const access = await os.features.checkByExternalOrgId("org_abc123", "ai_credit")
+
+if (access.canUse) {
+  console.log(`Remaining: ${access.remaining}`)
+}
+```
+
+---
+
+### Billing
+
+Track usage, claim subscriptions, and manage billing.
+
+#### `billing.trackUsage(input)`
+
+Track usage for a metered feature.
+
+```typescript
+const result = await os.billing.trackUsage({
+  companyId: "comp_xxx",
+  featureCode: "ai_credit",
   quantity: 5,
-  idempotencyKey: "unique-request-id", // Optional, for deduplication
-  metadata: { model: "gpt-4" }, // Optional
+  idempotencyKey: `request_${requestId}`, // Prevents double-counting
+  metadata: { model: "gpt-4", tokens: 1500 },
+})
+
+console.log({
+  currentUsage: result.currentUsage,
+  remaining: result.remaining,
+  billable: result.billableQuantity, // Amount beyond included tier
+  isAtLimit: result.isAtLimit,
 })
 ```
 
-### Manual Linking
+#### `billing.claimCheckout(input)`
+
+Claim a subscription from a completed Stripe Checkout Session.
+
+```typescript
+// In your Stripe checkout success handler
+const result = await os.billing.claimCheckout({
+  companyId: "comp_xxx",
+  checkoutSessionId: "cs_test_xxx", // From Stripe callback
+})
+
+if (result.alreadyClaimed) {
+  console.log("Subscription was already claimed")
+} else {
+  console.log(`Claimed subscription: ${result.subscriptionId}`)
+}
+```
+
+#### `billing.linkSubscription(input)`
+
+Link an existing Stripe subscription to a company.
+
+```typescript
+// When you create subscriptions on YOUR Stripe account
+const result = await os.billing.linkSubscription({
+  companyId: "comp_xxx",
+  stripeSubscriptionId: "sub_xxx",
+  stripeCustomerId: "cus_xxx", // Optional: fetched from subscription if omitted
+  tierCode: "pro", // Apply tier features
+  displayName: "Pro Plan",
+})
+
+console.log({
+  subscriptionId: result.subscriptionId,
+  isNew: !result.alreadyLinked,
+  featuresApplied: result.featuresApplied,
+})
+```
+
+#### `billing.getStatus(companyId)`
+
+Get billing status overview for a company.
+
+```typescript
+const status = await os.billing.getStatus("comp_xxx")
+
+console.log({
+  hasBilling: status.hasBillingProfile,
+  subscriptions: status.activeSubscriptions.length,
+  features: status.enabledFeaturesCount,
+})
+
+// Check active tier
+if (status.activeSubscriptions[0]?.tier) {
+  console.log(`Current tier: ${status.activeSubscriptions[0].tier.name}`)
+}
+```
+
+---
+
+### Subscriptions & Tiers
+
+Manage subscription tiers and apply features.
+
+#### `tiers.list()`
+
+List all available tiers for your product.
+
+```typescript
+const tiers = await os.tiers.list()
+
+for (const tier of tiers) {
+  console.log(`${tier.name} (${tier.code})`)
+}
+// ['Free', 'Pro', 'Enterprise']
+```
+
+#### `tiers.get(tierCode)`
+
+Get detailed tier information including Stripe prices.
+
+```typescript
+const tier = await os.tiers.get("pro")
+
+// Check base fee
+if (tier.baseFee) {
+  console.log(`Base fee: ${tier.baseFee.stripe.unitAmount / 100}€/mo`)
+  console.log(`Price ID: ${tier.baseFee.stripe.priceId}`)
+}
+
+// Access features
+for (const feature of tier.features) {
+  console.log(`${feature.code}:`, feature.configValues)
+}
+
+// Get all Stripe price IDs (base fee + feature prices)
+console.log("Stripe prices:", tier.stripePriceIds)
+// ['price_base', 'price_feature1', 'price_feature2']
+```
+
+#### `tiers.apply(tierCode, options)`
+
+Apply a tier's features to a company (without Stripe).
+
+```typescript
+// Apply free tier
+await os.tiers.apply("free", {
+  companyId: "comp_xxx",
+})
+
+// Apply with custom limits
+await os.tiers.apply("trial", {
+  companyId: "comp_xxx",
+  features: {
+    ai_credit: { included_quantity: 100 },
+    seats: { max_quantity: 10 },
+  },
+})
+```
+
+#### `subscriptions.create(tierCode, options)`
+
+Alias for `tiers.apply()` — apply a subscription tier.
+
+```typescript
+await os.subscriptions.create("pro", {
+  companyId: "comp_xxx",
+  features: {
+    ai_credit: { included_quantity: 500 },
+  },
+})
+```
+
+---
+
+### Links
+
+Manually manage product links.
+
+#### `links.create(input)`
+
+Create a manual link between your external org ID and an existing company.
 
 ```typescript
-// Link an external org ID to an existing company
 await os.links.create({
+  companyId: "comp_xxx",
+  externalOrgId: "org_abc123",
+  label: "Store Vienna", // Optional: display label
+  externalUserId: "user_xyz", // Optional: user who created the link
+})
+```
+
+#### `links.reset(options?)`
+
+Delete all product links for your product. Use before re-importing.
+
+```typescript
+// Basic reset (links only)
+const result = await os.links.reset()
+console.log(`Deleted ${result.linksDeleted} links`)
+
+// Full reset (links + contacts + MRR)
+const result = await os.links.reset({
+  deleteContacts: true,
+  resetMrr: true,
+})
+console.log(
+  `Deleted ${result.linksDeleted} links, ${result.contactsDeleted} contacts`
+)
+```
+
+---
+
+### Onboarding
+
+Complete customer onboarding in a single API call.
+
+The `onboard()` method handles:
+
+1. Smart company matching/creation
+2. Product linking
+3. Subscription claiming/linking
+4. Tier feature application
+
+#### Basic Usage
+
+```typescript
+const result = await os.onboard({
+  externalOrgId: "org_abc123", // Your product's org ID (required)
+  hints: {
+    companyName: "Acme Inc",
+    domain: "acme.com",
+    emails: ["john@acme.com"],
+  },
+  tierCode: "free",
+  contactEmail: "admin@acme.com",
+  contactName: "John Doe",
+  createdAt: "2024-01-15T10:30:00.000Z", // Optional: historical date
+})
+
+console.log({
+  companyId: result.companyId,
+  companyName: result.companyName,
+  linkStatus: result.linkStatus, // 'created' | 'linked' | 'already_linked'
+  tierApplied: result.billingStatus?.tierApplied,
+})
+```
+
+#### Scenario 1: User Completed Stripe Checkout
+
+```typescript
+const result = await os.onboard({
+  externalOrgId: "org_abc123",
+  hints: { companyName: "Acme Inc", domain: "acme.com" },
+  checkoutSessionId: "cs_test_xxx", // From Stripe checkout callback
+})
+
+// result.billingStatus.claimed = true
+// result.billingStatus.subscriptionId = 'sub_xxx'
+```
+
+#### Scenario 2: Free Tier Signup
+
+```typescript
+const result = await os.onboard({
+  externalOrgId: "org_abc123",
+  hints: { companyName: "Acme Inc" },
+  tierCode: "free",
+  contactEmail: "admin@acme.com",
+})
+
+// result.billingStatus.tierApplied = true
+```
+
+#### Scenario 3: You Create Stripe Subscription
+
+```typescript
+// 1. Get tier prices
+const tier = await os.tiers.get("pro")
+
+// 2. Create subscription on YOUR Stripe account
+const stripeSub = await stripe.subscriptions.create({
+  customer: stripeCustomerId,
+  items: tier.stripePriceIds.map((price) => ({ price })),
+})
+
+// 3. Onboard with the subscription
+const result = await os.onboard({
+  externalOrgId: "org_abc123",
+  hints: { companyName: "Acme Inc" },
+  stripeSubscriptionId: stripeSub.id,
+  stripeCustomerId: stripeCustomerId,
+  tierCode: "pro",
+})
+
+// result.billingStatus.linked = true
+// result.billingStatus.tierApplied = true
+```
+
+#### Handling Existing Customers
+
+```typescript
+const result = await os.onboard({
+  externalOrgId: "org_abc123",
+  hints: { companyName: "Acme Inc" },
+})
+
+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
+}
+```
+
+---
+
+## Common Patterns
+
+### Feature Gating
+
+```typescript
+async function checkFeatureAccess(orgId: string, feature: string) {
+  const access = await os.features.checkByExternalOrgId(orgId, feature)
+
+  if (!access.isEnabled) {
+    throw new Error(`Feature ${feature} is not available on your plan`)
+  }
+
+  if (!access.canUse) {
+    throw new Error(`Usage limit reached for ${feature}. Please upgrade.`)
+  }
+
+  return access
+}
+
+// Usage
+await checkFeatureAccess("org_abc123", "ai_credit")
+await performAIOperation()
+await os.billing.trackUsage({
   companyId: company.id,
-  externalOrgId: "org_new_123",
-  externalUserId: "user_456", // Optional
+  featureCode: "ai_credit",
+  quantity: 1,
 })
 ```
 
-## Configuration
+### Stripe Subscription Flow
+
+```typescript
+// 1. User selects a plan → Get tier prices
+const tier = await os.tiers.get("pro")
+
+// 2. Create Stripe Checkout Session with tier prices
+const session = await stripe.checkout.sessions.create({
+  customer: customerId,
+  line_items: tier.stripePriceIds.map((price) => ({
+    price,
+    quantity: 1,
+  })),
+  success_url: `${baseUrl}/success?session_id={CHECKOUT_SESSION_ID}`,
+  cancel_url: `${baseUrl}/cancel`,
+})
+
+// 3. After checkout completes → Claim subscription
+const result = await os.onboard({
+  externalOrgId: "org_abc123",
+  checkoutSessionId: session.id,
+})
+```
 
-| Option    | Type     | Required | Default                           | Description                    |
-| --------- | -------- | -------- | --------------------------------- | ------------------------------ |
-| `apiKey`  | `string` | ✅       | -                                 | API key from ChatarminOS admin |
-| `baseUrl` | `string` | -        | `https://os.chatarmin.com/api/v1` | API endpoint                   |
+### Backfilling Historical Data
+
+```typescript
+import { ChatarminOS } from "@chatarmin/os"
+import historicalData from "./migration-data.json"
+
+const os = new ChatarminOS({ apiKey: process.env.OS_API_KEY! })
+
+for (const org of historicalData) {
+  // Create company with historical date
+  const result = await os.onboard({
+    externalOrgId: org.id,
+    hints: {
+      companyName: org.name,
+      domain: org.domain,
+    },
+    tierCode: org.plan,
+    contactEmail: org.adminEmail,
+    createdAt: org.createdAt, // Historical timestamp
+  })
+
+  // Sync contacts
+  await os.contacts.bulkUpsert({
+    companyId: result.companyId,
+    contacts: org.users.map((u) => ({
+      email: u.email,
+      name: u.name,
+      role: u.role,
+    })),
+  })
+}
+```
+
+---
 
 ## TypeScript Support
 
-The SDK is fully typed. All methods return properly typed responses based on the ChatarminOS API schema.
+The SDK is fully typed with comprehensive TypeScript definitions.
+
+### Importing Types
+
+```typescript
+import { ChatarminOS } from "@chatarmin/os"
+import type {
+  ChatarminOSConfig,
+  CreateCompanyInput,
+  SmartLinkInput,
+  SmartLinkResult,
+  ContactInput,
+  FeatureCheckInput,
+  FeatureSetAccessInput,
+  TrackUsageInput,
+  OnboardInput,
+  OnboardResult,
+  ApplyTierInput,
+  ClaimCheckoutInput,
+  LinkSubscriptionInput,
+} from "@chatarmin/os"
+```
+
+### Router Types
+
+```typescript
+import type { AppRouter } from "@chatarmin/os"
+```
+
+---
+
+## Configuration
+
+| Option    | Type     | Required | Default                           | Description                 |
+| --------- | -------- | -------- | --------------------------------- | --------------------------- |
+| `apiKey`  | `string` | ✅       | —                                 | API key from OS admin panel |
+| `baseUrl` | `string` | —        | `https://os.chatarmin.com/api/v1` | API endpoint                |
 
 ```typescript
-import type { AppRouter } from "@chatarmin/os-sdk"
+const os = new ChatarminOS({
+  apiKey: process.env.OS_API_KEY!,
+  baseUrl: "https://os.chatarmin.com/api/v1", // Default
+})
+
+// Local development
+const osLocal = new ChatarminOS({
+  apiKey: process.env.OS_API_KEY!,
+  baseUrl: "http://localhost:3001/api/v1",
+})
 ```
 
+### Getting Your API Key
+
+1. Go to ChatarminOS → **Settings** → **Developers** → **API Keys**
+2. Click "Create API Key"
+3. Copy the key (format: `os_sk_xxxxxxxxxxxx`)
+4. Store in environment variables
+
+---
+
+## Error Handling
+
+The SDK uses tRPC under the hood. Errors include structured information:
+
+```typescript
+try {
+  await os.billing.trackUsage({
+    companyId: "comp_xxx",
+    featureCode: "ai_credit",
+    quantity: 1000,
+  })
+} catch (error) {
+  if (error instanceof TRPCClientError) {
+    console.error("Code:", error.data?.code) // e.g., 'FORBIDDEN'
+    console.error("Message:", error.message) // Human-readable message
+    console.error("HTTP Status:", error.data?.httpStatus)
+  }
+}
+```
+
+### Common Error Codes
+
+| Code                  | Description                |
+| --------------------- | -------------------------- |
+| `UNAUTHORIZED`        | Invalid or missing API key |
+| `FORBIDDEN`           | No access to this resource |
+| `NOT_FOUND`           | Company/feature not found  |
+| `BAD_REQUEST`         | Invalid input parameters   |
+| `PRECONDITION_FAILED` | Usage limit exceeded       |
+
+---
+
+## Related Documentation
+
+- **[QUICKSTART.md](./QUICKSTART.md)** — Quick publishing & installation guide
+- **[PUBLISHING.md](./PUBLISHING.md)** — Detailed publishing instructions
+- **[test-sdk.ts](./test-sdk.ts)** — Complete usage examples
+
+---
+
+## Support
+
+- **Email**: hello@chatarmin.com
+- **Documentation**: https://os.chatarmin.com/docs
+
+---
+
 ## License
 
 MIT © Chatarmin GmbH

package/dist/index.d.ts

@@ -113,7 +113,7 @@ export interface FeatureSetAccessInput {
     validUntil?: Date | null;
 }
 /**
- * Input for tracking feature usage.
+ * Input for tracking feature usage (increment operation).
  */
 export interface TrackUsageInput {
     /** Company ID */
@@ -121,7 +121,7 @@ export interface TrackUsageInput {
     /** Feature code to track */
     featureCode: string;
     /**
-     * Quantity to track.
+     * Quantity to track (must be positive).
      * @default 1
      */
     quantity?: number;
@@ -130,9 +130,67 @@ export interface TrackUsageInput {
      * Use a unique ID per operation (e.g., message ID).
      */
     idempotencyKey?: string;
-    /** Additional metadata for the usage event */
+    /**
+     * Additional metadata for the usage event.
+     * Store external references here (e.g., { externalId: "msg_123", type: "message" })
+     */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Input for setting usage to an absolute value.
+ * Use for corrections when you know what the total usage SHOULD be.
+ */
+export interface SetUsageInput {
+    /** Company ID */
+    companyId: string;
+    /** Feature code */
+    featureCode: string;
+    /** The absolute value to set usage to (must be >= 0) */
+    absoluteValue: number;
+    /** Reason for the set operation (required for audit trail) */
+    reason: string;
+    /** Admin user who performed the operation */
+    performedBy?: string;
+    /** Additional metadata (e.g., { ticketId: "SUPPORT-123" }) */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Input for adjusting usage by a delta.
+ * Use for explicit corrections - supports negative values for refunds.
+ */
+export interface AdjustUsageInput {
+    /** Company ID */
+    companyId: string;
+    /** Feature code */
+    featureCode: string;
+    /** The delta to apply (can be negative for refunds) */
+    delta: number;
+    /** Reason for the adjustment (required for audit trail) */
+    reason: string;
+    /** Reference to original event being adjusted (for Stripe cancellations) */
+    adjustsEventId?: string;
+    /** Admin user who performed the operation */
+    performedBy?: string;
+    /** Additional metadata (e.g., { ticketId: "REFUND-456" }) */
     metadata?: Record<string, unknown>;
 }
+/**
+ * Result from usage operations (track, set, adjust).
+ */
+export interface UsageResult {
+    success: boolean;
+    featureCode: string;
+    previousUsage: number;
+    currentUsage: number;
+    delta: number;
+    quantityLimit: number | null;
+    remaining: number | null;
+    isAtLimit: boolean;
+    includedQuantity: number;
+    billableQuantity: number;
+    meterId: string;
+    eventId: string | null;
+}
 /**
  * Input for claiming a Stripe checkout subscription.
  */
@@ -401,11 +459,11 @@ export declare class ChatarminOS {
         getByProductLink: (input: {
             externalOrgId: string;
         }) => Promise<{
+            external_org_id: string;
+            external_user_id: string | null;
             name: string;
             id: string;
             domain: string | null;
-            external_org_id: string;
-            external_user_id: string | null;
         } | null>;
         /**
          * Create a new company and link it to your product.
@@ -563,8 +621,8 @@ export declare class ChatarminOS {
             created_at: Date;
             updated_at: Date;
             company_id: string | null;
-            short_id: string | null;
             is_primary: boolean;
+            short_id: string | null;
             avatar_url: string | null;
         }>;
         /**
@@ -619,8 +677,8 @@ export declare class ChatarminOS {
             created_at: Date;
             updated_at: Date;
             company_id: string | null;
-            short_id: string | null;
             is_primary: boolean;
+            short_id: string | null;
             avatar_url: string | null;
         }[]>;
     };
@@ -923,6 +981,142 @@ export declare class ChatarminOS {
             billableQuantity: number;
             meterId: string;
         }>;
+        /**
+         * Set usage to an absolute value.
+         *
+         * Use this for corrections when you know what the total usage SHOULD be.
+         * Creates a snapshot for audit trail. The delta (difference) is calculated
+         * automatically and synced to Stripe.
+         *
+         * @param input - Set usage parameters
+         * @returns Result with previous and new usage values
+         *
+         * @example Correct usage to 100 (was 150)
+         * ```typescript
+         * const result = await os.billing.setUsage({
+         *   companyId: 'comp_xxx',
+         *   featureCode: 'ai_credit',
+         *   absoluteValue: 100,
+         *   reason: 'Corrected after customer support review',
+         *   performedBy: 'admin@company.com'
+         * })
+         *
+         * console.log({
+         *   previousUsage: result.previousUsage, // 150
+         *   currentUsage: result.currentUsage,   // 100
+         *   delta: result.delta                   // -50
+         * })
+         * ```
+         */
+        setUsage: (input: SetUsageInput) => Promise<UsageResult>;
+        /**
+         * Adjust usage by a delta (positive or negative).
+         *
+         * Use this for explicit corrections. Supports negative values for
+         * refunds or error corrections. Creates an audit trail and syncs
+         * to Stripe (including meter event adjustments when possible).
+         *
+         * @param input - Adjustment parameters
+         * @returns Result with previous and new usage values
+         *
+         * @example Refund 50 units
+         * ```typescript
+         * const result = await os.billing.adjustUsage({
+         *   companyId: 'comp_xxx',
+         *   featureCode: 'ai_credit',
+         *   delta: -50,
+         *   reason: 'Refund for failed API calls',
+         *   performedBy: 'support@company.com'
+         * })
+         * ```
+         *
+         * @example Add bonus units
+         * ```typescript
+         * const result = await os.billing.adjustUsage({
+         *   companyId: 'comp_xxx',
+         *   featureCode: 'ai_credit',
+         *   delta: 100,
+         *   reason: 'Promotional bonus for beta testers'
+         * })
+         * ```
+         */
+        adjustUsage: (input: AdjustUsageInput) => Promise<UsageResult>;
+        /**
+         * Get usage event history for a feature.
+         *
+         * Returns the history of usage events including increments, sets,
+         * and adjustments. Useful for auditing and debugging.
+         *
+         * @param companyId - Company ID
+         * @param featureCode - Feature code to get history for
+         * @param options - Query options
+         * @returns Array of usage events
+         *
+         * @example
+         * ```typescript
+         * const history = await os.billing.getUsageHistory(
+         *   'comp_xxx',
+         *   'ai_credit',
+         *   { limit: 20, eventType: 'adjustment' }
+         * )
+         *
+         * for (const event of history) {
+         *   console.log(`${event.event_type}: ${event.quantity} at ${event.event_time}`)
+         *   if (event.adjustment_reason) {
+         *     console.log(`  Reason: ${event.adjustment_reason}`)
+         *   }
+         * }
+         * ```
+         */
+        getUsageHistory: (companyId: string, featureCode: string, options?: {
+            limit?: number;
+            includeDelivered?: boolean;
+            eventType?: "increment" | "set" | "adjustment";
+        }) => Promise<{
+            id: string;
+            metadata: unknown;
+            quantity: number;
+            source: string;
+            created_at: Date;
+            company_id: string;
+            billing_profile_id: string;
+            meter_code: string;
+            available_product_id: string;
+            event_time: Date;
+            event_type: string;
+            previous_value: number | null;
+            adjustment_reason: string | null;
+            adjusts_event_id: string | null;
+            idempotency_key: string;
+            stripe_delivery_status: string;
+            stripe_event_id: string | null;
+            stripe_delivery_error: string | null;
+            delivered_at: Date | null;
+        }[]>;
+        /**
+         * Get usage snapshots for a feature.
+         *
+         * Returns audit snapshots created by set operations and reconciliations.
+         * Useful for understanding historical usage corrections.
+         *
+         * @param companyId - Company ID
+         * @param featureCode - Feature code
+         * @param limit - Max number of snapshots to return
+         * @returns Array of usage snapshots
+         */
+        getUsageSnapshots: (companyId: string, featureCode: string, limit?: number) => Promise<{
+            id: string;
+            metadata: unknown;
+            reason: string | null;
+            created_at: Date;
+            company_id: string;
+            meter_code: string;
+            created_by: string | null;
+            absolute_value: number;
+            billable_value: number;
+            snapshot_type: string;
+            trigger_event_id: string | null;
+        }[]>;
         /**
          * Claim a subscription from a completed Stripe Checkout Session.
          *
@@ -1086,16 +1280,16 @@ export declare class ChatarminOS {
         }) => Promise<{
             id: string;
             metadata: unknown;
-            label: string | null;
             confidence: number | null;
+            label: string | null;
             created_at: Date;
             updated_at: Date;
             company_id: string;
             product_id: string;
             external_org_id: string;
             external_user_id: string | null;
-            link_type: string;
             sync_status: string;
+            link_type: string;
         } | undefined>;
         /**
          * Delete all product links for this product.
@@ -1223,9 +1417,9 @@ export declare class ChatarminOS {
             description: string | null;
             code: string;
             is_active: boolean;
-            display_order: number;
             created_at: Date;
             updated_at: Date;
+            display_order: number;
             product_id: string;
         }[]>;
         /**
@@ -1341,9 +1535,9 @@ export declare class ChatarminOS {
             description: string | null;
             code: string;
             is_active: boolean;
-            display_order: number;
             created_at: Date;
             updated_at: Date;
+            display_order: number;
             product_id: string;
         }[]>;
         /**

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -555,6 +555,120 @@ export class ChatarminOS {
              * ```
              */
             trackUsage: (input) => client.billing.trackUsage.mutate(input),
+            /**
+             * Set usage to an absolute value.
+             *
+             * Use this for corrections when you know what the total usage SHOULD be.
+             * Creates a snapshot for audit trail. The delta (difference) is calculated
+             * automatically and synced to Stripe.
+             *
+             * @param input - Set usage parameters
+             * @returns Result with previous and new usage values
+             *
+             * @example Correct usage to 100 (was 150)
+             * ```typescript
+             * const result = await os.billing.setUsage({
+             *   companyId: 'comp_xxx',
+             *   featureCode: 'ai_credit',
+             *   absoluteValue: 100,
+             *   reason: 'Corrected after customer support review',
+             *   performedBy: 'admin@company.com'
+             * })
+             *
+             * console.log({
+             *   previousUsage: result.previousUsage, // 150
+             *   currentUsage: result.currentUsage,   // 100
+             *   delta: result.delta                   // -50
+             * })
+             * ```
+             */
+            setUsage: (input) => client.billing.setUsage.mutate({
+                ...input,
+                source: "api",
+            }),
+            /**
+             * Adjust usage by a delta (positive or negative).
+             *
+             * Use this for explicit corrections. Supports negative values for
+             * refunds or error corrections. Creates an audit trail and syncs
+             * to Stripe (including meter event adjustments when possible).
+             *
+             * @param input - Adjustment parameters
+             * @returns Result with previous and new usage values
+             *
+             * @example Refund 50 units
+             * ```typescript
+             * const result = await os.billing.adjustUsage({
+             *   companyId: 'comp_xxx',
+             *   featureCode: 'ai_credit',
+             *   delta: -50,
+             *   reason: 'Refund for failed API calls',
+             *   performedBy: 'support@company.com'
+             * })
+             * ```
+             *
+             * @example Add bonus units
+             * ```typescript
+             * const result = await os.billing.adjustUsage({
+             *   companyId: 'comp_xxx',
+             *   featureCode: 'ai_credit',
+             *   delta: 100,
+             *   reason: 'Promotional bonus for beta testers'
+             * })
+             * ```
+             */
+            adjustUsage: (input) => client.billing.adjustUsage.mutate({
+                ...input,
+                source: "api",
+            }),
+            /**
+             * Get usage event history for a feature.
+             *
+             * Returns the history of usage events including increments, sets,
+             * and adjustments. Useful for auditing and debugging.
+             *
+             * @param companyId - Company ID
+             * @param featureCode - Feature code to get history for
+             * @param options - Query options
+             * @returns Array of usage events
+             *
+             * @example
+             * ```typescript
+             * const history = await os.billing.getUsageHistory(
+             *   'comp_xxx',
+             *   'ai_credit',
+             *   { limit: 20, eventType: 'adjustment' }
+             * )
+             *
+             * for (const event of history) {
+             *   console.log(`${event.event_type}: ${event.quantity} at ${event.event_time}`)
+             *   if (event.adjustment_reason) {
+             *     console.log(`  Reason: ${event.adjustment_reason}`)
+             *   }
+             * }
+             * ```
+             */
+            getUsageHistory: (companyId, featureCode, options) => client.billing.getUsageHistory.query({
+                companyId,
+                featureCode,
+                ...options,
+            }),
+            /**
+             * Get usage snapshots for a feature.
+             *
+             * Returns audit snapshots created by set operations and reconciliations.
+             * Useful for understanding historical usage corrections.
+             *
+             * @param companyId - Company ID
+             * @param featureCode - Feature code
+             * @param limit - Max number of snapshots to return
+             * @returns Array of usage snapshots
+             */
+            getUsageSnapshots: (companyId, featureCode, limit) => client.billing.getUsageSnapshots.query({
+                companyId,
+                featureCode,
+                limit,
+            }),
             /**
              * Claim a subscription from a completed Stripe Checkout Session.
              *

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@chatarmin/os",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Type-safe SDK for ChatarminOS - Customer & Subscription Management",
   "type": "module",
   "publishConfig": {
-    "access": "restricted"
+    "access": "public"
   },
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",