warning_sdk 1.0.0

package/dist/core/aggregator.d.ts

@@ -0,0 +1,28 @@
+import { MetricFields } from './bucket';
+import { WarningSDKConfig } from './config';
+import { Transport } from './transport';
+export declare class Aggregator {
+    private config;
+    private transport;
+    private currentBucket;
+    private flushTimer;
+    private pendingBuckets;
+    private sendLoop;
+    private degradedMinute;
+    private capFlushMinute;
+    private pausedUntilMs;
+    private readonly MAX_PENDING_BUCKETS;
+    private readonly DEGRADE_THRESHOLD;
+    constructor(config: WarningSDKConfig, transport: Transport);
+    isPaused(): boolean;
+    private pauseForMs;
+    private createNewBucket;
+    private rotateBucket;
+    private enqueueBucket;
+    private drainQueue;
+    record(fields: MetricFields): void;
+    private startFlushInterval;
+    flush(): Promise<void>;
+    private flushBucket;
+    shutdown(): Promise<void>;
+}

package/dist/core/aggregator.js

@@ -0,0 +1,163 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Aggregator = void 0;
+const bucket_1 = require("./bucket");
+class Aggregator {
+    constructor(config, transport) {
+        this.flushTimer = null;
+        this.pendingBuckets = [];
+        this.sendLoop = null;
+        this.degradedMinute = null;
+        this.capFlushMinute = null;
+        this.pausedUntilMs = 0;
+        this.MAX_PENDING_BUCKETS = 5;
+        this.DEGRADE_THRESHOLD = Math.floor(bucket_1.Bucket.MAX_TOTAL_KEYS * 0.8);
+        this.config = config;
+        this.transport = transport;
+        this.currentBucket = this.createNewBucket();
+        this.startFlushInterval();
+    }
+    isPaused() {
+        return Date.now() < this.pausedUntilMs;
+    }
+    pauseForMs(durationMs) {
+        const d = Number.isFinite(durationMs) ? Math.max(0, durationMs) : 0;
+        const next = Date.now() + (d || 300000);
+        if (next > this.pausedUntilMs)
+            this.pausedUntilMs = next;
+        // Drop queued data to avoid memory growth and unnecessary work.
+        this.pendingBuckets = [];
+        this.currentBucket = this.createNewBucket();
+        this.degradedMinute = null;
+        this.capFlushMinute = null;
+    }
+    createNewBucket(alignedTime) {
+        const time = alignedTime ?? Date.now();
+        const bucketTime = Math.floor(time / 60000) * 60000;
+        return new bucket_1.Bucket(bucketTime);
+    }
+    rotateBucket(nextAlignedTime) {
+        const bucketToSend = this.currentBucket;
+        this.currentBucket = this.createNewBucket(nextAlignedTime);
+        if (bucketToSend.timestamp !== nextAlignedTime) {
+            this.degradedMinute = null;
+            this.capFlushMinute = null;
+        }
+        return bucketToSend;
+    }
+    enqueueBucket(bucket) {
+        if (bucket.isEmpty())
+            return;
+        if (this.pendingBuckets.length >= this.MAX_PENDING_BUCKETS) {
+            this.pendingBuckets.shift();
+        }
+        this.pendingBuckets.push(bucket);
+    }
+    async drainQueue() {
+        if (this.sendLoop)
+            return this.sendLoop;
+        this.sendLoop = (async () => {
+            while (this.pendingBuckets.length > 0) {
+                const bucket = this.pendingBuckets.shift();
+                if (!bucket)
+                    continue;
+                try {
+                    await this.flushBucket(bucket);
+                }
+                catch {
+                    // Silently fail, data is dropped to prevent memory leaks/blocking
+                }
+            }
+        })().finally(() => {
+            this.sendLoop = null;
+            if (this.pendingBuckets.length > 0) {
+                void this.drainQueue();
+            }
+        });
+        return this.sendLoop;
+    }
+    record(fields) {
+        if (this.isPaused())
+            return;
+        const eventTime = fields.timestamp ?? Date.now();
+        const alignedTime = Math.floor(eventTime / 60000) * 60000;
+        if (this.currentBucket.timestamp !== alignedTime) {
+            const bucketToSend = this.rotateBucket(alignedTime);
+            this.enqueueBucket(bucketToSend);
+            void this.drainQueue();
+        }
+        const degrade = this.degradedMinute === alignedTime;
+        if (degrade) {
+            this.currentBucket.incrementDegraded(fields);
+        }
+        else {
+            this.currentBucket.increment(fields);
+        }
+        if (this.degradedMinute === null && this.currentBucket.size() >= this.DEGRADE_THRESHOLD) {
+            this.degradedMinute = alignedTime;
+        }
+        if (this.currentBucket.size() >= bucket_1.Bucket.MAX_TOTAL_KEYS) {
+            if (this.capFlushMinute !== alignedTime) {
+                this.capFlushMinute = alignedTime;
+                this.degradedMinute = alignedTime;
+                const bucketToSend = this.rotateBucket(alignedTime);
+                this.enqueueBucket(bucketToSend);
+                void this.drainQueue();
+            }
+        }
+    }
+    startFlushInterval() {
+        if (this.flushTimer)
+            clearInterval(this.flushTimer);
+        this.flushTimer = setInterval(() => {
+            void this.flush().catch(() => { });
+        }, 10000);
+        if (this.flushTimer.unref) {
+            this.flushTimer.unref();
+        }
+    }
+    async flush() {
+        if (this.currentBucket.isEmpty()) {
+            const nowAligned = Math.floor(Date.now() / 60000) * 60000;
+            if (this.currentBucket.timestamp !== nowAligned) {
+                this.currentBucket = new bucket_1.Bucket(nowAligned);
+                this.degradedMinute = null;
+                this.capFlushMinute = null;
+            }
+            await this.drainQueue();
+            return;
+        }
+        const nowAligned = Math.floor(Date.now() / 60000) * 60000;
+        const bucketToSend = this.rotateBucket(nowAligned);
+        this.enqueueBucket(bucketToSend);
+        await this.drainQueue();
+    }
+    async flushBucket(bucketToSend) {
+        if (bucketToSend.isEmpty())
+            return;
+        if (this.isPaused())
+            return;
+        const metricsWithTime = bucketToSend.toJSONWithMinute(bucketToSend.timestamp);
+        const maxRows = Math.min(2000, metricsWithTime.length);
+        for (let i = 0; i < metricsWithTime.length; i += maxRows) {
+            const payload = {
+                project_id: this.config.projectId,
+                project_token: this.config.projectToken,
+                sent_at: Date.now(),
+                metrics: metricsWithTime.slice(i, i + maxRows)
+            };
+            const res = await this.transport.send(payload);
+            if (res?.paused) {
+                this.pauseForMs(res.retryAfterMs || 300000);
+                return;
+            }
+        }
+    }
+    async shutdown() {
+        if (this.flushTimer) {
+            clearInterval(this.flushTimer);
+        }
+        await this.flush();
+    }
+}
+exports.Aggregator = Aggregator;

