autumn-js
Version:
Autumn JS Library
1,529 lines (1,524 loc) • 46.7 kB
text/typescript
declare const __brand: unique symbol;
type Unrecognized<T> = T & {
[__brand]: "unrecognized";
};
type ClosedEnum<T extends Readonly<Record<string, string | number>>> = T[keyof T];
type OpenEnum<T extends Readonly<Record<string, string | number>>> = T[keyof T] | Unrecognized<T[keyof T] extends number ? number : string>;
/**
* Feature type: 'boolean' for on/off access, 'metered' for usage-tracked features, 'credit_system' for unified credit pools, 'ai_credit_system' for model-based token pricing.
*/
declare const BalanceType: {
readonly Boolean: "boolean";
readonly Metered: "metered";
readonly CreditSystem: "credit_system";
readonly AiCreditSystem: "ai_credit_system";
};
/**
* Feature type: 'boolean' for on/off access, 'metered' for usage-tracked features, 'credit_system' for unified credit pools, 'ai_credit_system' for model-based token pricing.
*/
type BalanceType = OpenEnum<typeof BalanceType>;
type BalanceCreditSchema = {
/**
* ID of the metered feature that draws from this credit system.
*/
meteredFeatureId: string;
/**
* Credits consumed per unit of the metered feature.
*/
creditCost: number;
};
type BalanceModelMarkups = {
markup?: number | undefined;
inputCost?: number | undefined;
outputCost?: number | undefined;
};
type BalanceProviderMarkups = {
markup: number;
};
/**
* Display names for the feature in billing UI and customer-facing components.
*/
type BalanceDisplay = {
/**
* Singular form for UI display (e.g., 'API call', 'seat').
*/
singular?: string | null | undefined;
/**
* Plural form for UI display (e.g., 'API calls', 'seats').
*/
plural?: string | null | undefined;
};
/**
* The full feature object if expanded.
*/
type BalanceFeature = {
/**
* The unique identifier for this feature, used in /check and /track calls.
*/
id: string;
/**
* Human-readable name displayed in the dashboard and billing UI.
*/
name: string;
/**
* Feature type: 'boolean' for on/off access, 'metered' for usage-tracked features, 'credit_system' for unified credit pools, 'ai_credit_system' for model-based token pricing.
*/
type: BalanceType;
/**
* For metered features: true if usage resets periodically (API calls, credits), false if allocated persistently (seats, storage).
*/
consumable: boolean;
/**
* Event names that trigger this feature's balance. Allows multiple features to respond to a single event.
*/
eventNames?: Array<string> | undefined;
/**
* For credit_system features: maps metered features to their credit costs.
*/
creditSchema?: Array<BalanceCreditSchema> | undefined;
/**
* Per-model markup overrides for AI credit systems.
*/
modelMarkups?: {
[k: string]: BalanceModelMarkups;
} | null | undefined;
/**
* Default percentage markup for AI credit systems. Use -100 to make usage free.
*/
defaultMarkup?: number | undefined;
/**
* Per-provider default markup percentages for AI credit systems.
*/
providerMarkups?: {
[k: string]: BalanceProviderMarkups;
} | null | undefined;
/**
* Display names for the feature in billing UI and customer-facing components.
*/
display?: BalanceDisplay | undefined;
/**
* Whether the feature is archived and hidden from the dashboard.
*/
archived: boolean;
};
declare const BalanceIntervalEnum: {
readonly OneOff: "one_off";
readonly Minute: "minute";
readonly Hour: "hour";
readonly Day: "day";
readonly Week: "week";
readonly Month: "month";
readonly Quarter: "quarter";
readonly SemiAnnual: "semi_annual";
readonly Year: "year";
};
type BalanceIntervalEnum = OpenEnum<typeof BalanceIntervalEnum>;
type BalanceReset = {
/**
* The reset interval (hour, day, week, month, etc.) or 'multiple' if combined from different intervals.
*/
interval: BalanceIntervalEnum | string;
/**
* Number of intervals between resets (eg. 2 for bi-monthly).
*/
intervalCount?: number | undefined;
/**
* Timestamp when the balance will next reset.
*/
resetsAt: number | null;
};
type BalanceTier = {
to: number | string;
amount: number;
flatAmount?: number | undefined;
};
/**
* How tiers are applied: graduated (split across bands) or volume (flat rate for the matched tier).
*/
declare const BalanceTierBehavior: {
readonly Graduated: "graduated";
readonly Volume: "volume";
};
/**
* How tiers are applied: graduated (split across bands) or volume (flat rate for the matched tier).
*/
type BalanceTierBehavior = OpenEnum<typeof BalanceTierBehavior>;
/**
* Whether usage is prepaid or billed pay-per-use.
*/
declare const BalanceBillingMethod: {
readonly Prepaid: "prepaid";
readonly UsageBased: "usage_based";
};
/**
* Whether usage is prepaid or billed pay-per-use.
*/
type BalanceBillingMethod = OpenEnum<typeof BalanceBillingMethod>;
type BalancePrice = {
/**
* The per-unit price amount.
*/
amount?: number | undefined;
/**
* Tiered pricing configuration if applicable.
*/
tiers?: Array<BalanceTier> | undefined;
/**
* How tiers are applied: graduated (split across bands) or volume (flat rate for the matched tier).
*/
tierBehavior?: BalanceTierBehavior | undefined;
/**
* The number of units per billing increment (eg. $9 / 250 units).
*/
billingUnits: number;
/**
* Whether usage is prepaid or billed pay-per-use.
*/
billingMethod: BalanceBillingMethod;
/**
* Maximum quantity that can be purchased, or null for unlimited.
*/
maxPurchase: number | null;
};
type Breakdown = {
/**
* The unique identifier for this balance breakdown.
*/
id: string;
/**
* The plan ID this balance originates from, or null for standalone balances.
*/
planId: string | null;
/**
* Amount granted from the plan's included usage.
*/
includedGrant: number;
/**
* Amount granted from prepaid purchases or top-ups.
*/
prepaidGrant: number;
/**
* Remaining balance available for use.
*/
remaining: number;
/**
* Amount consumed in the current period.
*/
usage: number;
/**
* Whether this balance has unlimited usage.
*/
unlimited: boolean;
/**
* Reset configuration for this balance, or null if no reset.
*/
reset: BalanceReset | null;
/**
* Pricing configuration if this balance has usage-based pricing.
*/
price: BalancePrice | null;
/**
* Timestamp when this balance expires, or null for no expiration.
*/
expiresAt: number | null;
};
type BalanceRollover = {
/**
* Amount of balance rolled over from a previous period.
*/
balance: number;
/**
* Timestamp when the rollover balance expires.
*/
expiresAt: number;
};
type Balance = {
/**
* The feature ID this balance is for.
*/
featureId: string;
/**
* The full feature object if expanded.
*/
feature?: BalanceFeature | undefined;
/**
* Total balance granted (included + prepaid).
*/
granted: number;
/**
* Remaining balance available for use.
*/
remaining: number;
/**
* Total usage consumed in the current period.
*/
usage: number;
/**
* Whether this feature has unlimited usage.
*/
unlimited: boolean;
/**
* Whether usage beyond the granted balance is allowed (with overage charges).
*/
overageAllowed: boolean;
/**
* Maximum quantity that can be purchased as a top-up, or null for unlimited.
*/
maxPurchase: number | null;
/**
* Timestamp when the balance will reset, or null for no reset.
*/
nextResetAt: number | null;
/**
* Detailed breakdown of balance sources when stacking multiple plans or grants.
*/
breakdown?: Array<Breakdown> | undefined;
/**
* Rollover balances carried over from previous periods.
*/
rollovers?: Array<BalanceRollover> | undefined;
};
/**
* Billing interval (e.g. 'month', 'year').
*/
declare const PlanPriceInterval: {
readonly OneOff: "one_off";
readonly Week: "week";
readonly Month: "month";
readonly Quarter: "quarter";
readonly SemiAnnual: "semi_annual";
readonly Year: "year";
};
/**
* Billing interval (e.g. 'month', 'year').
*/
type PlanPriceInterval = OpenEnum<typeof PlanPriceInterval>;
/**
* Display text for showing this price in pricing pages.
*/
type PlanPriceDisplay = {
/**
* Main display text (e.g. '$10' or '100 messages').
*/
primaryText: string;
/**
* Secondary display text (e.g. 'per month' or 'then $0.5 per 100').
*/
secondaryText?: string | undefined;
};
type PlanPrice = {
/**
* Base price amount for the plan.
*/
amount: number;
/**
* Billing interval (e.g. 'month', 'year').
*/
interval: PlanPriceInterval;
/**
* Number of intervals per billing cycle. Defaults to 1.
*/
intervalCount?: number | undefined;
/**
* Display text for showing this price in pricing pages.
*/
display?: PlanPriceDisplay | undefined;
};
/**
* The type of the feature
*/
declare const PlanType: {
readonly Static: "static";
readonly Boolean: "boolean";
readonly SingleUse: "single_use";
readonly ContinuousUse: "continuous_use";
readonly CreditSystem: "credit_system";
readonly AiCreditSystem: "ai_credit_system";
};
/**
* The type of the feature
*/
type PlanType = OpenEnum<typeof PlanType>;
type PlanFeatureDisplay = {
/**
* The singular display name for the feature.
*/
singular: string;
/**
* The plural display name for the feature.
*/
plural: string;
};
type PlanCreditSchema = {
/**
* The ID of the metered feature (should be a single_use feature).
*/
meteredFeatureId: string;
/**
* The credit cost of the metered feature.
*/
creditCost: number;
};
/**
* The full feature object if expanded.
*/
type PlanFeature = {
/**
* The ID of the feature, used to refer to it in other API calls like /track or /check.
*/
id: string;
/**
* The name of the feature.
*/
name?: string | null | undefined;
/**
* The type of the feature
*/
type: PlanType;
/**
* Singular and plural display names for the feature.
*/
display?: PlanFeatureDisplay | null | undefined;
/**
* Credit cost schema for credit system features.
*/
creditSchema?: Array<PlanCreditSchema> | null | undefined;
/**
* Whether or not the feature is archived.
*/
archived?: boolean | null | undefined;
};
/**
* The interval at which the feature balance resets (e.g. 'month', 'year'). For consumable features, usage resets to 0 and included units are restored.
*/
declare const PlanResetItemInterval: {
readonly OneOff: "one_off";
readonly Minute: "minute";
readonly Hour: "hour";
readonly Day: "day";
readonly Week: "week";
readonly Month: "month";
readonly Quarter: "quarter";
readonly SemiAnnual: "semi_annual";
readonly Year: "year";
};
/**
* The interval at which the feature balance resets (e.g. 'month', 'year'). For consumable features, usage resets to 0 and included units are restored.
*/
type PlanResetItemInterval = OpenEnum<typeof PlanResetItemInterval>;
type PlanItemReset = {
/**
* The interval at which the feature balance resets (e.g. 'month', 'year'). For consumable features, usage resets to 0 and included units are restored.
*/
interval: PlanResetItemInterval;
/**
* Number of intervals between resets. Defaults to 1.
*/
intervalCount?: number | undefined;
};
type PlanItemTier = {
to: number | string;
amount: number;
flatAmount?: number | undefined;
};
declare const PlanItemTierBehavior: {
readonly Graduated: "graduated";
readonly Volume: "volume";
};
type PlanItemTierBehavior = OpenEnum<typeof PlanItemTierBehavior>;
/**
* Billing interval for this price. For consumable features, should match reset.interval.
*/
declare const PlanPriceItemInterval: {
readonly OneOff: "one_off";
readonly Week: "week";
readonly Month: "month";
readonly Quarter: "quarter";
readonly SemiAnnual: "semi_annual";
readonly Year: "year";
};
/**
* Billing interval for this price. For consumable features, should match reset.interval.
*/
type PlanPriceItemInterval = OpenEnum<typeof PlanPriceItemInterval>;
/**
* 'prepaid' for features like seats where customers pay upfront, 'usage_based' for pay-as-you-go after included usage.
*/
declare const PlanItemBillingMethod: {
readonly Prepaid: "prepaid";
readonly UsageBased: "usage_based";
};
/**
* 'prepaid' for features like seats where customers pay upfront, 'usage_based' for pay-as-you-go after included usage.
*/
type PlanItemBillingMethod = OpenEnum<typeof PlanItemBillingMethod>;
type PlanItemPrice = {
/**
* Price per billing_units after included usage is consumed. Mutually exclusive with tiers.
*/
amount?: number | undefined;
/**
* Tiered pricing configuration. Each tier's 'to' INCLUDES the included amount. Either 'tiers' or 'amount' is required.
*/
tiers?: Array<PlanItemTier> | undefined;
tierBehavior?: PlanItemTierBehavior | undefined;
/**
* Billing interval for this price. For consumable features, should match reset.interval.
*/
interval: PlanPriceItemInterval;
/**
* Number of intervals per billing cycle. Defaults to 1.
*/
intervalCount?: number | undefined;
/**
* Number of units per price increment. Usage is rounded UP to the nearest billing_units when billed (e.g. billing_units=100 means 101 usage rounds to 200).
*/
billingUnits: number;
/**
* 'prepaid' for features like seats where customers pay upfront, 'usage_based' for pay-as-you-go after included usage.
*/
billingMethod: PlanItemBillingMethod;
/**
* Maximum units a customer can purchase beyond included. E.g. if included=100 and max_purchase=300, customer can use up to 400 total before usage is capped. Null for no limit.
*/
maxPurchase: number | null;
};
/**
* Display text for showing this item in pricing pages.
*/
type PlanItemDisplay = {
/**
* Main display text (e.g. '$10' or '100 messages').
*/
primaryText: string;
/**
* Secondary display text (e.g. 'per month' or 'then $0.5 per 100').
*/
secondaryText?: string | undefined;
};
/**
* When rolled over units expire.
*/
declare const ItemExpiryDurationType: {
readonly Month: "month";
readonly Forever: "forever";
};
/**
* When rolled over units expire.
*/
type ItemExpiryDurationType = OpenEnum<typeof ItemExpiryDurationType>;
/**
* Rollover configuration for unused units. If set, unused included units roll over to the next period.
*/
type PlanItemRollover = {
/**
* Maximum rollover units. Null for unlimited rollover.
*/
max: number | null;
/**
* Maximum rollover as a percentage (0-100) of included + prepaid grant. Mutually exclusive with max.
*/
maxPercentage?: number | null | undefined;
/**
* When rolled over units expire.
*/
expiryDurationType: ItemExpiryDurationType;
/**
* Number of periods before expiry.
*/
expiryDurationLength?: number | undefined;
};
type Item = {
/**
* The ID of the feature this item configures.
*/
featureId: string;
/**
* The full feature object if expanded.
*/
feature?: PlanFeature | undefined;
/**
* Number of free units included. For consumable features, balance resets to this number each interval.
*/
included: number;
/**
* Whether the customer has unlimited access to this feature.
*/
unlimited: boolean;
/**
* Reset configuration for consumable features. Null for non-consumable features like seats where usage persists across billing cycles.
*/
reset: PlanItemReset | null;
/**
* Pricing configuration for usage beyond included units. Null if feature is entirely free.
*/
price: PlanItemPrice | null;
/**
* Display text for showing this item in pricing pages.
*/
display?: PlanItemDisplay | undefined;
/**
* Rollover configuration for unused units. If set, unused included units roll over to the next period.
*/
rollover?: PlanItemRollover | undefined;
};
/**
* Unit of time for the trial duration ('day', 'month', 'year').
*/
declare const PlanDurationType: {
readonly Day: "day";
readonly Month: "month";
readonly Year: "year";
};
/**
* Unit of time for the trial duration ('day', 'month', 'year').
*/
type PlanDurationType = OpenEnum<typeof PlanDurationType>;
declare const OnEnd: {
readonly Bill: "bill";
readonly Revert: "revert";
};
type OnEnd = OpenEnum<typeof OnEnd>;
/**
* Free trial configuration. If set, new customers can try this plan before being charged.
*/
type FreeTrial = {
/**
* Number of duration_type periods the trial lasts.
*/
durationLength: number;
/**
* Unit of time for the trial duration ('day', 'month', 'year').
*/
durationType: PlanDurationType;
/**
* Whether a payment method is required to start the trial. If true, customer will be charged after trial ends.
*/
cardRequired: boolean;
/**
* Behavior when the trial ends. 'bill' charges the customer (default). 'revert' expires the trial and restores the customer's previous plan.
*/
onEnd?: OnEnd | null | undefined;
};
/**
* Environment this plan belongs to ('sandbox' or 'live').
*/
declare const PlanEnv: {
readonly Sandbox: "sandbox";
readonly Live: "live";
};
/**
* Environment this plan belongs to ('sandbox' or 'live').
*/
type PlanEnv = OpenEnum<typeof PlanEnv>;
/**
* Billing interval (e.g. 'month', 'year').
*/
declare const PlanPriceVariantDetailsInterval: {
readonly OneOff: "one_off";
readonly Week: "week";
readonly Month: "month";
readonly Quarter: "quarter";
readonly SemiAnnual: "semi_annual";
readonly Year: "year";
};
/**
* Billing interval (e.g. 'month', 'year').
*/
type PlanPriceVariantDetailsInterval = OpenEnum<typeof PlanPriceVariantDetailsInterval>;
/**
* Base price configuration for a plan.
*/
type BasePrice = {
/**
* Base price amount for the plan.
*/
amount: number;
/**
* Billing interval (e.g. 'month', 'year').
*/
interval: PlanPriceVariantDetailsInterval;
/**
* Number of intervals per billing cycle. Defaults to 1.
*/
intervalCount?: number | undefined;
};
/**
* Interval at which balance resets (e.g. 'month', 'year'). For consumable features only.
*/
declare const PlanAddItemResetInterval: {
readonly OneOff: "one_off";
readonly Minute: "minute";
readonly Hour: "hour";
readonly Day: "day";
readonly Week: "week";
readonly Month: "month";
readonly Quarter: "quarter";
readonly SemiAnnual: "semi_annual";
readonly Year: "year";
};
/**
* Interval at which balance resets (e.g. 'month', 'year'). For consumable features only.
*/
type PlanAddItemResetInterval = OpenEnum<typeof PlanAddItemResetInterval>;
/**
* Reset configuration for consumable features. Omit for non-consumable features like seats.
*/
type PlanVariantDetailsReset = {
/**
* Interval at which balance resets (e.g. 'month', 'year'). For consumable features only.
*/
interval: PlanAddItemResetInterval;
/**
* Number of intervals between resets. Defaults to 1.
*/
intervalCount?: number | undefined;
};
type PlanVariantDetailsTier = {
to: number | string;
amount: number;
flatAmount?: number | undefined;
};
declare const PlanVariantDetailsTierBehavior: {
readonly Graduated: "graduated";
readonly Volume: "volume";
};
type PlanVariantDetailsTierBehavior = OpenEnum<typeof PlanVariantDetailsTierBehavior>;
/**
* Billing interval. For consumable features, should match reset.interval.
*/
declare const PlanAddItemPriceInterval: {
readonly OneOff: "one_off";
readonly Week: "week";
readonly Month: "month";
readonly Quarter: "quarter";
readonly SemiAnnual: "semi_annual";
readonly Year: "year";
};
/**
* Billing interval. For consumable features, should match reset.interval.
*/
type PlanAddItemPriceInterval = OpenEnum<typeof PlanAddItemPriceInterval>;
/**
* 'prepaid' for upfront payment (seats), 'usage_based' for pay-as-you-go.
*/
declare const PlanAddItemBillingMethod: {
readonly Prepaid: "prepaid";
readonly UsageBased: "usage_based";
};
/**
* 'prepaid' for upfront payment (seats), 'usage_based' for pay-as-you-go.
*/
type PlanAddItemBillingMethod = OpenEnum<typeof PlanAddItemBillingMethod>;
/**
* Pricing for usage beyond included units. Omit for free features.
*/
type PlanVariantDetailsPrice = {
/**
* Price per billing_units after included usage. Either 'amount' or 'tiers' is required.
*/
amount?: number | undefined;
/**
* Tiered pricing. Either 'amount' or 'tiers' is required.
*/
tiers?: Array<PlanVariantDetailsTier> | undefined;
tierBehavior?: PlanVariantDetailsTierBehavior | undefined;
/**
* Billing interval. For consumable features, should match reset.interval.
*/
interval: PlanAddItemPriceInterval;
/**
* Number of intervals per billing cycle. Defaults to 1.
*/
intervalCount: number;
/**
* Units per price increment. Usage is rounded UP when billed (e.g. billing_units=100 means 101 rounds to 200).
*/
billingUnits: number;
/**
* 'prepaid' for upfront payment (seats), 'usage_based' for pay-as-you-go.
*/
billingMethod: PlanAddItemBillingMethod;
/**
* Max units purchasable beyond included. E.g. included=100, max_purchase=300 allows 400 total. Null for no limit.
*/
maxPurchase?: number | null | undefined;
};
/**
* Billing behavior when quantity increases mid-cycle.
*/
declare const OnIncrease: {
readonly BillImmediately: "bill_immediately";
readonly ProrateImmediately: "prorate_immediately";
readonly ProrateNextCycle: "prorate_next_cycle";
readonly BillNextCycle: "bill_next_cycle";
};
/**
* Billing behavior when quantity increases mid-cycle.
*/
type OnIncrease = OpenEnum<typeof OnIncrease>;
/**
* Credit behavior when quantity decreases mid-cycle.
*/
declare const OnDecrease: {
readonly Prorate: "prorate";
readonly ProrateImmediately: "prorate_immediately";
readonly ProrateNextCycle: "prorate_next_cycle";
readonly None: "none";
readonly NoProrations: "no_prorations";
};
/**
* Credit behavior when quantity decreases mid-cycle.
*/
type OnDecrease = OpenEnum<typeof OnDecrease>;
/**
* Proration settings for prepaid features. Controls mid-cycle quantity change billing.
*/
type Proration = {
/**
* Billing behavior when quantity increases mid-cycle.
*/
onIncrease: OnIncrease;
/**
* Credit behavior when quantity decreases mid-cycle.
*/
onDecrease: OnDecrease;
};
/**
* When rolled over units expire.
*/
declare const VariantDetailsExpiryDurationType: {
readonly Month: "month";
readonly Forever: "forever";
};
/**
* When rolled over units expire.
*/
type VariantDetailsExpiryDurationType = OpenEnum<typeof VariantDetailsExpiryDurationType>;
/**
* Rollover config for unused units. If set, unused included units carry over.
*/
type PlanVariantDetailsRollover = {
/**
* Max rollover units. Omit for unlimited rollover.
*/
max?: number | undefined;
/**
* Maximum rollover as a percentage (0-100) of included + prepaid grant. Mutually exclusive with max.
*/
maxPercentage?: number | undefined;
/**
* When rolled over units expire.
*/
expiryDurationType: VariantDetailsExpiryDurationType;
/**
* Number of periods before expiry.
*/
expiryDurationLength?: number | undefined;
};
/**
* Configuration for a feature item in a plan, including usage limits, pricing, and rollover settings.
*/
type PlanItem = {
/**
* The ID of the feature to configure.
*/
featureId: string;
/**
* Number of free units included. Balance resets to this each interval for consumable features.
*/
included?: number | undefined;
/**
* If true, customer has unlimited access to this feature.
*/
unlimited?: boolean | undefined;
/**
* Reset configuration for consumable features. Omit for non-consumable features like seats.
*/
reset?: PlanVariantDetailsReset | undefined;
/**
* Pricing for usage beyond included units. Omit for free features.
*/
price?: PlanVariantDetailsPrice | undefined;
/**
* Proration settings for prepaid features. Controls mid-cycle quantity change billing.
*/
proration?: Proration | undefined;
/**
* Rollover config for unused units. If set, unused included units carry over.
*/
rollover?: PlanVariantDetailsRollover | undefined;
};
/**
* Match items with this billing method (prepaid or usage_based).
*/
declare const PlanRemoveItemBillingMethod: {
readonly Prepaid: "prepaid";
readonly UsageBased: "usage_based";
};
/**
* Match items with this billing method (prepaid or usage_based).
*/
type PlanRemoveItemBillingMethod = OpenEnum<typeof PlanRemoveItemBillingMethod>;
declare const PlanIntervalRemoveItemEnum2: {
readonly OneOff: "one_off";
readonly Minute: "minute";
readonly Hour: "hour";
readonly Day: "day";
readonly Week: "week";
readonly Month: "month";
readonly Quarter: "quarter";
readonly SemiAnnual: "semi_annual";
readonly Year: "year";
};
type PlanIntervalRemoveItemEnum2 = OpenEnum<typeof PlanIntervalRemoveItemEnum2>;
declare const PlanIntervalRemoveItemEnum1: {
readonly OneOff: "one_off";
readonly Week: "week";
readonly Month: "month";
readonly Quarter: "quarter";
readonly SemiAnnual: "semi_annual";
readonly Year: "year";
};
type PlanIntervalRemoveItemEnum1 = OpenEnum<typeof PlanIntervalRemoveItemEnum1>;
/**
* Filter for matching plan items. All provided fields must match (AND).
*/
type PlanItemFilter = {
/**
* Match items linked to this feature.
*/
featureId?: string | undefined;
/**
* Match items with this billing method (prepaid or usage_based).
*/
billingMethod?: PlanRemoveItemBillingMethod | undefined;
/**
* Match items with this interval. Accepts either a BillingInterval (price-side) or a ResetInterval (reset-side, includes day/hour/minute) so price-less items keyed by reset.interval can be disambiguated.
*/
interval?: PlanIntervalRemoveItemEnum1 | PlanIntervalRemoveItemEnum2 | undefined;
/**
* Match items with this interval_count. Disambiguates between items that share an interval but differ in count.
*/
intervalCount?: number | undefined;
};
/**
* Unit of time for the trial ('day', 'month', 'year').
*/
declare const PlanVariantDetailsDurationType: {
readonly Day: "day";
readonly Month: "month";
readonly Year: "year";
};
/**
* Unit of time for the trial ('day', 'month', 'year').
*/
type PlanVariantDetailsDurationType = OpenEnum<typeof PlanVariantDetailsDurationType>;
/**
* Behavior when the trial ends. 'bill' charges the customer (default). 'revert' expires the trial and restores the customer's previous plan.
*/
declare const VariantDetailsOnEnd: {
readonly Bill: "bill";
readonly Revert: "revert";
};
/**
* Behavior when the trial ends. 'bill' charges the customer (default). 'revert' expires the trial and restores the customer's previous plan.
*/
type VariantDetailsOnEnd = OpenEnum<typeof VariantDetailsOnEnd>;
/**
* Free trial configuration for a plan.
*/
type FreeTrialParams = {
/**
* Number of duration_type periods the trial lasts.
*/
durationLength: number;
/**
* Unit of time for the trial ('day', 'month', 'year').
*/
durationType: PlanVariantDetailsDurationType;
/**
* If true, payment method required to start trial. Customer is charged after trial ends.
*/
cardRequired: boolean;
/**
* Behavior when the trial ends. 'bill' charges the customer (default). 'revert' expires the trial and restores the customer's previous plan.
*/
onEnd?: VariantDetailsOnEnd | undefined;
};
/**
* The time interval for the purchase limit window.
*/
declare const PlanVariantDetailsPurchaseLimitInterval: {
readonly Hour: "hour";
readonly Day: "day";
readonly Week: "week";
readonly Month: "month";
};
/**
* The time interval for the purchase limit window.
*/
type PlanVariantDetailsPurchaseLimitInterval = OpenEnum<typeof PlanVariantDetailsPurchaseLimitInterval>;
/**
* Optional rate limit to cap how often auto top-ups occur.
*/
type PlanVariantDetailsPurchaseLimit = {
/**
* The time interval for the purchase limit window.
*/
interval: PlanVariantDetailsPurchaseLimitInterval;
/**
* Number of intervals in the purchase limit window.
*/
intervalCount: number;
/**
* Maximum number of auto top-ups allowed within the interval.
*/
limit: number;
};
type PlanVariantDetailsAutoTopup = {
/**
* The ID of the feature (credit balance) to auto top-up.
*/
featureId: string;
/**
* Whether auto top-up is enabled.
*/
enabled: boolean;
/**
* 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?: PlanVariantDetailsPurchaseLimit | 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 PlanVariantDetailsLimitType: {
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 PlanVariantDetailsLimitType = OpenEnum<typeof PlanVariantDetailsLimitType>;
type PlanVariantDetailsSpendLimit = {
/**
* Optional feature ID this spend limit applies to.
*/
featureId?: string | undefined;
/**
* Whether the overage spend limit is enabled.
*/
enabled: boolean;
/**
* How overage_limit is interpreted: an absolute overage cap (default) or a percentage of the main-plan allowance.
*/
limitType?: PlanVariantDetailsLimitType | 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 PlanVariantDetailsUsageLimitInterval: {
readonly Day: "day";
readonly Week: "week";
readonly Month: "month";
readonly Year: "year";
};
/**
* Interval for the cap, aligned to the customer's billing cycle.
*/
type PlanVariantDetailsUsageLimitInterval = OpenEnum<typeof PlanVariantDetailsUsageLimitInterval>;
/**
* When set, only usage from events whose properties match counts toward this cap. Omit to count all usage of the feature.
*/
type PlanVariantDetailsFilter = {
properties: {
[k: string]: any;
};
};
type PlanVariantDetailsUsageLimit = {
/**
* The feature this usage limit applies to.
*/
featureId: string;
/**
* Whether this usage limit is enabled.
*/
enabled: boolean;
/**
* Maximum units allowed per interval.
*/
limit: number;
/**
* Interval for the cap, aligned to the customer's billing cycle.
*/
interval: PlanVariantDetailsUsageLimitInterval;
/**
* When set, only usage from events whose properties match counts toward this cap. Omit to count all usage of the feature.
*/
filter?: PlanVariantDetailsFilter | undefined;
};
/**
* Whether the threshold is an absolute count or a percentage of the usage allowance or remaining balance.
*/
declare const PlanVariantDetailsThresholdType: {
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 PlanVariantDetailsThresholdType = OpenEnum<typeof PlanVariantDetailsThresholdType>;
type PlanVariantDetailsUsageAlert = {
/**
* The feature ID this alert applies to.
*/
featureId?: string | undefined;
/**
* Whether this usage alert is enabled.
*/
enabled: boolean;
/**
* 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: PlanVariantDetailsThresholdType;
/**
* Optional user-defined label to distinguish multiple alerts on the same feature.
*/
name?: string | undefined;
};
type PlanVariantDetailsOverageAllowed = {
/**
* The feature ID this overage allowed control applies to.
*/
featureId: string;
/**
* Whether overage is allowed for this feature.
*/
enabled: boolean;
};
/**
* Override the plan's billing controls (auto top-ups, spend limits, usage limits, usage alerts, overage allowed) for this customer.
*/
type PlanVariantDetailsBillingControls = {
/**
* List of auto top-up configurations per feature.
*/
autoTopups?: Array<PlanVariantDetailsAutoTopup> | undefined;
/**
* List of overage spend limits per feature (caps overage spend).
*/
spendLimits?: Array<PlanVariantDetailsSpendLimit> | undefined;
/**
* List of hard usage caps per feature (max units per interval).
*/
usageLimits?: Array<PlanVariantDetailsUsageLimit> | undefined;
/**
* List of usage alert configurations per feature.
*/
usageAlerts?: Array<PlanVariantDetailsUsageAlert> | undefined;
/**
* List of overage allowed controls per feature. When enabled, usage can exceed balance.
*/
overageAllowed?: Array<PlanVariantDetailsOverageAllowed> | undefined;
};
/**
* The customization that transforms the base plan into this variant.
*/
type Customize = {
/**
* Override the base price of the plan. Pass null to remove the base price.
*/
price?: BasePrice | null | undefined;
/**
* Items to add to the plan.
*/
addItems?: Array<PlanItem> | undefined;
/**
* Filters selecting items to remove from the plan.
*/
removeItems?: Array<PlanItemFilter> | undefined;
/**
* Override the plan's default free trial. Pass an object to set a custom trial, or null to remove the trial entirely.
*/
freeTrial?: FreeTrialParams | null | undefined;
/**
* Override the plan's billing controls (auto top-ups, spend limits, usage limits, usage alerts, overage allowed) for this customer.
*/
billingControls?: PlanVariantDetailsBillingControls | undefined;
};
/**
* Details about how this variant relates to its latest base plan.
*/
type VariantDetails = {
/**
* The ID of the base plan this variant was derived from.
*/
basePlanId: string;
/**
* The customization that transforms the base plan into this variant.
*/
customize?: Customize | undefined;
};
/**
* Miscellaneous plan-level configuration flags.
*/
type PlanConfig = {
/**
* If true, entitlements attached to this plan will still reset on schedule even when the customer's product is in a past_due state.
*/
ignorePastDue: boolean;
};
/**
* The time interval for the purchase limit window.
*/
declare const PlanPurchaseLimitInterval: {
readonly Hour: "hour";
readonly Day: "day";
readonly Week: "week";
readonly Month: "month";
};
/**
* The time interval for the purchase limit window.
*/
type PlanPurchaseLimitInterval = OpenEnum<typeof PlanPurchaseLimitInterval>;
/**
* Optional rate limit to cap how often auto top-ups occur.
*/
type PlanPurchaseLimit = {
/**
* The time interval for the purchase limit window.
*/
interval: PlanPurchaseLimitInterval;
/**
* Number of intervals in the purchase limit window.
*/
intervalCount: number;
/**
* Maximum number of auto top-ups allowed within the interval.
*/
limit: number;
};
type PlanAutoTopup = {
/**
* The ID of the feature (credit balance) to auto top-up.
*/
featureId: string;
/**
* Whether auto top-up is enabled.
*/
enabled: boolean;
/**
* 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?: PlanPurchaseLimit | 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 PlanLimitType: {
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 PlanLimitType = OpenEnum<typeof PlanLimitType>;
type PlanSpendLimit = {
/**
* Optional feature ID this spend limit applies to.
*/
featureId?: string | undefined;
/**
* Whether the overage spend limit is enabled.
*/
enabled: boolean;
/**
* How overage_limit is interpreted: an absolute overage cap (default) or a percentage of the main-plan allowance.
*/
limitType?: PlanLimitType | 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 PlanUsageLimitInterval: {
readonly Day: "day";
readonly Week: "week";
readonly Month: "month";
readonly Year: "year";
};
/**
* Interval for the cap, aligned to the customer's billing cycle.
*/
type PlanUsageLimitInterval = OpenEnum<typeof PlanUsageLimitInterval>;
/**
* When set, only usage from events whose properties match counts toward this cap. Omit to count all usage of the feature.
*/
type PlanFilter = {
properties: {
[k: string]: any;
};
};
type PlanUsageLimit = {
/**
* The feature this usage limit applies to.
*/
featureId: string;
/**
* Whether this usage limit is enabled.
*/
enabled: boolean;
/**
* Maximum units allowed per interval.
*/
limit: number;
/**
* Interval for the cap, aligned to the customer's billing cycle.
*/
interval: PlanUsageLimitInterval;
/**
* When set, only usage from events whose properties match counts toward this cap. Omit to count all usage of the feature.
*/
filter?: PlanFilter | undefined;
};
/**
* Whether the threshold is an absolute count or a percentage of the usage allowance or remaining balance.
*/
declare const PlanThresholdType: {
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 PlanThresholdType = OpenEnum<typeof PlanThresholdType>;
type PlanUsageAlert = {
/**
* The feature ID this alert applies to.
*/
featureId?: string | undefined;
/**
* Whether this usage alert is enabled.
*/
enabled: boolean;
/**
* 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: PlanThresholdType;
/**
* Optional user-defined label to distinguish multiple alerts on the same feature.
*/
name?: string | undefined;
};
type PlanOverageAllowed = {
/**
* The feature ID this overage allowed control applies to.
*/
featureId: string;
/**
* Whether overage is allowed for this feature.
*/
enabled: boolean;
};
/**
* Plan-level billing controls used as customer defaults.
*/
type PlanBillingControls = {
/**
* List of auto top-up configurations per feature.
*/
autoTopups?: Array<PlanAutoTopup> | undefined;
/**
* List of overage spend limits per feature (caps overage spend).
*/
spendLimits?: Array<PlanSpendLimit> | undefined;
/**
* List of hard usage caps per feature (max units per interval).
*/
usageLimits?: Array<PlanUsageLimit> | undefined;
/**
* List of usage alert configurations per feature.
*/
usageAlerts?: Array<PlanUsageAlert> | undefined;
/**
* List of overage allowed controls per feature. When enabled, usage can exceed balance.
*/
overageAllowed?: Array<PlanOverageAllowed> | undefined;
};
/**
* The customer's current status with this plan. 'active' if attached, 'scheduled' if pending activation.
*/
declare const PlanStatus: {
readonly Active: "active";
readonly Scheduled: "scheduled";
};
/**
* The customer's current status with this plan. 'active' if attached, 'scheduled' if pending activation.
*/
type PlanStatus = OpenEnum<typeof PlanStatus>;
/**
* The action that would occur if this plan were attached to the customer.
*/
declare const AttachAction: {
readonly Activate: "activate";
readonly Upgrade: "upgrade";
readonly Downgrade: "downgrade";
readonly None: "none";
readonly Purchase: "purchase";
};
/**
* The action that would occur if this plan were attached to the customer.
*/
type AttachAction = OpenEnum<typeof AttachAction>;
type CustomerEligibility = {
/**
* Whether the trial on this plan is available to this customer. For example, if the customer used the trial in the past, this will be false.
*/
trialAvailable?: boolean | undefined;
/**
* The customer's current status with this plan. 'active' if attached, 'scheduled' if pending activation.
*/
status?: PlanStatus | undefined;
/**
* Whether the customer's active instance of this plan is set to cancel.
*/
canceling?: boolean | undefined;
/**
* Whether the customer is currently on a free trial of this plan.
*/
trialing?: boolean | undefined;
/**
* The action that would occur if this plan were attached to the customer.
*/
attachAction: AttachAction;
};
type Plan = {
/**
* Unique identifier for the plan.
*/
id: string;
/**
* Display name of the plan.
*/
name: string;
/**
* Optional description of the plan.
*/
description: string | null;
/**
* Group identifier for organizing related plans. Plans in the same group are mutually exclusive.
*/
group: string | null;
/**
* Version number of the plan. Incremented when plan configuration changes.
*/
version: number;
/**
* Whether this is an add-on plan that can be attached alongside a main plan.
*/
addOn: boolean;
/**
* If true, this plan is automatically attached when a customer is created. Used for free plans.
*/
autoEnable: boolean;
/**
* Base recurring price for the plan. Null for free plans or usage-only plans.
*/
price: PlanPrice | null;
/**
* Feature configurations included in this plan. Each item defines included units, pricing, and reset behavior for a feature.
*/
items: Array<Item>;
/**
* Free trial configuration. If set, new customers can try this plan before being charged.
*/
freeTrial?: FreeTrial | undefined;
/**
* Unix timestamp (ms) when the plan was created.
*/
createdAt: number;
/**
* Environment this plan belongs to ('sandbox' or 'live').
*/
env: PlanEnv;
/**
* Whether the plan is archived. Archived plans cannot be attached to new customers.
*/
archived: boolean;
/**
* Deprecated. Use variant_details.base_plan_id instead. If this is a variant, the ID of the base plan it was created from.
*/
baseVariantId: string | null;
/**
* Details about how this variant relates to its latest base plan.
*/
variantDetails?: VariantDetails | undefined;
/**
* Miscellaneous plan-level configuration flags.
*/
config: PlanConfig;
/**
* Plan-level billing controls used as customer defaults.
*/
billingControls?: PlanBillingControls | undefined;
/**
* Arbitrary key-value metadata defined by you for your own use. Shared across all versions of the plan.
*/
metadata: {
[k: string]: any;
};
customerEligibility?: CustomerEligibility | undefined;
};
export type { BalanceFeature as B, ClosedEnum as C, OpenEnum as O, Plan as P, Balance as a };