@centrali-io/centrali-sdk 5.5.0 → 6.0.0

package/src/managers/allowedDomains.ts

@@ -0,0 +1,90 @@
+// =====================================================
+// Allowed Domains Manager
+// =====================================================
+
+import type { Method } from 'axios';
+import type { ApiResponse } from '../types/common';
+import type { AllowedDomain, AddAllowedDomainOptions } from '../types/allowedDomains';
+import { getAllowedDomainsApiPath } from '../internal/paths';
+
+// =====================================================
+// Allowed Domains Manager
+// =====================================================
+
+/**
+ * AllowedDomainsManager provides methods for managing allowed domains for compute function external calls.
+ * Access via `client.allowedDomains`.
+ *
+ * Usage:
+ * ```ts
+ * // List all allowed domains
+ * const domains = await client.allowedDomains.list();
+ *
+ * // Add a new domain
+ * const domain = await client.allowedDomains.add({ domain: 'api.example.com' });
+ *
+ * // Remove a domain
+ * await client.allowedDomains.remove('domain-id');
+ * ```
+ */
+export class AllowedDomainsManager {
+    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 allowed domains in the workspace.
+     *
+     * @returns List of allowed domains with total count
+     *
+     * @example
+     * ```ts
+     * const result = await client.allowedDomains.list();
+     * console.log('Total domains:', result.meta.total);
+     * result.data.forEach(d => console.log(d.domain));
+     * ```
+     */
+    public list(): Promise<ApiResponse<AllowedDomain[]>> {
+        const path = getAllowedDomainsApiPath(this.workspaceId);
+        return this.requestFn<AllowedDomain[]>('GET', path);
+    }
+
+    /**
+     * Add a new allowed domain.
+     *
+     * @param options - The domain to add
+     * @returns The created allowed domain entry
+     *
+     * @example
+     * ```ts
+     * const result = await client.allowedDomains.add({ domain: 'api.stripe.com' });
+     * console.log('Added:', result.data.domain, result.data.id);
+     * ```
+     */
+    public add(options: AddAllowedDomainOptions): Promise<ApiResponse<AllowedDomain>> {
+        const path = getAllowedDomainsApiPath(this.workspaceId);
+        return this.requestFn<AllowedDomain>('POST', path, { domain: options.domain });
+    }
+
+    /**
+     * Remove an allowed domain by ID.
+     *
+     * @param domainId - The ID of the domain to remove
+     *
+     * @example
+     * ```ts
+     * await client.allowedDomains.remove('domain-id-123');
+     * ```
+     */
+    public remove(domainId: string): Promise<ApiResponse<void>> {
+        const path = getAllowedDomainsApiPath(this.workspaceId, domainId);
+        return this.requestFn<void>('DELETE', path);
+    }
+}

package/src/managers/anomalyInsights.ts

