@stacksjs/ts-cloud 0.7.108 → 0.7.109

package/dist/spend/model.d.ts

@@ -0,0 +1,228 @@
+/**
+ * Spend management: the shared vocabulary.
+ *
+ * A cap is only as good as the meter behind it. Cloud bills arrive late (AWS
+ * Cost Explorer lags a day and does not exist at all for Hetzner or a local
+ * box), so a budget that waits for the provider's number cannot stop a runaway
+ * loop - it can only describe one after the money is gone. Everything here is
+ * therefore built on *usage we observe ourselves*, priced locally through a
+ * price book, with the provider's invoice used later to true the estimate up.
+ *
+ * Money is integer cents throughout. Floating-point dollars accumulate rounding
+ * error across millions of usage records, and a cap that is off by a cent in
+ * the wrong direction is a cap that does not fire.
+ */
+import type { JsonValue } from '../control-plane';
+/** The physical unit a meter counts in. */
+export type MeterUnit = 'requests' | 'invocations' | 'gb' | 'gb_hours' | 'gb_seconds' | 'hours' | 'minutes' | 'count';
+/**
+ * Provider-neutral usage meters.
+ *
+ * These are deliberately *not* provider SKUs. `edge.egress_gb` is a gigabyte
+ * leaving the edge whether that edge is CloudFront, a Hetzner box's NIC, or
+ * nginx on a laptop; the price book is what turns it into money. Keeping the
+ * meter neutral is what lets one budget cover a mixed-provider project.
+ */
+export declare const METER_KEYS: readonly ['edge.requests', 'edge.egress_gb', 'function.invocations', 'function.gb_seconds', 'build.minutes', 'compute.instance_hours', 'storage.gb_hours', 'object.egress_gb', 'object.requests', 'database.gb_hours', 'database.io_requests', 'telemetry.ingest_gb', 'image.transformations'];
+export type MeterKey = (typeof METER_KEYS)[number] | (string & {});
+export interface MeterDefinition {
+    key: MeterKey;
+    unit: MeterUnit;
+    label: string;
+    /** Human-facing precision when rendering a quantity. */
+    precision: number;
+}
+export declare const METERS: Readonly<Record<string, MeterDefinition>>;
+/** Where a usage record came from and what it should be billed against. */
+export interface UsageScope {
+    organizationId: string;
+    projectId?: string;
+    environmentId?: string;
+    resourceId?: string;
+    provider?: string;
+    region?: string;
+}
+/** A single observed increment of usage. Deltas, never totals - see the store. */
+export interface UsageDelta extends UsageScope {
+    meter: MeterKey;
+    quantity: number;
+    /** When the usage happened (not when we noticed it). */
+    timestamp: string;
+    /** Free-form provenance, e.g. `{ source: 'edge-collector', host: 'web-1' }`. */
+    attributes?: Record<string, JsonValue>;
+}
+/** An hourly usage rollup as persisted. Quantities are additive; costs are derived. */
+export interface UsageRollup extends Required<Pick<UsageScope, 'organizationId'>> {
+    projectId: string;
+    environmentId: string;
+    resourceId: string;
+    provider: string;
+    region: string;
+    meter: MeterKey;
+    /** Inclusive start of the hour bucket, ISO-8601. */
+    bucketStart: string;
+    quantity: number;
+    costCents: number;
+    sampleCount: number;
+    updatedAt: string;
+}
+export type BudgetPeriod = 'daily' | 'weekly' | 'monthly';
+/**
+ * What a cap does when it is reached.
+ *
+ * Ordered from least to most disruptive. Enforcement never destroys data and
+ * every action is reversible; `suspend_project` parks traffic, it does not
+ * delete a thing.
+ */
+export declare const ENFORCEMENT_ACTIONS: readonly ['notify', 'block_builds', 'block_deployments', 'throttle_requests', 'suspend_functions', 'serve_static', 'suspend_project'];
+export type EnforcementAction = (typeof ENFORCEMENT_ACTIONS)[number];
+/** Disruption ranking, used to order a plan and to pick the strongest active action. */
+export declare const ENFORCEMENT_SEVERITY: Readonly<Record<EnforcementAction, number>>;
+/**
+ * One rung of the ladder: at `atPercent` of the limit, take these actions.
+ *
+ * Percent is of the *hard* limit when one is set, otherwise of the soft limit,
+ * so a single ladder reads consistently however the budget is configured.
+ */
+export interface BudgetThreshold {
+    atPercent: number;
+    actions: EnforcementAction[];
+    /** Fire on the forecast rather than on actual spend. Catches a spike early. */
+    onProjection?: boolean;
+}
+export interface Budget {
+    id: string;
+    organizationId: string;
+    projectId?: string;
+    environmentId?: string;
+    name: string;
+    period: BudgetPeriod;
+    /** IANA timezone the period boundaries are computed in. */
+    timezone: string;
+    currency: string;
+    /** Warn-only ceiling. Never enforces on its own; it drives `notify` rungs. */
+    softLimitCents?: number;
+    /** Enforcing ceiling. Reaching it runs the top of the ladder. */
+    hardLimitCents?: number;
+    thresholds: BudgetThreshold[];
+    /**
+     * Only these meters count toward the budget. Empty means every meter.
+     * Lets you cap "egress" without capping the whole project.
+     */
+    meters: MeterKey[];
+    /** Seconds a breach must persist before enforcement runs. Absorbs a blip. */
+    graceSeconds: number;
+    /**
+     * Percent below the trigger that spend must fall back to before an action is
+     * lifted. Without it, a scope sitting exactly on the line flaps.
+     */
+    hysteresisPercent: number;
+    /** Evaluate but never enforce. The way to roll a cap out safely. */
+    dryRun: boolean;
+    enabled: boolean;
+    version: number;
+    createdAt: string;
+    updatedAt: string;
+}
+export type SpendLevel = 'ok' | 'warning' | 'soft_capped' | 'hard_capped';
+/** The window a budget is currently being measured over. */
+export interface BudgetWindow {
+    start: string;
+    end: string;
+    elapsedMs: number;
+    totalMs: number;
+    label: string;
+}
+/** Forecast for the remainder of the window. */
+export interface SpendProjection {
+    /** Spend so far this window, cents. */
+    actualCents: number;
+    /** Cents per millisecond, from the observed burn. */
+    burnRateCentsPerMs: number;
+    /** Where the window lands if the current burn holds. */
+    projectedCents: number;
+    /** Fraction of the window elapsed, 0-1. Low values make the forecast noisy. */
+    elapsedFraction: number;
+    /**
+     * How much to trust `projectedCents`, 0-1. Grows with elapsed time and with
+     * the number of buckets observed; a forecast from 10 minutes of a month is
+     * arithmetic, not information.
+     */
+    confidence: number;
+    /** ISO timestamp the limit is projected to be hit, if it is hit in-window. */
+    exhaustionAt?: string;
+    /** Milliseconds until `exhaustionAt`. */
+    timeToExhaustionMs?: number;
+}
+/** A threshold that has been crossed. */
+export interface ThresholdBreach {
+    atPercent: number;
+    actions: EnforcementAction[];
+    /** True when the breach is against the forecast rather than actual spend. */
+    projected: boolean;
+    observedPercent: number;
+}
+/** The evaluator's verdict for one budget at one instant. */
+export interface SpendDecision {
+    budgetId: string;
+    level: SpendLevel;
+    window: BudgetWindow;
+    projection: SpendProjection;
+    /** Percent of the governing limit actually spent. */
+    usedPercent: number;
+    /** Percent of the governing limit the forecast lands at. */
+    projectedPercent: number;
+    breaches: ThresholdBreach[];
+    /** Actions the ladder calls for, deduped and ordered by severity. */
+    actions: EnforcementAction[];
+    /** Actions currently in force that should now be lifted. */
+    releases: EnforcementAction[];
+    /** True when `dryRun` suppressed real enforcement. */
+    simulated: boolean;
+    reason: string;
+    evaluatedAt: string;
+}
+export type EnforcementState = 'pending' | 'active' | 'releasing' | 'released' | 'failed';
+/** An enforcement action as applied to a scope, with what it takes to undo it. */
+export interface EnforcementRecord {
+    id: string;
+    budgetId: string;
+    organizationId: string;
+    projectId?: string;
+    environmentId?: string;
+    action: EnforcementAction;
+    state: EnforcementState;
+    reason: string;
+    /** Whatever the applier needs to restore the prior state. Never secrets. */
+    restore: Record<string, JsonValue>;
+    triggeredAtPercent: number;
+    simulated: boolean;
+    appliedAt?: string;
+    releasedAt?: string;
+    error?: string;
+    createdAt: string;
+    updatedAt: string;
+}
+export type AnomalyDirection = 'spike' | 'drop';
+/** A point that does not fit its own history. */
+export interface SpendAnomaly {
+    id: string;
+    organizationId: string;
+    projectId?: string;
+    environmentId?: string;
+    /** Meter key, or `cost` for the priced aggregate. */
+    signal: string;
+    direction: AnomalyDirection;
+    observed: number;
+    /** What the seasonal baseline expected. */
+    expected: number;
+    /** Robust z-score (MAD-based). */
+    score: number;
+    /** Plain-language delta, e.g. `+412%`. */
+    deltaPercent: number;
+    severity: 'info' | 'warning' | 'critical';
+    bucketStart: string;
+    evidence: Record<string, JsonValue>;
+    acknowledgedAt?: string;
+    createdAt: string;
+}

