@chatarmin/os 0.1.10 → 0.1.115

package/dist/index.d.ts

@@ -1,47 +1,322 @@
 import type { AppRouter } from "@chatarmin/api";
+/**
+ * Configuration options for the ChatarminOS SDK client.
+ */
 export interface ChatarminOSConfig {
-    /** API key generated in the OS admin for your product */
+    /**
+     * API key generated in the OS admin for your product.
+     * Found in Settings → Developers → API Keys.
+     * @example "os_sk_xxxxxxxxxxxxxxxxxxxx"
+     */
     apiKey: string;
-    /** Base URL of the OS API (default: https://os.chatarmin.com/api/v1) */
+    /**
+     * Base URL of the OS API.
+     * @default "https://os.chatarmin.com/api/v1"
+     */
     baseUrl?: string;
 }
+/**
+ * Input for creating a new company with product link.
+ */
+export interface CreateCompanyInput {
+    /** Company name (e.g., "Acme Inc") */
+    name: string;
+    /** Company domain for matching (e.g., "acme.com") */
+    domain?: string;
+    /** Your product's unique organization ID for this company */
+    externalOrgId: string;
+    /** Optional user ID who created this in your product */
+    externalUserId?: string;
+    /** Primary contact email */
+    contactEmail?: string;
+    /** Primary contact name */
+    contactName?: string;
+}
+/**
+ * Input for smart linking a company.
+ */
+export interface SmartLinkInput {
+    /** Your product's unique organization ID for this company */
+    externalOrgId: string;
+    /** Hints to help match existing companies */
+    hints: {
+        /** Company name to match against */
+        companyName?: string;
+        /** Domain to match (highest confidence) */
+        domain?: string;
+        /** Email addresses to match by domain */
+        emails?: string[];
+    };
+    /**
+     * Minimum confidence score (0-1) required for auto-linking.
+     * @default 0.6
+     */
+    minConfidence?: number;
+}
+/**
+ * Result from smart link operation.
+ */
+export interface SmartLinkResult {
+    /** Status of the link operation */
+    status: "already_linked" | "linked" | "no_match" | "suggestions";
+    /** Company ID if linked */
+    customerId?: string;
+    /** Company name if linked */
+    customerName?: string;
+    /** Confidence score of the match */
+    confidence?: number;
+    /** Reason for the match (e.g., "domain_match", "name_match") */
+    reason?: string;
+    /** Suggestions if no auto-link (when status is "suggestions") */
+    suggestions?: Array<{
+        customerId: string;
+        customerName: string;
+        confidence: number;
+        reason: string;
+    }>;
+}
+/**
+ * Input for checking feature access.
+ */
+export interface FeatureCheckInput {
+    /** Company ID to check */
+    companyId: string;
+    /** Feature code (e.g., "ai_credit", "whatsapp_messages") */
+    featureCode: string;
+}
+/**
+ * Input for tracking feature usage.
+ */
+export interface TrackUsageInput {
+    /** Company ID */
+    companyId: string;
+    /** Feature code to track */
+    featureCode: string;
+    /**
+     * Quantity to track.
+     * @default 1
+     */
+    quantity?: number;
+    /**
+     * Idempotency key to prevent duplicate tracking.
+     * Use a unique ID per operation (e.g., message ID).
+     */
+    idempotencyKey?: string;
+    /** Additional metadata for the usage event */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Input for claiming a Stripe checkout subscription.
+ */
+export interface ClaimCheckoutInput {
+    /** Company ID to link the subscription to */
+    companyId: string;
+    /** Stripe checkout session ID (cs_xxx) */
+    checkoutSessionId: string;
+}
+/**
+ * Input for linking an existing Stripe subscription.
+ */
+export interface LinkSubscriptionInput {
+    /** Company ID to link the subscription to */
+    companyId: string;
+    /** Stripe subscription ID (sub_xxx) */
+    stripeSubscriptionId: string;
+    /** Stripe customer ID (cus_xxx) - fetched from subscription if not provided */
+    stripeCustomerId?: string;
+    /** Tier code to apply features from (e.g., "free", "pro") */
+    tierCode?: string;
+    /** Display name for the subscription */
+    displayName?: string;
+}
+/**
+ * Input for applying a tier to a company.
+ */
+export interface ApplyTierInput {
+    /** Company ID to apply the tier to */
+    companyId: string;
+    /** Feature overrides (key: feature code, value: config overrides) */
+    features?: Record<string, Record<string, unknown>>;
+}
+/**
+ * Input for the unified onboarding flow.
+ */
+export interface OnboardInput {
+    /** Your product's unique organization ID for this customer */
+    externalOrgId: string;
+    /**
+     * Hints for smart company matching.
+     * Provide as much info as possible for best matching.
+     */
+    hints?: {
+        /** Company name to match against */
+        companyName?: string;
+        /** Domain to match (highest confidence) */
+        domain?: string;
+        /** Email addresses to match by domain */
+        emails?: string[];
+    };
+    /**
+     * Stripe checkout session ID to claim.
+     * Use when user completed Stripe checkout in your product.
+     * @example "cs_test_xxxxxxxxxxxxx"
+     */
+    checkoutSessionId?: string;
+    /**
+     * Existing Stripe subscription ID to link.
+     * Use when you create subscriptions on your product's Stripe account.
+     * @example "sub_xxxxxxxxxxxxx"
+     */
+    stripeSubscriptionId?: string;
+    /**
+     * Stripe customer ID.
+     * Will be fetched from subscription if not provided.
+     * @example "cus_xxxxxxxxxxxxx"
+     */
+    stripeCustomerId?: string;
+    /**
+     * Tier code to apply features from.
+     * Use for free tier signups or to tag linked subscriptions.
+     * @example "free" | "pro" | "enterprise"
+     */
+    tierCode?: string;
+    /** Primary contact email for new companies */
+    contactEmail?: string;
+    /** Primary contact name for new companies */
+    contactName?: string;
+}
+/**
+ * Result from the onboarding flow.
+ */
+export interface OnboardResult {
+    /** The company ID (either existing or newly created) */
+    companyId: string;
+    /** The company name */
+    companyName: string;
+    /**
+     * How the company was linked:
+     * - `already_linked`: Company was already linked to your product
+     * - `linked`: Existing company was found and linked
+     * - `created`: New company was created
+     */
+    linkStatus: "already_linked" | "linked" | "created";
+    /** Billing status (only present if billing was configured) */
+    billingStatus?: {
+        /** Subscription ID if created/claimed */
+        subscriptionId?: string;
+        /** True if subscription was claimed from checkout */
+        claimed?: boolean;
+        /** True if subscription was linked */
+        linked?: boolean;
+        /** True if tier features were applied */
+        tierApplied?: boolean;
+    };
+}
 /**
  * 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 declare class ChatarminOS {
     private 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: ChatarminOSConfig);
     /**
-     * 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(): {
         /**
-         * 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: {
             externalOrgId: string;
@@ -53,81 +328,125 @@ export declare class ChatarminOS {
             external_user_id: string | null;
         } | null>;
         /**
-         * 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: {
-            name: string;
-            domain?: string;
-            externalOrgId: string;
-            externalUserId?: string;
-            contactEmail?: string;
-            contactName?: string;
-        }) => Promise<{
+        create: (input: CreateCompanyInput) => Promise<{
             id: string;
             shortId: string | null;
             name: string;
             externalOrgId: string;
         }>;
         /**
-         * Smart link - find and link company using hints
+         * Smart link - intelligently find and link a company using hints.
          *
-         * @experimental
+         * 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
+         *
+         * @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: {
-            externalOrgId: string;
-            hints: {
-                companyName?: string;
-                domain?: string;
-                emails?: string[];
-            };
-            minConfidence?: number;
-        }) => Promise<{
-            status: "already_linked";
-            customerId: string;
-            customerName: string | undefined;
-            confidence: number;
-            suggestions?: undefined;
-            reason?: undefined;
-        } | {
-            status: "no_match";
-            suggestions: never[];
-            customerId?: undefined;
-            customerName?: undefined;
-            confidence?: undefined;
-            reason?: undefined;
-        } | {
-            status: "linked";
-            customerId: string;
-            customerName: string;
-            confidence: number;
-            reason: string;
-            suggestions?: undefined;
-        } | {
-            status: "suggestions";
-            suggestions: {
-                customerId: string;
-                customerName: string;
-                confidence: number;
-                reason: string;
-            }[];
-            customerId?: undefined;
-            customerName?: undefined;
-            confidence?: undefined;
-            reason?: undefined;
-        }>;
+        smartLink: (input: SmartLinkInput) => Promise<SmartLinkResult>;
     };
     /**
-     * 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(): {
         /**
-         * 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: {
-            companyId: string;
-            featureCode: string;
-        }) => Promise<{
+        check: (input: FeatureCheckInput) => Promise<{
             featureCode: string;
             isEnabled: boolean;
             hasQuantity: boolean;
@@ -139,8 +458,26 @@ export declare class ChatarminOS {
             canUse: boolean;
         }>;
         /**
-         * 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: string) => Promise<{
             featureCode: string;
@@ -155,20 +492,71 @@ export declare class ChatarminOS {
         }[]>;
     };
     /**
-     * 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(): {
         /**
-         * 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: {
-            companyId: string;
-            featureCode: string;
-            quantity?: number;
-            idempotencyKey?: string;
-            metadata?: Record<string, unknown>;
-        }) => Promise<{
+        trackUsage: (input: TrackUsageInput) => Promise<{
             success: boolean;
             featureCode: string;
             currentUsage: number;
@@ -179,13 +567,159 @@ export declare class ChatarminOS {
             billableQuantity: number;
             meterId: string;
         }>;
+        /**
+         * 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: ClaimCheckoutInput) => Promise<{
+            success: boolean;
+            subscriptionId: string;
+            alreadyClaimed: boolean;
+            status?: undefined;
+        } | {
+            success: boolean;
+            subscriptionId: string;
+            alreadyClaimed: boolean;
+            status: import("stripe").Stripe.Subscription.Status;
+        }>;
+        /**
+         * 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: 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;
+        }>;
+        /**
+         * 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}`)
+         * }
+         * ```
+         */
+        getStatus: (companyId: string) => Promise<{
+            hasBillingProfile: boolean;
+            stripeCustomerId: string | null;
+            activeSubscriptions: {
+                id: string;
+                status: string;
+                stripeSubscriptionId: string | null;
+                currentPeriodEnd: Date | null;
+                trialEnd: Date | null;
+                tier: {
+                    code: string;
+                    name: string | null;
+                } | null;
+            }[];
+            enabledFeaturesCount: number;
+        }>;
     };
     /**
-     * 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(): {
         /**
-         * 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: {
             companyId: string;
@@ -206,44 +740,80 @@ export declare class ChatarminOS {
         } | undefined>;
     };
     /**
-     * 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(): {
         /**
-         * 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: string, options: {
-            companyId: string;
-            features?: Record<string, Record<string, unknown>>;
-        }) => Promise<{
+        create: (tierCode: string, options: ApplyTierInput) => Promise<{
             tierId: string;
             tierName: string;
             featuresApplied: number;
         }>;
         /**
-         * 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: () => Promise<{
             features: {
@@ -265,7 +835,28 @@ export declare class ChatarminOS {
             product_id: string;
         }[]>;
         /**
-         * 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: string) => Promise<{
             id: string;
@@ -278,22 +869,57 @@ export declare class ChatarminOS {
                 hasQuantity: boolean;
                 configValues: unknown;
                 catalogPriceId: string | null;
+                stripe: {
+                    priceId: string;
+                    productId: string | null;
+                    productName: string | null;
+                    unitAmount: number | null;
+                    currency: string | null;
+                    interval: string | null;
+                    intervalCount: number | null;
+                    usageType: string | null;
+                    billingScheme: string | null;
+                } | null;
             }[];
+            stripePriceIds: string[];
         }>;
     };
     /**
-     * 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(): {
         /**
-         * 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: () => Promise<{
             features: {
@@ -315,7 +941,36 @@ export declare class ChatarminOS {
             product_id: string;
         }[]>;
         /**
-         * 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: string) => Promise<{
             id: string;
@@ -328,20 +983,146 @@ export declare class ChatarminOS {
                 hasQuantity: boolean;
                 configValues: unknown;
                 catalogPriceId: string | null;
+                stripe: {
+                    priceId: string;
+                    productId: string | null;
+                    productName: string | null;
+                    unitAmount: number | null;
+                    currency: string | null;
+                    interval: string | null;
+                    intervalCount: number | null;
+                    usageType: string | null;
+                    billingScheme: string | null;
+                } | null;
             }[];
+            stripePriceIds: string[];
         }>;
         /**
-         * 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: string, options: {
-            companyId: string;
-            features?: Record<string, Record<string, unknown>>;
-        }) => Promise<{
+        apply: (tierCode: string, options: ApplyTierInput) => Promise<{
             tierId: string;
             tierName: string;
             featuresApplied: number;
         }>;
     };
+    /**
+     * 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!')
+     * }
+     * ```
+     */
+    onboard(input: OnboardInput): Promise<OnboardResult>;
 }
 export type { AppRouter };
 export default ChatarminOS;