@centrali-io/centrali-sdk 5.5.0 → 6.0.0

package/src/managers/structures.ts

@@ -0,0 +1,205 @@
+// =====================================================
+// Structures Manager (Configuration-as-Code)
+// =====================================================
+
+import type { Method } from 'axios';
+import type { ApiResponse } from '../types/common';
+import type {
+    Structure,
+    CreateStructureInput,
+    UpdateStructureInput,
+    ListStructuresOptions,
+    ValidateStructureInput,
+} from '../types/structures';
+import {
+    getStructuresApiPath,
+    getStructureBySlugApiPath,
+    getStructureValidateApiPath,
+} from '../internal/paths';
+import { emitDeprecationWarning } from '../internal/deprecation';
+
+// =====================================================
+// Structures Manager (Configuration-as-Code)
+// =====================================================
+
+/**
+ * StructuresManager provides methods for managing data structures (schemas).
+ * Structures define the shape of records including properties, validation rules,
+ * and schema discovery modes.
+ * Access via `client.structures`.
+ *
+ * Usage:
+ * ```ts
+ * // List all structures
+ * const structures = await client.structures.list();
+ *
+ * // Create a new structure
+ * const structure = await client.structures.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.structures.validate({ slug: 'orders' });
+ * ```
+ */
+export class StructuresManager {
+    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 structures in the workspace.
+     *
+     * @param options - Optional list parameters (pagination)
+     * @returns List of structures
+     *
+     * @example
+     * ```ts
+     * const structures = await client.structures.list();
+     * const page2 = await client.structures.list({ page: 2, limit: 10 });
+     * ```
+     */
+    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);
+    }
+
+    /**
+     * Get a structure by ID.
+     *
+     * @param structureId - The structure UUID
+     * @returns The structure details
+     *
+     * @example
+     * ```ts
+     * const structure = await client.structures.get('structure-uuid');
+     * console.log('Properties:', structure.data.properties.length);
+     * ```
+     */
+    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);
+    }
+
+    /**
+     * Get a structure by its record slug.
+     *
+     * @param recordSlug - The structure's record slug (e.g., "orders")
+     * @returns The structure details
+     *
+     * @example
+     * ```ts
+     * const structure = await client.structures.getBySlug('orders');
+     * console.log('Structure name:', structure.data.name);
+     * ```
+     */
+    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);
+    }
+
+    /**
+     * Create a new structure.
+     *
+     * @param input - The structure definition
+     * @returns The created structure
+     *
+     * @example
+     * ```ts
+     * const structure = await client.structures.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>> {
+        emitDeprecationWarning('client.structures.create() is deprecated. Use client.collections.create() instead.');
+        const path = getStructuresApiPath(this.workspaceId);
+        return this.requestFn<Structure>('POST', path, input);
+    }
+
+    /**
+     * Update an existing structure.
+     *
+     * @param structureId - The structure UUID
+     * @param input - The fields to update
+     * @returns The updated structure
+     *
+     * @example
+     * ```ts
+     * const updated = await client.structures.update('structure-uuid', {
+     *   name: 'Updated Orders',
+     *   properties: [
+     *     { name: 'title', type: 'string', required: true },
+     *     { name: 'amount', type: 'number', minimum: 0 },
+     *     { name: 'priority', type: 'number' }
+     *   ]
+     * });
+     * ```
+     */
+    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);
+    }
+
+    /**
+     * Delete a structure.
+     *
+     * @param structureId - The structure UUID
+     *
+     * @example
+     * ```ts
+     * await client.structures.delete('structure-uuid');
+     * ```
+     */
+    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);
+    }
+
+    /**
+     * Validate a structure definition without creating it.
+     * Useful for checking slug uniqueness and property validity before creation.
+     *
+     * @param input - The structure definition to validate
+     * @returns Validation result
+     *
+     * @example
+     * ```ts
+     * const result = await client.structures.validate({
+     *   slug: 'orders',
+     *   properties: [{ name: 'title', type: 'string' }]
+     * });
+     * ```
+     */
+    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);
+    }
+}

package/src/managers/triggers.ts

