neosigma-sdk 0.0.1 → 0.1.0

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2025
+Copyright (c) 2026 NeoSigma Inc.
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal
@@ -19,4 +19,3 @@ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
-

package/README.md

@@ -1,15 +1,53 @@
 # neosigma-sdk
 
-Placeholder package for the neosigma-sdk project.
+NeoSigma TypeScript SDK. Emit product events that join your agent traces on
+`run_id`, in NeoSigma's own telemetry store.
 
-This is a dummy package published to reserve the package name on npm. The actual project will be published here in the future.
+## Quick start
 
-## Installation
+```ts
+import { init, trace, capture, identify, installShutdownHandlers } from "neosigma-sdk";
 
-```bash
-npm install neosigma-sdk
+init(); // reads NEOSIGMA_API_KEY / NEOSIGMA_EVENTS_ENDPOINT; dark without a key
+installShutdownHandlers(); // flush queued events on SIGTERM/SIGINT
+
+await trace({ runId: run.id, distinctId: userId }, async () => {
+  identify(userId, { plan: "pro" });
+  capture("message sent", { length: text.length });
+});
 ```
 
-## Note
+## How it joins
+
+`run_id` is the durable join key back to the agent's spans. Bind it once with
+`trace({ runId })`; every `capture()` inside that scope carries it, so product
+events sit next to the model's spans for the same run in ClickHouse. The ingest
+resolves your API key to an `org_id` server-side (the client never sends it).
+
+## Configuration
+
+| Env var | Default | Purpose |
+| --- | --- | --- |
+| `NEOSIGMA_API_KEY` | (none) | API key. Without it the SDK stays dark (a no-op). |
+| `NEOSIGMA_EVENTS_ENDPOINT` | `https://otel.neosigma.ai/v1/events` | Where events are POSTed. |
+| `NEOSIGMA_ENABLED` | `true` | Master switch. Set `false` to disable. |
+
+Pass the same values to `init({ apiKey, eventsEndpoint, enabled })` to override
+the environment.
+
+## Guarantees
+
+- **Fail-open.** Telemetry never throws into your code; `capture()` is non-blocking.
+  Network errors are swallowed and counted; a dead key disables the sink rather than hammering the ingest.
+- **Per-request identity.** Correlation ids live in `AsyncLocalStorage`, so
+  concurrent requests never leak ids into each other. Give each distinct actor
+  its own `trace()` scope.
+- **Scalar properties.** Property values are coerced to strings, finite numbers,
+  or booleans at the boundary, so a stray `null` or nested object can never
+  reject a batch.
+
+## Correlation across processes
 
-This package is currently a placeholder. Please check back later for the actual project release.
+`AsyncLocalStorage` does not cross a queue or process hop. When you hand work to
+another service or a background job, pass `run.id` in the payload and re-bind it
+on the far side with `trace({ runId })` (the Python SDK follows the same rule).

package/dist/config.d.ts

@@ -0,0 +1,19 @@
+export declare const DEFAULT_EVENTS_ENDPOINT = "https://otel.neosigma.ai/v1/events";
+export interface ResolvedConfig {
+    apiKey: string;
+    eventsEndpoint: string;
+    enabled: boolean;
+}
+type Env = Record<string, string | undefined>;
+/**
+ * Resolve config from code overrides then NEOSIGMA_* env, with documented
+ * defaults. Mirrors the Python Settings (env_prefix NEOSIGMA_).
+ */
+export declare function resolveConfig(overrides?: {
+    apiKey?: string;
+    eventsEndpoint?: string;
+    enabled?: boolean;
+}, env?: Env): ResolvedConfig;
+/** Dark-by-default: emit only when enabled AND an API key is present. */
+export declare function isEnabled(c: ResolvedConfig): boolean;
+export {};

package/dist/config.js

@@ -0,0 +1,18 @@
+export const DEFAULT_EVENTS_ENDPOINT = "https://otel.neosigma.ai/v1/events";
+/**
+ * Resolve config from code overrides then NEOSIGMA_* env, with documented
+ * defaults. Mirrors the Python Settings (env_prefix NEOSIGMA_).
+ */
+export function resolveConfig(overrides = {}, env = process.env) {
+    return {
+        apiKey: overrides.apiKey ?? env.NEOSIGMA_API_KEY ?? "",
+        eventsEndpoint: overrides.eventsEndpoint ??
+            env.NEOSIGMA_EVENTS_ENDPOINT ??
+            DEFAULT_EVENTS_ENDPOINT,
+        enabled: overrides.enabled ?? env.NEOSIGMA_ENABLED !== "false",
+    };
+}
+/** Dark-by-default: emit only when enabled AND an API key is present. */
+export function isEnabled(c) {
+    return c.enabled && c.apiKey !== "";
+}

