@veridia/node-sdk 1.0.2

package/.github/workflows/publish.yml

@@ -0,0 +1,49 @@
+name: Build & Publish
+
+on:
+  push:
+    tags:
+      - 'v*.*.*' # triggers only for version tags (v1.0.0, v1.1.2, etc.)
+
+jobs:
+  build-and-publish:
+    name: Build and publish to npm
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Use Node.js 22
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          registry-url: 'https://registry.npmjs.org/'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Lint
+        run: npm run lint --if-present
+
+      - name: Run tests
+        run: npm test --if-present
+
+      - name: Build SDK (CJS + ESM)
+        run: npm run build
+
+      - name: Verify package contents
+        run: npm pack --dry-run
+
+      - name: Publish to npm
+        if: startsWith(github.ref, 'refs/tags/v')
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+        run: npm publish --access public
+
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          generate_release_notes: true

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 veridia-io
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+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

@@ -0,0 +1,207 @@
+# Veridia Node SDK
+
+Official Node.js SDK for integrating with [Veridia Platform](https://veridia.io).  
+It provides an easy way to send user identification and tracking data, retrieve user segments, and integrate Veridia into your backend systems.
+
+---
+
+## 🚀 Installation
+
+```bash
+npm install @veridia/node-sdk
+```
+
+or with Yarn:
+
+```bash
+yarn add @veridia/node-sdk
+```
+
+---
+
+## 📦 Usage
+
+### ESM
+
+```ts
+import { VeridiaClient } from '@veridia/node-sdk';
+
+const client = new VeridiaClient({
+  accessKeyId: 'your-access-key-id',
+  secretAccessKey: 'your-secret-access-key',
+  logger: {
+    error: (service, msg, ctx) => console.error(`[ERROR] ${service}: ${msg}`, ctx),
+    warn: (service, msg, ctx) => console.warn(`[WARN] ${service}: ${msg}`, ctx),
+    info: (service, msg, ctx) => console.log(`[INFO] ${service}: ${msg}`, ctx),
+  },
+});
+```
+
+### CommonJS
+
+```js
+const { VeridiaClient } = require('@veridia/node-sdk');
+
+const client = new VeridiaClient({
+  accessKeyId: 'your-access-key-id',
+  secretAccessKey: 'your-secret-access-key',
+  logger: { error: console.error },
+});
+```
+
+---
+
+## 🧠 API Reference
+
+### `identify(identifierType, identifierId, attributes)`
+
+Identify a user and update their profile attributes. Provided attributes must match the Profile Attributes schema defined in the Veridia dashboard.
+
+```ts
+await client.identify('userId', '123', {
+  email: 'user@example.com',
+  country: 'US',
+  plan: 'premium',
+});
+```
+
+| Parameter        | Type                    | Description                  |
+| ---------------- | ----------------------- | ---------------------------- |
+| `identifierType` | `"userId"` \| `"email"` | How the user is identified.  |
+| `identifierId`   | `string`                | The unique identifier value. |
+| `attributes`     | `Record<string, any>`   | Arbitrary user attributes.   |
+
+---
+
+### `track(identifierType, identifierId, eventType, eventId, eventTime, properties)`
+
+Track an event performed by a user. Provided attributes must match the event attributes schema defined in the Veridia dashboard.
+
+```ts
+await client.track('userId', '123', 'purchase', 'evt-001', new Date().toISOString(), {
+  productId: 'A-1',
+  price: 49.99,
+});
+```
+
+| Parameter        | Type                    | Description                         |
+| ---------------- | ----------------------- | ----------------------------------- |
+| `identifierType` | `"userId"` \| `"email"` | How the user is identified.         |
+| `identifierId`   | `string`                | Unique identifier for the user.     |
+| `eventType`      | `string`                | Event type as in Veridia dashboard. |
+| `eventId`        | `string`                | Unique event ID for idempotency.    |
+| `eventTime`      | `string`                | ISO timestamp string.               |
+| `properties`     | `Record<string, any>`   | Optional event properties.          |
+
+---
+
+### `getUserSegments(identifierType, identifierId)`
+
+Fetches the list of segments the specified user currently belongs to.
+
+```ts
+const segments = await client.getUserSegments('userId', '123');
+console.log(segments); // ['617090ac-a1f6-4c70-a79e-40830a367324', '67f2c139-850f-469f-9ca4-a1c58e6d84ea']
+```
+
+Returns:
+`Promise<string[]>` — Array of segment identifiers.
+
+---
+
+### `flush()`
+
+Immediately sends all queued identify and track data.
+
+```ts
+await client.flush();
+```
+
+### `close()`
+
+Flushes all pending data and prepares the client for shutdown.
+Call this before process exit in background workers or serverless functions.
+
+```ts
+await client.close();
+```
+
+---
+
+## ⚙️ Configuration Options
+
+| Option                     | Type            | Default                     | Description                            |
+| -------------------------- | --------------- | --------------------------- | -------------------------------------- |
+| `accessKeyId`              | `string`        | —                           | Veridia API access key ID              |
+| `secretAccessKey`          | `string`        | —                           | Veridia API secret                     |
+| `endpoint`                 | `string`        | `https://api.veridia.io/v1` | API base URL                           |
+| `region`                   | `string`        | `"default"`                 | API region                             |
+| `maxBufferSize`            | `number`        | `500`                       | Max number of items before auto-flush  |
+| `maxBufferTimeMs`          | `number`        | `5000`                      | Max time before auto-flush             |
+| `retries`                  | `number`        | `3`                         | Retry attempts on transient errors     |
+| `timeoutMsGetUserSegments` | `number`        | `5000`                      | Timeout for `getUserSegments` requests |
+| `timeoutMsFlush`           | `number`        | `30000`                     | Timeout for batch flush                |
+| `logger`                   | `VeridiaLogger` | —                           | Custom logger implementation           |
+
+---
+
+## 🧾 Logger Interface
+
+The SDK supports pluggable logging.
+You can integrate your own logger (e.g. Pino, Winston, Bunyan) by providing the following interface:
+
+```ts
+interface VeridiaLogger {
+  info(service: string, message: string, context?: unknown): void;
+  warn(service: string, message: string, context?: unknown): void;
+  error(service: string, message: string, context?: unknown): void;
+}
+```
+
+Example:
+
+```ts
+import pino from 'pino';
+const log = pino();
+
+const client = new VeridiaClient({
+  accessKeyId: '...',
+  secretAccessKey: '...',
+  logger: {
+    info: (s, m, c) => log.info({ service: s, context: c }, m),
+    warn: (s, m, c) => log.warn({ service: s, context: c }, m),
+    error: (s, m, c) => log.error({ service: s, context: c }, m),
+  },
+});
+```
+
+---
+
+## 🧩 TypeScript Support
+
+The SDK ships with full `.d.ts` declarations and JSDoc for IntelliSense.
+Hover over any method in VS Code to see inline documentation and parameter hints.
+
+---
+
+## 🧪 Example Usage
+
+```ts
+import { VeridiaClient } from '@veridia/node-sdk';
+
+const client = new VeridiaClient({
+  accessKeyId: 'test',
+  secretAccessKey: 'test',
+  logger: { error: console.error },
+});
+
+await client.identify('userId', '123', { plan: 'gold' });
+await client.track('userId', '123', 'purchase', 'evt-123', new Date().toISOString());
+await client.flush();
+```
+
+---
+
+## 🧱 License
+
+[MIT](./LICENSE) © Veridia

package/dist/cjs/client.d.ts

@@ -0,0 +1,56 @@
+import { IdentifierPayload, IdentifyPayload, TrackPayload, VeridiaClientOptions } from './types.js';
+export declare class VeridiaClient {
+    private readonly options;
+    private trackBuffer;
+    private identifyBuffer;
+    private flushTimer?;
+    private readonly logger;
+    private readonly baseUrl;
+    private readonly region;
+    private readonly maxBufferSize;
+    private readonly maxBufferTimeMs;
+    private readonly retries;
+    private readonly retryBaseDelayMs;
+    private readonly timeoutMsGetUserSegments;
+    private readonly timeoutMsFlush;
+    constructor(options: VeridiaClientOptions);
+    /**
+     * Queues a user identification update to be flushed in batch.
+     *
+     * @param identifierType - The type of user identifier ("userId" | "email").
+     * @param identifierId - The unique ID or email.
+     * @param attributes - Key/value map of user attributes.
+     */
+    identify(identifierType: IdentifierPayload['type'], identifierId: IdentifierPayload['id'], attributes: IdentifyPayload['attributes']): void;
+    /**
+     * Sends a tracking event for the given user.
+     *
+     * @param identifierType - The type of user identifier ("userId" | "email").
+     * @param identifierId - The unique ID or email.
+     * @param eventType - Logical name of the event.
+     * @param eventId - Unique ID for idempotency.
+     * @param eventTime - ISO timestamp string.
+     * @param properties - Arbitrary event properties.
+     */
+    track(identifierType: IdentifierPayload['type'], identifierId: IdentifierPayload['id'], eventType: TrackPayload['eventType'], eventId: TrackPayload['eventId'], eventTime: TrackPayload['eventTime'], properties: TrackPayload['properties']): void;
+    /**
+     * Retrieves the current segments for the given user.
+     *
+     * @param identifierType - The type of user identifier ("userId" | "email").
+     * @param identifierId - The unique ID or email.
+     * @returns A list of segment identifiers the user currently belongs to.
+     */
+    getUserSegments(identifierType: IdentifierPayload['type'], identifierId: string): Promise<string[]>;
+    /**
+     * Sends all queued identify and track data to the Veridia API immediately.
+     * Automatically called when buffers reach their limit or after the configured time interval.
+     */
+    flush(): Promise<void>;
+    /**
+     * Flushes all pending data and prepares the client for shutdown.
+     * Should be called before application exit to ensure all data is sent.
+     */
+    close(): Promise<void>;
+    private scheduleFlushIfNeeded;
+    private flushBatch;
+}

package/dist/cjs/client.js

@@ -0,0 +1,220 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VeridiaClient = void 0;
+const aws4 = __importStar(require("aws4"));
+const http_js_1 = require("./http.js");
+const version_js_1 = require("./version.js");
+class VeridiaClient {
+    constructor(options) {
+        this.options = options;
+        this.trackBuffer = [];
+        this.identifyBuffer = [];
+        this.baseUrl = options.endpoint ?? 'https://api.veridia.io/v1';
+        this.region = options.region ?? 'default';
+        this.maxBufferSize = options.maxBufferSize ?? 500;
+        this.maxBufferTimeMs = options.maxBufferTimeMs ?? 5000;
+        this.retries = options.retries ?? 3;
+        this.retryBaseDelayMs = options.retryBaseDelayMs ?? 500;
+        this.timeoutMsGetUserSegments = options.timeoutMsGetUserSegments ?? 5_000;
+        this.timeoutMsFlush = options.timeoutMsFlush ?? 30_000;
+        this.logger = options.logger;
+    }
+    /**
+     * Queues a user identification update to be flushed in batch.
+     *
+     * @param identifierType - The type of user identifier ("userId" | "email").
+     * @param identifierId - The unique ID or email.
+     * @param attributes - Key/value map of user attributes.
+     */
+    identify(identifierType, identifierId, attributes) {
+        this.identifyBuffer.push({
+            identifier: {
+                type: identifierType,
+                id: identifierId,
+            },
+            attributes,
+        });
+        this.scheduleFlushIfNeeded(this.identifyBuffer);
+    }
+    /**
+     * Sends a tracking event for the given user.
+     *
+     * @param identifierType - The type of user identifier ("userId" | "email").
+     * @param identifierId - The unique ID or email.
+     * @param eventType - Logical name of the event.
+     * @param eventId - Unique ID for idempotency.
+     * @param eventTime - ISO timestamp string.
+     * @param properties - Arbitrary event properties.
+     */
+    track(identifierType, identifierId, eventType, eventId, eventTime, properties) {
+        this.trackBuffer.push({
+            identifier: { type: identifierType, id: identifierId },
+            eventId,
+            eventType,
+            eventTime,
+            properties,
+        });
+        this.scheduleFlushIfNeeded(this.trackBuffer);
+    }
+    /**
+     * Retrieves the current segments for the given user.
+     *
+     * @param identifierType - The type of user identifier ("userId" | "email").
+     * @param identifierId - The unique ID or email.
+     * @returns A list of segment identifiers the user currently belongs to.
+     */
+    async getUserSegments(identifierType, identifierId) {
+        try {
+            const path = `/segments/${identifierType}/${encodeURIComponent(identifierId)}`;
+            const url = `${this.baseUrl}${path}`;
+            const req = {
+                host: new URL(url).host,
+                path,
+                method: 'GET',
+                service: 'segments',
+                region: this.region,
+                headers: { 'User-Agent': `veridia-node-sdk/${version_js_1.SDK_VERSION}` },
+            };
+            aws4.sign(req, this.options);
+            const controller = new AbortController();
+            const timeout = setTimeout(() => controller.abort(), this.timeoutMsGetUserSegments);
+            const res = await (0, http_js_1.httpFetch)(url, {
+                method: req.method,
+                headers: req.headers,
+                signal: controller.signal,
+            }).finally(() => clearTimeout(timeout));
+            if (!res.ok) {
+                this.logger?.error('segments', 'getUserSegments API call failed', { status: res.status });
+                return [];
+            }
+            const data = (await res.json());
+            if (data.status === 'success' && Array.isArray(data.data)) {
+                return data.data;
+            }
+            this.logger?.error('segments', 'getUserSegments API returned invalid response', {
+                data: data,
+            });
+            return [];
+        }
+        catch (err) {
+            this.logger?.error('segments', 'getUserSegments encountered an error', {
+                error: err,
+            });
+            return [];
+        }
+    }
+    /**
+     * Sends all queued identify and track data to the Veridia API immediately.
+     * Automatically called when buffers reach their limit or after the configured time interval.
+     */
+    async flush() {
+        if (this.flushTimer) {
+            clearTimeout(this.flushTimer);
+            this.flushTimer = undefined;
+        }
+        await Promise.all([
+            this.flushBatch('profiles', this.identifyBuffer),
+            this.flushBatch('events', this.trackBuffer),
+        ]);
+    }
+    /**
+     * Flushes all pending data and prepares the client for shutdown.
+     * Should be called before application exit to ensure all data is sent.
+     */
+    async close() {
+        await this.flush();
+    }
+    scheduleFlushIfNeeded(buffer) {
+        if (buffer.length >= this.maxBufferSize) {
+            void this.flush();
+        }
+        else if (!this.flushTimer) {
+            this.flushTimer = setTimeout(() => this.flush(), this.maxBufferTimeMs);
+        }
+    }
+    async flushBatch(service, buffer) {
+        if (buffer.length === 0)
+            return;
+        const batch = [...buffer];
+        buffer.length = 0; // clear buffer safely
+        const urlObj = new URL(this.baseUrl + '/' + service);
+        const opts = {
+            host: urlObj.host,
+            path: urlObj.pathname + urlObj.search,
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                'User-Agent': `veridia-node-sdk/${version_js_1.SDK_VERSION}`,
+            },
+            body: JSON.stringify({ [service]: batch }),
+            service,
+            region: this.region,
+        };
+        aws4.sign(opts, this.options);
+        const signedOpts = {
+            method: opts.method,
+            headers: opts.headers,
+            body: opts.body,
+        };
+        for (let attempt = 1; attempt <= this.retries; attempt++) {
+            try {
+                const controller = new AbortController();
+                const timeout = setTimeout(() => controller.abort(), this.timeoutMsFlush);
+                const res = await (0, http_js_1.httpFetch)(urlObj.toString(), {
+                    ...signedOpts,
+                    signal: controller.signal,
+                }).finally(() => clearTimeout(timeout));
+                if (!res.ok) {
+                    throw new Error(`${service} flush failed: ${res.status}`);
+                }
+                if (this.logger?.info)
+                    this.logger.info(service, 'flush completed', { batchSize: batch.length });
+                return;
+            }
+            catch (err) {
+                if (this.logger?.warn)
+                    this.logger.warn(service, `flush attempt ${attempt} failed`, { error: err });
+                if (attempt === this.retries) {
+                    this.logger?.error(service, `flush failed after max retries`, { error: err });
+                    throw err;
+                }
+                await new Promise((r) => setTimeout(r, this.retryBaseDelayMs * 2 ** (attempt - 1))); // backoff
+            }
+        }
+    }
+}
+exports.VeridiaClient = VeridiaClient;
+//# sourceMappingURL=client.js.map

