@chatarmin/os 1.8.8 → 1.13.0

package/dist/onboard-flow.js

@@ -0,0 +1,118 @@
+function isFreeSignupTier(tierCode) {
+    return tierCode === 'free';
+}
+export async function runOnboardFlow(params) {
+    let companyId;
+    let companyName;
+    let linkStatus;
+    const existing = await params.companies.get({
+        externalOrgId: params.input.externalOrgId,
+    });
+    if (existing) {
+        companyId = existing.id;
+        companyName = existing.name;
+        linkStatus = 'already_linked';
+    }
+    else {
+        const newCompany = await params.companies.create({
+            name: params.input.hints?.companyName ?? `Company ${params.input.externalOrgId}`,
+            domain: params.input.hints?.domain,
+            externalOrgId: params.input.externalOrgId,
+            label: params.input.label,
+            contactEmail: params.input.contactEmail,
+            contactName: params.input.contactName,
+            createdAt: params.input.createdAt,
+        });
+        companyId = newCompany.id;
+        companyName = newCompany.name;
+        linkStatus = 'created';
+    }
+    const hasExplicitBilling = Boolean(params.input.checkoutSessionId) || Boolean(params.input.stripeSubscriptionId);
+    if (hasExplicitBilling) {
+        let billingStatus;
+        try {
+            if (params.input.checkoutSessionId) {
+                const claimResult = await params.billing.claimCheckout({
+                    companyId,
+                    checkoutSessionId: params.input.checkoutSessionId,
+                    externalOrgId: params.input.externalOrgId,
+                });
+                billingStatus = {
+                    subscriptionId: claimResult.subscriptionId,
+                    claimed: !claimResult.alreadyClaimed,
+                };
+            }
+            else {
+                const linkResult = await params.billing.linkSubscription({
+                    companyId,
+                    stripeSubscriptionId: params.input.stripeSubscriptionId,
+                    stripeCustomerId: params.input.stripeCustomerId,
+                    tierCode: params.input.tierCode,
+                    externalOrgId: params.input.externalOrgId,
+                });
+                billingStatus = {
+                    subscriptionId: linkResult.subscriptionId,
+                    linked: !linkResult.alreadyLinked,
+                    tierApplied: linkResult.tierApplied,
+                    featuresApplied: linkResult.featuresApplied,
+                    tierCode: params.input.tierCode,
+                };
+            }
+        }
+        catch (err) {
+            billingStatus = {
+                error: err instanceof Error ? err.message : String(err),
+            };
+        }
+        return {
+            companyId,
+            companyName,
+            linkStatus,
+            billingStatus,
+        };
+    }
+    if (isFreeSignupTier(params.input.tierCode) && linkStatus === 'created') {
+        try {
+            const setupResult = await params.companies.setupOnboardBilling({
+                companyId,
+                externalOrgId: params.input.externalOrgId,
+                tierCode: params.input.tierCode,
+                name: params.input.billing?.name ??
+                    params.input.hints?.companyName ??
+                    companyName,
+                email: params.input.billing?.email ?? params.input.contactEmail,
+                currency: params.input.billing?.currency,
+                trialPeriodDays: params.input.billing?.trialPeriodDays,
+            });
+            return {
+                companyId,
+                companyName,
+                linkStatus,
+                billingStatus: {
+                    billingProfileId: setupResult.billingProfileId,
+                    stripeCustomerId: setupResult.stripeCustomerId,
+                    subscriptionId: setupResult.subscriptionId,
+                    tierApplied: setupResult.featuresApplied > 0,
+                    featuresApplied: setupResult.featuresApplied,
+                    tierCode: setupResult.tierCode,
+                    subscriptionCreated: setupResult.subscriptionCreated,
+                },
+            };
+        }
+        catch (err) {
+            return {
+                companyId,
+                companyName,
+                linkStatus,
+                billingStatus: {
+                    error: err instanceof Error ? err.message : String(err),
+                },
+            };
+        }
+    }
+    return {
+        companyId,
+        companyName,
+        linkStatus,
+    };
+}

package/dist/onboard-types.d.ts