package/dist/context.d.ts

@@ -0,0 +1,34 @@
+/** The ambient run-correlation ids: the join spine for events + spans. */
+export interface Correlation {
+    runId: string;
+    distinctId: string;
+    sessionId: string;
+}
+export declare function currentRunId(): string;
+export declare function currentDistinctId(): string;
+export declare function currentSessionId(): string;
+/**
+ * Run `fn` with the given correlation ids bound (only non-empty ones overlay the
+ * parent scope), returning `fn`'s value. AsyncLocalStorage propagates the store
+ * across awaits within this async context, but NOT across a process/queue hop:
+ * thread runId into the job payload and re-bind it on the far side, exactly as
+ * the Python SDK requires.
+ *
+ * Each distinct actor should own its own `trace()` frame. `setDistinctId` mutates
+ * the current frame's store, so fanning out concurrent sub-tasks that each
+ * identify a different user UNDER ONE shared frame would clobber (last writer
+ * wins); give each its own `trace({ distinctId })` frame instead.
+ */
+export declare function trace<T>(opts: {
+    runId?: string;
+    distinctId?: string;
+    sessionId?: string;
+}, fn: () => T): T;
+/**
+ * Bind distinct_id for the rest of the current `trace()` scope (login -> later
+ * events), with no scoped reset, mirroring the Python set_distinct_id. Mutating
+ * the live store keeps it per-async-context (safe under concurrency when each
+ * actor owns its own frame). Outside any `trace()` scope there is no safe place
+ * to persist it in a shared server, so this no-ops with a rate-limited warning.
+ */
+export declare function setDistinctId(distinctId: string): void;

package/dist/context.js

@@ -0,0 +1,63 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import { crossedWarnBoundary } from "./warn.js";
+const als = new AsyncLocalStorage();
+// Out-of-scope setDistinctId/identify drops: rate-limit the warning so loss is
+// observable on a long-lived server (a one-shot warning would go silent for the
+// life of the container after the first stray call).
+let outsideScopeDrops = 0;
+function store() {
+    return als.getStore();
+}
+export function currentRunId() {
+    return store()?.runId ?? "";
+}
+export function currentDistinctId() {
+    return store()?.distinctId ?? "";
+}
+export function currentSessionId() {
+    return store()?.sessionId ?? "";
+}
+/**
+ * Run `fn` with the given correlation ids bound (only non-empty ones overlay the
+ * parent scope), returning `fn`'s value. AsyncLocalStorage propagates the store
+ * across awaits within this async context, but NOT across a process/queue hop:
+ * thread runId into the job payload and re-bind it on the far side, exactly as
+ * the Python SDK requires.
+ *
+ * Each distinct actor should own its own `trace()` frame. `setDistinctId` mutates
+ * the current frame's store, so fanning out concurrent sub-tasks that each
+ * identify a different user UNDER ONE shared frame would clobber (last writer
+ * wins); give each its own `trace({ distinctId })` frame instead.
+ */
+export function trace(opts, fn) {
+    const parent = store();
+    const merged = {
+        runId: opts.runId || parent?.runId || "",
+        distinctId: opts.distinctId || parent?.distinctId || "",
+        sessionId: opts.sessionId || parent?.sessionId || "",
+    };
+    return als.run(merged, fn);
+}
+/**
+ * Bind distinct_id for the rest of the current `trace()` scope (login -> later
+ * events), with no scoped reset, mirroring the Python set_distinct_id. Mutating
+ * the live store keeps it per-async-context (safe under concurrency when each
+ * actor owns its own frame). Outside any `trace()` scope there is no safe place
+ * to persist it in a shared server, so this no-ops with a rate-limited warning.
+ */
+export function setDistinctId(distinctId) {
+    if (!distinctId)
+        return;
+    const current = store();
+    if (current) {
+        current.distinctId = distinctId;
+        return;
+    }
+    const prev = outsideScopeDrops;
+    outsideScopeDrops += 1;
+    if (crossedWarnBoundary(prev, 1)) {
+        console.warn(`[neosigma] setDistinctId/identify called outside a trace() scope ` +
+            `(${outsideScopeDrops} dropped); ignored. Wrap request handling in ` +
+            `trace({ runId }, ...) so identity stays per-request.`);
+    }
+}

package/dist/events.d.ts