package/dist/cjs/http.d.ts

@@ -0,0 +1 @@
+export declare function httpFetch(input: RequestInfo | URL, init?: RequestInit): Promise<Response>;

package/dist/cjs/http.js

@@ -0,0 +1,54 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.httpFetch = httpFetch;
+let _fetch;
+async function getFetch() {
+    if (_fetch)
+        return _fetch;
+    if (typeof globalThis.fetch === 'function') {
+        _fetch = globalThis.fetch.bind(globalThis);
+    }
+    else {
+        const mod = await Promise.resolve().then(() => __importStar(require('node-fetch')));
+        _fetch = (mod.default ?? mod);
+    }
+    return _fetch;
+}
+async function httpFetch(input, init) {
+    const f = await getFetch();
+    return f(input, init);
+}
+//# sourceMappingURL=http.js.map

package/dist/cjs/index.d.ts

@@ -0,0 +1,2 @@
+export * from './types.js';
+export * from './client.js';

package/dist/cjs/index.js

@@ -0,0 +1,19 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./types.js"), exports);
+__exportStar(require("./client.js"), exports);
+//# sourceMappingURL=index.js.map

package/dist/cjs/types.d.ts

@@ -0,0 +1,57 @@
+export interface VeridiaLogContext {
+    status?: number;
+    error?: unknown;
+    data?: unknown;
+    [key: string]: unknown;
+}
+export type VeridiaLogger = {
+    /**
+     * Logs informational messages.
+     * @param service - Service called the logger.
+     * @param message - Human-readable message.
+     * @param context - Optional structured data or additional info.
+     */
+    info?: (service: string, message: string, context?: VeridiaLogContext) => void;
+    /**
+     * Logs warnings.
+     * @param service - Service called the logger.
+     * @param message - Human-readable message.
+     * @param context - Optional structured data or additional info.
+     */
+    warn?: (service: string, message: string, context?: VeridiaLogContext) => void;
+    /**
+     * Logs errors.
+     * @param service - Service called the logger.
+     * @param message - Human-readable message.
+     * @param context - Optional structured data or additional info.
+     */
+    error: (service: string, message: string, context?: VeridiaLogContext) => void;
+};
+export type VeridiaClientOptions = {
+    accessKeyId: string;
+    secretAccessKey: string;
+    endpoint?: string;
+    region?: string;
+    maxBufferSize?: number;
+    maxBufferTimeMs?: number;
+    retries?: number;
+    retryBaseDelayMs?: number;
+    timeoutMsGetUserSegments?: number;
+    timeoutMsFlush?: number;
+    logger?: VeridiaLogger;
+};
+export type IdentifierPayload = {
+    type: 'userId' | 'email';
+    id: string;
+};
+export type IdentifyPayload = {
+    identifier: IdentifierPayload;
+    attributes: any;
+};
+export type TrackPayload = {
+    identifier: IdentifierPayload;
+    eventId: string;
+    eventType: string;
+    eventTime: string;
+    properties: any;
+};

