@oxygen-agent/cli 1.377.3 → 1.591.1

package/node_modules/@oxygen/formula/dist/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * @oxygen/formula — the OXYGEN expression language, host-free.
+ *
+ * Tokenizer, parser, static analysis, function registry, and a scope-driven
+ * evaluator with no node builtins and no dependency beyond the dependency-free
+ * `@oxygen/shared/cli-result` leaf (for `OxygenError`) — so the exact semantics
+ * that run a formula column in the worker also run in the browser (formula
+ * editor previews, the visual workflow editor).
+ *
+ * Hosts bind identifiers by implementing `FormulaScope.resolve` —
+ * `@oxygen/tenant-db` binds them to a workspace table row.
+ */
+export { isRecord } from "./coerce.js";
+export * from "./evaluate.js";
+export * from "./expression.js";
+export * from "./formula-functions.js";
+export * from "./value-normalizers.js";

package/node_modules/@oxygen/formula/dist/index.js

@@ -0,0 +1,17 @@
+/**
+ * @oxygen/formula — the OXYGEN expression language, host-free.
+ *
+ * Tokenizer, parser, static analysis, function registry, and a scope-driven
+ * evaluator with no node builtins and no dependency beyond the dependency-free
+ * `@oxygen/shared/cli-result` leaf (for `OxygenError`) — so the exact semantics
+ * that run a formula column in the worker also run in the browser (formula
+ * editor previews, the visual workflow editor).
+ *
+ * Hosts bind identifiers by implementing `FormulaScope.resolve` —
+ * `@oxygen/tenant-db` binds them to a workspace table row.
+ */
+export { isRecord } from "./coerce.js";
+export * from "./evaluate.js";
+export * from "./expression.js";
+export * from "./formula-functions.js";
+export * from "./value-normalizers.js";

package/node_modules/@oxygen/formula/dist/value-normalizers.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Canonical value normalizers shared by every subsystem that compares
+ * identity-shaped values: CRM identity resolution, the formula function
+ * registry, row dedupe, and Records↔Tables binding. One source of truth so
+ * "does foo@Bar.com match FOO@bar.com" answers the same everywhere — including
+ * in the browser. Pure string functions — no I/O, no tenant context.
+ */
+export declare const VALUE_NORMALIZATIONS: readonly ["exact_text_v1", "lower_trim_v1", "email_v1", "domain_v1", "linkedin_url_v1", "uuid_v1"];
+export type ValueNormalization = (typeof VALUE_NORMALIZATIONS)[number];
+export declare function isValueNormalization(value: unknown): value is ValueNormalization;
+/** `email_v1`: case-insensitive mailbox match. */
+export declare function normalizeEmail(value: string): string;
+/**
+ * `domain_v1`: reduce a URL, hostname, or bare domain to its canonical
+ * registrable form — lowercased hostname without `www.` or trailing dots.
+ */
+export declare function normalizeDomain(value: string): string;
+/** `linkedin_url_v1`: trailing-slash-insensitive, case-insensitive profile URL match. */
+export declare function normalizeLinkedinUrl(value: string): string;
+/** `uuid_v1`: case-insensitive UUID match. */
+export declare function normalizeUuid(value: string): string;
+/** `exact_text_v1`: whitespace-trimmed verbatim match. */
+export declare function normalizeExactText(value: string): string;
+/** `lower_trim_v1`: the default loose text match (trimmed, case-insensitive). */
+export declare function normalizeLowerTrim(value: string): string;
+/**
+ * Apply a named normalization. Unknown names fall back to `exact_text_v1`
+ * semantics, matching the historical CRM identity behavior.
+ */
+export declare function normalizeValue(normalization: string, value: string): string;

package/node_modules/@oxygen/formula/dist/value-normalizers.js

