@gurulu/node 0.1.0

package/README.md

@@ -0,0 +1,49 @@
+# @gurulu/node
+
+Server-side analytics SDK for Gurulu.io. Tracks events, identifies users, and batches requests with automatic retries.
+
+## Installation
+
+```bash
+npm install @gurulu/node
+```
+
+## Usage
+
+```typescript
+import { Gurulu } from '@gurulu/node';
+
+const gurulu = new Gurulu({
+  siteId: 'your-site-id',
+  apiKey: 'your-api-key',
+});
+
+// Track an event
+gurulu.track('purchase_completed', { amount: 49.99, currency: 'USD' }, {
+  userId: 'user-123',
+});
+
+// Identify a user
+gurulu.identify('user-123', {
+  email: 'user@example.com',
+  plan: 'pro',
+});
+
+// Manually flush the event queue
+await gurulu.flush();
+
+// Graceful shutdown (flushes remaining events and stops the timer)
+await gurulu.shutdown();
+```
+
+## Configuration
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `siteId` | `string` | **required** | Your Gurulu site ID |
+| `apiKey` | `string` | **required** | Your Gurulu API key |
+| `endpoint` | `string` | `https://app.gurulu.io/api/ingest/v1/server` | Custom ingest endpoint |
+| `flushInterval` | `number` | `10000` | Auto-flush interval in ms |
+| `maxBatchSize` | `number` | `50` | Max events per batch |
+| `maxRetries` | `number` | `3` | Retry count for failed requests |
+| `debug` | `boolean` | `false` | Enable debug logging |

package/dist/node-sdk/src/business-events.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Business event emitters — Phase 10 W4.2.
+ *
+ * These are tiny factories that return envelope-shaped `ServerEvent` objects
+ * for common server-authored events (user signup, payment, subscription,
+ * order, lead capture). They stamp the canonical `event_tier = 'verified'`
+ * and `event_source = 'server_sdk'` fields so downstream readers can trust
+ * the provenance without guessing.
+ *
+ * The shape intentionally satisfies BOTH:
+ *   - the simple `ServerEvent` contract the /api/ingest/v1/server route
+ *     consumes (event_name, user_id, properties, timestamp,
+ *     idempotency_key?, correlation_id?), AND
+ *   - the richer canonical Envelope fields consumers may want to read
+ *     (event_tier, event_source) — we attach these at the top level so they
+ *     travel alongside the event without collapsing into properties.
+ *
+ * `createEnvelope` from @gurulu/shared-core is used to validate/normalize the
+ * shared envelope defaults where practical (event_type, timestamp,
+ * consent_level, etc.), but the ServerEvent-specific keys (user_id) remain at
+ * the root.
+ *
+ * Related docs: PHASE-10-ROADMAP.md §W4.2
+ */
+import { type Envelope, type ServerEvent } from '@gurulu/shared-core';
+/**
+ * Concrete shape returned by every business-event factory below:
+ * a ServerEvent with the canonical envelope provenance fields attached.
+ */
+export type BusinessEvent = ServerEvent & {
+    event_tier: Envelope['event_tier'];
+    event_source: Envelope['event_source'];
+    event_type: Envelope['event_type'];
+};
+export interface UserCreatedArgs {
+    userId: string;
+    email?: string;
+    traits?: Record<string, unknown>;
+}
+export declare function userCreated(args: UserCreatedArgs): BusinessEvent;
+export interface PaymentSucceededArgs {
+    userId: string;
+    amount: number;
+    currency: string;
+    orderId: string;
+    properties?: Record<string, unknown>;
+}
+export declare function paymentSucceeded(args: PaymentSucceededArgs): BusinessEvent;
+export interface SubscriptionStartedArgs {
+    userId: string;
+    plan: string;
+    amount?: number;
+    currency?: string;
+}
+export declare function subscriptionStarted(args: SubscriptionStartedArgs): BusinessEvent;
+export interface OrderPlacedArgs {
+    userId: string;
+    orderId: string;
+    total: number;
+    currency: string;
+    items?: Array<{
+        id: string;
+        qty: number;
+        price: number;
+    }>;
+}
+export declare function orderPlaced(args: OrderPlacedArgs): BusinessEvent;
+export interface LeadCapturedArgs {
+    anonymousId: string;
+    email?: string;
+    source?: string;
+}
+export declare function leadCaptured(args: LeadCapturedArgs): BusinessEvent;