package/dist/cjs/types.js

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

package/dist/cjs/version.d.ts

@@ -0,0 +1 @@
+export declare const SDK_VERSION = "1.0.2";

package/dist/cjs/version.js

@@ -0,0 +1,5 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SDK_VERSION = void 0;
+exports.SDK_VERSION = '1.0.2';
+//# sourceMappingURL=version.js.map

package/dist/esm/client.d.ts

@@ -0,0 +1,56 @@
+import { IdentifierPayload, IdentifyPayload, TrackPayload, VeridiaClientOptions } from './types.js';
+export declare class VeridiaClient {
+    private readonly options;
+    private trackBuffer;
+    private identifyBuffer;
+    private flushTimer?;
+    private readonly logger;
+    private readonly baseUrl;
+    private readonly region;
+    private readonly maxBufferSize;
+    private readonly maxBufferTimeMs;
+    private readonly retries;
+    private readonly retryBaseDelayMs;
+    private readonly timeoutMsGetUserSegments;
+    private readonly timeoutMsFlush;
+    constructor(options: VeridiaClientOptions);
+    /**
+     * Queues a user identification update to be flushed in batch.
+     *
+     * @param identifierType - The type of user identifier ("userId" | "email").
+     * @param identifierId - The unique ID or email.
+     * @param attributes - Key/value map of user attributes.
+     */
+    identify(identifierType: IdentifierPayload['type'], identifierId: IdentifierPayload['id'], attributes: IdentifyPayload['attributes']): void;
+    /**
+     * Sends a tracking event for the given user.
+     *
+     * @param identifierType - The type of user identifier ("userId" | "email").
+     * @param identifierId - The unique ID or email.
+     * @param eventType - Logical name of the event.
+     * @param eventId - Unique ID for idempotency.
+     * @param eventTime - ISO timestamp string.
+     * @param properties - Arbitrary event properties.
+     */
+    track(identifierType: IdentifierPayload['type'], identifierId: IdentifierPayload['id'], eventType: TrackPayload['eventType'], eventId: TrackPayload['eventId'], eventTime: TrackPayload['eventTime'], properties: TrackPayload['properties']): void;
+    /**
+     * Retrieves the current segments for the given user.
+     *
+     * @param identifierType - The type of user identifier ("userId" | "email").
+     * @param identifierId - The unique ID or email.
+     * @returns A list of segment identifiers the user currently belongs to.
+     */
+    getUserSegments(identifierType: IdentifierPayload['type'], identifierId: string): Promise<string[]>;
+    /**
+     * Sends all queued identify and track data to the Veridia API immediately.
+     * Automatically called when buffers reach their limit or after the configured time interval.
+     */
+    flush(): Promise<void>;
+    /**
+     * Flushes all pending data and prepares the client for shutdown.
+     * Should be called before application exit to ensure all data is sent.
+     */
+    close(): Promise<void>;
+    private scheduleFlushIfNeeded;
+    private flushBatch;
+}

