autumn-js/dist/better-auth/types.d.ts

Autumn JS Library

type ClosedEnum<T extends Readonly<Record<string, string | number>>> = T[keyof T];

declare const CustomerExpand: {
    readonly Invoices: "invoices";
    readonly TrialsUsed: "trials_used";
    readonly Rewards: "rewards";
    readonly Entities: "entities";
    readonly Referrals: "referrals";
    readonly PaymentMethod: "payment_method";
    readonly SubscriptionsPlan: "subscriptions.plan";
    readonly PurchasesPlan: "purchases.plan";
    readonly BalancesFeature: "balances.feature";
    readonly FlagsFeature: "flags.feature";
    readonly BillingControlsAutoTopupsPurchaseLimit: "billing_controls.auto_topups.purchase_limit";
};
type CustomerExpand = ClosedEnum<typeof CustomerExpand>;

/**
 * The time interval for the purchase limit window.
 */
declare const GetOrCreateCustomerPurchaseLimitInterval: {
    readonly Hour: "hour";
    readonly Day: "day";
    readonly Week: "week";
    readonly Month: "month";
};
/**
 * The time interval for the purchase limit window.
 */
type GetOrCreateCustomerPurchaseLimitInterval = ClosedEnum<typeof GetOrCreateCustomerPurchaseLimitInterval>;
/**
 * Optional rate limit to cap how often auto top-ups occur.
 */
type GetOrCreateCustomerPurchaseLimit = {
    /**
     * The time interval for the purchase limit window.
     */
    interval: GetOrCreateCustomerPurchaseLimitInterval;
    /**
     * Number of intervals in the purchase limit window.
     */
    intervalCount?: number | undefined;
    /**
     * Maximum number of auto top-ups allowed within the interval.
     */
    limit: number;
};
type GetOrCreateCustomerAutoTopup = {
    /**
     * The ID of the feature (credit balance) to auto top-up.
     */
    featureId: string;
    /**
     * Whether auto top-up is enabled.
     */
    enabled?: boolean | undefined;
    /**
     * When the balance drops below this threshold, an auto top-up will be purchased.
     */
    threshold: number;
    /**
     * Amount of credits to add per auto top-up.
     */
    quantity: number;
    /**
     * Optional rate limit to cap how often auto top-ups occur.
     */
    purchaseLimit?: GetOrCreateCustomerPurchaseLimit | undefined;
    /**
     * When true, auto top-up creates a send_invoice invoice instead of auto-charging.
     */
    invoiceMode?: boolean | undefined;
};
/**
 * How overage_limit is interpreted: an absolute overage cap (default) or a percentage of the main-plan allowance.
 */
declare const GetOrCreateCustomerLimitType: {
    readonly Absolute: "absolute";
    readonly UsagePercentage: "usage_percentage";
};
/**
 * How overage_limit is interpreted: an absolute overage cap (default) or a percentage of the main-plan allowance.
 */
type GetOrCreateCustomerLimitType = ClosedEnum<typeof GetOrCreateCustomerLimitType>;
type GetOrCreateCustomerSpendLimit = {
    /**
     * Optional feature ID this spend limit applies to.
     */
    featureId?: string | undefined;
    /**
     * Whether the overage spend limit is enabled.
     */
    enabled?: boolean | undefined;
    /**
     * How overage_limit is interpreted: an absolute overage cap (default) or a percentage of the main-plan allowance.
     */
    limitType?: GetOrCreateCustomerLimitType | undefined;
    /**
     * Overage cap for the feature: absolute units, or a percent (e.g. 120) when limit_type is usage_percentage.
     */
    overageLimit?: number | undefined;
    /**
     * When true, overage for this feature is not posted to Stripe. Usage tracking and balance resets still behave normally.
     */
    skipOverageBilling?: boolean | undefined;
};
/**
 * Interval for the cap, aligned to the customer's billing cycle.
 */
declare const GetOrCreateCustomerUsageLimitInterval: {
    readonly Day: "day";
    readonly Week: "week";
    readonly Month: "month";
    readonly Year: "year";
};
/**
 * Interval for the cap, aligned to the customer's billing cycle.
 */
type GetOrCreateCustomerUsageLimitInterval = ClosedEnum<typeof GetOrCreateCustomerUsageLimitInterval>;
/**
 * When set, only usage from events whose properties match counts toward this cap. Omit to count all usage of the feature.
 */
type GetOrCreateCustomerFilter = {
    properties: {
        [k: string]: string | number | boolean;
    };
};
type GetOrCreateCustomerUsageLimit = {
    /**
     * The feature this usage limit applies to.
     */
    featureId: string;
    /**
     * Whether this usage limit is enabled.
     */
    enabled?: boolean | undefined;
    /**
     * Maximum units allowed per interval.
     */
    limit: number;
    /**
     * Interval for the cap, aligned to the customer's billing cycle.
     */
    interval: GetOrCreateCustomerUsageLimitInterval;
    /**
     * When set, only usage from events whose properties match counts toward this cap. Omit to count all usage of the feature.
     */
    filter?: GetOrCreateCustomerFilter | undefined;
};
/**
 * Whether the threshold is an absolute count or a percentage of the usage allowance or remaining balance.
 */
declare const GetOrCreateCustomerThresholdType: {
    readonly Usage: "usage";
    readonly UsagePercentage: "usage_percentage";
    readonly Remaining: "remaining";
    readonly RemainingPercentage: "remaining_percentage";
};
/**
 * Whether the threshold is an absolute count or a percentage of the usage allowance or remaining balance.
 */
