@centrali-io/centrali-sdk 5.5.0 → 6.0.0

package/src/types/validation.ts

@@ -0,0 +1,167 @@
+// =====================================================
+// Validation Types (Data Quality)
+// =====================================================
+
+/**
+ * Validation issue types.
+ * - 'type': Schema type mismatch (e.g., string where array expected) - rule-based
+ * - 'format': Format validation (email, phone, url patterns) - rule-based
+ * - 'typo': Spelling/typo detection - AI-based
+ * - 'duplicate': Duplicate record detection - rule-based
+ * - 'semantic': Logical/semantic issues - AI-based
+ */
+export type ValidationIssueType = 'type' | 'format' | 'typo' | 'duplicate' | 'semantic';
+
+/**
+ * Validation suggestion status.
+ */
+export type ValidationSuggestionStatus = 'pending' | 'accepted' | 'rejected' | 'auto-applied';
+
+/**
+ * A validation suggestion from the AI validation system.
+ */
+export interface ValidationSuggestion {
+    /** Unique identifier */
+    id: string;
+    /** Workspace slug */
+    workspaceSlug: string;
+    /** Structure ID */
+    structureId: string;
+    /** Record ID */
+    recordId: string;
+    /** Structure's record slug */
+    recordSlug: string;
+    /** Field name with the issue */
+    field: string;
+    /** Type of issue detected */
+    issueType: ValidationIssueType;
+    /** Original value in the field */
+    originalValue: string | null;
+    /** Suggested corrected value */
+    suggestedValue: string | null;
+    /** Confidence score 0-1 */
+    confidence: number;
+    /** Current status */
+    status: ValidationSuggestionStatus;
+    /** Batch ID if created during batch scan */
+    batchId: string | null;
+    /** Additional metadata */
+    metadata: Record<string, any>;
+    /** Creation timestamp */
+    createdAt: string;
+    /** Last update timestamp */
+    updatedAt: string;
+    /** When resolved (accepted/rejected) */
+    resolvedAt: string | null;
+    /** Who resolved */
+    resolvedBy: string | null;
+}
+
+/**
+ * Options for listing validation suggestions.
+ */
+export interface ListValidationSuggestionsOptions {
+    /** Filter by structure slug (recordSlug) */
+    structureSlug?: string;
+    /** Filter by record ID */
+    recordId?: string;
+    /** Filter by status */
+    status?: ValidationSuggestionStatus;
+    /** Filter by issue type */
+    issueType?: ValidationIssueType;
+    /** Filter by batch ID */
+    batchId?: string;
+    /** Minimum confidence threshold */
+    minConfidence?: number;
+    /** Maximum results (default: 50, max: 100) */
+    limit?: number;
+    /** Offset for pagination */
+    offset?: number;
+}
+
+/**
+ * Batch scan status.
+ */
+export type BatchScanStatus = 'queued' | 'pending' | 'processing' | 'completed' | 'failed';
+
+/**
+ * Result from triggering a batch validation scan.
+ */
+export interface BatchScanResult {
+    /** Unique batch identifier */
+    batchId: string;
+    /** Current status */
+    status: BatchScanStatus;
+    /** Total records to scan */
+    total: number;
+    /** Records processed so far */
+    processed: number;
+    /** Issues found so far */
+    issuesFound: number;
+    /** When the scan started */
+    startedAt: string;
+    /** When the scan completed (if finished) */
+    completedAt?: string;
+    /** Error message if failed */
+    error?: string;
+}
+
+/**
+ * Options for triggering a batch scan.
+ */
+export interface TriggerScanOptions {
+    /** Validation types to run (defaults to structure config) */
+    validationTypes?: ValidationIssueType[];
+}
+
+/**
+ * Options for waiting for a scan to complete.
+ */
+export interface WaitForScanOptions {
+    /** Poll interval in milliseconds (default: 5000) */
+    pollInterval?: number;
+    /** Timeout in milliseconds (default: 300000 = 5 minutes) */
+    timeout?: number;
+}
+
+/**
+ * Summary of validation suggestions.
+ */
+export interface ValidationSummary {
+    /** Total suggestions */
+    total: number;
+    /** Pending suggestions */
+    pending: number;
+    /** Accepted suggestions */
+    accepted: number;
+    /** Rejected suggestions */
+    rejected: number;
+    /** Auto-applied suggestions */
+    autoApplied: number;
+    /** Breakdown by issue type */
+    byIssueType: Record<string, number>;
+}
+
+/**
+ * Result from accepting a suggestion.
+ */
+export interface AcceptSuggestionResult {
+    /** The updated suggestion */
+    suggestion: ValidationSuggestion;
+    /** Whether the record was updated */
+    recordUpdated: boolean;
+    /** Status message */
+    message: string;
+}
+
+/**
+ * Result from bulk operations.
+ */
+export interface BulkOperationResult {
+    /** Number of successful operations */
+    count: number;
+    /** Errors for failed operations */
+    errors?: Array<{ id: string; error: string }>;
+    /** Status message */
+    message: string;
+}

