@centrali-io/centrali-sdk 4.0.0 → 4.0.2

package/dist/index.js

@@ -51,7 +51,7 @@ 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 = exports.CentraliError = void 0;
+exports.CentraliSDK = exports.ComputeFunctionsManager = exports.CollectionsManager = 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;
@@ -78,6 +78,10 @@ exports.getStructureInsightsApiPath = getStructureInsightsApiPath;
 exports.getStructuresApiPath = getStructuresApiPath;
 exports.getStructureBySlugApiPath = getStructureBySlugApiPath;
 exports.getStructureValidateApiPath = getStructureValidateApiPath;
+exports.getCollectionInsightsApiPath = getCollectionInsightsApiPath;
+exports.getCollectionsApiPath = getCollectionsApiPath;
+exports.getCollectionBySlugApiPath = getCollectionBySlugApiPath;
+exports.getCollectionValidateApiPath = getCollectionValidateApiPath;
 exports.getComputeFunctionsApiPath = getComputeFunctionsApiPath;
 exports.getComputeFunctionTestApiPath = getComputeFunctionTestApiPath;
 exports.getSmartQueryTestApiPath = getSmartQueryTestApiPath;
@@ -102,6 +106,16 @@ const EventSourceImpl = typeof EventSource !== 'undefined'
     ? EventSource
     : eventsource_1.EventSource;
 // =====================================================
+// Deprecation Utility
+// =====================================================
+const _deprecationWarnings = new Set();
+function emitDeprecationWarning(message) {
+    if (!_deprecationWarnings.has(message)) {
+        _deprecationWarnings.add(message);
+        console.warn(`[DEPRECATION] ${message}`);
+    }
+}
+// =====================================================
 // Error Types
 // =====================================================
 /**
@@ -262,7 +276,7 @@ class RealtimeManager {
         let reconnectAttempt = 0;
         let reconnectTimeout = null;
         const connect = () => __awaiter(this, void 0, void 0, function* () {
-            var _a, _b, _c, _d;
+            var _a, _b, _c, _d, _e;
             // Zombie loop prevention: don't reconnect if unsubscribed
             if (unsubscribed) {
                 return;
@@ -284,12 +298,16 @@ class RealtimeManager {
                 const url = new URL(`${realtimeBaseUrl}${path}`);
                 // Add access token
                 url.searchParams.set('access_token', token);
-                // Add structure filter
-                if ((_b = options.structures) === null || _b === void 0 ? void 0 : _b.length) {
-                    url.searchParams.set('structures', options.structures.join(','));
+                // Add collection filter
+                if ((_b = options.collections) === null || _b === void 0 ? void 0 : _b.length) {
+                    url.searchParams.set('collections', options.collections.join(','));
+                }
+                else if ((_c = options.structures) === null || _c === void 0 ? void 0 : _c.length) {
+                    emitDeprecationWarning("The 'structures' filter option is deprecated. Use 'collections' instead.");
+                    url.searchParams.set('collections', options.structures.join(','));
                 }
                 // Add event type filter
-                if ((_c = options.events) === null || _c === void 0 ? void 0 : _c.length) {
+                if ((_d = options.events) === null || _d === void 0 ? void 0 : _d.length) {
                     url.searchParams.set('events', options.events.join(','));
                 }
                 // Add CFL filter
@@ -385,7 +403,7 @@ class RealtimeManager {
                 };
             }
             catch (err) {
-                (_d = options.onError) === null || _d === void 0 ? void 0 : _d.call(options, {
+                (_e = options.onError) === null || _e === void 0 ? void 0 : _e.call(options, {
                     code: 'CONNECTION_ERROR',
                     message: `Failed to connect: ${err}`,
                     recoverable: true,
@@ -594,6 +612,34 @@ function getStructureValidateApiPath(workspaceId) {
     return `data/workspace/${workspaceId}/api/v1/structures/validate`;
 }
 // =====================================================
+// Collection API Path Helpers (Configuration-as-Code)
+// =====================================================
+/**
+ * Generate collection-scoped anomaly insights API URL PATH.
+ */
+function getCollectionInsightsApiPath(workspaceId, collectionSlug) {
+    return `data/workspace/${workspaceId}/api/v1/collections/${collectionSlug}/insights`;
+}
+/**
+ * Generate Collections base API URL PATH.
+ */
+function getCollectionsApiPath(workspaceId, collectionId) {
+    const basePath = `data/workspace/${workspaceId}/api/v1/collections`;
+    return collectionId ? `${basePath}/${collectionId}` : basePath;
+}
+/**
+ * Generate Collection by slug API URL PATH.
+ */
+function getCollectionBySlugApiPath(workspaceId, recordSlug) {
+    return `data/workspace/${workspaceId}/api/v1/collections/slug/${recordSlug}`;
+}
+/**
+ * Generate Collection validate API URL PATH.
+ */
+function getCollectionValidateApiPath(workspaceId) {
+    return `data/workspace/${workspaceId}/api/v1/collections/validate`;
+}
+// =====================================================
 // Compute Function API Path Helpers (Configuration-as-Code)
 // =====================================================
 /**
@@ -2028,6 +2074,7 @@ class StructuresManager {
      * ```
      */
     list(options) {
+        emitDeprecationWarning('client.structures.list() is deprecated. Use client.collections.list() instead.');
         const path = getStructuresApiPath(this.workspaceId);
         return this.requestFn('GET', path, null, options);
     }