@@ -0,0 +1,80 @@
+/**
+ * Canonical value normalizers shared by every subsystem that compares
+ * identity-shaped values: CRM identity resolution, the formula function
+ * registry, row dedupe, and Records↔Tables binding. One source of truth so
+ * "does foo@Bar.com match FOO@bar.com" answers the same everywhere — including
+ * in the browser. Pure string functions — no I/O, no tenant context.
+ */
+export const VALUE_NORMALIZATIONS = [
+    "exact_text_v1",
+    "lower_trim_v1",
+    "email_v1",
+    "domain_v1",
+    "linkedin_url_v1",
+    "uuid_v1",
+];
+export function isValueNormalization(value) {
+    return typeof value === "string" && VALUE_NORMALIZATIONS.includes(value);
+}
+/** `email_v1`: case-insensitive mailbox match. */
+export function normalizeEmail(value) {
+    return value.trim().toLowerCase();
+}
+/**
+ * `domain_v1`: reduce a URL, hostname, or bare domain to its canonical
+ * registrable form — lowercased hostname without `www.` or trailing dots.
+ */
+export function normalizeDomain(value) {
+    const trimmed = value.trim().toLowerCase();
+    if (!trimmed)
+        return "";
+    try {
+        const parsed = new URL(trimmed.includes("://") ? trimmed : `https://${trimmed}`);
+        return parsed.hostname.replace(/^www\./, "").replace(/\.+$/, "");
+    }
+    catch {
+        return trimmed
+            .replace(/^https?:\/\//, "")
+            .split("/")[0]
+            ?.replace(/^www\./, "")
+            .replace(/\.+$/, "")
+            ?? "";
+    }
+}
+/** `linkedin_url_v1`: trailing-slash-insensitive, case-insensitive profile URL match. */
+export function normalizeLinkedinUrl(value) {
+    return value.trim().replace(/\/+$/, "").toLowerCase();
+}
+/** `uuid_v1`: case-insensitive UUID match. */
+export function normalizeUuid(value) {
+    return value.trim().toLowerCase();
+}
+/** `exact_text_v1`: whitespace-trimmed verbatim match. */
+export function normalizeExactText(value) {
+    return value.trim();
+}
+/** `lower_trim_v1`: the default loose text match (trimmed, case-insensitive). */
+export function normalizeLowerTrim(value) {
+    return value.trim().toLowerCase();
+}
+/**
+ * Apply a named normalization. Unknown names fall back to `exact_text_v1`
+ * semantics, matching the historical CRM identity behavior.
+ */
+export function normalizeValue(normalization, value) {
+    switch (normalization) {
+        case "email_v1":
+            return normalizeEmail(value);
+        case "domain_v1":
+            return normalizeDomain(value);
+        case "linkedin_url_v1":
+            return normalizeLinkedinUrl(value);
+        case "uuid_v1":
+            return normalizeUuid(value);
+        case "lower_trim_v1":
+            return normalizeLowerTrim(value);
+        case "exact_text_v1":
+        default:
+            return normalizeExactText(value);
+    }
+}

package/node_modules/@oxygen/formula/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@oxygen/formula",
+  "version": "0.0.0",
+  "private": false,
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./functions": {
+      "types": "./dist/formula-functions.d.ts",
+      "import": "./dist/formula-functions.js",
+      "default": "./dist/formula-functions.js"
+    },
+    "./value-normalizers": {
+      "types": "./dist/value-normalizers.d.ts",
+      "import": "./dist/value-normalizers.js",
+      "default": "./dist/value-normalizers.js"
+    }
+  },
+  "dependencies": {}
+}

package/node_modules/@oxygen/recipe-sdk/dist/index.d.ts

@@ -130,6 +130,19 @@ export type RecipeStepOptions<T> = {
     effect?: WorkflowStepEffect;
     run: () => T | Promise<T>;
 };