package/src/types/webhooks.ts

@@ -0,0 +1,114 @@
+// =====================================================
+// Webhook Subscription Types
+// =====================================================
+
+import type { RecordEventType } from './realtime';
+
+export type WebhookDeliveryStatus = 'success' | 'failed' | 'retrying';
+
+export interface WebhookSubscription {
+    id: string;
+    name: string;
+    url: string;
+    events: RecordEventType[];
+    /**
+     * Optional list of record slugs to scope the subscription to. When null or
+     * empty, the subscription receives events for all collections.
+     */
+    recordSlugs?: string[] | null;
+    active: boolean;
+    /**
+     * Signing secret (`whsec_` prefix). Returned by `create` and `rotateSecret`;
+     * undefined on subsequent reads so it is safe to pass subscriptions around.
+     */
+    secret?: string;
+    workspaceSlug: string;
+    createdAt?: string;
+    updatedAt?: string;
+}
+
+/**
+ * Full webhook delivery record including request payload and response body.
+ * Returned by `deliveries.get()`.
+ */
+export interface WebhookDelivery {
+    id: string;
+    webhookSubscriptionId: string;
+    workspaceSlug: string;
+    event: string;
+    attemptCount: number;
+    status: WebhookDeliveryStatus;
+    lastError?: string | null;
+    httpStatus?: number | null;
+    lastAttemptAt: string;
+    nextAttemptAt?: string | null;
+    requestPayload?: any;
+    responseBody?: string | null;
+    /** Delivery ID the row was replayed from, or null for original deliveries. */
+    replayedFrom?: string | null;
+    createdAt: string;
+    updatedAt: string;
+}
+
+/**
+ * Trimmed delivery row returned by `deliveries.list()` — omits `requestPayload`
+ * and `responseBody`. Fetch individual deliveries with `deliveries.get()` to get
+ * the full payload and response body.
+ */
+export type WebhookDeliverySummary = Omit<WebhookDelivery, 'requestPayload' | 'responseBody'>;
+
+export interface CreateWebhookSubscriptionInput {
+    name: string;
+    url: string;
+    events: RecordEventType[];
+    /** Optional — restrict to a subset of collections. Omit for all collections. */
+    recordSlugs?: string[];
+    active?: boolean;
+}
+
+export interface UpdateWebhookSubscriptionInput {
+    name?: string;
+    url?: string;
+    events?: RecordEventType[];
+    /**
+     * Update the collection scope. Pass an empty array (`[]`) to clear the
+     * restriction so the subscription receives events for all collections.
+     * Omit the field to leave the scope unchanged.
+     */
+    recordSlugs?: string[];
+    active?: boolean;
+}
+
+export interface ListWebhookDeliveriesOptions {
+    status?: WebhookDeliveryStatus;
+    /** ISO 8601 datetime or Date — include deliveries created at or after this time. */
+    since?: string | Date;
+    /** ISO 8601 datetime or Date — include deliveries created at or before this time. */
+    until?: string | Date;
+    limit?: number;
+    offset?: number;
+}
+
+/**
+ * Pagination metadata returned alongside `deliveries.list()` rows. The backend
+ * surfaces `{ data, meta }` which the SDK normalizer passes through as the
+ * `ApiResponse` itself — so `result.data` is the array and `result.meta` is
+ * this object.
+ */
+export interface WebhookDeliveriesListMeta {
+    total: number;
+    limit: number;
+    offset: number;
+}
+
+export interface WebhookReplayResponse {
+    deliveryId: string;
+    replayedFrom: string | null;
+    status: WebhookDeliveryStatus;
+}
+
+export interface WebhookCancelResponse {
+    deliveryId: string;
+    status: WebhookDeliveryStatus;
+    lastError: string | null;
+}

package/src/urls.ts