package/dist/spend/notifications.d.ts

@@ -0,0 +1,58 @@
+import type { AlertStore, NotificationDelivery } from '../alerts';
+import type { Budget, EnforcementAction, SpendAnomaly, SpendDecision } from './model';
+export type SpendEventType = 'spend.threshold' | 'spend.enforced' | 'spend.released' | 'spend.anomaly';
+/**
+ * Channel kinds worth waking someone for.
+ *
+ * A threshold crossing goes everywhere the routes point. Reaching the limit -
+ * where enforcement starts - is the one that should also reach a phone, which
+ * is why `sms` exists as a channel kind at all.
+ */
+export declare const URGENT_SPEND_EVENTS: readonly SpendEventType[];
+/** Money as an operator reads it, not as the database stores it. */
+export declare function formatCents(cents: number, currency?: string): string;
+/**
+ * A one-line summary an operator can act on from a phone.
+ *
+ * Deliberately leads with the money and the budget name rather than the
+ * percentage: "83% of Production" means nothing without knowing the limit.
+ */
+export declare function spendNotificationText(budget: Budget, decision: SpendDecision, event: SpendEventType): string;
+export interface SpendNotificationResult {
+    deliveries: NotificationDelivery[];
+    /** Routes that matched but were inside quiet hours. */
+    suppressed: string[];
+}
+/**
+ * Routes spend events to notification channels.
+ *
+ * Two rules borrowed from the alert router, for the same reasons:
+ *
+ *   - **Quiet hours never suppress a release.** Waking someone to say a cap
+ *     lifted is unnecessary; leaving them to think a cap is still on is worse.
+ *   - **Per-route rate limits apply.** A budget re-evaluated every minute must
+ *     not become a per-minute page, and the idempotency key does most of that
+ *     work already by collapsing repeats within a window.
+ */
+export declare class SpendNotificationRouter {
+    private readonly store;
+    private readonly options;
+    constructor(store: AlertStore, options?: {
+        now?: () => Date;
+    });
+    private now;
+    private channelsFor;
+    private dispatch;
+    /**
+     * Notify about a budget decision.
+     *
+     * The idempotency key includes the window and the crossed threshold, so the
+     * same breach re-evaluated every minute produces one delivery per threshold
+     * per window - not one per cycle.
+     */
+    notifyDecision(budget: Budget, decision: SpendDecision): SpendNotificationResult;
+    /** Notify that enforcement was lifted. */
+    notifyRelease(budget: Budget, decision: SpendDecision, released: readonly EnforcementAction[]): SpendNotificationResult;
+    /** Notify about a detected anomaly. One delivery per anomaly, ever. */
+    notifyAnomaly(anomaly: SpendAnomaly, currency?: string): SpendNotificationResult;
+}

