shield360 1.0.1 → 1.2.0

package/dist/budgets/index.d.ts

@@ -0,0 +1,110 @@
+/**
+ * Budget check: ask Shield360 whether this app may spend on a model call.
+ *
+ *   Shield360.budgets.check({ model, estimatedCostUsd })
+ *     -> { allowed, action: allow | warn | throttle | block, reason, ... }
+ *
+ * The answer comes from the platform's GET /api/budgets/decision, the one
+ * spend decision every Shield360 enforcement point uses, asked with the
+ * environment's API key and this app's service name. App budgets (Costs ->
+ * Budgets, "App") and project budgets with enforcement rules apply.
+ *
+ * It does not call the platform on every request. Like the CLI's proxy and
+ * hooks (cli/internal/spenddecision), a decision is reused for the
+ * ttlSeconds the platform sets (60 s by default) while the estimated cost of
+ * the calls checked with it fits in its headroomUsd, the spend left before
+ * any limit turns stricter. Concurrent checks share one fetch.
+ *
+ * It never throws. When no decision can be read it fails open (allowed) by
+ * default; closed when `failClosed` is set here or on the client, or when
+ * the last decision read said failClosed (a budget with a block rule that
+ * asks for it). A failed read is not retried for a few seconds.
+ *
+ * Must stay in sync with: sdk/python/src/shield360/budgets.py
+ */
+export type BudgetAction = 'allow' | 'warn' | 'throttle' | 'block';
+export type BudgetCheckOptions = {
+    /** The app's service name; defaults to the applicationName given to init(). */
+    app?: string;
+    /** The model the call will use, for model budgets. */
+    model?: string;
+    /** What the call may cost in USD, when the caller can estimate it. Held against the decision's headroom. */
+    estimatedCostUsd?: number;
+    /** Refuse when no decision can be read. Overrides the client's setting for this check. */
+    failClosed?: boolean;
+};
+export type BudgetCheckResult = {
+    /** Whether the call may go ahead. */
+    allowed: boolean;
+    action: BudgetAction;
+    /** budget_ok, budget_warn, budget_throttle, budget_block, budget_override or budget_unavailable. */
+    code: string;
+    /** What to show or log, from the platform. Empty when allowed with nothing to say. */
+    reason: string;
+    /** The limit that decided, when one did. */
+    limit: {
+        id: string;
+        name: string;
+        scope: string;
+    } | null;
+    /** Spend left before a stricter action, from the decision; null when spending cannot make it stricter. */
+    headroomUsd: number | null;
+    /** Answered from a decision already fetched. */
+    cached: boolean;
+    /** No decision could be read; `allowed` is the fail mode's. */
+    unavailable: boolean;
+};
+export type BudgetClientOptions = {
+    /** Shield360 URL; defaults to init()'s shield360Url or SHIELD360_URL. */
+    url?: string;
+    /** Environment API key; defaults to init()'s shield360ApiKey or SHIELD360_API_KEY. */
+    apiKey?: string;
+    /** The app's service name; defaults to init()'s applicationName. */
+    app?: string;
+    /** Refuse when no decision can be read (default false; env SHIELD360_BUDGET_FAIL_CLOSED=1). */
+    failClosed?: boolean;
+    /** One fetch's timeout. Default 3000 ms. */
+    timeoutMs?: number;
+    fetch?: typeof fetch;
+    now?: () => number;
+};
+export declare const UNAVAILABLE_REASON = "Shield360 could not check the budget for this AI call, and this app is set to wait until it can. Try again shortly. [budget_unavailable]";
+/** Thrown by the automatic pre-call check (init({ budgetCheck })) when a budget refuses the call. */
+export declare class BudgetExceededError extends Error {
+    readonly result: BudgetCheckResult;
+    constructor(result: BudgetCheckResult);
+}
+export declare class BudgetClient {
+    private readonly opts;
+    private cache;
+    private inflight;
+    private unavailableUntil;
+    private calls;
+    /** The last decision read asked to fail closed. */
+    private failClosedHint;
+    constructor(opts?: BudgetClientOptions);
+    private now;
+    private creds;
+    /** Forget cached decisions (after changing a budget, and in tests). */
+    reset(): void;
+    /** The decision for one call. Never throws. */
+    check(options?: BudgetCheckOptions): Promise<BudgetCheckResult>;
+    private failClosed;
+    private unavailable;
+    private checkUnsafe;
+    private fits;
+    private fetchDecision;
+    /** Throttle is a per-subject sliding minute, as the CLI keeps it. */
+    private throttled;
+    private result;
+}
+/** The process's client, built from init()'s URL, API key and applicationName. */
+export declare function defaultBudgetClient(): BudgetClient;
+/** Replace the process's client (init({ budgetCheck: { failClosed } }) and tests). */
+export declare function configureBudgets(opts?: BudgetClientOptions): BudgetClient;
+/** Shield360.budgets: check() with the process's client. */
+export declare const budgets: {
+    check: (options?: BudgetCheckOptions) => Promise<BudgetCheckResult>;
+    configure: typeof configureBudgets;
+    reset: () => void;
+};

