@centrali-io/centrali-sdk 5.5.0 → 6.0.0

package/src/client.ts

@@ -0,0 +1,1507 @@
+import axios, { AxiosError, AxiosInstance, AxiosRequestConfig, AxiosRequestHeaders, AxiosResponse, Method } from 'axios';
+import qs from 'qs';
+
+import { CentraliError, isCentraliError, toCentraliError } from './internal/error';
+import { emitDeprecationWarning } from './internal/deprecation';
+import { fetchClientToken } from './internal/auth';
+import { getApiUrl } from './urls';
+import { isCanonicalQueryDefinition } from './internal/queryGuard';
+
+import {
+    getRecordApiPath,
+    getFileUploadApiPath,
+    getSearchApiPath,
+} from './internal/paths';
+
+import type { CentraliSDKOptions, ApiResponse } from './types/common';
+import type { CheckAuthorizationOptions, AuthorizationResult } from './types/auth';
+import type { DeleteRecordOptions, RecordTtlOptions, GetRecordOptions, QueryRecordOptions } from './types/records';
+import type { SearchOptions, SearchResponse } from './types/search';
+import type { QueryDefinition, QueryResult } from '../query-types';
+
+import { RealtimeManager } from './realtime/manager';
+import { OrchestrationsManager } from './managers/orchestrations';
+import { TriggersManager } from './managers/triggers';
+import { RecordsManager } from './managers/records';
+import { AuditLogManager } from './managers/auditLog';
+import { SmartQueriesManager } from './managers/smartQueries';
+import { AnomalyInsightsManager } from './managers/anomalyInsights';
+import { ValidationManager } from './managers/validation';
+import { AllowedDomainsManager } from './managers/allowedDomains';
+import { StructuresManager } from './managers/structures';
+import { CollectionsManager } from './managers/collections';
+import { ComputeFunctionsManager } from './managers/functions';
+import { FunctionRunsManager } from './managers/functionRuns';
+import { OrchestrationRunsManager } from './managers/orchestrationRuns';
+import { FilesManager } from './managers/files';
+import { WebhookSubscriptionsManager } from './managers/webhookSubscriptions';
+import { QueryManager } from './managers/query';
+
+export class CentraliSDK {
+    private axios: AxiosInstance;
+    private token: string | null = null;
+    private options: CentraliSDKOptions;
+    private _realtime: RealtimeManager | null = null;
+    private _triggers: TriggersManager | null = null;
+    private _records: RecordsManager | null = null;
+    private _auditLog: AuditLogManager | null = null;
+    private _smartQueries: SmartQueriesManager | null = null;
+    private _queryRecordsLegacyWarned: boolean = false;
+    private _anomalyInsights: AnomalyInsightsManager | null = null;
+    private _validation: ValidationManager | null = null;
+    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 _runs: FunctionRunsManager | null = null;
+    private _orchestrationRuns: OrchestrationRunsManager | null = null;
+    private _files: FilesManager | null = null;
+    private _webhookSubscriptions: WebhookSubscriptionsManager | null = null;
+    private _query: QueryManager | null = null;
+    private isRefreshingToken: boolean = false;
+    private tokenRefreshPromise: Promise<string> | null = null;
+
+    constructor(options: CentraliSDKOptions) {
+        this.options = options;
+        this.token = options.token || null;
+
+        // Validate mutually exclusive auth options
+        const authPaths = [
+            options.publishableKey ? 'publishableKey' : null,
+            options.getToken ? 'getToken' : null,
+            (options.clientId || options.clientSecret) ? 'clientId/clientSecret' : null,
+        ].filter(Boolean);
+
+        if (options.publishableKey && authPaths.length > 1) {
+            throw new Error(`Cannot use publishableKey with ${authPaths.filter(p => p !== 'publishableKey').join(', ')}. Use one auth method.`);
+        }
+        if (options.getToken && (options.clientId || options.clientSecret)) {
+            throw new Error('Cannot use getToken with clientId/clientSecret. Use one auth method.');
+        }
+
+        const apiUrl = getApiUrl(options.baseUrl);
+        this.axios = axios.create({
+            baseURL: apiUrl,
+            paramsSerializer: (params: Record<string, any>): string =>
+                    qs.stringify(params, { arrayFormat: "repeat" }),
+            proxy: false,
+            ...options.axiosConfig,
+        });
+
+        // Attach async interceptor to fetch token on first request if needed
+        this.axios.interceptors.request.use(
+            async (config) => {
+                // Auth path 1: Publishable key — send as x-api-key header, no token logic
+                if (this.options.publishableKey) {
+                    config.headers['x-api-key'] = this.options.publishableKey;
+                    return config;
+                }
+
+                // Auth path 2: Dynamic token callback (getToken) — call on each request
+                if (this.options.getToken) {
+                    this.token = await this.options.getToken();
+                    if (this.token) {
+                        config.headers.Authorization = `Bearer ${this.token}`;
+                    }
+                    return config;
+                }
+
+                // Auth path 3: Client credentials — fetch token on first request
+                if (!this.token && this.options.clientId && this.options.clientSecret) {
+                    this.token = await fetchClientToken(
+                        this.options.clientId,
+                        this.options.clientSecret,
+                        this.options.baseUrl
+                    );
+                }
+                if (this.token) {
+                    config.headers.Authorization = `Bearer ${this.token}`;
+                }
+                return config;
+            },
+            (error) => Promise.reject(error)
+        );
+
+        // Response interceptor for automatic token refresh on 401/403
+        this.axios.interceptors.response.use(
+            (response) => response,
+            async (error) => {
+                const originalRequest = error.config;
+
+                // Publishable keys: no retry — scope errors are permanent
+                if (this.options.publishableKey) {
+                    return Promise.reject(error);
+                }
+
+                const isAuthError = error.response?.status === 401 || error.response?.status === 403;
+                const hasNotRetried = !originalRequest._hasRetried;
+
+                // getToken path: retry once with a fresh token on 401
+                if (isAuthError && this.options.getToken && hasNotRetried) {
+                    originalRequest._hasRetried = true;
+                    try {
+                        this.token = await this.options.getToken();
+                        originalRequest.headers.Authorization = `Bearer ${this.token}`;
+                        return this.axios(originalRequest);
+                    } catch (refreshError) {
+                        return Promise.reject(error);
+                    }
+                }
+
+                // Client credentials path: refresh token and retry on 401/403
+                const hasClientCredentials = this.options.clientId && this.options.clientSecret;
+
+                if (isAuthError && hasClientCredentials && hasNotRetried) {
+                    // Mark request as retried to prevent infinite loops
+                    originalRequest._hasRetried = true;
+
+                    try {
+                        // If already refreshing, wait for the existing refresh to complete
+                        if (this.isRefreshingToken && this.tokenRefreshPromise) {
+                            await this.tokenRefreshPromise;
+                        } else {
+                            // Start a new token refresh
+                            this.isRefreshingToken = true;
+                            this.tokenRefreshPromise = fetchClientToken(
+                                this.options.clientId!,
+                                this.options.clientSecret!,
+                                this.options.baseUrl
+                            );
+                            this.token = await this.tokenRefreshPromise;
+                            this.isRefreshingToken = false;
+                            this.tokenRefreshPromise = null;
+                        }
+
+                        // Retry the original request with the new token
+                        originalRequest.headers.Authorization = `Bearer ${this.token}`;
+                        return this.axios(originalRequest);
+                    } catch (refreshError) {
+                        // Token refresh failed, clear state and reject
+                        this.isRefreshingToken = false;
+                        this.tokenRefreshPromise = null;
+                        this.token = null;
+                        return Promise.reject(toCentraliError(refreshError));
+                    }
+                }
+
+                return Promise.reject(toCentraliError(error));
+            }
+        );
+    }
+
+    /**
+     * Realtime namespace for subscribing to SSE events.
+     *
+     * Usage:
+     * ```ts
+     * const sub = client.realtime.subscribe({
+     *   structures: ['order'],
+     *   events: ['record_created', 'record_updated'],
+     *   onEvent: (event) => console.log(event),
+     * });
+     * // Later: sub.unsubscribe();
+     * ```
+     *
+     * IMPORTANT: Initial Sync Pattern
+     * Realtime delivers only new events after connection. For dashboards and lists:
+     * 1. Fetch current records first
+     * 2. Subscribe to realtime
+     * 3. Apply diffs while UI shows the snapshot
+     */
+    public get realtime(): RealtimeManager {
+        if (!this._realtime) {
+            this._realtime = new RealtimeManager(
+                this.options.baseUrl,
+                this.options.workspaceId,
+                () => this.getTokenOrFetch()
+            );
+        }
+        return this._realtime;
+    }
+
+    /**
+     * Get the current token, or fetch one using client credentials if available.
+     * This ensures realtime subscriptions work without needing a prior HTTP request.
+     */
+    private async getTokenOrFetch(): Promise<string | null> {
+        // If token exists, return it
+        if (this.token) {
+            return this.token;
+        }
+        // For client-credentials flow, proactively fetch token if not available
+        if (this.options.clientId && this.options.clientSecret) {
+            this.token = await fetchClientToken(
+                this.options.clientId,
+                this.options.clientSecret,
+                this.options.baseUrl
+            );
+            return this.token;
+        }
+        // No token and no credentials
+        return null;
+    }
+
+    /**
+     * Triggers namespace for invoking and managing function triggers.
+     *
+     * Usage:
+     * ```ts
+     * // Invoke an on-demand trigger
+     * const job = await client.triggers.invoke('trigger-id');
+     *
+     * // Invoke with custom payload
+     * const job = await client.triggers.invoke('trigger-id', {
+     *   payload: { orderId: '12345' }
+     * });
+     *
+     * // Get trigger details
+     * const trigger = await client.triggers.get('trigger-id');
+     *
+     * // List all triggers
+     * const triggers = await client.triggers.list();
+     * ```
+     */
+    public get triggers(): TriggersManager {
+        if (!this._triggers) {
+            this._triggers = new TriggersManager(
+                this.options.workspaceId,
+                this.request.bind(this)
+            );
+        }
+        return this._triggers;
+    }
+
+    /**
+     * Records namespace — canonical query surface for records (CEN-1194).
+     *
+     * Three methods, one engine, one envelope:
+     * - `records.query(resource, definition)` — POST `/records/query` with a
+     *   full `QueryDefinition` (boolean trees, `select`, `text`, `include`).
+     * - `records.list(resource, urlOpts?)` — GET adapter for simple URL-param
+     *   queries. Bookmarkable; cannot express nested booleans.
+     * - `records.search(resource, text, opts?)` — sugar over `query({ text })`.
+     *
+     * @example
+     * ```ts
+     * // Boolean tree with sort + projection
+     * const orders = await client.records.query<Order>('orders', {
+     *   resource: 'orders',
+     *   where: {
+     *     and: [
+     *       { 'data.status': { eq: 'paid' } },
+     *       { 'data.amount': { gte: 100 } }
+     *     ]
+     *   },
+     *   sort: [{ field: 'createdAt', direction: 'desc' }],
+     *   page: { limit: 50 },
+     *   select: { fields: ['id', 'data.amount', 'data.customer'] }
+     * });
+     *
+     * // Simple GET
+     * const recent = await client.records.list<Order>('orders', {
+     *   'data.status': 'paid',
+     *   sort: '-createdAt',
+     * });
+     *
+     * // Text search
+     * const matches = await client.records.search<Order>('orders', 'urgent');
+     * ```
+     */
+    public get records(): RecordsManager {
+        if (!this._records) {
+            this._records = new RecordsManager(
+                this.options.workspaceId,
+                this.request.bind(this)
+            );
+        }
+        return this._records;
+    }
+
+    /**
+     * Query namespace — canonical query primitives bundled into the SDK
+     * (CEN-1202). Validate, translate-from-legacy, and parse URL-style
+     * queries locally without a server roundtrip. Same source as the
+     * server-side validator, so behavior matches byte-for-byte.
+     *
+     * @example
+     * ```ts
+     * const r = client.query.validate({ resource: 'orders', page: { limit: 50 } });
+     * if (!r.ok) console.error(r.errors);
+     * ```
+     */
+    public get query(): QueryManager {
+        if (!this._query) {
+            this._query = new QueryManager();
+        }
+        return this._query;
+    }
+
+    /**
+     * Audit Log namespace — canonical query surface for the workspace audit
+     * log (CEN-1215, Phase 3 of the query foundation).
+     *
+     * Routes through `POST /workspace/<ws>/api/v1/audit/query` on the
+     * workspace service. Same `QueryDefinition` vocabulary as
+     * {@link CentraliSDK.records | records} so callers learn one shape and
+     * reuse it.
+     *
+     * @example
+     * ```ts
+     * // Per-resource 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 },
+     * });
+     * ```
+     */
+    public get auditLog(): AuditLogManager {
+        if (!this._auditLog) {
+            this._auditLog = new AuditLogManager(
+                this.options.workspaceId,
+                this.request.bind(this)
+            );
+        }
+        return this._auditLog;
+    }
+
+    /**
+     * Saved Queries namespace — list, execute, create, update, and delete
+     * saved (formerly "smart") queries. Routes through the canonical
+     * `/saved-queries/*` endpoints (Phase 4 of the query foundation,
+     * CEN-1198). The data service dual-mounts the deprecated `/smart-queries`
+     * alias for the deprecation window.
+     *
+     * Usage:
+     * ```ts
+     * // List all saved queries in workspace
+     * const allQueries = await client.savedQueries.listAll();
+     *
+     * // List saved queries for a structure
+     * const queries = await client.savedQueries.list('employee');
+     *
+     * // Get a saved query by name
+     * const query = await client.savedQueries.getByName('employee', 'Active Employees');
+     *
+     * // Execute a saved query
+     * const results = await client.savedQueries.execute('employee', query.data.id);
+     * console.log('Found:', results.data.length, 'records');
+     * ```
+     */
+    public get savedQueries(): SmartQueriesManager {
+        if (!this._smartQueries) {
+            this._smartQueries = new SmartQueriesManager(
+                this.options.workspaceId,
+                this.request.bind(this)
+            );
+        }
+        return this._smartQueries;
+    }
+
+    /**
+     * @deprecated Use `client.savedQueries` instead. The "smart queries"
+     * surface was renamed to "saved queries" in Phase 4 of the query
+     * foundation (CEN-1198). This getter is a deprecated alias and will be
+     * removed in a future major SDK release.
+     */
+    public get smartQueries(): SmartQueriesManager {
+        emitDeprecationWarning('client.smartQueries is deprecated. Use client.savedQueries instead.');
+        if (!this._smartQueriesAlias) {
+            this._smartQueriesAlias = new SmartQueriesManager(
+                this.options.workspaceId,
+                this.requestWithDeprecationHeader('smartQueries'),
+            );
+        }
+        return this._smartQueriesAlias;
+    }
+    private _smartQueriesAlias?: SmartQueriesManager;
+
+    /**
+     * Anomaly Insights namespace for querying and managing AI-generated insights.
+     *
+     * Usage:
+     * ```ts
+     * // List all active critical insights
+     * const insights = await client.anomalyInsights.list({
+     *   status: 'active',
+     *   severity: 'critical'
+     * });
+     *
+     * // Get insights for a specific structure
+     * const orderInsights = await client.anomalyInsights.listByStructure('orders');
+     *
+     * // Get insight summary
+     * const summary = await client.anomalyInsights.getSummary();
+     * console.log('Critical:', summary.data.bySeverity.critical);
+     *
+     * // Acknowledge an insight
+     * await client.anomalyInsights.acknowledge('insight-id');
+     *
+     * // Dismiss an insight
+     * await client.anomalyInsights.dismiss('insight-id');
+     * ```
+     */
+    public get anomalyInsights(): AnomalyInsightsManager {
+        if (!this._anomalyInsights) {
+            this._anomalyInsights = new AnomalyInsightsManager(
+                this.options.workspaceId,
+                this.request.bind(this)
+            );
+        }
+        return this._anomalyInsights;
+    }
+
+    /**
+     * Validation namespace for AI-powered data quality validation.
+     *
+     * Features:
+     * - Trigger batch validation scans on structures
+     * - List and manage validation suggestions (typos, format issues, duplicates)
+     * - Accept or reject suggestions to fix data
+     *
+     * Usage:
+     * ```ts
+     * // Trigger a batch scan
+     * const batch = await client.validation.triggerScan('orders');
+     *
+     * // Wait for completion
+     * const result = await client.validation.waitForScan(batch.data.batchId);
+     *
+     * // List pending suggestions
+     * const suggestions = await client.validation.listSuggestions({ status: 'pending' });
+     *
+     * // Accept a suggestion (applies the fix)
+     * await client.validation.accept('suggestion-id');
+     * ```
+     */
+    public get validation(): ValidationManager {
+        if (!this._validation) {
+            this._validation = new ValidationManager(
+                this.options.workspaceId,
+                this.request.bind(this)
+            );
+        }
+        return this._validation;
+    }
+
+    /**
+     * Orchestrations namespace for managing multi-step workflows.
+     *
+     * Orchestrations chain compute functions together with conditional logic,
+     * delays, and decision branches to automate complex business processes.
+     *
+     * Usage:
+     * ```ts
+     * // List all orchestrations
+     * const orchestrations = await client.orchestrations.list();
+     *
+     * // Trigger an on-demand orchestration
+     * const run = await client.orchestrations.trigger('orch-id', {
+     *   input: { orderId: '12345' }
+     * });
+     *
+     * // Get run status
+     * const runStatus = await client.orchestrations.getRun('orch-id', run.data.id);
+     *
+     * // Create a new orchestration
+     * const orch = await client.orchestrations.create({
+     *   slug: 'order-processing',
+     *   name: 'Order Processing',
+     *   trigger: { type: 'on-demand' },
+     *   steps: [
+     *     { id: 'validate', type: 'compute', functionId: 'func_validate', onSuccess: { nextStepId: 'process' } },
+     *     { id: 'process', type: 'compute', functionId: 'func_process' }
+     *   ]
+     * });
+     * ```
+     */
+    public get orchestrations(): OrchestrationsManager {
+        if (!this._orchestrations) {
+            this._orchestrations = new OrchestrationsManager(
+                this.options.workspaceId,
+                this.request.bind(this)
+            );
+        }
+        return this._orchestrations;
+    }
+
+    /**
+     * Allowed Domains namespace for managing compute function external call domains.
+     *
+     * Usage:
+     * ```ts
+     * // List all allowed domains
+     * const domains = await client.allowedDomains.list();
+     *
+     * // Add a new domain
+     * const domain = await client.allowedDomains.add({ domain: 'api.stripe.com' });
+     *
+     * // Remove a domain
+     * await client.allowedDomains.remove('domain-id');
+     * ```
+     */
+    public get allowedDomains(): AllowedDomainsManager {
+        if (!this._allowedDomains) {
+            this._allowedDomains = new AllowedDomainsManager(
+                this.options.workspaceId,
+                this.request.bind(this)
+            );
+        }
+        return this._allowedDomains;
+    }
+
+    /**
+     * Structures namespace for managing data structures (schemas).
+     * Provides CRUD operations and validation for structure definitions.
+     *
+     * Usage:
+     * ```ts
+     * // List all structures
+     * const structures = await client.structures.list();
+     *
+     * // Create a structure
+     * const structure = await client.structures.create({
+     *   name: 'Orders',
+     *   slug: 'orders',
+     *   properties: [{ name: 'title', type: 'string', required: true }]
+     * });
+     *
+     * // Validate before creating
+     * const result = await client.structures.validate({ slug: 'orders' });
+     * ```
+     */
+    public get structures(): StructuresManager {
+        emitDeprecationWarning('client.structures is deprecated. Use client.collections instead.');
+        if (!this._structures) {
+            this._structures = new StructuresManager(
+                this.options.workspaceId,
+                this.requestWithDeprecationHeader('structures'),
+            );
+        }
+        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.
+     *
+     * Usage:
+     * ```ts
+     * // List all functions
+     * const fns = await client.functions.list();
+     *
+     * // Create a function
+     * const fn = await client.functions.create({
+     *   name: 'Process Order',
+     *   code: 'async function run() { return { ok: true }; }'
+     * });
+     *
+     * // Test execute without saving
+     * const result = await client.functions.testExecute({
+     *   code: 'async function run() { return executionParams; }',
+     *   params: { test: true }
+     * });
+     * ```
+     */
+    public get functions(): ComputeFunctionsManager {
+        if (!this._functions) {
+            this._functions = new ComputeFunctionsManager(
+                this.options.workspaceId,
+                this.request.bind(this)
+            );
+        }
+        return this._functions;
+    }
+
+    /**
+     * Function Runs namespace — query function execution history. Canonical
+     * accessor (CEN-1227); pairs with `client.orchestrationRuns` for
+     * orchestration runs (CEN-1217).
+     *
+     * Usage:
+     * ```ts
+     * // Get a specific run
+     * const run = await client.functionRuns.get('run-id');
+     *
+     * // List runs for a trigger
+     * const runs = await client.functionRuns.listByTrigger('trigger-id');
+     *
+     * // List failed runs for a compute definition
+     * const failed = await client.functionRuns.listByFunction('fn-id', {
+     *   status: 'failure'
+     * });
+     *
+     * // Canonical query surface
+     * const failures = await client.functionRuns.query({
+     *   where: { and: [{ status: { eq: 'failure' } }] },
+     *   limit: 50
+     * });
+     * ```
+     */
+    public get functionRuns(): FunctionRunsManager {
+        if (!this._runs) {
+            this._runs = new FunctionRunsManager(
+                this.options.workspaceId,
+                this.request.bind(this)
+            );
+        }
+        return this._runs;
+    }
+
+    /**
+     * Orchestration Runs namespace — canonical query surface for orchestration
+     * run history (CEN-1217 / Phase 3).
+     *
+     * Per-orchestration trigger / list / get-by-id helpers stay on
+     * `client.orchestrations.{trigger, listRuns, getRun, getRunSteps}`. Use
+     * this namespace when you want the canonical `QueryDefinition` shape
+     * (nested boolean trees, `select`, paging) or workspace-wide queries.
+     *
+     * Usage:
+     * ```ts
+     * // Recent failed runs across the workspace
+     * const failures = await client.orchestrationRuns.query({
+     *   resource: 'orchestration-runs',
+     *   where: { and: [{ status: { eq: 'failed' } }] },
+     *   sort: [{ field: 'startedAt', direction: 'desc' }],
+     *   page: { limit: 50 },
+     * });
+     *
+     * // Authoring dry-run from a query builder UI
+     * const plan = await client.orchestrationRuns.test({
+     *   resource: 'orchestration-runs',
+     *   where: { and: [{ orchestrationId: { eq: 'orch-123' } }] },
+     * });
+     * ```
+     */
+    public get orchestrationRuns(): OrchestrationRunsManager {
+        if (!this._orchestrationRuns) {
+            this._orchestrationRuns = new OrchestrationRunsManager(
+                this.options.workspaceId,
+                this.request.bind(this)
+            );
+        }
+        return this._orchestrationRuns;
+    }
+
+    /**
+     * Files namespace — canonical query surface for files (CEN-1218 /
+     * Phase 3). Pairs with the existing top-level helpers
+     * (`client.uploadFile`, `client.getFileRenderUrl`,
+     * `client.createFolder`, …) — those stay where they are. Use this
+     * namespace when you want the canonical `QueryDefinition` shape
+     * (nested boolean trees, projection, paging, range/array operators
+     * on `tags`).
+     *
+     * Usage:
+     * ```ts
+     * // Recent images
+     * const images = await client.files.query({
+     *   resource: 'files',
+     *   where: { fileType: { eq: 'image' } },
+     *   sort: [{ field: 'createdAt', direction: 'desc' }],
+     *   page: { limit: 50 },
+     * });
+     *
+     * // Authoring dry-run
+     * const plan = await client.files.test({
+     *   resource: 'files',
+     *   where: { folderId: { eq: 'folder-uuid' } },
+     * });
+     * ```
+     */
+    public get files(): FilesManager {
+        if (!this._files) {
+            this._files = new FilesManager(
+                this.options.workspaceId,
+                this.request.bind(this)
+            );
+        }
+        return this._files;
+    }
+
+    /**
+     * @deprecated Use `client.functionRuns` instead. Renamed in CEN-1227 ahead
+     * of `client.orchestrationRuns` (CEN-1217), at which point `client.runs`
+     * would be ambiguous (function runs vs. orchestration runs). This getter
+     * is a deprecated alias and will be removed in a future major SDK release.
+     */
+    public get runs(): FunctionRunsManager {
+        emitDeprecationWarning('client.runs is deprecated. Use client.functionRuns instead.');
+        if (!this._runsAlias) {
+            const Mgr = FunctionRunsManager;
+            this._runsAlias = new Mgr(
+                this.options.workspaceId,
+                this.requestWithDeprecationHeader('runs'),
+            );
+        }
+        return this._runsAlias;
+    }
+    private _runsAlias?: FunctionRunsManager;
+
+    /**
+     * Webhook subscriptions namespace for outbound webhooks — create, update,
+     * rotate signing secrets, inspect delivery history, and replay/cancel
+     * individual deliveries.
+     *
+     * Usage:
+     * ```ts
+     * // Create a subscription (capture secret immediately — not returned on reads)
+     * const sub = await centrali.webhookSubscriptions.create({
+     *   name: 'Order notifications',
+     *   url: 'https://api.example.com/hooks/centrali',
+     *   events: [RecordEvents.CREATED, RecordEvents.UPDATED],
+     *   recordSlugs: ['orders'],
+     * });
+     *
+     * // Rotate the signing secret (immediate cutover)
+     * const rotated = await centrali.webhookSubscriptions.rotateSecret(sub.data.id);
+     *
+     * // Inspect deliveries
+     * const deliveries = await centrali.webhookSubscriptions.deliveries.list(sub.data.id, {
+     *   status: 'failed'
+     * });
+     *
+     * // Replay a failed delivery
+     * await centrali.webhookSubscriptions.deliveries.retry(deliveries.data[0].id);
+     * ```
+     */
+    public get webhookSubscriptions(): WebhookSubscriptionsManager {
+        if (!this._webhookSubscriptions) {
+            this._webhookSubscriptions = new WebhookSubscriptionsManager(
+                this.options.workspaceId,
+                this.request.bind(this)
+            );
+        }
+        return this._webhookSubscriptions;
+    }
+
+    /**
+     * Manually set or update the bearer token for subsequent requests.
+     */
+    public setToken(token: string): void {
+        this.token = token;
+    }
+
+    /**
+     * Fetch Service Account token using Client Credentials flow.
+     */
+    public async fetchServiceAccountToken(): Promise<string> {
+        if (!this.options.clientId || !this.options.clientSecret) {
+            throw new Error('Client ID and Client Secret are required to fetch Service Account token.');
+        }
+       const token = await fetchClientToken(
+            this.options.clientId,
+            this.options.clientSecret,
+            this.options.baseUrl
+        );
+        return token;
+    }
+
+    /**
+     * Build a manager-shaped request callback that tags every outbound call
+     * with `X-Centrali-Deprecated-Method`. Used by `@deprecated` SDK aliases
+     * (`client.smartQueries`, `client.structures`, `client.runs`) so the
+     * existing per-route deprecation counter on the data/workspace services
+     * (CEN-1196) can attribute hits back to which SDK surface the caller used,
+     * even when the underlying HTTP route is canonical and doesn't fire its
+     * own deprecation telemetry.
+     */
+    private requestWithDeprecationHeader(methodName: string) {
+        return <T>(
+            method: Method,
+            path: string,
+            data?: any,
+            queryParams?: Record<string, any>,
+        ): Promise<ApiResponse<T>> => {
+            return this.request<T>(method, path, data, queryParams, {
+                headers: { 'X-Centrali-Deprecated-Method': methodName },
+            });
+        };
+    }
+
+    /**
+     * Perform an HTTP request.
+     */
+    private async request<T>(
+        method: Method,
+        path: string,
+        data?: any,
+        queryParams?: Record<string, any>,
+        config?: AxiosRequestConfig
+    ): Promise<ApiResponse<T>> {
+        const resp = await this.axios.request<ApiResponse<T>>({
+            method,
+            url: path,
+            data,
+            params: queryParams,
+            ...config,
+        });
+
+        // 🔧 Normalize responses to always return { data: T, ... } format
+        // Handle primitives (strings, numbers, etc.)
+        if (typeof resp.data !== 'object' || resp.data === null) {
+            return { data: resp.data as T };
+        }
+        // Handle arrays (which are objects but should be wrapped in data property)
+        if (Array.isArray(resp.data)) {
+            return { data: resp.data as T };
+        }
+        // Handle { result } responses (smart queries and some other endpoints)
+        if ('result' in resp.data && !('data' in resp.data)) {
+            return { data: (resp.data as any).result as T };
+        }
+        // Handle objects that don't have a data property (legacy endpoints)
+        if (!('data' in resp.data)) {
+            return { data: resp.data as T };
+        }
+        return resp.data;
+    }
+
+    // ------------------ Data API Methods ------------------
+
+    /** Create a new record in a given recordSlug. */
+    public createRecord<T = any>(
+        recordSlug: string,
+        record: Record<string, any>,
+        options?: RecordTtlOptions
+    ): Promise<ApiResponse<T>> {
+        const path = getRecordApiPath(this.options.workspaceId, recordSlug);
+        const queryParams: Record<string, string> = {};
+        if (options?.ttlSeconds) queryParams.ttlSeconds = String(options.ttlSeconds);
+        if (options?.expiresAt) queryParams.expiresAt = options.expiresAt;
+        return this.request('POST', path, { ...record }, Object.keys(queryParams).length > 0 ? queryParams : undefined);
+    }
+
+    /** Get the token used for authentication. */
+    public getToken(): string | null {
+        return this.token;
+    }
+
+
+    /**
+     * Retrieve a record by ID.
+     *
+     * @param recordSlug - The structure's record slug
+     * @param id - The record ID
+     * @param options - Optional parameters including expand for reference fields
+     *
+     * @example
+     * // Basic fetch
+     * const order = await centrali.getRecord('Order', 'order-123');
+     *
+     * // With expanded references
+     * const order = await centrali.getRecord('Order', 'order-123', {
+     *   expand: 'customer,items'
+     * });
+     * // Access expanded data: order.data.data._expanded.customer
+     */
+    public getRecord<T = any>(
+        recordSlug: string,
+        id: string,
+        options?: GetRecordOptions
+    ): Promise<ApiResponse<T>> {
+        const path = getRecordApiPath(this.options.workspaceId, recordSlug, id);
+        return this.request('GET', path, null, options);
+    }
+
+    /**
+     * Query records with filters, pagination, sorting, and reference expansion.
+     *
+     * IMPORTANT: Filters are passed at the TOP LEVEL, not nested under 'filter'.
+     * Use 'data.' prefix for custom fields and bracket notation for operators.
+     *
+     * @param recordSlug - The structure's record slug
+     * @param queryParams - Query parameters (filters at top level, plus sort, pagination, expand)
+     *
+     * @example
+     * // Simple equality filter
+     * const activeProducts = await centrali.queryRecords('Product', {
+     *   'data.status': 'active',
+     *   sort: '-createdAt',
+     *   page: 1,
+     *   pageSize: 10
+     * });
+     *
+     * // Filter with operators (bracket notation)
+     * const products = await centrali.queryRecords('Product', {
+     *   'data.inStock': true,
+     *   'data.price[lte]': 100,
+     *   sort: '-createdAt',
+     *   pageSize: 10
+     * });
+     *
+     * // Multiple values with 'in' operator (comma-separated string)
+     * const orders = await centrali.queryRecords('Order', {
+     *   'data.status[in]': 'pending,processing',
+     *   expand: 'customer,items'
+     * });
+     * // Access expanded data: orders.data[0].data._expanded.customer
+     *
+     * // Range filters
+     * const customers = await centrali.queryRecords('Customer', {
+     *   'data.age[gte]': 18,
+     *   'data.age[lte]': 65,
+     *   'data.verified': true
+     * });
+     *
+     * // Filter with 'ne' (not equal)
+     * const availableItems = await centrali.queryRecords('Product', {
+     *   'data.status[ne]': 'discontinued',
+     *   pageSize: 100
+     * });
+     */
+    /**
+     * Canonical query (CEN-1194). When called with a `QueryDefinition` body,
+     * routes to `POST /records/query` and returns canonical `QueryResult<T>`.
+     *
+     * @example
+     * const result = await centrali.queryRecords<Order>('orders', {
+     *   resource: 'orders',
+     *   where: { 'data.status': { eq: 'paid' } },
+     *   page: { limit: 50 }
+     * });
+     * console.log(result.data, result.meta.hasMore);
+     */
+    public queryRecords<T = any>(
+        resource: string,
+        definition: QueryDefinition
+    ): Promise<QueryResult<T>>;
+    /**
+     * Legacy GET-adapter form. Pass `QueryRecordOptions` (URL-param style with
+     * `data.field[op]` keys, `sort: '-createdAt'`, `pageSize`, etc.) and the
+     * call routes to `GET /records/slug/:rs`.
+     *
+     * @deprecated Since 5.5.0. Prefer the canonical overload above (pass a
+     *   `QueryDefinition`) or {@link CentraliSDK.records | client.records.list()}
+     *   for the GET adapter explicitly. The legacy form keeps working — server-side
+     *   it already routes through the canonical engine (CEN-1181 WS3) — but the
+     *   client-side type story diverges from the canonical surface. Emits a
+     *   one-shot `console.warn` per client.
+     */
+    public queryRecords<T = any>(
+        recordSlug: string,
+        queryParams?: QueryRecordOptions
+    ): Promise<ApiResponse<T>>;
+    public queryRecords<T = any>(
+        resourceOrSlug: string,
+        arg2?: QueryDefinition | QueryRecordOptions
+    ): Promise<QueryResult<T>> | Promise<ApiResponse<T>> {
+        if (isCanonicalQueryDefinition(arg2)) {
+            return this.records.query<T>(resourceOrSlug, arg2);
+        }
+        if (!this._queryRecordsLegacyWarned) {
+            this._queryRecordsLegacyWarned = true;
+            // eslint-disable-next-line no-console
+            console.warn(
+                '[centrali-sdk] `client.queryRecords(slug, urlOpts)` (legacy URL-param form) is deprecated — pass a canonical `QueryDefinition` (`{ resource, where, sort, page, … }`) for `POST /records/query`, or use `client.records.list(resource, urlOpts)` for the GET adapter explicitly.'
+            );
+        }
+        const path = getRecordApiPath(this.options.workspaceId, resourceOrSlug);
+        return this.request<T>('GET', path, null, arg2);
+    }
+
+    /** Get records by Ids. */
+    public getRecordsByIds<T = any>(
+        recordSlug: string,
+        ids: string[]
+    ): Promise<ApiResponse<T[]>> {
+        const path = getRecordApiPath(this.options.workspaceId, recordSlug) + '/bulk/get';
+        return this.request('POST', path, { ids });
+    }
+
+    /** Update an existing record by ID. */
+    public updateRecord<T = any>(
+        recordSlug: string,
+        id: string,
+        updates: Record<string, any>,
+        options?: RecordTtlOptions
+    ): Promise<ApiResponse<T>> {
+        const path = getRecordApiPath(this.options.workspaceId, recordSlug, id);
+        const queryParams: Record<string, string> = {};
+        if (options?.ttlSeconds) queryParams.ttlSeconds = String(options.ttlSeconds);
+        if (options?.expiresAt) queryParams.expiresAt = options.expiresAt;
+        if (options?.clearTtl) queryParams.clearTtl = 'true';
+        return this.request('PUT', path, { ...updates }, Object.keys(queryParams).length > 0 ? queryParams : undefined);
+    }
+
+    /**
+     * Upsert a record: find by match fields, update if exists, create if not.
+     * Uses advisory locking for atomicity — safe for concurrent calls.
+     *
+     * @param recordSlug - The structure's record slug
+     * @param options - { match: key-value pairs to find existing record, data: full record data }
+     * @returns Response where result.data is the record and result.operation indicates create/update
+     *
+     * @example
+     * const result = await client.upsertRecord('HourlyRollup', {
+     *   match: { metricKey: 'pageviews', bucketHour: '2025-01-01T10:00' },
+     *   data: { metricKey: 'pageviews', bucketHour: '2025-01-01T10:00', count: 42 },
+     * });
+     * // result.data → the record
+     * // result.operation → 'created' or 'updated'
+     */
+    public upsertRecord<T = any>(
+        recordSlug: string,
+        options: { match: Record<string, any>; data: Record<string, any> }
+    ): Promise<ApiResponse<T> & { operation: 'created' | 'updated' }> {
+        const path = getRecordApiPath(this.options.workspaceId, recordSlug) + '/upsert';
+        return this.request('POST', path, { match: options.match, data: options.data }) as Promise<ApiResponse<T> & { operation: 'created' | 'updated' }>;
+    }
+
+    /** Delete a record by ID (soft delete by default, can be restored). */
+    public deleteRecord(
+        recordSlug: string,
+        id: string,
+        options?: DeleteRecordOptions
+    ): Promise<ApiResponse<null>> {
+        const path = getRecordApiPath(this.options.workspaceId, recordSlug, id);
+        const queryParams = options?.hard ? { hard: 'true' } : undefined;
+        return this.request('DELETE', path, null, queryParams);
+    }
+
+    /** Restore a soft-deleted record by ID. */
+    public restoreRecord(
+        recordSlug: string,
+        id: string
+    ): Promise<ApiResponse<null>> {
+        const path = getRecordApiPath(this.options.workspaceId, recordSlug, id) + '/restore';
+        return this.request('POST', path);
+    }
+
+    // ------------------ Secrets API Methods ------------------
+
+    /**
+     * Reveal plaintext values of secret fields for a record.
+     * Requires secrets:reveal permission.
+     *
+     * @param recordSlug - The structure's record slug
+     * @param id - The record ID
+     * @param fields - Optional array of specific secret field names to reveal
+     * @returns Object with field names as keys and plaintext secret values
+     *
+     * @example
+     * ```ts
+     * // Reveal all secrets
+     * const result = await client.revealSecrets('users', 'record-123');
+     * console.log(result.data.revealed.apiKey); // "sk_live_..."
+     *
+     * // Reveal specific fields
+     * const result = await client.revealSecrets('users', 'record-123', ['apiKey']);
+     * ```
+     */
+    public revealSecrets(
+        recordSlug: string,
+        id: string,
+        fields?: string[]
+    ): Promise<ApiResponse<{ revealed: Record<string, any> }>> {
+        const path = getRecordApiPath(this.options.workspaceId, recordSlug, id) + '/secrets/reveal';
+        return this.request('POST', path, fields ? { fields } : {});
+    }
+
+    /**
+     * Compare a candidate value against a secret field without revealing the stored secret.
+     * Requires secrets:compare permission.
+     *
+     * @param recordSlug - The structure's record slug
+     * @param id - The record ID
+     * @param field - The secret field name to compare against
+     * @param value - The candidate value to compare
+     * @returns Boolean indicating if the values match
+     *
+     * @example
+     * ```ts
+     * const result = await client.compareSecret('users', 'record-123', 'apiKey', 'sk_live_test');
+     * if (result.data.matches) {
+     *   console.log('API key is valid');
+     * }
+     * ```
+     */
+    public compareSecret(
+        recordSlug: string,
+        id: string,
+        field: string,
+        value: string
+    ): Promise<ApiResponse<{ matches: boolean }>> {
+        const path = getRecordApiPath(this.options.workspaceId, recordSlug, id) + '/secrets/compare';
+        return this.request('POST', path, { field, value });
+    }
+
+    // ------------------ Storage API Methods ------------------
+
+    /**
+     * Upload a file to the storage service.
+     *
+     * @param file - The file to upload
+     * @param location - Target folder path (e.g., '/root/shared/images'). Defaults to '/root/shared' if not specified.
+     *                   /root/shared always exists. For custom subfolders, create them first with createFolder().
+     * @param isPublic - If true, the file will be publicly accessible without authentication. Defaults to false.
+     * @returns The file URL or render ID
+     *
+     * @example
+     * ```ts
+     * // Upload to default location (/root/shared)
+     * const result = await client.uploadFile(file);
+     *
+     * // Upload to specific folder
+     * const result = await client.uploadFile(file, '/root/shared/images');
+     *
+     * // Upload as public file
+     * const result = await client.uploadFile(file, '/root/shared/public', true);
+     * ```
+     */
+    public async uploadFile(
+        file: File,
+        location?: string,
+        isPublic: boolean = false
+    ): Promise<ApiResponse<string>> {
+        const path = getFileUploadApiPath(this.options.workspaceId);
+        const formData = new FormData();
+        const fileName = this.options.workspaceId + Date.now() + file.name;
+
+        formData.append('file', file);
+        formData.append('fileName', fileName);
+        formData.append('isPublic', isPublic ? 'true' : 'false');
+
+        // Only append location if specified; backend defaults to /root/shared
+        if (location) {
+            formData.append('location', location);
+        }
+
+        return this.request<string>('POST', path, formData, undefined, {
+            headers: {
+                'Content-Type': 'multipart/form-data',
+            },
+        });
+    }
+
+    // ------------------ Folder API Methods ------------------
+
+    /**
+     * Create a folder in the storage service.
+     * Use this to create subfolders under /root/shared (which always exists).
+     *
+     * @param name - The folder name (e.g., 'logos', 'avatars')
+     * @param location - Parent folder path (e.g., '/root/shared'). Defaults to '/root/shared'.
+     * @returns The created folder object
+     *
+     * @example
+     * ```ts
+     * // Create a folder under /root/shared
+     * const folder = await client.createFolder('logos', '/root/shared');
+     * // Result: folder at /root/shared/logos
+     *
+     * // Then upload to it
+     * const { data: renderId } = await client.uploadFile(file, '/root/shared/logos', true);
+     * ```
+     */
+    public async createFolder(
+        name: string,
+        location: string = '/root/shared'
+    ): Promise<ApiResponse<any>> {
+        const path = `storage/ws/${this.options.workspaceId}/api/v1/folders`;
+        return this.request<any>('POST', path, { name, location });
+    }
+
+    /**
+     * List folders in the workspace, optionally filtered by parent location.
+     *
+     * @param location - Parent folder path to list contents of (e.g., '/root/shared'). If omitted, lists top-level folders.
+     * @returns Array of folder objects
+     *
+     * @example
+     * ```ts
+     * // List all folders under /root/shared
+     * const folders = await client.listFolders('/root/shared');
+     *
+     * // Check if a folder exists before uploading
+     * const folders = await client.listFolders('/root/shared');
+     * const hasLogos = folders.data.some(f => f.name === 'logos');
+     * if (!hasLogos) {
+     *     await client.createFolder('logos', '/root/shared');
+     * }
+     * ```
+     */
+    public async listFolders(location?: string): Promise<ApiResponse<any[]>> {
+        const path = `storage/ws/${this.options.workspaceId}/api/v1/folders`;
+        const params = location ? { location } : undefined;
+        return this.request<any[]>('GET', path, null, params);
+    }
+
+    /**
+     * Get a specific folder by ID.
+     *
+     * @param folderId - The folder ID (UUID)
+     * @returns The folder object
+     */
+    public async getFolder(folderId: string): Promise<ApiResponse<any>> {
+        const path = `storage/ws/${this.options.workspaceId}/api/v1/folders/${folderId}`;
+        return this.request<any>('GET', path);
+    }
+
+    /**
+     * List sub-folders within a specific folder.
+     *
+     * @param folderId - The parent folder ID (UUID)
+     * @returns Array of sub-folder objects
+     */
+    public async listSubFolders(folderId: string): Promise<ApiResponse<any[]>> {
+        const path = `storage/ws/${this.options.workspaceId}/api/v1/folders/${folderId}/sub-folders`;
+        return this.request<any[]>('GET', path);
+    }
+
+    /**
+     * Delete a folder by ID. System folders (/root, /root/shared, /root/users) cannot be deleted.
+     *
+     * @param folderId - The folder ID (UUID) to delete
+     */
+    public async deleteFolder(folderId: string): Promise<ApiResponse<void>> {
+        const path = `storage/ws/${this.options.workspaceId}/api/v1/folders/${folderId}`;
+        return this.request<void>('DELETE', path);
+    }
+
+    // ------------------ File Render/Download URL Methods ------------------
+
+    /**
+     * Get the render URL for a file. Use this URL to display files inline (e.g., images in img tags).
+     * Supports optional image transformation parameters.
+     *
+     * @param renderId - The render ID returned from uploadFile()
+     * @param options - Optional image transformation parameters
+     * @returns The full render URL
+     *
+     * @example
+     * ```ts
+     * // Basic render URL
+     * const url = client.getFileRenderUrl('abc123');
+     * // => "https://api.centrali.io/storage/ws/my-workspace/api/v1/render/abc123"
+     *
+     * // With image transformations
+     * const thumbUrl = client.getFileRenderUrl('abc123', { width: 200 });
+     * const compressedUrl = client.getFileRenderUrl('abc123', { width: 800, quality: 60, format: 'webp' });
+     * ```
+     */
+    public getFileRenderUrl(
+        renderId: string,
+        options?: {
+            width?: number;
+            height?: number;
+            quality?: number;
+            format?: 'jpeg' | 'png' | 'webp';
+        }
+    ): string {
+        const apiUrl = getApiUrl(this.options.baseUrl);
+        const baseUrl = `${apiUrl}/storage/ws/${this.options.workspaceId}/api/v1/render/${renderId}`;
+
+        if (!options) {
+            return baseUrl;
+        }
+
+        const params = new URLSearchParams();
+        if (options.width) params.append('width', String(options.width));
+        if (options.height) params.append('height', String(options.height));
+        if (options.quality) params.append('quality', String(options.quality));
+        if (options.format) params.append('format', options.format);
+
+        const queryString = params.toString();
+        return queryString ? `${baseUrl}?${queryString}` : baseUrl;
+    }
+
+    /**
+     * Get the download URL for a file. Use this URL to download files as attachments.
+     *
+     * @param renderId - The render ID returned from uploadFile()
+     * @returns The full download URL
+     *
+     * @example
+     * ```ts
+     * const downloadUrl = client.getFileDownloadUrl('abc123');
+     * // => "https://api.centrali.io/storage/ws/my-workspace/api/v1/download/abc123"
+     * ```
+     */
+    public getFileDownloadUrl(renderId: string): string {
+        const apiUrl = getApiUrl(this.options.baseUrl);
+        return `${apiUrl}/storage/ws/${this.options.workspaceId}/api/v1/download/${renderId}`;
+    }
+
+    // ------------------ Search API Methods ------------------
+
+    /**
+     * Search records across the workspace using full-text search.
+     *
+     * @param query - The search query string
+     * @param options - Optional search parameters
+     * @returns Search results with hits and metadata
+     *
+     * @example
+     * ```ts
+     * // Basic search
+     * const results = await client.search('customer email');
+     * console.log('Found:', results.data.totalHits, 'results');
+     * results.data.hits.forEach(hit => console.log(hit.id, hit.structureSlug));
+     *
+     * // Search with structure filter
+     * const userResults = await client.search('john', { structures: 'users' });
+     *
+     * // Search multiple structures with limit
+     * const results = await client.search('active', {
+     *   structures: ['users', 'orders'],
+     *   limit: 50
+     * });
+     * ```
+     */
+    public async search(
+        query: string,
+        options?: SearchOptions
+    ): Promise<ApiResponse<SearchResponse>> {
+        const path = getSearchApiPath(this.options.workspaceId);
+
+        const queryParams: Record<string, string> = { q: query };
+
+        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.collections = structures;
+        }
+
+        if (options?.limit) {
+            queryParams.limit = String(options.limit);
+        }
+
+        return this.request<SearchResponse>('GET', path, null, queryParams);
+    }
+
+    // ------------------ Authorization API Methods (BYOT) ------------------
+
+    /**
+     * Check if an action is authorized for an external token.
+     *
+     * Use this method when you want to authorize access using tokens from your
+     * own identity provider (Clerk, Auth0, Okta, etc.) instead of Centrali's
+     * built-in authentication.
+     *
+     * **Use Cases:**
+     * 1. **AuthZ-as-a-Service**: Define custom resources (orders, invoices) in Centrali
+     *    and use it purely for authorization decisions.
+     * 2. **External IdP for Centrali resources**: Access Centrali data (records, files)
+     *    using your corporate IdP tokens.
+     *
+     * **Prerequisites:**
+     * - Configure an External Auth Provider in Centrali Console (Settings → External Auth)
+     * - Define claim mappings to extract attributes from your JWT
+     * - Create policies that reference the extracted attributes (prefixed with `ext_`)
+     *
+     * @example
+     * // Simple authorization check
+     * const result = await client.checkAuthorization({
+     *   token: clerkJWT,
+     *   resource: 'orders',
+     *   action: 'read'
+     * });
+     *
+     * if (result.data.allowed) {
+     *   // Proceed with the action
+     * }
+     *
+     * @example
+     * // Authorization with context for policy evaluation
+     * const result = await client.checkAuthorization({
+     *   token: clerkJWT,
+     *   resource: 'orders',
+     *   action: 'approve',
+     *   context: {
+     *     orderId: 'order-123',
+     *     orderAmount: 50000,
+     *     department: 'sales'
+     *   }
+     * });
+     *
+     * // Policy can check: ext_role == 'manager' AND request_metadata.orderAmount > 10000
+     *
+     * @param options - Authorization check options
+     * @returns Promise resolving to the authorization result
+     */
+    public async checkAuthorization(
+        options: CheckAuthorizationOptions
+    ): Promise<ApiResponse<AuthorizationResult>> {
+        const { token, resource, action, resourceCategory = 'custom', context } = options;
+
+        const path = `/workspace/${this.options.workspaceId}/api/v1/access/evaluate`;
+
+        const body = {
+            action,
+            resource_name: resource,
+            resource_category: resourceCategory,
+            request_data: context ? { request_metadata: context } : undefined
+        };
+
+        // Make request with the external token
+        const response = await this.axios.request<{
+            status: string;
+            response: 'allow' | 'deny' | 'not_applicable';
+            message?: string;
+        }>({
+            method: 'POST',
+            url: path,
+            data: body,
+            headers: {
+                'Authorization': `Bearer ${token}`,
+                'Content-Type': 'application/json'
+            }
+        });
+
+        return {
+            data: {
+                allowed: response.data.response === 'allow',
+                decision: response.data.response,
+                message: response.data.message
+            }
+        };
+    }
+
+}