@nozle-js/react 0.8.0 → 0.10.0

package/dist/index.d.ts

@@ -1,8 +1,75 @@
 import * as React from 'react';
-import React__default, { ReactNode } from 'react';
+import React__default, { ReactNode, CSSProperties } from 'react';
 
-interface CompletedCheckoutResult {
-    type: 'completed';
+/** A short-lived customer-portal credential issued by the merchant's backend. */
+interface BillingPortalSession {
+    token: string;
+    /** Nozle Core base URL, without /graphql. Defaults to https://api.nozle.app/core. */
+    apiUrl?: string;
+}
+type CreateBillingPortalSession = (options: {
+    signal: AbortSignal;
+}) => Promise<BillingPortalSession>;
+declare class BillingPortalError extends Error {
+    readonly code: "session" | "unauthorized" | "request" | "changed";
+    constructor(code: "session" | "unauthorized" | "request" | "changed");
+}
+
+type CancellationOperation = "cancel" | "uncancel";
+interface CancellationSubscription {
+    /** Core UUID, distinct from the external subscription identifier. */
+    id: string;
+    externalId: string;
+    name: string;
+    status: string;
+    endingAt: string | null;
+    pendingPlanName?: string | null;
+}
+interface CancellationPreview {
+    operation: CancellationOperation;
+    effectiveAt: string;
+    renewalAt: string | null;
+}
+interface CancellationInput {
+    /** External subscription identifier. The merchant authenticates the customer separately. */
+    subscriptionId: string;
+    operation: CancellationOperation;
+    signal: AbortSignal;
+}
+interface CancellationApplyInput extends CancellationInput {
+    idempotencyKey: string;
+    /** Required for cancellation; the server must reject a changed access-end date. */
+    expectedEffectiveAt?: string;
+}
+interface CancellationActions {
+    preview: (input: CancellationInput) => Promise<CancellationPreview>;
+    apply: (input: CancellationApplyInput) => Promise<unknown>;
+}
+interface CancellationControlProps {
+    subscription: CancellationSubscription;
+    actions: CancellationActions;
+    /** Read persisted state after every attempt, including an ambiguous network failure. */
+    refresh: (signal: AbortSignal) => Promise<CancellationSubscription | null>;
+    onChanged?: () => void;
+    onError?: (error: BillingPortalError) => void;
+    locale?: string;
+    timezone?: string;
+    nonce?: string;
+}
+/** Customer cancellation UI. All mutations go through the merchant's authenticated callbacks. */
+declare function CancellationControl(props: CancellationControlProps): React.JSX.Element;
+
+interface CheckoutSubscriptionResult {
+    external_entity_id?: string;
+    external_subscription_id?: string;
+    checkout_id?: string;
+    effective_at?: string;
+    renewal_at?: string | null;
+    amount_due_cents?: number | string;
+    currency?: string;
+}
+interface CompletedCheckoutResult extends CheckoutSubscriptionResult {
+    type: "completed";
     status: string;
     payment_source?: string;
     subscription_id?: string;
@@ -11,26 +78,80 @@ interface CompletedCheckoutResult {
     amount_cents?: number;
     currency?: string;
 }
-interface ScheduledCheckoutResult {
-    type: 'scheduled';
+interface ScheduledCheckoutResult extends CheckoutSubscriptionResult {
+    type: "scheduled";
     status: string;
     subscription_id?: string;
     plan_code?: string;
+    effective_at?: string;
+    pending_subscription_id?: string;
+}
+interface RazorpayCheckoutResult {
+    type: "razorpay";
+    checkout_id: string;
+    key_id: string;
+    order_id: string;
+    amount_cents: number;
+    currency: string;
+    expires_at?: string;
+    invoice_id?: string;
+    customer_id?: string;
+    recurring?: boolean;
+    mandate_max_amount_cents?: number;
+}
+interface ProcessingCheckoutResult {
+    type: "processing";
+    checkout_id: string;
+    status: string;
+}
+interface HostedCheckoutResult {
+    type: "hosted";
+    payment_url: string;
+    checkout_id?: string;
+}
+interface RazorpayVerification {
+    razorpay_order_id: string;
+    razorpay_payment_id: string;
+    razorpay_signature: string;
+}
+interface CheckoutStatus {
+    checkout_id: string;
+    provider: "razorpay" | "stripe";
+    status: "processing" | "awaiting_payment" | "succeeded" | "failed" | "expired" | "needs_review";
+    fulfillment_status: "pending" | "processing" | "succeeded";
+    amount_cents?: number;
+    currency?: string;
+    invoice_id?: string | null;
+    checkout?: CheckoutResult;
 }
+/** Call your authenticated merchant backend, which calls Nozle using its secret key. */
+type VerifyCheckout = (checkoutId: string, verification: RazorpayVerification) => Promise<CheckoutStatus>;
+type GetCheckoutStatus = (checkoutId: string) => Promise<CheckoutStatus>;
 type CheckoutResult = {
-    type: 'stripe';
+    type: "stripe";
     url?: string;
     clientSecret?: string;
     client_secret?: string;
-} | {
-    type: 'razorpay';
-    orderId: string;
-} | CompletedCheckoutResult | ScheduledCheckoutResult | {
+    publishable_key?: string;
+    stripe_account?: string;
+    checkout_id?: string;
+    invoice_id?: string;
+    amount_cents?: number;
+    currency?: string;
+    external_entity_id?: string;
+    external_subscription_id?: string;
+} | RazorpayCheckoutResult | ProcessingCheckoutResult | HostedCheckoutResult | CompletedCheckoutResult | ScheduledCheckoutResult | {
     url: string;
 };
 interface CreateCheckoutInput {
     planCode: string;
     returnUrl: string;
+    idempotencyKey?: string;
+    registerMandate?: boolean;
+    /** Select the customer's external subscription for a plan change. */
+    subscriptionId?: string;
+    /** Opaque, server-issued confirmation for the displayed quote. */
+    quoteId?: string;
 }
 type CreateCheckout = (input: CreateCheckoutInput) => Promise<CheckoutResult>;
 interface NozleClient {
@@ -41,19 +162,125 @@ interface NozleClient {
 interface BillingContextValue {
     client: NozleClient;
     createCheckout?: CreateCheckout;
+    verifyCheckout?: VerifyCheckout;
+    getCheckoutStatus?: GetCheckoutStatus;
 }
 declare const BillingContext: React__default.Context<BillingContextValue | null>;
 interface BillingProviderProps {
     publishableKey: string;
     createCheckout?: CreateCheckout;
+    verifyCheckout?: VerifyCheckout;
+    getCheckoutStatus?: GetCheckoutStatus;
     baseUrl?: string;
     children: ReactNode;
 }
-declare function BillingProvider({ publishableKey, createCheckout, baseUrl, children, }: BillingProviderProps): React__default.ReactElement;
+declare function BillingProvider({ publishableKey, createCheckout, verifyCheckout, getCheckoutStatus, baseUrl, children, }: BillingProviderProps): React__default.ReactElement;
 declare function useOptionalBillingContext(): BillingContextValue | null;
 declare function useBillingContext(): BillingContextValue;
 declare function useNozleClient(): NozleClient;
 
+interface PortalPlan {
+    code: string;
+    name: string;
+    amountCents: string | number;
+    currency: string;
+    interval: string;
+}
+type PlanChangeOperation = "upgrade" | "downgrade";
+interface PlanChangeState {
+    subscriptionId: string;
+    status: string;
+    currentPlan: PortalPlan;
+    endingAt: string | null;
+    pendingChange: {
+        id: string;
+        plan: PortalPlan;
+        effectiveAt: string;
+    } | null;
+    eligiblePlans: Array<PortalPlan & {
+        operation: PlanChangeOperation;
+    }>;
+    blockedReason: string | null;
+    checkout: CheckoutResult | null;
+    checkoutStatus: "none" | "awaiting_payment" | "processing" | "succeeded" | "failed" | "expired" | "needs_review";
+}
+interface PlanChangePreview {
+    operation: PlanChangeOperation;
+    timing: "immediate" | "end_of_period";
+    currency: string;
+    creditAmountCents: string | number;
+    debitAmountCents: string | number;
+    netAmountCents: string | number;
+    amountDueNowCents: string | number;
+    amountDueAtEffectiveCents: string | number;
+    effectiveAt: string;
+    renewalAt: string | null;
+    quoteToken: string;
+}
+interface PlanChangeInput {
+    subscriptionId: string;
+    signal: AbortSignal;
+}
+interface PlanChangePreviewInput extends PlanChangeInput {
+    targetPlanCode: string;
+}
+interface PlanChangeApplyInput extends PlanChangePreviewInput {
+    quoteToken: string;
+    idempotencyKey: string;
+    returnUrl: string;
+}
+interface PlanChangeWithdrawInput extends PlanChangeInput {
+    pendingChangeId: string;
+    idempotencyKey: string;
+}
+interface PlanChangeActions {
+    load: (input: PlanChangeInput) => Promise<PlanChangeState>;
+    status: (input: PlanChangeInput) => Promise<PlanChangeState>;
+    preview: (input: PlanChangePreviewInput) => Promise<PlanChangePreview>;
+    apply: (input: PlanChangeApplyInput) => Promise<CheckoutResult>;
+    withdraw: (input: PlanChangeWithdrawInput) => Promise<unknown>;
+    /** Merchant callbacks scoped to this selected subscription. */
+    verifyCheckout?: (input: PlanChangeInput & {
+        checkoutId: string;
+        verification: RazorpayVerification;
+    }) => Promise<CheckoutStatus>;
+    getCheckoutStatus?: (input: PlanChangeInput & {
+        checkoutId: string;
+    }) => Promise<CheckoutStatus>;
+}
+interface PlanChangeControlProps {
+    subscriptionId: string;
+    /** Change when another control updates this subscription; in-flight request keys are preserved. */
+    refreshKey?: string;
+    actions: PlanChangeActions;
+    onChanged?: () => void;
+    onError?: (error: BillingPortalError) => void;
+    returnUrl?: string;
+    locale?: string;
+    timezone?: string;
+    nonce?: string;
+}
+/** Payment-backed upgrades and scheduled downgrades for one external subscription. */
+declare function PlanChangeControl(props: PlanChangeControlProps): React.JSX.Element;
+
+interface BillingPortalProps {
+    /** Stable callback to an authenticated merchant endpoint. Never accept customer identity from browser input. */
+    createSession: CreateBillingPortalSession;
+    /** Optional authenticated merchant callbacks enabling cancel/keep controls. */
+    cancellationActions?: CancellationActions;
+    /** Optional authenticated merchant callbacks for upgrades and scheduled downgrades. */
+    planChangeActions?: PlanChangeActions;
+    /** Formats amounts and dates. Interface copy is currently English. */
+    locale?: string;
+    className?: string;
+    style?: CSSProperties;
+    /** CSP nonce for the component's scoped stylesheet. No Tailwind setup is required. */
+    nonce?: string;
+    onError?: (error: BillingPortalError) => void;
+}
+/** Native React customer portal. Uses customer-scoped GraphQL, with no iframe or global auth storage. */
+declare function BillingPortal({ createSession, cancellationActions, planChangeActions, locale, className, style, nonce, onError, }: BillingPortalProps): React.JSX.Element;
+
 interface Plan$1 {
     code: string;
     name: string;
@@ -156,39 +383,55 @@ interface PlanComparisonProps {
  */
 declare function PlanComparison({ plans, features, }: PlanComparisonProps): React__default.ReactElement;
 
-interface CheckoutButtonProps {
+interface RazorpayActions {
+    verifyCheckout?: VerifyCheckout;
+    getCheckoutStatus?: GetCheckoutStatus;
+    onSuccess?: (paymentId: string) => void;
+    onProcessing?: (status: CheckoutStatus) => void;
+    onDismiss?: () => void;
+    onError?: (error: Error) => void;
+}
+interface RazorpayOptions {
+    key: string;
+    order_id: string;
+    amount: number;
+    currency: string;
+    customer_id?: string;
+    recurring?: '1';
+    handler: (response: RazorpayVerification) => void;
+    modal: {
+        ondismiss: () => void;
+    };
+}
+interface RazorpayInstance {
+    open(): void;
+    close(): void;
+    on(event: string, callback: () => void): void;
+}
+declare global {
+    interface Window {
+        Razorpay?: new (options: RazorpayOptions) => RazorpayInstance;
+    }
+}
+
+interface CheckoutButtonProps extends Omit<RazorpayActions, "verifyCheckout" | "getCheckoutStatus"> {
     planCode: string;
     returnUrl?: string;
     label?: string;
     className?: string;
     style?: React__default.CSSProperties;
     onError?: (error: Error) => void;
+    /** @deprecated The server supplies the public Razorpay key in the checkout response. */
     razorpayKeyId?: string;
+    registerMandate?: boolean;
     onStripeClientSecret?: (clientSecret: string) => void;
     onSuccess?: (paymentId: string) => void;
     onComplete?: (result: CompletedCheckoutResult) => void;
     onScheduled?: (result: ScheduledCheckoutResult) => void;
 }
-interface RazorpayOptions {
-    key: string;
-    order_id: string;
-    handler: (response: {
-        razorpay_payment_id: string;
-    }) => void;
-    modal?: {
-        ondismiss?: () => void;
-    };
-}
-declare global {
-    interface Window {
-        Razorpay: new (options: RazorpayOptions) => {
-            open(): void;
-        };
-    }
-}
-declare function CheckoutButton({ planCode, returnUrl, label, className, style, onError, razorpayKeyId, onStripeClientSecret, onSuccess, onComplete, onScheduled, }: CheckoutButtonProps): React__default.ReactElement;
+declare function CheckoutButton({ planCode, returnUrl, label, className, style, onError, razorpayKeyId, registerMandate, onProcessing, onDismiss, onStripeClientSecret, onSuccess, onComplete, onScheduled, }: CheckoutButtonProps): React__default.ReactElement;
 
-interface CheckoutProps {
+interface StripeCheckoutProps {
     /** Stripe PaymentIntent client secret */
     clientSecret: string;
     /** Stripe publishable key */
@@ -223,19 +466,47 @@ interface UseCheckoutResult {
     error: Error | null;
 }
 declare function useCheckout(): UseCheckoutResult;
-declare function Checkout({ clientSecret, publishableKey, stripeAccount, returnUrl, submitLabel, onSuccess, onComplete, onError, onReady, className, style, children, }: CheckoutProps): React__default.JSX.Element;
+interface ProviderCheckoutProps {
+    checkout: CheckoutResult;
+    submitLabel?: string;
+    onSuccess?: (paymentId: string) => void;
+    onComplete?: () => void;
+    onProcessing?: (status: CheckoutStatus) => void;
+    onError?: (error: Error) => void;
+    className?: string;
+    returnUrl?: string;
+    verifyCheckout?: VerifyCheckout;
+    getCheckoutStatus?: GetCheckoutStatus;
+    onDismiss?: () => void;
+}
+type CheckoutProps = StripeCheckoutProps | ProviderCheckoutProps;
+declare function Checkout(props: CheckoutProps): React__default.JSX.Element;
 
 interface ProrationPreview {
     credit: number;
     debit: number;
     net: number;
     nextBillingDate: string;
+    /** Currency of legacy major-unit preview amounts. Defaults to USD for existing integrations. */
+    currency?: string;
 }
 interface UpgradeModalProps {
     isOpen: boolean;
     planCode: string;
     returnUrl?: string;
+    subscriptionId?: string;
+    quoteId?: string;
+    idempotencyKey?: string;
     preview?: ProrationPreview;
+    locale?: string;
+    title?: string;
+    confirmLabel?: string;
+    confirmDisabled?: boolean;
+    busy?: boolean;
+    nonce?: string;
+    children?: React__default.ReactNode;
+    /** Authenticated merchant action. Allows the same confirmation UI without BillingProvider. */
+    onSubmit?: () => Promise<void>;
     onStripeClientSecret?: (clientSecret: string) => void;
     onCheckoutStarted?: () => void;
     onCompleted?: () => void;
@@ -244,11 +515,14 @@ interface UpgradeModalProps {
     onCancel?: () => void;
     onError?: (error: Error) => void;
 }
-declare function UpgradeModal({ isOpen, planCode, returnUrl, preview, onStripeClientSecret, onCheckoutStarted, onCompleted, onScheduled, onConfirm, onCancel, onError, }: UpgradeModalProps): React__default.ReactElement | null;
+declare function UpgradeModal(props: UpgradeModalProps): React__default.ReactElement | null;
 
 interface UpgradeButtonProps {
     planCode: string;
     returnUrl?: string;
+    subscriptionId?: string;
+    quoteId?: string;
+    idempotencyKey?: string;
     preview?: ProrationPreview;
     label?: string;
     className?: string;
@@ -259,7 +533,7 @@ interface UpgradeButtonProps {
     onUpgraded?: () => void;
     onError?: (error: Error) => void;
 }
-declare function UpgradeButton({ planCode, returnUrl, preview, label, className, style, onStripeClientSecret, onCheckoutStarted, onDowngradeScheduled, onUpgraded, onError, }: UpgradeButtonProps): React__default.ReactElement;
+declare function UpgradeButton({ planCode, returnUrl, subscriptionId, quoteId, idempotencyKey, preview, label, className, style, onStripeClientSecret, onCheckoutStarted, onDowngradeScheduled, onUpgraded, onError, }: UpgradeButtonProps): React__default.ReactElement;
 
 /**
  * Presentational entitlement gate. The merchant backend owns entitlement
@@ -457,4 +731,4 @@ interface PaymentMethodDisplayProps {
 }
 declare function PaymentMethodDisplay({ paymentMethod, onUpdatePaymentMethod, updateHref, }: PaymentMethodDisplayProps): React.JSX.Element;
 
-export { BillingContext, type BillingContextValue, BillingProvider, type BillingProviderProps, type Plan$1 as CatalogPlan, Checkout, CheckoutButton, type CheckoutButtonProps, type CheckoutProps, type CheckoutResult, type ComparisonFeature, type CompletedCheckoutResult, type CreateCheckout, type CreateCheckoutInput, FeatureGate, type FeatureGateProps, LockedOverlay, type LockedOverlayProps, type NozleClient, type PaymentMethod, PaymentMethodDisplay, type PaymentMethodDisplayProps, type Plan, PlanBadge, type PlanBadgeProps, PlanCard, type PlanCardProps, PlanComparison, type PlanComparisonProps, PlanGate, type PlanGateProps, type PricingPlan, PricingTable, type PricingTableProps, type ProrationPreview, type ScheduledCheckoutResult, UpgradeButton, type UpgradeButtonProps, UpgradeModal, type UpgradeModalProps, UpgradePrompt, type UpgradePromptProps, UsageAlert, type UsageAlertFeature, type UsageAlertProps, UsageDashboard, type UsageDashboardFeature, type UsageDashboardProps, UsageGate, type UsageGateProps, UsageMeter, type UsageMeterProps, type UseCheckoutResult, type UseCheckoutResult$1 as UseCheckoutSessionResult, getUsageMeterColor, useBillingContext, useCheckout, useCheckout$1 as useCheckoutSession, useNozleClient, useOptionalBillingContext, usePlans };
+export { BillingContext, type BillingContextValue, BillingPortal, BillingPortalError, type BillingPortalProps, type BillingPortalSession, BillingProvider, type BillingProviderProps, type CancellationActions, type CancellationApplyInput, CancellationControl, type CancellationControlProps, type CancellationInput, type CancellationOperation, type CancellationPreview, type CancellationSubscription, type Plan$1 as CatalogPlan, Checkout, CheckoutButton, type CheckoutButtonProps, type CheckoutProps, type CheckoutResult, type CheckoutStatus, type CheckoutSubscriptionResult, type ComparisonFeature, type CompletedCheckoutResult, type CreateBillingPortalSession, type CreateCheckout, type CreateCheckoutInput, FeatureGate, type FeatureGateProps, type GetCheckoutStatus, type HostedCheckoutResult, LockedOverlay, type LockedOverlayProps, type NozleClient, type PaymentMethod, PaymentMethodDisplay, type PaymentMethodDisplayProps, type Plan, PlanBadge, type PlanBadgeProps, PlanCard, type PlanCardProps, type PlanChangeActions, type PlanChangeApplyInput, PlanChangeControl, type PlanChangeControlProps, type PlanChangeInput, type PlanChangeOperation, type PlanChangePreview, type PlanChangePreviewInput, type PlanChangeState, type PlanChangeWithdrawInput, PlanComparison, type PlanComparisonProps, PlanGate, type PlanGateProps, type PortalPlan, type PricingPlan, PricingTable, type PricingTableProps, type ProcessingCheckoutResult, type ProrationPreview, type RazorpayCheckoutResult, type RazorpayVerification, type ScheduledCheckoutResult, UpgradeButton, type UpgradeButtonProps, UpgradeModal, type UpgradeModalProps, UpgradePrompt, type UpgradePromptProps, UsageAlert, type UsageAlertFeature, type UsageAlertProps, UsageDashboard, type UsageDashboardFeature, type UsageDashboardProps, UsageGate, type UsageGateProps, UsageMeter, type UsageMeterProps, type UseCheckoutResult, type UseCheckoutResult$1 as UseCheckoutSessionResult, type VerifyCheckout, getUsageMeterColor, useBillingContext, useCheckout, useCheckout$1 as useCheckoutSession, useNozleClient, useOptionalBillingContext, usePlans };