@@ -0,0 +1,33 @@
+/**
+ * Generate the API URL from the base URL by adding the 'api.' subdomain.
+ * E.g., https://centrali.io -> https://api.centrali.io
+ */
+export function getApiUrl(baseUrl: string): string {
+    const url = new URL(baseUrl);
+    // If already has 'api.' subdomain, return as-is
+    if (url.hostname.startsWith('api.')) {
+        return `${url.protocol}//${url.hostname}`;
+    }
+    return `${url.protocol}//api.${url.hostname}`;
+}
+
+/**
+ * Generate the auth server URL from the base URL.
+ * E.g., https://centrali.io -> https://auth.centrali.io
+ */
+export function getAuthUrl(baseUrl: string): string {
+    const url = new URL(baseUrl);
+    // Strip 'api.' prefix if present to get root domain
+    const hostname = url.hostname.startsWith('api.')
+        ? url.hostname.slice(4)
+        : url.hostname;
+    return `${url.protocol}//auth.${hostname}`;
+}
+
+/**
+ * Generate the realtime service URL from the base URL.
+ * E.g., https://centrali.io -> https://api.centrali.io/realtime
+ */
+export function getRealtimeUrl(baseUrl: string): string {
+    return `${getApiUrl(baseUrl)}/realtime`;
+}

package/dist/query-types.d.ts