package/dist/node-sdk/src/business-events.js

@@ -0,0 +1,113 @@
+"use strict";
+/**
+ * Business event emitters — Phase 10 W4.2.
+ *
+ * These are tiny factories that return envelope-shaped `ServerEvent` objects
+ * for common server-authored events (user signup, payment, subscription,
+ * order, lead capture). They stamp the canonical `event_tier = 'verified'`
+ * and `event_source = 'server_sdk'` fields so downstream readers can trust
+ * the provenance without guessing.
+ *
+ * The shape intentionally satisfies BOTH:
+ *   - the simple `ServerEvent` contract the /api/ingest/v1/server route
+ *     consumes (event_name, user_id, properties, timestamp,
+ *     idempotency_key?, correlation_id?), AND
+ *   - the richer canonical Envelope fields consumers may want to read
+ *     (event_tier, event_source) — we attach these at the top level so they
+ *     travel alongside the event without collapsing into properties.
+ *
+ * `createEnvelope` from @gurulu/shared-core is used to validate/normalize the
+ * shared envelope defaults where practical (event_type, timestamp,
+ * consent_level, etc.), but the ServerEvent-specific keys (user_id) remain at
+ * the root.
+ *
+ * Related docs: PHASE-10-ROADMAP.md §W4.2
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.userCreated = userCreated;
+exports.paymentSucceeded = paymentSucceeded;
+exports.subscriptionStarted = subscriptionStarted;
+exports.orderPlaced = orderPlaced;
+exports.leadCaptured = leadCaptured;
+const shared_core_1 = require("@gurulu/shared-core");
+const SDK_VERSION = 'node@0.1.0';
+function baseEnvelope(eventName, anonymousId, properties) {
+    return (0, shared_core_1.createEnvelope)({
+        site_id: '', // supplied at transport time by the client
+        anonymous_id: anonymousId,
+        session_id: '', // server SDK has no browser session
+        event_name: eventName,
+        event_type: 'server',
+        event_tier: 'verified',
+        event_source: 'server_sdk',
+        consent_level: 'accepted',
+        sdk_version: SDK_VERSION,
+        timestamp: new Date(Date.now()).toISOString(),
+        properties,
+    });
+}
+function toBusinessEvent(envelope, userId, extras = {}) {
+    return {
+        event_name: envelope.event_name,
+        user_id: userId,
+        properties: envelope.properties,
+        timestamp: envelope.timestamp,
+        event_type: envelope.event_type,
+        event_tier: envelope.event_tier,
+        event_source: envelope.event_source,
+        ...extras,
+    };
+}
+function userCreated(args) {
+    const props = {
+        ...(args.traits ?? {}),
+    };
+    if (args.email !== undefined)
+        props.email = args.email;
+    const env = baseEnvelope('user_created', args.userId, props);
+    return toBusinessEvent(env, args.userId);
+}
+function paymentSucceeded(args) {
+    const props = {
+        ...(args.properties ?? {}),
+        amount: args.amount,
+        currency: args.currency,
+        order_id: args.orderId,
+    };
+    const env = baseEnvelope('payment_succeeded', args.userId, props);
+    return toBusinessEvent(env, args.userId);
+}
+function subscriptionStarted(args) {
+    const props = {
+        plan: args.plan,
+    };
+    if (args.amount !== undefined)
+        props.amount = args.amount;
+    if (args.currency !== undefined)
+        props.currency = args.currency;
+    const env = baseEnvelope('subscription_started', args.userId, props);
+    return toBusinessEvent(env, args.userId);
+}
+function orderPlaced(args) {
+    const props = {
+        order_id: args.orderId,
+        total: args.total,
+        currency: args.currency,
+    };
+    if (args.items !== undefined)
+        props.items = args.items;
+    const env = baseEnvelope('order_placed', args.userId, props);
+    return toBusinessEvent(env, args.userId);
+}
+function leadCaptured(args) {
+    const props = {};
+    if (args.email !== undefined)
+        props.email = args.email;
+    if (args.source !== undefined)
+        props.source = args.source;
+    const env = baseEnvelope('lead_captured', args.anonymousId, props);
+    // Lead capture uses anonymous_id as the user_id placeholder until the lead
+    // is resolved to a real account; the server route accepts any non-empty
+    // user_id string and will look up the canonical profile from it.
+    return toBusinessEvent(env, args.anonymousId);
+}

package/dist/node-sdk/src/client.d.ts

@@ -0,0 +1,70 @@
+/**
+ * @gurulu/node — server-side SDK client.
+ *
+ * Responsibilities (Phase 10 W4.2):
+ *   - Queue + batch server events.
+ *   - Auto-flush at batchSize boundary and on a periodic timer.
+ *   - Exponential-backoff retry (200ms, 600ms, 1800ms — 3 attempts total) on
+ *     5xx / network errors. No retry on 4xx.
+ *   - Attach deterministic Idempotency-Key headers so the server can dedupe
+ *     replayed batches across retries.
+ *   - Dead-letter callback for batches that exhaust retries or are rejected
+ *     with a client error.
+ *   - Flush on process.beforeExit + SIGTERM.
+ *
+ * Event shapes are pulled from @gurulu/shared-core (W1.2). Only the transport
+ * config (`GuruluClientConfig`) is local.
+ *
+ * Related docs: PHASE-10-ROADMAP.md §W4.2
+ */
+import type { ServerEvent } from '@gurulu/shared-core';
+import type { GuruluClientConfig } from './types';
+export interface GuruluClient {
+    track(event: ServerEvent): void;
+    flush(): Promise<void>;
+    shutdown(): Promise<void>;
+    /** Current queue length — exposed for tests and observability. */
+    readonly queueSize: number;
+}
+/**
+ * Deterministic idempotency key for a server event. Hashes the tuple
+ * (site_id, event_name, timestamp, anonymous_id/user_id) so replayed events
+ * across retries produce the same key and the server can dedupe.
+ */
+export declare function createIdempotencyKey(event: ServerEvent, siteId: string): string;
+export declare class Gurulu implements GuruluClient {
+    private readonly siteId;
+    private readonly apiKey;
+    private readonly endpoint;
+    private readonly flushInterval;
+    private readonly batchSize;
+    private readonly timeout;
+    private readonly onError?;
+    private readonly onDeadLetter?;
+    private readonly fetchImpl;
+    private readonly debug;
+    private queue;
+    private flushTimer;
+    private inFlight;
+    private shutdownHandlers;
+    constructor(config: GuruluClientConfig);
+    get queueSize(): number;
+    /**
+     * Enqueue a server event. Auto-flushes synchronously when the queue reaches
+     * `batchSize`. Each event is stamped with a timestamp if missing so the
+     * idempotency key is stable across retries.
+     */
+    track(event: ServerEvent): void;
+    /**
+     * POST all queued events in one batch. On 5xx / network error retries with
+     * exponential backoff (200ms, 600ms, 1800ms). On 4xx drops the batch and
+     * fires the dead-letter callback. Concurrent flush calls are serialized.
+     */
+    flush(): Promise<void>;
+    private sendBatch;
+    /**
+     * Stop the periodic flush timer, detach process listeners, and perform a
+     * final flush. Safe to call multiple times.
+     */
+    shutdown(): Promise<void>;
+}

