@centrali-io/centrali-sdk 5.5.0 → 6.0.0

package/src/internal/auth.ts

@@ -0,0 +1,35 @@
+import axios from 'axios';
+import { getApiUrl, getAuthUrl } from '../urls';
+
+// Helper to encode form data
+export function encodeFormData(data: Record<string, string>): string {
+    return new URLSearchParams(data).toString();
+}
+
+/**
+ * Retrieve an access token using the Client Credentials flow.
+ */
+export async function fetchClientToken(
+    clientId: string,
+    clientSecret: string,
+    baseUrl: string
+): Promise<string> {
+    const authUrl = getAuthUrl(baseUrl);
+    const apiUrl = getApiUrl(baseUrl);
+    const tokenEndpoint = `${authUrl}/token`;
+    const form = encodeFormData({
+        grant_type: 'client_credentials',
+        client_id: clientId,
+        client_secret: clientSecret,
+        resource: `${apiUrl}/data`
+    });
+    const resp = await axios.post(
+        tokenEndpoint,
+        form,
+        { headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+          proxy: false
+        }
+    );
+
+    return resp.data.access_token;
+}

package/src/internal/deprecation.ts

@@ -0,0 +1,11 @@
+// =====================================================
+// Deprecation Utility
+// =====================================================
+
+const _deprecationWarnings = new Set<string>();
+export function emitDeprecationWarning(message: string): void {
+    if (!_deprecationWarnings.has(message)) {
+        _deprecationWarnings.add(message);
+        console.warn(`[DEPRECATION] ${message}`);
+    }
+}

package/src/internal/error.ts