package/dist/spend/pricing.d.ts

@@ -0,0 +1,109 @@
+/**
+ * The price book: usage in, cents out.
+ *
+ * Caps have to be enforceable on any provider, including ones with no billing
+ * API at all. A Hetzner box has a fixed monthly price and an included traffic
+ * allowance; a local box costs nothing until it egresses. Neither will ever
+ * answer a Cost Explorer query, so the platform prices usage itself and treats
+ * the provider invoice as a later correction rather than the source of truth.
+ *
+ * Rates are cents per unit and are stored as `microCentsPerUnit` (cents x 1e6)
+ * because per-request prices are genuinely tiny - CloudFront charges about
+ * 0.0000075 cents per request, which rounds to zero in any coarser unit and
+ * would silently make request floods free.
+ */
+import type { MeterKey } from './model';
+/** Cents x 1e6, so sub-cent unit prices survive integer storage. */
+export declare const MICRO_CENTS = 1000000;
+/**
+ * A graduated pricing tier.
+ *
+ * `upToQuantity` is the cumulative top of the tier, `null` for the final,
+ * unbounded one. Graduated (not flat-rate) semantics: quantity inside each tier
+ * is charged at that tier's rate, matching how every cloud actually bills.
+ */
+export interface PriceTier {
+    upToQuantity: number | null;
+    microCentsPerUnit: number;
+}
+export interface PriceEntry {
+    meter: MeterKey;
+    provider: string;
+    /** Omit for a provider-wide default; a region-specific entry wins over it. */
+    region?: string;
+    /** Quantity billed at zero before tiers apply (a free allowance). */
+    includedQuantity?: number;
+    /** Flat rate. Ignored when `tiers` is present. */
+    microCentsPerUnit?: number;
+    tiers?: PriceTier[];
+    /**
+     * Charged once per window regardless of usage (a box's monthly rental).
+     * Applied by the caller for the whole window, not per usage record.
+     */
+    fixedCentsPerPeriod?: number;
+}
+export interface PriceBook {
+    currency: string;
+    entries: PriceEntry[];
+}
+export interface PricedUsage {
+    meter: MeterKey;
+    provider: string;
+    region?: string;
+    quantity: number;
+    /** Quantity that fell inside the free allowance. */
+    includedQuantity: number;
+    billableQuantity: number;
+    costCents: number;
+    /** No price entry matched; cost is 0 and the caller should surface this. */
+    unpriced: boolean;
+}
+export interface PricedTotal {
+    currency: string;
+    totalCents: number;
+    lines: PricedUsage[];
+    /** Meters that had usage but no matching price entry. */
+    unpricedMeters: string[];
+}
+/**
+ * Cost of `quantity` units under a graduated tier list, in micro-cents.
+ *
+ * Tiers are sorted defensively: a book assembled from several sources should
+ * not price differently because someone listed the unbounded tier first.
+ */
+export declare function tieredMicroCents(quantity: number, tiers: PriceTier[]): number;
+/** Most specific match wins: exact region, then provider default, then wildcard provider. */
+export declare function findPriceEntry(book: PriceBook, meter: MeterKey, provider?: string, region?: string): PriceEntry | undefined;
+export interface UsageLine {
+    meter: MeterKey;
+    quantity: number;
+    provider?: string;
+    region?: string;
+}
+/**
+ * Price one usage line.
+ *
+ * `alreadyUsedQuantity` lets a caller price incrementally across a window while
+ * still honouring a free allowance: pass the quantity already billed this
+ * period and the allowance is consumed once, not once per call.
+ */
+export declare function priceUsage(book: PriceBook, line: UsageLine, alreadyUsedQuantity?: number): PricedUsage;
+/** Price a set of lines, one allowance per (meter, provider, region). */
+export declare function priceUsageLines(book: PriceBook, lines: UsageLine[]): PricedTotal;
+/** Round a cent amount to whole cents for storage or display. */
+export declare function roundCents(cents: number): number;
+/**
+ * Merge price books, later entries winning on an exact (meter, provider,
+ * region) match. This is how an operator overrides a shipped default without
+ * forking the whole book.
+ */
+export declare function mergePriceBooks(base: PriceBook, ...overrides: PriceBook[]): PriceBook;
+/**
+ * Shipped defaults, in US cents, list price, us-east-1 / eu-central.
+ *
+ * These are estimates for *forecasting and capping*, not an invoice. They are
+ * intentionally slightly conservative (rounded up) so a cap trips a little
+ * early rather than a little late - the failure mode of a cap that fires at
+ * 101% is a surprised user, and the whole point is not to surprise them.
+ */
+export declare const DEFAULT_PRICE_BOOK: PriceBook;