@@ -1,187 +0,0 @@
-export type QueryDefinition = {
-    /**
-     * Logical resource being queried.
-     *
-     * - For records: the collection (a.k.a. structure) slug — e.g. `"orders"`,
-     *   `"customers"`. The records executor treats this as the collection slug.
-     * - For other queryable resources: the resource type identifier — e.g.
-     *   `"audit-log"`, `"function-runs"`, `"files"`, `"webhook-deliveries"`.
-     *
-     * Named `resource` (not `collection`) because "collection" is overloaded in
-     * Centrali — it's the renamed records-bucket entity, so `collection: "audit-log"`
-     * would read as a category error. `resource` is REST-canonical and reads
-     * truthfully across every executor.
-     */
-    resource: string;
-    where?: WhereExpression;
-    text?: TextSearchClause;
-    sort?: SortClause[];
-    page?: PageClause;
-    select?: SelectClause;
-    include?: IncludeClause[];
-};
-export type SavedQueryDefinition = {
-    name: string;
-    description?: string;
-    query: QueryDefinition;
-    variables?: Record<string, QueryVariableDefinition>;
-};
-export type WhereExpression = FieldConditionMap | {
-    and: WhereExpression[];
-} | {
-    or: WhereExpression[];
-} | {
-    not: WhereExpression;
-};
-export type FieldConditionMap = {
-    [field: string]: FieldCondition;
-};
-/**
- * Exactly-one helper: for a record of operator → value-type, produces a union
- * where each variant has exactly one of the keys present and all the others
- * forbidden via `?: never`. This enforces the contract's "exactly one operator
- * per FieldCondition" rule at the type level — `{ eq: 1, ne: 2 }` fails to
- * type-check.
- */
-type ExactlyOneOperator<T> = {
-    [K in keyof T]: {
-        [P in K]: T[P];
-    } & {
-        [P in Exclude<keyof T, K>]?: never;
-    };
-}[keyof T];
-type FieldOperatorMap = {
-    eq: ScalarValue;
-    ne: ScalarValue;
-    gt: number | string;
-    gte: number | string;
-    lt: number | string;
-    lte: number | string;
-    in: ScalarValue[];
-    nin: ScalarValue[];
-    contains: string;
-    startsWith: string;
-    endsWith: string;
-    hasAny: ScalarValue[];
-    hasAll: ScalarValue[];
-    exists: boolean;
-};
-export type FieldCondition = ExactlyOneOperator<FieldOperatorMap>;
-export type ScalarValue = string | number | boolean | null;
-export type CanonicalOperator = 'eq' | 'ne' | 'gt' | 'gte' | 'lt' | 'lte' | 'in' | 'nin' | 'contains' | 'startsWith' | 'endsWith' | 'hasAny' | 'hasAll' | 'exists';
-export declare const CANONICAL_OPERATORS: readonly CanonicalOperator[];
-/** Argument shape an operator expects in a `FieldCondition`. */
-export type OperatorValueShape = 
-/** Single scalar input (string/number/boolean/null). */
-'scalar'
-/** Array of scalars — UI typically renders a chip / comma input. */
- | 'array'
-/** Boolean toggle — `exists`. */
- | 'boolean';
-/**
- * Logical type families an operator applies to. The visual builder narrows
- * the dropdown to the operators valid for the selected field's type.
- *
- * `any` means the operator is type-agnostic (`eq`, `ne`, `exists`).
- */
-export type OperatorTypeApplicability = 'string' | 'number' | 'boolean' | 'datetime' | 'array' | 'any';
-export type OperatorMeta = {
-    /** Canonical bare operator name. */
-    operator: CanonicalOperator;
-    /** Human-readable label for dropdowns. */
-    label: string;
-    /** Short, symbol-style label suitable for compact number/datetime UIs. */
-    shortLabel?: string;
-    /** Argument shape — drives the value input affordance. */
-    valueShape: OperatorValueShape;
-    /** Field types this operator applies to. */
-    applicableTypes: OperatorTypeApplicability[];
-};
-export declare const OPERATOR_METADATA: Readonly<Record<CanonicalOperator, OperatorMeta>>;
-/**
- * Operators applicable to a given field-type. Used by builder UIs to narrow
- * the dropdown when the user selects a field; falls back to `any`-applicable
- * operators when the type is unknown.
- */
-export declare function operatorsForFieldType(type: OperatorTypeApplicability | string): readonly OperatorMeta[];
-export type TextSearchClause = {
-    query: string;
-    fields?: string[];
-    typoTolerance?: boolean;
-};
-export type SortClause = {
-    field: string;
-    direction: 'asc' | 'desc';
-};
-/**
- * Two pagination modes. Per contract §6 they are mutually exclusive — `cursor`
- * is forbidden in offset mode and `offset` is forbidden in cursor mode so a
- * caller cannot construct an ambiguous request.
- */
-export type PageClause = {
-    limit: number;
-    offset?: number;
-    cursor?: never;
-} | {
-    limit: number;
-    cursor?: string;
-    offset?: never;
-};
-/**
- * Records Phase 1 page defaults (contract §6).
- * Same default and cap for GET adapter and POST query body.
- */
-export declare const RECORDS_PAGE_DEFAULT_LIMIT = 50;
-export declare const RECORDS_PAGE_MAX_LIMIT = 500;
-export type SelectClause = {
-    fields: string[];
-};
-/**
- * Phase 1 reserves the shape but rejects execution with `unsupported_clause`.
- */
-export type IncludeClause = {
-    relation: string;
-};
-export type VariableType = 'string' | 'number' | 'boolean' | 'datetime' | 'id' | {
-    array: VariableType;
-} | {
-    reference: string;
-};
-export type QueryVariableDefinition = {
-    type: VariableType;
-    required?: boolean;
-    default?: ScalarValue;
-    description?: string;
-};
-export type QueryExecutionMode = 'filter' | 'search' | 'hybrid';
-export type QueryResultMeta = {
-    total?: number;
-    limit: number;
-    offset?: number;
-    cursor?: string;
-    nextCursor?: string;
-    hasMore?: boolean;
-    processingTimeMs?: number;
-    mode?: QueryExecutionMode;
-};
-export type QueryResult<T> = {
-    data: T[];
-    meta: QueryResultMeta;
-};
-export type QueryErrorCode = 'unsupported_clause' | 'unsupported_operator' | 'unsupported_legacy_operator' | 'unreadable_field' | 'invalid_query' | 'legacy_write_unsupported';
-export type QueryError = {
-    code: QueryErrorCode;
-    message: string;
-    /** Dotted path inside the QueryDefinition where the error was detected, e.g. "where.data.status.eq". */
-    path?: string;
-    /** For `unsupported_clause` / `unsupported_operator`, the offending name. */
-    clause?: string;
-};
-export type ValidationResult<T> = {
-    ok: true;
-    value: T;
-} | {
-    ok: false;
-    errors: QueryError[];
-};
-export {};

package/dist/query-types.js

