@stigg/agent-sdk-js 0.0.0-stage → 1.0.0

package/dist/core/dimensions.js

@@ -0,0 +1,47 @@
+"use strict";
+/**
+ * The vendor's usage object, reduced to something an event can carry.
+ *
+ * Stigg dimensions are a flat map of scalars, so a nested object has to be flattened or dropped -
+ * there is no third option, and stringifying a subtree would put something no meter can aggregate
+ * into a field a meter is meant to read.
+ *
+ * Everything here is a limit rather than a translation, because the input is not ours: a vendor
+ * adds fields whenever it likes, and this runs on every metered call. Depth, count and type are
+ * all capped so a response that grows a large nested block cannot grow the event with it.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RAW_PREFIX = void 0;
+exports.flattenRaw = flattenRaw;
+/** Prefix for everything read off the vendor's object, so it can never shadow a metric. */
+exports.RAW_PREFIX = 'raw.';
+const MAX_DEPTH = 2;
+const MAX_KEYS = 32;
+const isScalar = (value) => typeof value === 'string' || typeof value === 'boolean' || (typeof value === 'number' && Number.isFinite(value));
+/**
+ * The vendor's own usage block as event dimensions, `raw.`-prefixed and flattened with dotted keys.
+ *
+ * Fractions are kept: an event states what the vendor said and a meter is free to sum decimals,
+ * which is the one place a gateway's `cost` can be reported honestly. `null`, `undefined`, arrays
+ * and anything past the depth cap are dropped rather than coerced - a zero that was never reported
+ * is worse than a counter that is absent.
+ */
+function flattenRaw(raw) {
+    if (!raw)
+        return {};
+    const flat = {};
+    const walk = (node, path, depth) => {
+        for (const [key, value] of Object.entries(node)) {
+            if (Object.keys(flat).length >= MAX_KEYS)
+                return;
+            const name = path ? `${path}.${key}` : key;
+            if (isScalar(value))
+                flat[`${exports.RAW_PREFIX}${name}`] = value;
+            else if (depth < MAX_DEPTH && value && typeof value === 'object' && !Array.isArray(value)) {
+                walk(value, name, depth + 1);
+            }
+        }
+    };
+    walk(raw, '', 0);
+    return flat;
+}

package/dist/core/hooks.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Running an application's own callbacks, where their failure must not become the caller's.
+ *
+ * Hooks are instrumentation. One that throws has told us something went wrong with the watching,
+ * not with the work - so it cannot be allowed to fail a decision, flip a delivered ingest, or
+ * escape a promise the contract says never rejects. It cannot be ignored either, which is what a
+ * bare `try {} catch {}` amounts to.
+ *
+ * Shared, because every path that calls one has to get this right the same way, and the ones that
+ * reimplemented it are exactly the ones that got it wrong.
+ */
+/** Whether a callback typed `=> void` actually handed back something to wait on. */
+export declare function isThenable(value: unknown): value is PromiseLike<unknown>;
+/**
+ * Invokes a callback and routes its failure to `onFailure`, synchronous or not.
+ *
+ * The types say `void`, but nothing stops an application writing `async onIngest` - and a
+ * rejection there would otherwise surface as an unhandled one, which on Node's default takes the
+ * process down over instrumentation.
+ */
+export declare function safely(invoke: () => unknown, onFailure: (err: unknown) => void): void;

package/dist/core/hooks.js

