@stacksjs/ts-cloud 0.7.108 → 0.7.110

package/dist/spend/focus.d.ts

@@ -0,0 +1,93 @@
+/**
+ * FOCUS export: cost data in the shape FinOps tools already read.
+ *
+ * FOCUS (FinOps Open Cost and Usage Specification) is the interchange format
+ * Vantage, CloudZero, and the rest ingest. Emitting it matters more than it
+ * looks: without it, every team wanting cost observability writes a bespoke
+ * transformer against our column names, and that transformer breaks the first
+ * time we add a meter.
+ *
+ * Two deliberate choices:
+ *
+ *   - **Newline-delimited JSON**, not an array. A year of hourly rollups is
+ *     large, and a consumer should be able to stream it without holding the
+ *     whole export in memory - which also means we can generate it without
+ *     doing so either.
+ *   - **Daily granularity by default.** FOCUS consumers expect a billing
+ *     period grain, and an hourly export is ~24x the rows for detail nobody
+ *     reconciles against an invoice. Hourly stays available for our own API.
+ */
+import type { UsageRollup } from './model';
+/** The specification version these rows conform to. */
+export declare const FOCUS_VERSION = "1.3";
+/**
+ * A FOCUS billing record.
+ *
+ * Column names are the specification's, not ours - that is the whole point.
+ * Only the columns we can populate honestly are emitted; inventing a
+ * `ContractedCost` we do not know would be worse than omitting it.
+ */
+export interface FocusRecord {
+    /** Specification version, so a consumer can branch on it. */
+    FocusVersion: string;
+    /** Inclusive start of the charge period, ISO-8601. */
+    ChargePeriodStart: string;
+    /** Exclusive end. */
+    ChargePeriodEnd: string;
+    BillingPeriodStart: string;
+    BillingPeriodEnd: string;
+    BillingCurrency: string;
+    /** What the customer is billed. We report our estimate. */
+    BilledCost: number;
+    /** Amortized cost. Identical to billed here: we model no commitments. */
+    EffectiveCost: number;
+    ListCost: number;
+    ChargeCategory: 'Usage';
+    ChargeDescription: string;
+    /** `AWS`, `Hetzner`, or whatever the meter was attributed to. */
+    ProviderName: string;
+    PublisherName: string;
+    InvoiceIssuerName: string;
+    ServiceName: string;
+    ServiceCategory: string;
+    /** Our meter key, so a consumer can map back to what we measured. */
+    SkuId: string;
+    PricingUnit: string;
+    PricingQuantity: number;
+    ConsumedQuantity: number;
+    ConsumedUnit: string;
+    RegionId?: string;
+    ResourceId?: string;
+    /** The project and environment, so cost splits the way teams are organized. */
+    SubAccountId?: string;
+    SubAccountName?: string;
+    Tags: Record<string, string>;
+}
+export interface FocusExportOptions {
+    /** Billing period the rows belong to. */
+    billingPeriodStart: string;
+    billingPeriodEnd: string;
+    currency?: string;
+    /** `daily` (the FOCUS norm) or `hourly` (our native grain). */
+    granularity?: 'hourly' | 'daily';
+    /** Names for the sub-account column, keyed by project id. */
+    projectNames?: Record<string, string>;
+}
+/**
+ * Convert rollups into FOCUS records.
+ *
+ * Rows are aggregated to the requested grain first. Emitting one record per
+ * rollup at daily granularity would produce 24 rows per day per meter that a
+ * consumer then has to sum, which defeats the point of choosing a grain.
+ */
+export declare function toFocusRecords(rollups: readonly UsageRollup[], options: FocusExportOptions): FocusRecord[];
+/** Serialize to newline-delimited JSON, one record per line. */
+export declare function toFocusJsonl(records: readonly FocusRecord[]): string;
+/**
+ * Stream the export.
+ *
+ * A year at hourly grain is hundreds of thousands of rows; building one string
+ * would hold the whole export in memory on both ends. The chunking is by
+ * record count rather than bytes because a consumer reads lines, not bytes.
+ */
+export declare function streamFocusJsonl(records: readonly FocusRecord[], chunkSize?: number): Generator<string>;

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

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