@@ -0,0 +1,52 @@
+/**
+ * The product-event wire contract: types that cross SDK -> sink -> ingest.
+ *
+ * These names ARE the cross-package contract. They mirror
+ * neosigma_sdk.events.models.ProductEvent and
+ * neosigma_otel_ingest.events_store.EventIngest field-for-field (snake_case).
+ * Renaming a field here silently breaks ingest, so treat the names as frozen
+ * and change them in lockstep with the Python contract. The guard is structural:
+ * contract/wire_fields.json is generated from the Python model and pinned by a
+ * Python sync test; test/parity.test.ts pins WIRE_FIELDS against that fixture.
+ *
+ * org_id is intentionally absent: it is authoritative server-side (resolved
+ * from the API key by the ingest), never client-supplied.
+ */
+/** Scalar property values, matching the Python PropertyValue union. */
+export type PropertyValue = string | number | boolean;
+export interface ProductEvent {
+    /** Idempotency key, minted client-side (UUIDv4 string). */
+    event_uuid: string;
+    /** The product event name (e.g. "message sent"). */
+    event_name: string;
+    /** Analytics actor; "" when anonymous. */
+    distinct_id: string;
+    /** Durable join key back to agent spans; "" outside a correlated run. */
+    run_id: string;
+    /** Optional framework/session id. */
+    session_id: string;
+    /** Best-effort OTel trace id; "" when no active span. */
+    trace_id: string;
+    /** Event time in unix nanoseconds. bigint: ns exceeds Number safe range. */
+    timestamp_ns: bigint;
+    /** Scalar event properties (coerced to scalars at the capture boundary). */
+    properties: Record<string, PropertyValue>;
+}
+export interface EventBatch {
+    events: ProductEvent[];
+}
+/**
+ * The frozen wire field set. Pinned against the Python-derived
+ * contract/wire_fields.json by test/parity.test.ts.
+ */
+export declare const WIRE_FIELDS: readonly string[];
+/**
+ * Serialize a batch to the exact JSON the sink POSTs. This is the wire-encoding
+ * boundary, so it lives with the contract it encodes. The bigint timestamp_ns is
+ * emitted as a quoted decimal string ("1750..."); the ingest's Pydantic int
+ * field coerces it back to an exact integer (pinned by the Python regression
+ * test). JSON.stringify cannot encode a bigint, so the replacer stringifies it;
+ * every other value (including finite numbers) passes through unchanged, so a
+ * numeric property stays a bare JSON number and survives as an int.
+ */
+export declare function serializeBatch(batch: EventBatch): string;

package/dist/events.js

@@ -0,0 +1,40 @@
+/**
+ * The product-event wire contract: types that cross SDK -> sink -> ingest.
+ *
+ * These names ARE the cross-package contract. They mirror
+ * neosigma_sdk.events.models.ProductEvent and
+ * neosigma_otel_ingest.events_store.EventIngest field-for-field (snake_case).
+ * Renaming a field here silently breaks ingest, so treat the names as frozen
+ * and change them in lockstep with the Python contract. The guard is structural:
+ * contract/wire_fields.json is generated from the Python model and pinned by a
+ * Python sync test; test/parity.test.ts pins WIRE_FIELDS against that fixture.
+ *
+ * org_id is intentionally absent: it is authoritative server-side (resolved
+ * from the API key by the ingest), never client-supplied.
+ */
+/**
+ * The frozen wire field set. Pinned against the Python-derived
+ * contract/wire_fields.json by test/parity.test.ts.
+ */
+export const WIRE_FIELDS = [
+    "event_uuid",
+    "event_name",
+    "distinct_id",
+    "run_id",
+    "session_id",
+    "trace_id",
+    "timestamp_ns",
+    "properties",
+];
+/**
+ * Serialize a batch to the exact JSON the sink POSTs. This is the wire-encoding
+ * boundary, so it lives with the contract it encodes. The bigint timestamp_ns is
+ * emitted as a quoted decimal string ("1750..."); the ingest's Pydantic int
+ * field coerces it back to an exact integer (pinned by the Python regression
+ * test). JSON.stringify cannot encode a bigint, so the replacer stringifies it;
+ * every other value (including finite numbers) passes through unchanged, so a
+ * numeric property stays a bare JSON number and survives as an int.
+ */
+export function serializeBatch(batch) {
+    return JSON.stringify(batch, (_key, value) => typeof value === "bigint" ? value.toString() : value);
+}

package/dist/index.d.ts