package/dist/spend/pricing.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/spend/projection.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Forecasting: where does this window land if nothing changes?
+ *
+ * A cap that only reacts to actual spend is always late - by the time a
+ * monthly budget reads 100%, the money is gone. The useful signal is the
+ * forecast, and the hard part about a forecast is knowing when to distrust it.
+ * Ten minutes into a month, a burn rate extrapolates to a number that is
+ * arithmetically correct and completely meaningless.
+ *
+ * So every projection carries a confidence, and the evaluator refuses to
+ * enforce on a low-confidence one. Two things build confidence: elapsed time
+ * (a longer sample is a better sample) and the number of buckets that actually
+ * carried spend (one huge hour is a spike, not a trend).
+ */
+import type { BudgetWindow, SpendProjection } from './model';
+export interface ProjectionInput {
+    window: BudgetWindow;
+    actualCents: number;
+    /** Hourly cost buckets in the window, ascending. Optional but sharpens the estimate. */
+    series?: ReadonlyArray<{
+        bucketStart: string;
+        costCents: number;
+    }>;
+    /** The limit to project exhaustion against, in cents. */
+    limitCents?: number;
+    /**
+     * How much weight recent buckets get, 0-1. Higher reacts faster to a spike;
+     * 0 falls back to the flat window average.
+     */
+    recencyWeight?: number;
+}
+export declare function projectSpend(input: ProjectionInput): SpendProjection;
+/** Percent of `limitCents` that `cents` represents. A zero limit is treated as fully used. */
+export declare function percentOfLimit(cents: number, limitCents?: number): number;
+/** Human-readable time-to-cap, e.g. `2d 4h`. Empty when the cap is not projected to be hit. */
+export declare function formatTimeToExhaustion(ms?: number): string;

