@stacksjs/ts-cloud 0.7.105 → 0.7.109

package/dist/spend/anomaly-config.d.ts

@@ -0,0 +1,130 @@
+import type { ControlPlaneStore } from '../control-plane';
+import type { AnomalyOptions } from './anomaly';
+import type { AlertSeverity } from '../alerts';
+export type AnomalySensitivity = 'low' | 'medium' | 'high';
+/**
+ * Robust z-score thresholds per sensitivity.
+ *
+ * High is 2.5 rather than something dramatic: with a MAD-based score, 2.5 is
+ * already well outside ordinary variation, and going lower turns the detector
+ * into a random number generator on any noisy signal.
+ */
+export declare const SENSITIVITY_THRESHOLDS: Readonly<Record<AnomalySensitivity, number>>;
+export interface AnomalyConfig {
+    id: string;
+    organizationId: string;
+    projectId?: string;
+    environmentId?: string;
+    /** `cost`, a meter key, or a telemetry signal like `http.status.5xx`. */
+    signal: string;
+    enabled: boolean;
+    sensitivity: AnomalySensitivity;
+    /** Points per season. 24 for a daily shape, 168 for a weekly one. */
+    seasonLength: number;
+    /** Absolute change below which nothing is reported, in the signal's units. */
+    minAbsoluteDelta: number;
+    detectDrops: boolean;
+    severity: AlertSeverity;
+    version: number;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface AnomalySilence {
+    id: string;
+    organizationId: string;
+    projectId?: string;
+    signal?: string;
+    /** Glob against the route, e.g. `/webhooks/**`. */
+    routePattern?: string;
+    statusCode?: number;
+    reason: string;
+    actorId?: string;
+    /** Null means indefinite. A silence with no end is a decision, so it is recorded. */
+    expiresAt?: string;
+    createdAt: string;
+}
+/** Glob matcher, same tiny dialect the rate limiter uses. */
+export declare function routeMatches(pattern: string, route: string): boolean;
+export interface AnomalyCandidate {
+    signal: string;
+    route?: string;
+    statusCode?: number;
+}
+export interface CreateAnomalyConfigInput {
+    organizationId: string;
+    projectId?: string;
+    environmentId?: string;
+    signal: string;
+    enabled?: boolean;
+    sensitivity?: AnomalySensitivity;
+    seasonLength?: number;
+    minAbsoluteDelta?: number;
+    detectDrops?: boolean;
+    severity?: AlertSeverity;
+}
+export declare class AnomalyConfigStore {
+    private readonly controlPlane;
+    private readonly options;
+    constructor(controlPlane: ControlPlaneStore, options?: {
+        now?: () => Date;
+    });
+    private now;
+    private query;
+    /** Create or replace the config for a scope and signal. */
+    upsert(input: CreateAnomalyConfigInput): AnomalyConfig;
+    get(id: string): AnomalyConfig | undefined;
+    list(filter: {
+        organizationId: string;
+        projectId?: string;
+    }): AnomalyConfig[];
+    delete(id: string): boolean;
+    /**
+     * The detector options for a signal, honouring the most specific config.
+     *
+     * Falls back to the shipped preset when nothing is configured, so detection
+     * works out of the box and configuration is a refinement rather than a
+     * prerequisite.
+     */
+    optionsFor(scope: {
+        organizationId: string;
+        projectId?: string;
+        environmentId?: string;
+    }, signal: string): {
+        options: AnomalyOptions;
+        config?: AnomalyConfig;
+        enabled: boolean;
+    };
+    /**
+     * Silence a pattern.
+     *
+     * An empty matcher is refused. "Silence everything" is what disabling the
+     * config is for, and a silence that matches everything is indistinguishable
+     * from a broken detector when someone later asks why nothing fires.
+     */
+    silence(input: {
+        organizationId: string;
+        projectId?: string;
+        signal?: string;
+        routePattern?: string;
+        statusCode?: number;
+        reason: string;
+        actorId?: string;
+        expiresAt?: string;
+    }): AnomalySilence;
+    listSilences(filter: {
+        organizationId: string;
+        projectId?: string;
+        includeExpired?: boolean;
+    }): AnomalySilence[];
+    removeSilence(id: string): boolean;
+    /**
+     * Whether a candidate is silenced.
+     *
+     * Checked *before* detection runs, not after, so a silenced pattern costs no
+     * computation and never reaches the dashboard.
+     */
+    isSilenced(scope: {
+        organizationId: string;
+        projectId?: string;
+    }, candidate: AnomalyCandidate): AnomalySilence | undefined;
+}

package/dist/spend/anomaly-config.test.d.ts

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

package/dist/spend/anomaly.d.ts

@@ -0,0 +1,114 @@
+/**
+ * Anomaly detection for spend and traffic.
+ *
+ * The naive version of this - mean plus three standard deviations - does not
+ * survive contact with real infrastructure data, for two reasons:
+ *
+ *   1. **The mean is not robust.** One genuine incident poisons the baseline
+ *      for as long as it stays in the window, so the detector goes quiet
+ *      exactly when it matters. Median and MAD (median absolute deviation) are
+ *      unmoved by up to half the sample being garbage.
+ *   2. **Infrastructure data is seasonal.** Traffic at 3am Sunday is not
+ *      traffic at 3pm Tuesday. A flat baseline fires every weekday morning and
+ *      teaches everyone to ignore it. The baseline here is per-phase: an hour
+ *      is compared against the same hour on previous days.
+ *
+ * Two guards keep the noise down further: a warmup (no history, no verdict)
+ * and an absolute floor (a jump from $0.01 to $0.09 is 800% and worth nobody's
+ * pager).
+ */
+import type { AnomalyDirection } from './model';
+export interface SeriesPoint {
+    bucketStart: string;
+    value: number;
+}
+export interface AnomalyOptions {
+    /**
+     * Points per season. 24 for hourly data with a daily cycle (the default),
+     * 168 for hourly data with a weekly cycle.
+     */
+    seasonLength?: number;
+    /** Robust z-score above which a point is anomalous. Lower is more sensitive. */
+    threshold?: number;
+    /** Minimum same-phase observations before any verdict. Below this: warmup. */
+    minHistory?: number;
+    /**
+     * Absolute change below which nothing is reported, in the series' own units.
+     * This is what stops a rounding-error spike from paging anyone.
+     */
+    minAbsoluteDelta?: number;
+    /** Report drops as well as spikes. Off by default; a spend drop is good news. */
+    detectDrops?: boolean;
+    /** Score at which an anomaly is `critical` rather than `warning`. */
+    criticalThreshold?: number;
+}
+export interface AnomalyPoint {
+    bucketStart: string;
+    observed: number;
+    expected: number;
+    score: number;
+    direction: AnomalyDirection;
+    deltaPercent: number;
+    severity: 'info' | 'warning' | 'critical';
+    /** Same-phase observations the baseline was drawn from. */
+    historySize: number;
+    /** The robust spread of the baseline, in the series' units. */
+    deviation: number;
+}
+export interface AnomalyResult {
+    anomalies: AnomalyPoint[];
+    /** True when there was not enough history to judge anything. */
+    warmingUp: boolean;
+    /** Points evaluated (excludes those skipped for lack of history). */
+    evaluated: number;
+}
+export declare function median(values: readonly number[]): number;
+/**
+ * Median absolute deviation, scaled to be comparable to a standard deviation.
+ *
+ * The 1.4826 factor makes MAD a consistent estimator of sigma for normal data,
+ * so a threshold of 3 means roughly what it means for a classic z-score.
+ */
+export declare function medianAbsoluteDeviation(values: readonly number[], center?: number): number;
+/**
+ * Robust z-score.
+ *
+ * A MAD of zero means the history is perfectly flat - common for a meter that
+ * is usually idle. Falling back to a small fraction of the center keeps a real
+ * jump detectable without dividing by zero and calling everything infinite.
+ */
+export declare function robustZScore(value: number, history: readonly number[]): {
+    score: number;
+    center: number;
+    deviation: number;
+};
+/**
+ * Exponentially weighted moving average.
+ *
+ * Exposed because it is the right baseline for a series with a trend but no
+ * seasonality - a slowly growing storage meter, for instance.
+ */
+export declare function ewma(values: readonly number[], alpha?: number): number[];
+/**
+ * Find points that do not fit their own history.
+ *
+ * Returns anomalies in bucket order. Callers usually only act on the most
+ * recent one; the full list is what makes a backfill or a chart useful.
+ */
+export declare function detectAnomalies(series: readonly SeriesPoint[], options?: AnomalyOptions): AnomalyResult;
+/**
+ * Judge only the most recent point.
+ *
+ * This is the shape an evaluation loop wants: it runs every hour and only
+ * cares whether the hour that just closed was strange.
+ */
+export declare function detectLatestAnomaly(series: readonly SeriesPoint[], options?: AnomalyOptions): AnomalyPoint | undefined;
+/**
+ * Sensible option presets per signal class.
+ *
+ * Cost gets a floor of 25 cents because nobody wants to hear that a $0.02 hour
+ * became $0.30. Request counts get a much higher absolute floor for the same
+ * reason at a different scale, and a weekly season because request traffic has
+ * a strong weekday/weekend shape that a daily season would keep re-discovering.
+ */
+export declare function anomalyOptionsForSignal(signal: string): AnomalyOptions;

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

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

package/dist/spend/api.d.ts

@@ -0,0 +1,42 @@
+/**
+ * The billing and usage API.
+ *
+ * This exists so an *agent* can ask before it acts. The interesting question
+ * is not "what did last month cost" - a dashboard answers that - but "if I
+ * kick off this deploy, or this batch job, or this backfill, does it fit in
+ * what is left?" A CI pipeline, a scheduled job, or a coding agent can read
+ * `/api/v1/usage`, see the remaining headroom and the projection, and decide.
+ *
+ * Which is why every budget in the response carries `remainingCents`,
+ * `projectedCents`, `projectionConfidence`, and `timeToCap` rather than just a
+ * total: a caller deciding whether to proceed needs the forecast and how much
+ * to trust it, not an invoice.
+ *
+ * Routing lives here rather than in the main handler's if/else chain so the
+ * spend surface can be tested on its own.
+ */
+import type { ApiTokenPrincipal } from '../automation';
+import type { AutomationApiService } from '../api/service';
+import type { SpendService } from './service';
+import type { SpendStore } from './store';
+export interface SpendApiContext {
+    store: SpendStore;
+    service: SpendService;
+    /** Reused for scope resolution and capability checks. */
+    authorization: AutomationApiService;
+    now?: () => Date;
+}
+export interface SpendApiRequest {
+    method: string;
+    url: URL;
+    body?: () => Promise<Record<string, any>>;
+}
+/**
+ * Handle a spend route, or return undefined if the path is not one of ours.
+ *
+ * Returning undefined rather than a 404 lets the caller keep its own routing
+ * fallthrough intact.
+ */
+export declare function handleSpendRequest(context: SpendApiContext, principal: ApiTokenPrincipal, request: SpendApiRequest): Promise<Record<string, unknown> | undefined>;
+/** OpenAPI path entries for the spend surface, merged into the main document. */
+export declare function spendOpenApiPaths(): Record<string, unknown>;

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

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

package/dist/spend/appliers.d.ts

@@ -0,0 +1,126 @@
+/**
+ * Turning a decision into a real effect.
+ *
+ * Every applier does the same two things, in this order:
+ *
+ *   1. Write the gate (see `gate.ts`). This is what makes the cap true.
+ *   2. Ask a transport to make the traffic-facing change, if the action has one.
+ *
+ * Order matters. Gate first means a transport that times out still leaves the
+ * cap in force - the builds and deploys stop even if the edge did not get the
+ * message. The reverse order would leave a window where the edge is throttled
+ * but the control plane thinks nothing happened, and the next evaluation cycle
+ * would try to apply it again.
+ *
+ * Release runs the same two steps in reverse: restore the traffic path first,
+ * then open the gate. A caller that gets its service back before the gate
+ * opens is fine; the other way round would admit traffic to an edge still
+ * serving a 503.
+ */
+import type { JsonValue } from '../control-plane';
+import type { EnforcementApplier, EnforcementReleaser } from './enforcement';
+import type { EnforcementAction } from './model';
+import type { SpendGate } from './gate';
+/**
+ * What a driver must implement for the traffic-affecting actions.
+ *
+ * Deliberately small and provider-neutral: AWS does these through CloudFront
+ * and Lambda concurrency, a Hetzner box through rpx and systemd, and a test
+ * through a fake. Each method returns the state needed to undo it, because a
+ * cap that cannot be lifted is an outage.
+ */
+export interface SpendEnforcementTransport {
+    /** Apply an edge rate-limit multiplier. Returns the previous configuration. */
+    throttleRequests?(input: {
+        projectId?: string;
+        environmentId?: string;
+        factor: number;
+    }): Promise<Record<string, JsonValue>> | Record<string, JsonValue>;
+    restoreRequests?(restore: Record<string, JsonValue>): Promise<void> | void;
+    /** Stop invoking functions; cached and static responses keep serving. */
+    suspendFunctions?(input: {
+        projectId?: string;
+        environmentId?: string;
+    }): Promise<Record<string, JsonValue>> | Record<string, JsonValue>;
+    resumeFunctions?(restore: Record<string, JsonValue>): Promise<void> | void;
+    /** Serve only the last built static output. */
+    serveStatic?(input: {
+        projectId?: string;
+        environmentId?: string;
+    }): Promise<Record<string, JsonValue>> | Record<string, JsonValue>;
+    restoreDynamic?(restore: Record<string, JsonValue>): Promise<void> | void;
+    /** Park inbound traffic behind a 503. Never removes data. */
+    suspendProject?(input: {
+        projectId?: string;
+        environmentId?: string;
+    }): Promise<Record<string, JsonValue>> | Record<string, JsonValue>;
+    resumeProject?(restore: Record<string, JsonValue>): Promise<void> | void;
+}
+/** Called when an action fires, so notifications can go out. */
+export type SpendNotifier = (input: {
+    action: EnforcementAction;
+    budgetId: string;
+    reason: string;
+    simulated: boolean;
+    released: boolean;
+}) => Promise<void> | void;
+export interface EnforcementHandlerOptions {
+    gate: SpendGate;
+    transport?: SpendEnforcementTransport;
+    notify?: SpendNotifier;
+    /**
+     * Multiplier applied to rate limits when `throttle_requests` fires.
+     * Half by default: enough to stop a runaway, gentle enough that a real user
+     * mostly does not notice.
+     */
+    throttleFactor?: number;
+}
+/**
+ * Build the `{ apply, release }` pair that `runEnforcement` expects.
+ *
+ * Without a transport this still produces a fully working cap for builds,
+ * deploys, and notifications - the actions that need no box - and records the
+ * traffic-affecting ones in the gate so they are visible and reversible even
+ * though nothing at the edge changed. That is the honest degradation: the
+ * dashboard says what is in force, and `unsupported: true` in the restore
+ * payload says why it had no traffic effect.
+ */
+export declare function createEnforcementHandlers(options: EnforcementHandlerOptions): {
+    apply: EnforcementApplier;
+    release: EnforcementReleaser;
+};
+/**
+ * A transport that records calls instead of making them.
+ *
+ * Not only for tests: this is what a `--dry-run` cap run uses to show an
+ * operator exactly which traffic changes a budget would make, before it is
+ * allowed to make them.
+ */
+export declare class RecordingSpendTransport implements SpendEnforcementTransport {
+    readonly calls: Array<{
+        method: string;
+        input: unknown;
+    }>;
+    private record;
+    throttleRequests(input: {
+        projectId?: string;
+        environmentId?: string;
+        factor: number;
+    }): Record<string, JsonValue>;
+    restoreRequests(restore: Record<string, JsonValue>): void;
+    suspendFunctions(input: {
+        projectId?: string;
+        environmentId?: string;
+    }): Record<string, JsonValue>;
+    resumeFunctions(restore: Record<string, JsonValue>): void;
+    serveStatic(input: {
+        projectId?: string;
+        environmentId?: string;
+    }): Record<string, JsonValue>;
+    restoreDynamic(restore: Record<string, JsonValue>): void;
+    suspendProject(input: {
+        projectId?: string;
+        environmentId?: string;
+    }): Record<string, JsonValue>;
+    resumeProject(restore: Record<string, JsonValue>): void;
+}

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

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

package/dist/spend/enforcement.d.ts

@@ -0,0 +1,111 @@
+/**
+ * Applying and lifting a cap.
+ *
+ * The design rule is that **enforcement is always reversible and never
+ * destructive**. A budget's job is to stop the meter, not to lose anyone's
+ * work. So no action here deletes a resource, drops a database, or discards a
+ * build; the strongest rung parks traffic behind a static response and even
+ * that records exactly what it changed so the restore is mechanical.
+ *
+ * A second rule: **an enforcement action is a request, not a fact**. Applying
+ * one means talking to a driver, and drivers fail. Every record therefore
+ * moves pending -> active -> released with an explicit failed state, and a
+ * failure to apply never silently reads as "capped".
+ */
+import type { JsonValue } from '../control-plane';
+import type { Budget, EnforcementAction, EnforcementRecord, SpendDecision } from './model';
+import type { SpendStore } from './store';
+/** What an action does, in words an operator can act on. */
+export declare const ENFORCEMENT_DESCRIPTIONS: Readonly<Record<EnforcementAction, string>>;
+/**
+ * Actions that change what users see.
+ *
+ * These need an explicit opt-in on a production environment: silently taking a
+ * customer's site off the air to save $20 is worse than the bill.
+ */
+export declare const USER_VISIBLE_ACTIONS: readonly EnforcementAction[];
+export interface EnforcementStep {
+    action: EnforcementAction;
+    description: string;
+    userVisible: boolean;
+    /** True when policy blocks this step from running automatically. */
+    requiresApproval: boolean;
+    reason: string;
+}
+export interface EnforcementPlan {
+    budgetId: string;
+    simulated: boolean;
+    /** Steps to apply, least disruptive first. */
+    apply: EnforcementStep[];
+    /** Steps to lift, most disruptive first, so a scope recovers safely. */
+    release: EnforcementStep[];
+    /** Steps withheld pending human approval. */
+    withheld: EnforcementStep[];
+}
+export interface EnforcementPolicy {
+    /**
+     * Environment kinds where user-visible actions need approval rather than
+     * running on their own. Production is in this list by default.
+     */
+    approvalRequiredFor?: readonly string[];
+    /** The kind of the environment being enforced, e.g. `production`. */
+    environmentKind?: string;
+    /** Ceiling on automatic disruption; nothing above it applies unattended. */
+    maxAutomaticAction?: EnforcementAction;
+}
+/**
+ * Turn a decision into an ordered, approval-aware plan.
+ *
+ * Apply runs least-disruptive-first so the cheapest lever gets a chance to
+ * work before the expensive one. Release runs most-disruptive-first so a
+ * recovering project gets its traffic back before it gets its build queue.
+ */
+export declare function planEnforcement(decision: SpendDecision, policy?: EnforcementPolicy): EnforcementPlan;
+/** Applies one action against the platform. Returns whatever the release needs. */
+export type EnforcementApplier = (action: EnforcementAction, context: {
+    budget: Budget;
+    decision: SpendDecision;
+    record: EnforcementRecord;
+}) => Promise<Record<string, JsonValue>> | Record<string, JsonValue>;
+/** Undoes one action, given the restore payload the applier returned. */
+export type EnforcementReleaser = (action: EnforcementAction, context: {
+    budget: Budget;
+    record: EnforcementRecord;
+    restore: Record<string, JsonValue>;
+}) => Promise<void> | void;
+export interface EnforcementRunResult {
+    applied: EnforcementRecord[];
+    released: EnforcementRecord[];
+    failed: Array<{
+        action: EnforcementAction;
+        error: string;
+    }>;
+    withheld: EnforcementStep[];
+    simulated: boolean;
+}
+/**
+ * Run a plan against the store, calling out to the driver for each step.
+ *
+ * A dry-run budget records everything and calls nothing, which is the point:
+ * an operator can watch a cap for a month before letting it touch anything.
+ * A step whose applier throws lands in `failed` and its record in `failed`
+ * state - the caller can retry next cycle, and nothing pretends the cap is on.
+ */
+export declare function runEnforcement(store: SpendStore, budget: Budget, decision: SpendDecision, plan: EnforcementPlan, handlers: {
+    apply: EnforcementApplier;
+    release: EnforcementReleaser;
+}): Promise<EnforcementRunResult>;
+/** The strongest action currently in force for a scope, if any. */
+export declare function strongestActiveAction(records: readonly EnforcementRecord[]): EnforcementAction | undefined;
+/**
+ * Whether an operation is allowed right now.
+ *
+ * The gate every caller should ask before starting work that costs money. It
+ * fails *open* on an unknown operation: a cap should never block something it
+ * was not designed to reason about.
+ */
+export declare function isOperationAllowed(operation: 'build' | 'deploy' | 'function_invoke' | 'request', active: readonly EnforcementRecord[]): {
+    allowed: boolean;
+    blockedBy?: EnforcementAction;
+    reason?: string;
+};

package/dist/spend/enforcement.integration.test.d.ts

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

package/dist/spend/evaluator.d.ts

@@ -0,0 +1,70 @@
+/**
+ * The cap evaluator: budget + usage in, decision out.
+ *
+ * Pure and clock-injected, so every rung of the ladder is testable without a
+ * database or a real month passing. The store applies the result; this file
+ * only decides.
+ *
+ * Three details are what separate a usable cap from an annoying one:
+ *
+ *   - **Hysteresis.** A scope parked on the line would otherwise enforce and
+ *     release every evaluation cycle, paging someone each time. An action is
+ *     only lifted once spend drops a configured margin below its trigger.
+ *   - **Grace.** A single spiky minute should not suspend production. A breach
+ *     must persist for `graceSeconds` before enforcement runs; notifications
+ *     still fire immediately, because a warning has no blast radius.
+ *   - **Confidence.** Projection-based rungs are ignored while the forecast is
+ *     still noise. Enforcing on ten minutes of extrapolation is how you take a
+ *     site down over nothing.
+ */
+import type { Budget, BudgetWindow, EnforcementAction, SpendDecision, SpendLevel } from './model';
+/** Below this confidence a forecast cannot trigger anything but a notification. */
+export declare const MIN_PROJECTION_CONFIDENCE = 0.35;
+export interface EvaluateInput {
+    budget: Budget;
+    window: BudgetWindow;
+    /** Spend so far in the window, cents. */
+    actualCents: number;
+    series?: ReadonlyArray<{
+        bucketStart: string;
+        costCents: number;
+    }>;
+    /** Actions currently in force, so the evaluator can decide what to release. */
+    activeActions?: readonly EnforcementAction[];
+    /**
+     * When the current breach was first observed. Grace is measured from here.
+     *
+     * Omitting it on a budget with a grace period means "first seen now", so the
+     * first cycle of a breach never enforces. That is the safe reading: a caller
+     * that is not tracking the clock has no way to know the breach has lasted.
+     */
+    breachingSince?: string;
+    now?: Date;
+}
+/**
+ * The limit a budget's percentages are measured against.
+ *
+ * The hard limit governs when there is one, so a ladder written as "100% =
+ * block deploys" means the same thing whether or not a soft limit exists.
+ */
+export declare function governingLimitCents(budget: Budget): number | undefined;
+/**
+ * Evaluate one budget.
+ *
+ * The returned `actions` are what *should* be in force; `releases` are actions
+ * currently in force that should not be. A caller that applies both converges
+ * on the right state no matter how many cycles it missed.
+ */
+export declare function evaluateBudget(input: EvaluateInput): SpendDecision;
+/**
+ * Combine decisions for overlapping budgets on one scope.
+ *
+ * The strictest wins: an org-wide cap must not be loosened by a permissive
+ * project budget, and an environment cap must be able to tighten. Releases only
+ * survive if no other budget still wants the action.
+ */
+export declare function mergeDecisions(decisions: readonly SpendDecision[]): {
+    actions: EnforcementAction[];
+    releases: EnforcementAction[];
+    level: SpendLevel;
+};

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

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