package/dist/spend/gate.d.ts

@@ -0,0 +1,96 @@
+/**
+ * The spend gate: what "capped" actually means to the rest of the platform.
+ *
+ * The naive way to apply a cap is for each enforcement action to reach into
+ * the subsystem it affects and switch something off. That fails in three ways
+ * this design avoids:
+ *
+ *   1. **It is not crash-safe.** A cap applied by mutating in-memory state
+ *      quietly lifts itself the next time the control plane restarts, which is
+ *      exactly when a runaway workload is least supervised.
+ *   2. **It couples every action to a driver.** `block_builds` would need SSH
+ *      to a box to mean anything, so it could not be tested, and a driver
+ *      outage would read as "not capped".
+ *   3. **It has no single answer.** With state spread across five subsystems,
+ *      "is this project capped?" has five answers that drift.
+ *
+ * Instead, enforcement writes one durable record - the gate - into the control
+ * plane, and the subsystems that spend money *read* it before acting. The gate
+ * is the source of truth; a driver call is an additional, best-effort effect
+ * on top of it. So a driver that fails leaves the cap in force rather than
+ * silently open, and lifting a cap is a delete rather than an undo.
+ */
+import type { ControlPlaneStore } from '../control-plane';
+import type { EnforcementAction } from './model';
+/** Operations the gate can refuse. */
+export type GatedOperation = 'build' | 'deploy' | 'function_invoke' | 'request';
+/** Control-plane setting key holding every live gate entry. */
+export declare const SPEND_GATE_SETTING = "spend.gates";
+export interface SpendGateEntry {
+    budgetId: string;
+    action: EnforcementAction;
+    organizationId: string;
+    projectId?: string;
+    environmentId?: string;
+    reason: string;
+    /** A simulated entry is recorded and reported but never refuses anything. */
+    simulated: boolean;
+    appliedAt: string;
+}
+export interface GateVerdict {
+    allowed: boolean;
+    action?: EnforcementAction;
+    reason?: string;
+    budgetId?: string;
+}
+type Scope = {
+    organizationId: string;
+    projectId?: string;
+    environmentId?: string;
+};
+export declare class SpendGate {
+    private readonly controlPlane;
+    private readonly options;
+    constructor(controlPlane: ControlPlaneStore, options?: {
+        now?: () => Date;
+    });
+    private read;
+    private write;
+    /** Entries governing a scope - equal or broader. Most disruptive first. */
+    list(scope?: Scope): SpendGateEntry[];
+    /**
+     * Entries under a scope - equal or narrower.
+     *
+     * What a dashboard and a reconcile pass want: everything an organization has
+     * in force, including its projects' own caps.
+     */
+    listUnder(scope: Scope): SpendGateEntry[];
+    /** Record an action as in force. Idempotent on (budget, action). */
+    open(entry: Omit<SpendGateEntry, 'appliedAt'> & {
+        appliedAt?: string;
+    }): SpendGateEntry;
+    /** Lift an action. Returns false when it was not in force. */
+    close(budgetId: string, action: EnforcementAction): boolean;
+    /** Lift every action for a budget. Used when a budget is deleted or disabled. */
+    closeBudget(budgetId: string): number;
+    /**
+     * The question every spending caller should ask.
+     *
+     * Fails open for an operation the gate has no rule about: a cap must never
+     * block something it was not designed to reason about.
+     */
+    check(operation: GatedOperation, scope: Scope): GateVerdict;
+    /** The strongest action in force for a scope, ignoring simulated entries. */
+    strongest(scope: Scope): EnforcementAction | undefined;
+}
+/** Raised when a spend cap refuses an operation. Carries a 402 for the API. */
+export declare class SpendCapError extends Error {
+    readonly operation: GatedOperation;
+    readonly verdict: GateVerdict;
+    readonly code = "spend_cap_exceeded";
+    readonly status = 402;
+    constructor(operation: GatedOperation, verdict: GateVerdict);
+}
+/** Throw unless the gate allows the operation. The one-liner for a call site. */
+export declare function assertSpendAllows(gate: SpendGate, operation: GatedOperation, scope: Scope): void;
+export {};