package/dist/core/bucket.d.ts

@@ -0,0 +1,41 @@
+export interface MetricFields {
+    serviceName?: string;
+    method: string;
+    route: string;
+    status: number;
+    apiKeyId?: string;
+    ipHash?: string;
+    uaHash?: string;
+    latencyMs?: number;
+    aborted?: boolean;
+    timestamp?: number;
+}
+export declare class Bucket {
+    timestamp: number;
+    counts: Map<string, {
+        count: number;
+        sumLatencyMs?: number;
+        minLatencyMs?: number;
+        maxLatencyMs?: number;
+        latencyHistogram?: Record<string, number>;
+    }>;
+    private ipTracking;
+    private overflowProtection;
+    private static MAX_UNIQUE_IPS;
+    static readonly MAX_TOTAL_KEYS = 2000;
+    private static readonly SEP;
+    private static readonly ESC;
+    constructor(timestamp: number);
+    private static escapePart;
+    private static unescapePart;
+    private static splitKey;
+    private static latencyBucket;
+    static generateKeyParts(serviceName: string, method: string, route: string, status: number, apiKeyId?: string, ipHash?: string, uaHash?: string): string;
+    private incrementInternal;
+    increment(fields: MetricFields): void;
+    incrementDegraded(fields: MetricFields): void;
+    isEmpty(): boolean;
+    size(): number;
+    toJSON(): any[];
+    toJSONWithMinute(minute: number): any[];
+}

package/dist/core/bucket.js

