@centrali-io/centrali-sdk 3.1.3 → 3.1.5

package/dist/index.js

@@ -5,6 +5,39 @@
  * A lightweight SDK for interacting with Centrali's Data, Compute, and Realtime APIs,
  * with support for user-provided tokens or client credentials (Client ID/Secret).
  */
+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;
+    };
+})();
 var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
     function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
     return new (P || (P = Promise))(function (resolve, reject) {
@@ -18,7 +51,8 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.CentraliSDK = exports.ComputeFunctionsManager = exports.StructuresManager = exports.AllowedDomainsManager = exports.ValidationManager = exports.AnomalyInsightsManager = exports.SmartQueriesManager = exports.TriggersManager = exports.OrchestrationsManager = exports.RealtimeManager = void 0;
+exports.CentraliSDK = exports.ComputeFunctionsManager = exports.StructuresManager = exports.AllowedDomainsManager = exports.ValidationManager = exports.AnomalyInsightsManager = exports.SmartQueriesManager = exports.TriggersManager = exports.OrchestrationsManager = exports.RealtimeManager = exports.CentraliError = void 0;
+exports.isCentraliError = isCentraliError;
 exports.getApiUrl = getApiUrl;
 exports.getAuthUrl = getAuthUrl;
 exports.getRealtimeUrl = getRealtimeUrl;
@@ -60,13 +94,82 @@ exports.getOrchestrationsApiPath = getOrchestrationsApiPath;
 exports.getOrchestrationRunsApiPath = getOrchestrationRunsApiPath;
 exports.getOrchestrationRunStepsApiPath = getOrchestrationRunStepsApiPath;
 exports.getAllowedDomainsApiPath = getAllowedDomainsApiPath;
-const axios_1 = __importDefault(require("axios"));
+const axios_1 = __importStar(require("axios"));
 const qs_1 = __importDefault(require("qs"));
 const eventsource_1 = require("eventsource");
 // Use native EventSource in browser, polyfill in Node.js
 const EventSourceImpl = typeof EventSource !== 'undefined'
     ? EventSource
     : eventsource_1.EventSource;
+// =====================================================
+// Error Types
+// =====================================================
+/**
+ * Error thrown by the Centrali SDK when an HTTP request fails.
+ * Wraps the underlying HTTP error to avoid leaking transport details.
+ *
+ * @example
+ * ```ts
+ * import { CentraliSDK, CentraliError } from '@centrali-io/centrali-sdk';
+ *
+ * try {
+ *   await client.records.create(structureId, data);
+ * } catch (err) {
+ *   if (err instanceof CentraliError) {
+ *     console.log(err.status);  // 400
+ *     console.log(err.code);    // 'VALIDATION_ERROR'
+ *     console.log(err.message); // 'structureSlug is required'
+ *   }
+ * }
+ * ```
+ */
+class CentraliError extends Error {
+    constructor(message, status, statusText, body, code, fieldErrors) {
+        super(message);
+        this.name = 'CentraliError';
+        this.status = status;
+        this.statusText = statusText;
+        this.body = body;
+        this.code = code;
+        this.fieldErrors = fieldErrors;
+        // Restore prototype chain (required when extending built-ins in TypeScript)
+        Object.setPrototypeOf(this, CentraliError.prototype);
+    }
+}
+exports.CentraliError = CentraliError;
+/**
+ * Type guard to check if a value is a CentraliError.
+ *
+ * @example
+ * ```ts
+ * } catch (err) {
+ *   if (isCentraliError(err)) {
+ *     console.log(err.status);
+ *   }
+ * }
+ * ```
+ */
+function isCentraliError(err) {
+    return err instanceof CentraliError;
+}
+function toCentraliError(err) {
+    var _a, _b, _c, _d;
+    if (err instanceof CentraliError)
+        return err;
+    if (err instanceof axios_1.AxiosError) {
+        const status = (_a = err.response) === null || _a === void 0 ? void 0 : _a.status;
+        const statusText = (_b = err.response) === null || _b === void 0 ? void 0 : _b.statusText;
+        const body = (_c = err.response) === null || _c === void 0 ? void 0 : _c.data;
+        const message = (_d = body === null || body === void 0 ? void 0 : body.message) !== null && _d !== void 0 ? _d : err.message;
+        const code = typeof (body === null || body === void 0 ? void 0 : body.error) === 'string' ? body.error : undefined;
+        const fieldErrors = Array.isArray(body === null || body === void 0 ? void 0 : body.fieldErrors) ? body.fieldErrors : undefined;
+        return new CentraliError(message, status, statusText, body, code, fieldErrors);
+    }
+    if (err instanceof Error) {
+        return new CentraliError(err.message);
+    }
+    return new CentraliError(String(err));
+}
 // Helper to encode form data
 function encodeFormData(data) {
     return new URLSearchParams(data).toString();
@@ -2250,10 +2353,10 @@ class CentraliSDK {
                     this.isRefreshingToken = false;
                     this.tokenRefreshPromise = null;
                     this.token = null;
-                    return Promise.reject(refreshError);
+                    return Promise.reject(toCentraliError(refreshError));
                 }
             }
-            return Promise.reject(error);
+            return Promise.reject(toCentraliError(error));
         }));
     }
     /**
@@ -2570,9 +2673,14 @@ class CentraliSDK {
     }
     // ------------------ Data API Methods ------------------
     /** Create a new record in a given recordSlug. */