+export type RecipeWaitOptions = {
+    /** Relative deadline. Exactly one of `seconds` or `until` is required. */
+    seconds?: number;
+    /** Absolute deadline as an ISO-8601 instant. */
+    until?: string;
+};
+export type RecipeWaitResult = {
+    waited: boolean;
+    /** The deadline this wait resolved against, ISO-8601. */
+    resume_at: string;
+    /** True when the mode short-circuited the wait instead of parking. */
+    simulated?: boolean;
+};
 export type RecipeContext = {
     input: unknown;
     mode: WorkflowMode;
@@ -143,6 +156,23 @@ export type RecipeContext = {
     approvals: RecipeApprovalApi;
     log: (level: RecipeLogLevel, message: string, payload?: Record<string, unknown>) => void;
     step: <T = unknown>(key: string, options: RecipeStepOptions<T>) => Promise<T>;
+    /**
+     * Park the run until a deadline, durably.
+     *
+     * NOT a sleep: the run's lease is released and the worker moves on, so a wait
+     * of three days costs no compute and survives a deploy or a crash. When the
+     * deadline passes the recipe replays from its last checkpoint and this call
+     * returns — so everything before it keeps its recorded results and no tool is
+     * re-run.
+     *
+     * The `key` is the checkpoint identity, exactly like ctx.step(): it is what
+     * lets a replay recognise a wait it has already served rather than restarting
+     * the clock. Reusing a key within one execution is refused.
+     *
+     * Outside `live` the wait returns immediately — a dry run has no real clock to
+     * honour, and blocking a preview for three days would make previews unusable.
+     */
+    wait: (key: string, options: RecipeWaitOptions) => Promise<RecipeWaitResult>;
     now: () => Promise<string>;
     uuid: () => Promise<string>;
 };

package/node_modules/@oxygen/recipe-sdk/dist/index.js

@@ -14,8 +14,8 @@ export function defineRecipe(input) {
     if (input.runtime !== undefined && input.runtime !== "durable") {
         throw new Error("Recipe runtime must be durable.");
     }
-    if (!Array.isArray(input.tools) || input.tools.length === 0) {
-        throw new Error("Durable recipes must declare at least one allowed tool.");
+    if (!Array.isArray(input.tools)) {
+        throw new Error("Durable recipes must declare a tools array (use tools: [] for pure recipes).");
     }
     const tools = Array.from(new Set(input.tools.map((tool) => {
         if (typeof tool !== "string" || !tool.trim()) {

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

@@ -0,0 +1,60 @@
+/**
+ * The immutable anchor day of a commitment — the UTC day-of-month it was
+ * created on. Stored once at creation and never recomputed, so the clamp in
+ * {@link nextAnchorDueAt} can always project from the original intent (the 31st)
+ * rather than from a previously clamped value (the 28th).
+ */
+export declare function anchorDayOf(anchorAt: Date): number;
+/**
+ * The next due instant for a commitment: exactly one calendar month after
+ * `periodStart`, on `anchorDay` clamped to the target month's length, preserving
+ * `periodStart`'s UTC time-of-day.
+ *
+ * Time-of-day is preserved so a mailbox connected at 09:14 bills at 09:14 — a
+ * commitment created minutes ago must not become due "today at 00:00" and get
+ * charged twice in one day by the next sweep tick.
+ *
+ * `anchorDay` is clamped into 1..31 defensively; a caller passing a value from a
+ * corrupted row gets a sane projection instead of an Invalid Date.
+ */
+export declare function nextAnchorDueAt(periodStart: Date, anchorDay: number): Date;
+/**
+ * The atomic-claim cursor for one commitment period. Replaces the calendar-month
+ * `YYYY-MM` key the other billers use; the shared billMonthlyCreditCycle engine
+ * never inspects the key's shape, so the swap is contained here.
+ *
+ * The period start is the identity (not the due date): a period is claimed once,
+ * and stamping the START means a claim written before the anchor advances still
+ * names the period that was actually billed.
+ */
+export declare function commitmentCycleKey(commitmentId: string, periodStart: Date): string;
+/**
+ * How many times a commitment on `anchorDay` falls due in the half-open window
+ * [from, to). Used to size the block for subscription periods longer than a
+ * month and to project "what will this cost me before my next renewal" on the
+ * commitments surface.
+ *
+ * Walks period by period rather than dividing elapsed days, because month
+ * lengths differ and the clamped anchor is not a fixed stride.
+ */
+export declare function occurrencesInPeriod(from: Date, to: Date, anchorDay: number): number;
+/**
+ * How many months of every fixed resource the block must hold, given the
+ * subscription period length in days.
+ *
+ * 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.
+ *
+ * Returns at least 1 — a missing/zero/garbage period length must never collapse
+ * the block to nothing, which would silently disable the whole feature.
+ */
+export declare function blockPeriodsForSubscription(periodDays: number | null | undefined): number;
+/**
+ * Days between two instants, floored. Small helper so callers deriving
+ * `blockPeriodsForSubscription` from a Stripe period pair do not each reimplement
+ * the millisecond math (and get it wrong across DST by using local dates).
+ */
+export declare function periodLengthDays(start: Date | null | undefined, end: Date | null | undefined): number | null;

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

@@ -0,0 +1,135 @@
+// Rolling per-resource monthly anchors for FIXED (committed) credit charges.
+//
+// Every other recurring biller in Oxygen (managed inboxes, warmup, placement,
+// LinkedIn seats, egress addons) keys its cycle on the CALENDAR month —
+// `YYYY-MM`. That is correct for a rail whose vendor invoices monthly, but it is
+// wrong for a per-resource commitment: a mailbox connected on the 9th should
+// bill on the 9th, and a LinkedIn account connected on the 22nd on the 22nd, so
+// each individual resource rolls its own month independently of the calendar and
+// independently of the subscription period.
+//
+// THE ANCHOR DAY IS STORED SEPARATELY FROM THE LAST DUE DATE, and that is the
+// whole trick. If you derive the next due date from the previous one by "same
+// day next month, clamped", a 31st anchor DECAYS: 31 Jan -> 28 Feb -> 28 Mar ->
+// 28 Apr, and the customer silently drifts three days earlier every year. Keeping
+// the immutable `anchorDay` and re-clamping from it each period gives the Stripe
+// anchor rule instead: 31 Jan -> 28 Feb -> 31 Mar. The clamp is a per-period
+// projection, never a mutation of the anchor.
+//
+// Pure module: no DB, no clock reads beyond the arguments handed in, no
+// dependencies. All arithmetic is UTC — a rolling anchor must not shift when the
+// worker host's local zone crosses DST.
+/** Milliseconds in a day. Local to keep this module dependency-free. */
+const DAY_MS = 24 * 60 * 60 * 1000;
+/**
+ * Days in a given UTC (year, monthIndex). `Date.UTC(y, m + 1, 0)` is the last
+ * day of month `m`, which is exactly the count.
+ */
+function daysInUtcMonth(year, monthIndex) {
+    return new Date(Date.UTC(year, monthIndex + 1, 0)).getUTCDate();
+}
+/**
+ * The immutable anchor day of a commitment — the UTC day-of-month it was
+ * created on. Stored once at creation and never recomputed, so the clamp in
+ * {@link nextAnchorDueAt} can always project from the original intent (the 31st)
+ * rather than from a previously clamped value (the 28th).
+ */
+export function anchorDayOf(anchorAt) {
+    return anchorAt.getUTCDate();
+}
+/**
+ * The next due instant for a commitment: exactly one calendar month after
+ * `periodStart`, on `anchorDay` clamped to the target month's length, preserving
+ * `periodStart`'s UTC time-of-day.
+ *
+ * Time-of-day is preserved so a mailbox connected at 09:14 bills at 09:14 — a
+ * commitment created minutes ago must not become due "today at 00:00" and get
+ * charged twice in one day by the next sweep tick.
+ *
+ * `anchorDay` is clamped into 1..31 defensively; a caller passing a value from a
+ * corrupted row gets a sane projection instead of an Invalid Date.
+ */
+export function nextAnchorDueAt(periodStart, anchorDay) {
+    const safeAnchorDay = Math.min(31, Math.max(1, Math.trunc(anchorDay)));
+    const year = periodStart.getUTCFullYear();
+    const monthIndex = periodStart.getUTCMonth();
+    // Normalize the +1 month ourselves rather than letting Date roll it: passing
+    // monthIndex 12 to Date.UTC is well-defined, but computing the target's day
+    // count needs the normalized (year, month) pair anyway.
+    const targetYear = monthIndex === 11 ? year + 1 : year;
+    const targetMonthIndex = monthIndex === 11 ? 0 : monthIndex + 1;
+    const day = Math.min(safeAnchorDay, daysInUtcMonth(targetYear, targetMonthIndex));
+    return new Date(Date.UTC(targetYear, targetMonthIndex, day, periodStart.getUTCHours(), periodStart.getUTCMinutes(), periodStart.getUTCSeconds(), periodStart.getUTCMilliseconds()));
+}
+/**
+ * The atomic-claim cursor for one commitment period. Replaces the calendar-month
+ * `YYYY-MM` key the other billers use; the shared billMonthlyCreditCycle engine
+ * never inspects the key's shape, so the swap is contained here.
+ *
+ * The period start is the identity (not the due date): a period is claimed once,
+ * and stamping the START means a claim written before the anchor advances still
+ * names the period that was actually billed.
+ */
+export function commitmentCycleKey(commitmentId, periodStart) {
+    return `${commitmentId}:${periodStart.toISOString()}`;
+}
+/**
+ * How many times a commitment on `anchorDay` falls due in the half-open window
+ * [from, to). Used to size the block for subscription periods longer than a
+ * month and to project "what will this cost me before my next renewal" on the
+ * commitments surface.
+ *
+ * Walks period by period rather than dividing elapsed days, because month
+ * lengths differ and the clamped anchor is not a fixed stride.
+ */
+export function occurrencesInPeriod(from, to, anchorDay) {
+    if (!(from instanceof Date) || !(to instanceof Date))
+        return 0;
+    if (Number.isNaN(from.getTime()) || Number.isNaN(to.getTime()))
+        return 0;
+    if (to <= from)
+        return 0;
+    let count = 0;
+    let cursor = from;
+    // Hard bound: a caller passing a decade-wide window should get a number, not a
+    // hang. 1200 periods is 100 years — far past any real subscription.
+    for (let guard = 0; guard < 1200; guard += 1) {
+        cursor = nextAnchorDueAt(cursor, anchorDay);
+        if (cursor >= to)
+            break;
+        count += 1;
+    }
+    return count;
+}
+/**
+ * How many months of every fixed resource the block must hold, given the
+ * subscription period length in days.
+ *
+ * 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.
+ *
+ * Returns at least 1 — a missing/zero/garbage period length must never collapse
+ * the block to nothing, which would silently disable the whole feature.
+ */
+export function blockPeriodsForSubscription(periodDays) {
+    if (typeof periodDays !== "number" || !Number.isFinite(periodDays) || periodDays <= 0) {
+        return 1;
+    }
+    return Math.max(1, Math.ceil(periodDays / 30));
+}
+/**
+ * Days between two instants, floored. Small helper so callers deriving
+ * `blockPeriodsForSubscription` from a Stripe period pair do not each reimplement
+ * the millisecond math (and get it wrong across DST by using local dates).
+ */
+export function periodLengthDays(start, end) {
+    if (!start || !end)
+        return null;
+    const ms = end.getTime() - start.getTime();
+    if (!Number.isFinite(ms) || ms <= 0)
+        return null;
+    return Math.floor(ms / DAY_MS);
+}

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

@@ -35,6 +35,60 @@ export declare const CREDIT_TOPUP_DEFAULT_CREDITS = 20000;
 export declare function isValidCreditTopupCredits(credits: number): boolean;
 export declare function creditTopupUsdCents(credits: number): number | null;
 export declare const AUTOMATION_ACTION_CREDITS = 0.01;
+/** 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 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.
+ */
+export declare const SENDING_MAILBOX_MONTHLY_CREDITS = 1000;
+/**
+ * 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 = 3000;
+/**
+ * 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.
+ */
+export declare const COMMITMENT_PAST_DUE_GRACE_DAYS = 14;
+/**
+ * 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
+ * mailbox re-import, or a reconciler blip must not re-charge a full month. Past
+ * this window a reconnect is treated as genuinely new and gets a fresh anchor,
+ * so a long-dead row can never resurrect and bill a stale period.
+ */
+export declare const COMMITMENT_RESUME_WINDOW_MS: number;
+/**
+ * Maximum periods one commitment may catch up in a single sweep tick. A worker
+ * outage (or a resurrected row) must never drain a wallet in one lump: past this
+ * many overdue periods the biller skips forward, stamps metadata.skipped_periods,
+ * and logs. Fail closed TOWARD the customer.
+ */
+export declare const COMMITMENT_MAX_CATCHUP_PERIODS = 3;
+/**
+ * Free month granted to resources that already existed when commitments went
+ * live. Combined with CREDIT_COMMITMENT_EPOCH_AT (which pins their anchor to
+ * go-live rather than their original created_at), this guarantees no existing
+ * customer is charged for infrastructure that was free when they connected it.
+ */
+export declare const COMMITMENT_GRACE_DAYS = 30;
+/**
+ * Flat ratified monthly price for a commitment kind, in credits — or null when
+ * the price is not owned HERE (warmup and deliverability are ratified in
+ * @oxygen/control-db; their callers use the integrations readers).
+ *
+ * Returning null is the fail-closed signal: an unpriced kind creates NO
+ * commitment row rather than a zero-credit one, matching the
+ * InboxPricingUnsignedError / WarmupPricingUnsignedError doctrine.
+ */
+export declare function ratifiedCommitmentCredits(kind: CreditCommitmentKind): number | null;
 export declare const CREDIT_TOPUP_PACKS: readonly [{
     readonly id: "10";
     readonly usdCents: 1000;
@@ -64,16 +118,16 @@ export declare const BASE_PRICING_PLANS: {
         readonly tier: "free";
         readonly name: "Free";
         readonly monthlyPriceCents: 0;
-        readonly monthlyCredits: 10000;
+        readonly monthlyCredits: 0;
         readonly weeklyCreditsLimit: null;
-        readonly rolloverCap: 10000;
+        readonly rolloverCap: null;
         readonly monthlyAutomationActions: null;
         readonly automationOverageCentsPerMillion: null;
         readonly automationOverageEnabledDefault: false;
         readonly byokEnabled: false;
-        readonly description: "Get $10 in credits on us every month — try OXYGEN with managed email, phone enrichment, and AI credits.";
-        readonly ctaLabel: "Start free";
-        readonly features: readonly ["$10 in credits every month", "All integrations", "Workflows", "No card required"];
+        readonly description: "No active plan. Start a 7-day Starter trial to use OXYGEN — existing credit balances remain spendable.";
+        readonly ctaLabel: "Start trial";
+        readonly features: readonly ["Existing credits stay spendable", "Read access to your workspace"];
     };
     readonly starter: {
         readonly tier: "starter";
@@ -185,6 +239,46 @@ export declare function isBillingCurrency(value: string): value is BillingCurren
 export declare function normalizeBillingCurrency(value: string | null | undefined): BillingCurrency;
 export declare function getCurrentFreeTierCycleKey(date?: Date): string;
 export declare function getCurrentBillingCycleKey(date?: Date): string;
+/**
+ * A monthly Stripe period runs 28-31 days; 35 leaves slack for a proration or a
+ * billing-anchor shift without admitting a quarterly or annual period.
+ */
+export declare const CREDIT_CYCLE_MAX_PERIOD_DAYS = 35;
+export type CreditCycleSource = "subscription_period" | "calendar_month";
+export type CreditCycleWindow = {
+    start: Date;
+    /** Exclusive; may be in the future (the cycle is usually still running). */
+    end: Date;
+    source: CreditCycleSource;
+    /** "July 2026" | "Jun 10 – Jul 10" */
+    label: string;
+};
+/**
+ * The window the credit-allowance bar measures: "this month's credits", resolved
+ * to the boundary at which the plan's grant actually renews.
+ *
+ * A Stripe-managed monthly subscription renews on its own period boundary, so
+ * that is the honest cycle for it. Everything else — off-Stripe custom plans,
+ * the free tier, and any non-monthly Stripe period — renews by CALENDAR month,
+ * which is the same boundary already used by getCurrentBillingCycleKey(),
+ * getCurrentFreeTierCycleKey(), the shared-billing workspace cap, and the
+ * automation-actions meter. The fallback is therefore consistent with every
+ * other monthly concept in the product rather than an invention.
+ *
+ * The length guard cuts BOTH ways deliberately. `now - start <= 35d` rejects a
+ * stale period a webhook never advanced; `end - start <= 35d` rejects a genuine
+ * annual subscription, which would otherwise pass the first check on day 3 and
+ * render a 365-day "month".
+ */
+export declare function resolveCreditCycleWindow(input: {
+    subscription: {
+        currentPeriodStart: Date | null;
+        currentPeriodEnd: Date | null;
+        /** isOffStripeSubscription(subscription.metadata) — resolved by the caller. */
+        offStripe: boolean;
+    } | null;
+    now?: Date;
+}): CreditCycleWindow;
 export declare function evaluateWeeklyQuota(usedCredits: number, requestedCredits: number, weeklyCreditsLimit: number): {
     usedCredits: number;
     requestedCredits: number;