package/dist/esm/client.js

@@ -0,0 +1,220 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VeridiaClient = void 0;
+const aws4 = __importStar(require("aws4"));
+const http_js_1 = require("./http.js");
+const version_js_1 = require("./version.js");
+class VeridiaClient {
+    constructor(options) {
+        this.options = options;
+        this.trackBuffer = [];
+        this.identifyBuffer = [];
+        this.baseUrl = options.endpoint ?? 'https://api.veridia.io/v1';
+        this.region = options.region ?? 'default';
+        this.maxBufferSize = options.maxBufferSize ?? 500;
+        this.maxBufferTimeMs = options.maxBufferTimeMs ?? 5000;
+        this.retries = options.retries ?? 3;
+        this.retryBaseDelayMs = options.retryBaseDelayMs ?? 500;
+        this.timeoutMsGetUserSegments = options.timeoutMsGetUserSegments ?? 5_000;
+        this.timeoutMsFlush = options.timeoutMsFlush ?? 30_000;
+        this.logger = options.logger;
+    }
+    /**
+     * Queues a user identification update to be flushed in batch.
+     *
+     * @param identifierType - The type of user identifier ("userId" | "email").
+     * @param identifierId - The unique ID or email.
+     * @param attributes - Key/value map of user attributes.
+     */
+    identify(identifierType, identifierId, attributes) {
+        this.identifyBuffer.push({
+            identifier: {
+                type: identifierType,
+                id: identifierId,
+            },
+            attributes,
+        });
+        this.scheduleFlushIfNeeded(this.identifyBuffer);
+    }
+    /**
+     * Sends a tracking event for the given user.
+     *
+     * @param identifierType - The type of user identifier ("userId" | "email").
+     * @param identifierId - The unique ID or email.
+     * @param eventType - Logical name of the event.
+     * @param eventId - Unique ID for idempotency.
+     * @param eventTime - ISO timestamp string.
+     * @param properties - Arbitrary event properties.
+     */
+    track(identifierType, identifierId, eventType, eventId, eventTime, properties) {
+        this.trackBuffer.push({
+            identifier: { type: identifierType, id: identifierId },
+            eventId,
+            eventType,
+            eventTime,
+            properties,
+        });
+        this.scheduleFlushIfNeeded(this.trackBuffer);
+    }
+    /**
+     * Retrieves the current segments for the given user.
+     *
+     * @param identifierType - The type of user identifier ("userId" | "email").
+     * @param identifierId - The unique ID or email.
+     * @returns A list of segment identifiers the user currently belongs to.
+     */
+    async getUserSegments(identifierType, identifierId) {
+        try {
+            const path = `/segments/${identifierType}/${encodeURIComponent(identifierId)}`;
+            const url = `${this.baseUrl}${path}`;
+            const req = {
+                host: new URL(url).host,
+                path,
+                method: 'GET',
+                service: 'segments',
+                region: this.region,
+                headers: { 'User-Agent': `veridia-node-sdk/${version_js_1.SDK_VERSION}` },
+            };
+            aws4.sign(req, this.options);
+            const controller = new AbortController();
+            const timeout = setTimeout(() => controller.abort(), this.timeoutMsGetUserSegments);
+            const res = await (0, http_js_1.httpFetch)(url, {
+                method: req.method,
+                headers: req.headers,
+                signal: controller.signal,
+            }).finally(() => clearTimeout(timeout));
+            if (!res.ok) {
+                this.logger?.error('segments', 'getUserSegments API call failed', { status: res.status });
+                return [];
+            }
+            const data = (await res.json());
+            if (data.status === 'success' && Array.isArray(data.data)) {
+                return data.data;
+            }
+            this.logger?.error('segments', 'getUserSegments API returned invalid response', {
+                data: data,
+            });
+            return [];
+        }
+        catch (err) {
+            this.logger?.error('segments', 'getUserSegments encountered an error', {
+                error: err,
+            });
+            return [];
+        }
+    }
+    /**
+     * Sends all queued identify and track data to the Veridia API immediately.
+     * Automatically called when buffers reach their limit or after the configured time interval.
+     */
+    async flush() {
+        if (this.flushTimer) {
+            clearTimeout(this.flushTimer);
+            this.flushTimer = undefined;
+        }
+        await Promise.all([
+            this.flushBatch('profiles', this.identifyBuffer),
+            this.flushBatch('events', this.trackBuffer),
+        ]);
+    }
+    /**
+     * Flushes all pending data and prepares the client for shutdown.
+     * Should be called before application exit to ensure all data is sent.
+     */
+    async close() {
+        await this.flush();
+    }
+    scheduleFlushIfNeeded(buffer) {
+        if (buffer.length >= this.maxBufferSize) {
+            void this.flush();
+        }
+        else if (!this.flushTimer) {
+            this.flushTimer = setTimeout(() => this.flush(), this.maxBufferTimeMs);
+        }
+    }
+    async flushBatch(service, buffer) {
+        if (buffer.length === 0)
+            return;
+        const batch = [...buffer];
+        buffer.length = 0; // clear buffer safely
+        const urlObj = new URL(this.baseUrl + '/' + service);
+        const opts = {
+            host: urlObj.host,
+            path: urlObj.pathname + urlObj.search,
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                'User-Agent': `veridia-node-sdk/${version_js_1.SDK_VERSION}`,
+            },
+            body: JSON.stringify({ [service]: batch }),
+            service,
+            region: this.region,
+        };
+        aws4.sign(opts, this.options);
+        const signedOpts = {
+            method: opts.method,
+            headers: opts.headers,
+            body: opts.body,
+        };
+        for (let attempt = 1; attempt <= this.retries; attempt++) {
+            try {
+                const controller = new AbortController();
+                const timeout = setTimeout(() => controller.abort(), this.timeoutMsFlush);
+                const res = await (0, http_js_1.httpFetch)(urlObj.toString(), {
+                    ...signedOpts,
+                    signal: controller.signal,
+                }).finally(() => clearTimeout(timeout));
+                if (!res.ok) {
+                    throw new Error(`${service} flush failed: ${res.status}`);
+                }
+                if (this.logger?.info)
+                    this.logger.info(service, 'flush completed', { batchSize: batch.length });
+                return;
+            }
+            catch (err) {
+                if (this.logger?.warn)
+                    this.logger.warn(service, `flush attempt ${attempt} failed`, { error: err });
+                if (attempt === this.retries) {
+                    this.logger?.error(service, `flush failed after max retries`, { error: err });
+                    throw err;
+                }
+                await new Promise((r) => setTimeout(r, this.retryBaseDelayMs * 2 ** (attempt - 1))); // backoff
+            }
+        }
+    }
+}
+exports.VeridiaClient = VeridiaClient;
+//# sourceMappingURL=client.js.map