@@ -0,0 +1,47 @@
+"use strict";
+/**
+ * Running an application's own callbacks, where their failure must not become the caller's.
+ *
+ * Hooks are instrumentation. One that throws has told us something went wrong with the watching,
+ * not with the work - so it cannot be allowed to fail a decision, flip a delivered ingest, or
+ * escape a promise the contract says never rejects. It cannot be ignored either, which is what a
+ * bare `try {} catch {}` amounts to.
+ *
+ * Shared, because every path that calls one has to get this right the same way, and the ones that
+ * reimplemented it are exactly the ones that got it wrong.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isThenable = isThenable;
+exports.safely = safely;
+/** Whether a callback typed `=> void` actually handed back something to wait on. */
+function isThenable(value) {
+    return typeof value?.then === 'function';
+}
+/**
+ * Invokes a callback and routes its failure to `onFailure`, synchronous or not.
+ *
+ * The types say `void`, but nothing stops an application writing `async onIngest` - and a
+ * rejection there would otherwise surface as an unhandled one, which on Node's default takes the
+ * process down over instrumentation.
+ */
+function safely(invoke, onFailure) {
+    // The reporter is the application's code too - an `onError` that throws, a logger that throws
+    // while saying so. Losing the report is the last acceptable failure here; letting it escape
+    // would fail the work the callback was only watching.
+    const report = (err) => {
+        try {
+            onFailure(err);
+        }
+        catch {
+            // Nowhere left to report to.
+        }
+    };
+    try {
+        const returned = invoke();
+        if (isThenable(returned))
+            void Promise.resolve(returned).catch(report);
+    }
+    catch (err) {
+        report(err);
+    }
+}

package/dist/core/session.d.ts

