@oxygen-agent/cli 1.1010.721 → 1.1010.905

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;
@@ -75,7 +85,8 @@ 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;
+/** 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
@@ -87,12 +98,17 @@ export declare function creditTopupUsdCentsAtRate(credits: number, usdCentsPer10
 /** 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 ever been 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.
+ * 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];
+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
@@ -100,7 +116,37 @@ export declare const CREDIT_TOPUP_LEGACY_USD_CENTS_PER_100: number;
  * wrote, and it is refused rather than credited at a cheaper rate.
  */
 export declare function isAcceptedCreditTopupRate(usdCentsPer100: number, currentUsdCentsPer100?: number): boolean;
-export declare const AUTOMATION_ACTION_CREDITS = 0.001;
+/**
+ * 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", "x_account", "phone_number"];
 export type CreditCommitmentKind = (typeof CREDIT_COMMITMENT_KINDS)[number];
@@ -113,11 +159,6 @@ export type CreditCommitmentKind = (typeof CREDIT_COMMITMENT_KINDS)[number];
  * 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.
- */
-export declare const MANAGED_MAILBOX_MONTHLY_CREDITS = 300;
 /**
  * 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
@@ -125,6 +166,25 @@ export declare const MANAGED_MAILBOX_MONTHLY_CREDITS = 300;
  * days with no auto-cancel). The pause and the disconnect sweep are slice S23.
  */
 export declare const COMMITMENT_PAST_DUE_GRACE_DAYS = 7;
+/**
+ * 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 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
@@ -157,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;
 /**
@@ -221,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;
@@ -233,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;
@@ -365,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;
@@ -394,6 +530,26 @@ export declare const CREDIT_CYCLE_MAX_PERIOD_DAYS = 35;
 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;