@@ -0,0 +1,237 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Bucket = void 0;
+class Bucket {
+    constructor(timestamp) {
+        this.ipTracking = new Map();
+        this.overflowProtection = new Set();
+        this.timestamp = timestamp;
+        this.counts = new Map();
+    }
+    static escapePart(value) {
+        let out = '';
+        for (let i = 0; i < value.length; i += 1) {
+            const ch = value[i];
+            if (ch === Bucket.ESC || ch === Bucket.SEP) {
+                out += Bucket.ESC;
+            }
+            out += ch;
+        }
+        return out;
+    }
+    static unescapePart(value) {
+        let out = '';
+        let escaped = false;
+        for (let i = 0; i < value.length; i += 1) {
+            const ch = value[i];
+            if (escaped) {
+                out += ch;
+                escaped = false;
+                continue;
+            }
+            if (ch === Bucket.ESC) {
+                escaped = true;
+                continue;
+            }
+            out += ch;
+        }
+        if (escaped)
+            return null;
+        return out;
+    }
+    static splitKey(key) {
+        const parts = [];
+        let current = '';
+        let escaped = false;
+        for (let i = 0; i < key.length; i += 1) {
+            const ch = key[i];
+            if (escaped) {
+                current += Bucket.ESC;
+                current += ch;
+                escaped = false;
+                continue;
+            }
+            if (ch === Bucket.ESC) {
+                escaped = true;
+                continue;
+            }
+            if (ch === Bucket.SEP) {
+                parts.push(current);
+                current = '';
+                continue;
+            }
+            current += ch;
+        }
+        if (escaped)
+            return null;
+        parts.push(current);
+        return parts;
+    }
+    static latencyBucket(ms) {
+        // Buckets must match backend parser:
+        // - "a-b" or "a+" (see warning_backend/analytics.py:_parse_bucket_range)
+        if (ms < 0)
+            ms = 0;
+        if (ms <= 10)
+            return "0-10";
+        if (ms <= 25)
+            return "10-25";
+        if (ms <= 50)
+            return "25-50";
+        if (ms <= 100)
+            return "50-100";
+        if (ms <= 200)
+            return "100-200";
+        if (ms <= 350)
+            return "200-350";
+        if (ms <= 500)
+            return "350-500";
+        if (ms <= 750)
+            return "500-750";
+        if (ms <= 1000)
+            return "750-1000";
+        if (ms <= 1500)
+            return "1000-1500";
+        if (ms <= 2000)
+            return "1500-2000";
+        if (ms <= 3000)
+            return "2000-3000";
+        if (ms <= 5000)
+            return "3000-5000";
+        return "5000+";
+    }
+    static generateKeyParts(serviceName, method, route, status, apiKeyId, ipHash, uaHash) {
+        const svc = serviceName || '';
+        const ak = apiKeyId || '';
+        const ip = ipHash || '';
+        const ua = uaHash || '';
+        return [
+            Bucket.escapePart(svc),
+            Bucket.escapePart(method),
+            Bucket.escapePart(route),
+            Bucket.escapePart(String(status)),
+            Bucket.escapePart(ak),
+            Bucket.escapePart(ip),
+            Bucket.escapePart(ua)
+        ].join(Bucket.SEP);
+    }
+    incrementInternal(fields, degraded) {
+        let ipHash = fields.ipHash || '';
+        if (!degraded && fields.ipHash) {
+            const guardKey = `${fields.serviceName || ''}|${fields.method}|${fields.route}|${fields.apiKeyId || 'none'}`;
+            if (this.overflowProtection.has(guardKey)) {
+                ipHash = 'MANY';
+            }
+            else {
+                let s = this.ipTracking.get(guardKey);
+                if (!s) {
+                    s = new Set();
+                    this.ipTracking.set(guardKey, s);
+                }
+                s.add(ipHash);
+                if (s.size > Bucket.MAX_UNIQUE_IPS) {
+                    this.overflowProtection.add(guardKey);
+                    this.ipTracking.delete(guardKey);
+                    ipHash = 'MANY';
+                }
+            }
+        }
+        const k = Bucket.generateKeyParts(fields.serviceName || '', fields.method, fields.route, fields.status, fields.apiKeyId, degraded ? undefined : ipHash, degraded ? undefined : fields.uaHash);
+        let current = this.counts.get(k);
+        if (!current) {
+            if (this.counts.size >= Bucket.MAX_TOTAL_KEYS) {
+                return;
+            }
+            current = { count: 0 };
+            this.counts.set(k, current);
+        }
+        current.count += 1;
+        if (Number.isFinite(fields.latencyMs)) {
+            const latency = fields.latencyMs;
+            current.sumLatencyMs = (current.sumLatencyMs || 0) + latency;
+            current.maxLatencyMs = current.maxLatencyMs === undefined ? latency : Math.max(current.maxLatencyMs, latency);
+            current.minLatencyMs = current.minLatencyMs === undefined ? latency : Math.min(current.minLatencyMs, latency);
+            const bucket = Bucket.latencyBucket(latency);
+            const hist = current.latencyHistogram || (current.latencyHistogram = {});
+            hist[bucket] = (hist[bucket] || 0) + 1;
+        }
+    }
+    increment(fields) {
+        this.incrementInternal(fields, false);
+    }
+    incrementDegraded(fields) {
+        this.incrementInternal(fields, true);
+    }
+    isEmpty() {
+        return this.counts.size === 0;
+    }
+    size() {
+        return this.counts.size;
+    }
+    toJSON() {
+        const metrics = [];
+        for (const [k, v] of this.counts.entries()) {
+            const parts = Bucket.splitKey(k);
+            if (!parts || parts.length !== 7)
+                continue;
+            const unescaped = parts.map(part => Bucket.unescapePart(part));
+            if (unescaped.some(part => part === null))
+                continue;
+            const [serviceName, method, route, statusRaw, apiKeyId, ipHash, uaHash] = unescaped;
+            const statusValue = parseInt(statusRaw, 10);
+            if (!Number.isFinite(statusValue))
+                continue;
+            metrics.push({
+                service_name: serviceName || undefined,
+                method,
+                route,
+                status: statusValue,
+                api_key_id: apiKeyId || undefined,
+                ip_hash: ipHash || undefined,
+                ua_hash: uaHash || undefined,
+                count: v.count,
+                sum_latency_ms: v.sumLatencyMs,
+                min_latency_ms: v.minLatencyMs,
+                max_latency_ms: v.maxLatencyMs,
+                latency_histogram: v.latencyHistogram && Object.keys(v.latencyHistogram).length ? v.latencyHistogram : undefined
+            });
+        }
+        return metrics;
+    }
+    toJSONWithMinute(minute) {
+        const metrics = [];
+        for (const [k, v] of this.counts.entries()) {
+            const parts = Bucket.splitKey(k);
+            if (!parts || parts.length !== 7)
+                continue;
+            const unescaped = parts.map(part => Bucket.unescapePart(part));
+            if (unescaped.some(part => part === null))
+                continue;
+            const [serviceName, method, route, statusRaw, apiKeyId, ipHash, uaHash] = unescaped;
+            const statusValue = parseInt(statusRaw, 10);
+            if (!Number.isFinite(statusValue))
+                continue;
+            metrics.push({
+                service_name: serviceName || undefined,
+                method,
+                route,
+                status: statusValue,
+                api_key_id: apiKeyId || undefined,
+                ip_hash: ipHash || undefined,
+                ua_hash: uaHash || undefined,
+                count: v.count,
+                sum_latency_ms: v.sumLatencyMs,
+                min_latency_ms: v.minLatencyMs,
+                max_latency_ms: v.maxLatencyMs,
+                latency_histogram: v.latencyHistogram && Object.keys(v.latencyHistogram).length ? v.latencyHistogram : undefined,
+                minute
+            });
+        }
+        return metrics;
+    }
+}
+exports.Bucket = Bucket;
+Bucket.MAX_UNIQUE_IPS = 50;
+Bucket.MAX_TOTAL_KEYS = 2000;
+Bucket.SEP = '\u001f';
+Bucket.ESC = '\\';

