@veridia/node-sdk 1.0.3 → 1.0.6

package/README.md

@@ -1,7 +1,9 @@
 # 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.
+[![npm version](https://img.shields.io/npm/v/@veridia/node-sdk.svg)](https://www.npmjs.com/package/@veridia/node-sdk)
+
+Official Node.js SDK for integrating with the [Veridia Platform](https://veridia.io).  
+It provides an easy way to identify users, send tracking events, retrieve user segments, and manage batching with retries and timeouts — all from your backend.
 
 ---
 
@@ -55,7 +57,8 @@ const client = new VeridiaClient({
 
 ### `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.
+Identify a user and update their profile attributes.
+Provided attributes must match the Profile Attributes schema defined in your Veridia dashboard.
 
 ```ts
 await client.identify('userId', '123', {
@@ -65,17 +68,18 @@ await client.identify('userId', '123', {
 });
 ```
 
-| Parameter        | Type                    | Description                  |
-| ---------------- | ----------------------- | ---------------------------- |
-| `identifierType` | `"userId"` \| `"email"` | How the user is identified.  |
-| `identifierId`   | `string`                | The unique identifier value. |
-| `attributes`     | `Record<string, any>`   | Arbitrary user attributes.   |
+| Parameter        | Type                    | Description                 |
+| ---------------- | ----------------------- | --------------------------- |
+| `identifierType` | `"userId"` \| `"email"` | How the user is identified. |
+| `identifierId`   | `string`                | 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.
+Track an event performed by a user.
+Provided attributes must match the event attributes schema defined in your Veridia dashboard.
 
 ```ts
 await client.track('userId', '123', 'purchase', 'evt-001', new Date().toISOString(), {
@@ -84,26 +88,34 @@ await client.track('userId', '123', 'purchase', 'evt-001', new Date().toISOStrin
 });
 ```
 
-| 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.          |
+| Parameter        | Type                    | Description                      |
+| ---------------- | ----------------------- | -------------------------------- |
+| `identifierType` | `"userId"` \| `"email"` | How the user is identified.      |
+| `identifierId`   | `string`                | Unique user identifier.          |
+| `eventType`      | `string`                | Logical name of the event.       |
+| `eventId`        | `string`                | Unique event ID for idempotency. |
+| `eventTime`      | `string`                | ISO timestamp string.            |
+| `properties`     | `Record<string, any>`   | Optional event properties.       |
 
 ---
 
-### `getUserSegments(identifierType, identifierId)`
+### `getUserSegments(identifierType, identifierId, [noSegmentsOnError=true])`
 
 Fetches the list of segments the specified user currently belongs to.
+If the API call fails and `noSegmentsOnError` is set to `false`, it will throw an error.
+Otherwise, it will return an empty array.
 
 ```ts
 const segments = await client.getUserSegments('userId', '123');
 console.log(segments); // ['617090ac-a1f6-4c70-a79e-40830a367324', '67f2c139-850f-469f-9ca4-a1c58e6d84ea']
 ```
 
+| Parameter           | Type       | Default   | Description                                         |
+| ------------------- | ---------- | --------- | --------------------------------------------------- | ------------------------ |
+| `identifierType`    | `"userId"` | `"email"` | —                                                   | Type of user identifier. |
+| `identifierId`      | `string`   | —         | Unique user ID or email.                            |
+| `noSegmentsOnError` | `boolean`  | `true`    | If true, returns `[]` instead of throwing an error. |
+
 Returns:
 `Promise<string[]>` — Array of segment identifiers.
 
@@ -112,6 +124,7 @@ Returns:
 ### `flush()`
 
 Immediately sends all queued identify and track data.
+Automatically called when buffers reach their configured limits or after the flush interval.
 
 ```ts
 await client.flush();
@@ -119,8 +132,8 @@ 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.
+Flushes any remaining buffered data and closes the client gracefully.
+Call this before application exit in workers or serverless environments.
 
 ```ts
 await client.close();
@@ -130,31 +143,39 @@ 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           |
+| 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.                                   |
+| `autoFlush`                | `boolean`       | `true`                      | Whether to automatically flush buffered data. |
+| `maxBufferSize`            | `number`        | `500`                       | Max number of items before auto-flush.        |
+| `maxBufferTimeMs`          | `number`        | `5000`                      | Max time (ms) before auto-flush.              |
+| `retries`                  | `number`        | `3`                         | Retry attempts on transient network errors.   |
+| `retryBaseDelayMs`         | `number`        | `500`                       | Base delay (ms) for exponential backoff.      |
+| `timeoutMsGetUserSegments` | `number`        | `5000`                      | Timeout (ms) for `getUserSegments` calls.     |
+| `timeoutMsFlush`           | `number`        | `30000`                     | Timeout (ms) for batch flush requests.        |
+| `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;
+  info?(service: string, message: string, context?: VeridiaLogContext): void;
+  warn?(service: string, message: string, context?: VeridiaLogContext): void;
+  error(service: string, message: string, context?: VeridiaLogContext): void;
+}
+
+interface VeridiaLogContext {
+  status?: number;
+  error?: unknown;
+  data?: unknown;
+  [key: string]: unknown;
 }
 ```
 
@@ -179,8 +200,8 @@ const client = new VeridiaClient({
 
 ## 🧩 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.
+The SDK ships with full `.d.ts` declarations and JSDoc documentation.
+Hover over any method in VS Code to see inline descriptions and parameter hints.
 
 ---
 
@@ -198,6 +219,9 @@ const client = new VeridiaClient({
 await client.identify('userId', '123', { plan: 'gold' });
 await client.track('userId', '123', 'purchase', 'evt-123', new Date().toISOString());
 await client.flush();
+
+const segments = await client.getUserSegments('userId', '123');
+console.log('Segments:', segments);
 ```
 
 ---

package/dist/cjs/client.d.ts

@@ -7,6 +7,7 @@ export declare class VeridiaClient {
     private readonly logger;
     private readonly baseUrl;
     private readonly region;
+    private readonly autoFlush;
     private readonly maxBufferSize;
     private readonly maxBufferTimeMs;
     private readonly retries;
@@ -38,9 +39,10 @@ export declare class VeridiaClient {
      *
      * @param identifierType - The type of user identifier ("userId" | "email").
      * @param identifierId - The unique ID or email.
+     * @param [noSegmentsOnError=true] - Whether to throw an error or to return empty array of segments. Defaults to true.
      * @returns A list of segment identifiers the user currently belongs to.
      */
-    getUserSegments(identifierType: IdentifierPayload['type'], identifierId: string): Promise<string[]>;
+    getUserSegments(identifierType: IdentifierPayload['type'], identifierId: string, noSegmentsOnError?: boolean): 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.

package/dist/cjs/client.js

@@ -44,6 +44,7 @@ class VeridiaClient {
         this.identifyBuffer = [];
         this.baseUrl = options.endpoint ?? 'https://api.veridia.io/v1';
         this.region = options.region ?? 'default';
+        this.autoFlush = options.autoFlush ?? true;
         this.maxBufferSize = options.maxBufferSize ?? 500;
         this.maxBufferTimeMs = options.maxBufferTimeMs ?? 5000;
         this.retries = options.retries ?? 3;
@@ -67,7 +68,8 @@ class VeridiaClient {
             },
             attributes,
         });
-        this.scheduleFlushIfNeeded(this.identifyBuffer);
+        if (this.autoFlush)
+            this.scheduleFlushIfNeeded('profiles', this.identifyBuffer);
     }
     /**
      * Sends a tracking event for the given user.
@@ -87,16 +89,18 @@ class VeridiaClient {
             eventTime,
             properties,
         });
-        this.scheduleFlushIfNeeded(this.trackBuffer);
+        if (this.autoFlush)
+            this.scheduleFlushIfNeeded('events', 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.
+     * @param [noSegmentsOnError=true] - Whether to throw an error or to return empty array of segments. Defaults to true.
      * @returns A list of segment identifiers the user currently belongs to.
      */
-    async getUserSegments(identifierType, identifierId) {
+    async getUserSegments(identifierType, identifierId, noSegmentsOnError = true) {
         try {
             const path = `/segments/${identifierType}/${encodeURIComponent(identifierId)}`;
             const url = `${this.baseUrl}${path}`;
@@ -118,7 +122,10 @@ class VeridiaClient {
             }).finally(() => clearTimeout(timeout));
             if (!res.ok) {
                 this.logger?.error('segments', 'getUserSegments API call failed', { status: res.status });
-                return [];
+                if (noSegmentsOnError)
+                    return [];
+                else
+                    throw new Error(`getUserSegments API call failed: ${res.status}`);
             }
             const data = (await res.json());
             if (data.status === 'success' && Array.isArray(data.data)) {
@@ -127,13 +134,19 @@ class VeridiaClient {
             this.logger?.error('segments', 'getUserSegments API returned invalid response', {
                 data: data,
             });
-            return [];
+            if (noSegmentsOnError)
+                return [];
+            else
+                throw new Error(`getUserSegments API returned invalid response: ${JSON.stringify(data)}`);
         }
         catch (err) {
             this.logger?.error('segments', 'getUserSegments encountered an error', {
                 error: err,
             });
-            return [];
+            if (noSegmentsOnError)
+                return [];
+            else
+                throw err;
         }
     }
     /**
@@ -157,12 +170,18 @@ class VeridiaClient {
     async close() {
         await this.flush();
     }
-    scheduleFlushIfNeeded(buffer) {
+    scheduleFlushIfNeeded(service, buffer) {
         if (buffer.length >= this.maxBufferSize) {
-            void this.flush();
+            this.flush().catch((error) => {
+                this.logger?.error(service, 'automatic flush failed', { error });
+            });
         }
         else if (!this.flushTimer) {
-            this.flushTimer = setTimeout(() => this.flush(), this.maxBufferTimeMs);
+            this.flushTimer = setTimeout(() => {
+                this.flush().catch((error) => {
+                    this.logger?.error(service, 'automatic flush failed', { error });
+                });
+            }, this.maxBufferTimeMs);
         }
     }
     async flushBatch(service, buffer) {

package/dist/cjs/types.d.ts

@@ -32,6 +32,7 @@ export type VeridiaClientOptions = {
     secretAccessKey: string;
     endpoint?: string;
     region?: string;
+    autoFlush?: boolean;
     maxBufferSize?: number;
     maxBufferTimeMs?: number;
     retries?: number;

package/dist/cjs/version.d.ts

@@ -1 +1 @@
-export declare const SDK_VERSION = "1.0.3";
+export declare const SDK_VERSION = "1.0.6";

package/dist/cjs/version.js

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

package/dist/esm/client.d.ts

@@ -7,6 +7,7 @@ export declare class VeridiaClient {
     private readonly logger;
     private readonly baseUrl;
     private readonly region;
+    private readonly autoFlush;
     private readonly maxBufferSize;
     private readonly maxBufferTimeMs;
     private readonly retries;
@@ -38,9 +39,10 @@ export declare class VeridiaClient {
      *
      * @param identifierType - The type of user identifier ("userId" | "email").
      * @param identifierId - The unique ID or email.
+     * @param [noSegmentsOnError=true] - Whether to throw an error or to return empty array of segments. Defaults to true.
      * @returns A list of segment identifiers the user currently belongs to.
      */
-    getUserSegments(identifierType: IdentifierPayload['type'], identifierId: string): Promise<string[]>;
+    getUserSegments(identifierType: IdentifierPayload['type'], identifierId: string, noSegmentsOnError?: boolean): 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.

package/dist/esm/client.js

@@ -44,6 +44,7 @@ class VeridiaClient {
         this.identifyBuffer = [];
         this.baseUrl = options.endpoint ?? 'https://api.veridia.io/v1';
         this.region = options.region ?? 'default';
+        this.autoFlush = options.autoFlush ?? true;
         this.maxBufferSize = options.maxBufferSize ?? 500;
         this.maxBufferTimeMs = options.maxBufferTimeMs ?? 5000;
         this.retries = options.retries ?? 3;
@@ -67,7 +68,8 @@ class VeridiaClient {
             },
             attributes,
         });
-        this.scheduleFlushIfNeeded(this.identifyBuffer);
+        if (this.autoFlush)
+            this.scheduleFlushIfNeeded('profiles', this.identifyBuffer);
     }
     /**
      * Sends a tracking event for the given user.
@@ -87,16 +89,18 @@ class VeridiaClient {
             eventTime,
             properties,
         });
-        this.scheduleFlushIfNeeded(this.trackBuffer);
+        if (this.autoFlush)
+            this.scheduleFlushIfNeeded('events', 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.
+     * @param [noSegmentsOnError=true] - Whether to throw an error or to return empty array of segments. Defaults to true.
      * @returns A list of segment identifiers the user currently belongs to.
      */
-    async getUserSegments(identifierType, identifierId) {
+    async getUserSegments(identifierType, identifierId, noSegmentsOnError = true) {
         try {
             const path = `/segments/${identifierType}/${encodeURIComponent(identifierId)}`;
             const url = `${this.baseUrl}${path}`;
@@ -118,7 +122,10 @@ class VeridiaClient {
             }).finally(() => clearTimeout(timeout));
             if (!res.ok) {
                 this.logger?.error('segments', 'getUserSegments API call failed', { status: res.status });
-                return [];
+                if (noSegmentsOnError)
+                    return [];
+                else
+                    throw new Error(`getUserSegments API call failed: ${res.status}`);
             }
             const data = (await res.json());
             if (data.status === 'success' && Array.isArray(data.data)) {
@@ -127,13 +134,19 @@ class VeridiaClient {
             this.logger?.error('segments', 'getUserSegments API returned invalid response', {
                 data: data,
             });
-            return [];
+            if (noSegmentsOnError)
+                return [];
+            else
+                throw new Error(`getUserSegments API returned invalid response: ${JSON.stringify(data)}`);
         }
         catch (err) {
             this.logger?.error('segments', 'getUserSegments encountered an error', {
                 error: err,
             });
-            return [];
+            if (noSegmentsOnError)
+                return [];
+            else
+                throw err;
         }
     }
     /**
@@ -157,12 +170,18 @@ class VeridiaClient {
     async close() {
         await this.flush();
     }
-    scheduleFlushIfNeeded(buffer) {
+    scheduleFlushIfNeeded(service, buffer) {
         if (buffer.length >= this.maxBufferSize) {
-            void this.flush();
+            this.flush().catch((error) => {
+                this.logger?.error(service, 'automatic flush failed', { error });
+            });
         }
         else if (!this.flushTimer) {
-            this.flushTimer = setTimeout(() => this.flush(), this.maxBufferTimeMs);
+            this.flushTimer = setTimeout(() => {
+                this.flush().catch((error) => {
+                    this.logger?.error(service, 'automatic flush failed', { error });
+                });
+            }, this.maxBufferTimeMs);
         }
     }
     async flushBatch(service, buffer) {

package/dist/esm/types.d.ts

@@ -32,6 +32,7 @@ export type VeridiaClientOptions = {
     secretAccessKey: string;
     endpoint?: string;
     region?: string;
+    autoFlush?: boolean;
     maxBufferSize?: number;
     maxBufferTimeMs?: number;
     retries?: number;

package/dist/esm/version.d.ts

@@ -1 +1 @@
-export declare const SDK_VERSION = "1.0.3";
+export declare const SDK_VERSION = "1.0.6";

package/dist/esm/version.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@veridia/node-sdk",
-  "version": "1.0.3",
+  "version": "1.0.6",
   "description": "",
   "main": "./dist/cjs/index.js",
   "module": "./dist/esm/index.js",