shield360 1.0.1 → 1.2.0

package/dist/customer/index.js

@@ -0,0 +1,132 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CustomerSpanProcessor = exports.ATTR_CUSTOMER_USER_ID = exports.ATTR_CUSTOMER_TENANT_ID = void 0;
+exports.normaliseCustomerId = normaliseCustomerId;
+exports.normaliseCustomer = normaliseCustomer;
+exports.setCustomer = setCustomer;
+exports.withCustomer = withCustomer;
+exports.getCustomer = getCustomer;
+/**
+ * Cost per end customer: SaaS builders tag each AI call with their own
+ * customer (tenant) and, optionally, the end user inside that tenant, so
+ * Shield360 can show cost and margin per end customer.
+ *
+ * Shield360.setCustomer() sets a process-wide default; Shield360.withCustomer()
+ * scopes a customer to one call tree through AsyncLocalStorage and wins over
+ * the default. CustomerSpanProcessor stamps every span started while a
+ * customer is in effect, so one processor covers every instrumentation.
+ *
+ * The SDK never hashes. Ids are sent as given: Shield360 stores user ids only
+ * as a keyed hash on its side, and keeps tenant ids as given unless the
+ * organisation opts to hash them.
+ */
+const node_async_hooks_1 = require("node:async_hooks");
+const semantic_convention_1 = __importDefault(require("../semantic-convention"));
+exports.ATTR_CUSTOMER_TENANT_ID = semantic_convention_1.default.SHIELD360_CUSTOMER_TENANT_ID;
+exports.ATTR_CUSTOMER_USER_ID = semantic_convention_1.default.SHIELD360_CUSTOMER_USER_ID;
+const MAX_ID_LENGTH = 256;
+function hasControlCharacter(value) {
+    for (let i = 0; i < value.length; i++) {
+        const code = value.charCodeAt(i);
+        if (code <= 0x1f || (code >= 0x7f && code <= 0x9f))
+            return true;
+    }
+    return false;
+}
+/**
+ * A valid id, or undefined. Strings and finite numbers are accepted, trimmed,
+ * 1–256 characters, with no control characters. Never throws, never logs.
+ */
+function normaliseCustomerId(value) {
+    let text;
+    if (typeof value === 'string')
+        text = value;
+    else if (typeof value === 'number' && Number.isFinite(value))
+        text = String(value);
+    else if (typeof value === 'bigint')
+        text = value.toString();
+    else
+        return undefined;
+    text = text.trim();
+    if (text.length < 1 || text.length > MAX_ID_LENGTH || hasControlCharacter(text))
+        return undefined;
+    return text;
+}
+/**
+ * A validated customer, or null. A user is only attributable inside a tenant,
+ * so a userId without a valid tenantId is dropped with it.
+ */
+function normaliseCustomer(input) {
+    try {
+        if (!input || typeof input !== 'object')
+            return null;
+        const tenantId = normaliseCustomerId(input.tenantId);
+        if (!tenantId)
+            return null;
+        const userId = normaliseCustomerId(input.userId);
+        return userId ? { tenantId, userId } : { tenantId };
+    }
+    catch {
+        return null;
+    }
+}
+// The scoped customer. A store of { customer: null } means "no customer here",
+// so an invalid or null scoped customer never falls back to the default.
+const _scoped = new node_async_hooks_1.AsyncLocalStorage();
+let _default = 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.
+ */
+function setCustomer(customer) {
+    _default = normaliseCustomer(customer);
+}
+/**
+ * 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.
+ */
+function withCustomer(customer, fn) {
+    return _scoped.run({ customer: normaliseCustomer(customer) }, fn);
+}
+/** The customer in effect here (scoped, else the default), or null. */
+function getCustomer() {
+    const store = _scoped.getStore();
+    const customer = store ? store.customer : _default;
+    return customer ? { ...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.
+ */
+class CustomerSpanProcessor {
+    onStart(span, _parentContext) {
+        try {
+            const store = _scoped.getStore();
+            const customer = store ? store.customer : _default;
+            if (!customer)
+                return;
+            if (span.attributes[exports.ATTR_CUSTOMER_TENANT_ID] !== undefined)
+                return;
+            span.setAttribute(exports.ATTR_CUSTOMER_TENANT_ID, customer.tenantId);
+            if (customer.userId)
+                span.setAttribute(exports.ATTR_CUSTOMER_USER_ID, customer.userId);
+        }
+        catch {
+            // Never break span creation.
+        }
+    }
+    onEnd(_span) { }
+    forceFlush() {
+        return Promise.resolve();
+    }
+    shutdown() {
+        return Promise.resolve();
+    }
+}
+exports.CustomerSpanProcessor = CustomerSpanProcessor;
+//# sourceMappingURL=index.js.map

package/dist/customer/index.js.map

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

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

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

package/dist/feedback/__tests__/feedback.test.js

@@ -0,0 +1,80 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const api_1 = require("@opentelemetry/api");
+const config_1 = __importDefault(require("../../config"));
+const __1 = require("..");
+const TRACE = '0af7651916cd43dd8448eb211c80319c';
+const SPAN = 'b7ad6b7169203331';
+describe('feedback', () => {
+    const fetchMock = jest.fn();
+    const realFetch = global.fetch;
+    beforeEach(() => {
+        fetchMock.mockReset();
+        fetchMock.mockResolvedValue({ ok: true });
+        global.fetch = fetchMock;
+        config_1.default.shield360Url = 'https://shield360.example/';
+        config_1.default.shield360ApiKey = 'key-1';
+        config_1.default.applicationName = 'checkout';
+        (0, __1.configureFeedback)({ app: 'checkout', release: '2.0.0' });
+    });
+    afterAll(() => {
+        global.fetch = realFetch;
+    });
+    it('posts the rating with the key, naming the app and release', async () => {
+        await expect((0, __1.feedback)({ traceId: TRACE.toUpperCase(), spanId: SPAN, score: -1, comment: 'wrong', userId: 'u-1', metadata: { plan: 'pro' } })).resolves.toBe(true);
+        const [url, init] = fetchMock.mock.calls[0];
+        expect(url).toBe('https://shield360.example/api/feedback');
+        expect(init.method).toBe('POST');
+        expect(init.headers.Authorization).toBe('Bearer key-1');
+        expect(JSON.parse(init.body)).toEqual({
+            traceId: TRACE,
+            spanId: SPAN,
+            score: -1,
+            comment: 'wrong',
+            userId: 'u-1',
+            metadata: { plan: 'pro' },
+            app: 'checkout',
+            release: '2.0.0',
+        });
+    });
+    it('defaults to the active trace', async () => {
+        const active = jest
+            .spyOn(api_1.trace, 'getActiveSpan')
+            .mockReturnValue(api_1.trace.wrapSpanContext({ traceId: TRACE, spanId: SPAN, traceFlags: api_1.TraceFlags.SAMPLED }));
+        expect((0, __1.getCurrentTraceId)()).toBe(TRACE);
+        expect((0, __1.getCurrentSpanId)()).toBe(SPAN);
+        await expect((0, __1.feedback)({ score: 5 })).resolves.toBe(true);
+        expect(JSON.parse(fetchMock.mock.calls[0][1].body).traceId).toBe(TRACE);
+        active.mockReturnValue(undefined);
+        expect((0, __1.getCurrentTraceId)()).toBeUndefined();
+        active.mockRestore();
+    });
+    it('never throws: bad input, no trace, no key, a refusal or a network error are false', async () => {
+        await expect((0, __1.feedback)({ score: 1 })).resolves.toBe(false);
+        await expect((0, __1.feedback)({ traceId: 'nope', score: 1 })).resolves.toBe(false);
+        await expect((0, __1.feedback)({ traceId: TRACE, score: 0 })).resolves.toBe(false);
+        await expect((0, __1.feedback)({ traceId: TRACE, score: 3, scale: 'thumbs' })).resolves.toBe(false);
+        await expect((0, __1.feedback)({ traceId: TRACE, spanId: 'x', score: 1 })).resolves.toBe(false);
+        await expect((0, __1.feedback)(undefined)).resolves.toBe(false);
+        expect(fetchMock).not.toHaveBeenCalled();
+        config_1.default.shield360ApiKey = undefined;
+        const saved = process.env.SHIELD360_API_KEY;
+        delete process.env.SHIELD360_API_KEY;
+        await expect((0, __1.feedback)({ traceId: TRACE, score: 1 })).resolves.toBe(false);
+        if (saved !== undefined)
+            process.env.SHIELD360_API_KEY = saved;
+        config_1.default.shield360ApiKey = 'key-1';
+        fetchMock.mockResolvedValueOnce({ ok: false, status: 400 });
+        await expect((0, __1.feedback)({ traceId: TRACE, score: 1 })).resolves.toBe(false);
+        fetchMock.mockRejectedValueOnce(new Error('offline'));
+        await expect((0, __1.feedback)({ traceId: TRACE, score: 1 })).resolves.toBe(false);
+    });
+    it('sends the star scale when asked, so one star is not a thumbs up', async () => {
+        await (0, __1.feedback)({ traceId: TRACE, score: 1, scale: 'stars' });
+        expect(JSON.parse(fetchMock.mock.calls[0][1].body)).toMatchObject({ score: 1, scale: 'stars' });
+    });
+});
+//# sourceMappingURL=feedback.test.js.map

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

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

package/dist/feedback/index.d.ts

@@ -0,0 +1,48 @@
+/**
+ * User feedback: what one of your application's users thought of an AI
+ * response, sent to Shield360 (`POST /api/feedback`) against the trace that
+ * produced it.
+ *
+ * Call it from your server, with the environment's API key — never from a
+ * browser. It never throws: anything wrong (no trace, no URL or key, a bad
+ * score, the network) resolves to `false`.
+ *
+ * Shield360 keeps the score, ids, application and release. The comment is
+ * kept only when your organisation's Data retention setting stores end users'
+ * free text (with secrets and personal data masked); `userId` and `tenantId`
+ * are kept only as a keyed hash.
+ */
+export type FeedbackScale = 'thumbs' | 'stars';
+export interface FeedbackOptions {
+    /** The trace rated. Defaults to the active span's trace. */
+    traceId?: string;
+    /** The span rated, when it was one call in the trace. */
+    spanId?: string;
+    /** 1 or -1 (thumbs), or 1 to 5 (stars; pass `scale: 'stars'` for a one-star rating). */
+    score: number;
+    scale?: FeedbackScale;
+    comment?: string;
+    /** Your end user's id. Stored only as a keyed hash. */
+    userId?: string;
+    /** Your end user's tenant or account. Stored only as a keyed hash. */
+    tenantId?: string;
+    metadata?: Record<string, string | number | boolean>;
+    /** Your own id for this rating: sending it again replaces the earlier rating. */
+    feedbackId?: string;
+    /** Defaults to the URL and key `init` was given, then SHIELD360_URL / SHIELD360_API_KEY. */
+    url?: string;
+    apiKey?: string;
+    /** Default 5000. */
+    timeoutMs?: number;
+}
+/** Set by `init`: the application and release every rating names. */
+export declare function configureFeedback(values: {
+    app?: string;
+    release?: string;
+}): void;
+/** The active span's trace id, or undefined outside a trace. */
+export declare function getCurrentTraceId(): string | undefined;
+/** The active span's id, or undefined outside a trace. */
+export declare function getCurrentSpanId(): string | undefined;
+/** Sends one rating. Resolves to whether Shield360 accepted it; never rejects. */
+export declare function feedback(options: FeedbackOptions): Promise<boolean>;

package/dist/feedback/index.js

@@ -0,0 +1,97 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.configureFeedback = configureFeedback;
+exports.getCurrentTraceId = getCurrentTraceId;
+exports.getCurrentSpanId = getCurrentSpanId;
+exports.feedback = feedback;
+const api_1 = require("@opentelemetry/api");
+const config_1 = __importDefault(require("../config"));
+const TRACE_ID = /^[0-9a-f]{32}$/i;
+const SPAN_ID = /^[0-9a-f]{16}$/i;
+const INVALID_TRACE = '0'.repeat(32);
+let defaults = {};
+/** Set by `init`: the application and release every rating names. */
+function configureFeedback(values) {
+    defaults = { ...values };
+}
+/** The active span's trace id, or undefined outside a trace. */
+function getCurrentTraceId() {
+    try {
+        const id = api_1.trace.getActiveSpan()?.spanContext().traceId;
+        return id && TRACE_ID.test(id) && id !== INVALID_TRACE ? id : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** The active span's id, or undefined outside a trace. */
+function getCurrentSpanId() {
+    try {
+        const id = api_1.trace.getActiveSpan()?.spanContext().spanId;
+        return id && SPAN_ID.test(id) && id !== '0'.repeat(16) ? id : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function validScore(score, scale) {
+    if (typeof score !== 'number' || !Number.isInteger(score))
+        return false;
+    if (scale === 'thumbs')
+        return score === 1 || score === -1;
+    if (scale === 'stars')
+        return score >= 1 && score <= 5;
+    return score === -1 || (score >= 1 && score <= 5);
+}
+/** Sends one rating. Resolves to whether Shield360 accepted it; never rejects. */
+async function feedback(options) {
+    try {
+        if (!options || typeof options !== 'object')
+            return false;
+        const traceId = (options.traceId || getCurrentTraceId() || '').toLowerCase();
+        if (!TRACE_ID.test(traceId) || traceId === INVALID_TRACE)
+            return false;
+        if (options.spanId && !SPAN_ID.test(options.spanId))
+            return false;
+        if (!validScore(options.score, options.scale))
+            return false;
+        const url = (options.url || config_1.default.shield360Url || process.env.SHIELD360_URL || '').trim().replace(/\/+$/, '');
+        const apiKey = (options.apiKey || config_1.default.shield360ApiKey || process.env.SHIELD360_API_KEY || '').trim();
+        if (!url || !apiKey)
+            return false;
+        const body = {
+            traceId,
+            score: options.score,
+            ...(options.spanId ? { spanId: options.spanId.toLowerCase() } : {}),
+            ...(options.scale ? { scale: options.scale } : {}),
+            ...(options.comment ? { comment: options.comment } : {}),
+            ...(options.userId ? { userId: options.userId } : {}),
+            ...(options.tenantId ? { tenantId: options.tenantId } : {}),
+            ...(options.metadata ? { metadata: options.metadata } : {}),
+            ...(options.feedbackId ? { feedbackId: options.feedbackId } : {}),
+            ...(defaults.app || config_1.default.applicationName ? { app: defaults.app || config_1.default.applicationName } : {}),
+            ...(defaults.release ? { release: defaults.release } : {}),
+        };
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), options.timeoutMs ?? 5000);
+        try {
+            const response = await fetch(`${url}/api/feedback`, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${apiKey}` },
+                body: JSON.stringify(body),
+                signal: controller.signal,
+            });
+            return response.ok;
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=index.js.map

package/dist/feedback/index.js.map

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

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

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