@socwarden/sdk 1.0.0-alpha.1

package/README.md

@@ -0,0 +1,131 @@
+# @socwarden/sdk
+
+Node.js/TypeScript SDK for [SOCWarden](https://socwarden.io) security event tracking.
+
+## Installation
+
+```bash
+npm install @socwarden/sdk
+```
+
+## Quick Start
+
+```typescript
+import { SOCWardenClient } from '@socwarden/sdk';
+
+const soc = new SOCWardenClient({
+  apiKey: 'sk_live_...',
+  // endpoint: 'https://ingest.socwarden.io', // default
+  // timeout: 5000, // default, in ms
+});
+```
+
+## Usage
+
+### track() — Named Arguments
+
+```typescript
+// Simple event
+await soc.track('auth.login.success', { actor: userId });
+
+// With full options
+await soc.track('data.exported', {
+  actor: { id: user.id, email: user.email },
+  metadata: { format: 'csv', rows: 1500 },
+  resource: { type: 'Report', id: report.id },
+  ip: '203.0.113.42',
+});
+
+// With explicit actor fields
+await soc.track('auth.login.failure', {
+  actorEmail: req.body.email,
+  ip: req.ip,
+  userAgent: req.get('user-agent'),
+});
+```
+
+### trackData() — Raw Object
+
+```typescript
+await soc.trackData('auth.login.success', {
+  actor_id: user.id,
+  actor_email: user.email,
+  metadata: { role: 'admin' },
+});
+```
+
+### event() — Fluent Builder
+
+```typescript
+await soc.event('data.exported')
+  .actor({ id: user.id, email: user.email })
+  .resource('Report', report.id)
+  .meta('format', 'csv')
+  .meta('rows', 1500)
+  .send();
+
+// Chaining metadata
+await soc.event('auth.mfa.enrolled')
+  .actor(user.id)
+  .metadata({ method: 'totp', provider: 'google' })
+  .severity('info')
+  .send();
+```
+
+### Express Middleware
+
+The middleware captures request context (IP, user-agent, path, etc.) and attaches it to every event sent during the request lifecycle.
+
+```typescript
+import express from 'express';
+import { SOCWardenClient, socwardenMiddleware } from '@socwarden/sdk';
+
+const soc = new SOCWardenClient({ apiKey: 'sk_live_...' });
+const app = express();
+
+// Attach SOCWarden middleware
+app.use(socwardenMiddleware(soc));
+
+app.post('/login', async (req, res) => {
+  const user = await authenticate(req.body);
+
+  if (user) {
+    // IP, user-agent, path are auto-captured from the request
+    await soc.track('auth.login.success', { actor: user.id });
+    res.json({ ok: true });
+  } else {
+    await soc.track('auth.login.failure', {
+      actorEmail: req.body.email,
+    });
+    res.status(401).json({ error: 'Invalid credentials' });
+  }
+});
+```
+
+## Rate Limit Handling
+
+The SDK automatically handles 429 (rate limit) responses:
+
+1. On receiving a 429, it backs off for the `Retry-After` duration (default: 1 hour).
+2. During backoff, events are silently dropped to avoid overwhelming the ingestor.
+3. Every 5 minutes, a probe request is sent to check if the quota has been restored.
+4. On a successful probe, normal sending resumes immediately.
+
+## Requirements
+
+- Node.js 18+ (uses native `fetch`)
+- No runtime dependencies
+
+## TypeScript
+
+All types are exported for full TypeScript support:
+
+```typescript
+import type {
+  SOCWardenOptions,
+  TrackOptions,
+  ActorInput,
+  ResourceInput,
+  EventPayload,
+} from '@socwarden/sdk';
+```

package/dist/builder.d.ts

@@ -0,0 +1,90 @@
+import type { SOCWardenClient } from './client';
+import type { ActorInput, ResourceInput } from './types';
+/**
+ * Fluent builder for constructing and sending SOCWarden events.
+ *
+ * ```ts
+ * await soc.event('auth.login.success')
+ *   .actor({ id: 'usr_123', email: 'john@example.com' })
+ *   .ip('203.0.113.42')
+ *   .metadata({ mfa: true })
+ *   .resource('Session', 'sess_abc')
+ *   .send();
+ * ```
+ */
+export declare class EventBuilder {
+    private readonly eventName;
+    private readonly client;
+    private data;
+    constructor(event: string, client: SOCWardenClient);
+    /**
+     * Set the actor (user) who triggered the event.
+     *
+     * Accepts a string ID or an object with `id` and optional `email`.
+     *
+     * ```ts
+     * .actor('usr_123')
+     * .actor({ id: 'usr_123', email: 'john@example.com' })
+     * ```
+     */
+    actor(actorOrId: ActorInput, email?: string): this;
+    /**
+     * Set the actor ID directly.
+     */
+    actorId(id: string): this;
+    /**
+     * Set the actor email directly.
+     */
+    actorEmail(email: string): this;
+    /**
+     * Set the source IP address.
+     */
+    ip(ip: string): this;
+    /**
+     * Set the User-Agent string.
+     */
+    userAgent(ua: string): this;
+    /**
+     * Merge custom metadata key-value pairs. Can be called multiple times;
+     * values are merged (later calls override earlier keys).
+     *
+     * ```ts
+     * .metadata({ role: 'admin', format: 'csv' })
+     * ```
+     */
+    metadata(obj: Record<string, unknown>): this;
+    /**
+     * Set a single metadata key-value pair.
+     *
+     * ```ts
+     * .meta('role', 'admin')
+     * ```
+     */
+    meta(key: string, value: unknown): this;
+    /**
+     * Set the event timestamp (ISO 8601 string or Date object).
+     */
+    timestamp(ts: string | Date): this;
+    /**
+     * Set the event severity hint for the enricher.
+     */
+    severity(severity: string): this;
+    /**
+     * Attach the resource that was acted upon.
+     *
+     * ```ts
+     * .resource('Order', 'ord_123')
+     * .resource({ type: 'Order', id: 'ord_123' })
+     * ```
+     */
+    resource(typeOrObj: ResourceInput, id?: string): this;
+    /**
+     * Send the event to SOCWarden.
+     */
+    send(): Promise<void>;
+    /**
+     * Get the built data object (for testing/inspection).
+     */
+    toObject(): Record<string, unknown>;
+}
+//# sourceMappingURL=builder.d.ts.map

package/dist/builder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"builder.d.ts","sourceRoot":"","sources":["../src/builder.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,UAAU,CAAC;AAChD,OAAO,KAAK,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAEzD;;;;;;;;;;;GAWG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAkB;IACzC,OAAO,CAAC,IAAI,CAA+B;gBAE/B,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,eAAe;IASlD;;;;;;;;;OASG;IACH,KAAK,CAAC,SAAS,EAAE,UAAU,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI;IAkBlD;;OAEG;IACH,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI;IAKzB;;OAEG;IACH,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAS/B;;OAEG;IACH,EAAE,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI;IAKpB;;OAEG;IACH,SAAS,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI;IAS3B;;;;;;;OAOG;IACH,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAQ5C;;;;;;OAMG;IACH,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,IAAI;IAWvC;;OAEG;IACH,SAAS,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI;IAKlC;;OAEG;IACH,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI;IAWhC;;;;;;;OAOG;IACH,QAAQ,CAAC,SAAS,EAAE,aAAa,EAAE,EAAE,CAAC,EAAE,MAAM,GAAG,IAAI;IAmBrD;;OAEG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAI3B;;OAEG;IACH,QAAQ,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;CAMpC"}

package/dist/builder.js

@@ -0,0 +1,182 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EventBuilder = void 0;
+/**
+ * Fluent builder for constructing and sending SOCWarden events.
+ *
+ * ```ts
+ * await soc.event('auth.login.success')
+ *   .actor({ id: 'usr_123', email: 'john@example.com' })
+ *   .ip('203.0.113.42')
+ *   .metadata({ mfa: true })
+ *   .resource('Session', 'sess_abc')
+ *   .send();
+ * ```
+ */
+class EventBuilder {
+    eventName;
+    client;
+    data = {};
+    constructor(event, client) {
+        this.eventName = event;
+        this.client = client;
+    }
+    // ---------------------------------------------------------------------------
+    //  Actor
+    // ---------------------------------------------------------------------------
+    /**
+     * Set the actor (user) who triggered the event.
+     *
+     * Accepts a string ID or an object with `id` and optional `email`.
+     *
+     * ```ts
+     * .actor('usr_123')
+     * .actor({ id: 'usr_123', email: 'john@example.com' })
+     * ```
+     */
+    actor(actorOrId, email) {
+        if (typeof actorOrId === 'string') {
+            this.data.actor_id = actorOrId;
+            if (email !== undefined) {
+                this.data.actor_email = email;
+            }
+        }
+        else {
+            this.data.actor_id = actorOrId.id;
+            if (actorOrId.email) {
+                this.data.actor_email = actorOrId.email;
+            }
+            if (email !== undefined) {
+                this.data.actor_email = email;
+            }
+        }
+        return this;
+    }
+    /**
+     * Set the actor ID directly.
+     */
+    actorId(id) {
+        this.data.actor_id = id;
+        return this;
+    }
+    /**
+     * Set the actor email directly.
+     */
+    actorEmail(email) {
+        this.data.actor_email = email;
+        return this;
+    }
+    // ---------------------------------------------------------------------------
+    //  Request context
+    // ---------------------------------------------------------------------------
+    /**
+     * Set the source IP address.
+     */
+    ip(ip) {
+        this.data.ip = ip;
+        return this;
+    }
+    /**
+     * Set the User-Agent string.
+     */
+    userAgent(ua) {
+        this.data.user_agent = ua;
+        return this;
+    }
+    // ---------------------------------------------------------------------------
+    //  Metadata
+    // ---------------------------------------------------------------------------
+    /**
+     * Merge custom metadata key-value pairs. Can be called multiple times;
+     * values are merged (later calls override earlier keys).
+     *
+     * ```ts
+     * .metadata({ role: 'admin', format: 'csv' })
+     * ```
+     */
+    metadata(obj) {
+        this.data.metadata = {
+            ...(this.data.metadata ?? {}),
+            ...obj,
+        };
+        return this;
+    }
+    /**
+     * Set a single metadata key-value pair.
+     *
+     * ```ts
+     * .meta('role', 'admin')
+     * ```
+     */
+    meta(key, value) {
+        const existing = this.data.metadata ?? {};
+        existing[key] = value;
+        this.data.metadata = existing;
+        return this;
+    }
+    // ---------------------------------------------------------------------------
+    //  Timestamp & severity
+    // ---------------------------------------------------------------------------
+    /**
+     * Set the event timestamp (ISO 8601 string or Date object).
+     */
+    timestamp(ts) {
+        this.data.timestamp = ts instanceof Date ? ts.toISOString() : ts;
+        return this;
+    }
+    /**
+     * Set the event severity hint for the enricher.
+     */
+    severity(severity) {
+        const existing = this.data.metadata ?? {};
+        existing._severity = severity;
+        this.data.metadata = existing;
+        return this;
+    }
+    // ---------------------------------------------------------------------------
+    //  Resource
+    // ---------------------------------------------------------------------------
+    /**
+     * Attach the resource that was acted upon.
+     *
+     * ```ts
+     * .resource('Order', 'ord_123')
+     * .resource({ type: 'Order', id: 'ord_123' })
+     * ```
+     */
+    resource(typeOrObj, id) {
+        const existing = this.data.metadata ?? {};
+        if (typeof typeOrObj === 'string') {
+            existing.resource_type = typeOrObj;
+            if (id !== undefined) {
+                existing.resource_id = id;
+            }
+        }
+        else {
+            existing.resource_type = typeOrObj.type;
+            existing.resource_id = typeOrObj.id;
+        }
+        this.data.metadata = existing;
+        return this;
+    }
+    // ---------------------------------------------------------------------------
+    //  Send
+    // ---------------------------------------------------------------------------
+    /**
+     * Send the event to SOCWarden.
+     */
+    async send() {
+        await this.client.trackData(this.eventName, this.data);
+    }
+    /**
+     * Get the built data object (for testing/inspection).
+     */
+    toObject() {
+        return {
+            event: this.eventName,
+            ...this.data,
+        };
+    }
+}
+exports.EventBuilder = EventBuilder;
+//# sourceMappingURL=builder.js.map

package/dist/builder.js.map

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

package/dist/client.d.ts

@@ -0,0 +1,74 @@
+import { EventBuilder } from './builder';
+import { SOCWardenOptions, TrackOptions } from './types';
+export declare class SOCWardenClient {
+    private readonly apiKey;
+    private readonly endpoint;
+    private readonly timeout;
+    /** In-memory backoff state for 429 handling. */
+    private backoffUntil;
+    private lastProbe;
+    constructor(options: SOCWardenOptions);
+    /**
+     * Track a security event using named arguments.
+     *
+     * ```ts
+     * await soc.track('auth.login.success', { actor: user.id });
+     * await soc.track('data.exported', {
+     *   actor: { id: user.id, email: user.email },
+     *   metadata: { format: 'csv' },
+     *   resource: { type: 'Report', id: report.id },
+     * });
+     * ```
+     */
+    track(event: string, options?: TrackOptions): Promise<void>;
+    /**
+     * Track a security event using a raw data object.
+     *
+     * ```ts
+     * await soc.trackData('auth.login.success', {
+     *   actor_id: user.id,
+     *   actor_email: user.email,
+     *   metadata: { role: 'admin' },
+     * });
+     * ```
+     */
+    trackData(event: string, data?: Record<string, unknown>): Promise<void>;
+    /**
+     * Start building an event with the fluent API.
+     *
+     * ```ts
+     * await soc.event('data.exported')
+     *   .actor(user.id)
+     *   .resource('Report', report.id)
+     *   .meta('format', 'csv')
+     *   .send();
+     * ```
+     */
+    event(name: string): EventBuilder;
+    /**
+     * @deprecated No-op — context is now stored per-request in AsyncLocalStorage.
+     * Kept for API compatibility only; will be removed in a future major version.
+     */
+    setContext(): void;
+    /**
+     * @deprecated No-op — context is now stored per-request in AsyncLocalStorage.
+     * Kept for API compatibility only; will be removed in a future major version.
+     */
+    clearContext(): void;
+    private resolveNamedArgs;
+    private static readonly EVENT_TYPE_REGEX;
+    private dispatch;
+    private buildPayload;
+    private collectContext;
+    private sanitizeQueryString;
+    /**
+     * Send an event payload to the ingestor with 429 backoff handling.
+     *
+     * Backoff strategy (mirrors Laravel SDK):
+     *  - On 429: back off for Retry-After seconds (default 1 hour).
+     *  - During backoff: silently drop events, except for a probe every 5 minutes.
+     *  - On successful probe: clear backoff and resume normal sending.
+     */
+    private send;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,EAGL,gBAAgB,EAChB,YAAY,EACb,MAAM,SAAS,CAAC;AA6BjB,qBAAa,eAAe;IAC1B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IAEjC,gDAAgD;IAChD,OAAO,CAAC,YAAY,CAAa;IACjC,OAAO,CAAC,SAAS,CAAa;gBAKlB,OAAO,EAAE,gBAAgB;IAsBrC;;;;;;;;;;;OAWG;IACG,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC;IAKjE;;;;;;;;;;OAUG;IACG,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIjF;;;;;;;;;;OAUG;IACH,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,YAAY;IAIjC;;;OAGG;IACH,UAAU,IAAI,IAAI;IAKlB;;;OAGG;IACH,YAAY,IAAI,IAAI;IAQpB,OAAO,CAAC,gBAAgB;IAgExB,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,gBAAgB,CAAwD;YAElF,QAAQ;IAiBtB,OAAO,CAAC,YAAY;IAsBpB,OAAO,CAAC,cAAc;IAuDtB,OAAO,CAAC,mBAAmB;IAiB3B;;;;;;;OAOG;YACW,IAAI;CAqDnB"}

package/dist/client.js

@@ -0,0 +1,333 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SOCWardenClient = void 0;
+const builder_1 = require("./builder");
+const os_1 = require("os");
+const context_1 = require("./context");
+const SDK_NAME = 'socwarden-node';
+const SDK_VERSION = '1.0.0';
+const BACKOFF_DURATION = 3600; // 1 hour in seconds
+const PROBE_INTERVAL = 300; // 5 minutes in seconds
+const SENSITIVE_PARAMS = ['token', 'key', 'password', 'secret', 'code', 'auth', 'session', 'csrf'];
+/**
+ * Returns ip if it is a valid IPv4 or IPv6 address, otherwise undefined.
+ * Matches the ingestor's validate:"omitempty,ip" constraint.
+ */
+function sanitizeIP(ip) {
+    if (!ip)
+        return undefined;
+    // IPv4
+    const ipv4 = /^(\d{1,3}\.){3}\d{1,3}$/;
+    if (ipv4.test(ip)) {
+        const parts = ip.split('.').map(Number);
+        if (parts.every((p) => p >= 0 && p <= 255))
+            return ip;
+    }
+    // IPv6: contains colon and only hex digits and colons
+    if (ip.includes(':') && /^[0-9a-fA-F:]+$/.test(ip))
+        return ip;
+    return undefined;
+}
+class SOCWardenClient {
+    apiKey;
+    endpoint;
+    timeout;
+    /** In-memory backoff state for 429 handling. */
+    backoffUntil = 0;
+    lastProbe = 0;
+    // D4 FIX: Per-request context is now stored in AsyncLocalStorage (see middleware.ts)
+    // rather than on the shared instance, preventing concurrent request contamination.
+    constructor(options) {
+        if (!options.apiKey) {
+            throw new Error('[SOCWarden] apiKey is required');
+        }
+        this.apiKey = options.apiKey;
+        this.endpoint = (options.endpoint ?? 'https://ingest.socwarden.io').replace(/\/+$/, '');
+        this.timeout = options.timeout ?? 5000;
+        // D2 FIX: Enforce HTTPS to prevent API key transmission in cleartext.
+        if (!this.endpoint.startsWith('https://')) {
+            if (process.env.NODE_ENV === 'production') {
+                throw new Error('[SOCWarden] Endpoint must use HTTPS in production. API keys must not be transmitted in cleartext.');
+            }
+            console.warn('[SOCWarden] WARNING: Endpoint is using HTTP. API keys will be transmitted in cleartext.');
+        }
+    }
+    // ---------------------------------------------------------------------------
+    //  Public API
+    // ---------------------------------------------------------------------------
+    /**
+     * Track a security event using named arguments.
+     *
+     * ```ts
+     * await soc.track('auth.login.success', { actor: user.id });
+     * await soc.track('data.exported', {
+     *   actor: { id: user.id, email: user.email },
+     *   metadata: { format: 'csv' },
+     *   resource: { type: 'Report', id: report.id },
+     * });
+     * ```
+     */
+    async track(event, options) {
+        const data = options ? this.resolveNamedArgs(options) : {};
+        await this.dispatch(event, data);
+    }
+    /**
+     * Track a security event using a raw data object.
+     *
+     * ```ts
+     * await soc.trackData('auth.login.success', {
+     *   actor_id: user.id,
+     *   actor_email: user.email,
+     *   metadata: { role: 'admin' },
+     * });
+     * ```
+     */
+    async trackData(event, data = {}) {
+        await this.dispatch(event, data);
+    }
+    /**
+     * Start building an event with the fluent API.
+     *
+     * ```ts
+     * await soc.event('data.exported')
+     *   .actor(user.id)
+     *   .resource('Report', report.id)
+     *   .meta('format', 'csv')
+     *   .send();
+     * ```
+     */
+    event(name) {
+        return new builder_1.EventBuilder(name, this);
+    }
+    /**
+     * @deprecated No-op — context is now stored per-request in AsyncLocalStorage.
+     * Kept for API compatibility only; will be removed in a future major version.
+     */
+    setContext() {
+        // D4 FIX: Context is stored in AsyncLocalStorage by the middleware.
+        // This method is intentionally a no-op.
+    }
+    /**
+     * @deprecated No-op — context is now stored per-request in AsyncLocalStorage.
+     * Kept for API compatibility only; will be removed in a future major version.
+     */
+    clearContext() {
+        // D4 FIX: AsyncLocalStorage context is automatically scoped to the request.
+    }
+    // ---------------------------------------------------------------------------
+    //  Internal: argument resolution
+    // ---------------------------------------------------------------------------
+    resolveNamedArgs(options) {
+        const data = {};
+        // Actor: object reads id + email; string is just id
+        if (options.actor !== undefined) {
+            if (typeof options.actor === 'string') {
+                data.actor_id = options.actor;
+            }
+            else {
+                data.actor_id = options.actor.id;
+                if (options.actor.email) {
+                    data.actor_email = options.actor.email;
+                }
+            }
+        }
+        // Explicit scalars override actor-resolved values
+        if (options.actorId !== undefined) {
+            data.actor_id = options.actorId;
+        }
+        if (options.actorEmail !== undefined) {
+            data.actor_email = options.actorEmail;
+        }
+        if (options.ip !== undefined) {
+            data.ip = sanitizeIP(options.ip);
+        }
+        if (options.userAgent !== undefined) {
+            data.user_agent = options.userAgent;
+        }
+        if (options.metadata !== undefined) {
+            data.metadata = { ...options.metadata };
+        }
+        if (options.timestamp !== undefined) {
+            data.timestamp =
+                options.timestamp instanceof Date
+                    ? options.timestamp.toISOString()
+                    : options.timestamp;
+        }
+        // Resource: object reads type + id; string is just type
+        if (options.resource !== undefined) {
+            const meta = (data.metadata ?? {});
+            if (typeof options.resource === 'string') {
+                meta.resource_type = options.resource;
+                if (options.resourceId !== undefined) {
+                    meta.resource_id = options.resourceId;
+                }
+            }
+            else {
+                meta.resource_type = options.resource.type;
+                meta.resource_id = options.resource.id;
+            }
+            data.metadata = meta;
+        }
+        // Remove undefined values
+        return Object.fromEntries(Object.entries(data).filter(([, v]) => v !== undefined && v !== null));
+    }
+    // ---------------------------------------------------------------------------
+    //  Internal: dispatch and send
+    // ---------------------------------------------------------------------------
+    // D3 FIX: Validate event_type format before sending to the ingestor.
+    static EVENT_TYPE_REGEX = /^[a-z][a-z0-9]{0,29}(\.[a-z][a-z0-9_]{0,29}){1,3}$/;
+    async dispatch(event, data) {
+        // D3 FIX: Validate event type format before sending.
+        if (!SOCWardenClient.EVENT_TYPE_REGEX.test(event)) {
+            console.warn(`[SOCWarden] Invalid event type format, dropping event: "${event}". ` +
+                'Event types must match ^[a-z][a-z0-9]{0,29}(\\.[a-z][a-z0-9_]{0,29}){1,3}$');
+            return;
+        }
+        const payload = this.buildPayload(event, data);
+        try {
+            await this.send(payload);
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            console.warn(`[SOCWarden] Failed to send event: ${message}`);
+        }
+    }
+    buildPayload(event, data) {
+        const payload = {
+            event,
+            source: 'sdk',
+        };
+        const fields = ['actor_id', 'actor_email', 'user_agent', 'metadata', 'timestamp'];
+        for (const field of fields) {
+            if (data[field] !== undefined) {
+                payload[field] = data[field];
+            }
+        }
+        if (data.ip !== undefined) {
+            payload.ip = data.ip;
+        }
+        // Attach auto-context if middleware captured it
+        payload.context = this.collectContext(data);
+        return payload;
+    }
+    collectContext(data) {
+        const context = {
+            sdk: {
+                name: SDK_NAME,
+                version: SDK_VERSION,
+            },
+            server: {
+                hostname: (0, os_1.hostname)(),
+                runtime: `Node.js ${process.version}`,
+                pid: process.pid,
+            },
+        };
+        // D4 FIX: Read per-request context from AsyncLocalStorage instead of the
+        // shared instance property to prevent concurrent request contamination.
+        const requestCtx = context_1.requestContextStorage.getStore();
+        if (requestCtx?.request) {
+            const req = requestCtx.request;
+            context.request = {
+                method: req.method,
+                path: req.path,
+            };
+            if (req.ip) {
+                context.request.ip = req.ip;
+            }
+            if (req.queryString) {
+                context.request.query_string = this.sanitizeQueryString(req.queryString);
+            }
+            if (req.referer) {
+                context.request.referer = req.referer;
+            }
+            if (req.origin) {
+                context.request.origin = req.origin;
+            }
+            if (req.contentType) {
+                context.request.content_type = req.contentType;
+            }
+            if (req.acceptLanguage) {
+                context.request.accept_language = req.acceptLanguage;
+            }
+            if (req.requestId) {
+                context.request.request_id = req.requestId;
+            }
+            if (req.userAgent) {
+                context.request.user_agent = req.userAgent;
+            }
+        }
+        // D1 FIX: Browser context from X-SOCWarden-Context header removed —
+        // trusting arbitrary HTTP headers allows spoofing of server-side metadata.
+        return context;
+    }
+    sanitizeQueryString(qs) {
+        if (!qs)
+            return '';
+        return qs
+            .split('&')
+            .map((pair) => {
+            const [key, ...rest] = pair.split('=');
+            const paramName = key.toLowerCase();
+            const isSensitive = SENSITIVE_PARAMS.some((s) => paramName.includes(s));
+            if (isSensitive && rest.length > 0) {
+                return `${key}=[REDACTED]`;
+            }
+            return pair;
+        })
+            .join('&');
+    }
+    /**
+     * Send an event payload to the ingestor with 429 backoff handling.
+     *
+     * Backoff strategy (mirrors Laravel SDK):
+     *  - On 429: back off for Retry-After seconds (default 1 hour).
+     *  - During backoff: silently drop events, except for a probe every 5 minutes.
+     *  - On successful probe: clear backoff and resume normal sending.
+     */
+    async send(payload) {
+        const now = Math.floor(Date.now() / 1000);
+        // Check backoff
+        if (this.backoffUntil > 0 && now < this.backoffUntil) {
+            // During backoff, only send probes at PROBE_INTERVAL
+            if (now - this.lastProbe < PROBE_INTERVAL) {
+                return; // silently drop
+            }
+            this.lastProbe = now;
+        }
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+        try {
+            const response = await fetch(`${this.endpoint}/v1/events`, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    Authorization: `Bearer ${this.apiKey}`,
+                },
+                body: JSON.stringify(payload),
+                signal: controller.signal,
+            });
+            if (response.status === 429) {
+                const retryAfter = parseInt(response.headers.get('Retry-After') ?? '', 10);
+                const backoffSeconds = isNaN(retryAfter) ? BACKOFF_DURATION : retryAfter;
+                this.backoffUntil = now + backoffSeconds;
+                console.warn(`[SOCWarden] Quota exceeded (429). Backing off for ${backoffSeconds}s`);
+                return;
+            }
+            // Clear backoff on any successful response
+            if (response.ok && this.backoffUntil > 0) {
+                this.backoffUntil = 0;
+                this.lastProbe = 0;
+                console.info('[SOCWarden] Quota restored, backoff cleared');
+            }
+            if (!response.ok) {
+                const body = await response.text().catch(() => '');
+                console.warn(`[SOCWarden] Event send failed (HTTP ${response.status}): ${body}`);
+            }
+        }
+        finally {
+            clearTimeout(timeoutId);
+        }
+    }
+}
+exports.SOCWardenClient = SOCWardenClient;
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

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