@@ -1,137 +0,0 @@
-"use strict";
-// ---------------------------------------------------------------------------
-// AUTO-GENERATED — DO NOT EDIT BY HAND.
-//
-// Source: services/backend/shared/query/src/types.ts (@centrali/query)
-// Regenerate: `npm run sync:query-types` (also runs on prebuild).
-//
-// The shared package is the single source of truth for canonical query types.
-// This file is a types-only port so the published SDK stays a single npm
-// install. See CEN-1194 for the alignment, CEN-1202 for runtime bundling.
-// ---------------------------------------------------------------------------
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.RECORDS_PAGE_MAX_LIMIT = exports.RECORDS_PAGE_DEFAULT_LIMIT = exports.OPERATOR_METADATA = exports.CANONICAL_OPERATORS = void 0;
-exports.operatorsForFieldType = operatorsForFieldType;
-exports.CANONICAL_OPERATORS = [
-    'eq',
-    'ne',
-    'gt',
-    'gte',
-    'lt',
-    'lte',
-    'in',
-    'nin',
-    'contains',
-    'startsWith',
-    'endsWith',
-    'hasAny',
-    'hasAll',
-    'exists',
-];
-exports.OPERATOR_METADATA = {
-    eq: {
-        operator: 'eq',
-        label: 'equals',
-        shortLabel: '=',
-        valueShape: 'scalar',
-        applicableTypes: ['any'],
-    },
-    ne: {
-        operator: 'ne',
-        label: 'not equals',
-        shortLabel: '≠',
-        valueShape: 'scalar',
-        applicableTypes: ['any'],
-    },
-    gt: {
-        operator: 'gt',
-        label: 'greater than',
-        shortLabel: '>',
-        valueShape: 'scalar',
-        applicableTypes: ['number', 'datetime'],
-    },
-    gte: {
-        operator: 'gte',
-        label: 'greater or equal',
-        shortLabel: '≥',
-        valueShape: 'scalar',
-        applicableTypes: ['number', 'datetime'],
-    },
-    lt: {
-        operator: 'lt',
-        label: 'less than',
-        shortLabel: '<',
-        valueShape: 'scalar',
-        applicableTypes: ['number', 'datetime'],
-    },
-    lte: {
-        operator: 'lte',
-        label: 'less or equal',
-        shortLabel: '≤',
-        valueShape: 'scalar',
-        applicableTypes: ['number', 'datetime'],
-    },
-    in: {
-        operator: 'in',
-        label: 'in',
-        valueShape: 'array',
-        applicableTypes: ['string', 'number', 'datetime'],
-    },
-    nin: {
-        operator: 'nin',
-        label: 'not in',
-        valueShape: 'array',
-        applicableTypes: ['string', 'number', 'datetime'],
-    },
-    contains: {
-        operator: 'contains',
-        label: 'contains',
-        valueShape: 'scalar',
-        applicableTypes: ['string'],
-    },
-    startsWith: {
-        operator: 'startsWith',
-        label: 'starts with',
-        valueShape: 'scalar',
-        applicableTypes: ['string'],
-    },
-    endsWith: {
-        operator: 'endsWith',
-        label: 'ends with',
-        valueShape: 'scalar',
-        applicableTypes: ['string'],
-    },
-    hasAny: {
-        operator: 'hasAny',
-        label: 'has any of',
-        valueShape: 'array',
-        applicableTypes: ['array'],
-    },
-    hasAll: {
-        operator: 'hasAll',
-        label: 'has all of',
-        valueShape: 'array',
-        applicableTypes: ['array'],
-    },
-    exists: {
-        operator: 'exists',
-        label: 'exists',
-        valueShape: 'boolean',
-        applicableTypes: ['any'],
-    },
-};
-/**
- * Operators applicable to a given field-type. Used by builder UIs to narrow
- * the dropdown when the user selects a field; falls back to `any`-applicable
- * operators when the type is unknown.
- */
-function operatorsForFieldType(type) {
-    const t = type;
-    return exports.CANONICAL_OPERATORS.map((op) => exports.OPERATOR_METADATA[op]).filter((meta) => meta.applicableTypes.includes('any') || meta.applicableTypes.includes(t));
-}
-/**
- * Records Phase 1 page defaults (contract §6).
- * Same default and cap for GET adapter and POST query body.
- */
-exports.RECORDS_PAGE_DEFAULT_LIMIT = 50;
-exports.RECORDS_PAGE_MAX_LIMIT = 500;

package/dist/scripts/smoke-types.d.ts

@@ -1,12 +0,0 @@
-/**
- * Type-only smoke for the canonical query surface added in 5.5.0 (CEN-1194).
- *
- * Runs as part of `npm run build` because it lives in the same project as
- * `index.ts`. Compiling means the canonical types and new methods type-check
- * end-to-end. There is no runtime assertion — when the SDK has a real test
- * harness (separate ticket), these calls will turn into integration tests.
- *
- * To run manually:
- *   npx tsc --noEmit scripts/smoke-types.ts
- */
-export {};