package/dist/spend/index.d.ts

@@ -0,0 +1,20 @@
+export * from './model';
+export * from './pricing';
+export * from './window';
+export * from './meter';
+export * from './store';
+export * from './projection';
+export * from './evaluator';
+export * from './enforcement';
+export * from './anomaly';
+export * from './anomaly-config';
+export * from './signals';
+export * from './focus';
+export * from './service';
+export * from './gate';
+export * from './appliers';
+export * from './notifications';
+export * from './lease';
+export * from './runner';
+export * from './transports';
+export * from './api';

package/dist/spend/index.js

@@ -0,0 +1,173 @@
+import {
+  AnomalyConfigStore,
+  AwsSpendTransport,
+  ComputeSpendTransport,
+  CounterTracker,
+  DEFAULT_METER_MAPPINGS,
+  DEFAULT_PRICE_BOOK,
+  DEFAULT_THRESHOLDS,
+  DETECTABLE_SIGNALS,
+  ENFORCEMENT_ACTIONS,
+  ENFORCEMENT_DESCRIPTIONS,
+  ENFORCEMENT_SEVERITY,
+  FOCUS_VERSION,
+  METERS,
+  METER_KEYS,
+  MICRO_CENTS,
+  MIN_PROJECTION_CONFIDENCE,
+  RecordingSpendTransport,
+  SENSITIVITY_THRESHOLDS,
+  SPEND_CYCLE_SECONDS,
+  SPEND_GATE_SETTING,
+  SPEND_LEASE_SETTING,
+  SignalSource,
+  SpendCapError,
+  SpendGate,
+  SpendLoopLease,
+  SpendNotificationRouter,
+  SpendRunner,
+  SpendService,
+  SpendStore,
+  URGENT_SPEND_EVENTS,
+  USER_VISIBLE_ACTIONS,
+  aggregateDeltas,
+  anomalyOptionsForSignal,
+  assertSpendAllows,
+  budgetWindow,
+  compositeSpendTransport,
+  createEnforcementHandlers,
+  detectAnomalies,
+  detectLatestAnomaly,
+  evaluateBudget,
+  ewma,
+  findMapping,
+  findPriceEntry,
+  formatCents,
+  formatTimeToExhaustion,
+  governingLimitCents,
+  handleSpendRequest,
+  hourBucket,
+  hourBucketsBetween,
+  isOperationAllowed,
+  isValidTimeZone,
+  lookbackHoursForSignal,
+  median,
+  medianAbsoluteDeviation,
+  mergeDecisions,
+  mergePriceBooks,
+  meterTelemetry,
+  optionsForSignal,
+  percentOfLimit,
+  planEnforcement,
+  previousBudgetWindow,
+  priceUsage,
+  priceUsageLines,
+  projectSpend,
+  robustZScore,
+  roundCents,
+  routeMatches,
+  runEnforcement,
+  scopeKey,
+  signalDefinition,
+  spendNotificationText,
+  spendOpenApiPaths,
+  startSpendLoop,
+  streamFocusJsonl,
+  strongestActiveAction,
+  tieredMicroCents,
+  toFocusJsonl,
+  toFocusRecords,
+  usageDeltaKey,
+  utcInstantOfLocal,
+  zeroFill,
+  zoneOffsetMs,
+  zonedParts
+} from "../chunk-19bs955w.js";
+import"../chunk-aa2dkn7b.js";
+import"../chunk-t2s3gdq6.js";
+import"../chunk-v0bahtg2.js";
+export {
+  zonedParts,
+  zoneOffsetMs,
+  zeroFill,
+  utcInstantOfLocal,
+  usageDeltaKey,
+  toFocusRecords,
+  toFocusJsonl,
+  tieredMicroCents,
+  strongestActiveAction,
+  streamFocusJsonl,
+  startSpendLoop,
+  spendOpenApiPaths,
+  spendNotificationText,
+  signalDefinition,
+  scopeKey,
+  runEnforcement,
+  routeMatches,
+  roundCents,
+  robustZScore,
+  projectSpend,
+  priceUsageLines,
+  priceUsage,
+  previousBudgetWindow,
+  planEnforcement,
+  percentOfLimit,
+  optionsForSignal,
+  meterTelemetry,
+  mergePriceBooks,
+  mergeDecisions,
+  medianAbsoluteDeviation,
+  median,
+  lookbackHoursForSignal,
+  isValidTimeZone,
+  isOperationAllowed,
+  hourBucketsBetween,
+  hourBucket,
+  handleSpendRequest,
+  governingLimitCents,
+  formatTimeToExhaustion,
+  formatCents,
+  findPriceEntry,
+  findMapping,
+  ewma,
+  evaluateBudget,
+  detectLatestAnomaly,
+  detectAnomalies,
+  createEnforcementHandlers,
+  compositeSpendTransport,
+  budgetWindow,
+  assertSpendAllows,
+  anomalyOptionsForSignal,
+  aggregateDeltas,
+  USER_VISIBLE_ACTIONS,
+  URGENT_SPEND_EVENTS,
+  SpendStore,
+  SpendService,
+  SpendRunner,
+  SpendNotificationRouter,
+  SpendLoopLease,
+  SpendGate,
+  SpendCapError,
+  SignalSource,
+  SPEND_LEASE_SETTING,
+  SPEND_GATE_SETTING,
+  SPEND_CYCLE_SECONDS,
+  SENSITIVITY_THRESHOLDS,
+  RecordingSpendTransport,
+  MIN_PROJECTION_CONFIDENCE,
+  MICRO_CENTS,
+  METER_KEYS,
+  METERS,
+  FOCUS_VERSION,
+  ENFORCEMENT_SEVERITY,
+  ENFORCEMENT_DESCRIPTIONS,
+  ENFORCEMENT_ACTIONS,
+  DETECTABLE_SIGNALS,
+  DEFAULT_THRESHOLDS,
+  DEFAULT_PRICE_BOOK,
+  DEFAULT_METER_MAPPINGS,
+  CounterTracker,
+  ComputeSpendTransport,
+  AwsSpendTransport,
+  AnomalyConfigStore
+};