package/dist/context.d.ts

@@ -0,0 +1,13 @@
+import { AsyncLocalStorage } from 'async_hooks';
+import type { CapturedContext } from './types';
+/**
+ * D4 FIX: Per-request AsyncLocalStorage context store.
+ *
+ * Storing per-request context (IP, user-agent, etc.) on the shared singleton
+ * SOCWardenClient instance causes concurrent requests to contaminate each
+ * other's context. AsyncLocalStorage provides automatic isolation: each
+ * request runs in its own async context and getStore() always returns the
+ * correct context for the current request, even under high concurrency.
+ */
+export declare const requestContextStorage: AsyncLocalStorage<CapturedContext>;
+//# sourceMappingURL=context.d.ts.map

package/dist/context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAE/C;;;;;;;;GAQG;AACH,eAAO,MAAM,qBAAqB,oCAA2C,CAAC"}

package/dist/context.js

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.requestContextStorage = void 0;
+const async_hooks_1 = require("async_hooks");
+/**
+ * D4 FIX: Per-request AsyncLocalStorage context store.
+ *
+ * Storing per-request context (IP, user-agent, etc.) on the shared singleton
+ * SOCWardenClient instance causes concurrent requests to contaminate each
+ * other's context. AsyncLocalStorage provides automatic isolation: each
+ * request runs in its own async context and getStore() always returns the
+ * correct context for the current request, even under high concurrency.
+ */
+exports.requestContextStorage = new async_hooks_1.AsyncLocalStorage();
+//# sourceMappingURL=context.js.map