@@ -0,0 +1,31 @@
+export { trace } from "./context.js";
+export { installShutdownHandlers } from "./sink.js";
+export type { ProductEvent, PropertyValue } from "./events.js";
+export type { EventSink } from "./sink.js";
+/**
+ * Initialize the SDK. Idempotent. Installs the production HTTP sink when an API
+ * key is configured and enabled; otherwise stays dark (the default BufferSink,
+ * a no-op for the host). Never throws. To flush on shutdown, also call
+ * installShutdownHandlers() once at boot.
+ */
+export declare function init(overrides?: {
+    apiKey?: string;
+    eventsEndpoint?: string;
+    enabled?: boolean;
+}): void;
+/**
+ * Emit a product event, stamped with the ambient run-correlation ids (bound by
+ * trace()). Mints an idempotency event_uuid and a call-site timestamp, and
+ * sanitizes properties to wire-safe scalars. Fail-open: never throws.
+ */
+export declare function capture(eventName: string, properties?: Record<string, unknown>): void;
+/**
+ * Bind distinct_id for subsequent events in the current trace() scope and emit a
+ * $identify event. Call once per request after auth, inside a trace() scope.
+ * Fail-open.
+ */
+export declare function identify(distinctId: string, properties?: Record<string, unknown>): void;
+/** Flush queued events (best-effort). Call before a serverless invocation ends. */
+export declare function flush(): Promise<void>;
+/** Stop the sink's flush loop, flush remaining events, and reset to dark. */
+export declare function shutdown(): Promise<void>;

package/dist/index.js

@@ -0,0 +1,80 @@
+import { randomUUID } from "node:crypto";
+import { isEnabled, resolveConfig } from "./config.js";
+import { currentDistinctId, currentRunId, currentSessionId, setDistinctId, } from "./context.js";
+import { coerceProperties } from "./properties.js";
+import { HttpEventSink, getEventSink, resetSink, setEventSink } from "./sink.js";
+import { nowNs } from "./time.js";
+export { trace } from "./context.js";
+export { installShutdownHandlers } from "./sink.js";
+let initialized = false;
+/**
+ * Initialize the SDK. Idempotent. Installs the production HTTP sink when an API
+ * key is configured and enabled; otherwise stays dark (the default BufferSink,
+ * a no-op for the host). Never throws. To flush on shutdown, also call
+ * installShutdownHandlers() once at boot.
+ */
+export function init(overrides) {
+    if (initialized)
+        return;
+    initialized = true;
+    try {
+        const cfg = resolveConfig(overrides);
+        if (!isEnabled(cfg))
+            return; // dark-by-default
+        setEventSink(new HttpEventSink({ endpoint: cfg.eventsEndpoint, apiKey: cfg.apiKey }));
+    }
+    catch {
+        /* fail-open: degrade to dark, never break the host */
+    }
+}
+/**
+ * Emit a product event, stamped with the ambient run-correlation ids (bound by
+ * trace()). Mints an idempotency event_uuid and a call-site timestamp, and
+ * sanitizes properties to wire-safe scalars. Fail-open: never throws.
+ */
+export function capture(eventName, properties) {
+    try {
+        const event = {
+            event_uuid: randomUUID(),
+            event_name: eventName,
+            distinct_id: currentDistinctId(),
+            run_id: currentRunId(),
+            session_id: currentSessionId(),
+            trace_id: "", // populated only if a TS OTel span integration is added later
+            timestamp_ns: nowNs(),
+            properties: coerceProperties(properties),
+        };
+        getEventSink().emit(event);
+    }
+    catch {
+        /* fail-open */
+    }
+}
+/**
+ * Bind distinct_id for subsequent events in the current trace() scope and emit a
+ * $identify event. Call once per request after auth, inside a trace() scope.
+ * Fail-open.
+ */
+export function identify(distinctId, properties) {
+    try {
+        setDistinctId(distinctId);
+        capture("$identify", properties);
+    }
+    catch {
+        /* fail-open */
+    }
+}
+/** Flush queued events (best-effort). Call before a serverless invocation ends. */
+export async function flush() {
+    try {
+        await getEventSink().flush?.();
+    }
+    catch {
+        /* fail-open */
+    }
+}
+/** Stop the sink's flush loop, flush remaining events, and reset to dark. */
+export async function shutdown() {
+    await resetSink();
+    initialized = false;
+}

package/dist/properties.d.ts

@@ -0,0 +1,17 @@
+import type { PropertyValue } from "./events.js";
+/**
+ * Coerce arbitrary caller-supplied property values into wire-safe scalars.
+ *
+ * `PropertyValue` is a compile-time type only; JS does not enforce it at
+ * runtime, so a caller can pass `null`, `NaN`, a nested object, etc. Sending any
+ * of those would make the ingest's Pydantic model reject the ENTIRE batch (the
+ * sink is fail-open and never inspects status, so the whole batch is silently
+ * lost). This boundary guarantees every emitted value is a `string`, a finite
+ * `number`, or a `boolean`, which the ingest always accepts.
+ *
+ * Rules: finite scalars pass through; `undefined`/`null`/functions/symbols are
+ * dropped (no meaningful scalar); non-finite numbers and bigints are stringified;
+ * `Date`s become a bare ISO-8601 string; other objects/arrays are JSON-stringified
+ * (best-effort, dropped if not serializable).
+ */
+export declare function coerceProperties(props: Record<string, unknown> | undefined): Record<string, PropertyValue>;