-    createRecord(recordSlug, record) {
+    createRecord(recordSlug, record, options) {
         const path = getRecordApiPath(this.options.workspaceId, recordSlug);
-        return this.request('POST', path, Object.assign({}, record));
+        const queryParams = {};
+        if (options === null || options === void 0 ? void 0 : options.ttlSeconds)
+            queryParams.ttlSeconds = String(options.ttlSeconds);
+        if (options === null || options === void 0 ? void 0 : options.expiresAt)
+            queryParams.expiresAt = options.expiresAt;
+        return this.request('POST', path, Object.assign({}, record), Object.keys(queryParams).length > 0 ? queryParams : undefined);
     }
     /** Get the token used for authentication. */
     getToken() {
@@ -2655,9 +2763,16 @@ class CentraliSDK {
         return this.request('POST', path, { ids });
     }
     /** Update an existing record by ID. */
-    updateRecord(recordSlug, id, updates) {
+    updateRecord(recordSlug, id, updates, options) {
         const path = getRecordApiPath(this.options.workspaceId, recordSlug, id);
-        return this.request('PUT', path, Object.assign({}, updates));
+        const queryParams = {};
+        if (options === null || options === void 0 ? void 0 : options.ttlSeconds)
+            queryParams.ttlSeconds = String(options.ttlSeconds);
+        if (options === null || options === void 0 ? void 0 : options.expiresAt)
+            queryParams.expiresAt = options.expiresAt;
+        if (options === null || options === void 0 ? void 0 : options.clearTtl)
+            queryParams.clearTtl = 'true';
+        return this.request('PUT', path, Object.assign({}, updates), Object.keys(queryParams).length > 0 ? queryParams : undefined);
     }
     /**
      * Upsert a record: find by match fields, update if exists, create if not.

package/index.ts

@@ -5,7 +5,7 @@
  * with support for user-provided tokens or client credentials (Client ID/Secret).
  */
 
-import axios, {AxiosInstance, AxiosRequestConfig, AxiosRequestHeaders, AxiosResponse, Method} from 'axios';
+import axios, {AxiosError, AxiosInstance, AxiosRequestConfig, AxiosRequestHeaders, AxiosResponse, Method} from 'axios';
 import qs from 'qs';
 import {EventSource as EventSourcePolyfill} from 'eventsource';
 
@@ -14,6 +14,95 @@ const EventSourceImpl: typeof EventSource = typeof EventSource !== 'undefined'
     ? EventSource
     : EventSourcePolyfill as unknown as typeof EventSource;
 
+// =====================================================
+// Error Types
+// =====================================================
+
+/**
+ * Error thrown by the Centrali SDK when an HTTP request fails.
+ * Wraps the underlying HTTP error to avoid leaking transport details.
+ *
+ * @example
+ * ```ts
+ * import { CentraliSDK, CentraliError } from '@centrali-io/centrali-sdk';
+ *
+ * try {
+ *   await client.records.create(structureId, data);
+ * } catch (err) {
+ *   if (err instanceof CentraliError) {
+ *     console.log(err.status);  // 400
+ *     console.log(err.code);    // 'VALIDATION_ERROR'
+ *     console.log(err.message); // 'structureSlug is required'
+ *   }
+ * }
+ * ```
+ */
+export class CentraliError extends Error {
+    /** HTTP status code (e.g. 400, 401, 404, 500). Undefined for network errors. */
+    readonly status: number | undefined;
+    /** HTTP status text (e.g. "Bad Request"). Undefined for network errors. */
+    readonly statusText: string | undefined;
+    /** Machine-readable error code in SCREAMING_SNAKE_CASE (e.g. 'VALIDATION_ERROR', 'NOT_FOUND'). Undefined for network errors. */
+    readonly code: string | undefined;
+    /** Field-level validation errors. Present when code is 'VALIDATION_ERROR' and the server included per-field details. */
+    readonly fieldErrors: { field: string; message: string }[] | undefined;
+    /** Parsed response body from the server. Undefined if no response was received. */
+    readonly body: unknown;
+
+    constructor(
+        message: string,
+        status?: number,
+        statusText?: string,
+        body?: unknown,
+        code?: string,
+        fieldErrors?: { field: string; message: string }[]
+    ) {
+        super(message);
+        this.name = 'CentraliError';
+        this.status = status;
+        this.statusText = statusText;
+        this.body = body;
+        this.code = code;
+        this.fieldErrors = fieldErrors;
+
+        // Restore prototype chain (required when extending built-ins in TypeScript)
+        Object.setPrototypeOf(this, CentraliError.prototype);
+    }
+}
+
+/**
+ * Type guard to check if a value is a CentraliError.
+ *
+ * @example
+ * ```ts
+ * } catch (err) {
+ *   if (isCentraliError(err)) {
+ *     console.log(err.status);
+ *   }
+ * }
+ * ```
+ */
+export function isCentraliError(err: unknown): err is CentraliError {
+    return err instanceof CentraliError;
+}
+
+function toCentraliError(err: unknown): CentraliError {
+    if (err instanceof CentraliError) return err;
+    if (err instanceof AxiosError) {
+        const status = err.response?.status;
+        const statusText = err.response?.statusText;
+        const body = err.response?.data as any;
+        const message = body?.message ?? err.message;
+        const code = typeof body?.error === 'string' ? body.error : undefined;
+        const fieldErrors = Array.isArray(body?.fieldErrors) ? body.fieldErrors : undefined;
+        return new CentraliError(message, status, statusText, body, code, fieldErrors);
+    }
+    if (err instanceof Error) {
+        return new CentraliError(err.message);
+    }
+    return new CentraliError(String(err));
+}
+
 // =====================================================
 // Realtime Types
 // =====================================================
@@ -588,6 +677,18 @@ export interface DeleteRecordOptions {
     hard?: boolean;
 }
 
+/**
+ * Options for setting TTL (Time-To-Live) on a record.
+ */
+export interface RecordTtlOptions {
+    /** TTL in seconds. Record expires after this duration. */
+    ttlSeconds?: number;
+    /** Explicit expiration timestamp (ISO 8601 string). */
+    expiresAt?: string;
+    /** Set to true to remove TTL and make record permanent. Only valid on update. */
+    clearTtl?: boolean;
+}
+
 // =====================================================
 // Allowed Domains Types
 // =====================================================
@@ -1541,6 +1642,8 @@ export interface UpdateStructureInput {
     properties?: PropertyDefinition[];
     enableVersioning?: boolean;
     tags?: string[];
+    /** Default TTL in seconds for new records in this structure. Set to null to clear. */
+    defaultTtlSeconds?: number | null;
 }
 
 /**
@@ -4478,11 +4581,11 @@ export class CentraliSDK {
                         this.isRefreshingToken = false;
                         this.tokenRefreshPromise = null;
                         this.token = null;
-                        return Promise.reject(refreshError);
+                        return Promise.reject(toCentraliError(refreshError));
                     }
                 }
 
-                return Promise.reject(error);
+                return Promise.reject(toCentraliError(error));
             }
         );
     }
@@ -4860,10 +4963,14 @@ export class CentraliSDK {
     /** Create a new record in a given recordSlug. */
     public createRecord<T = any>(
         recordSlug: string,
-        record: Record<string, any>
+        record: Record<string, any>,
+        options?: RecordTtlOptions
     ): Promise<ApiResponse<T>> {
         const path = getRecordApiPath(this.options.workspaceId, recordSlug);
-        return this.request('POST', path, {  ...record });
+        const queryParams: Record<string, string> = {};
+        if (options?.ttlSeconds) queryParams.ttlSeconds = String(options.ttlSeconds);
+        if (options?.expiresAt) queryParams.expiresAt = options.expiresAt;
+        return this.request('POST', path, { ...record }, Object.keys(queryParams).length > 0 ? queryParams : undefined);
     }
 
     /** Get the token used for authentication. */
@@ -4965,10 +5072,15 @@ export class CentraliSDK {
     public updateRecord<T = any>(
         recordSlug: string,
         id: string,
-        updates: Record<string, any>
+        updates: Record<string, any>,
+        options?: RecordTtlOptions
     ): Promise<ApiResponse<T>> {
         const path = getRecordApiPath(this.options.workspaceId, recordSlug, id);
-        return this.request('PUT', path, {  ...updates });
+        const queryParams: Record<string, string> = {};
+        if (options?.ttlSeconds) queryParams.ttlSeconds = String(options.ttlSeconds);
+        if (options?.expiresAt) queryParams.expiresAt = options.expiresAt;
+        if (options?.clearTtl) queryParams.clearTtl = 'true';
+        return this.request('PUT', path, { ...updates }, Object.keys(queryParams).length > 0 ? queryParams : undefined);
     }
 
     /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@centrali-io/centrali-sdk",
-  "version": "3.1.3",
+  "version": "3.1.5",
   "description": "Centrali Node SDK",
   "main": "dist/index.js",
   "type": "commonjs",