package/dist/context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.js","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":";;;AAAA,6CAAgD;AAGhD;;;;;;;;GAQG;AACU,QAAA,qBAAqB,GAAG,IAAI,+BAAiB,EAAmB,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { SOCWardenClient } from './client';
+export { EventBuilder } from './builder';
+export { socwardenMiddleware } from './middleware';
+export type { SOCWardenOptions, TrackOptions, ActorInput, ResourceInput, EventPayload, RequestContext, CapturedContext, } from './types';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,UAAU,CAAC;AAC3C,OAAO,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC;AACnD,YAAY,EACV,gBAAgB,EAChB,YAAY,EACZ,UAAU,EACV,aAAa,EACb,YAAY,EACZ,cAAc,EACd,eAAe,GAChB,MAAM,SAAS,CAAC"}

package/dist/index.js

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.socwardenMiddleware = exports.EventBuilder = exports.SOCWardenClient = void 0;
+var client_1 = require("./client");
+Object.defineProperty(exports, "SOCWardenClient", { enumerable: true, get: function () { return client_1.SOCWardenClient; } });
+var builder_1 = require("./builder");
+Object.defineProperty(exports, "EventBuilder", { enumerable: true, get: function () { return builder_1.EventBuilder; } });
+var middleware_1 = require("./middleware");
+Object.defineProperty(exports, "socwardenMiddleware", { enumerable: true, get: function () { return middleware_1.socwardenMiddleware; } });
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;AAAA,mCAA2C;AAAlC,yGAAA,eAAe,OAAA;AACxB,qCAAyC;AAAhC,uGAAA,YAAY,OAAA;AACrB,2CAAmD;AAA1C,iHAAA,mBAAmB,OAAA"}