package/dist/properties.js

@@ -0,0 +1,57 @@
+/**
+ * Coerce arbitrary caller-supplied property values into wire-safe scalars.
+ *
+ * `PropertyValue` is a compile-time type only; JS does not enforce it at
+ * runtime, so a caller can pass `null`, `NaN`, a nested object, etc. Sending any
+ * of those would make the ingest's Pydantic model reject the ENTIRE batch (the
+ * sink is fail-open and never inspects status, so the whole batch is silently
+ * lost). This boundary guarantees every emitted value is a `string`, a finite
+ * `number`, or a `boolean`, which the ingest always accepts.
+ *
+ * Rules: finite scalars pass through; `undefined`/`null`/functions/symbols are
+ * dropped (no meaningful scalar); non-finite numbers and bigints are stringified;
+ * `Date`s become a bare ISO-8601 string; other objects/arrays are JSON-stringified
+ * (best-effort, dropped if not serializable).
+ */
+export function coerceProperties(props) {
+    const out = {};
+    if (!props)
+        return out;
+    for (const [key, value] of Object.entries(props)) {
+        const coerced = coerceValue(value);
+        if (coerced !== undefined)
+            out[key] = coerced;
+    }
+    return out;
+}
+function coerceValue(value) {
+    switch (typeof value) {
+        case "string":
+        case "boolean":
+            return value;
+        case "number":
+            return Number.isFinite(value) ? value : String(value);
+        case "bigint":
+            return value.toString();
+        case "undefined":
+        case "symbol":
+        case "function":
+            return undefined;
+        case "object":
+            if (value === null)
+                return undefined;
+            // A Date via JSON.stringify would arrive as a double-quoted ISO string
+            // ('"2026-..."'); emit the bare ISO-8601 string instead.
+            if (value instanceof Date) {
+                return Number.isNaN(value.getTime()) ? undefined : value.toISOString();
+            }
+            try {
+                return JSON.stringify(value);
+            }
+            catch {
+                return undefined; // circular / non-serializable: drop rather than throw
+            }
+        default:
+            return undefined;
+    }
+}

package/dist/sink.d.ts

@@ -0,0 +1,62 @@
+import { type ProductEvent } from "./events.js";
+/** Where capture() hands a built event. flush/shutdown are optional. */
+export interface EventSink {
+    emit(event: ProductEvent): void;
+    flush?(): Promise<void>;
+    shutdown?(): Promise<void>;
+}
+/** Default in-process sink: a bounded buffer for tests / dark mode. */
+export declare class BufferSink implements EventSink {
+    private readonly maxlen;
+    private events;
+    constructor(maxlen?: number);
+    emit(event: ProductEvent): void;
+    drain(): ProductEvent[];
+}
+/** Bounded, background-flushing sink that POSTs event batches to the ingest. */
+export declare class HttpEventSink implements EventSink {
+    private readonly endpoint;
+    private readonly apiKey;
+    private readonly maxQueue;
+    private readonly batchSize;
+    private readonly timeoutMs;
+    private readonly schemeOk;
+    private queue;
+    private timer;
+    private activeFlush;
+    /** Total events dropped (queue-full, non-http endpoint, disabled, or post error). */
+    dropped: number;
+    /** Set when a 401/403 marks the key dead; the sink then stops POSTing. */
+    disabled: boolean;
+    constructor(opts: {
+        endpoint: string;
+        apiKey: string;
+        maxQueue?: number;
+        batchSize?: number;
+        flushIntervalMs?: number;
+        timeoutMs?: number;
+    });
+    emit(event: ProductEvent): void;
+    flush(): Promise<void>;
+    shutdown(): Promise<void>;
+    private stopTimer;
+    private recordDropped;
+    private post;
+}
+export declare function setEventSink(sink: EventSink): void;
+export declare function getEventSink(): EventSink;
+export declare function flushSink(): Promise<void>;
+export declare function resetSink(): Promise<void>;
+/**
+ * Opt-in: flush queued events on SIGTERM/SIGINT (Cloud Run sends SIGTERM before
+ * stopping an instance, e.g. on every deploy/scale-in). Without this, the
+ * trailing queue is lost on teardown. Idempotent. The host calls this once at
+ * boot; left opt-in so a library import never installs process handlers behind
+ * the host's back.
+ *
+ * Registered with `once`, and after the flush the signal is re-raised to the
+ * (now listener-less) process so Node's default handler terminates it. Without
+ * the re-raise, installing a handler suppresses the default exit and the process
+ * would hang if any other handle (e.g. an HTTP server) is still open.
+ */
+export declare function installShutdownHandlers(proc?: NodeJS.Process): void;