@@ -0,0 +1,215 @@
+// =====================================================
+// Anomaly Insights Manager
+// =====================================================
+
+import type { Method } from 'axios';
+import type { ApiResponse } from '../types/common';
+import type {
+    AnomalyInsight,
+    ListInsightsOptions,
+    AnomalyAnalysisResult,
+    InsightsSummary,
+} from '../types/insights';
+import {
+    getAnomalyInsightsApiPath,
+    getStructureInsightsApiPath,
+    getAnomalyInsightAcknowledgeApiPath,
+    getAnomalyInsightDismissApiPath,
+    getAnomalyInsightsBulkAcknowledgeApiPath,
+    getAnomalyInsightsSummaryApiPath,
+    getAnomalyAnalysisTriggerApiPath,
+} from '../internal/paths';
+
+// =====================================================
+// Anomaly Insights Manager
+// =====================================================
+
+/**
+ * AnomalyInsightsManager provides methods for querying and managing AI-generated anomaly insights.
+ * Access via `client.anomalyInsights`.
+ *
+ * Usage:
+ * ```ts
+ * // List all active insights
+ * const insights = await client.anomalyInsights.list({ status: 'active' });
+ *
+ * // Get insights for a specific structure
+ * const orderInsights = await client.anomalyInsights.listByStructure('orders');
+ *
+ * // Get insight summary
+ * const summary = await client.anomalyInsights.getSummary();
+ *
+ * // Acknowledge an insight
+ * await client.anomalyInsights.acknowledge('insight-id');
+ *
+ * // Dismiss an insight
+ * await client.anomalyInsights.dismiss('insight-id');
+ * ```
+ */
+export class AnomalyInsightsManager {
+    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 anomaly insights with optional filters.
+     *
+     * @param options - Optional filter and pagination options
+     * @returns List of anomaly insights
+     *
+     * @example
+     * ```ts
+     * // List all active critical insights
+     * const insights = await client.anomalyInsights.list({
+     *   status: 'active',
+     *   severity: 'critical'
+     * });
+     *
+     * // List insights for a specific structure
+     * const orderInsights = await client.anomalyInsights.list({
+     *   structureSlug: 'orders'
+     * });
+     * ```
+     */
+    public list(options?: ListInsightsOptions): Promise<ApiResponse<AnomalyInsight[]>> {
+        const path = getAnomalyInsightsApiPath(this.workspaceId);
+        return this.requestFn<AnomalyInsight[]>('GET', path, null, options);
+    }
+
+    /**
+     * List insights for a specific structure.
+     *
+     * @param structureSlug - The structure's record slug
+     * @param options - Optional filter options
+     * @returns List of insights for the structure
+     *
+     * @example
+     * ```ts
+     * const insights = await client.anomalyInsights.listByStructure('orders');
+     * ```
+     */
+    public listByStructure(
+        structureSlug: string,
+        options?: Omit<ListInsightsOptions, 'structureSlug'>
+    ): Promise<ApiResponse<AnomalyInsight[]>> {
+        const path = getStructureInsightsApiPath(this.workspaceId, structureSlug);
+        return this.requestFn<AnomalyInsight[]>('GET', path, null, options);
+    }
+
+    /**
+     * Get a single insight by ID.
+     *
+     * @param insightId - The insight UUID
+     * @returns The insight details
+     *
+     * @example
+     * ```ts
+     * const insight = await client.anomalyInsights.get('insight-id');
+     * console.log('Insight:', insight.data.title);
+     * ```
+     */
+    public get(insightId: string): Promise<ApiResponse<AnomalyInsight>> {
+        const path = getAnomalyInsightsApiPath(this.workspaceId, insightId);
+        return this.requestFn<AnomalyInsight>('GET', path);
+    }
+
+    /**
+     * Acknowledge an insight.
+     * Marks the insight as reviewed/handled.
+     *
+     * @param insightId - The insight UUID
+     * @returns The updated insight
+     *
+     * @example
+     * ```ts
+     * await client.anomalyInsights.acknowledge('insight-id');
+     * ```
+     */
+    public acknowledge(insightId: string): Promise<ApiResponse<AnomalyInsight>> {
+        const path = getAnomalyInsightAcknowledgeApiPath(this.workspaceId, insightId);
+        return this.requestFn<AnomalyInsight>('POST', path);
+    }
+
+    /**
+     * Dismiss an insight.
+     * Marks the insight as not relevant/false positive.
+     *
+     * @param insightId - The insight UUID
+     * @returns The updated insight
+     *
+     * @example
+     * ```ts
+     * await client.anomalyInsights.dismiss('insight-id');
+     * ```
+     */
+    public dismiss(insightId: string): Promise<ApiResponse<AnomalyInsight>> {
+        const path = getAnomalyInsightDismissApiPath(this.workspaceId, insightId);
+        return this.requestFn<AnomalyInsight>('POST', path);
+    }
+
+    /**
+     * Bulk acknowledge multiple insights.
+     *
+     * @param ids - Array of insight IDs to acknowledge
+     * @returns Result with count of updated insights
+     *
+     * @example
+     * ```ts
+     * const result = await client.anomalyInsights.bulkAcknowledge(['id1', 'id2']);
+     * console.log('Acknowledged:', result.data.updated);
+     * ```
+     */
+    public bulkAcknowledge(ids: string[]): Promise<ApiResponse<{ updated: number; message: string }>> {
+        const path = getAnomalyInsightsBulkAcknowledgeApiPath(this.workspaceId);
+        return this.requestFn<{ updated: number; message: string }>('POST', path, { ids });
+    }
+
+    /**
+     * Get insights summary/statistics.
+     *
+     * @param structureSlug - Optional structure to filter summary
+     * @returns Summary of insights by status and severity
+     *
+     * @example
+     * ```ts
+     * // Get overall summary
+     * const summary = await client.anomalyInsights.getSummary();
+     * console.log('Critical insights:', summary.data.bySeverity.critical);
+     *
+     * // Get summary for a specific structure
+     * const orderSummary = await client.anomalyInsights.getSummary('orders');
+     * ```
+     */
+    public getSummary(structureSlug?: string): Promise<ApiResponse<InsightsSummary>> {
+        const path = getAnomalyInsightsSummaryApiPath(this.workspaceId);
+        const params = structureSlug ? { structureSlug } : undefined;
+        return this.requestFn<InsightsSummary>('GET', path, null, params);
+    }
+
+    /**
+     * Trigger anomaly analysis for a structure.
+     * Starts an AI-powered analysis to detect anomalies in the structure's data.
+     *
+     * @param structureSlug - The structure's record slug to analyze
+     * @returns Result indicating if analysis was triggered and the batch ID
+     *
+     * @example
+     * ```ts
+     * const result = await client.anomalyInsights.triggerAnalysis('orders');
+     * if (result.data.success) {
+     *   console.log('Analysis started:', result.data.batchId);
+     * }
+     * ```
+     */
+    public triggerAnalysis(structureSlug: string): Promise<ApiResponse<AnomalyAnalysisResult>> {
+        const path = getAnomalyAnalysisTriggerApiPath(this.workspaceId);
+        return this.requestFn<AnomalyAnalysisResult>('POST', path, { structureSlug });
+    }
+}

package/src/managers/auditLog.ts

