@chatarmin/os 1.5.8 → 1.7.0

package/dist/index.d.ts

@@ -1,8 +1,8 @@
 import type { AppRouter } from "@chatarmin/api";
-export type { BillingDashboardContext, BillingDashboardFeatureBilling, BillingDashboardFeatureRow, GetBillingDashboardContextInput, } from "./types/billing-dashboard-context.js";
-export type { FeatureAccessListItem } from "./types/feature-access-list-item.js";
-export type { ListProductFeatureCatalogInput, ProductFeatureCatalogItem } from "./types/product-feature-catalog.js";
-export type { ClaimCheckoutInput, EnsureFeatureSubscriptionInput, EnsureFeatureSubscriptionResult, LinkSubscriptionInput, RelinkBillingProfileInput, SetUsageInput, SyncCompanyFromStripeInput, SyncCompanyFromStripeResult, UsageResult, } from "./types/chatarmin-os-billing-inputs.js";
+import { type CompaniesClient } from "./companies";
+export { webhooks, constructProductWebhookEvent, generateTestWebhookHeaders, OsWebhookSignatureVerificationError, WEBHOOK_ID_HEADER, WEBHOOK_SIGNATURE_HEADER, WEBHOOK_TIMESTAMP_HEADER, } from "./webhooks";
+export type { ConstructProductWebhookEventOptions, ProductWebhookEventPayload, ProductWebhookHeaders, VerifiedProductWebhookEvent, } from "./webhooks";
+export type { CompaniesClient, CompanyAssignee, CompanyAssignees, CreateCompanyInput, CreateCompanyResult, GetCompanyInput, LinkedCompany, ListCompaniesInput, ListCompaniesResult, ListLinkedCompaniesInput, ListLinkedCompaniesResult, ProductCompany, UpdateCompanyResult, } from "./companies";
 /**
  * Configuration options for the ChatarminOS SDK client.
  */
@@ -42,72 +42,6 @@ export declare class ChatarminOSError extends Error {
         details: ChatarminOSErrorDetails;
     };
 }