@@ -0,0 +1,161 @@
+import { EngineError } from '../errors';
+import { type GovernanceHeaders } from '../headers';
+import { type ResolvedContext } from './context';
+import type { GovernanceEngine } from '../engine/engine';
+import type { ErrorContext } from '../config';
+import type { Logger } from '../logger';
+import { type GovernanceDecision, type IngestResult, type Measurement, type Metrics, type TokenUsage } from '../types';
+/** Everything the session reports back while it works. Set once, at `wrap`. */
+export type SessionHooks = {
+    /** Every check this client makes. The whole decision, already formatted as `.summary`. */
+    onDecision?: (decision: GovernanceDecision) => void;
+    /** Every ingest this client makes - including the ones that failed. */
+    onIngest?: (result: IngestResult) => void;
+};
+export type SessionDeps = {
+    /**
+     * Resolved at the point of use, not at construction.
+     *
+     * Building the engine is a network round trip - a probe that decides which transport serves
+     * which operation - and `wrap` is a setup call that reads as instant. So it starts that work
+     * and hands the session the promise: the first call that needs an engine awaits it, and every
+     * call after that gets one already resolved. The latency moves to the first request rather
+     * than disappearing.
+     */
+    engine: () => Promise<GovernanceEngine>;
+    logger: Logger;
+    onError: (error: EngineError, context: ErrorContext) => void;
+    hooks: SessionHooks;
+};
+/** What a client did, for whoever wants to print it. Spans every context it served. */
+export type GovernanceSummary = {
+    checks: number;
+    ingested: number;
+    /**
+     * Everything this client reported, summed per feature id - what it sent, not what it was billed.
+     *
+     * Under `'sync'` Stigg says whether a delivery was a replay, and a replay is left out: it
+     * consumed nothing. Under `'async'` it cannot say, so a retry Stigg deduplicated still counts
+     * here. Stigg remains the record of what was actually charged; this is the client's own tally.
+     */
+    reported: Metrics;
+    ingestFailures: number;
+    lastDecision?: GovernanceDecision;
+};
+export type IngestOptions = {
+    /** Overrides the context's own name for this one report - the vendor method that was gated. */
+    event?: {
+        name: string;
+    };
+    /** The vendor's usage object, for the event to carry. Ignored under `'sync'`. */
+    raw?: Record<string, unknown>;
+    /**
+     * What deduplicates this report. Overrides the context's own, and is what a caller reaches for
+     * when one logical turn is reported twice - a retry, or a resumed stream.
+     */
+    idempotencyKey?: string;
+};
+export declare class GovernanceSession {
+    private readonly deps;
+    private readonly pending;
+    private readonly reported;
+    private checks;
+    private ingested;
+    private ingestFailures;
+    private step;
+    private decision?;
+    /** The unmapped-feature warning is said once per client, not once per call. */
+    private warnedUnmapped;
+    constructor(deps: SessionDeps);
+    get lastDecision(): GovernanceDecision | undefined;
+    /** The attribution to send downstream when part of the work happens in another process. */
+    headers(context: ResolvedContext): GovernanceHeaders;
+    /**
+     * Primes the cache that actually serves these checks, so the calls that follow read local state.
+     *
+     * It primes the *engine's* cache, not one here - there isn't one. The engine loads the
+     * customer's whole entitlement state, so every entitlement is warm rather than one decision,
+     * and each check is still evaluated against the amount it actually asks for. An engine with no
+     * cache (the governance REST client) implements nothing and this is a no-op, which is the
+     * honest answer: there would be nothing for the round trip to fill.
+     *
+     * Failures are logged rather than thrown: the client works either way, and the first real check
+     * applies the error policy.
+     */
+    warmUp(context: ResolvedContext): Promise<void>;
+    /**
+     * The enforcement path. Returns a decision, never throws - a refusal is a commercial event the
+     * application routes on, not an exception it recovers from.
+     */
+    check(context: ResolvedContext, requestedUsage?: number): Promise<GovernanceDecision>;
+    /** Applies the context's mapper to a token measurement. The path every binding uses. */
+    ingestTokens(context: ResolvedContext, usage: TokenUsage, options?: IngestOptions): Promise<IngestResult>;
+    /**
+     * Ingests whatever a binding measured, through the context's mapper.
+     *
+     * The mapper runs inside the boundary that never throws, because it is the application's own
+     * function over a vendor's object and either half is free to change shape - a throw there would
+     * put an exception where the contract promises a result.
+     */
+    ingestMeasurement(context: ResolvedContext, measurement: Measurement | TokenUsage, options?: IngestOptions): Promise<IngestResult>;
+    /**
+     * Reports one value against the entitlement this context checks.
+     *
+     * The narrow case, and the only one where the SDK knows what a report costs the budget it gates
+     * on - which is why it is also the only one that can name the feature for you.
+     */
+    ingest(context: ResolvedContext, value: number, options?: IngestOptions): Promise<IngestResult>;
+    /**
+     * Reports named metrics directly, skipping the mapper. The path a gateway and a hand-rolled
+     * binding use, where the numbers are already in Stigg's own vocabulary.
+     */
+    ingestMetrics(context: ResolvedContext, metrics: Metrics, options?: IngestOptions): Promise<IngestResult>;
+    /**
+     * The instrumentation path: one report per metric, all in one call where the transport has one.
+     *
+     * Never throws and never applies the error policy - the spend already happened, so failing here
+     * must not fail the caller's call. Errors go to `onError`.
+     */
+    private send;
+    /**
+     * A binding's own failure at measuring a call that already happened.
+     *
+     * A recipe reads usage off a vendor's response, and a vendor is free to change that response -
+     * so reading it can throw. The call succeeded and the money is spent either way, which makes
+     * this the same kind of event as a failed ingest: counted, reported, and never raised at the
+     * caller, who asked the vendor for something and got it.
+     */
+    failedToMeasure(context: ResolvedContext, err: unknown): void;
+    /** Waits for in-flight ingests, so a caller knows what was actually delivered. */
+    drain(): Promise<GovernanceSummary>;
+    summary(): GovernanceSummary;
+    /** `correlationId:n` - distinct per call, for a vendor that offered no id of its own. */
+    private nextKey;
+    /**
+     * The failure that looks like success, said once.
+     *
+     * A call gates on one capability and reports to another. Stigg only moves the one to the other
+     * when the feature is credit-backed in the catalog - and when it is not, every call still
+     * succeeds, every ingest returns `ok`, and the budget never moves. Nothing else in the system
+     * can notice: the check keeps passing because nothing was ever spent.
+     *
+     * The two modes fail the same way and can be told about it to different degrees. A usage report
+     * answers with a credit balance, so its silence is proof. An event answers with nothing at all,
+     * so the most that can be said is that nothing reported names what this call checks, and whether
+     * a meter closes that gap is configuration this process cannot see.
+     */
+    private warnIfNothingDrains;
+    private record;
+    /**
+     * Hooks are instrumentation, so a throwing one must not reach the caller: it cannot turn an
+     * allow into a denial, flip a delivered ingest to `ok: false`, or reject a promise the contract
+     * says never rejects. The failure is reported like any other.
+     */
+    private hook;
+    /**
+     * The last stop for a failure. `onError` is the application's own code and can throw too, and
+     * there is nowhere left to report that to, so it falls back to the logger.
+     */
+    private reportError;
+    private failedIngest;
+}