@@ -0,0 +1,105 @@
+// =====================================================
+// Audit Log Manager (canonical query surface — CEN-1215)
+// =====================================================
+
+import type { Method } from 'axios';
+import type { ApiResponse } from '../types/common';
+import type { QueryDefinition, QueryResult } from '../../query-types';
+
+
+/**
+ * AuditLogManager exposes the canonical query surface for the audit log.
+ *
+ * Phase 3 of the query foundation (CEN-1214 epic). Workspace-service backed,
+ * not data-service — the audit log is a workspace concern. The shape mirrors
+ * `RecordsManager` so a caller writing audit-log queries uses the same
+ * vocabulary they already know from records.
+ *
+ * - {@link AuditLogManager.query | query} — full POST `/audit/query`. Use for
+ *   nested boolean trees, `select` projection, paging.
+ * - {@link AuditLogManager.test | test} — authoring dry-run against
+ *   `/audit/query/test`. Validates and plans without executing.
+ *
+ * Access via `client.auditLog`.
+ *
+ * @example
+ * ```ts
+ * // Per-resource history (canonical equivalent of legacy GET /audit/.../history).
+ * const history = await client.auditLog.query({
+ *   resource: 'audit-log',
+ *   where: {
+ *     and: [
+ *       { resourceType: { eq: 'structure' } },
+ *       { resourceId: { eq: 'r-123' } },
+ *     ],
+ *   },
+ *   sort: [{ field: 'createdAt', direction: 'desc' }],
+ *   page: { limit: 50 },
+ * });
+ *
+ * // Workspace-wide activity feed in a date range, projecting only the columns
+ * // the table needs (drops the heavy `changes` JSONB).
+ * const activity = await client.auditLog.query({
+ *   resource: 'audit-log',
+ *   where: {
+ *     and: [
+ *       { createdAt: { gte: '2026-04-01' } },
+ *       { createdAt: { lt: '2026-05-01' } },
+ *     ],
+ *   },
+ *   sort: [{ field: 'createdAt', direction: 'desc' }],
+ *   page: { limit: 100 },
+ *   select: { fields: ['type', 'resourceType', 'resourceId', 'actorId', 'summary', 'createdAt'] },
+ * });
+ * ```
+ */
+export class AuditLogManager {
+    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;
+    }
+
+    /**
+     * Run a canonical query against `POST /workspace/<ws>/api/v1/audit/query`.
+     *
+     * The body **is** a `QueryDefinition`. `resource` is forced to `"audit-log"`
+     * — the workspace executor rejects anything else. Returns the canonical
+     * `{ data, meta }` envelope.
+     *
+     * The `where` clause that pins both `resourceType.eq` and `resourceId.eq`
+     * uses `audit_logs:retrieve` server-side; everything else uses
+     * `audit_logs:list`. Retrieve-only roles can still query their own
+     * resource's history this way.
+     */
+    public async query<T = any>(
+        definition: Omit<QueryDefinition, 'resource'> & { resource?: string }
+    ): Promise<QueryResult<T>> {
+        const path = `workspace/api/v1/${this.workspaceId}/audit/query`;
+        const body: QueryDefinition = { ...definition, resource: 'audit-log' };
+        const resp = await this.requestFn<T[]>('POST', path, body);
+        return resp as unknown as QueryResult<T>;
+    }
+
+    /**
+     * Authoring-time dry-run against `POST /audit/query/test`.
+     *
+     * Same input shape as {@link AuditLogManager.query | query}. Returns a
+     * plan summary on success or structured `QueryError`s on failure, without
+     * executing the query. Use from query builders to surface precise errors
+     * before saving / running.
+     */
+    public async test(
+        definition: Omit<QueryDefinition, 'resource'> & { resource?: string }
+    ): Promise<{ ok: true; plan: { executor: string; resource: string; mode: string; hasUnreadableField: boolean } }> {
+        const path = `workspace/api/v1/${this.workspaceId}/audit/query/test`;
+        const body: QueryDefinition = { ...definition, resource: 'audit-log' };
+        const resp = await this.requestFn<{ ok: true; plan: { executor: string; resource: string; mode: string; hasUnreadableField: boolean } }>('POST', path, body);
+        return resp.data;
+    }
+}

package/src/managers/collections.ts

@@ -0,0 +1,197 @@
+// =====================================================
+// Collections Manager (Configuration-as-Code)
+// =====================================================
+
+import type { Method } from 'axios';
+import type { ApiResponse } from '../types/common';
+import type {
+    Structure,
+    CreateStructureInput,
+    UpdateStructureInput,
+    ListCollectionsOptions,
+    ValidateStructureInput,
+} from '../types/structures';
+import {
+    getCollectionsApiPath,
+    getCollectionBySlugApiPath,
+    getCollectionValidateApiPath,
+} from '../internal/paths';
+
+// =====================================================
+// 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',
+ *   recordSlug: 'orders',
+ *   properties: [
+ *     { name: 'title', type: 'string', required: true },
+ *     { name: 'amount', type: 'number', minimum: 0 }
+ *   ]
+ * });
+ *
+ * // Validate before creating
+ * const validation = await client.collections.validate({ recordSlug: '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',
+     *   recordSlug: '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);
+    }
+}