package/dist/middleware.d.ts

@@ -0,0 +1,42 @@
+import type { SOCWardenClient } from './client';
+export { requestContextStorage } from './context';
+/**
+ * Minimal Express-compatible request interface.
+ * Avoids requiring Express as a dependency.
+ */
+interface ExpressRequest {
+    method: string;
+    path: string;
+    ip?: string;
+    query?: Record<string, unknown>;
+    get(header: string): string | undefined;
+}
+/**
+ * Minimal Express-compatible response interface.
+ */
+interface ExpressResponse {
+    on(event: string, listener: () => void): void;
+}
+/**
+ * Minimal Express-compatible next function.
+ */
+type NextFunction = (err?: unknown) => void;
+/**
+ * Express middleware that captures request context for SOCWarden events.
+ *
+ * When active, every event sent during the request lifecycle will automatically
+ * include request metadata (method, path, IP, user-agent, etc.) in the
+ * `context` field of the payload.
+ *
+ * ```ts
+ * import express from 'express';
+ * import { SOCWardenClient, socwardenMiddleware } from '@socwarden/sdk';
+ *
+ * const soc = new SOCWardenClient({ apiKey: 'sk_live_...' });
+ * const app = express();
+ *
+ * app.use(socwardenMiddleware(soc));
+ * ```
+ */
+export declare function socwardenMiddleware(client: SOCWardenClient): (req: ExpressRequest, _res: ExpressResponse, next: NextFunction) => void;
+//# sourceMappingURL=middleware.d.ts.map

