@chatarmin/os 0.1.10 → 0.3.0

package/dist/index.js

@@ -1,35 +1,67 @@
 import { createTRPCClient, httpBatchLink } from "@trpc/client";
 import superjson from "superjson";
+// ============================================================================
+// SDK Client
+// ============================================================================
 /**
  * ChatarminOS SDK Client
  *
- * Type-safe client for interacting with ChatarminOS from your product.
+ * Type-safe client for interacting with ChatarminOS from your B2B SaaS product.
+ * Use this SDK to manage companies, track feature usage, and handle billing.
  *
- * @example
+ * @example Basic Setup
  * ```typescript
  * import { ChatarminOS } from '@chatarmin/os-sdk'
  *
- * const os = new ChatarminOS({ apiKey: process.env.OS_API_KEY! })
+ * const os = new ChatarminOS({
+ *   apiKey: process.env.OS_API_KEY!
+ * })
+ * ```
+ *
+ * @example Complete Onboarding Flow
+ * ```typescript
+ * // When a new user signs up in your product:
+ * const result = await os.onboard({
+ *   externalOrgId: 'org_abc123',
+ *   hints: {
+ *     companyName: 'Acme Inc',
+ *     domain: 'acme.com'
+ *   },
+ *   tierCode: 'free' // Apply free tier features
+ * })
  *
- * // Resolve company by your org ID
- * const company = await os.companies.getByProductLink({ externalOrgId: 'org_123' })
+ * console.log(result.companyId) // Use this for all future API calls
+ * ```
  *
- * // Track usage
+ * @example Track Usage
+ * ```typescript
  * await os.billing.trackUsage({
  *   companyId: company.id,
  *   featureCode: 'ai_credit',
  *   quantity: 1
  * })
- *
- * // Check feature access
- * const access = await os.features.check({
- *   companyId: company.id,
- *   featureCode: 'whatsapp_messages'
- * })
  * ```
+ *
+ * @see https://os.chatarmin.com/docs for full documentation
  */
 export class ChatarminOS {
     client;
+    /**
+     * Create a new ChatarminOS SDK client.
+     *
+     * @param config - Configuration options
+     * @param config.apiKey - Your product's API key from OS admin
+     * @param config.baseUrl - Custom API base URL (optional)
+     *
+     * @example
+     * ```typescript
+     * const os = new ChatarminOS({
+     *   apiKey: process.env.OS_API_KEY!,
+     *   // Optional: custom base URL for development
+     *   baseUrl: 'http://localhost:3001/api/v1'
+     * })
+     * ```
+     */
     constructor(config) {
         const baseUrl = config.baseUrl || "https://os.chatarmin.com/api/v1";
         this.client = createTRPCClient({
@@ -44,104 +76,460 @@ export class ChatarminOS {
             ],
         });
     }
+    // ==========================================================================
+    // Companies
+    // ==========================================================================
     /**
-     * Company operations
+     * Company management operations.
+     *
+     * Companies represent your customers in ChatarminOS. Each company can be
+     * linked to your product via an external organization ID.
+     *
+     * @example
+     * ```typescript
+     * // Look up a company by your org ID
+     * const company = await os.companies.getByProductLink({
+     *   externalOrgId: 'org_abc123'
+     * })
+     *
+     * // Create a new company
+     * const newCompany = await os.companies.create({
+     *   name: 'Acme Inc',
+     *   domain: 'acme.com',
+     *   externalOrgId: 'org_abc123',
+     *   contactEmail: 'admin@acme.com'
+     * })
+     * ```
      */
     get companies() {
+        const client = this.client;
         return {
             /**
-             * Get company by their external org ID in your product
+             * Look up a company by their external organization ID in your product.
+             *
+             * Use this to resolve your product's org ID to a ChatarminOS company.
+             * Returns `null` if no company is linked with this external ID.
+             *
+             * @param input - The lookup parameters
+             * @param input.externalOrgId - Your product's organization ID
+             * @returns The company if found, or `null`
+             *
+             * @example
+             * ```typescript
+             * const company = await os.companies.getByProductLink({
+             *   externalOrgId: 'org_abc123'
+             * })
+             *
+             * if (company) {
+             *   console.log(`Found: ${company.name}`)
+             * } else {
+             *   console.log('Company not linked yet')
+             * }
+             * ```
              */
-            getByProductLink: (input) => this.client.companies.getByProductLink.query(input),
+            getByProductLink: (input) => client.companies.getByProductLink.query(input),
             /**
-             * Create a new company and link to your product
+             * Create a new company and link it to your product.
+             *
+             * This creates a company in ChatarminOS and automatically links it
+             * to your product using the provided external organization ID.
+             *
+             * @param input - Company creation parameters
+             * @returns The created company with ID and short ID
+             *
+             * @example
+             * ```typescript
+             * const company = await os.companies.create({
+             *   name: 'Acme Inc',
+             *   domain: 'acme.com',
+             *   externalOrgId: 'org_abc123',
+             *   contactEmail: 'admin@acme.com',
+             *   contactName: 'John Doe'
+             * })
+             *
+             * console.log(company.id)      // UUID
+             * console.log(company.shortId) // e.g., "acme-inc"
+             * ```
              */
-            create: (input) => this.client.companies.createWithLink.mutate(input),
+            create: (input) => client.companies.createWithLink.mutate(input),
             /**
-             * Smart link - find and link company using hints
+             * Smart link - intelligently find and link a company using hints.
+             *
+             * This method attempts to find an existing company in ChatarminOS
+             * that matches the provided hints (domain, name, emails). If found
+             * with sufficient confidence, it automatically creates a link.
+             *
+             * **Matching priority:**
+             * 1. Domain match (95% confidence)
+             * 2. Name match (up to 80% confidence)
+             * 3. Email domain match (70% confidence)
+             *
+             * @param input - Smart link parameters
+             * @returns Result with status and company info if linked
              *
-             * @experimental
+             * @example
+             * ```typescript
+             * const result = await os.companies.smartLink({
+             *   externalOrgId: 'org_abc123',
+             *   hints: {
+             *     companyName: 'Acme Inc',
+             *     domain: 'acme.com',
+             *     emails: ['john@acme.com']
+             *   },
+             *   minConfidence: 0.7
+             * })
+             *
+             * if (result.status === 'linked') {
+             *   console.log(`Linked to ${result.customerName}`)
+             * } else if (result.status === 'suggestions') {
+             *   console.log('Possible matches:', result.suggestions)
+             * }
+             * ```
+             *
+             * @experimental This API may change in future versions
              */
-            smartLink: (input) => this.client.companies.smartLink.mutate(input),
+            smartLink: (input) => client.companies.smartLink.mutate(input),
         };
     }
+    // ==========================================================================
+    // Features
+    // ==========================================================================
     /**
-     * Feature access operations
+     * Feature access and entitlement operations.
+     *
+     * Check what features a company has access to and their current usage.
+     * Features are defined in ChatarminOS and assigned via subscription tiers.
+     *
+     * @example
+     * ```typescript
+     * // Check if company can use a feature
+     * const access = await os.features.check({
+     *   companyId: company.id,
+     *   featureCode: 'ai_credit'
+     * })
+     *
+     * if (access.canUse) {
+     *   // Feature is available
+     *   console.log(`Remaining: ${access.remaining}`)
+     * } else {
+     *   // Feature is disabled or limit reached
+     *   console.log('Upgrade required')
+     * }
+     * ```
      */
     get features() {
         const client = this.client;
         return {
             /**
-             * Check if a company has access to a feature
-             * Returns detailed access info including usage and limits
+             * Check if a company has access to a specific feature.
+             *
+             * Returns detailed access information including whether the feature
+             * is enabled, current usage, limits, and whether they can use more.
+             *
+             * @param input - Check parameters
+             * @param input.companyId - Company ID to check
+             * @param input.featureCode - Feature code (e.g., "ai_credit")
+             * @returns Detailed feature access information
+             *
+             * @example
+             * ```typescript
+             * const access = await os.features.check({
+             *   companyId: 'comp_xxx',
+             *   featureCode: 'ai_credit'
+             * })
+             *
+             * console.log({
+             *   enabled: access.isEnabled,
+             *   canUse: access.canUse,
+             *   usage: access.currentUsage,
+             *   limit: access.quantityLimit,
+             *   remaining: access.remaining,
+             *   included: access.includedQuantity
+             * })
+             * ```
              */
             check: (input) => client.features.check.query(input),
             /**
-             * List all features and their access status for a company
-             * Useful for showing a company's full feature set
+             * List all features and their access status for a company.
+             *
+             * Returns a complete list of features with their current status,
+             * useful for displaying a company's full feature set or building
+             * a feature comparison view.
+             *
+             * @param companyId - Company ID to list features for
+             * @returns Array of feature access records
+             *
+             * @example
+             * ```typescript
+             * const features = await os.features.listAccess(company.id)
+             *
+             * for (const f of features) {
+             *   console.log(`${f.featureName}: ${f.isEnabled ? '✓' : '✗'}`)
+             *   if (f.quantityLimit) {
+             *     console.log(`  Usage: ${f.currentUsage} / ${f.quantityLimit}`)
+             *   }
+             * }
+             * ```
              */
             listAccess: (companyId) => client.features.getAccess.query({ companyId }),
         };
     }
+    // ==========================================================================
+    // Billing
+    // ==========================================================================
     /**
-     * Billing and usage tracking
+     * Billing, usage tracking, and subscription management.
+     *
+     * Track feature usage for billing, claim subscriptions from Stripe checkout,
+     * or link existing Stripe subscriptions to companies.
+     *
+     * @example Track Usage
+     * ```typescript
+     * await os.billing.trackUsage({
+     *   companyId: company.id,
+     *   featureCode: 'ai_credit',
+     *   quantity: 1,
+     *   idempotencyKey: `msg_${messageId}` // Prevent double-counting
+     * })
+     * ```
+     *
+     * @example Claim Checkout Subscription
+     * ```typescript
+     * // After Stripe checkout completes
+     * const result = await os.billing.claimCheckout({
+     *   companyId: company.id,
+     *   checkoutSessionId: 'cs_xxx'
+     * })
+     * ```
+     *
+     * @example Link Existing Subscription
+     * ```typescript
+     * // When you create subscriptions on your Stripe account
+     * const result = await os.billing.linkSubscription({
+     *   companyId: company.id,
+     *   stripeSubscriptionId: 'sub_xxx',
+     *   tierCode: 'pro' // Apply tier features
+     * })
+     * ```
      */
     get billing() {
+        const client = this.client;
         return {
             /**
-             * Track usage for a feature
-             * Returns updated usage info after tracking
+             * Track usage for a metered feature.
+             *
+             * Increments the usage counter for a feature and returns the
+             * updated usage information. Use idempotency keys to prevent
+             * duplicate tracking.
+             *
+             * @param input - Usage tracking parameters
+             * @returns Updated usage information
+             * @throws {TRPCError} If feature is not enabled or limit exceeded
+             *
+             * @example
+             * ```typescript
+             * const result = await os.billing.trackUsage({
+             *   companyId: 'comp_xxx',
+             *   featureCode: 'ai_credit',
+             *   quantity: 5,
+             *   idempotencyKey: `request_${requestId}`,
+             *   metadata: { model: 'gpt-4' }
+             * })
+             *
+             * console.log({
+             *   currentUsage: result.currentUsage,
+             *   remaining: result.remaining,
+             *   billable: result.billableQuantity,
+             *   isAtLimit: result.isAtLimit
+             * })
+             * ```
+             */
+            trackUsage: (input) => client.billing.trackUsage.mutate(input),
+            /**
+             * Claim a subscription from a completed Stripe Checkout Session.
+             *
+             * Use this after a user completes Stripe checkout in your product.
+             * This links the subscription and customer to the company in OS.
+             *
+             * @param input - Claim parameters
+             * @returns Result with subscription ID and claim status
+             *
+             * @example
+             * ```typescript
+             * // In your Stripe checkout success handler:
+             * const result = await os.billing.claimCheckout({
+             *   companyId: company.id,
+             *   checkoutSessionId: session.id // From Stripe callback
+             * })
+             *
+             * if (result.alreadyClaimed) {
+             *   console.log('Subscription was already claimed')
+             * } else {
+             *   console.log(`Claimed subscription: ${result.subscriptionId}`)
+             * }
+             * ```
+             */
+            claimCheckout: (input) => client.billing.claimCheckout.mutate(input),
+            /**
+             * Link an existing Stripe subscription to a company.
+             *
+             * Use this when you create subscriptions on your product's Stripe
+             * account and want OS to track them. Optionally applies tier features.
+             *
+             * @param input - Link parameters
+             * @returns Result with subscription ID, link status, and features applied
+             *
+             * @example
+             * ```typescript
+             * // After creating subscription on your Stripe account:
+             * const result = await os.billing.linkSubscription({
+             *   companyId: company.id,
+             *   stripeSubscriptionId: 'sub_xxx',
+             *   stripeCustomerId: 'cus_xxx', // Optional
+             *   tierCode: 'pro', // Apply tier features
+             *   displayName: 'Pro Plan'
+             * })
+             *
+             * console.log({
+             *   subscriptionId: result.subscriptionId,
+             *   isNew: !result.alreadyLinked,
+             *   featuresApplied: result.featuresApplied
+             * })
+             * ```
+             */
+            linkSubscription: (input) => client.billing.linkSubscription.mutate(input),
+            /**
+             * Get billing status for a company.
+             *
+             * Quick check for subscription status, active features, and
+             * billing profile information.
+             *
+             * @param companyId - Company ID to check
+             * @returns Billing status overview
+             *
+             * @example
+             * ```typescript
+             * const status = await os.billing.getStatus(company.id)
+             *
+             * 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}`)
+             * }
+             * ```
              */
-            trackUsage: (input) => this.client.billing.trackUsage.mutate(input),
+            getStatus: (companyId) => client.billing.getStatus.query({ companyId }),
         };
     }
+    // ==========================================================================
+    // Links
+    // ==========================================================================
     /**
-     * Link operations - manually link external IDs to companies
+     * Manual link operations for associating external IDs with companies.
+     *
+     * Use these when you need direct control over the linking process,
+     * bypassing the smart link algorithm.
+     *
+     * @example
+     * ```typescript
+     * // Manually link an external org ID to an existing company
+     * await os.links.create({
+     *   companyId: 'comp_xxx',
+     *   externalOrgId: 'org_abc123',
+     *   externalUserId: 'user_xyz'
+     * })
+     * ```
      */
     get links() {
+        const client = this.client;
         return {
             /**
-             * Simple link: associate external org ID with an existing company
+             * Create a manual link between your external org ID and an existing company.
+             *
+             * Use this when you know the exact company ID and want to create
+             * a direct link without smart matching.
+             *
+             * @param input - Link parameters
+             * @returns The created link record
+             *
+             * @example
+             * ```typescript
+             * const link = await os.links.create({
+             *   companyId: 'comp_xxx',
+             *   externalOrgId: 'org_abc123',
+             *   externalUserId: 'user_xyz' // Optional: user who created the link
+             * })
+             * ```
              */
-            create: (input) => this.client.companies.linkToProduct.mutate({
+            create: (input) => client.companies.linkToProduct.mutate({
                 customerId: input.companyId,
-                productCode: "", // Will use the product from API key
+                productCode: "", // Uses product from API key
                 externalOrgId: input.externalOrgId,
                 externalUserId: input.externalUserId,
                 linkType: "identified",
             }),
         };
     }
+    // ==========================================================================
+    // Subscriptions
+    // ==========================================================================
     /**
-     * Subscription operations
+     * Subscription and tier management.
+     *
+     * Create subscriptions from tier templates, list available tiers,
+     * and manage company entitlements.
      *
      * @example
      * ```typescript
-     * // Create subscription from a tier template
-     * const sub = await os.subscriptions.create("free", {
-     *   companyId: "comp_xxx",
-     * })
+     * // List available tiers
+     * const tiers = await os.subscriptions.tiers()
      *
-     * // Create with overrides
-     * const sub = await os.subscriptions.create("pro", {
-     *   companyId: "comp_xxx",
+     * // Apply a tier to a company
+     * const result = await os.subscriptions.create('pro', {
+     *   companyId: company.id,
      *   features: {
-     *     ai_agent: { included_quantity: 200 }
+     *     ai_credit: { included_quantity: 500 }
      *   }
      * })
-     *
-     * // Get available tiers
-     * const tiers = await os.subscriptions.tiers()
      * ```
      */
     get subscriptions() {
         const client = this.client;
         return {
             /**
-             * Create or apply a subscription tier to a company
+             * Apply a subscription tier to a company.
+             *
+             * This grants the company access to all features defined in the tier.
+             * Use feature overrides to customize specific feature limits.
              *
-             * @param tierCode - The tier code (e.g., "free", "pro", "enterprise")
-             * @param options - Subscription options including companyId and optional overrides
+             * **Note:** This only applies feature access, it doesn't create a
+             * Stripe subscription. Use `billing.linkSubscription` for that.
+             *
+             * @param tierCode - Tier code (e.g., "free", "pro", "enterprise")
+             * @param options - Company ID and optional feature overrides
+             * @returns Result with tier info and features applied
+             *
+             * @example
+             * ```typescript
+             * // Apply tier with defaults
+             * await os.subscriptions.create('free', {
+             *   companyId: company.id
+             * })
+             *
+             * // Apply with custom limits
+             * await os.subscriptions.create('pro', {
+             *   companyId: company.id,
+             *   features: {
+             *     ai_credit: { included_quantity: 1000 },
+             *     seats: { max_quantity: 50 }
+             *   }
+             * })
+             * ```
              */
             create: (tierCode, options) => client.tiers.applyByCode.mutate({
                 tierCode,
@@ -149,38 +537,159 @@ export class ChatarminOS {
                 featureOverrides: options.features,
             }),
             /**
-             * Get all available tiers for the current product
+             * Get all available tiers for your product.
+             *
+             * Returns the list of subscription tiers configured in ChatarminOS
+             * for your product, including their features.
+             *
+             * @returns Array of available tiers with features
+             *
+             * @example
+             * ```typescript
+             * const tiers = await os.subscriptions.tiers()
+             *
+             * for (const tier of tiers) {
+             *   console.log(`${tier.name} (${tier.code})`)
+             *   for (const feature of tier.features) {
+             *     console.log(`  - ${feature.name}`)
+             *   }
+             * }
+             * ```
              */
             tiers: () => client.tiers.listForProduct.query({ includeInactive: false }),
             /**
-             * Get tier details by code
+             * Get detailed information about a specific tier.
+             *
+             * Returns the tier with all its features, including Stripe price IDs
+             * if configured. Use this to get the prices needed to create a
+             * Stripe subscription.
+             *
+             * @param tierCode - Tier code to look up
+             * @returns Tier details with features and Stripe prices
+             *
+             * @example
+             * ```typescript
+             * const tier = await os.subscriptions.getTier('pro')
+             *
+             * console.log(tier.stripePriceIds)
+             * // ['price_xxx', 'price_yyy']
+             *
+             * // Use these to create a Stripe subscription
+             * const sub = await stripe.subscriptions.create({
+             *   customer: customerId,
+             *   items: tier.stripePriceIds.map(price => ({ price }))
+             * })
+             * ```
              */
             getTier: (tierCode) => client.tiers.getByCode.query({ code: tierCode }),
         };
     }
+    // ==========================================================================
+    // Tiers
+    // ==========================================================================
     /**
-     * Tier operations (alias for subscriptions.tiers for convenience)
+     * Tier operations (convenient access to subscription tiers).
      *
-     * @example
+     * Tiers define what features and limits a company gets. Each tier
+     * can have associated Stripe prices for billing.
+     *
+     * @example Get Tier with Stripe Prices
      * ```typescript
-     * // Get tier details
-     * const freeTier = await os.tiers.get("free")
-     * console.log(freeTier.features)
+     * const tier = await os.tiers.get('pro')
+     *
+     * // Create Stripe subscription using tier prices
+     * const stripeSub = await stripe.subscriptions.create({
+     *   customer: stripeCustomerId,
+     *   items: tier.stripePriceIds.map(price => ({ price }))
+     * })
+     *
+     * // Link back to OS
+     * await os.billing.linkSubscription({
+     *   companyId: company.id,
+     *   stripeSubscriptionId: stripeSub.id,
+     *   tierCode: 'pro'
+     * })
      * ```
      */
     get tiers() {
         const client = this.client;
         return {
             /**
-             * List all available tiers
+             * List all available tiers for your product.
+             *
+             * @returns Array of tiers with their features
+             *
+             * @example
+             * ```typescript
+             * const tiers = await os.tiers.list()
+             * console.log(tiers.map(t => t.name))
+             * // ['Free', 'Pro', 'Enterprise']
+             * ```
              */
             list: () => client.tiers.listForProduct.query({ includeInactive: false }),
             /**
-             * Get tier details by code
+             * Get detailed tier information by code.
+             *
+             * Returns full tier details including:
+             * - Features with config values
+             * - Stripe price IDs for subscription creation
+             * - Stripe product info
+             *
+             * @param tierCode - Tier code (e.g., "free", "pro")
+             * @returns Tier with features and Stripe prices
+             *
+             * @example
+             * ```typescript
+             * const tier = await os.tiers.get('pro')
+             *
+             * // Access features
+             * for (const feature of tier.features) {
+             *   console.log(feature.code, feature.configValues)
+             * }
+             *
+             * // Get Stripe prices for subscription creation
+             * console.log(tier.stripePriceIds)
+             * // ['price_xxx', 'price_yyy']
+             *
+             * // Feature-level Stripe info
+             * const aiFeature = tier.features.find(f => f.code === 'ai_credit')
+             * if (aiFeature?.stripe) {
+             *   console.log(aiFeature.stripe.priceId)
+             *   console.log(aiFeature.stripe.unitAmount) // in cents
+             * }
+             * ```
              */
             get: (tierCode) => client.tiers.getByCode.query({ code: tierCode }),
             /**
-             * Apply a tier to a company
+             * Apply a tier's features to a company (without Stripe).
+             *
+             * Use this for:
+             * - Free tiers that don't need Stripe
+             * - Trial periods
+             * - Manual entitlement grants
+             *
+             * For paid tiers with Stripe, use `billing.linkSubscription` instead.
+             *
+             * @param tierCode - Tier code to apply
+             * @param options - Company ID and optional feature overrides
+             * @returns Result with applied features count
+             *
+             * @example
+             * ```typescript
+             * // Apply free tier
+             * const result = await os.tiers.apply('free', {
+             *   companyId: company.id
+             * })
+             * console.log(`Applied ${result.featuresApplied} features`)
+             *
+             * // Apply with overrides
+             * await os.tiers.apply('trial', {
+             *   companyId: company.id,
+             *   features: {
+             *     ai_credit: { included_quantity: 100 }
+             *   }
+             * })
+             * ```
              */
             apply: (tierCode, options) => client.tiers.applyByCode.mutate({
                 tierCode,
@@ -189,6 +698,170 @@ export class ChatarminOS {
             }),
         };
     }
+    // ==========================================================================
+    // Onboarding
+    // ==========================================================================
+    /**
+     * Complete onboarding flow in a single call.
+     *
+     * This is the recommended way to onboard new customers. It handles:
+     * 1. Smart company matching/creation
+     * 2. Product linking
+     * 3. Subscription claiming/linking
+     * 4. Tier feature application
+     *
+     * **Scenarios:**
+     *
+     * 1. **Stripe Checkout completed** - Pass `checkoutSessionId`
+     * 2. **Free signup** - Pass `tierCode` only
+     * 3. **You create Stripe subscription** - Pass `stripeSubscriptionId` + `tierCode`
+     *
+     * @param input - Onboarding parameters
+     * @returns Result with company info and billing status
+     *
+     * @example 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 callback
+     * })
+     *
+     * // result.billingStatus.claimed = true
+     * ```
+     *
+     * @example Scenario 2: Free tier signup
+     * ```typescript
+     * const result = await os.onboard({
+     *   externalOrgId: 'org_abc123',
+     *   hints: {
+     *     companyName: 'Acme Inc',
+     *     domain: 'acme.com'
+     *   },
+     *   tierCode: 'free',
+     *   contactEmail: 'admin@acme.com',
+     *   contactName: 'John Doe'
+     * })
+     *
+     * // result.billingStatus.tierApplied = true
+     * ```
+     *
+     * @example Scenario 3: You create Stripe subscription
+     * ```typescript
+     * // First, get tier prices
+     * const tier = await os.tiers.get('pro')
+     *
+     * // Create subscription on YOUR Stripe account
+     * const stripeSub = await stripe.subscriptions.create({
+     *   customer: stripeCustomerId,
+     *   items: tier.stripePriceIds.map(price => ({ price }))
+     * })
+     *
+     * // Then 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
+     * ```
+     *
+     * @example Handle existing customers
+     * ```typescript
+     * const result = await os.onboard({
+     *   externalOrgId: 'org_abc123',
+     *   hints: { companyName: 'Acme Inc' }
+     * })
+     *
+     * if (result.linkStatus === 'already_linked') {
+     *   console.log('Welcome back!')
+     * } else if (result.linkStatus === 'linked') {
+     *   console.log('Found existing company, linked!')
+     * } else {
+     *   console.log('New company created!')
+     * }
+     * ```
+     */
+    async onboard(input) {
+        // Step 1: Smart link or create company
+        let companyId;
+        let companyName;
+        let linkStatus;
+        const smartLinkResult = await this.companies.smartLink({
+            externalOrgId: input.externalOrgId,
+            hints: input.hints ?? {},
+        });
+        if (smartLinkResult.status === "already_linked") {
+            companyId = smartLinkResult.customerId;
+            companyName = smartLinkResult.customerName;
+            linkStatus = "already_linked";
+        }
+        else if (smartLinkResult.status === "linked") {
+            companyId = smartLinkResult.customerId;
+            companyName = smartLinkResult.customerName;
+            linkStatus = "linked";
+        }
+        else {
+            // No match found - create new company
+            const newCompany = await this.companies.create({
+                name: input.hints?.companyName ?? `Company ${input.externalOrgId}`,
+                domain: input.hints?.domain,
+                externalOrgId: input.externalOrgId,
+                contactEmail: input.contactEmail,
+                contactName: input.contactName,
+            });
+            companyId = newCompany.id;
+            companyName = newCompany.name;
+            linkStatus = "created";
+        }
+        // Step 2: Handle billing
+        let billingStatus;
+        if (input.checkoutSessionId) {
+            // Claim subscription from checkout
+            const claimResult = await this.billing.claimCheckout({
+                companyId,
+                checkoutSessionId: input.checkoutSessionId,
+            });
+            billingStatus = {
+                subscriptionId: claimResult.subscriptionId,
+                claimed: !claimResult.alreadyClaimed,
+            };
+        }
+        else if (input.stripeSubscriptionId) {
+            // Link existing subscription
+            const linkResult = await this.billing.linkSubscription({
+                companyId,
+                stripeSubscriptionId: input.stripeSubscriptionId,
+                stripeCustomerId: input.stripeCustomerId,
+                tierCode: input.tierCode,
+            });
+            billingStatus = {
+                subscriptionId: linkResult.subscriptionId,
+                linked: !linkResult.alreadyLinked,
+                tierApplied: linkResult.tierApplied,
+            };
+        }
+        else if (input.tierCode) {
+            // Just apply tier features (no Stripe)
+            const applyResult = await this.tiers.apply(input.tierCode, { companyId });
+            billingStatus = {
+                tierApplied: applyResult.featuresApplied > 0,
+            };
+        }
+        return {
+            companyId,
+            companyName,
+            linkStatus,
+            billingStatus,
+        };
+    }
 }
 // Default export
 export default ChatarminOS;