package/dist/esm/http.d.ts

@@ -0,0 +1 @@
+export declare function httpFetch(input: RequestInfo | URL, init?: RequestInit): Promise<Response>;

package/dist/esm/http.js

@@ -0,0 +1,21 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.httpFetch = httpFetch;
+let _fetch;
+async function getFetch() {
+    if (_fetch)
+        return _fetch;
+    if (typeof globalThis.fetch === 'function') {
+        _fetch = globalThis.fetch.bind(globalThis);
+    }
+    else {
+        const mod = await import('node-fetch');
+        _fetch = (mod.default ?? mod);
+    }
+    return _fetch;
+}
+async function httpFetch(input, init) {
+    const f = await getFetch();
+    return f(input, init);
+}
+//# sourceMappingURL=http.js.map

package/dist/esm/index.d.ts

@@ -0,0 +1,2 @@
+export * from './types.js';
+export * from './client.js';

package/dist/esm/index.js

@@ -0,0 +1,19 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./types.js"), exports);
+__exportStar(require("./client.js"), exports);
+//# sourceMappingURL=index.js.map

package/dist/esm/types.d.ts

@@ -0,0 +1,57 @@
+export interface VeridiaLogContext {
+    status?: number;
+    error?: unknown;
+    data?: unknown;
+    [key: string]: unknown;
+}
+export type VeridiaLogger = {
+    /**
+     * Logs informational messages.
+     * @param service - Service called the logger.
+     * @param message - Human-readable message.
+     * @param context - Optional structured data or additional info.
+     */
+    info?: (service: string, message: string, context?: VeridiaLogContext) => void;
+    /**
+     * Logs warnings.
+     * @param service - Service called the logger.
+     * @param message - Human-readable message.
+     * @param context - Optional structured data or additional info.
+     */
+    warn?: (service: string, message: string, context?: VeridiaLogContext) => void;
+    /**
+     * Logs errors.
+     * @param service - Service called the logger.
+     * @param message - Human-readable message.
+     * @param context - Optional structured data or additional info.
+     */
+    error: (service: string, message: string, context?: VeridiaLogContext) => void;
+};
+export type VeridiaClientOptions = {
+    accessKeyId: string;
+    secretAccessKey: string;
+    endpoint?: string;
+    region?: string;
+    maxBufferSize?: number;
+    maxBufferTimeMs?: number;
+    retries?: number;
+    retryBaseDelayMs?: number;
+    timeoutMsGetUserSegments?: number;
+    timeoutMsFlush?: number;
+    logger?: VeridiaLogger;
+};
+export type IdentifierPayload = {
+    type: 'userId' | 'email';
+    id: string;
+};
+export type IdentifyPayload = {
+    identifier: IdentifierPayload;
+    attributes: any;
+};
+export type TrackPayload = {
+    identifier: IdentifierPayload;
+    eventId: string;
+    eventType: string;
+    eventTime: string;
+    properties: any;
+};