package/dist/middleware.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"middleware.d.ts","sourceRoot":"","sources":["../src/middleware.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,UAAU,CAAC;AAGhD,OAAO,EAAE,qBAAqB,EAAE,MAAM,WAAW,CAAC;AAElD;;;GAGG;AACH,UAAU,cAAc;IACtB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAChC,GAAG,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;CACzC;AAED;;GAEG;AACH,UAAU,eAAe;IACvB,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,IAAI,GAAG,IAAI,CAAC;CAC/C;AAED;;GAEG;AACH,KAAK,YAAY,GAAG,CAAC,GAAG,CAAC,EAAE,OAAO,KAAK,IAAI,CAAC;AAE5C;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,eAAe,IAMjD,KAAK,cAAc,EAAE,MAAM,eAAe,EAAE,MAAM,YAAY,KAAG,IAAI,CA8B9E"}

package/dist/middleware.js

@@ -0,0 +1,71 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.requestContextStorage = void 0;
+exports.socwardenMiddleware = socwardenMiddleware;
+const context_1 = require("./context");
+var context_2 = require("./context");
+Object.defineProperty(exports, "requestContextStorage", { enumerable: true, get: function () { return context_2.requestContextStorage; } });
+/**
+ * Express middleware that captures request context for SOCWarden events.
+ *
+ * When active, every event sent during the request lifecycle will automatically
+ * include request metadata (method, path, IP, user-agent, etc.) in the
+ * `context` field of the payload.
+ *
+ * ```ts
+ * import express from 'express';
+ * import { SOCWardenClient, socwardenMiddleware } from '@socwarden/sdk';
+ *
+ * const soc = new SOCWardenClient({ apiKey: 'sk_live_...' });
+ * const app = express();
+ *
+ * app.use(socwardenMiddleware(soc));
+ * ```
+ */
+function socwardenMiddleware(client) {
+    // D4 FIX: client parameter retained for API compatibility but context is now
+    // stored in AsyncLocalStorage instead of on the shared singleton instance,
+    // preventing concurrent request context contamination.
+    void client;
+    return (req, _res, next) => {
+        const queryString = buildQueryString(req.query);
+        const capturedContext = {
+            request: {
+                method: req.method,
+                path: req.path,
+                ip: req.ip ?? req.get('x-forwarded-for')?.split(',')[0].trim(),
+                userAgent: req.get('user-agent'),
+                queryString,
+                referer: req.get('referer'),
+                origin: req.get('origin'),
+                contentType: req.get('content-type'),
+                acceptLanguage: req.get('accept-language'),
+                requestId: req.get('x-request-id') ?? req.get('x-correlation-id'),
+            },
+            sdk: {
+                name: 'socwarden-node',
+                version: '1.0.0',
+            },
+        };
+        // D1 FIX: X-SOCWarden-Context header removed — trusting arbitrary HTTP headers
+        // allows any client to spoof server-side metadata. Server context is collected
+        // locally by the SDK and must not be merged from incoming request headers.
+        // D4 FIX: Run the rest of the request handling within the AsyncLocalStorage
+        // context so each concurrent request has its own isolated context.
+        context_1.requestContextStorage.run(capturedContext, next);
+    };
+}
+/**
+ * Reconstruct a query string from Express's parsed query object.
+ */
+function buildQueryString(query) {
+    if (!query)
+        return undefined;
+    const entries = Object.entries(query).filter(([, v]) => v !== undefined && v !== null);
+    if (entries.length === 0)
+        return undefined;
+    return entries
+        .map(([k, v]) => `${encodeURIComponent(k)}=${encodeURIComponent(String(v))}`)
+        .join('&');
+}
+//# sourceMappingURL=middleware.js.map