type GetOrCreateCustomerThresholdType = ClosedEnum<typeof GetOrCreateCustomerThresholdType>;
type GetOrCreateCustomerUsageAlert = {
    /**
     * The feature ID this alert applies to.
     */
    featureId?: string | undefined;
    /**
     * Whether this usage alert is enabled.
     */
    enabled?: boolean | undefined;
    /**
     * The threshold value that triggers the alert. For usage or remaining, this is an absolute count. For usage_percentage or remaining_percentage, this is a percentage (0-100).
     */
    threshold: number;
    /**
     * Whether the threshold is an absolute count or a percentage of the usage allowance or remaining balance.
     */
    thresholdType: GetOrCreateCustomerThresholdType;
    /**
     * Optional user-defined label to distinguish multiple alerts on the same feature.
     */
    name?: string | undefined;
};
type GetOrCreateCustomerOverageAllowed = {
    /**
     * The feature ID this overage allowed control applies to.
     */
    featureId: string;
    /**
     * Whether overage is allowed for this feature.
     */
    enabled?: boolean | undefined;
};
/**
 * Billing controls for the customer (auto top-ups, etc.)
 */
type GetOrCreateCustomerBillingControls = {
    /**
     * List of auto top-up configurations per feature.
     */
    autoTopups?: Array<GetOrCreateCustomerAutoTopup> | undefined;
    /**
     * List of overage spend limits per feature (caps overage spend).
     */
    spendLimits?: Array<GetOrCreateCustomerSpendLimit> | undefined;
    /**
     * List of hard usage caps per feature (max units per interval).
     */
    usageLimits?: Array<GetOrCreateCustomerUsageLimit> | undefined;
    /**
     * List of usage alert configurations per feature.
     */
    usageAlerts?: Array<GetOrCreateCustomerUsageAlert> | undefined;
    /**
     * List of overage allowed controls per feature. When enabled, usage can exceed balance.
     */
    overageAllowed?: Array<GetOrCreateCustomerOverageAllowed> | undefined;
};
/**
 * Miscellaneous configurations for the customer.
 */
type GetOrCreateCustomerConfig = {
    /**
     * Whether to disable the shared customer-level pool for entities.
     */
    disablePooledBalance?: boolean | undefined;
    /**
     * Stops Autumn from posting usage-overage line items to Stripe for this customer. Check/track and balance resets still behave normally. When set, this overrides the organization-level disable_overage_billing setting.
     */
    disableOverageBilling?: boolean | undefined;
};
type GetOrCreateCustomerParams = {
    customerId: string | null;
    /**
     * Customer's name
     */
    name?: string | null | undefined;
    /**
     * Customer's email address
     */
    email?: string | null | undefined;
    /**
     * Unique identifier (eg, serial number) to detect duplicate customers and prevent free trial abuse
     */
    fingerprint?: string | null | undefined;
    /**
     * Additional metadata for the customer
     */
    metadata?: {
        [k: string]: any;
    } | null | undefined;
    /**
     * Stripe customer ID if you already have one
     */
    stripeId?: string | null | undefined;
    /**
     * Whether to create the customer in Stripe
     */
    createInStripe?: boolean | undefined;
    /**
     * The ID of the free plan to auto-enable for the customer
     */
    autoEnablePlanId?: string | undefined;
    /**
     * Whether to send email receipts to this customer
     */
    sendEmailReceipts?: boolean | undefined;
    /**
     * Billing controls for the customer (auto top-ups, etc.)
     */
    billingControls?: GetOrCreateCustomerBillingControls | undefined;
    /**
     * Miscellaneous configurations for the customer.
     */
    config?: GetOrCreateCustomerConfig | undefined;
    /**
     * Fields to expand in the returned customer response, such as subscriptions.plan, purchases.plan, balances.feature, or flags.feature.
     */
    expand?: Array<CustomerExpand> | undefined;
};

/** Customer ID type derived from SDK */
type CustomerId = NonNullable<GetOrCreateCustomerParams["customerId"]>;
/** Customer data that can be passed to SDK methods */
type CustomerData = Partial<Omit<GetOrCreateCustomerParams, "customerId" | "expand">>;
/** Resolved identity from the identify function */
type ResolvedIdentity = {
    customerId: CustomerId | null | undefined;
    customerData?: CustomerData;
};
/** Result of the identify function (can be sync or async) */
type AuthResult = ResolvedIdentity | null | Promise<ResolvedIdentity | null>;

type CustomerScope = "user" | "organization" | "user_and_organization";
/** Custom identity resolver function */
type IdentifyFn = (context: {
    session: BetterAuthSession | null;
    organization: BetterAuthOrganization | null;
}) => AuthResult;
type AutumnOptions = {
    /** Autumn API secret key (defaults to AUTUMN_SECRET_KEY env var) */
    secretKey?: string;
    /** Base URL for Autumn API */
    baseURL?: string;
    /** Autumn API URL (alias for baseURL) */
    autumnURL?: string;
    /** How to resolve customer identity from session */
    customerScope?: CustomerScope;
    /** Custom identity resolver (overrides customerScope) */
    identify?: IdentifyFn;
};
/** Better Auth session shape (minimal) */
type BetterAuthSession = {
    user: {
        id: string;
        name?: string;
        email?: string;
    };
    session: {
        id: string;
        activeOrganizationId?: string | null;
    };
};
/** Better Auth organization shape (minimal) */
type BetterAuthOrganization = {
    id: string;
    name: string;
    slug?: string;
};

export type { AutumnOptions, BetterAuthOrganization, BetterAuthSession, CustomerScope, IdentifyFn };