@oxygen-agent/cli 1.1010.650 → 1.1010.905

package/node_modules/@oxygen/shared/dist/billing-anchors.js

@@ -108,8 +108,10 @@ export function occurrencesInPeriod(from, to, anchorDay) {
  * The block is a STANDING one-month-per-resource reserve (see
  * credit-commitments.ts): because every anchor is at most one month out, holding
  * one month per active resource always covers every fixed charge falling due
- * inside any coming subscription period of <= 1 month. Longer periods (annual
- * plans) need proportionally more held, or the block runs dry mid-term.
+ * inside any coming subscription period of <= 1 month. Longer periods need
+ * proportionally more held, or the block runs dry mid-term. A yearly plan is
+ * not such a period: it grants monthly slices, so its caller passes the current
+ * slice's length (see recomputeOrgCommitmentBlock, P-23).
  *
  * Returns at least 1 — a missing/zero/garbage period length must never collapse
  * the block to nothing, which would silently disable the whole feature.
@@ -133,3 +135,93 @@ export function periodLengthDays(start, end) {
         return null;
     return Math.floor(ms / DAY_MS);
 }
+// ---------------------------------------------------------------------------
+// Monthly credit slices of a longer (annual) subscription period
+// ---------------------------------------------------------------------------
+//
+// Repricing 2026-09, decision 1.2: every plan size can be paid annually, and the
+// credits are STILL granted monthly. One paid annual period therefore funds a
+// sequence of monthly grant slices. P-8 (PROPOSED default) anchors the slices to
+// the subscription period start, walked with the same immutable-anchor clamp as
+// the commitment anchors above: a period starting 31 Jan slices at 28 Feb,
+// 31 Mar, 30 Apr ... and never decays to the 28th.
+/** Average Gregorian month length in days: 365.2425 / 12. */
+const AVERAGE_MONTH_DAYS = 365.2425 / 12;
+/** Longest period that is still ONE monthly grant (matches the allowance-bar guard). */
+export const SINGLE_GRANT_PERIOD_MAX_DAYS = 35;
+/**
+ * The monthly grant slices of one paid subscription period.
+ *
+ * A period of at most {@link SINGLE_GRANT_PERIOD_MAX_DAYS} days is a single
+ * slice covering the whole period, which is exactly today's monthly grant. A
+ * longer period is cut on its start's anchor day. The slice count is bounded by
+ * the period's length in average months (12 for a year, including leap years
+ * and clamped anchors), and the last slice absorbs any remainder, so a period
+ * end whose time of day differs from its start by seconds can never produce a
+ * thirteenth sliver.
+ */
+export function subscriptionGrantSlices(periodStart, periodEnd) {
+    if (!(periodStart instanceof Date) || !(periodEnd instanceof Date))
+        return [];
+    if (Number.isNaN(periodStart.getTime()) || Number.isNaN(periodEnd.getTime()))
+        return [];
+    if (periodEnd <= periodStart)
+        return [];
+    const periodDays = (periodEnd.getTime() - periodStart.getTime()) / DAY_MS;
+    if (periodDays <= SINGLE_GRANT_PERIOD_MAX_DAYS) {
+        return [{ index: 0, start: periodStart, end: periodEnd }];
+    }
+    const maxSlices = Math.max(1, Math.round(periodDays / AVERAGE_MONTH_DAYS));
+    const anchorDay = anchorDayOf(periodStart);
+    const slices = [];
+    let cursor = periodStart;
+    for (let index = 0; index < maxSlices; index += 1) {
+        const next = nextAnchorDueAt(cursor, anchorDay);
+        if (index === maxSlices - 1 || next >= periodEnd) {
+            slices.push({ index, start: cursor, end: periodEnd });
+            break;
+        }
+        slices.push({ index, start: cursor, end: next });
+        cursor = next;
+    }
+    return slices;
+}
+/**
+ * The slices of a period that have started by `now`, in order. Nothing after the
+ * period end is ever due: a subscription set to cancel at period end, or a row
+ * whose renewal webhook has not arrived yet, stops at its last paid slice.
+ */
+export function dueSubscriptionGrantSlices(periodStart, periodEnd, now) {
+    return subscriptionGrantSlices(periodStart, periodEnd).filter((slice) => slice.start.getTime() <= now.getTime());
+}
+/** The slice `now` falls in, or null outside the period. */
+export function currentSubscriptionGrantSlice(periodStart, periodEnd, now) {
+    return (subscriptionGrantSlices(periodStart, periodEnd).find((slice) => slice.start.getTime() <= now.getTime() && now.getTime() < slice.end.getTime()) ?? null);
+}
+/**
+ * When the next monthly credit grant of a paid plan arrives (repricing 2026-09,
+ * S13: "know when my credits arrive").
+ *
+ * A monthly plan grants with its renewal, at the period end. A yearly plan
+ * grants each slice at its start, so the next grant is the end of the slice
+ * `now` falls in; the last slice's end is the renewal. A grant that depends on
+ * the renewal is null when the renewal will not happen (`renews: false`: a
+ * scheduled cancellation, a lapsed or unpaid plan), because no grant follows.
+ */
+export function nextSubscriptionCreditGrantAt(input) {
+    const now = input.now ?? new Date();
+    const end = input.periodEnd;
+    if (!(end instanceof Date) || Number.isNaN(end.getTime()))
+        return null;
+    if (end.getTime() <= now.getTime())
+        return null;
+    const start = input.periodStart;
+    if (input.billingInterval === "year"
+        && start instanceof Date
+        && !Number.isNaN(start.getTime())) {
+        const slice = currentSubscriptionGrantSlice(start, end, now);
+        if (slice && slice.end.getTime() < end.getTime())
+            return slice.end;
+    }
+    return input.renews ? end : null;
+}

package/node_modules/@oxygen/shared/dist/billing.d.ts

@@ -1,3 +1,4 @@
+import { type RepricingOptions } from "./repricing.js";
 export declare const WEEKLY_USAGE_WINDOW_DAYS = 7;
 export declare const BILLING_CURRENCIES: readonly ["usd"];
 export type BillingCurrency = (typeof BILLING_CURRENCIES)[number];
@@ -52,7 +53,16 @@ export type PricingPlanDefinition = {
 export type PricingPlanMetadata = Record<string, unknown> | null | undefined;
 export declare const CONTACT_SALES_URL = "mailto:priority@oxygen-agent.com";
 export declare const CREDITS_PER_USD = 100;
-export declare const TOPUP_USD_CENTS_PER_100_CREDITS = 125;
+/**
+ * US cents per 100 on-demand top-up credits right now. The rate rises from 125
+ * ($1.25) to the seed's 130 ($1.30) at the 2026-09 repricing's effective instant
+ * (decision 1.5, slice S10), so it is read per call through the switch and never
+ * from the snapshot: plan credits are then at least 23% cheaper (1 - 1.00/1.30),
+ * where they were 20% cheaper at $1.25. A page that shows it resolves it on the
+ * server and passes the number down, because a client bundle cannot read the
+ * switch.
+ */
+export declare function creditTopupUsdCentsPer100(options?: RepricingOptions): number;
 export declare const CREDIT_TOPUP_MIN_CREDITS = 800;
 export declare const CREDIT_TOPUP_MAX_CREDITS = 100000;
 export declare const CREDIT_TOPUP_STEP_CREDITS = 100;
@@ -60,8 +70,8 @@ export declare const CREDIT_TOPUP_DEFAULT_CREDITS = 2000;
 export declare function isValidCreditTopupCredits(credits: number): boolean;
 /**
  * A shortfall expressed as an amount `oxygen billing topup` will actually SELL:
- * rounded up onto the 1,000-credit step and clamped into the purchasable
- * [8,000 .. 1,000,000] band. A next_action (or an alert email) naming a number the
+ * rounded up onto CREDIT_TOPUP_STEP_CREDITS (100) and clamped into the purchasable
+ * [CREDIT_TOPUP_MIN_CREDITS .. CREDIT_TOPUP_MAX_CREDITS] band (800 .. 100,000). A next_action (or an alert email) naming a number the
  * top-up route refuses with `invalid_topup_amount` is not a next action, it is a
  * second dead end during the incident it exists to end.
  *
@@ -75,30 +85,106 @@ export declare function isValidCreditTopupCredits(credits: number): boolean;
  * second rounding formula is how two customer-facing figures drift apart.
  */
 export declare function creditTopupAmountForShortfall(credits: number): number;
-export declare function creditTopupUsdCents(credits: number): number | null;
-export declare const AUTOMATION_ACTION_CREDITS = 0.001;
+/** Price of a custom top-up at the rate in force now (`creditTopupUsdCentsPer100`). */
+export declare function creditTopupUsdCents(credits: number, options?: RepricingOptions): number | null;
+/**
+ * Price of a custom top-up at an explicit rate. A checkout session records the
+ * rate it was quoted at (`CREDIT_TOPUP_RATE_METADATA_KEY`), and fulfillment
+ * re-prices it at THAT rate, never the rate in force when Stripe confirms the
+ * payment: a session opened before a rate change and paid after it must still
+ * be credited.
+ */
+export declare function creditTopupUsdCentsAtRate(credits: number, usdCentsPer100: number): number | null;
+/** Checkout-session metadata key carrying the rate a top-up was quoted at. */
+export declare const CREDIT_TOPUP_RATE_METADATA_KEY = "usd_cents_per_100";
+/**
+ * Every top-up rate (US cents per 100 credits) a checkout has been or can be
+ * minted at. Append when the rate changes; never remove one, because an unpaid
+ * session quoted at it can still be paid. The first entry is also the rate of
+ * sessions created before the rate was written into their metadata.
+ *
+ * 130 is the 2026-09 rate (decision 1.5). It is listed before the switch's
+ * instant as well, so a session minted after the instant is still credited if
+ * an operator rolls the switch back before the customer pays. Accepting a rate
+ * higher than the one in force can never credit a purchase cheaply.
+ */
+export declare const CREDIT_TOPUP_SOLD_USD_CENTS_PER_100: readonly [125, 130];
+export declare const CREDIT_TOPUP_LEGACY_USD_CENTS_PER_100: number;
+/**
+ * Whether fulfillment may price a session at `usdCentsPer100`: a rate OXYGEN has
+ * sold at, or the rate in force now. Anything else is metadata no OXYGEN server
+ * wrote, and it is refused rather than credited at a cheaper rate.
+ */
+export declare function isAcceptedCreditTopupRate(usdCentsPer100: number, currentUsdCentsPer100?: number): boolean;
+/**
+ * Credits one workflow step costs right now. Every step a live run executes
+ * (a manifest step, a billable graph node, a recipe checkpoint, the durable
+ * recipe runtime) draws this from the one credit pool; rows written inside a run
+ * are free (repricing 2026-09, decisions 6.1 and 6.2). Seed key:
+ * charge.automation.action.
+ *
+ * The step price rises 0.001 → 0.05 at the repricing's effective instant (S07),
+ * so it is read per call through the switch and never from the snapshot. A page
+ * that shows it resolves it on the server and passes the number down.
+ */
+export declare function automationStepCredits(options?: RepricingOptions): number;
+/**
+ * Credits one provider call made with the customer's own API key (BYOK) costs
+ * right now: the platform fee of decision 6.3. The vendor bills the call to the
+ * customer's own account; this is OXYGEN's fee for running it. Seed key:
+ * charge.byok.platform_fee.
+ *
+ * 0 until the repricing's effective instant (S07), then 0.05, so it is read per
+ * call through the switch and never from the snapshot. Every BYOK provider call
+ * is admitted and captured at this price by `chargeByokCall`
+ * (`@oxygen/integrations`).
+ */
+export declare function byokPlatformFeeCredits(options?: RepricingOptions): number;
+/**
+ * Whether the step credits a live run executes count toward its approved
+ * `max_credits` and a trigger's per-delivery ceiling (proposal P-45). Dark until
+ * the step price rises with it: counting 0.001 steps would only tighten ceilings
+ * customers already approved.
+ */
+export declare function automationStepsCountTowardRunCap(options?: RepricingOptions): boolean;
 /** Kinds of resource that carry a fixed monthly credit commitment. */
-export declare const CREDIT_COMMITMENT_KINDS: readonly ["sending_mailbox", "managed_mailbox", "mailbox_warmup", "deliverability_unit", "linkedin_account", "whatsapp_account"];
+export declare const CREDIT_COMMITMENT_KINDS: readonly ["sending_mailbox", "managed_mailbox", "mailbox_warmup", "deliverability_unit", "linkedin_account", "whatsapp_account", "x_account", "phone_number"];
 export type CreditCommitmentKind = (typeof CREDIT_COMMITMENT_KINDS)[number];
 /**
  * Sequencer platform fee per CONNECTED SENDING MAILBOX per month, in credits
  * ($1.00). Charged on EVERY mailbox wired to the sequencer — BYOK/self-connected
  * Gmail and Microsoft inboxes included — and it STACKS on Oxygen-sold mailboxes,
- * which additionally pay their own mailbox/warmup/placement lines.
+ * which additionally pay their own mailbox/warmup/placement lines. Read from the
+ * pricing seed (`commitment.sending_mailbox`) through the generated snapshot, so
+ * there is one definition of the price.
  */
 export declare const SENDING_MAILBOX_MONTHLY_CREDITS = 100;
 /**
- * Oxygen-sold managed mailbox per month, in credits ($3.00). Flat, superseding
- * the dynamic vendor-COGS x 1.25 quote for the recurring mailbox line.
+ * Grace window after a commitment goes past_due before the account disconnects.
+ * Repricing 2026-09 decision 2.8: sending from the account pauses at once, and
+ * after 7 days without funds the account disconnects (replacing the earlier 14
+ * days with no auto-cancel). The pause and the disconnect sweep are slice S23.
  */
-export declare const MANAGED_MAILBOX_MONTHLY_CREDITS = 300;
+export declare const COMMITMENT_PAST_DUE_GRACE_DAYS = 7;
 /**
- * Grace window after a commitment goes past_due before the owning subsystem may
- * suspend the resource. Notify -> pause -> lapse; never auto-cancel. Aligned with
- * the subscription entitlement grace so a customer never hits two different
- * clocks for the same missed payment.
+ * P-15 (PROPOSED default, awaiting ratification): what "disconnect" means for a
+ * rented phone number. Releasing a number at the carrier is irreversible, so it is
+ * suspended at COMMITMENT_PAST_DUE_GRACE_DAYS (it already cannot dial while past
+ * due) and released only after this many days without funds.
  */
-export declare const COMMITMENT_PAST_DUE_GRACE_DAYS = 14;
+export declare const PHONE_NUMBER_PAST_DUE_RELEASE_DAYS = 30;
+/**
+ * What happens to a connected account whose reservation renewal was refused, and
+ * when (decision 2.8 and P-15). `teardown` is the one irreversible-or-disconnecting
+ * step and `teardownAt` its instant; `suspendedAt` marks the day-7 rung for a kind
+ * whose teardown waits longer (a phone number).
+ */
+export type CommitmentGraceSchedule = {
+    teardown: "disconnect" | "release";
+    teardownAt: Date;
+    suspendedAt: Date | null;
+};
+export declare function commitmentGraceSchedule(kind: CreditCommitmentKind, pastDueSince: Date): CommitmentGraceSchedule;
 /**
  * Reconnect window in which an ENDED commitment resumes instead of starting a new
  * one. The single most important anti-double-charge rule: a Unipile re-auth, a
@@ -131,26 +217,48 @@ export declare const COMMITMENT_GRACE_DAYS = 30;
  * InboxPricingUnsignedError / WarmupPricingUnsignedError doctrine.
  */
 export declare function ratifiedCommitmentCredits(kind: CreditCommitmentKind): number | null;
-export declare const CREDIT_TOPUP_PACKS: readonly [{
-    readonly id: "10";
-    readonly usdCents: 1000;
-    readonly credits: 800;
-}, {
-    readonly id: "25";
-    readonly usdCents: 2500;
-    readonly credits: 2000;
-}, {
-    readonly id: "100";
-    readonly usdCents: 10000;
-    readonly credits: 8000;
-}, {
-    readonly id: "250";
-    readonly usdCents: 25000;
-    readonly credits: 20000;
-}];
-export type CreditTopupPack = (typeof CREDIT_TOPUP_PACKS)[number];
-export type CreditTopupPackId = CreditTopupPack["id"];
+export type CreditTopupPack = {
+    readonly id: string;
+    readonly usdCents: number;
+    readonly credits: number;
+};
+/**
+ * The dollar packs sold at $1.25 per 100 credits, on offer until the 2026-09
+ * repricing's effective instant. The id is the pack's price in dollars.
+ */
+export declare const CREDIT_TOPUP_LEGACY_PACKS: readonly CreditTopupPack[];
+/**
+ * The credit-first packs on offer from the 2026-09 repricing's instant, at $1.30
+ * per 100 credits (decision 1.5; the pack set is PROPOSED P-7). Dollar packs at
+ * $1.30 would buy fractional credits ($10 → 769.2), so these fix the credits and
+ * the id names them. The ids are new on purpose: fulfillment credits a pack
+ * session `pack.credits` without re-checking its amount, so reusing '10' or '25'
+ * with a new price would credit an old unpaid session from the new table.
+ */
+export declare const CREDIT_TOPUP_PACKS_2026_09: readonly CreditTopupPack[];
+/** Every pack id a checkout session may carry, whichever table sold it. */
+export declare const CREDIT_TOPUP_KNOWN_PACKS: readonly CreditTopupPack[];
+/** The packs on offer now: the dollar packs until the switch, the credit-first packs from it. */
+export declare function creditTopupPacks(options?: RepricingOptions): readonly CreditTopupPack[];
+/**
+ * Any pack a session may name, with the credits and price it was SOLD at. Used by
+ * fulfillment, which must credit an old session its original credits whichever
+ * packs are on offer when Stripe confirms the payment.
+ */
 export declare function resolveCreditTopupPack(id: string | null | undefined): CreditTopupPack | null;
+/**
+ * How the top-up route sells a pack id right now. A pack on offer sells at its
+ * own price. Any other known id (a dollar pack after the switch from an older
+ * CLI, or a credit-first pack before it) still works and buys the pack's credits
+ * as a custom amount at the rate in force, so an old client sees the current
+ * quote and never an old price. Null for an unknown id.
+ */
+export declare function quoteCreditTopupPack(id: string | null | undefined, options?: RepricingOptions): {
+    pack: CreditTopupPack;
+    offered: boolean;
+    credits: number;
+    usdCents: number;
+} | null;
 export declare const TRIAL_PERIOD_DAYS = 7;
 export declare const TRIAL_CREDIT_GRANT = 2000;
 /**
@@ -195,6 +303,54 @@ export declare const FREE_TIER_GRANTS_ENABLED_ENV_VAR = "OXYGEN_FREE_TIER_GRANTS
 export declare function freeTierGrantsEnabled(env?: Record<string, string | undefined>): boolean;
 export declare const WALKTHROUGH_COMPLETION_BONUS_CREDITS = 100;
 export declare const WALKTHROUGH_SCRAPE_MAX_CREDITS = 200;
+/**
+ * The volume bonus of a plan (repricing 2026-09, decision 1.3): the monthly
+ * credits it grants above face value ($1 = 100 credits). +5% on $499 (52,395),
+ * +10% on $999 (109,890), +15% on $1,999 (229,885); $49-$199 stay flat.
+ *
+ * DERIVED from the seeded monthlyCredits rather than declared, so the schedule
+ * lives in one place (packages/control-db/src/pricing/seed.ts). Only the
+ * purchasable Oxygen rungs carry a bonus: a legacy plan whose credits exceed its
+ * price (launch_50 bought 20,000 credits for $50 under the old unit) is not a
+ * volume bonus, and a contact-sales plan has no face value.
+ */
+export declare function planVolumeBonusCredits(planKey: string | null | undefined): number;
+/**
+ * The volume bonus inside one subscription grant of `monthlyCredits` on
+ * `planKey`: the plan's bonus when the grant is the plan's seeded allowance, and
+ * 0 when a metadata override replaced it (a custom allowance carries no
+ * schedule to defer). Grant writers pass this to grantSubscriptionCredits.
+ */
+export declare function subscriptionGrantVolumeBonusCredits(planKey: string | null | undefined, monthlyCredits: number | null | undefined): number;
+/** The volume bonus as a whole percentage of face value: 5, 10, 15, or 0. */
+export declare function planVolumeBonusPercent(planKey: string | null | undefined): number;
+/**
+ * Agency partner bonus (repricing 2026-09, decision 9.1): a partner earns
+ * +15% of its plan's face value in bonus credits every month, on every Oxygen
+ * size from $99, on top of the volume bonus. The two percentages ADD (spec
+ * PROPOSED default P-1, option A of the agency-partner benchmark): the $1,999
+ * plan grants 229,885 + 29,985 = 259,870, never 229,885 x 1.15.
+ *
+ * The bonus is its own ledger line (category `partner_bonus`), never part of
+ * the plan's monthlyCredits, so it stays out of every limit or guard derived
+ * from the plan allowance (P-3, P-54, P-61).
+ */
+export declare const PARTNER_BONUS_PERCENT = 15;
+/** The smallest plan that earns the partner bonus: $99 a month. */
+export declare const PARTNER_BONUS_MINIMUM_MONTHLY_PRICE_CENTS = 9900;
+/**
+ * The monthly partner bonus of a plan: 15% of face value ($1 = 100 credits),
+ * rounded half up to a whole credit (section 2's rounding rule). 0 for Free,
+ * $49, the grandfathered Starter/Pro/Team and older legacy plans, and the
+ * contact-sales plans (P-3: Oxygen sizes only).
+ */
+export declare function planPartnerBonusCredits(planKey: string | null | undefined): number;
+/**
+ * The partner bonus that rides with one subscription grant of `monthlyCredits`
+ * on `planKey`: the plan's bonus when the grant is the plan's seeded allowance,
+ * 0 when a metadata override replaced it (a custom contract is priced by hand).
+ */
+export declare function subscriptionGrantPartnerBonusCredits(planKey: string | null | undefined, monthlyCredits: number | null | undefined): number;
 export declare const BASE_PRICING_PLANS: {
     readonly free: {
         readonly monthlyPriceCents: number | null;
@@ -207,9 +363,9 @@ export declare const BASE_PRICING_PLANS: {
         readonly monthlyAutomationActions: null;
         readonly automationOverageCentsPerMillion: null;
         readonly automationOverageEnabledDefault: false;
-        readonly description: "Your CRM, tables, and workflows — free forever. Credits pay for enrichment and AI; connecting a sender, publishing, managed email infrastructure, and your own provider keys need a plan.";
+        readonly description: "Your CRM and tables — free forever. Credits pay for enrichment, AI and workflow steps; your own provider keys need a paid plan.";
         readonly ctaLabel: "Upgrade";
-        readonly features: readonly ["CRM, Tables, Workflows, and Knowledge — unmetered", "Sequences: author, preview, and enroll", "Agents and Workspace Copilot", "Credits for enrichment and AI, topped up any time"];
+        readonly features: readonly ["CRM, Tables, and Knowledge — unmetered; workflows pay per step", "Sequences: author, preview, and enroll", "Agents and Workspace Copilot", "Credits for enrichment and AI, topped up any time"];
     };
     readonly oxygen: {
         readonly monthlyPriceCents: number | null;
@@ -339,12 +495,18 @@ export declare function resolveSubscriptionEntitlement(input: {
     currentPeriodStart?: Date | null;
     currentPeriodEnd?: Date | null;
     trialEnd?: Date | null;
+    /**
+     * `subscriptions.past_due_since`: when this unpaid streak was first seen.
+     * The past-due grace counts from here, never from a period start that a
+     * yearly plan may have set months ago.
+     */
+    pastDueSince?: Date | null;
     now?: Date;
     /** Overrides the env switch. Injected by tests; production reads the flag. */
     freeTierEntitled?: boolean;
 }): SubscriptionEntitlement;
 export type ResolvedPricingPlan = PricingPlanDefinition;
-export declare function resolveBasePricingPlan(tier: string | null | undefined): ResolvedPricingPlan | null;
+export declare function resolveBasePricingPlan(tier: string | null | undefined, options?: RepricingOptions): ResolvedPricingPlan | null;
 export declare function applyPricingPlanMetadataOverrides(// skipcq: JS-R1005
 plan: PricingPlanDefinition, metadata: PricingPlanMetadata): PricingPlanDefinition;
 export declare function isSelfServePlanTier(value: string): value is SelfServePlanTier;
@@ -361,6 +523,33 @@ export declare function getCurrentBillingCycleKey(date?: Date): string;
  * billing-anchor shift without admitting a quarterly or annual period.
  */
 export declare const CREDIT_CYCLE_MAX_PERIOD_DAYS = 35;
+/**
+ * Annual billing (Repricing 2026-09, decision 1.2): a year costs ten months of
+ * the monthly price, and the credits are still granted monthly.
+ */
+export declare const ANNUAL_BILLING_MONTHS_CHARGED = 10;
+/** The yearly price of a rung, in cents: ten times its monthly price. */
+export declare function annualPlanPriceCents(monthlyPriceCents: number): number;
+/** How often a plan Price bills. Credits are granted monthly on both. */
+export type PlanBillingInterval = "month" | "year";
+export declare const PLAN_BILLING_INTERVALS: readonly PlanBillingInterval[];
+/**
+ * A billing interval as a customer or an agent types it. `month`/`monthly` and
+ * `year`/`yearly`/`annual`/`annually` are accepted; anything else is null so the
+ * caller can refuse it by name instead of silently billing monthly.
+ */
+export declare function parsePlanBillingInterval(value: unknown): PlanBillingInterval | null;
+/**
+ * What one charge of a rung costs on an interval, in cents: the monthly price,
+ * or ten months' price for a year.
+ */
+export declare function planChargeCents(monthlyPriceCents: number, interval: PlanBillingInterval): number;
+/**
+ * The per-month equivalent of one charge, in cents, rounded to the cent: $990 a
+ * year is $82.50 a month. This is what `recurring_monthly` reports, so a yearly
+ * plan is never compared as if it cost $990 a month.
+ */
+export declare function planMonthlyEquivalentCents(chargeCents: number, interval: PlanBillingInterval): number;
 export type CreditCycleSource = "subscription_period" | "calendar_month";
 export type CreditCycleWindow = {
     start: Date;
@@ -389,6 +578,21 @@ export declare function isStripeManagedSubscription(subscription: {
     stripeSubscriptionId?: string | null;
     metadata?: Record<string, unknown> | null;
 }): boolean;
+/**
+ * Whether a Stripe subscription is scheduled to end. A classic-billing-mode
+ * period-end cancel sets `cancel_at_period_end`; a Billing Portal cancel on a
+ * flexible-billing-mode subscription sets only `cancel_at` (to the period end)
+ * and leaves `cancel_at_period_end` false (Stripe billing-mode comparison docs;
+ * reproduced in test mode 2026-09-26). Reading the boolean alone showed a
+ * Portal-cancelled plan as renewing. `cancel_at` on a subscription that has
+ * already ended records when it ended, not a pending cancellation, so it only
+ * counts while the subscription is still live.
+ */
+export declare function stripeSubscriptionCancellationScheduled(subscription: {
+    status: string;
+    cancel_at_period_end?: boolean | null;
+    cancel_at?: number | null;
+}): boolean;
 /**
  * The window the credit-allowance bar measures: "this month's credits", resolved
  * to the boundary at which the plan's grant actually renews.
@@ -412,6 +616,12 @@ export declare function resolveCreditCycleWindow(input: {
         currentPeriodEnd: Date | null;
         /** isOffStripeSubscription(subscription.metadata) — resolved by the caller. */
         offStripe: boolean;
+        /**
+         * planBillingIntervalForPriceId(subscription.stripePriceId). A yearly
+         * period grants its credits in monthly slices, so the cycle the bar measures
+         * is the current slice, anchored to the period start (P-8).
+         */
+        billingInterval?: "month" | "year" | null;
     } | null;
     now?: Date;
 }): CreditCycleWindow;