-/**
- * 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;
-    /** Display label for the product link (e.g., "Chatarmin CX", "Shopify") */
-    label?: string;
-    /** Primary contact email */
-    contactEmail?: string;
-    /** Primary contact name */
-    contactName?: string;
-    /** Optional: Set a historical created_at timestamp (ISO 8601 format) */
-    createdAt?: string;
-}
-/**
- * Input for smart linking a company.
- */
-export interface SmartLinkInput {
-    /** Your product's unique organization ID for this company */
-    externalOrgId: string;
-    /** Display label for the product link (e.g., "Chatarmin CX", "Shopify") */
-    label: 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.8
-     */
-    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.
  */
@@ -125,10 +59,26 @@ export interface FeatureCheckInput {
     verifySubscription?: boolean;
 }
 /**
- * Billing details for a feature when `includeBillingDetails: true`.
- * Includes Stripe period/price details and `stripeSubscriptionItemId`.
+ * Billing details for a feature (when includeBillingDetails: true)
  */
-export type FeatureBillingDetails = import("./types/billing-dashboard-context.js").BillingDashboardFeatureBilling;
+export interface FeatureBillingDetails {
+    /** Stripe subscription item ID */
+    stripeSubscriptionItemId: string | null;
+    /** Current billing period start */
+    currentPeriodStart: Date | null;
+    /** Current billing period end */
+    currentPeriodEnd: Date | null;
+    /** Unit amount in cents (e.g., 100 = $1.00) */
+    unitAmount: number | null;
+    /** Currency code (e.g., "usd") */
+    currency: string | null;
+    /** Billing interval (e.g., "month", "year") */
+    intervalUnit: string | null;
+    /** Usage type (e.g., "metered", "licensed") */
+    usageType: string | null;
+    /** Subscription status (e.g., "active", "trialing") */
+    subscriptionStatus: string | null;
+}
 /**
  * Input for listing feature access.
  */
@@ -199,21 +149,94 @@ export interface FeatureSetAccessInput {
     /** When the access expires (null for no expiration) */
     validUntil?: Date | null;
 }
-export interface LinkedCompany {
-    id: string;
-    name: string;
-    shortId: string | null;
-    domain: string | null;
-    externalOrgId: string;
-    label: string | null;
+export interface SyncCompanyFromStripeInput {
+    companyId: string;
+    stripeCustomerId?: string;
+    forceReassign?: boolean;
+}
+export interface SyncCompanyFromStripeResult {
+    billingProfileId: string;
+    stripeCustomerId: string;
+    subscriptionsSynced: number;
+    subscriptionItemsSynced: number;
+    featuresLinked: number;
+    matchedMeters: number;
+}
+export interface EnsureFeatureSubscriptionInput {
+    companyId: string;
+    featureCode: string;
+    stripeSubscriptionId?: string;
+}
+export interface RelinkBillingProfileInput {
+    companyId: string;
+    stripeCustomerId: string;
+}
+export interface EnsureFeatureSubscriptionResult {
+    success: boolean;
+    subscriptionItemId: string | null;
+    stripePriceId: string | null;
+    stripeSubscriptionId: string | null;
+    action: "already_linked" | "linked_existing" | "created_new" | "failed";
+    error?: string;
+}
+/**
+ * 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>;
+}
+/**
+ * Result from usage operations.
+ */
+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;
 }
-export interface ListLinkedCompaniesInput {
-    limit?: number;
-    cursor?: string;
+/**
+ * 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;
 }
-export interface ListLinkedCompaniesResult {
-    companies: LinkedCompany[];
-    nextCursor?: 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.
@@ -277,16 +300,13 @@ export interface OnboardInput {
     /** Display label for the product link (e.g., "Chatarmin CX", "Shopify") */
     label: string;
     /**
-     * Hints for smart company matching.
-     * Provide as much info as possible for best matching.
+     * Company details used when creating a new company via onboard().
      */
     hints?: {
-        /** Company name to match against */
+        /** Company name for new companies */
         companyName?: string;
-        /** Domain to match (highest confidence) */
+        /** Domain for new companies */
         domain?: string;
-        /** Email addresses to match by domain */
-        emails?: string[];
     };
     /**
      * Stripe checkout session ID to claim.
@@ -334,10 +354,9 @@ export interface OnboardResult {
     /**
      * 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";
+    linkStatus: "already_linked" | "created";
     /** Billing status (only present if billing was configured) */
     billingStatus?: {
         /** Subscription ID if created/claimed */
@@ -396,6 +415,10 @@ export interface OnboardResult {
  * @see https://os.chatarmin.com/docs for full documentation
  */
 export declare class ChatarminOS {
+    static webhooks: {
+        constructEvent: typeof import("./webhooks").constructProductWebhookEvent;
+        generateTestHeaders: typeof import("./webhooks").generateTestWebhookHeaders;
+    };
     private client;
     private call;
     /**
@@ -424,10 +447,13 @@ export declare class ChatarminOS {
      * @example
      * ```typescript
      * // Look up a company by your org ID
-     * const company = await os.companies.getByProductLink({
+     * const company = await os.companies.get({
      *   externalOrgId: 'org_abc123'
      * })
      *
+     * // Route support mail to the assigned CSM
+     * const csmEmail = company?.assignees.csm?.email
+     *
      * // Create a new company
      * const newCompany = await os.companies.create({
      *   name: 'Acme Inc',
@@ -437,134 +463,7 @@ export declare class ChatarminOS {
      * })
      * ```
      */
-    get companies(): {
-        /**
-         * List companies linked to your product.
-         *
-         * Use cursor pagination to iterate through all linked companies.
-         */
-        listLinked: (input?: ListLinkedCompaniesInput) => Promise<ListLinkedCompaniesResult>;
-        /**
-         * 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;
-        }) => Promise<{
-            id: string;
-            name: string;
-            domain: string | null;
-            external_org_id: string;
-            external_user_id: string | null;
-        } | null>;
-        /**
-         * 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: CreateCompanyInput) => Promise<{
-            id: string;
-            shortId: string | null;
-            name: string;
-            externalOrgId: string;
-        }>;
-        /**
-         * Update company metadata.
-         *
-         * Used for backfilling data like historical created_at dates.
-         *
-         * @param input - Update parameters
-         * @returns Whether the update was applied
-         *
-         * @example
-         * ```typescript
-         * await os.companies.update({
-         *   companyId: 'uuid-here',
-         *   createdAt: '2023-01-15T10:30:00.000Z'
-         * })
-         * ```
-         */
-        update: (input: {
-            companyId: string;
-            createdAt?: string;
-        }) => Promise<{
-            updated: boolean;
-        }>;
-        /**
-         * 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
-         *
-         * @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: SmartLinkInput) => Promise<SmartLinkResult>;
-    };
+    get companies(): CompaniesClient;
     /**
      * Contact management operations.
      *
@@ -689,7 +588,29 @@ export declare class ChatarminOS {
             avatar_url: string | null;
         }[]>;
     };
-    /** Feature access and entitlements (`check`, `listAccess`, `listForProduct`, …). */
+    /**
+     * 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 specific feature.
@@ -761,8 +682,49 @@ export declare class ChatarminOS {
          * }
          * ```
          */
-        listAccess: (input: ListFeatureAccessInput | string) => Promise<import("@chatarmin/contracts").FeatureAccessCommonFields[]>;
-        listForProduct: (input?: import("./index.js").ListProductFeatureCatalogInput) => Promise<import("./index.js").ProductFeatureCatalogItem[]>;
+        listAccess: (input: ListFeatureAccessInput | string) => Promise<({
+            featureCode: string;
+            featureName: string;
+            description: string | null;
+            hasQuantity: boolean;
+            isEnabled: boolean;
+            quantityLimit: number | null;
+            includedQuantity: number;
+            currentUsage: number;
+            source: string;
+            validUntil: Date | null;
+            stripeSubscriptionItemId: string | null;
+            stripePriceId: string | null;
+            stripeSubscriptionId: string | null;
+            meterId: string | null;
+            configValues: Record<string, unknown>;
+        } | {
+            billing: {
+                stripeSubscriptionItemId: string | null;
+                currentPeriodStart: Date | null;
+                currentPeriodEnd: Date | null;
+                unitAmount: number | null;
+                currency: string | null;
+                intervalUnit: string | null;
+                usageType: string | null;
+                subscriptionStatus: string | null;
+            };
+            featureCode: string;
+            featureName: string;
+            description: string | null;
+            hasQuantity: boolean;
+            isEnabled: boolean;
+            quantityLimit: number | null;
+            includedQuantity: number;
+            currentUsage: number;
+            source: string;
+            validUntil: Date | null;
+            stripeSubscriptionItemId: string | null;
+            stripePriceId: string | null;
+            stripeSubscriptionId: string | null;
+            meterId: string | null;
+            configValues: Record<string, unknown>;
+        })[]>;
         /**
          * Update feature access for a company with partial config merge.
          *
@@ -943,8 +905,61 @@ export declare class ChatarminOS {
      * ```
      */
     get billing(): {
-        getDashboardContext: (input: import("./index.js").GetBillingDashboardContextInput) => Promise<import("./index.js").BillingDashboardContext>;
-        setUsage: (input: import("./index.js").SetUsageInput) => Promise<import("./index.js").UsageResult>;
+        /**
+         * 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>;
+        /**
+         * 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;
@@ -953,10 +968,10 @@ export declare class ChatarminOS {
             id: string;
             created_at: Date;
             metadata: unknown;
-            event_type: string;
+            billing_profile_id: string | null;
             source: string;
             idempotency_key: string;
-            billing_profile_id: string | null;
+            event_type: string;
             subscription_item_id: string | null;
             feature_access_id: string | null;
             meter_code: string;
@@ -972,8 +987,36 @@ export declare class ChatarminOS {
             stripe_event_id: string | null;
             stripe_delivery_error: string | null;
             delivered_at: Date | null;
+            reconcile_target_key: string | null;
+            reconcile_period_start: Date | null;
+            reconcile_period_end: Date | null;
+            reconcile_current_stripe_quantity: number | null;
         }[]>;
-        claimCheckout: (input: import("./index.js").ClaimCheckoutInput) => Promise<{
+        /**
+         * 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;
@@ -984,7 +1027,34 @@ export declare class ChatarminOS {
             alreadyClaimed: boolean;
             status: import("stripe").Stripe.Subscription.Status;
         }>;
-        linkSubscription: (input: import("./index.js").LinkSubscriptionInput) => Promise<{
+        /**
+         * 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;
@@ -999,6 +1069,31 @@ export declare class ChatarminOS {
             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;
@@ -1011,23 +1106,23 @@ export declare class ChatarminOS {
                 name: string;
                 metadata: unknown;
                 status: string;
-                mrr_cents: number;
-                mrr_committed_cents: number;
-                mrr_usage_cents: number;
-                contract_start_at: Date | null;
-                contract_end_at: Date | null;
-                subscription_status: string;
-                max_days_overdue: number;
                 company_id: string | null;
+                last_synced_at: Date | null;
                 stripe_customer_id: string;
                 link_status: string;
                 default_currency: string;
                 has_payment_method: boolean;
+                subscription_status: string;
+                contract_start_at: Date | null;
+                contract_end_at: Date | null;
+                mrr_cents: number;
+                mrr_committed_cents: number;
+                mrr_usage_cents: number;
                 open_invoices_count: number;
                 open_amount_cents: number;
                 past_due_invoices_count: number;
                 past_due_amount_cents: number;
-                last_synced_at: Date | null;
+                max_days_overdue: number;
                 company_group_id: string | null;
             }[];
             activeSubscriptions: {
@@ -1044,8 +1139,14 @@ export declare class ChatarminOS {
             }[];
             enabledFeaturesCount: number;
         }>;
-        syncCompanyFromStripe: (input: import("./index.js").SyncCompanyFromStripeInput) => Promise<import("./index.js").SyncCompanyFromStripeResult>;
-        relinkBillingProfile: (input: import("./index.js").RelinkBillingProfileInput) => Promise<{
+        /**
+         * Sync billing profile, subscriptions, and feature access from Stripe.
+         */
+        syncCompanyFromStripe: (input: SyncCompanyFromStripeInput) => Promise<SyncCompanyFromStripeResult>;
+        /**
+         * Relink billing profile to a new Stripe customer (destructive).
+         */
+        relinkBillingProfile: (input: RelinkBillingProfileInput) => Promise<{
             billingProfileId: string;
             stripeCustomerId: string;
             subscriptionsSynced: number;
@@ -1053,7 +1154,10 @@ export declare class ChatarminOS {
             featuresLinked: number;
             matchedMeters: number;
         }>;
-        ensureFeatureSubscription: (input: import("./index.js").EnsureFeatureSubscriptionInput) => Promise<import("./index.js").EnsureFeatureSubscriptionResult>;
+        /**
+         * Ensure a feature is linked to an active Stripe subscription item.
+         */
+        ensureFeatureSubscription: (input: EnsureFeatureSubscriptionInput) => Promise<EnsureFeatureSubscriptionResult>;
     };
     /**
      * Manual link operations for associating external IDs with companies.
@@ -1121,6 +1225,7 @@ export declare class ChatarminOS {
             link_type: string;
             label: string | null;
             external_display_name: string | null;
+            billing_profile_id: string | null;
         }>;
         /**
          * Delete all product links for this product.
@@ -1569,8 +1674,6 @@ export declare class ChatarminOS {
      *
      * 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!')
      * }