@churnkey/react 0.6.0 → 0.6.2

package/dist/step-graph-BpoAhd0d.d.ts

@@ -0,0 +1,650 @@
+import { ReactNode, ReactElement, ComponentType } from 'react';
+
+interface DirectAddress {
+    line1?: string;
+    line2?: string;
+    city?: string;
+    state?: string;
+    postalCode?: string;
+    /** ISO 3166-1 alpha-2 */
+    country?: string;
+}
+interface DirectCustomer {
+    id: string;
+    email?: string;
+    name?: string;
+    lastName?: string;
+    phone?: string;
+    /** ISO 4217 */
+    currency?: string;
+    addresses?: DirectAddress[];
+    metadata?: Record<string, unknown>;
+}
+interface DirectPrice {
+    id: string;
+    type?: 'standalone' | 'product';
+    active?: boolean;
+    productId?: string;
+    name?: string;
+    description?: string;
+    duration?: {
+        interval: 'day' | 'week' | 'month' | 'year';
+        intervalCount?: number;
+    };
+    amount: {
+        model?: 'fixed' | 'tiered';
+        /** Smallest currency unit (cents for USD). */
+        value: number;
+        currency?: string;
+    };
+    metadata?: Record<string, unknown>;
+}
+interface DirectCoupon {
+    id?: string;
+    name?: string;
+    percentOff?: number;
+    /** Smallest currency unit (cents for USD). */
+    amountOff?: number;
+    currency?: string;
+    duration?: 'once' | 'repeating' | 'forever';
+    durationInMonths?: number;
+    metadata?: Record<string, unknown>;
+}
+type SubscriptionStatus = {
+    name: 'active';
+    currentPeriod: {
+        start: Date | string;
+        end: Date | string;
+    };
+} | {
+    name: 'trial';
+    trial: {
+        start: Date | string;
+        end: Date | string;
+    };
+    currentPeriod?: {
+        start: Date | string;
+        end: Date | string;
+    };
+} | {
+    name: 'paused';
+    pause: {
+        start: Date | string;
+        end?: Date | string;
+    };
+    currentPeriod?: {
+        start: Date | string;
+        end: Date | string;
+    };
+} | {
+    name: 'canceled';
+    canceledAt: Date | string;
+} | {
+    name: 'unpaid';
+    currentPeriod?: {
+        start: Date | string;
+        end: Date | string;
+    };
+} | {
+    name: 'future';
+    currentPeriod?: {
+        start: Date | string;
+        end: Date | string;
+    };
+};
+interface DirectSubscriptionItem {
+    id?: string;
+    price: DirectPrice;
+    quantity?: number;
+}
+interface DirectSubscription {
+    id: string;
+    customerId?: string;
+    start: Date | string;
+    status: SubscriptionStatus;
+    items: DirectSubscriptionItem[];
+    duration?: {
+        interval: 'day' | 'week' | 'month' | 'year';
+        intervalCount?: number;
+    };
+    end?: Date | string;
+    discounts?: Array<{
+        id?: string;
+        coupon?: DirectCoupon;
+        start?: Date | string;
+        end?: Date | string;
+    }>;
+    metadata?: Record<string, unknown>;
+}
+interface DiscountOffer {
+    type: 'discount';
+    couponId?: string;
+    percentOff?: number;
+    /** Smallest currency unit (cents for USD). */
+    amountOff?: number;
+    currency?: string;
+    durationInMonths?: number;
+}
+interface PauseOffer {
+    type: 'pause';
+    months: number;
+    interval?: 'month' | 'week';
+}
+interface PlanChangeOffer {
+    type: 'plan_change';
+    plans: PlanOption[];
+}
+/**
+ * Plan option in a `plan_change` offer — `DirectPrice` plus optional
+ * cancel-flow merchandising fields. Marketing fields are presentation-only
+ * and live on `PlanOption` rather than `DirectPrice` so `Direct` stays a
+ * clean billing-data shape reusable outside the cancel-flow context.
+ */
+interface PlanOption extends DirectPrice {
+    /** Short marketing line (e.g. "Most popular"). */
+    tagline?: string;
+    /** Bullet list of plan features shown on the card. */
+    features?: string[];
+    /** Pre-formatted "before" price rendered struck-through (e.g. "$49/mo"). */
+    msrp?: string;
+}
+interface TrialExtensionOffer {
+    type: 'trial_extension';
+    days: number;
+}
+interface ContactOffer {
+    type: 'contact';
+    url?: string;
+    label?: string;
+}
+interface RedirectOffer {
+    type: 'redirect';
+    url: string;
+    label: string;
+}
+interface RebateOffer {
+    type: 'rebate';
+    /** The rebate amount (pre-tax), smallest currency unit. The card is refunded this plus any tax charged on it. */
+    amountMinor: number;
+    currency: string;
+    /** Gross paid on the target invoice. Server-resolved in token mode. */
+    amountPaidMinor?: number;
+    /** amountPaidMinor minus the full refund (the rebate plus its tax). Server-resolved in token mode. */
+    netAfterRebateMinor?: number;
+    paymentMethodBrand?: string;
+    paymentMethodLast4?: string;
+}
+interface CustomOfferConfig {
+    type: string;
+    data?: Record<string, unknown>;
+}
+type BuiltInOfferConfig = DiscountOffer | PauseOffer | PlanChangeOffer | TrialExtensionOffer | ContactOffer | RedirectOffer | RebateOffer;
+type OfferConfig = BuiltInOfferConfig | CustomOfferConfig;
+type OfferDecision = OfferConfig & {
+    copy: OfferCopy;
+    decisionId?: string;
+};
+interface OfferCopy {
+    headline: string;
+    /**
+     * May contain HTML when the flow was authored in the Churnkey dashboard
+     * (the description editor is rich text). Render with the exported
+     * `RichText` component — the same renderer the built-in steps use — rather
+     * than as a text node, or the markup shows escaped.
+     */
+    body: string;
+    cta: string;
+    declineCta: string;
+}
+type AcceptedOffer = OfferConfig & {
+    /** Survey reason that routed to this offer. Absent when the offer was
+     *  declared as a standalone `OfferStep`. */
+    reasonId?: string;
+    /** Payload from custom offers — whatever your component passed to
+     *  `onAccept(result)`. Built-in offer types do not populate this. */
+    result?: Record<string, unknown>;
+};
+interface ReasonConfig {
+    id: string;
+    label: string;
+    /**
+     * When true, picking this reason reveals a text input below the reason list.
+     * The typed text lands on the session as `followupResponse`. `surveyChoiceId`
+     * still carries the reason's `id` and `surveyChoiceValue` still carries the
+     * static `label`, so analytics groupings stay stable.
+     */
+    freeform?: boolean;
+    offer?: OfferConfig;
+}
+interface SurveyStep {
+    type: 'survey';
+    guid?: string;
+    title?: string;
+    description?: string;
+    reasons: ReasonConfig[];
+    classNames?: SurveyClassNames;
+}
+interface OfferStep {
+    type: 'offer';
+    guid?: string;
+    title?: string;
+    description?: string;
+    /**
+     * Offer attached to this step. Set this to declare a standalone offer
+     * step (one that isn't routed from a survey reason). `copy` is optional —
+     * the SDK synthesizes default copy from the offer config when none is
+     * provided, the same way it does for survey-attached offers.
+     */
+    offer?: OfferConfig | OfferDecision;
+    classNames?: OfferClassNames;
+}
+interface FeedbackStep {
+    type: 'feedback';
+    guid?: string;
+    title?: string;
+    description?: string;
+    placeholder?: string;
+    required?: boolean;
+    minLength?: number;
+    classNames?: FeedbackClassNames;
+}
+interface ConfirmStep {
+    type: 'confirm';
+    guid?: string;
+    title?: string;
+    description?: string;
+    /** Optional bullet list of what the customer is giving up. Rendered between the description and the period-end notice. */
+    losses?: string[];
+    /** Heading above the loss list. Defaults to "You'll lose access to:". */
+    lossesLabel?: string;
+    confirmLabel?: string;
+    goBackLabel?: string;
+    classNames?: ConfirmClassNames;
+}
+interface SuccessStep {
+    type: 'success';
+    guid?: string;
+    savedTitle?: string;
+    savedDescription?: string;
+    cancelledTitle?: string;
+    cancelledDescription?: string;
+    classNames?: SuccessClassNames;
+}
+interface CustomStepConfig {
+    type: string;
+    guid?: string;
+    title?: string;
+    description?: string;
+    data?: Record<string, unknown>;
+}
+type BuiltInStep = SurveyStep | OfferStep | FeedbackStep | ConfirmStep | SuccessStep;
+type Step = BuiltInStep | CustomStepConfig;
+type BuiltInStepType = 'survey' | 'offer' | 'feedback' | 'confirm' | 'success';
+interface SurveyClassNames {
+    root?: string;
+    title?: string;
+    description?: string;
+    reasonList?: string;
+    reasonButton?: string;
+    reasonButtonSelected?: string;
+    reasonLabel?: string;
+    followupInput?: string;
+    continueButton?: string;
+}
+interface OfferClassNames {
+    root?: string;
+    title?: string;
+    description?: string;
+    card?: string;
+    headline?: string;
+    body?: string;
+    acceptButton?: string;
+    declineButton?: string;
+    discountBadge?: string;
+    priceComparison?: string;
+    pauseSlider?: string;
+    planGrid?: string;
+    planCard?: string;
+    planCardSelected?: string;
+}
+interface FeedbackClassNames {
+    root?: string;
+    title?: string;
+    description?: string;
+    textarea?: string;
+    characterCount?: string;
+    submitButton?: string;
+}
+interface ConfirmClassNames {
+    root?: string;
+    title?: string;
+    description?: string;
+    lossList?: string;
+    lossLabel?: string;
+    lossItem?: string;
+    lossBullet?: string;
+    confirmButton?: string;
+    goBackButton?: string;
+    periodEndNotice?: string;
+}
+interface SuccessClassNames {
+    root?: string;
+    icon?: string;
+    title?: string;
+    description?: string;
+    closeButton?: string;
+}
+interface StructuralClassNames {
+    overlay?: string;
+    modal?: string;
+    closeButton?: string;
+    backButton?: string;
+}
+/**
+ * Typed surface for `appearance.variables`. Every key maps to a `--ck-*`
+ * CSS custom property. Consumers who need a token not in this list can
+ * still set the underlying CSS variable directly — these are the ones
+ * exposed through the typed JS API.
+ */
+interface AppearanceVariables {
+    colorBackground: string;
+    colorSurface: string;
+    colorSurfaceMuted: string;
+    colorBorder: string;
+    colorBorderStrong: string;
+    colorText: string;
+    colorTextSecondary: string;
+    colorTextMuted: string;
+    colorPrimary: string;
+    colorPrimaryHover: string;
+    colorPrimarySoft: string;
+    colorSuccess: string;
+    colorSuccessSoft: string;
+    colorDanger: string;
+    colorDangerHover: string;
+    colorDangerSoft: string;
+    fontFamily: string;
+    fontFamilyMono: string;
+    /**
+     * Display face used by step titles and other visual headlines. Defaults
+     * to `fontFamily`. Set this when your brand uses a separate display face
+     * (Tiempos, Canela, etc.) for headings.
+     */
+    fontFamilyDisplay: string;
+    fontSize: string;
+    /** Weight applied to the step title. Default `'600'`. */
+    fontWeightDisplay: string;
+    /** Letter spacing applied to the step title. Default `'-0.015em'`. */
+    letterSpacingDisplay: string;
+    borderRadius: string;
+    radiusSm: string;
+    radiusMd: string;
+    radiusLg: string;
+    radiusXl: string;
+    shadowModal: string;
+    shadowCard: string;
+    /**
+     * Color of the dim behind the modal. Defaults to a neutral translucent
+     * ink. Set to `color-mix(in srgb, var(--ck-color-primary) 40%, transparent)`
+     * to derive the overlay from your primary color, or any CSS color value.
+     */
+    overlayColor: string;
+}
+interface Appearance {
+    /**
+     * `'auto'` follows the user's OS preference (`prefers-color-scheme`) and
+     * watches for changes. Default: `'light'`.
+     */
+    colorScheme?: 'auto' | 'light' | 'dark';
+    variables?: Partial<AppearanceVariables>;
+}
+interface CustomStepProps {
+    step: CustomStepConfig;
+    customer: DirectCustomer | null;
+    subscriptions: DirectSubscription[];
+    onNext: (result?: Record<string, unknown>) => void;
+    onBack: () => void;
+}
+interface CustomOfferProps {
+    offer: OfferDecision;
+    customer: DirectCustomer | null;
+    subscriptions: DirectSubscription[];
+    onAccept: (result?: Record<string, unknown>) => Promise<void>;
+    onDecline: () => void;
+    isProcessing: boolean;
+}
+interface ComponentOverrides {
+    Modal?: (props: ModalProps) => ReactElement;
+    CloseButton?: (props: CloseButtonProps) => ReactElement;
+    BackButton?: (props: BackButtonProps) => ReactElement;
+    Survey?: (props: SurveyStepProps) => ReactElement;
+    Offer?: (props: OfferStepProps) => ReactElement;
+    Feedback?: (props: FeedbackStepProps) => ReactElement;
+    Confirm?: (props: ConfirmStepProps) => ReactElement;
+    Success?: (props: SuccessStepProps) => ReactElement;
+    ReasonButton?: (props: ReasonButtonProps) => ReactElement;
+    DiscountOffer?: (props: OfferStepProps) => ReactElement;
+    PauseOffer?: (props: OfferStepProps) => ReactElement;
+    PlanChangeOffer?: (props: OfferStepProps) => ReactElement;
+    TrialExtensionOffer?: (props: OfferStepProps) => ReactElement;
+    ContactOffer?: (props: OfferStepProps) => ReactElement;
+    RedirectOffer?: (props: OfferStepProps) => ReactElement;
+    RebateOffer?: (props: OfferStepProps) => ReactElement;
+}
+type CustomComponents = Record<string, ComponentType<CustomStepProps> | ComponentType<CustomOfferProps>>;
+interface ModalProps {
+    open: boolean;
+    onClose: () => void;
+    children: ReactNode;
+    className?: string;
+    overlayClassName?: string;
+}
+interface CloseButtonProps {
+    onClose: () => void;
+    className?: string;
+}
+interface BackButtonProps {
+    onBack: () => void;
+    className?: string;
+}
+interface SurveyStepProps {
+    title: string;
+    description?: string;
+    customer: DirectCustomer | null;
+    subscriptions: DirectSubscription[];
+    reasons: ReasonConfig[];
+    selectedReason: string | null;
+    onSelectReason: (id: string) => void;
+    /** Free-text value when the selected reason has `freeform: true`. Lands on the session as `followupResponse`. */
+    followupResponse: string;
+    /** Set the follow-up response. The SDK forwards the value to the session. */
+    onFollowupResponseChange: (text: string) => void;
+    onNext: () => void;
+    classNames?: SurveyClassNames;
+    components?: Partial<ComponentOverrides>;
+}
+interface OfferStepProps {
+    title?: string;
+    description?: string;
+    customer: DirectCustomer | null;
+    subscriptions: DirectSubscription[];
+    offer: OfferDecision;
+    /**
+     * Accept the offer. The optional `result` is included on the resulting
+     * `AcceptedOffer` payload — used by offers that need a user choice (e.g.
+     * `plan_change` passes `{ planId }`).
+     */
+    onAccept: (result?: Record<string, unknown>) => Promise<void>;
+    onDecline: () => void;
+    isProcessing: boolean;
+    classNames?: OfferClassNames;
+    /**
+     * Forwarded to the default `Offer` switcher so it can dispatch to per-type
+     * overrides (`DiscountOffer`, `PauseOffer`, etc). Custom `Offer`
+     * implementations can ignore this.
+     */
+    components?: Partial<ComponentOverrides>;
+}
+interface FeedbackStepProps {
+    title: string;
+    description?: string;
+    customer: DirectCustomer | null;
+    subscriptions: DirectSubscription[];
+    placeholder?: string;
+    required: boolean;
+    minLength: number;
+    value: string;
+    onChange: (text: string) => void;
+    onSubmit: () => void;
+    classNames?: FeedbackClassNames;
+}
+interface ConfirmStepProps {
+    title: string;
+    description?: string;
+    customer: DirectCustomer | null;
+    subscriptions: DirectSubscription[];
+    losses?: string[];
+    lossesLabel?: string;
+    confirmLabel: string;
+    goBackLabel: string;
+    onConfirm: () => Promise<void>;
+    onGoBack: () => void;
+    isProcessing: boolean;
+    classNames?: ConfirmClassNames;
+}
+interface SuccessStepProps {
+    outcome: 'saved' | 'cancelled';
+    offer?: OfferDecision;
+    title: string;
+    description?: string;
+    customer: DirectCustomer | null;
+    subscriptions: DirectSubscription[];
+    onClose: () => void;
+    classNames?: SuccessClassNames;
+}
+interface ReasonButtonProps {
+    reason: ReasonConfig;
+    index: number;
+    isSelected: boolean;
+    onSelect: (id: string) => void;
+}
+interface FlowState {
+    step: string;
+    currentStepId: string;
+    selectedReason: string | null;
+    followupResponse: string;
+    feedback: string;
+    outcome: 'saved' | 'cancelled' | null;
+    isProcessing: boolean;
+    error: Error | null;
+    customer: DirectCustomer | null;
+    subscriptions: DirectSubscription[];
+}
+declare const MODES: readonly ["live", "test", "sandbox"];
+/**
+ * Environment a session runs against. `'test'` and `'sandbox'` both keep
+ * sessions out of live analytics; `'sandbox'` additionally routes server-side
+ * billing actions to the org's Stripe Sandbox credentials, which live under a
+ * separate Stripe account ID from live/test mode.
+ */
+type Mode = (typeof MODES)[number];
+interface FlowConfig extends FlowCallbacks {
+    appId?: string;
+    customer?: DirectCustomer;
+    subscriptions?: DirectSubscription[];
+    /**
+     * Client-side attribute layer on top of provider data, e.g. usage counts
+     * or entitlements only the host app knows (`{ videosCreated: 28 }`). In token mode
+     * they're sent with the config request so segments can match on them when
+     * picking the blueprint. In every mode they resolve as merge fields and
+     * are recorded on the session, taking precedence over `customer.metadata`
+     * keys. Same role as the embed's `customerAttributes`.
+     */
+    customerAttributes?: Record<string, unknown>;
+    session?: string;
+    apiBaseUrl?: string;
+    steps?: Step[];
+    /**
+     * Tags the session as live, test, or sandbox. Use `'test'` from staging so
+     * your dashboard can filter out non-production traffic, or `'sandbox'` when
+     * the org is connected to a Stripe Sandbox. Defaults to `'live'`.
+     * In token mode the mode is encoded in the signed token and overrides
+     * this field.
+     */
+    mode?: Mode;
+}
+type OfferCallback = (offer: AcceptedOffer, customer: DirectCustomer | null) => Promise<void> | void;
+type CancelCallback = (customer: DirectCustomer | null) => Promise<void> | void;
+/**
+ * Two kinds of callbacks, distinguished by name:
+ *
+ * - `handle<Type>` runs the action. When defined, it replaces whatever
+ *   Churnkey would do on the server — the consumer takes responsibility.
+ *   In local mode (no token), handlers are the only path that does anything.
+ * - `on<Type>` is a listener that fires after the action. Side effects only —
+ *   refetch state, log analytics, show a toast. Errors thrown here are
+ *   swallowed; listeners can't flip the flow into an error state.
+ *
+ * `onAccept` is a catch-all that fires alongside the per-type listener.
+ */
+interface FlowCallbacks {
+    handleDiscount?: OfferCallback;
+    handlePause?: OfferCallback;
+    handlePlanChange?: OfferCallback;
+    handleTrialExtension?: OfferCallback;
+    handleRebate?: OfferCallback;
+    handleCancel?: CancelCallback;
+    onAccept?: OfferCallback;
+    onDiscount?: OfferCallback;
+    onPause?: OfferCallback;
+    onPlanChange?: OfferCallback;
+    onTrialExtension?: OfferCallback;
+    onRebate?: OfferCallback;
+    onCancel?: CancelCallback;
+    onClose?: () => void;
+    onStepChange?: (step: string, prevStep: string) => void;
+}
+interface CancelFlowProps extends FlowCallbacks {
+    appId?: string;
+    customer?: DirectCustomer;
+    subscriptions?: DirectSubscription[];
+    /** See FlowConfig.customerAttributes. */
+    customerAttributes?: Record<string, unknown>;
+    session?: string;
+    steps?: Step[];
+    apiBaseUrl?: string;
+    /** See FlowConfig.mode. Ignored in token mode (the token is authoritative). */
+    mode?: Mode;
+    appearance?: Appearance;
+    classNames?: StructuralClassNames;
+    components?: Partial<ComponentOverrides>;
+    customComponents?: CustomComponents;
+}
+
+interface ResolvedStep {
+    guid: string;
+    type: string;
+    defaultNextStep?: string;
+    defaultPreviousStep?: string;
+    title?: string;
+    description?: string;
+    reasons?: ReasonConfig[];
+    offersAttached?: Record<string, string>;
+    numChoices?: number;
+    offer?: OfferDecision;
+    /** True if this step was synthesized from a survey choice. Used by stepIndex so synthetic offers share the survey's progress slot. */
+    surveyOffer?: boolean;
+    placeholder?: string;
+    required?: boolean;
+    minLength?: number;
+    losses?: string[];
+    lossesLabel?: string;
+    savedTitle?: string;
+    savedDescription?: string;
+    cancelledTitle?: string;
+    cancelledDescription?: string;
+    data?: Record<string, unknown>;
+    classNames?: unknown;
+}
+
+export type { SuccessStep as $, AcceptedOffer as A, BackButtonProps as B, CancelFlowProps as C, DirectAddress as D, FlowState as E, FeedbackStepProps as F, Mode as G, OfferClassNames as H, OfferConfig as I, OfferCopy as J, OfferDecision as K, OfferStep as L, ModalProps as M, PlanChangeOffer as N, OfferStepProps as O, PauseOffer as P, PlanOption as Q, ReasonButtonProps as R, SuccessStepProps as S, ReasonConfig as T, RebateOffer as U, RedirectOffer as V, ResolvedStep as W, Step as X, StructuralClassNames as Y, SubscriptionStatus as Z, SuccessClassNames as _, ConfirmStepProps as a, SurveyClassNames as a0, SurveyStep as a1, TrialExtensionOffer as a2, SurveyStepProps as b, CloseButtonProps as c, Appearance as d, AppearanceVariables as e, BuiltInOfferConfig as f, BuiltInStep as g, BuiltInStepType as h, ComponentOverrides as i, ConfirmClassNames as j, ConfirmStep as k, ContactOffer as l, CustomComponents as m, CustomOfferConfig as n, CustomOfferProps as o, CustomStepConfig as p, CustomStepProps as q, DirectCoupon as r, DirectCustomer as s, DirectPrice as t, DirectSubscription as u, DirectSubscriptionItem as v, DiscountOffer as w, FeedbackClassNames as x, FeedbackStep as y, FlowConfig as z };

package/dist/styles.css.d.ts

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@churnkey/react",
-  "version": "0.6.0",
+  "version": "0.6.2",
   "description": "Production-ready cancel flow for React. Drop-in component, headless hook, or full customization. Works standalone or with Churnkey for AI-powered retention.",
   "license": "MIT",
   "repository": {