@@ -2044,6 +2091,7 @@ class StructuresManager {
      * ```
      */
     get(structureId) {
+        emitDeprecationWarning('client.structures.get() is deprecated. Use client.collections.get() instead.');
         const path = getStructuresApiPath(this.workspaceId, structureId);
         return this.requestFn('GET', path);
     }
@@ -2060,6 +2108,7 @@ class StructuresManager {
      * ```
      */
     getBySlug(recordSlug) {
+        emitDeprecationWarning('client.structures.getBySlug() is deprecated. Use client.collections.getBySlug() instead.');
         const path = getStructureBySlugApiPath(this.workspaceId, recordSlug);
         return this.requestFn('GET', path);
     }
@@ -2086,6 +2135,7 @@ class StructuresManager {
      * ```
      */
     create(input) {
+        emitDeprecationWarning('client.structures.create() is deprecated. Use client.collections.create() instead.');
         const path = getStructuresApiPath(this.workspaceId);
         return this.requestFn('POST', path, input);
     }
@@ -2109,6 +2159,7 @@ class StructuresManager {
      * ```
      */
     update(structureId, input) {
+        emitDeprecationWarning('client.structures.update() is deprecated. Use client.collections.update() instead.');
         const path = getStructuresApiPath(this.workspaceId, structureId);
         return this.requestFn('PUT', path, input);
     }
@@ -2123,6 +2174,7 @@ class StructuresManager {
      * ```
      */
     delete(structureId) {
+        emitDeprecationWarning('client.structures.delete() is deprecated. Use client.collections.delete() instead.');
         const path = getStructuresApiPath(this.workspaceId, structureId);
         return this.requestFn('DELETE', path);
     }
@@ -2142,12 +2194,178 @@ class StructuresManager {
      * ```
      */
     validate(input) {
+        emitDeprecationWarning('client.structures.validate() is deprecated. Use client.collections.validate() instead.');
         const path = getStructureValidateApiPath(this.workspaceId);
         return this.requestFn('POST', path, input);
     }
 }
 exports.StructuresManager = StructuresManager;
 // =====================================================
+// Collections Manager (Configuration-as-Code)
+// =====================================================
+/**
+ * CollectionsManager provides methods for managing data collections (schemas).
+ * Collections define the shape of records including properties, validation rules,
+ * and schema discovery modes.
+ * Access via `client.collections`.
+ *
+ * Usage:
+ * ```ts
+ * // List all collections
+ * const collections = await client.collections.list();
+ *
+ * // Create a new collection
+ * const collection = await client.collections.create({
+ *   name: 'Orders',
+ *   slug: 'orders',
+ *   properties: [
+ *     { name: 'title', type: 'string', required: true },
+ *     { name: 'amount', type: 'number', minimum: 0 }
+ *   ]
+ * });
+ *
+ * // Validate before creating
+ * const validation = await client.collections.validate({ slug: 'orders' });
+ * ```
+ */
+class CollectionsManager {
+    constructor(workspaceId, requestFn) {
+        this.workspaceId = workspaceId;
+        this.requestFn = requestFn;
+    }
+    /**
+     * List all collections in the workspace.
+     *
+     * @param options - Optional list parameters (pagination)
+     * @returns List of collections
+     *
+     * @example
+     * ```ts
+     * const collections = await client.collections.list();
+     * const page2 = await client.collections.list({ page: 2, limit: 10 });
+     * ```
+     */
+    list(options) {
+        const path = getCollectionsApiPath(this.workspaceId);
+        return this.requestFn('GET', path, null, options);
+    }
+    /**
+     * Get a collection by ID.
+     *
+     * @param collectionId - The collection UUID
+     * @returns The collection details
+     *
+     * @example
+     * ```ts
+     * const collection = await client.collections.get('collection-uuid');
+     * console.log('Properties:', collection.data.properties.length);
+     * ```
+     */
+    get(collectionId) {
+        const path = getCollectionsApiPath(this.workspaceId, collectionId);
+        return this.requestFn('GET', path);
+    }
+    /**
+     * Get a collection by its record slug.
+     *
+     * @param recordSlug - The collection's record slug (e.g., "orders")
+     * @returns The collection details
+     *
+     * @example
+     * ```ts
+     * const collection = await client.collections.getBySlug('orders');
+     * console.log('Collection name:', collection.data.name);
+     * ```
+     */
+    getBySlug(recordSlug) {
+        const path = getCollectionBySlugApiPath(this.workspaceId, recordSlug);
+        return this.requestFn('GET', path);
+    }
+    /**
+     * Create a new collection.
+     *
+     * @param input - The collection definition
+     * @returns The created collection
+     *
+     * @example
+     * ```ts
+     * const collection = await client.collections.create({
+     *   name: 'Orders',
+     *   slug: 'orders',
+     *   description: 'Customer orders',
+     *   properties: [
+     *     { name: 'title', type: 'string', required: true },
+     *     { name: 'amount', type: 'number', minimum: 0 },
+     *     { name: 'status', type: 'string', enum: ['pending', 'completed'] }
+     *   ],
+     *   enableVersioning: true,
+     *   schemaDiscoveryMode: 'strict'
+     * });
+     * ```
+     */
+    create(input) {
+        const path = getCollectionsApiPath(this.workspaceId);
+        return this.requestFn('POST', path, input);
+    }
+    /**
+     * Update an existing collection.
+     *
+     * @param collectionId - The collection UUID
+     * @param input - The fields to update
+     * @returns The updated collection
+     *
+     * @example
+     * ```ts
+     * const updated = await client.collections.update('collection-uuid', {
+     *   name: 'Updated Orders',
+     *   properties: [
+     *     { name: 'title', type: 'string', required: true },
+     *     { name: 'amount', type: 'number', minimum: 0 },
+     *     { name: 'priority', type: 'number' }
+     *   ]
+     * });
+     * ```
+     */
+    update(collectionId, input) {
+        const path = getCollectionsApiPath(this.workspaceId, collectionId);
+        return this.requestFn('PUT', path, input);
+    }
+    /**
+     * Delete a collection.
+     *
+     * @param collectionId - The collection UUID
+     *
+     * @example
+     * ```ts
+     * await client.collections.delete('collection-uuid');
+     * ```
+     */
+    delete(collectionId) {
+        const path = getCollectionsApiPath(this.workspaceId, collectionId);
+        return this.requestFn('DELETE', path);
+    }
+    /**
+     * Validate a collection definition without creating it.
+     * Useful for checking slug uniqueness and property validity before creation.
+     *
+     * @param input - The collection definition to validate
+     * @returns Validation result
+     *
+     * @example
+     * ```ts
+     * const result = await client.collections.validate({
+     *   slug: 'orders',
+     *   properties: [{ name: 'title', type: 'string' }]
+     * });
+     * ```
+     */
+    validate(input) {
+        const path = getCollectionValidateApiPath(this.workspaceId);
+        return this.requestFn('POST', path, input);
+    }
+}
+exports.CollectionsManager = CollectionsManager;
+// =====================================================
 // Compute Functions Manager (Configuration-as-Code)
 // =====================================================
 /**
@@ -2303,6 +2521,7 @@ class CentraliSDK {
         this._orchestrations = null;
         this._allowedDomains = null;
         this._structures = null;
+        this._collections = null;
         this._functions = null;
         this.isRefreshingToken = false;
         this.tokenRefreshPromise = null;
@@ -2593,11 +2812,39 @@ class CentraliSDK {
      * ```
      */
     get structures() {
+        emitDeprecationWarning('client.structures is deprecated. Use client.collections instead.');
         if (!this._structures) {
             this._structures = new StructuresManager(this.options.workspaceId, this.request.bind(this));
         }
         return this._structures;
     }
+    /**
+     * Collections namespace for managing data collections (schemas).
+     * Provides CRUD operations and validation for collection definitions.
+     * This is the preferred API — use `client.collections` instead of `client.structures`.
+     *
+     * Usage:
+     * ```ts
+     * // List all collections
+     * const collections = await client.collections.list();
+     *
+     * // Create a collection
+     * const collection = await client.collections.create({
+     *   name: 'Orders',
+     *   slug: 'orders',
+     *   properties: [{ name: 'title', type: 'string', required: true }]
+     * });
+     *
+     * // Validate before creating
+     * const result = await client.collections.validate({ slug: 'orders' });
+     * ```
+     */
+    get collections() {
+        if (!this._collections) {
+            this._collections = new CollectionsManager(this.options.workspaceId, this.request.bind(this));
+        }
+        return this._collections;
+    }
     /**
      * Functions namespace for managing compute functions.
      * Provides CRUD operations and test execution for compute function code.
@@ -2974,11 +3221,18 @@ class CentraliSDK {
         return __awaiter(this, void 0, void 0, function* () {
             const path = getSearchApiPath(this.options.workspaceId);
             const queryParams = { q: query };
-            if (options === null || options === void 0 ? void 0 : options.structures) {
+            if (options === null || options === void 0 ? void 0 : options.collections) {
+                const collections = Array.isArray(options.collections)
+                    ? options.collections.join(',')
+                    : options.collections;
+                queryParams.collections = collections;
+            }
+            else if (options === null || options === void 0 ? void 0 : options.structures) {
+                emitDeprecationWarning("The 'structures' search option is deprecated. Use 'collections' instead.");
                 const structures = Array.isArray(options.structures)
                     ? options.structures.join(',')
                     : options.structures;
-                queryParams.structures = structures;
+                queryParams.collections = structures;
             }
             if (options === null || options === void 0 ? void 0 : options.limit) {
                 queryParams.limit = String(options.limit);

package/index.ts

@@ -14,6 +14,18 @@ const EventSourceImpl: typeof EventSource = typeof EventSource !== 'undefined'
     ? EventSource
     : EventSourcePolyfill as unknown as typeof EventSource;
 
+// =====================================================
+// Deprecation Utility
+// =====================================================
+
+const _deprecationWarnings = new Set<string>();
+function emitDeprecationWarning(message: string): void {
+    if (!_deprecationWarnings.has(message)) {
+        _deprecationWarnings.add(message);
+        console.warn(`[DEPRECATION] ${message}`);
+    }
+}
+
 // =====================================================
 // Error Types
 // =====================================================
@@ -470,6 +482,8 @@ export interface RealtimeError {
 export interface RealtimeSubscribeOptions {
     /** Structure recordSlugs to filter events (e.g., ["order", "customer"]). Empty = all structures */
     structures?: string[];
+    /** Collection recordSlugs to filter events (e.g., ["order", "customer"]). Empty = all collections */
+    collections?: string[];
     /** Event types to filter (e.g., ["record_created"]). Empty = all events */
     events?: RealtimeEventType[];
     /** CFL (Centrali Filter Language) expression for data filtering (e.g., "status = 'active'") */
@@ -1654,6 +1668,11 @@ export interface ListStructuresOptions {
     limit?: number;
 }
 
+/**
+ * Options for listing collections (alias for ListStructuresOptions).
+ */
+export type ListCollectionsOptions = ListStructuresOptions;
+
 /**
  * Input for validating a structure definition.
  */
@@ -1834,6 +1853,8 @@ export interface TestSmartQueryInput {
 export interface SearchOptions {
     /** Filter by structure slug(s). Can be a single slug or array of slugs */
     structures?: string | string[];
+    /** Filter by collection slug(s). Can be a single slug or array of slugs */
+    collections?: string | string[];
     /** Maximum number of results to return (default: 20, max: 100) */
     limit?: number;
 }
@@ -2277,9 +2298,12 @@ export class RealtimeManager {
                 // Add access token
                 url.searchParams.set('access_token', token);
 
-                // Add structure filter
-                if (options.structures?.length) {
-                    url.searchParams.set('structures', options.structures.join(','));
+                // Add collection filter
+                if (options.collections?.length) {
+                    url.searchParams.set('collections', options.collections.join(','));
+                } else if (options.structures?.length) {
+                    emitDeprecationWarning("The 'structures' filter option is deprecated. Use 'collections' instead.");
+                    url.searchParams.set('collections', options.structures.join(','));
                 }
 
                 // Add event type filter
@@ -2630,6 +2654,39 @@ export function getStructureValidateApiPath(workspaceId: string): string {
     return `data/workspace/${workspaceId}/api/v1/structures/validate`;
 }
 
+// =====================================================
+// Collection API Path Helpers (Configuration-as-Code)
+// =====================================================
+
+/**
+ * Generate collection-scoped anomaly insights API URL PATH.
+ */
+export function getCollectionInsightsApiPath(workspaceId: string, collectionSlug: string): string {
+    return `data/workspace/${workspaceId}/api/v1/collections/${collectionSlug}/insights`;
+}
+
+/**
+ * Generate Collections base API URL PATH.
+ */
+export function getCollectionsApiPath(workspaceId: string, collectionId?: string): string {
+    const basePath = `data/workspace/${workspaceId}/api/v1/collections`;
+    return collectionId ? `${basePath}/${collectionId}` : basePath;
+}
+
+/**
+ * Generate Collection by slug API URL PATH.
+ */
+export function getCollectionBySlugApiPath(workspaceId: string, recordSlug: string): string {
+    return `data/workspace/${workspaceId}/api/v1/collections/slug/${recordSlug}`;
+}
+
+/**
+ * Generate Collection validate API URL PATH.
+ */
+export function getCollectionValidateApiPath(workspaceId: string): string {
+    return `data/workspace/${workspaceId}/api/v1/collections/validate`;
+}
+
 // =====================================================
 // Compute Function API Path Helpers (Configuration-as-Code)
 // =====================================================
@@ -4212,6 +4269,7 @@ export class StructuresManager {
      * ```
      */
     public list(options?: ListStructuresOptions): Promise<ApiResponse<Structure[]>> {
+        emitDeprecationWarning('client.structures.list() is deprecated. Use client.collections.list() instead.');
         const path = getStructuresApiPath(this.workspaceId);
         return this.requestFn<Structure[]>('GET', path, null, options);
     }
@@ -4229,6 +4287,7 @@ export class StructuresManager {
      * ```
      */
     public get(structureId: string): Promise<ApiResponse<Structure>> {
+        emitDeprecationWarning('client.structures.get() is deprecated. Use client.collections.get() instead.');
         const path = getStructuresApiPath(this.workspaceId, structureId);
         return this.requestFn<Structure>('GET', path);
     }
@@ -4246,6 +4305,7 @@ export class StructuresManager {
      * ```
      */
     public getBySlug(recordSlug: string): Promise<ApiResponse<Structure>> {
+        emitDeprecationWarning('client.structures.getBySlug() is deprecated. Use client.collections.getBySlug() instead.');
         const path = getStructureBySlugApiPath(this.workspaceId, recordSlug);
         return this.requestFn<Structure>('GET', path);
     }
@@ -4273,6 +4333,7 @@ export class StructuresManager {
      * ```
      */
     public create(input: CreateStructureInput): Promise<ApiResponse<Structure>> {
+        emitDeprecationWarning('client.structures.create() is deprecated. Use client.collections.create() instead.');
         const path = getStructuresApiPath(this.workspaceId);
         return this.requestFn<Structure>('POST', path, input);
     }
@@ -4297,6 +4358,7 @@ export class StructuresManager {
      * ```
      */
     public update(structureId: string, input: UpdateStructureInput): Promise<ApiResponse<Structure>> {
+        emitDeprecationWarning('client.structures.update() is deprecated. Use client.collections.update() instead.');
         const path = getStructuresApiPath(this.workspaceId, structureId);
         return this.requestFn<Structure>('PUT', path, input);
     }
@@ -4312,6 +4374,7 @@ export class StructuresManager {
      * ```
      */
     public delete(structureId: string): Promise<ApiResponse<void>> {
+        emitDeprecationWarning('client.structures.delete() is deprecated. Use client.collections.delete() instead.');
         const path = getStructuresApiPath(this.workspaceId, structureId);
         return this.requestFn<void>('DELETE', path);
     }
@@ -4332,11 +4395,191 @@ export class StructuresManager {
      * ```
      */
     public validate(input: ValidateStructureInput): Promise<ApiResponse<any>> {
+        emitDeprecationWarning('client.structures.validate() is deprecated. Use client.collections.validate() instead.');
         const path = getStructureValidateApiPath(this.workspaceId);
         return this.requestFn<any>('POST', path, input);
     }
 }
 
+// =====================================================
+// Collections Manager (Configuration-as-Code)
+// =====================================================
+
+/**
+ * CollectionsManager provides methods for managing data collections (schemas).
+ * Collections define the shape of records including properties, validation rules,
+ * and schema discovery modes.
+ * Access via `client.collections`.
+ *
+ * Usage:
+ * ```ts
+ * // List all collections
+ * const collections = await client.collections.list();
+ *
+ * // Create a new collection
+ * const collection = await client.collections.create({
+ *   name: 'Orders',
+ *   slug: 'orders',
+ *   properties: [
+ *     { name: 'title', type: 'string', required: true },
+ *     { name: 'amount', type: 'number', minimum: 0 }
+ *   ]
+ * });
+ *
+ * // Validate before creating
+ * const validation = await client.collections.validate({ slug: 'orders' });
+ * ```
+ */
+export class CollectionsManager {
+    private requestFn: <T>(method: Method, path: string, data?: any, queryParams?: Record<string, any>) => Promise<ApiResponse<T>>;
+    private workspaceId: string;
+
+    constructor(
+        workspaceId: string,
+        requestFn: <T>(method: Method, path: string, data?: any, queryParams?: Record<string, any>) => Promise<ApiResponse<T>>
+    ) {
+        this.workspaceId = workspaceId;
+        this.requestFn = requestFn;
+    }
+
+    /**
+     * List all collections in the workspace.
+     *
+     * @param options - Optional list parameters (pagination)
+     * @returns List of collections
+     *
+     * @example
+     * ```ts
+     * const collections = await client.collections.list();
+     * const page2 = await client.collections.list({ page: 2, limit: 10 });
+     * ```
+     */
+    public list(options?: ListCollectionsOptions): Promise<ApiResponse<Structure[]>> {
+        const path = getCollectionsApiPath(this.workspaceId);
+        return this.requestFn<Structure[]>('GET', path, null, options);
+    }
+
+    /**
+     * Get a collection by ID.
+     *
+     * @param collectionId - The collection UUID
+     * @returns The collection details
+     *
+     * @example
+     * ```ts
+     * const collection = await client.collections.get('collection-uuid');
+     * console.log('Properties:', collection.data.properties.length);
+     * ```
+     */
+    public get(collectionId: string): Promise<ApiResponse<Structure>> {
+        const path = getCollectionsApiPath(this.workspaceId, collectionId);
+        return this.requestFn<Structure>('GET', path);
+    }
+
+    /**
+     * Get a collection by its record slug.
+     *
+     * @param recordSlug - The collection's record slug (e.g., "orders")
+     * @returns The collection details
+     *
+     * @example
+     * ```ts
+     * const collection = await client.collections.getBySlug('orders');
+     * console.log('Collection name:', collection.data.name);
+     * ```
+     */
+    public getBySlug(recordSlug: string): Promise<ApiResponse<Structure>> {
+        const path = getCollectionBySlugApiPath(this.workspaceId, recordSlug);
+        return this.requestFn<Structure>('GET', path);
+    }
+
+    /**
+     * Create a new collection.
+     *
+     * @param input - The collection definition
+     * @returns The created collection
+     *
+     * @example
+     * ```ts
+     * const collection = await client.collections.create({
+     *   name: 'Orders',
+     *   slug: 'orders',
+     *   description: 'Customer orders',
+     *   properties: [
+     *     { name: 'title', type: 'string', required: true },
+     *     { name: 'amount', type: 'number', minimum: 0 },
+     *     { name: 'status', type: 'string', enum: ['pending', 'completed'] }
+     *   ],
+     *   enableVersioning: true,
+     *   schemaDiscoveryMode: 'strict'
+     * });
+     * ```
+     */
+    public create(input: CreateStructureInput): Promise<ApiResponse<Structure>> {
+        const path = getCollectionsApiPath(this.workspaceId);
+        return this.requestFn<Structure>('POST', path, input);
+    }
+
+    /**
+     * Update an existing collection.
+     *
+     * @param collectionId - The collection UUID
+     * @param input - The fields to update
+     * @returns The updated collection
+     *
+     * @example
+     * ```ts
+     * const updated = await client.collections.update('collection-uuid', {
+     *   name: 'Updated Orders',
+     *   properties: [
+     *     { name: 'title', type: 'string', required: true },
+     *     { name: 'amount', type: 'number', minimum: 0 },
+     *     { name: 'priority', type: 'number' }
+     *   ]
+     * });
+     * ```
+     */
+    public update(collectionId: string, input: UpdateStructureInput): Promise<ApiResponse<Structure>> {
+        const path = getCollectionsApiPath(this.workspaceId, collectionId);
+        return this.requestFn<Structure>('PUT', path, input);
+    }
+
+    /**
+     * Delete a collection.
+     *
+     * @param collectionId - The collection UUID
+     *
+     * @example
+     * ```ts
+     * await client.collections.delete('collection-uuid');
+     * ```
+     */
+    public delete(collectionId: string): Promise<ApiResponse<void>> {
+        const path = getCollectionsApiPath(this.workspaceId, collectionId);
+        return this.requestFn<void>('DELETE', path);
+    }
+
+    /**
+     * Validate a collection definition without creating it.
+     * Useful for checking slug uniqueness and property validity before creation.
+     *
+     * @param input - The collection definition to validate
+     * @returns Validation result
+     *
+     * @example
+     * ```ts
+     * const result = await client.collections.validate({
+     *   slug: 'orders',
+     *   properties: [{ name: 'title', type: 'string' }]
+     * });
+     * ```
+     */
+    public validate(input: ValidateStructureInput): Promise<ApiResponse<any>> {
+        const path = getCollectionValidateApiPath(this.workspaceId);
+        return this.requestFn<any>('POST', path, input);
+    }
+}
+
 // =====================================================
 // Compute Functions Manager (Configuration-as-Code)
 // =====================================================
@@ -4507,6 +4750,7 @@ export class CentraliSDK {
     private _orchestrations: OrchestrationsManager | null = null;
     private _allowedDomains: AllowedDomainsManager | null = null;
     private _structures: StructuresManager | null = null;
+    private _collections: CollectionsManager | null = null;
     private _functions: ComputeFunctionsManager | null = null;
     private isRefreshingToken: boolean = false;
     private tokenRefreshPromise: Promise<string> | null = null;
@@ -4856,6 +5100,7 @@ export class CentraliSDK {
      * ```
      */
     public get structures(): StructuresManager {
+        emitDeprecationWarning('client.structures is deprecated. Use client.collections instead.');
         if (!this._structures) {
             this._structures = new StructuresManager(
                 this.options.workspaceId,
@@ -4865,6 +5110,37 @@ export class CentraliSDK {
         return this._structures;
     }
 
+    /**
+     * Collections namespace for managing data collections (schemas).
+     * Provides CRUD operations and validation for collection definitions.
+     * This is the preferred API — use `client.collections` instead of `client.structures`.
+     *
+     * Usage:
+     * ```ts
+     * // List all collections
+     * const collections = await client.collections.list();
+     *
+     * // Create a collection
+     * const collection = await client.collections.create({
+     *   name: 'Orders',
+     *   slug: 'orders',
+     *   properties: [{ name: 'title', type: 'string', required: true }]
+     * });
+     *
+     * // Validate before creating
+     * const result = await client.collections.validate({ slug: 'orders' });
+     * ```
+     */
+    public get collections(): CollectionsManager {
+        if (!this._collections) {
+            this._collections = new CollectionsManager(
+                this.options.workspaceId,
+                this.request.bind(this)
+            );
+        }
+        return this._collections;
+    }
+
     /**
      * Functions namespace for managing compute functions.
      * Provides CRUD operations and test execution for compute function code.
@@ -5329,11 +5605,17 @@ export class CentraliSDK {
 
         const queryParams: Record<string, string> = { q: query };
 
-        if (options?.structures) {
+        if (options?.collections) {
+            const collections = Array.isArray(options.collections)
+                ? options.collections.join(',')
+                : options.collections;
+            queryParams.collections = collections;
+        } else if (options?.structures) {
+            emitDeprecationWarning("The 'structures' search option is deprecated. Use 'collections' instead.");
             const structures = Array.isArray(options.structures)
                 ? options.structures.join(',')
                 : options.structures;
-            queryParams.structures = structures;
+            queryParams.collections = structures;
         }
 
         if (options?.limit) {

package/package.json

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