package/dist/esm/types.js

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

package/dist/esm/version.d.ts

@@ -0,0 +1 @@
+export declare const SDK_VERSION = "1.0.2";

package/dist/esm/version.js

@@ -0,0 +1,5 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SDK_VERSION = void 0;
+exports.SDK_VERSION = '1.0.2';
+//# sourceMappingURL=version.js.map

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@veridia/node-sdk",
+  "version": "1.0.2",
+  "description": "",
+  "main": "./dist/cjs/index.js",
+  "module": "./dist/esm/index.js",
+  "types": "./dist/esm/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/esm/index.d.ts",
+      "import": "./dist/esm/index.js",
+      "require": "./dist/cjs/index.js"
+    }
+  },
+  "scripts": {
+    "build": "npm pkg get version | xargs -I {} sh -c \"sed -i.bak -e 's/__SDK_VERSION__/{}/g' src/version.ts && rm -f src/version.ts.bak\" && npm run build:cjs && npm run build:esm",
+    "build:cjs": "tsc -p tsconfig.cjs.json",
+    "build:esm": "tsc -p tsconfig.esm.json",
+    "clean": "rm -rf dist",
+    "test": "vitest",
+    "lint": "eslint . --ext .ts",
+    "format": "prettier --write .",
+    "prepare": "husky install"
+  },
+  "dependencies": {
+    "aws4": "1.13.2",
+    "node-fetch": "^3.3.2"
+  },
+  "devDependencies": {
+    "@types/aws4": "^1.11.6",
+    "@types/node": "^24.9.2",
+    "@typescript-eslint/eslint-plugin": "^8.46.2",
+    "@typescript-eslint/parser": "^8.46.2",
+    "eslint": "^9.38.0",
+    "eslint-plugin-prettier": "^5.5.4",
+    "husky": "^8.0.0",
+    "prettier": "^3.6.2",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.6"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/veridia-io/veridia-node-sdk.git"
+  }
+}