@@ -0,0 +1,90 @@
+// =====================================================
+// Error Types
+// =====================================================
+
+import { AxiosError } from 'axios';
+
+/**
+ * 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;
+}
+
+export 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));
+}

package/src/internal/paths.ts

@@ -0,0 +1,456 @@
+/**
+ * Generate Records API URL PATH.
+ */
+
+export function getRecordApiPath(workspaceId: string,recordSlug: string, id?: string): string {
+    return id ? `data/workspace/${workspaceId}/api/v1/records/slug/${recordSlug}/${id}` : `data/workspace/${workspaceId}/api/v1/records/slug/${recordSlug}`;
+}
+
+
+/**
+ * Generate File Upload API URL PATH.
+ * @param workspaceId
+ */
+export function getFileUploadApiPath(workspaceId: string): string {
+    return `storage/ws/${workspaceId}/api/v1/files`;
+}
+
+/**
+ * Generate canonical Files query API URL PATH (CEN-1218 / Phase 3).
+ * Backs `POST /files/query`, `/files/query/test`, and the
+ * `GET /files` URL adapter. Lives on the storage service alongside
+ * the upload + render endpoints.
+ */
+export function getFilesCanonicalApiPath(workspaceId: string, suffix?: 'query' | 'query/test'): string {
+    const basePath = `storage/ws/${workspaceId}/api/v1/files`;
+    return suffix ? `${basePath}/${suffix}` : basePath;
+}
+
+/**
+ * Generate Function Triggers base API URL PATH.
+ */
+export function getFunctionTriggersApiPath(workspaceId: string, triggerId?: string): string {
+    const basePath = `data/workspace/${workspaceId}/api/v1/function-triggers`;
+    return triggerId ? `${basePath}/${triggerId}` : basePath;
+}
+
+/**
+ * Generate Function Trigger execute API URL PATH.
+ */
+export function getFunctionTriggerExecuteApiPath(workspaceId: string, triggerId: string): string {
+    return `data/workspace/${workspaceId}/api/v1/function-triggers/${triggerId}/execute`;
+}
+
+/**
+ * Generate Function Trigger pause API URL PATH.
+ */
+export function getFunctionTriggerPauseApiPath(workspaceId: string, triggerId: string): string {
+    return `data/workspace/${workspaceId}/api/v1/function-triggers/${triggerId}/pause`;
+}
+
+/**
+ * Generate Function Trigger resume API URL PATH.
+ */
+export function getFunctionTriggerResumeApiPath(workspaceId: string, triggerId: string): string {
+    return `data/workspace/${workspaceId}/api/v1/function-triggers/${triggerId}/resume`;
+}
+
+/**
+ * Generate Endpoint trigger invocation API URL PATH.
+ */
+export function getEndpointApiPath(workspaceId: string, path: string): string {
+    return `data/workspace/${workspaceId}/api/v1/endpoints/${path}`;
+}
+
+/**
+ * Generate Saved Queries base API URL PATH for workspace-level operations.
+ *
+ * Phase 4 (CEN-1198) of the query foundation moved the canonical mount from
+ * `/smart-queries` to `/saved-queries`. The data service dual-mounts both for
+ * the deprecation window; this helper emits the canonical path.
+ */
+export function getSmartQueriesApiPath(workspaceId: string): string {
+    return `data/workspace/${workspaceId}/api/v1/saved-queries`;
+}
+
+/**
+ * Generate Saved Queries API URL PATH for structure-level operations.
+ */
+export function getSmartQueriesStructureApiPath(workspaceId: string, structureSlug: string, queryId?: string): string {
+    const basePath = `data/workspace/${workspaceId}/api/v1/saved-queries/slug/${structureSlug}`;
+    return queryId ? `${basePath}/${queryId}` : basePath;
+}
+
+/**
+ * Generate Saved Query by name API URL PATH.
+ */
+export function getSmartQueryByNameApiPath(workspaceId: string, structureSlug: string, name: string): string {
+    return `data/workspace/${workspaceId}/api/v1/saved-queries/slug/${structureSlug}/name/${encodeURIComponent(name)}`;
+}
+
+/**
+ * Generate Saved Query execute API URL PATH.
+ */
+export function getSmartQueryExecuteApiPath(workspaceId: string, structureSlug: string, queryId: string): string {
+    return `data/workspace/${workspaceId}/api/v1/saved-queries/slug/${structureSlug}/execute/${queryId}`;
+}
+
+/**
+ * Phase 4 canonical saved-query path helpers (no `slug` segment). These hit
+ * the canonical write/execute endpoints that accept canonical `query` bodies
+ * and `variables` typed declarations.
+ */
+export function getSavedQueryCanonicalCollectionPath(workspaceId: string): string {
+    return `data/workspace/${workspaceId}/api/v1/saved-queries`;
+}
+export function getSavedQueryCanonicalByIdPath(workspaceId: string, queryId: string): string {
+    return `data/workspace/${workspaceId}/api/v1/saved-queries/${queryId}`;
+}
+export function getSavedQueryCanonicalExecutePath(workspaceId: string, queryId: string): string {
+    return `data/workspace/${workspaceId}/api/v1/saved-queries/${queryId}/execute`;
+}
+export function getSavedQueryCanonicalTestPath(workspaceId: string): string {
+    return `data/workspace/${workspaceId}/api/v1/saved-queries/test`;
+}
+
+/**
+ * Generate Search API URL PATH.
+ */
+export function getSearchApiPath(workspaceId: string): string {
+    return `search/workspace/${workspaceId}/api/v1/records/search`;
+}
+
+/**
+ * Generate Anomaly Insights base API URL PATH.
+ */
+export function getAnomalyInsightsApiPath(workspaceId: string, insightId?: string): string {
+    const basePath = `data/workspace/${workspaceId}/api/v1/ai/insights`;
+    return insightId ? `${basePath}/${insightId}` : basePath;
+}
+
+/**
+ * Generate Anomaly Insights summary API URL PATH.
+ */
+export function getAnomalyInsightsSummaryApiPath(workspaceId: string): string {
+    return `data/workspace/${workspaceId}/api/v1/ai/insights/summary`;
+}
+
+/**
+ * Generate Anomaly Insights acknowledge API URL PATH.
+ */
+export function getAnomalyInsightAcknowledgeApiPath(workspaceId: string, insightId: string): string {
+    return `data/workspace/${workspaceId}/api/v1/ai/insights/${insightId}/acknowledge`;
+}
+
+/**
+ * Generate Anomaly Insights dismiss API URL PATH.
+ */
+export function getAnomalyInsightDismissApiPath(workspaceId: string, insightId: string): string {
+    return `data/workspace/${workspaceId}/api/v1/ai/insights/${insightId}/dismiss`;
+}
+
+/**
+ * Generate Anomaly Insights bulk acknowledge API URL PATH.
+ */
+export function getAnomalyInsightsBulkAcknowledgeApiPath(workspaceId: string): string {
+    return `data/workspace/${workspaceId}/api/v1/ai/insights/bulk-acknowledge`;
+}
+
+/**
+ * Generate Anomaly analysis trigger API URL PATH.
+ */
+export function getAnomalyAnalysisTriggerApiPath(workspaceId: string): string {
+    return `data/workspace/${workspaceId}/api/v1/ai/anomalies/analyze`;
+}
+
+/**
+ * Generate structure-scoped anomaly insights API URL PATH.
+ */
+export function getStructureInsightsApiPath(workspaceId: string, structureSlug: string): string {
+    return `data/workspace/${workspaceId}/api/v1/structures/${structureSlug}/insights`;
+}
+
+// =====================================================
+// Structure API Path Helpers (Configuration-as-Code)
+// =====================================================
+
+/**
+ * Generate Structures base API URL PATH.
+ */
+export function getStructuresApiPath(workspaceId: string, structureId?: string): string {
+    const basePath = `data/workspace/${workspaceId}/api/v1/structures`;
+    return structureId ? `${basePath}/${structureId}` : basePath;
+}
+
+/**
+ * Generate Structure by slug API URL PATH.
+ */
+export function getStructureBySlugApiPath(workspaceId: string, recordSlug: string): string {
+    return `data/workspace/${workspaceId}/api/v1/structures/slug/${recordSlug}`;
+}
+
+/**
+ * Generate Structure validate API URL PATH.
+ */
+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)
+// =====================================================
+
+/**
+ * Generate Compute Functions base API URL PATH.
+ */
+export function getComputeFunctionsApiPath(workspaceId: string, functionId?: string): string {
+    const basePath = `data/workspace/${workspaceId}/api/v1/compute-functions`;
+    return functionId ? `${basePath}/${functionId}` : basePath;
+}
+
+/**
+ * Generate Compute Function test execution API URL PATH.
+ */
+export function getComputeFunctionTestApiPath(workspaceId: string): string {
+    return `data/workspace/${workspaceId}/api/v1/compute-functions/test`;
+}
+
+// =====================================================
+// Function Runs API Path Helpers
+// =====================================================
+
+/**
+ * Generate Function Runs base API URL PATH.
+ */
+export function getFunctionRunsApiPath(workspaceId: string, runId?: string): string {
+    const basePath = `data/workspace/${workspaceId}/api/v1/function-runs`;
+    return runId ? `${basePath}/${runId}` : basePath;
+}
+
+/**
+ * Generate Function Runs by trigger API URL PATH.
+ */
+export function getFunctionRunsByTriggerApiPath(workspaceId: string, triggerId: string): string {
+    return `data/workspace/${workspaceId}/api/v1/function-runs/trigger/${triggerId}`;
+}
+
+/**
+ * Generate Function Runs by function API URL PATH.
+ */
+export function getFunctionRunsByFunctionApiPath(workspaceId: string, functionId: string): string {
+    return `data/workspace/${workspaceId}/api/v1/function-runs/function/${functionId}`;
+}
+
+// =====================================================
+// Compute Job Status API Path Helper
+// =====================================================
+
+/**
+ * Generate Compute Job Status API URL PATH.
+ */
+export function getComputeJobStatusApiPath(workspaceId: string, jobId: string): string {
+    return `data/workspace/${workspaceId}/api/v1/jobs/compute/${jobId}`;
+}
+
+// =====================================================
+// Smart Query Test API Path Helper (Configuration-as-Code)
+// =====================================================
+
+/**
+ * Generate Saved Query test execution API URL PATH.
+ */
+export function getSmartQueryTestApiPath(workspaceId: string, structureSlug: string): string {
+    return `data/workspace/${workspaceId}/api/v1/saved-queries/slug/${structureSlug}/test`;
+}
+
+// =====================================================
+// Validation API Path Helpers
+// =====================================================
+
+/**
+ * Generate Validation suggestions base API URL PATH.
+ */
+export function getValidationSuggestionsApiPath(workspaceId: string, suggestionId?: string): string {
+    const basePath = `data/workspace/${workspaceId}/api/v1/ai/validation/suggestions`;
+    return suggestionId ? `${basePath}/${suggestionId}` : basePath;
+}
+
+/**
+ * Generate Validation suggestion accept API URL PATH.
+ */
+export function getValidationSuggestionAcceptApiPath(workspaceId: string, suggestionId: string): string {
+    return `data/workspace/${workspaceId}/api/v1/ai/validation/suggestions/${suggestionId}/accept`;
+}
+
+/**
+ * Generate Validation suggestion reject API URL PATH.
+ */
+export function getValidationSuggestionRejectApiPath(workspaceId: string, suggestionId: string): string {
+    return `data/workspace/${workspaceId}/api/v1/ai/validation/suggestions/${suggestionId}/reject`;
+}
+
+/**
+ * Generate Validation bulk accept API URL PATH.
+ */
+export function getValidationBulkAcceptApiPath(workspaceId: string): string {
+    return `data/workspace/${workspaceId}/api/v1/ai/validation/suggestions/bulk-accept`;
+}
+
+/**
+ * Generate Validation bulk reject API URL PATH.
+ */
+export function getValidationBulkRejectApiPath(workspaceId: string): string {
+    return `data/workspace/${workspaceId}/api/v1/ai/validation/suggestions/bulk-reject`;
+}
+
+/**
+ * Generate Validation summary API URL PATH.
+ */
+export function getValidationSummaryApiPath(workspaceId: string): string {
+    return `data/workspace/${workspaceId}/api/v1/ai/validation/summary`;
+}
+
+/**
+ * Generate Validation record suggestions API URL PATH.
+ */
+export function getValidationRecordSuggestionsApiPath(workspaceId: string, recordId: string): string {
+    return `data/workspace/${workspaceId}/api/v1/ai/validation/records/${recordId}/suggestions`;
+}
+
+/**
+ * Generate Validation structure pending count API URL PATH.
+ */
+export function getValidationPendingCountApiPath(workspaceId: string, structureSlug: string): string {
+    return `data/workspace/${workspaceId}/api/v1/ai/validation/structures/${structureSlug}/pending-count`;
+}
+
+/**
+ * Generate Validation batch scan API URL PATH (AI Service).
+ * Note: This routes to the AI service, not the Data service.
+ */
+export function getValidationScanApiPath(workspaceId: string, batchId?: string): string {
+    const basePath = `ai/workspace/${workspaceId}/api/v1/validate/scan`;
+    return batchId ? `${basePath}/${batchId}` : basePath;
+}
+
+// =====================================================
+// Orchestration API Paths
+// =====================================================
+
+/**
+ * Generate Orchestrations API URL PATH.
+ * Routes to the orchestration service.
+ */
+export function getOrchestrationsApiPath(workspaceId: string, orchestrationId?: string): string {
+    const basePath = `orchestration/ws/${workspaceId}/api/v1/orchestrations`;
+    return orchestrationId ? `${basePath}/${orchestrationId}` : basePath;
+}
+
+/**
+ * Generate Orchestration Runs API URL PATH.
+ */
+export function getOrchestrationRunsApiPath(workspaceId: string, orchestrationId: string, runId?: string): string {
+    const basePath = `orchestration/ws/${workspaceId}/api/v1/orchestrations/${orchestrationId}/runs`;
+    return runId ? `${basePath}/${runId}` : basePath;
+}
+
+/**
+ * Generate Orchestration Run Steps API URL PATH.
+ */
+export function getOrchestrationRunStepsApiPath(workspaceId: string, orchestrationId: string, runId: string): string {
+    return `orchestration/ws/${workspaceId}/api/v1/orchestrations/${orchestrationId}/runs/${runId}/steps`;
+}
+
+/**
+ * Generate canonical Orchestration Runs query API URL PATH (CEN-1217).
+ * Backs `POST /orchestration-runs/query`, `/query/test`, and the
+ * `GET /orchestration-runs` URL adapter.
+ */
+export function getOrchestrationRunsCanonicalApiPath(workspaceId: string, suffix?: 'query' | 'query/test'): string {
+    const basePath = `orchestration/ws/${workspaceId}/api/v1/orchestration-runs`;
+    return suffix ? `${basePath}/${suffix}` : basePath;
+}
+
+/**
+ * Generate Allowed Domains API URL PATH.
+ */
+export function getAllowedDomainsApiPath(workspaceId: string, domainId?: string): string {
+    const basePath = `data/workspace/${workspaceId}/api/v1/settings/allowed-domains`;
+    return domainId ? `${basePath}/${domainId}` : basePath;
+}
+
+// =====================================================
+// Webhook Subscription API Paths
+// =====================================================
+
+/**
+ * Generate Webhook Subscriptions API URL PATH.
+ */
+export function getWebhookSubscriptionsApiPath(workspaceId: string, subscriptionId?: string): string {
+    const basePath = `data/workspace/${workspaceId}/api/v1/webhook-subscriptions`;
+    return subscriptionId ? `${basePath}/${subscriptionId}` : basePath;
+}
+
+/**
+ * Generate rotate-secret API URL PATH for a webhook subscription.
+ */
+export function getWebhookSubscriptionRotateSecretApiPath(workspaceId: string, subscriptionId: string): string {
+    return `data/workspace/${workspaceId}/api/v1/webhook-subscriptions/${subscriptionId}/rotate-secret`;
+}
+
+/**
+ * Generate deliveries API URL PATH scoped to a webhook subscription.
+ */
+export function getWebhookSubscriptionDeliveriesApiPath(workspaceId: string, subscriptionId: string, deliveryId?: string): string {
+    const basePath = `data/workspace/${workspaceId}/api/v1/webhook-subscriptions/${subscriptionId}/deliveries`;
+    return deliveryId ? `${basePath}/${deliveryId}` : basePath;
+}
+
+/**
+ * Generate retry API URL PATH for a webhook delivery.
+ * Retry is workspace-scoped (not nested under a subscription) — only the delivery ID is needed.
+ */
+export function getWebhookDeliveryRetryApiPath(workspaceId: string, deliveryId: string): string {
+    return `data/workspace/${workspaceId}/api/v1/webhook-subscriptions/deliveries/${deliveryId}/retry`;
+}
+
+/**
+ * Generate cancel API URL PATH for a webhook delivery retry.
+ * Cancel is workspace-scoped — only the delivery ID is needed.
+ */
+export function getWebhookDeliveryCancelApiPath(workspaceId: string, deliveryId: string): string {
+    return `data/workspace/${workspaceId}/api/v1/webhook-subscriptions/deliveries/${deliveryId}/cancel`;
+}

package/src/internal/queryGuard.ts

@@ -0,0 +1,21 @@
+import type { QueryDefinition } from '../../query-types';
+
+/**
+ * Discriminator for the dual-shape `client.queryRecords(...)` overload.
+ *
+ * Returns `true` if the argument is a canonical `QueryDefinition`. The
+ * marker is **the presence of `resource`** — that field is required by the
+ * canonical contract (`docs/superpowers/specs/2026-04-25-query-foundation-contract.md` §3)
+ * and isn't a legal key in the legacy `QueryRecordOptions` URL-param shape.
+ *
+ * Callers who want to omit `resource` (relying on the first argument to fill
+ * it in) should use `client.records.query(resource, definition)` directly,
+ * which has its own backfill behavior.
+ */
+export function isCanonicalQueryDefinition(arg: any): arg is QueryDefinition {
+    return (
+        arg !== null &&
+        typeof arg === 'object' &&
+        typeof arg.resource === 'string'
+    );
+}