package/dist/core/client.d.ts

@@ -0,0 +1,22 @@
+import { WarningSDKConfig } from './config';
+export declare class WarningClient {
+    readonly config: WarningSDKConfig;
+    private aggregator;
+    private initialized;
+    constructor(config: Partial<WarningSDKConfig>);
+    isPaused(): boolean;
+    recordRequest(req: {
+        serviceName?: string;
+        method: string;
+        route: string;
+        status: number;
+        ip?: string;
+        userAgent?: string;
+        apiKeyId?: string;
+        authToken?: string;
+        aborted?: boolean;
+        latencyMs?: number;
+        timestamp?: number;
+    }): void;
+    flush(): Promise<void>;
+}

package/dist/core/client.js

@@ -0,0 +1,51 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WarningClient = void 0;
+const config_1 = require("./config");
+const aggregator_1 = require("./aggregator");
+const transport_1 = require("./transport");
+const privacy_1 = require("./privacy");
+class WarningClient {
+    constructor(config) {
+        this.initialized = false;
+        this.config = (0, config_1.validateConfig)(config);
+        const transport = new transport_1.Transport(this.config);
+        this.aggregator = new aggregator_1.Aggregator(this.config, transport);
+        this.initialized = true;
+    }
+    isPaused() {
+        return this.aggregator.isPaused();
+    }
+    recordRequest(req) {
+        if (!this.initialized)
+            return;
+        if (this.aggregator.isPaused())
+            return;
+        const serviceName = req.serviceName || this.config.serviceName;
+        let finalIpHash = req.ip ? privacy_1.Privacy.passThroughIp(req.ip) : undefined;
+        let finalUaHash = req.userAgent ? privacy_1.Privacy.passThroughUa(req.userAgent) : undefined;
+        let apiKeyId = req.apiKeyId;
+        if (!apiKeyId && req.authToken) {
+            apiKeyId = privacy_1.Privacy.passThroughApiKey(req.authToken);
+        }
+        let latencyMs = req.latencyMs;
+        if (!Number.isFinite(latencyMs) || latencyMs < 0 || latencyMs >= 120000) {
+            latencyMs = undefined;
+        }
+        this.aggregator.record({
+            serviceName: serviceName,
+            method: req.method.toUpperCase(),
+            route: req.route,
+            status: req.status,
+            apiKeyId: apiKeyId,
+            ipHash: finalIpHash,
+            uaHash: finalUaHash,
+            latencyMs: latencyMs,
+            timestamp: req.timestamp || Date.now()
+        });
+    }
+    flush() {
+        return this.aggregator.flush();
+    }
+}
+exports.WarningClient = WarningClient;