package/dist/spend/lease.d.ts

@@ -0,0 +1,54 @@
+/**
+ * A lease, so only one process runs the spend loop at a time.
+ *
+ * The loop is started in more than one place by design - the dashboard server
+ * runs it, and `cloud spend:work` runs it standalone - so two of them
+ * overlapping is a configuration people will actually reach.
+ *
+ * Most of the damage is already prevented downstream: the gate is idempotent on
+ * (budget, action), enforcement records have a unique index on live rows, and
+ * notification deliveries dedupe on their idempotency key. What a lease adds is
+ * avoiding the *work*: two processes evaluating every budget every minute
+ * doubles the database traffic and the provider calls that enforcement makes,
+ * and provider calls are rate-limited and occasionally billed.
+ *
+ * It is an advisory lease with a TTL, not a distributed lock. A process that
+ * dies holding one blocks the loop for at most `ttlSeconds`, which is the right
+ * trade: a stalled cap for a minute is better than a lock nobody can clear.
+ */
+import type { ControlPlaneStore } from '../control-plane';
+export declare const SPEND_LEASE_SETTING = "spend.loop.lease";
+export interface SpendLeaseState {
+    owner: string;
+    acquiredAt: string;
+    expiresAt: string;
+}
+export interface SpendLeaseOptions {
+    /** Identifies the holder in the record. A hostname and pid is ideal. */
+    owner?: string;
+    /** How long a held lease stays valid without renewal. */
+    ttlSeconds?: number;
+    now?: () => Date;
+}
+export declare class SpendLoopLease {
+    private readonly controlPlane;
+    readonly owner: string;
+    private readonly ttlMs;
+    constructor(controlPlane: ControlPlaneStore, options?: SpendLeaseOptions);
+    private readonly nowFn;
+    private read;
+    /** The current holder, or undefined when the lease is free or expired. */
+    current(): SpendLeaseState | undefined;
+    /**
+     * Take or renew the lease.
+     *
+     * Read and write happen inside one transaction, because two processes doing
+     * read-then-write outside one would both see it free and both take it -
+     * which is the exact race the lease exists to prevent.
+     */
+    acquire(): boolean;
+    /** Give the lease up. Only the holder may, so a late release cannot steal it. */
+    release(): boolean;
+    /** True when this process currently holds it. */
+    held(): boolean;
+}

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

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