@@ -0,0 +1,349 @@
+// =====================================================
+// Triggers Manager
+// =====================================================
+
+import type { Method } from 'axios';
+import type { ApiResponse } from '../types/common';
+import type {
+    FunctionTrigger,
+    InvokeTriggerOptions,
+    InvokeEndpointOptions,
+    CreateTriggerInput,
+    UpdateTriggerInput,
+    ListAllTriggersOptions,
+    TriggerWithHealth,
+} from '../types/triggers';
+import type { TriggerInvokeResponse } from '../types/records';
+import {
+    getFunctionTriggerExecuteApiPath,
+    getFunctionTriggersApiPath,
+    getFunctionTriggerPauseApiPath,
+    getFunctionTriggerResumeApiPath,
+    getEndpointApiPath,
+} from '../internal/paths';
+
+// =====================================================
+
+/**
+ * TriggersManager provides methods for working with on-demand function triggers.
+ * Access via `client.triggers`.
+ *
+ * Note: This manager only works with on-demand triggers. Scheduled, event-driven,
+ * and webhook triggers are managed through other mechanisms.
+ *
+ * Usage:
+ * ```ts
+ * // Invoke an on-demand trigger
+ * const result = await client.triggers.invoke('trigger-id');
+ *
+ * // Invoke with custom payload
+ * const result = await client.triggers.invoke('trigger-id', {
+ *   payload: { customData: 'value' }
+ * });
+ *
+ * // Get an on-demand trigger by ID
+ * const trigger = await client.triggers.get('trigger-id');
+ *
+ * // List all on-demand triggers
+ * const triggers = await client.triggers.list();
+ * ```
+ */
+export class TriggersManager {
+    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;
+    }
+
+    /**
+     * Invoke an on-demand trigger by ID.
+     *
+     * @param triggerId - The ID of the trigger to invoke
+     * @param options - Optional invoke options including custom payload
+     * @returns The queued job ID for tracking the execution
+     *
+     * @example
+     * ```ts
+     * // Simple invocation
+     * const job = await client.triggers.invoke('trigger-id');
+     * console.log('Job queued:', job.data);
+     *
+     * // With custom payload
+     * const job = await client.triggers.invoke('trigger-id', {
+     *   payload: { orderId: '12345', action: 'process' }
+     * });
+     * ```
+     */
+    public invoke(
+        triggerId: string,
+        options?: InvokeTriggerOptions
+    ): Promise<ApiResponse<TriggerInvokeResponse>> {
+        const path = getFunctionTriggerExecuteApiPath(this.workspaceId, triggerId);
+        const data = options?.payload ?? {};
+        return this.requestFn<TriggerInvokeResponse>('POST', path, data);
+    }
+
+    /**
+     * Get an on-demand trigger by ID.
+     *
+     * Note: This method validates that the trigger is an on-demand trigger.
+     * If the trigger exists but is not on-demand, an error will be thrown.
+     *
+     * @param triggerId - The ID of the on-demand trigger to retrieve
+     * @returns The trigger details
+     * @throws Error if the trigger is not an on-demand trigger
+     *
+     * @example
+     * ```ts
+     * const trigger = await client.triggers.get('trigger-id');
+     * console.log('Trigger name:', trigger.data.name);
+     * ```
+     */
+    public async get(triggerId: string): Promise<ApiResponse<FunctionTrigger>> {
+        const path = getFunctionTriggersApiPath(this.workspaceId, triggerId);
+        const response = await this.requestFn<FunctionTrigger>('GET', path);
+
+        // Validate that the trigger is on-demand
+        if (response.data && response.data.executionType !== 'on-demand') {
+            throw new Error(`Trigger '${triggerId}' is not an on-demand trigger. Only on-demand triggers can be invoked via the SDK.`);
+        }
+
+        return response;
+    }
+
+    /**
+     * List all on-demand triggers in the workspace.
+     *
+     * This method automatically filters to only return triggers with executionType 'on-demand'.
+     *
+     * @param queryParams - Optional query parameters for pagination, search, etc.
+     * @returns List of on-demand triggers with pagination metadata
+     *
+     * @example
+     * ```ts
+     * // List all on-demand triggers
+     * const triggers = await client.triggers.list();
+     *
+     * // With pagination
+     * const triggers = await client.triggers.list({ limit: 10, page: 1 });
+     *
+     * // With search
+     * const triggers = await client.triggers.list({ search: 'process-order' });
+     * ```
+     */
+    public list(queryParams?: Record<string, any>): Promise<ApiResponse<FunctionTrigger[]>> {
+        const path = getFunctionTriggersApiPath(this.workspaceId);
+        // Always filter for on-demand triggers only
+        const params = {
+            ...queryParams,
+            executionType: 'on-demand'
+        };
+        return this.requestFn<FunctionTrigger[]>('GET', path, null, params);
+    }
+
+    /**
+     * Pause a function trigger.
+     *
+     * Pauses an event-driven or scheduled trigger to temporarily disable it from firing.
+     * When paused, the trigger will not execute until resumed.
+     *
+     * For scheduled triggers, this also pauses the underlying scheduler job.
+     *
+     * @param triggerId - The ID of the trigger to pause
+     * @returns The updated trigger with enabled = false
+     *
+     * @example
+     * ```ts
+     * // Pause a trigger
+     * const result = await client.triggers.pauseTrigger('trigger-id');
+     * console.log('Trigger paused:', result.data.enabled === false);
+     * ```
+     */
+    public pauseTrigger(triggerId: string): Promise<ApiResponse<FunctionTrigger>> {
+        const path = getFunctionTriggerPauseApiPath(this.workspaceId, triggerId);
+        return this.requestFn<FunctionTrigger>('PATCH', path, {});
+    }
+
+    /**
+     * Resume a paused function trigger.
+     *
+     * Resumes a paused event-driven or scheduled trigger to re-enable it.
+     * Once resumed, the trigger will start firing again on matching events or schedules.
+     *
+     * For scheduled triggers, this also resumes the underlying scheduler job.
+     *
+     * @param triggerId - The ID of the trigger to resume
+     * @returns The updated trigger with enabled = true
+     *
+     * @example
+     * ```ts
+     * // Resume a paused trigger
+     * const result = await client.triggers.resumeTrigger('trigger-id');
+     * console.log('Trigger resumed:', result.data.enabled === true);
+     * ```
+     */
+    public resumeTrigger(triggerId: string): Promise<ApiResponse<FunctionTrigger>> {
+        const path = getFunctionTriggerResumeApiPath(this.workspaceId, triggerId);
+        return this.requestFn<FunctionTrigger>('PATCH', path, {});
+    }
+
+    /**
+     * Create a new function trigger.
+     *
+     * @param input - The trigger definition
+     * @returns The created trigger
+     *
+     * @example
+     * ```ts
+     * // Create an event-driven trigger
+     * const trigger = await client.triggers.create({
+     *   name: 'On Order Created',
+     *   functionId: 'function-uuid',
+     *   executionType: 'event-driven',
+     *   triggerMetadata: { event: 'record.created', recordSlug: 'orders' }
+     * });
+     *
+     * // Create a scheduled trigger
+     * const scheduled = await client.triggers.create({
+     *   name: 'Daily Report',
+     *   functionId: 'function-uuid',
+     *   executionType: 'scheduled',
+     *   triggerMetadata: { scheduleType: 'cron', cronExpression: '0 9 * * *', timezone: 'America/New_York' }
+     * });
+     * ```
+     */
+    public create(input: CreateTriggerInput): Promise<ApiResponse<FunctionTrigger>> {
+        const path = getFunctionTriggersApiPath(this.workspaceId);
+        return this.requestFn<FunctionTrigger>('POST', path, input);
+    }
+
+    /**
+     * Update an existing function trigger.
+     *
+     * @param triggerId - The trigger UUID
+     * @param input - The fields to update
+     * @returns The updated trigger
+     *
+     * @example
+     * ```ts
+     * const updated = await client.triggers.update('trigger-uuid', {
+     *   name: 'Updated Trigger Name',
+     *   enabled: false
+     * });
+     * ```
+     */
+    public update(triggerId: string, input: UpdateTriggerInput): Promise<ApiResponse<FunctionTrigger>> {
+        const path = getFunctionTriggersApiPath(this.workspaceId, triggerId);
+        return this.requestFn<FunctionTrigger>('PUT', path, input);
+    }
+
+    /**
+     * Delete a function trigger.
+     *
+     * @param triggerId - The trigger UUID
+     *
+     * @example
+     * ```ts
+     * await client.triggers.delete('trigger-uuid');
+     * ```
+     */
+    public delete(triggerId: string): Promise<ApiResponse<void>> {
+        const path = getFunctionTriggersApiPath(this.workspaceId, triggerId);
+        return this.requestFn<void>('DELETE', path);
+    }
+
+    /**
+     * List all triggers in the workspace (not filtered by execution type).
+     * Unlike `list()` which only returns on-demand triggers, `listAll()` returns
+     * triggers of all types with optional filtering.
+     *
+     * @param options - Optional list parameters (pagination, filtering, health)
+     * @returns List of triggers
+     *
+     * @example
+     * ```ts
+     * // List all triggers
+     * const all = await client.triggers.listAll();
+     *
+     * // Filter by execution type
+     * const scheduled = await client.triggers.listAll({ executionType: 'scheduled' });
+     *
+     * // Include health metrics
+     * const withHealth = await client.triggers.listAll({ includeHealth: true });
+     * ```
+     */
+    public listAll(options?: ListAllTriggersOptions): Promise<ApiResponse<(FunctionTrigger | TriggerWithHealth)[]>> {
+        const path = getFunctionTriggersApiPath(this.workspaceId);
+        return this.requestFn<(FunctionTrigger | TriggerWithHealth)[]>('GET', path, null, options);
+    }
+
+    /**
+     * Get a trigger by ID with full details (no on-demand type restriction).
+     * Unlike `get()` which validates on-demand type, `getDetails()` returns
+     * any trigger type.
+     *
+     * @param triggerId - The trigger UUID
+     * @param options - Optional parameters (includeHealth)
+     * @returns The trigger details
+     *
+     * @example
+     * ```ts
+     * const trigger = await client.triggers.getDetails('trigger-uuid');
+     *
+     * // With health metrics
+     * const withHealth = await client.triggers.getDetails('trigger-uuid', { includeHealth: true });
+     * ```
+     */
+    public getDetails(triggerId: string, options?: { includeHealth?: boolean }): Promise<ApiResponse<FunctionTrigger | TriggerWithHealth>> {
+        const path = getFunctionTriggersApiPath(this.workspaceId, triggerId);
+        return this.requestFn<FunctionTrigger | TriggerWithHealth>('GET', path, null, options);
+    }
+
+    /**
+     * Invoke a synchronous compute endpoint by its path.
+     *
+     * Unlike `invoke()` (which is async and returns a job ID), endpoint triggers
+     * execute the function and return the result inline. Max 30 second timeout.
+     *
+     * @param endpointPath - The endpoint path (e.g., 'create-order')
+     * @param options - Optional method, payload, headers, query params
+     * @returns The function's response (status, data, headers)
+     *
+     * @example
+     * ```ts
+     * // POST to an endpoint
+     * const result = await client.triggers.invokeEndpoint('create-order', {
+     *   payload: { product: 'Widget', quantity: 5 }
+     * });
+     * console.log('Status:', result.data.status);
+     * console.log('Response:', result.data.data);
+     *
+     * // GET with query params
+     * const users = await client.triggers.invokeEndpoint('list-users', {
+     *   method: 'GET',
+     *   query: { role: 'admin' }
+     * });
+     *
+     * // With API key auth
+     * const result = await client.triggers.invokeEndpoint('webhook/stripe', {
+     *   payload: stripeEvent,
+     *   headers: { 'X-API-Key': 'your-api-key' }
+     * });
+     * ```
+     */
+    public invokeEndpoint<T = any>(
+        endpointPath: string,
+        options?: InvokeEndpointOptions
+    ): Promise<ApiResponse<T>> {
+        const path = getEndpointApiPath(this.workspaceId, endpointPath);
+        const method = (options?.method || 'POST') as Method;
+        const data = ['GET', 'DELETE'].includes(method) ? undefined : (options?.payload || {});
+        const queryParams = options?.query;
+        return this.requestFn<T>(method, path, data, queryParams);
+    }
+}