package/dist/spend/runner.d.ts

@@ -0,0 +1,130 @@
+/**
+ * The spend loop: the thing that actually runs on a timer.
+ *
+ * Everything else in this module is a component - a store, a pure evaluator, a
+ * set of handlers. This is the composition, and it is deliberately the only
+ * place that knows the order:
+ *
+ *     ingest -> evaluate -> enforce -> notify -> detect anomalies -> prune
+ *
+ * Ingest first, because a decision made against last cycle's usage is a
+ * decision made a minute late, and a minute is a lot of invocations. Prune
+ * last, because pruning is the only step that is safe to skip if the process
+ * dies partway through.
+ *
+ * Cadence matters more than it looks. The loop is designed to run every minute:
+ * usage rolls up hourly, so a more frequent cycle re-reads the same numbers,
+ * and a less frequent one widens the window in which a runaway loop bills
+ * unchecked. One minute is the shortest interval at which every step is cheap.
+ */
+import type { AlertStore } from '../alerts';
+import type { ControlPlaneStore } from '../control-plane';
+import type { TelemetryRecord } from '../telemetry';
+import type { SpendEnforcementTransport } from './appliers';
+import type { EnforcementPolicy } from './enforcement';
+import type { EnforcementAction, SpendAnomaly, SpendDecision } from './model';
+import type { SpendStore } from './store';
+import { SpendGate } from './gate';
+import { SpendLoopLease } from './lease';
+import { SpendService } from './service';
+export interface SpendRunnerOptions {
+    controlPlane: ControlPlaneStore;
+    store: SpendStore;
+    /** Reuses the alert channels and routes an operator already configured. */
+    alerts?: AlertStore;
+    transport?: SpendEnforcementTransport;
+    policy?: EnforcementPolicy;
+    /** Days of hourly rollups to keep. Default 400, so year-over-year works. */
+    retentionDays?: number;
+    now?: () => Date;
+}
+export interface SpendRunnerScope {
+    organizationId: string;
+    projectId?: string;
+    environmentId?: string;
+    environmentKind?: string;
+}
+export interface SpendRunResult {
+    scope: SpendRunnerScope;
+    ingested: {
+        applied: number;
+        duplicates: number;
+        costCents: number;
+        unpricedMeters: string[];
+    };
+    decisions: SpendDecision[];
+    applied: EnforcementAction[];
+    released: EnforcementAction[];
+    failed: Array<{
+        action: EnforcementAction;
+        error: string;
+    }>;
+    withheld: EnforcementAction[];
+    anomalies: SpendAnomaly[];
+    notificationsSent: number;
+    ranAt: string;
+    durationMs: number;
+    /** Anything that went wrong without stopping the cycle. */
+    warnings: string[];
+}
+/**
+ * Runs one spend cycle for one scope.
+ *
+ * Every step is wrapped: a failure in notification must not stop enforcement,
+ * and a failure in anomaly detection must not stop either. The alternative -
+ * one throw aborting the cycle - means a broken Slack webhook disables the
+ * spend cap, which is precisely backwards.
+ */
+export declare class SpendRunner {
+    private readonly options;
+    readonly gate: SpendGate;
+    readonly service: SpendService;
+    private readonly notifications?;
+    constructor(options: SpendRunnerOptions);
+    private now;
+    /** Meter a telemetry batch. Safe to call from a collector on its own cadence. */
+    ingest(organizationId: string, records: readonly TelemetryRecord[], defaultProvider?: string): SpendRunResult['ingested'];
+    /**
+     * Run one full cycle.
+     *
+     * `telemetry` is optional: a deployment where collectors POST usage directly
+     * to the API has already ingested by the time this runs, and passing an
+     * empty batch simply skips step one.
+     */
+    run(scope: SpendRunnerScope, telemetry?: readonly TelemetryRecord[]): Promise<SpendRunResult>;
+    /**
+     * Drop gate entries whose budget is gone or disabled.
+     *
+     * This is the failure mode that would otherwise be invisible: a cap applied,
+     * then the budget deleted, leaves deployments blocked by a rule nobody can
+     * find. Reconciling here makes the gate converge on the budgets that exist.
+     */
+    reconcileGate(scope: SpendRunnerScope): EnforcementAction[];
+    /** Run every organization the control plane knows about. The cron entry point. */
+    runAll(telemetry?: readonly TelemetryRecord[]): Promise<SpendRunResult[]>;
+}
+/** How often the loop should run, in seconds. See the note at the top of the file. */
+export declare const SPEND_CYCLE_SECONDS = 60;
+/**
+ * Start the loop on an interval.
+ *
+ * Returns a stop function. Cycles never overlap: a slow cycle delays the next
+ * one rather than running two evaluations against the same usage, which would
+ * double-apply enforcement and double-notify.
+ */
+export interface SpendLoopOptions {
+    intervalSeconds?: number;
+    /**
+     * Only run when this lease can be held. Pass one whenever the loop might be
+     * started in more than one process - a dashboard server and a `spend:work`
+     * worker on the same box is the ordinary case.
+     */
+    lease?: SpendLoopLease;
+    /** Run one cycle immediately instead of waiting out the first interval. */
+    immediate?: boolean;
+    onResult?: (results: SpendRunResult[]) => void;
+    /** Called when a cycle was skipped because another process holds the lease. */
+    onSkip?: (holder: string) => void;
+    onError?: (error: unknown) => void;
+}
+export declare function startSpendLoop(runner: SpendRunner, options?: SpendLoopOptions): () => void;