package/dist/node-sdk/src/client.js

@@ -0,0 +1,255 @@
+"use strict";
+/**
+ * @gurulu/node — server-side SDK client.
+ *
+ * Responsibilities (Phase 10 W4.2):
+ *   - Queue + batch server events.
+ *   - Auto-flush at batchSize boundary and on a periodic timer.
+ *   - Exponential-backoff retry (200ms, 600ms, 1800ms — 3 attempts total) on
+ *     5xx / network errors. No retry on 4xx.
+ *   - Attach deterministic Idempotency-Key headers so the server can dedupe
+ *     replayed batches across retries.
+ *   - Dead-letter callback for batches that exhaust retries or are rejected
+ *     with a client error.
+ *   - Flush on process.beforeExit + SIGTERM.
+ *
+ * Event shapes are pulled from @gurulu/shared-core (W1.2). Only the transport
+ * config (`GuruluClientConfig`) is local.
+ *
+ * Related docs: PHASE-10-ROADMAP.md §W4.2
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Gurulu = void 0;
+exports.createIdempotencyKey = createIdempotencyKey;
+const crypto_1 = require("crypto");
+const DEFAULT_ENDPOINT = 'https://app.gurulu.io/api/ingest/v1/server';
+const DEFAULT_FLUSH_INTERVAL = 5000;
+const DEFAULT_BATCH_SIZE = 50;
+const DEFAULT_TIMEOUT = 10000;
+const RETRY_DELAYS_MS = [200, 600, 1800];
+/**
+ * Deterministic idempotency key for a server event. Hashes the tuple
+ * (site_id, event_name, timestamp, anonymous_id/user_id) so replayed events
+ * across retries produce the same key and the server can dedupe.
+ */
+function createIdempotencyKey(event, siteId) {
+    const parts = [
+        siteId,
+        event.event_name ?? '',
+        event.timestamp ?? '',
+        event.user_id ?? '',
+    ];
+    return (0, crypto_1.createHash)('sha256').update(parts.join('|')).digest('hex');
+}
+class Gurulu {
+    siteId;
+    apiKey;
+    endpoint;
+    flushInterval;
+    batchSize;
+    timeout;
+    onError;
+    onDeadLetter;
+    fetchImpl;
+    debug;
+    queue = [];
+    flushTimer = null;
+    inFlight = null;
+    shutdownHandlers = [];
+    constructor(config) {
+        if (!config.siteId)
+            throw new Error('siteId is required');
+        if (!config.apiKey)
+            throw new Error('apiKey is required');
+        this.siteId = config.siteId;
+        this.apiKey = config.apiKey;
+        this.endpoint = config.endpoint || DEFAULT_ENDPOINT;
+        this.flushInterval = config.flushInterval ?? DEFAULT_FLUSH_INTERVAL;
+        this.batchSize = config.batchSize ?? DEFAULT_BATCH_SIZE;
+        this.timeout = config.timeout ?? DEFAULT_TIMEOUT;
+        this.onError = config.onError;
+        this.onDeadLetter = config.onDeadLetter;
+        this.debug = config.debug ?? false;
+        const injected = config.fetchImpl;
+        if (injected) {
+            this.fetchImpl = injected;
+        }
+        else {
+            const g = globalThis;
+            if (typeof g.fetch !== 'function') {
+                throw new Error('global fetch is not available; pass fetchImpl in config (Node 18+ required)');
+            }
+            this.fetchImpl = g.fetch.bind(globalThis);
+        }
+        if (this.flushInterval > 0) {
+            this.flushTimer = setInterval(() => {
+                // Fire and forget; errors surface via onError.
+                void this.flush();
+            }, this.flushInterval);
+            // Let the process exit even if the timer is pending.
+            const t = this.flushTimer;
+            if (typeof t.unref === 'function')
+                t.unref();
+        }
+        if (!config.disableAutoShutdown && typeof process !== 'undefined' && typeof process.on === 'function') {
+            const beforeExit = () => {
+                void this.flush();
+            };
+            const onSigterm = () => {
+                void this.shutdown();
+            };
+            process.on('beforeExit', beforeExit);
+            process.on('SIGTERM', onSigterm);
+            this.shutdownHandlers.push(() => {
+                process.off('beforeExit', beforeExit);
+                process.off('SIGTERM', onSigterm);
+            });
+        }
+    }
+    get queueSize() {
+        return this.queue.length;
+    }
+    /**
+     * Enqueue a server event. Auto-flushes synchronously when the queue reaches
+     * `batchSize`. Each event is stamped with a timestamp if missing so the
+     * idempotency key is stable across retries.
+     */
+    track(event) {
+        if (!event || !event.event_name) {
+            if (this.debug)
+                console.warn('[gurulu] event_name is required');
+            return;
+        }
+        if (!event.user_id) {
+            if (this.debug)
+                console.warn('[gurulu] user_id is required for server events');
+            return;
+        }
+        const stamped = {
+            ...event,
+            timestamp: event.timestamp ?? new Date().toISOString(),
+        };
+        this.queue.push(stamped);
+        if (this.debug) {
+            console.log(`[gurulu] queued: ${stamped.event_name} (${this.queue.length}/${this.batchSize})`);
+        }
+        if (this.queue.length >= this.batchSize) {
+            void this.flush();
+        }
+    }
+    /**
+     * POST all queued events in one batch. On 5xx / network error retries with
+     * exponential backoff (200ms, 600ms, 1800ms). On 4xx drops the batch and
+     * fires the dead-letter callback. Concurrent flush calls are serialized.
+     */
+    async flush() {
+        // Serialize concurrent flushes so retries don't interleave.
+        if (this.inFlight) {
+            await this.inFlight;
+        }
+        if (this.queue.length === 0)
+            return;
+        const batch = this.queue.splice(0, this.queue.length);
+        const run = this.sendBatch(batch);
+        this.inFlight = run.finally(() => {
+            this.inFlight = null;
+        });
+        await this.inFlight;
+    }
+    async sendBatch(batch) {
+        // Idempotency key for the whole batch — hashed over individual event keys.
+        const perEventKeys = batch.map((e) => createIdempotencyKey(e, this.siteId));
+        const batchKey = (0, crypto_1.createHash)('sha256').update(perEventKeys.join('|')).digest('hex');
+        const body = JSON.stringify({
+            site_id: this.siteId,
+            events: batch,
+        });
+        const headers = {
+            'Content-Type': 'application/json',
+            Authorization: `Bearer ${this.apiKey}`,
+            'Idempotency-Key': batchKey,
+        };
+        let lastError = null;
+        for (let attempt = 0; attempt < RETRY_DELAYS_MS.length; attempt++) {
+            try {
+                const res = await this.fetchImpl(this.endpoint, {
+                    method: 'POST',
+                    headers,
+                    body,
+                });
+                if (res.ok) {
+                    if (this.debug)
+                        console.log(`[gurulu] flushed ${batch.length} events`);
+                    return;
+                }
+                if (res.status >= 400 && res.status < 500) {
+                    // Client error — don't retry. Drop + dead-letter.
+                    const text = await safeText(res);
+                    const err = new Error(`client_error ${res.status}: ${text}`);
+                    if (this.debug)
+                        console.error(`[gurulu] ${err.message}`);
+                    this.onError?.(err);
+                    this.onDeadLetter?.(batch, {
+                        kind: 'client_error',
+                        status: res.status,
+                        message: text,
+                    });
+                    return;
+                }
+                lastError = new Error(`server_error ${res.status}`);
+                this.onError?.(lastError);
+            }
+            catch (err) {
+                lastError = err instanceof Error ? err : new Error(String(err));
+                this.onError?.(lastError);
+            }
+            // Not the last attempt — sleep with the fixed exponential schedule.
+            if (attempt < RETRY_DELAYS_MS.length - 1) {
+                await sleep(RETRY_DELAYS_MS[attempt + 1 - 1]);
+                // ^ Index arithmetic: attempt=0 -> use RETRY_DELAYS_MS[0]=200, etc.
+            }
+        }
+        // All 3 attempts failed.
+        if (this.debug) {
+            console.error(`[gurulu] dropping batch of ${batch.length} after retries: ${lastError?.message}`);
+        }
+        if (this.onDeadLetter) {
+            this.onDeadLetter(batch, {
+                kind: lastError?.message.startsWith('server_error') ? 'server_error' : 'network_error',
+                message: lastError?.message ?? 'unknown error',
+            });
+        }
+        else if (this.debug) {
+            console.error('[gurulu] no dead-letter callback configured; events lost');
+        }
+    }
+    /**
+     * Stop the periodic flush timer, detach process listeners, and perform a
+     * final flush. Safe to call multiple times.
+     */
+    async shutdown() {
+        if (this.flushTimer) {
+            clearInterval(this.flushTimer);
+            this.flushTimer = null;
+        }
+        for (const detach of this.shutdownHandlers.splice(0)) {
+            try {
+                detach();
+            }
+            catch { /* best-effort */ }
+        }
+        await this.flush();
+    }
+}
+exports.Gurulu = Gurulu;
+async function safeText(res) {
+    try {
+        return await res.text();
+    }
+    catch {
+        return '';
+    }
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/dist/node-sdk/src/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * @gurulu/node — public entry point.
+ *
+ * Phase 10 W4.2: server SDK hardening adds batch+retry, deterministic
+ * idempotency keys, dead-letter callbacks, and business event emitters.
+ */
+export { Gurulu, createIdempotencyKey } from './client';
+export type { GuruluClient } from './client';
+export type { GuruluClientConfig, DeadLetterCallback, ErrorCallback, } from './types';
+export type { Envelope, ServerEvent, EventTier, EventSource, ConsentLevel, } from '@gurulu/shared-core';
+export { userCreated, paymentSucceeded, subscriptionStarted, orderPlaced, leadCaptured, } from './business-events';
+export type { BusinessEvent, UserCreatedArgs, PaymentSucceededArgs, SubscriptionStartedArgs, OrderPlacedArgs, LeadCapturedArgs, } from './business-events';

package/dist/node-sdk/src/index.js

@@ -0,0 +1,19 @@
+"use strict";
+/**
+ * @gurulu/node — public entry point.
+ *
+ * Phase 10 W4.2: server SDK hardening adds batch+retry, deterministic
+ * idempotency keys, dead-letter callbacks, and business event emitters.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.leadCaptured = exports.orderPlaced = exports.subscriptionStarted = exports.paymentSucceeded = exports.userCreated = exports.createIdempotencyKey = exports.Gurulu = void 0;
+var client_1 = require("./client");
+Object.defineProperty(exports, "Gurulu", { enumerable: true, get: function () { return client_1.Gurulu; } });
+Object.defineProperty(exports, "createIdempotencyKey", { enumerable: true, get: function () { return client_1.createIdempotencyKey; } });
+// Business event emitters (W4.2).
+var business_events_1 = require("./business-events");
+Object.defineProperty(exports, "userCreated", { enumerable: true, get: function () { return business_events_1.userCreated; } });
+Object.defineProperty(exports, "paymentSucceeded", { enumerable: true, get: function () { return business_events_1.paymentSucceeded; } });
+Object.defineProperty(exports, "subscriptionStarted", { enumerable: true, get: function () { return business_events_1.subscriptionStarted; } });
+Object.defineProperty(exports, "orderPlaced", { enumerable: true, get: function () { return business_events_1.orderPlaced; } });
+Object.defineProperty(exports, "leadCaptured", { enumerable: true, get: function () { return business_events_1.leadCaptured; } });

package/dist/node-sdk/src/types.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Node SDK public types.
+ *
+ * Canonical event shapes (Envelope, ServerEvent, EventTier, EventSource,
+ * ConsentLevel, createEnvelope, normalizeLegacy, parseEnvelope) are re-exported
+ * from @gurulu/shared-core — single source of truth per W1.2.
+ *
+ * The only node-sdk-specific addition is the transport config
+ * (GuruluClientConfig) which wraps the shared ServerEvent with the knobs
+ * needed to actually ship events to the ingest endpoint.
+ *
+ * Related docs: PHASE-10-ROADMAP.md §W1.2, §W4.2
+ */
+import type { ServerEvent } from '@gurulu/shared-core';
+export * from '@gurulu/shared-core';
+/**
+ * Dead-letter callback fired when a batch is permanently dropped (either
+ * because all retries failed against a 5xx/network error, or because the
+ * server replied 4xx).
+ */
+export type DeadLetterCallback = (batch: ServerEvent[], reason: {
+    kind: 'client_error' | 'network_error' | 'server_error';
+    status?: number;
+    message: string;
+}) => void;
+export type ErrorCallback = (err: Error) => void;
+export interface GuruluClientConfig {
+    siteId: string;
+    apiKey: string;
+    endpoint?: string;
+    /** Periodic flush interval in ms. Default 5000. */
+    flushInterval?: number;
+    /** Max events per batch. Auto-flushes when queue reaches this size. Default 50. */
+    batchSize?: number;
+    /** Per-request HTTP timeout in ms. Default 10000. */
+    timeout?: number;
+    /** Fired on every transport error (retryable or not). */
+    onError?: ErrorCallback;
+    /** Fired when a batch is permanently dropped. */
+    onDeadLetter?: DeadLetterCallback;
+    /** Inject fetch for testing (defaults to globalThis.fetch). */
+    fetchImpl?: typeof fetch;
+    /** Suppress automatic process.on('beforeExit'/'SIGTERM') hooks. */
+    disableAutoShutdown?: boolean;
+    debug?: boolean;
+}

package/dist/node-sdk/src/types.js

@@ -0,0 +1,30 @@
+"use strict";
+/**
+ * Node SDK public types.
+ *
+ * Canonical event shapes (Envelope, ServerEvent, EventTier, EventSource,
+ * ConsentLevel, createEnvelope, normalizeLegacy, parseEnvelope) are re-exported
+ * from @gurulu/shared-core — single source of truth per W1.2.
+ *
+ * The only node-sdk-specific addition is the transport config
+ * (GuruluClientConfig) which wraps the shared ServerEvent with the knobs
+ * needed to actually ship events to the ingest endpoint.
+ *
+ * Related docs: PHASE-10-ROADMAP.md §W1.2, §W4.2
+ */
+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 });
+__exportStar(require("@gurulu/shared-core"), exports);