package/dist/core/config.d.ts

@@ -0,0 +1,18 @@
+export interface WarningSDKConfig {
+    projectId: string;
+    projectToken: string;
+    ingestKey: string;
+    serviceName?: string;
+    collectorUrl?: string;
+    /**
+     * Which inbound header contains the business's end-user API token.
+     * Used to derive `api_key_id` (hashed identifier) for key-sharing detection.
+     *
+     * Defaults to "authorization".
+     */
+    authHeaderName?: string;
+    debug?: boolean;
+    logger?: (level: 'debug' | 'info' | 'warn' | 'error', message: string) => void;
+}
+export declare const DEFAULT_CONFIG: Partial<WarningSDKConfig>;
+export declare function validateConfig(config: Partial<WarningSDKConfig>): WarningSDKConfig;

package/dist/core/config.js

@@ -0,0 +1,46 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_CONFIG = void 0;
+exports.validateConfig = validateConfig;
+exports.DEFAULT_CONFIG = {};
+function validateConfig(config) {
+    const sanitized = { ...config };
+    const merged = { ...exports.DEFAULT_CONFIG, ...sanitized };
+    const log = (level, message) => {
+        if (merged.logger) {
+            merged.logger(level, message);
+            return;
+        }
+        if (level === 'error') {
+            console.error(message);
+            return;
+        }
+        if (merged.debug) {
+            const fn = level === 'debug'
+                ? console.debug
+                : level === 'info'
+                    ? console.info
+                    : level === 'warn'
+                        ? console.warn
+                        : console.error;
+            fn(message);
+        }
+    };
+    if (!merged.projectId) {
+        log('error', "WarningSDK: Missing 'projectId'.");
+        throw new Error("WarningSDK: Missing required config 'projectId'.");
+    }
+    if (!merged.projectToken) {
+        log('error', "WarningSDK: Missing 'projectToken'.");
+        throw new Error("WarningSDK: Missing required config 'projectToken'.");
+    }
+    if (!merged.ingestKey) {
+        log('error', "WarningSDK: Missing 'ingestKey'.");
+        throw new Error("WarningSDK: Missing required config 'ingestKey'.");
+    }
+    if (!merged.collectorUrl) {
+        log('error', "WarningSDK: Missing 'collectorUrl' (Collector URL).");
+        throw new Error("WarningSDK: Missing required config 'collectorUrl'.");
+    }
+    return merged;
+}

package/dist/core/deterministicCrypto.d.ts

@@ -0,0 +1,8 @@
+export declare class DeterministicCrypto {
+    private encKey;
+    private macKey;
+    private nonceKey;
+    constructor(cryptoKey: string);
+    encryptDeterministic(value: string, aad: string): string;
+    decryptDeterministic(token: string, aad: string): string | null;
+}

package/dist/core/deterministicCrypto.js