package/dist/middleware.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"middleware.js","sourceRoot":"","sources":["../src/middleware.ts"],"names":[],"mappings":";;;AA8CA,kDAoCC;AAjFD,uCAAkD;AAElD,qCAAkD;AAAzC,gHAAA,qBAAqB,OAAA;AA0B9B;;;;;;;;;;;;;;;;GAgBG;AACH,SAAgB,mBAAmB,CAAC,MAAuB;IACzD,6EAA6E;IAC7E,2EAA2E;IAC3E,uDAAuD;IACvD,KAAK,MAAM,CAAC;IAEZ,OAAO,CAAC,GAAmB,EAAE,IAAqB,EAAE,IAAkB,EAAQ,EAAE;QAC9E,MAAM,WAAW,GAAG,gBAAgB,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;QAEhD,MAAM,eAAe,GAAoB;YACvC,OAAO,EAAE;gBACP,MAAM,EAAE,GAAG,CAAC,MAAM;gBAClB,IAAI,EAAE,GAAG,CAAC,IAAI;gBACd,EAAE,EAAE,GAAG,CAAC,EAAE,IAAI,GAAG,CAAC,GAAG,CAAC,iBAAiB,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE;gBAC9D,SAAS,EAAE,GAAG,CAAC,GAAG,CAAC,YAAY,CAAC;gBAChC,WAAW;gBACX,OAAO,EAAE,GAAG,CAAC,GAAG,CAAC,SAAS,CAAC;gBAC3B,MAAM,EAAE,GAAG,CAAC,GAAG,CAAC,QAAQ,CAAC;gBACzB,WAAW,EAAE,GAAG,CAAC,GAAG,CAAC,cAAc,CAAC;gBACpC,cAAc,EAAE,GAAG,CAAC,GAAG,CAAC,iBAAiB,CAAC;gBAC1C,SAAS,EAAE,GAAG,CAAC,GAAG,CAAC,cAAc,CAAC,IAAI,GAAG,CAAC,GAAG,CAAC,kBAAkB,CAAC;aAClE;YACD,GAAG,EAAE;gBACH,IAAI,EAAE,gBAAgB;gBACtB,OAAO,EAAE,OAAO;aACjB;SACF,CAAC;QAEF,+EAA+E;QAC/E,+EAA+E;QAC/E,2EAA2E;QAE3E,4EAA4E;QAC5E,mEAAmE;QACnE,+BAAqB,CAAC,GAAG,CAAC,eAAe,EAAE,IAAI,CAAC,CAAC;IACnD,CAAC,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,SAAS,gBAAgB,CAAC,KAA+B;IACvD,IAAI,CAAC,KAAK;QAAE,OAAO,SAAS,CAAC;IAE7B,MAAM,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,MAAM,CAC1C,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,KAAK,SAAS,IAAI,CAAC,KAAK,IAAI,CACzC,CAAC;IACF,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,SAAS,CAAC;IAE3C,OAAO,OAAO;SACX,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,kBAAkB,CAAC,CAAC,CAAC,IAAI,kBAAkB,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;SAC5E,IAAI,CAAC,GAAG,CAAC,CAAC;AACf,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,114 @@
+/**
+ * Configuration options for the SOCWarden client.
+ */
+export interface SOCWardenOptions {
+    /** API key for authenticating with the SOCWarden ingestor. */
+    apiKey: string;
+    /** Ingestor endpoint URL. Defaults to https://ingest.socwarden.io */
+    endpoint?: string;
+    /** HTTP request timeout in milliseconds. Defaults to 5000. */
+    timeout?: number;
+}
+/**
+ * Actor identification — either a string ID or an object with id and optional email.
+ */
+export type ActorInput = string | {
+    id: string;
+    email?: string;
+};
+/**
+ * Resource identification — either a string type or an object with type and id.
+ */
+export type ResourceInput = string | {
+    type: string;
+    id: string;
+};
+/**
+ * Options for the `track()` method (named-args style).
+ */
+export interface TrackOptions {
+    /** Actor (user) who triggered the event. String is treated as actor ID. */
+    actor?: ActorInput;
+    /** Explicit actor ID (overrides actor if both provided). */
+    actorId?: string;
+    /** Explicit actor email (overrides actor.email if both provided). */
+    actorEmail?: string;
+    /** Source IP address. Auto-detected from request context if middleware is active. */
+    ip?: string;
+    /** User-Agent string. Auto-detected from request context if middleware is active. */
+    userAgent?: string;
+    /** Custom metadata key-value pairs. */
+    metadata?: Record<string, unknown>;
+    /** Event timestamp (ISO 8601 string or Date object). Defaults to now. */
+    timestamp?: string | Date;
+    /** Resource that was acted upon. String is treated as resource type. */
+    resource?: ResourceInput;
+    /** Explicit resource ID (used when resource is a string type). */
+    resourceId?: string;
+}
+/**
+ * Payload sent to the SOCWarden ingestor POST /v1/events endpoint.
+ */
+export interface EventPayload {
+    event: string;
+    source: string;
+    actor_id?: string;
+    actor_email?: string;
+    ip?: string;
+    user_agent?: string;
+    metadata?: Record<string, unknown>;
+    timestamp?: string;
+    context?: RequestContext;
+}
+/**
+ * Auto-collected context attached to every event when middleware is active.
+ */
+export interface RequestContext {
+    sdk: {
+        name: string;
+        version: string;
+    };
+    server?: {
+        hostname: string;
+        runtime: string;
+        pid: number;
+    };
+    request?: {
+        method: string;
+        path: string;
+        ip?: string;
+        user_agent?: string;
+        query_string?: string;
+        referer?: string;
+        origin?: string;
+        content_type?: string;
+        accept_language?: string;
+        request_id?: string;
+    };
+    /** Browser context relayed from the browser SDK via X-SOCWarden-Context header. */
+    browser?: Record<string, unknown>;
+}
+/**
+ * Internal context captured by the Express middleware for the current request.
+ */
+export interface CapturedContext {
+    request: {
+        method: string;
+        path: string;
+        ip?: string;
+        userAgent?: string;
+        queryString?: string;
+        referer?: string;
+        origin?: string;
+        contentType?: string;
+        acceptLanguage?: string;
+        requestId?: string;
+    };
+    sdk: {
+        name: string;
+        version: string;
+    };
+    /** Browser context decoded from X-SOCWarden-Context header (relay mode). */
+    browser?: Record<string, unknown>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

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

package/dist/types.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@socwarden/sdk",
+  "version": "1.0.0-alpha.1",
+  "description": "SOCWarden Node.js/TypeScript SDK for security event tracking",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "test": "npx tsx --test src/__tests__/*.test.ts",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "socwarden",
+    "security",
+    "soc",
+    "event-tracking",
+    "threat-detection"
+  ],
+  "license": "MIT",
+  "devDependencies": {
+    "@types/node": "^25.5.0",
+    "tsx": "^4.21.0",
+    "typescript": "^5.5.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}