package/dist/sink.js

@@ -0,0 +1,238 @@
+import { serializeBatch } from "./events.js";
+import { crossedWarnBoundary } from "./warn.js";
+const API_KEY_HEADER = "X-Neosigma-API-Key";
+const ALLOWED_SCHEMES = new Set(["http:", "https:"]);
+// Sink tunables. Genuine constants, not env-config: a client SDK's queue/batch
+// shape is a property of the SDK, not something a host tunes per deploy. Named
+// (not inline literals) so the values are discoverable in one place; the two
+// caps are distinct concerns that merely share a number today.
+const DEFAULT_MAX_QUEUE = 10_000; // HttpEventSink backpressure cap (events)
+const DEFAULT_BUFFER_MAXLEN = 10_000; // BufferSink ring cap (events)
+const DEFAULT_BATCH_SIZE = 100; // events per POST
+const DEFAULT_TIMEOUT_MS = 10_000; // per-POST abort deadline
+const DEFAULT_FLUSH_INTERVAL_MS = 5_000; // background flush cadence
+// Safety cap on shutdown()'s drain loop: keeps teardown bounded if a host keeps
+// emit()ing *during* shutdown. Realistic teardown needs 1-2 rounds; this is slack.
+const MAX_SHUTDOWN_FLUSHES = 100;
+/** Default in-process sink: a bounded buffer for tests / dark mode. */
+export class BufferSink {
+    maxlen;
+    events = [];
+    constructor(maxlen = DEFAULT_BUFFER_MAXLEN) {
+        this.maxlen = maxlen;
+    }
+    emit(event) {
+        this.events.push(event);
+        if (this.events.length > this.maxlen)
+            this.events.shift();
+    }
+    drain() {
+        const out = this.events;
+        this.events = [];
+        return out;
+    }
+}
+/** Bounded, background-flushing sink that POSTs event batches to the ingest. */
+export class HttpEventSink {
+    endpoint;
+    apiKey;
+    maxQueue;
+    batchSize;
+    timeoutMs;
+    schemeOk;
+    queue = [];
+    timer;
+    // The in-flight flush, or null. Concurrent flush() callers await this same
+    // promise instead of no-op'ing, so shutdown() genuinely waits for an in-flight
+    // background flush to finish before returning (otherwise it could drop the
+    // events still being POSTed — the exact thing shutdown exists to prevent).
+    activeFlush = null;
+    /** Total events dropped (queue-full, non-http endpoint, disabled, or post error). */
+    dropped = 0;
+    /** Set when a 401/403 marks the key dead; the sink then stops POSTing. */
+    disabled = false;
+    constructor(opts) {
+        this.endpoint = opts.endpoint;
+        this.apiKey = opts.apiKey;
+        this.maxQueue = opts.maxQueue ?? DEFAULT_MAX_QUEUE;
+        this.batchSize = opts.batchSize ?? DEFAULT_BATCH_SIZE;
+        this.timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+        let ok = false;
+        try {
+            ok = ALLOWED_SCHEMES.has(new URL(this.endpoint).protocol);
+        }
+        catch {
+            ok = false;
+        }
+        this.schemeOk = ok;
+        const interval = opts.flushIntervalMs ?? DEFAULT_FLUSH_INTERVAL_MS;
+        // .catch keeps the SDK fail-open: flush() swallows post errors today, but a
+        // background timer must never turn a future/unexpected rejection into an
+        // unhandled rejection that could crash the host.
+        this.timer = setInterval(() => void this.flush().catch(() => { }), interval);
+        // Never hold the process open for telemetry.
+        this.timer.unref?.();
+    }
+    emit(event) {
+        if (this.disabled || this.queue.length >= this.maxQueue) {
+            this.recordDropped(1);
+            return;
+        }
+        this.queue.push(event);
+    }
+    flush() {
+        // A concurrent flush already owns the drain: await the same operation rather
+        // than starting a second one (or returning before it completes).
+        if (this.activeFlush)
+            return this.activeFlush;
+        this.activeFlush = (async () => {
+            try {
+                // Snapshot at entry so flush() is bounded by the queue size NOW and always
+                // terminates, even if emit() keeps adding during the awaits (the Python
+                // sink drains a snapshot for the same reason).
+                const pending = this.queue;
+                this.queue = [];
+                for (let i = 0; i < pending.length; i += this.batchSize) {
+                    await this.post(pending.slice(i, i + this.batchSize));
+                }
+            }
+            finally {
+                this.activeFlush = null;
+            }
+        })();
+        return this.activeFlush;
+    }
+    async shutdown() {
+        this.stopTimer();
+        // Await any in-flight background flush, then keep flushing until the queue is
+        // empty, so events emit()ed while a flush was in flight aren't left behind.
+        // Bounded by MAX_SHUTDOWN_FLUSHES: a host that keeps emit()ing *during*
+        // shutdown can't spin teardown forever — past the cap the few trailing events
+        // are dropped rather than hanging the process.
+        await this.flush();
+        for (let round = 0; this.queue.length > 0 && round < MAX_SHUTDOWN_FLUSHES; round++) {
+            await this.flush();
+        }
+        // Hit the cap with the queue still non-empty: a host that out-paced the drain.
+        // Account for the trailing events as dropped — counted and subject to the warn
+        // cadence, never silently lost — and clear the queue so the sink ends empty,
+        // as this method's contract (and the comment above) promises.
+        if (this.queue.length > 0) {
+            this.recordDropped(this.queue.length);
+            this.queue = [];
+        }
+    }
+    stopTimer() {
+        if (this.timer) {
+            clearInterval(this.timer);
+            this.timer = undefined;
+        }
+    }
+    recordDropped(n) {
+        const prev = this.dropped;
+        this.dropped += n;
+        if (crossedWarnBoundary(prev, n)) {
+            // First loss, then rate-limited: silent total loss must be observable. The
+            // api key is never included in the message.
+            console.warn(`[neosigma] dropped ${this.dropped} event(s) (ingest unreachable, ` +
+                `disabled, or queue full).`);
+        }
+    }
+    async post(events) {
+        if (events.length === 0)
+            return;
+        if (this.disabled || !this.schemeOk) {
+            // Disabled (dead key) or a non-http(s) endpoint (misconfig): never POST.
+            this.recordDropped(events.length);
+            return;
+        }
+        const body = { events };
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+        try {
+            const res = await fetch(this.endpoint, {
+                method: "POST",
+                headers: {
+                    "Content-Type": "application/json",
+                    [API_KEY_HEADER]: this.apiKey,
+                },
+                body: serializeBatch(body),
+                signal: controller.signal,
+            });
+            if (res.status === 401 || res.status === 403) {
+                // Dead/revoked key: stop hammering the ingest for the rest of the process.
+                this.disabled = true;
+                this.stopTimer();
+                this.recordDropped(events.length);
+            }
+            else if (!res.ok) {
+                this.recordDropped(events.length);
+            }
+        }
+        catch {
+            // Fail-open: the ingest being unreachable must not break the host.
+            this.recordDropped(events.length);
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+}
+// ── active-sink registry ─────────────────────────────────────────────────────
+let active = new BufferSink();
+export function setEventSink(sink) {
+    // Shut the old sink down so its flush timer isn't orphaned, but best-effort:
+    // the SDK is fail-open, so a rejecting shutdown must not surface as an
+    // unhandled rejection.
+    if (active !== sink)
+        void active.shutdown?.().catch(() => { });
+    active = sink;
+}
+export function getEventSink() {
+    return active;
+}
+export async function flushSink() {
+    try {
+        await active.flush?.();
+    }
+    catch {
+        /* fail-open */
+    }
+}
+export async function resetSink() {
+    try {
+        await active.shutdown?.();
+    }
+    catch {
+        /* fail-open */
+    }
+    active = new BufferSink();
+}
+// ── graceful shutdown ────────────────────────────────────────────────────────
+let handlersInstalled = false;
+/**
+ * Opt-in: flush queued events on SIGTERM/SIGINT (Cloud Run sends SIGTERM before
+ * stopping an instance, e.g. on every deploy/scale-in). Without this, the
+ * trailing queue is lost on teardown. Idempotent. The host calls this once at
+ * boot; left opt-in so a library import never installs process handlers behind
+ * the host's back.
+ *
+ * Registered with `once`, and after the flush the signal is re-raised to the
+ * (now listener-less) process so Node's default handler terminates it. Without
+ * the re-raise, installing a handler suppresses the default exit and the process
+ * would hang if any other handle (e.g. an HTTP server) is still open.
+ */
+export function installShutdownHandlers(proc = process) {
+    if (handlersInstalled)
+        return;
+    handlersInstalled = true;
+    const onSignal = (signal) => {
+        void resetSink()
+            .catch(() => { })
+            .then(() => {
+            proc.kill(proc.pid, signal);
+        });
+    };
+    proc.once("SIGTERM", () => onSignal("SIGTERM"));
+    proc.once("SIGINT", () => onSignal("SIGINT"));
+}

package/dist/time.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Current wall-clock time in unix nanoseconds.
+ *
+ * Date.now() is millisecond-resolution and a safe integer; multiplying by 1e6 in
+ * bigint yields exact nanoseconds. A JS number could not hold ns exactly (it
+ * exceeds 2**53), hence bigint. The DateTime64(6) store keeps the value exactly.
+ */
+export declare function nowNs(): bigint;

package/dist/time.js

@@ -0,0 +1,10 @@
+/**
+ * Current wall-clock time in unix nanoseconds.
+ *
+ * Date.now() is millisecond-resolution and a safe integer; multiplying by 1e6 in
+ * bigint yields exact nanoseconds. A JS number could not hold ns exactly (it
+ * exceeds 2**53), hence bigint. The DateTime64(6) store keeps the value exactly.
+ */
+export function nowNs() {
+    return BigInt(Date.now()) * 1000000n;
+}

package/dist/warn.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Rate-limited drop/no-op warnings. Two paths lose data silently by design
+ * (the fail-open sink and out-of-scope setDistinctId); a one-shot warning would
+ * go quiet for the life of a long-running container after the first stray call,
+ * and warning every time would flood the log. This is the shared cadence: warn
+ * on the first loss, then once per WARN_EVERY thereafter.
+ */
+export declare const WARN_EVERY = 100;
+/**
+ * True if adding `n` losses to a running total of `prev` crosses a warn
+ * boundary: the very first loss (prev === 0), or a step over a WARN_EVERY
+ * multiple. Pure so both callers (the sink's batched drops and context's
+ * single-step drops) share one tested rule instead of hand-rolling the modulo.
+ */
+export declare function crossedWarnBoundary(prev: number, n: number, every?: number): boolean;

package/dist/warn.js

@@ -0,0 +1,19 @@
+/**
+ * Rate-limited drop/no-op warnings. Two paths lose data silently by design
+ * (the fail-open sink and out-of-scope setDistinctId); a one-shot warning would
+ * go quiet for the life of a long-running container after the first stray call,
+ * and warning every time would flood the log. This is the shared cadence: warn
+ * on the first loss, then once per WARN_EVERY thereafter.
+ */
+export const WARN_EVERY = 100;
+/**
+ * True if adding `n` losses to a running total of `prev` crosses a warn
+ * boundary: the very first loss (prev === 0), or a step over a WARN_EVERY
+ * multiple. Pure so both callers (the sink's batched drops and context's
+ * single-step drops) share one tested rule instead of hand-rolling the modulo.
+ */
+export function crossedWarnBoundary(prev, n, every = WARN_EVERY) {
+    if (prev === 0)
+        return true;
+    return Math.floor(prev / every) !== Math.floor((prev + n) / every);
+}

package/package.json

@@ -1,23 +1,56 @@
 {
-    "name": "neosigma-sdk",
-    "version": "0.0.1",
-    "description": "Placeholder package for the neosigma-sdk project",
-    "main": "index.js",
-    "scripts": {
-        "test": "echo \"Error: no test specified\" && exit 1"
-    },
-    "keywords": [
-        "neosigma",
-        "neosigma-sdk"
-    ],
-    "author": "NeoSigma Inc. <founders@neosigma.ai>",
-    "license": "MIT",
-    "homepage": "https://www.neosigma.ai",
-    "repository": {
-        "type": "git",
-        "url": ""
-    },
-    "engines": {
-        "node": ">=14.0.0"
+  "name": "neosigma-sdk",
+  "version": "0.1.0",
+  "description": "NeoSigma TypeScript SDK: emit product events that join your agent traces on run_id.",
+  "license": "MIT",
+  "homepage": "https://www.neosigma.ai",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/neosigmaai/neosigma.git",
+    "directory": "packages/neosigma-sdk-ts"
+  },
+  "bugs": {
+    "url": "https://github.com/neosigmaai/neosigma/issues"
+  },
+  "keywords": [
+    "neosigma",
+    "neosigma-sdk",
+    "telemetry",
+    "observability",
+    "analytics"
+  ],
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
     }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "smoke:bun": "bun run scripts/bun-smoke.ts",
+    "prepack": "npm run build"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "^5.7.0",
+    "vitest": "^2.1.8"
+  }
 }

package/index.js

@@ -1,13 +0,0 @@
-/**
- * neosigma-sdk - Placeholder package
- *
- * This is a placeholder package for the neosigma-sdk project.
- * The actual project will be published here in the future.
- */
-
-module.exports = {
-    version: '0.0.1',
-    neosigma: function () {
-        // NeoSigma SDK function
-    }
-};