@@ -0,0 +1,153 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DeterministicCrypto = void 0;
+const crypto = __importStar(require("crypto"));
+const VERSION_PREFIX = 'w1.';
+const VERSION_BYTE = 1;
+const SALT = Buffer.from('warning-crypto-v1', 'utf8');
+const INFO = Buffer.from('deterministic-v1', 'utf8');
+function toBase64Url(buf) {
+    return buf
+        .toString('base64')
+        .replace(/\+/g, '-')
+        .replace(/\//g, '_')
+        .replace(/=+$/g, '');
+}
+function fromBase64Url(s) {
+    const normalized = s.replace(/-/g, '+').replace(/_/g, '/');
+    const padLen = (4 - (normalized.length % 4)) % 4;
+    const padded = normalized + '='.repeat(padLen);
+    return Buffer.from(padded, 'base64');
+}
+function packParts(...parts) {
+    const out = [];
+    for (const part of parts) {
+        const len = Buffer.alloc(4);
+        len.writeUInt32BE(part.length, 0);
+        out.push(len, part);
+    }
+    return Buffer.concat(out);
+}
+function hmacSha256(key, data) {
+    return crypto.createHmac('sha256', key).update(data).digest();
+}
+function deriveKeys(masterKey) {
+    // HKDF-SHA256(masterKey, salt=SALT, info=INFO) -> 96 bytes
+    const okm = Buffer.from(crypto.hkdfSync('sha256', masterKey, SALT, INFO, 96));
+    return {
+        encKey: okm.subarray(0, 32),
+        macKey: okm.subarray(32, 64),
+        nonceKey: okm.subarray(64, 96),
+    };
+}
+function parseKeyString(key) {
+    const trimmed = (key || '').trim();
+    if (!trimmed)
+        throw new Error("WarningSDK: Missing required config 'cryptoKey'.");
+    if (trimmed.startsWith('hex:')) {
+        const hex = trimmed.slice(4).trim();
+        const buf = Buffer.from(hex, 'hex');
+        if (buf.length < 32)
+            throw new Error("WarningSDK: 'cryptoKey' (hex) must be at least 32 bytes.");
+        return buf;
+    }
+    // Accept base64 / base64url, with or without padding.
+    const buf = fromBase64Url(trimmed);
+    if (buf.length < 32)
+        throw new Error("WarningSDK: 'cryptoKey' (base64) must be at least 32 bytes.");
+    return buf;
+}
+function xorWithKeystream(encKey, nonce, data) {
+    const out = Buffer.alloc(data.length);
+    let offset = 0;
+    let counter = 0;
+    while (offset < data.length) {
+        const ctr = Buffer.alloc(4);
+        ctr.writeUInt32BE(counter >>> 0, 0);
+        const block = hmacSha256(encKey, Buffer.concat([nonce, ctr]));
+        const take = Math.min(block.length, data.length - offset);
+        for (let i = 0; i < take; i += 1) {
+            out[offset + i] = data[offset + i] ^ block[i];
+        }
+        offset += take;
+        counter += 1;
+    }
+    return out;
+}
+class DeterministicCrypto {
+    constructor(cryptoKey) {
+        const master = parseKeyString(cryptoKey);
+        const keys = deriveKeys(master);
+        this.encKey = keys.encKey;
+        this.macKey = keys.macKey;
+        this.nonceKey = keys.nonceKey;
+    }
+    encryptDeterministic(value, aad) {
+        if (!value)
+            return '';
+        const aadBuf = Buffer.from(aad || '', 'utf8');
+        const pt = Buffer.from(value, 'utf8');
+        const nonce = hmacSha256(this.nonceKey, packParts(aadBuf, pt)).subarray(0, 16);
+        const ct = xorWithKeystream(this.encKey, nonce, pt);
+        const tag = hmacSha256(this.macKey, packParts(aadBuf, nonce, ct)).subarray(0, 16);
+        const payload = Buffer.concat([Buffer.from([VERSION_BYTE]), nonce, ct, tag]);
+        return VERSION_PREFIX + toBase64Url(payload);
+    }
+    decryptDeterministic(token, aad) {
+        if (!token || !token.startsWith(VERSION_PREFIX))
+            return null;
+        const aadBuf = Buffer.from(aad || '', 'utf8');
+        const raw = fromBase64Url(token.slice(VERSION_PREFIX.length));
+        if (raw.length < 1 + 16 + 16)
+            return null;
+        if (raw[0] !== VERSION_BYTE)
+            return null;
+        const nonce = raw.subarray(1, 1 + 16);
+        const tag = raw.subarray(raw.length - 16);
+        const ct = raw.subarray(1 + 16, raw.length - 16);
+        const expected = hmacSha256(this.macKey, packParts(aadBuf, nonce, ct)).subarray(0, 16);
+        if (expected.length !== tag.length || !crypto.timingSafeEqual(expected, tag))
+            return null;
+        const pt = xorWithKeystream(this.encKey, nonce, ct);
+        try {
+            return pt.toString('utf8');
+        }
+        catch {
+            return null;
+        }
+    }
+}
+exports.DeterministicCrypto = DeterministicCrypto;

package/dist/core/privacy.d.ts

@@ -0,0 +1,5 @@
+export declare class Privacy {
+    static passThroughIp(ip: string): string | undefined;
+    static passThroughApiKey(rawKey: string): string | undefined;
+    static passThroughUa(ua: string): string | undefined;
+}

package/dist/core/privacy.js

@@ -0,0 +1,18 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Privacy = void 0;
+class Privacy {
+    static passThroughIp(ip) {
+        const v = (ip || '').trim();
+        return v.length ? v : undefined;
+    }
+    static passThroughApiKey(rawKey) {
+        const v = (rawKey || '').trim();
+        return v.length ? v : undefined;
+    }
+    static passThroughUa(ua) {
+        const v = (ua || '').trim();
+        return v.length ? v : undefined;
+    }
+}
+exports.Privacy = Privacy;

package/dist/core/transport.d.ts

@@ -0,0 +1,12 @@
+import { WarningSDKConfig } from './config';
+export type TransportSendResult = {
+    paused?: boolean;
+    reason?: string;
+    retryAfterMs?: number;
+    statusCode?: number;
+};
+export declare class Transport {
+    private config;
+    constructor(config: WarningSDKConfig);
+    send(payload: any): Promise<TransportSendResult>;
+}

package/dist/core/transport.js

@@ -0,0 +1,107 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Transport = void 0;
+const http = __importStar(require("http"));
+const https = __importStar(require("https"));
+class Transport {
+    constructor(config) {
+        this.config = config;
+    }
+    async send(payload) {
+        if (!this.config.projectToken)
+            return {};
+        const data = JSON.stringify(payload);
+        let url;
+        try {
+            url = new URL(this.config.collectorUrl || '');
+        }
+        catch {
+            return {};
+        }
+        const isHttps = url.protocol === 'https:';
+        const options = {
+            hostname: url.hostname,
+            port: url.port || (isHttps ? 443 : 80),
+            path: `${url.pathname}${url.search}`,
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                'Content-Length': Buffer.byteLength(data),
+                'x-ingest-key': this.config.ingestKey,
+                'User-Agent': 'warning-sdk-node/1.0.0'
+            },
+            timeout: 2000
+        };
+        return new Promise((resolve) => {
+            const requester = isHttps ? https : http;
+            const req = requester.request(options, (res) => {
+                const statusCode = res.statusCode || 0;
+                let body = '';
+                res.setEncoding('utf8');
+                res.on('data', (chunk) => {
+                    if (body.length <= 8192)
+                        body += chunk;
+                });
+                res.on('end', () => {
+                    const out = { statusCode };
+                    // Default behavior: treat as "sent" even if backend rejected (so app never breaks).
+                    // But if backend says credits are 0, we pause sending on the SDK side.
+                    try {
+                        const parsed = JSON.parse(body || '{}');
+                        const paused = Boolean(parsed?.paused) || statusCode === 402;
+                        if (paused) {
+                            out.paused = true;
+                            out.reason = String(parsed?.reason || 'paused');
+                            const retry = parsed?.retry_after_ms;
+                            if (Number.isFinite(retry) && retry > 0)
+                                out.retryAfterMs = Number(retry);
+                        }
+                    }
+                    catch {
+                        // ignore
+                    }
+                    resolve(out);
+                });
+            });
+            req.on('error', () => {
+                resolve({});
+            });
+            req.write(data);
+            req.end();
+        });
+    }
+}
+exports.Transport = Transport;

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export * from './core/config';
+export * from './core/client';
+export * from './core/bucket';
+export * from './core/aggregator';
+export * from './platforms/express';
+export { warning as default } from './platforms/express';