@@ -0,0 +1,99 @@
+/**
+ * Input for the unified onboarding flow.
+ */
+export interface OnboardInput {
+    /** Your product's unique organization ID for this customer */
+    externalOrgId: string;
+    /** Display label for the product link (e.g., "Chatarmin CX", "Shopify") */
+    label: string;
+    /**
+     * Company details used when creating a new company via onboard().
+     */
+    hints?: {
+        /** Company name for new companies */
+        companyName?: string;
+        /** Domain for new companies */
+        domain?: 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 for onboard billing setup (`free`) or claim/link flows.
+     * @example "free" | "pro" | "enterprise"
+     */
+    tierCode?: string;
+    /**
+     * Billing identity overrides for free-tier onboard billing setup.
+     */
+    billing?: {
+        name?: string;
+        email?: string;
+        currency?: string;
+        trialPeriodDays?: number | null;
+    };
+    /** Primary contact email for new companies */
+    contactEmail?: string;
+    /** Primary contact name for new companies */
+    contactName?: string;
+    /**
+     * Historical created_at timestamp for the company.
+     * Only used when creating new companies (not for existing matches).
+     * @example "2024-01-15T10:30:00.000Z"
+     */
+    createdAt?: 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
+     * - `created`: New company was created
+     */
+    linkStatus: 'already_linked' | 'created';
+    /** Billing status when checkoutSessionId or stripeSubscriptionId was provided */
+    billingStatus?: {
+        /** Billing profile ID when created or reused */
+        billingProfileId?: string;
+        /** Stripe customer ID when a billing profile exists */
+        stripeCustomerId?: string;
+        /** 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;
+        /** Number of feature access rows upserted */
+        featuresApplied?: number;
+        /** Tier code that was applied */
+        tierCode?: string;
+        /** True if a new subscription was created during onboard */
+        subscriptionCreated?: boolean;
+        /** Error message if billing failed (company still linked) */
+        error?: string;
+    };
+}
+//# sourceMappingURL=onboard-types.d.ts.map

package/dist/onboard-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"onboard-types.d.ts","sourceRoot":"","sources":["../src/onboard-types.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,8DAA8D;IAC9D,aAAa,EAAE,MAAM,CAAA;IAErB,2EAA2E;IAC3E,KAAK,EAAE,MAAM,CAAA;IAEb;;OAEG;IACH,KAAK,CAAC,EAAE;QACN,qCAAqC;QACrC,WAAW,CAAC,EAAE,MAAM,CAAA;QACpB,+BAA+B;QAC/B,MAAM,CAAC,EAAE,MAAM,CAAA;KAChB,CAAA;IAED;;;;OAIG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAA;IAE1B;;;;OAIG;IACH,oBAAoB,CAAC,EAAE,MAAM,CAAA;IAE7B;;;;OAIG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAA;IAEzB;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAA;IAEjB;;OAEG;IACH,OAAO,CAAC,EAAE;QACR,IAAI,CAAC,EAAE,MAAM,CAAA;QACb,KAAK,CAAC,EAAE,MAAM,CAAA;QACd,QAAQ,CAAC,EAAE,MAAM,CAAA;QACjB,eAAe,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;KAChC,CAAA;IAED,8CAA8C;IAC9C,YAAY,CAAC,EAAE,MAAM,CAAA;IAErB,6CAA6C;IAC7C,WAAW,CAAC,EAAE,MAAM,CAAA;IAEpB;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,wDAAwD;IACxD,SAAS,EAAE,MAAM,CAAA;IAEjB,uBAAuB;IACvB,WAAW,EAAE,MAAM,CAAA;IAEnB;;;;OAIG;IACH,UAAU,EAAE,gBAAgB,GAAG,SAAS,CAAA;IAExC,iFAAiF;IACjF,aAAa,CAAC,EAAE;QACd,gDAAgD;QAChD,gBAAgB,CAAC,EAAE,MAAM,CAAA;QACzB,uDAAuD;QACvD,gBAAgB,CAAC,EAAE,MAAM,CAAA;QACzB,yCAAyC;QACzC,cAAc,CAAC,EAAE,MAAM,CAAA;QACvB,qDAAqD;QACrD,OAAO,CAAC,EAAE,OAAO,CAAA;QACjB,sCAAsC;QACtC,MAAM,CAAC,EAAE,OAAO,CAAA;QAChB,yCAAyC;QACzC,WAAW,CAAC,EAAE,OAAO,CAAA;QACrB,6CAA6C;QAC7C,eAAe,CAAC,EAAE,MAAM,CAAA;QACxB,iCAAiC;QACjC,QAAQ,CAAC,EAAE,MAAM,CAAA;QACjB,4DAA4D;QAC5D,mBAAmB,CAAC,EAAE,OAAO,CAAA;QAC7B,6DAA6D;QAC7D,KAAK,CAAC,EAAE,MAAM,CAAA;KACf,CAAA;CACF"}

package/dist/onboard-types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chatarmin/os",
-  "version": "1.8.8",
+  "version": "1.13.0",
   "description": "Type-safe SDK for ChatarminOS - Customer & Subscription Management",
   "type": "module",
   "publishConfig": {