package/dist/budgets/index.js

@@ -0,0 +1,239 @@
+"use strict";
+/**
+ * Budget check: ask Shield360 whether this app may spend on a model call.
+ *
+ *   Shield360.budgets.check({ model, estimatedCostUsd })
+ *     -> { allowed, action: allow | warn | throttle | block, reason, ... }
+ *
+ * The answer comes from the platform's GET /api/budgets/decision, the one
+ * spend decision every Shield360 enforcement point uses, asked with the
+ * environment's API key and this app's service name. App budgets (Costs ->
+ * Budgets, "App") and project budgets with enforcement rules apply.
+ *
+ * It does not call the platform on every request. Like the CLI's proxy and
+ * hooks (cli/internal/spenddecision), a decision is reused for the
+ * ttlSeconds the platform sets (60 s by default) while the estimated cost of
+ * the calls checked with it fits in its headroomUsd, the spend left before
+ * any limit turns stricter. Concurrent checks share one fetch.
+ *
+ * It never throws. When no decision can be read it fails open (allowed) by
+ * default; closed when `failClosed` is set here or on the client, or when
+ * the last decision read said failClosed (a budget with a block rule that
+ * asks for it). A failed read is not retried for a few seconds.
+ *
+ * Must stay in sync with: sdk/python/src/shield360/budgets.py
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.budgets = exports.BudgetClient = exports.BudgetExceededError = exports.UNAVAILABLE_REASON = void 0;
+exports.defaultBudgetClient = defaultBudgetClient;
+exports.configureBudgets = configureBudgets;
+const config_1 = __importDefault(require("../config"));
+const DEFAULT_TTL_MS = 60000;
+const MAX_TTL_MS = 600000;
+/** How long a failed read stands before the next check tries again. */
+const UNAVAILABLE_BACKOFF_MS = 5000;
+const MAX_SUBJECT = 256;
+const ACTIONS = ['allow', 'warn', 'throttle', 'block'];
+exports.UNAVAILABLE_REASON = 'Shield360 could not check the budget for this AI call, and this app is set to wait until it can. Try again shortly. [budget_unavailable]';
+function envFlag(name) {
+    const v = (typeof process !== 'undefined' ? process.env?.[name] : undefined)?.trim().toLowerCase();
+    return v === '1' || v === 'true' || v === 'yes';
+}
+const positive = (v) => (typeof v === 'number' && Number.isFinite(v) && v > 0 ? v : 0);
+function clean(v) {
+    if (typeof v !== 'string')
+        return undefined;
+    const t = v.trim();
+    return t && t.length <= MAX_SUBJECT ? t : undefined;
+}
+/** Thrown by the automatic pre-call check (init({ budgetCheck })) when a budget refuses the call. */
+class BudgetExceededError extends Error {
+    constructor(result) {
+        super(result.reason || `Shield360 budget refused this AI call. [${result.code}]`);
+        this.name = 'BudgetExceededError';
+        this.result = result;
+    }
+}
+exports.BudgetExceededError = BudgetExceededError;
+class BudgetClient {
+    constructor(opts = {}) {
+        this.cache = new Map();
+        this.inflight = new Map();
+        this.unavailableUntil = new Map();
+        this.calls = new Map();
+        /** The last decision read asked to fail closed. */
+        this.failClosedHint = false;
+        this.opts = opts;
+    }
+    now() {
+        return this.opts.now ? this.opts.now() : Date.now();
+    }
+    creds() {
+        const env = typeof process !== 'undefined' ? process.env : {};
+        return {
+            url: this.opts.url ?? config_1.default.shield360Url ?? env.SHIELD360_URL,
+            apiKey: this.opts.apiKey ?? config_1.default.shield360ApiKey ?? env.SHIELD360_API_KEY,
+        };
+    }
+    /** Forget cached decisions (after changing a budget, and in tests). */
+    reset() {
+        this.cache.clear();
+        this.inflight.clear();
+        this.unavailableUntil.clear();
+        this.calls.clear();
+        this.failClosedHint = false;
+    }
+    /** The decision for one call. Never throws. */
+    async check(options = {}) {
+        try {
+            return await this.checkUnsafe(options);
+        }
+        catch {
+            return this.unavailable(options);
+        }
+    }
+    failClosed(options) {
+        if (options.failClosed !== undefined)
+            return options.failClosed;
+        if (this.opts.failClosed !== undefined)
+            return this.opts.failClosed || this.failClosedHint;
+        return envFlag('SHIELD360_BUDGET_FAIL_CLOSED') || this.failClosedHint;
+    }
+    unavailable(options) {
+        const closed = this.failClosed(options);
+        return {
+            allowed: !closed,
+            action: closed ? 'block' : 'allow',
+            code: 'budget_unavailable',
+            reason: closed ? exports.UNAVAILABLE_REASON : '',
+            limit: null,
+            headroomUsd: null,
+            cached: false,
+            unavailable: true,
+        };
+    }
+    async checkUnsafe(options) {
+        const app = clean(options.app) ?? clean(this.opts.app) ?? clean(config_1.default.applicationName);
+        const model = clean(options.model);
+        const cost = positive(options.estimatedCostUsd);
+        const { url, apiKey } = this.creds();
+        if (!app || !url || !apiKey)
+            return this.unavailable(options);
+        const key = `${app}\u0000${model ?? ''}`.toLowerCase();
+        const now = this.now();
+        const hit = this.cache.get(key);
+        if (hit && now - hit.fetchedAt < hit.ttlMs && this.fits(hit, cost)) {
+            hit.spent += cost;
+            return this.result(key, hit.decision, true);
+        }
+        if ((this.unavailableUntil.get(key) ?? 0) > now)
+            return this.unavailable(options);
+        let pending = this.inflight.get(key);
+        const started = !pending;
+        if (!pending) {
+            pending = this.fetchDecision(url, apiKey, app, model, cost).finally(() => this.inflight.delete(key));
+            this.inflight.set(key, pending);
+        }
+        const entry = await pending;
+        if (!entry) {
+            this.unavailableUntil.set(key, this.now() + UNAVAILABLE_BACKOFF_MS);
+            return this.unavailable(options);
+        }
+        this.unavailableUntil.delete(key);
+        if (started)
+            this.cache.set(key, entry);
+        // The fetch asked with the first call's cost; every call that shares the decision counts against its headroom.
+        entry.spent += cost;
+        return this.result(key, entry.decision, !started);
+    }
+    fits(entry, cost) {
+        const h = entry.decision.headroomUsd;
+        return h === null || h === undefined || entry.spent + cost <= h;
+    }
+    async fetchDecision(url, apiKey, app, model, cost) {
+        const doFetch = this.opts.fetch ?? (typeof fetch === 'function' ? fetch : undefined);
+        if (!doFetch)
+            return null;
+        const q = new URLSearchParams({ app });
+        if (model)
+            q.set('model', model);
+        if (cost > 0)
+            q.set('cost', cost.toFixed(6));
+        const controller = typeof AbortController === 'function' ? new AbortController() : undefined;
+        const timer = setTimeout(() => controller?.abort(), this.opts.timeoutMs ?? 3000);
+        try {
+            const res = await doFetch(`${url.replace(/\/+$/, '')}/api/budgets/decision?${q.toString()}`, {
+                headers: { Authorization: `Bearer ${apiKey}`, Accept: 'application/json' },
+                signal: controller?.signal,
+            });
+            if (!res.ok)
+                return null;
+            const decision = (await res.json());
+            if (!decision || typeof decision !== 'object' || !ACTIONS.includes(decision.action))
+                return null;
+            this.failClosedHint = decision.failClosed === true;
+            const ttl = Number(decision.ttlSeconds) > 0 ? Math.min(Number(decision.ttlSeconds) * 1000, MAX_TTL_MS) : DEFAULT_TTL_MS;
+            return { decision, fetchedAt: this.now(), ttlMs: ttl, spent: 0 };
+        }
+        catch {
+            return null;
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    /** Throttle is a per-subject sliding minute, as the CLI keeps it. */
+    throttled(key, rpm) {
+        const now = this.now();
+        const recent = (this.calls.get(key) ?? []).filter((t) => now - t < 60000);
+        if (recent.length >= rpm) {
+            this.calls.set(key, recent);
+            return true;
+        }
+        recent.push(now);
+        this.calls.set(key, recent);
+        return false;
+    }
+    result(key, d, cached) {
+        const action = (ACTIONS.includes(d.action) ? d.action : 'allow');
+        let allowed = action === 'allow' || action === 'warn';
+        if (action === 'throttle') {
+            const rpm = Math.max(1, Math.floor(Number(d.throttle?.requestsPerMinute) || 1));
+            allowed = !this.throttled(key, rpm);
+        }
+        const headroom = typeof d.headroomUsd === 'number' && Number.isFinite(d.headroomUsd) ? d.headroomUsd : null;
+        return {
+            allowed,
+            action,
+            code: typeof d.code === 'string' ? d.code : `budget_${action === 'allow' ? 'ok' : action}`,
+            reason: typeof d.reason === 'string' ? d.reason : '',
+            limit: d.limit && typeof d.limit === 'object' ? { id: String(d.limit.id ?? ''), name: String(d.limit.name ?? ''), scope: String(d.limit.scope ?? '') } : null,
+            headroomUsd: headroom,
+            cached,
+            unavailable: false,
+        };
+    }
+}
+exports.BudgetClient = BudgetClient;
+let defaultClient = null;
+/** The process's client, built from init()'s URL, API key and applicationName. */
+function defaultBudgetClient() {
+    if (!defaultClient)
+        defaultClient = new BudgetClient();
+    return defaultClient;
+}
+/** Replace the process's client (init({ budgetCheck: { failClosed } }) and tests). */
+function configureBudgets(opts = {}) {
+    defaultClient = new BudgetClient(opts);
+    return defaultClient;
+}
+/** Shield360.budgets: check() with the process's client. */
+exports.budgets = {
+    check: (options) => defaultBudgetClient().check(options),
+    configure: configureBudgets,
+    reset: () => defaultBudgetClient().reset(),
+};
+//# sourceMappingURL=index.js.map

package/dist/budgets/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/budgets/index.ts"],"names":[],"mappings":"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"}

package/dist/config.js

@@ -1,7 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 class Shield360Config {
-    static updateConfig({ environment = 'default', applicationName = 'default', tracer, otlpEndpoint, otlpHeaders, disableBatch = false, captureMessageContent = true, pricingJson, disableMetrics = false, disableEvents = false, maxContentLength = null, customSpanAttributes = null, shield360ApiKey, shield360Url, }) {
+    static updateConfig({ environment = 'default', applicationName = 'default', tracer, otlpEndpoint, otlpHeaders, disableBatch = false, captureMessageContent = false, pricingJson, disableMetrics = false, disableEvents = false, maxContentLength = null, customSpanAttributes = null, shield360ApiKey, shield360Url, }) {
         this.environment = environment;
         this.applicationName = applicationName;
         this.tracer = tracer;

package/dist/config.js.map

@@ -1 +1 @@
-{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":";;AAGA,MAAqB,eAAe;IAkBlC,MAAM,CAAC,YAAY,CAAC,EAClB,WAAW,GAAG,SAAS,EACvB,eAAe,GAAG,SAAS,EAC3B,MAAM,EACN,YAAY,EACZ,WAAW,EACX,YAAY,GAAG,KAAK,EACpB,qBAAqB,GAAG,IAAI,EAC5B,WAAW,EACX,cAAc,GAAG,KAAK,EACtB,aAAa,GAAG,KAAK,EACrB,gBAAgB,GAAG,IAAI,EACvB,oBAAoB,GAAG,IAAI,EAC3B,eAAe,EACf,YAAY,GAQb;QACC,IAAI,CAAC,WAAW,GAAG,WAAW,CAAC;QAC/B,IAAI,CAAC,eAAe,GAAG,eAAe,CAAC;QACvC,IAAI,CAAC,MAAM,GAAG,MAA4C,CAAC;QAC3D,IAAI,CAAC,YAAY,GAAG,YAAY,CAAC;QACjC,IAAI,CAAC,WAAW,GAAG,WAAW,CAAC;QAC/B,IAAI,CAAC,YAAY,GAAG,YAAY,CAAC;QACjC,IAAI,CAAC,qBAAqB,GAAG,qBAAqB,CAAC;QACnD,IAAI,CAAC,WAAW,GAAG,WAAW,CAAC;QAC/B,IAAI,CAAC,cAAc,GAAG,cAAc,CAAC;QACrC,IAAI,CAAC,aAAa,GAAG,aAAa,CAAC;QACnC,IAAI,CAAC,gBAAgB,GAAG,gBAAgB,CAAC;QACzC,IAAI,CAAC,oBAAoB,GAAG,oBAAoB,CAAC;QACjD,IAAI,CAAC,eAAe,GAAG,eAAe,CAAC;QACvC,IAAI,CAAC,YAAY,GAAG,YAAY,CAAC;IACnC,CAAC;CACF;AAxDD,kCAwDC"}
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":";;AAGA,MAAqB,eAAe;IAkBlC,MAAM,CAAC,YAAY,CAAC,EAClB,WAAW,GAAG,SAAS,EACvB,eAAe,GAAG,SAAS,EAC3B,MAAM,EACN,YAAY,EACZ,WAAW,EACX,YAAY,GAAG,KAAK,EACpB,qBAAqB,GAAG,KAAK,EAC7B,WAAW,EACX,cAAc,GAAG,KAAK,EACtB,aAAa,GAAG,KAAK,EACrB,gBAAgB,GAAG,IAAI,EACvB,oBAAoB,GAAG,IAAI,EAC3B,eAAe,EACf,YAAY,GAQb;QACC,IAAI,CAAC,WAAW,GAAG,WAAW,CAAC;QAC/B,IAAI,CAAC,eAAe,GAAG,eAAe,CAAC;QACvC,IAAI,CAAC,MAAM,GAAG,MAA4C,CAAC;QAC3D,IAAI,CAAC,YAAY,GAAG,YAAY,CAAC;QACjC,IAAI,CAAC,WAAW,GAAG,WAAW,CAAC;QAC/B,IAAI,CAAC,YAAY,GAAG,YAAY,CAAC;QACjC,IAAI,CAAC,qBAAqB,GAAG,qBAAqB,CAAC;QACnD,IAAI,CAAC,WAAW,GAAG,WAAW,CAAC;QAC/B,IAAI,CAAC,cAAc,GAAG,cAAc,CAAC;QACrC,IAAI,CAAC,aAAa,GAAG,aAAa,CAAC;QACnC,IAAI,CAAC,gBAAgB,GAAG,gBAAgB,CAAC;QACzC,IAAI,CAAC,oBAAoB,GAAG,oBAAoB,CAAC;QACjD,IAAI,CAAC,eAAe,GAAG,eAAe,CAAC;QACvC,IAAI,CAAC,YAAY,GAAG,YAAY,CAAC;IACnC,CAAC;CACF;AAxDD,kCAwDC"}

package/dist/customer/__tests__/customer.test.d.ts

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

package/dist/customer/__tests__/customer.test.js

@@ -0,0 +1,155 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const sdk_trace_base_1 = require("@opentelemetry/sdk-trace-base");
+const sdk_trace_node_1 = require("@opentelemetry/sdk-trace-node");
+const index_1 = __importDefault(require("../../index"));
+const tracing_1 = __importDefault(require("../../otel/tracing"));
+const index_2 = require("../index");
+const tick = () => new Promise((r) => setTimeout(r, 1));
+afterEach(() => (0, index_2.setCustomer)(null));
+describe('customer context', () => {
+    it('has no customer by default', () => {
+        expect((0, index_2.getCustomer)()).toBeNull();
+    });
+    it('sets and clears a process-wide default', () => {
+        (0, index_2.setCustomer)({ tenantId: 'acme', userId: 'u1' });
+        expect((0, index_2.getCustomer)()).toEqual({ tenantId: 'acme', userId: 'u1' });
+        (0, index_2.setCustomer)(null);
+        expect((0, index_2.getCustomer)()).toBeNull();
+    });
+    it('withCustomer wins over the default, nests, and restores after', () => {
+        (0, index_2.setCustomer)({ tenantId: 'default-co' });
+        const seen = (0, index_2.withCustomer)({ tenantId: 'acme', userId: 'u1' }, () => {
+            const outer = (0, index_2.getCustomer)();
+            const inner = (0, index_2.withCustomer)({ tenantId: 'globex' }, () => (0, index_2.getCustomer)());
+            return { outer, inner, after: (0, index_2.getCustomer)() };
+        });
+        expect(seen.outer).toEqual({ tenantId: 'acme', userId: 'u1' });
+        expect(seen.inner).toEqual({ tenantId: 'globex' });
+        expect(seen.after).toEqual({ tenantId: 'acme', userId: 'u1' });
+        expect((0, index_2.getCustomer)()).toEqual({ tenantId: 'default-co' });
+    });
+    it('propagates across awaits and keeps concurrent calls apart', async () => {
+        const run = (tenantId) => (0, index_2.withCustomer)({ tenantId }, async () => {
+            await tick();
+            await Promise.resolve();
+            return (0, index_2.getCustomer)()?.tenantId;
+        });
+        const results = await Promise.all([run('a'), run('b'), run('c')]);
+        expect(results).toEqual(['a', 'b', 'c']);
+        expect((0, index_2.getCustomer)()).toBeNull();
+    });
+    it('a null or invalid scoped customer means no customer, not the default', () => {
+        (0, index_2.setCustomer)({ tenantId: 'default-co' });
+        expect((0, index_2.withCustomer)(null, () => (0, index_2.getCustomer)())).toBeNull();
+        expect((0, index_2.withCustomer)({ tenantId: '   ' }, () => (0, index_2.getCustomer)())).toBeNull();
+    });
+    it('is exposed on the default export', () => {
+        expect(index_1.default.setCustomer).toBe(index_2.setCustomer);
+        expect(index_1.default.withCustomer).toBe(index_2.withCustomer);
+        expect(index_1.default.getCustomer).toBe(index_2.getCustomer);
+    });
+    it('returns a copy, so callers cannot change the customer in effect', () => {
+        (0, index_2.setCustomer)({ tenantId: 'acme' });
+        (0, index_2.getCustomer)().tenantId = 'mutated';
+        expect((0, index_2.getCustomer)()).toEqual({ tenantId: 'acme' });
+    });
+});
+describe('validation', () => {
+    it('trims strings and converts finite numbers', () => {
+        expect((0, index_2.normaliseCustomerId)('  acme ')).toBe('acme');
+        expect((0, index_2.normaliseCustomerId)(42)).toBe('42');
+        expect((0, index_2.normaliseCustomerId)('x'.repeat(256))).toBe('x'.repeat(256));
+    });
+    it.each([
+        ['empty', ''],
+        ['whitespace', '  \t '],
+        ['too long', 'x'.repeat(257)],
+        ['newline', 'ac\nme'],
+        ['NUL', 'ac\u0000me'],
+        ['DEL', 'ac\u007fme'],
+        ['C1 control', 'ac\u0085me'],
+        ['NaN', NaN],
+        ['Infinity', Infinity],
+        ['object', { id: 'acme' }],
+        ['boolean', true],
+        ['null', null],
+        ['undefined', undefined],
+    ])('drops %s', (_name, value) => {
+        expect((0, index_2.normaliseCustomerId)(value)).toBeUndefined();
+    });
+    it('drops a userId without a valid tenantId', () => {
+        expect((0, index_2.normaliseCustomer)({ userId: 'u1' })).toBeNull();
+        expect((0, index_2.normaliseCustomer)({ tenantId: '', userId: 'u1' })).toBeNull();
+    });
+    it('keeps the tenant when only the userId is invalid', () => {
+        expect((0, index_2.normaliseCustomer)({ tenantId: 'acme', userId: 'bad\nid' })).toEqual({ tenantId: 'acme' });
+    });
+    it('never throws on odd input', () => {
+        expect(() => (0, index_2.setCustomer)('acme')).not.toThrow();
+        expect((0, index_2.getCustomer)()).toBeNull();
+        const hostile = { get tenantId() { throw new Error('boom'); } };
+        expect(() => (0, index_2.setCustomer)(hostile)).not.toThrow();
+        expect((0, index_2.getCustomer)()).toBeNull();
+    });
+    it('an invalid default clears the previous one', () => {
+        (0, index_2.setCustomer)({ tenantId: 'acme' });
+        (0, index_2.setCustomer)({ tenantId: '' });
+        expect((0, index_2.getCustomer)()).toBeNull();
+    });
+});
+describe('CustomerSpanProcessor', () => {
+    let exporter;
+    let provider;
+    beforeEach(() => {
+        exporter = new sdk_trace_base_1.InMemorySpanExporter();
+        provider = new sdk_trace_node_1.NodeTracerProvider({
+            spanProcessors: [new index_2.CustomerSpanProcessor(), new sdk_trace_base_1.SimpleSpanProcessor(exporter)],
+        });
+    });
+    afterEach(async () => {
+        await provider.shutdown();
+    });
+    const startAndEnd = (name = 'chat gpt-4o', attributes) => provider.getTracer('test').startSpan(name, { attributes }).end();
+    const lastAttrs = () => {
+        const spans = exporter.getFinishedSpans();
+        return spans[spans.length - 1].attributes;
+    };
+    it('leaves spans alone when no customer is in effect', () => {
+        startAndEnd();
+        expect(lastAttrs()[index_2.ATTR_CUSTOMER_TENANT_ID]).toBeUndefined();
+        expect(lastAttrs()[index_2.ATTR_CUSTOMER_USER_ID]).toBeUndefined();
+    });
+    it('stamps the default customer on every span, GenAI or not', () => {
+        (0, index_2.setCustomer)({ tenantId: 'acme', userId: 'u1' });
+        startAndEnd('GET /orders', { 'http.method': 'GET' });
+        expect(lastAttrs()[index_2.ATTR_CUSTOMER_TENANT_ID]).toBe('acme');
+        expect(lastAttrs()[index_2.ATTR_CUSTOMER_USER_ID]).toBe('u1');
+    });
+    it('stamps the scoped customer, across awaits, over the default', async () => {
+        (0, index_2.setCustomer)({ tenantId: 'default-co' });
+        await (0, index_2.withCustomer)({ tenantId: 'acme', userId: 7 }, async () => {
+            await tick();
+            startAndEnd();
+        });
+        expect(lastAttrs()[index_2.ATTR_CUSTOMER_TENANT_ID]).toBe('acme');
+        expect(lastAttrs()[index_2.ATTR_CUSTOMER_USER_ID]).toBe('7');
+        startAndEnd();
+        expect(lastAttrs()[index_2.ATTR_CUSTOMER_TENANT_ID]).toBe('default-co');
+        expect(lastAttrs()[index_2.ATTR_CUSTOMER_USER_ID]).toBeUndefined();
+    });
+    it('never overwrites a tenant id the caller set on the span', () => {
+        (0, index_2.setCustomer)({ tenantId: 'acme', userId: 'u1' });
+        startAndEnd('chat', { [index_2.ATTR_CUSTOMER_TENANT_ID]: 'given' });
+        expect(lastAttrs()[index_2.ATTR_CUSTOMER_TENANT_ID]).toBe('given');
+        expect(lastAttrs()[index_2.ATTR_CUSTOMER_USER_ID]).toBeUndefined();
+    });
+    it('is registered first in the processors the SDK builds', () => {
+        const processors = tracing_1.default.buildSpanProcessors({ disableBatch: true });
+        expect(processors[0]).toBeInstanceOf(index_2.CustomerSpanProcessor);
+    });
+});
+//# sourceMappingURL=customer.test.js.map

package/dist/customer/__tests__/customer.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"customer.test.js","sourceRoot":"","sources":["../../../src/customer/__tests__/customer.test.ts"],"names":[],"mappings":"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"}

package/dist/customer/index.d.ts

@@ -0,0 +1,48 @@
+import type { Context } from '@opentelemetry/api';
+import type { ReadableSpan, Span, SpanProcessor } from '@opentelemetry/sdk-trace-base';
+export declare const ATTR_CUSTOMER_TENANT_ID: string;
+export declare const ATTR_CUSTOMER_USER_ID: string;
+/** The customer a call is attributed to. userId is only ever set with a tenantId. */
+export type Customer = {
+    tenantId: string;
+    userId?: string;
+};
+/** What callers pass: ids may be strings or numbers; anything invalid is dropped. */
+export type CustomerInput = {
+    tenantId?: string | number | null;
+    userId?: string | number | null;
+};
+/**
+ * A valid id, or undefined. Strings and finite numbers are accepted, trimmed,
+ * 1–256 characters, with no control characters. Never throws, never logs.
+ */
+export declare function normaliseCustomerId(value: unknown): string | undefined;
+/**
+ * A validated customer, or null. A user is only attributable inside a tenant,
+ * so a userId without a valid tenantId is dropped with it.
+ */
+export declare function normaliseCustomer(input: CustomerInput | null | undefined): Customer | null;
+/**
+ * Set the process-wide default customer; null clears it. An invalid tenantId
+ * also clears it, so calls are never attributed to the wrong customer.
+ */
+export declare function setCustomer(customer: CustomerInput | null): void;
+/**
+ * Run fn (sync or async) with this customer in effect for every span it
+ * starts. Nested calls override; the scoped customer wins over the default.
+ * Passing null (or an invalid tenantId) runs fn with no customer.
+ */
+export declare function withCustomer<T>(customer: CustomerInput | null, fn: () => T): T;
+/** The customer in effect here (scoped, else the default), or null. */
+export declare function getCustomer(): Customer | null;
+/**
+ * Stamps shield360.customer.tenant_id / user_id on every span started while a
+ * customer is in effect. A span that already carries a tenant id (set by the
+ * caller) is left alone, so explicit attributes are never mixed with ours.
+ */
+export declare class CustomerSpanProcessor implements SpanProcessor {
+    onStart(span: Span, _parentContext: Context): void;
+    onEnd(_span: ReadableSpan): void;
+    forceFlush(): Promise<void>;
+    shutdown(): Promise<void>;
+}