package/dist/index.js

@@ -0,0 +1,27 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = void 0;
+__exportStar(require("./core/config"), exports);
+__exportStar(require("./core/client"), exports);
+__exportStar(require("./core/bucket"), exports);
+__exportStar(require("./core/aggregator"), exports);
+__exportStar(require("./platforms/express"), exports);
+// export * from './platforms/fastify';
+// export * from './platforms/nestjs';
+// export * from './platforms/next';
+var express_1 = require("./platforms/express");
+Object.defineProperty(exports, "default", { enumerable: true, get: function () { return express_1.warning; } });

package/dist/platforms/express.d.ts

@@ -0,0 +1,5 @@
+import { Request, Response, NextFunction } from 'express';
+import { WarningClient } from '../core/client';
+import { WarningSDKConfig } from '../core/config';
+export declare function warningMiddleware(config: Partial<WarningSDKConfig> | WarningClient): (req: Request, res: Response, next: NextFunction) => void;
+export declare function warning(config: Partial<WarningSDKConfig> | WarningClient): (req: Request, res: Response, next: NextFunction) => void;

package/dist/platforms/express.js

@@ -0,0 +1,102 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.warningMiddleware = warningMiddleware;
+exports.warning = warning;
+const client_1 = require("../core/client");
+function warningMiddleware(config) {
+    const client = config instanceof client_1.WarningClient ? config : new client_1.WarningClient(config);
+    return (req, res, next) => {
+        if (client.isPaused()) {
+            return next();
+        }
+        const startTime = process.hrtime.bigint();
+        let recorded = false;
+        const record = () => {
+            if (recorded)
+                return;
+            recorded = true;
+            try {
+                const method = req.method;
+                const statusCode = res.statusCode;
+                const aborted = req.aborted || !res.writableEnded;
+                let routePath = 'UNKNOWN';
+                if (req.route && req.route.path) {
+                    routePath = req.baseUrl ? (req.baseUrl + req.route.path) : req.route.path;
+                }
+                else {
+                    const fullPath = (req.baseUrl || '') + (req.path || '');
+                    const segments = fullPath.split('/').map((segment) => {
+                        if (!segment)
+                            return segment; // empty
+                        if (/^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$/.test(segment)) {
+                            return ':uuid';
+                        }
+                        if (/^[0-9a-fA-F]{24,}$/.test(segment)) {
+                            return ':hex_id';
+                        }
+                        if (/^\d+$/.test(segment)) {
+                            return ':id';
+                        }
+                        if (segment.length >= 26) {
+                            if (/[0-9]/.test(segment)) {
+                                return ':id_str';
+                            }
+                        }
+                        if (segment.length >= 20 && /[-_]/.test(segment)) {
+                            return ':id_str';
+                        }
+                        return segment;
+                    });
+                    routePath = segments.join('/');
+                }
+                if (!routePath || routePath === 'UNKNOWN') {
+                    routePath = 'RAW_PATH_UNAVAILABLE';
+                }
+                // If behind a proxy/CDN, enable: app.set('trust proxy', true)
+                let ip = req.ip;
+                if (ip) {
+                    ip = ip.trim();
+                }
+                if (!ip || ip.length === 0)
+                    ip = undefined;
+                const authHeaderName = (client.config.authHeaderName || 'authorization').toLowerCase();
+                const authHeader = req.headers[authHeaderName];
+                let authToken;
+                if (authHeader) {
+                    let raw = Array.isArray(authHeader) ? authHeader[0] : authHeader;
+                    if (raw.toLowerCase().startsWith('bearer ')) {
+                        raw = raw.substring(7).trim();
+                    }
+                    if (raw.toLowerCase().startsWith('token ')) {
+                        raw = raw.substring(6).trim();
+                    }
+                    if (raw.length > 0) {
+                        authToken = raw;
+                    }
+                }
+                const userAgent = req.headers['user-agent'];
+                const endTime = process.hrtime.bigint();
+                const latencyMs = Number((endTime - startTime) / BigInt(1000000));
+                client.recordRequest({
+                    serviceName: client.config.serviceName,
+                    method: method,
+                    route: routePath,
+                    status: statusCode,
+                    ip: ip,
+                    userAgent: userAgent,
+                    authToken: authToken,
+                    aborted: aborted,
+                    latencyMs: latencyMs,
+                    timestamp: Date.now()
+                });
+            }
+            catch (e) { }
+        };
+        res.once('finish', record);
+        res.once('close', record);
+        next();
+    };
+}
+function warning(config) {
+    return warningMiddleware(config);
+}

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "warning_sdk",
+  "version": "1.0.0",
+  "description": "",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "example:simple-server": "ts-node examples/simple-server.ts",
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "keywords": [],
+  "author": "",
+  "license": "ISC",
+  "type": "commonjs",
+  "devDependencies": {
+    "@nestjs/common": "^11.1.9",
+    "@nestjs/core": "^11.1.9",
+    "@nestjs/platform-express": "^11.1.9",
+    "@types/express": "^5.0.6",
+    "@types/node": "^25.0.3",
+    "@types/react": "^19.2.7",
+    "@types/react-dom": "^19.2.3",
+    "fastify": "^5.6.2",
+    "fastify-plugin": "^5.1.0",
+    "next": "^16.1.0",
+    "react": "^19.2.3",
+    "react-dom": "^19.2.3",
+    "reflect-metadata": "^0.2.2",
+    "rxjs": "^7.8.2",
+    "ts-node": "^10.9.2",
+    "typescript": "^5.9.3",
+    "express": "^5.2.1"
+  },
+  "peerDependencies": {
+    "express": ">=4"
+  }
+}