package/dist/spend/meter.d.ts

@@ -0,0 +1,70 @@
+import type { TelemetryRecord } from '../telemetry';
+import type { MeterKey, UsageDelta } from './model';
+/** A rule mapping a telemetry signal onto a meter. */
+export interface MeterMapping {
+    /** Telemetry `name` to match, or a prefix when it ends with `*`. */
+    match: string;
+    meter: MeterKey;
+    /** Which field carries the quantity. `value` is the default. */
+    field?: 'value' | 'bytesOut' | 'bytesIn' | 'durationMs' | 'count';
+    /** Multiply the raw field by this to reach the meter's unit. */
+    scale?: number;
+    /**
+     * The signal is a monotonically increasing counter and must be differenced.
+     * Anything an agent reports as a running period total needs this.
+     */
+    cumulative?: boolean;
+}
+/**
+ * Default mappings against the signal names the platform already emits.
+ *
+ * `request.count` and `traffic.requests` both exist because the edge collector
+ * and the dashboard's own instrumentation grew up separately; mapping both is
+ * cheaper and less brittle than renaming a signal that operators' dashboards
+ * already query.
+ */
+export declare const DEFAULT_METER_MAPPINGS: readonly MeterMapping[];
+export declare function findMapping(name: string, mappings?: readonly MeterMapping[]): MeterMapping | undefined;
+/** Stable id for a delta, so replaying the same record is a no-op in the store. */
+export declare function usageDeltaKey(delta: UsageDelta, sourceId: string): string;
+/**
+ * Difference monotonic counters into deltas.
+ *
+ * `/proc/net/dev` style counters reset on reboot and wrap on 32-bit interfaces.
+ * A naive subtraction turns either into a hugely negative delta - or, worse,
+ * a caller who clamps at zero silently loses the usage. The rule used here: a
+ * value lower than the last one means the counter restarted, so the new value
+ * *is* the delta. That over-counts by at most one scrape interval and never
+ * under-counts, which is the right direction for something guarding a budget.
+ */
+export declare class CounterTracker {
+    private readonly resetToleranceRatio;
+    private readonly last;
+    constructor(resetToleranceRatio?: number);
+    /** Returns the increment to bill, or undefined when there is nothing new. */
+    delta(key: string, value: number, at?: Date | string): number | undefined;
+    /** Drop tracked counters not seen since `before`, so a retired host stops holding memory. */
+    prune(before: Date): number;
+    get size(): number;
+}
+export interface MeteredDelta extends UsageDelta {
+    /** Deterministic idempotency key. */
+    key: string;
+}
+export interface MeterOptions {
+    mappings?: readonly MeterMapping[];
+    /** Shared across calls so cumulative counters difference correctly over time. */
+    counters?: CounterTracker;
+    /** Fallback when a record carries no provider attribute. */
+    defaultProvider?: string;
+}
+/**
+ * Convert telemetry records into usage deltas.
+ *
+ * Records that map to no meter are skipped silently - the telemetry stream
+ * carries far more than billing cares about, and warning on each would drown
+ * the log.
+ */
+export declare function meterTelemetry(organizationId: string, records: readonly TelemetryRecord[], options?: MeterOptions): MeteredDelta[];
+/** Collapse deltas that share a scope, meter, and hour. Fewer rows, same total. */
+export declare function aggregateDeltas(deltas: readonly UsageDelta[]): UsageDelta[];

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

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