@centrali-io/centrali-sdk 5.5.0 → 6.0.0

package/src/types/search.ts

@@ -0,0 +1,44 @@
+// =====================================================
+// Search Types
+// =====================================================
+
+/**
+ * Options for searching records.
+ */
+export interface SearchOptions {
+    /** Filter by structure slug(s). Can be a single slug or array of slugs */
+    structures?: string | string[];
+    /** Filter by collection slug(s). Can be a single slug or array of slugs */
+    collections?: string | string[];
+    /** Maximum number of results to return (default: 20, max: 100) */
+    limit?: number;
+}
+
+/**
+ * A single search result hit.
+ */
+export interface SearchHit {
+    /** The record ID */
+    id: string;
+    /** The record slug (structure type) */
+    recordSlug: string;
+    /** The structure slug */
+    structureSlug: string;
+    /** The indexed record data */
+    [key: string]: unknown;
+}
+
+/**
+ * Response from a search query.
+ */
+export interface SearchResponse {
+    /** Array of matching records */
+    hits: SearchHit[];
+    /** Estimated total number of matching records */
+    totalHits: number;
+    /** Time taken to process the search in milliseconds */
+    processingTimeMs: number;
+    /** The original search query */
+    query: string;
+}
+

package/src/types/smartQueries.ts

@@ -0,0 +1,303 @@
+import type { QueryDefinition, QueryVariableDefinition, ScalarValue } from '../../query-types';
+
+// =====================================================
+// Smart Query Types (saved-query surface for `client.savedQueries`)
+// =====================================================
+//
+// These types describe the **stored** saved-query shape and the operator
+// vocabulary the `/saved-queries/*` routes accept. They back both
+// `client.savedQueries.*` (canonical) and the deprecated `client.smartQueries`
+// alias. The SDK still exports the type names with `SmartQuery` prefixes for
+// back-compat; canonical `SavedQuery*` aliases will be added in a follow-up.
+
+/**
+ * Smart query definition stored in the database.
+ */
+export interface SmartQuery {
+    /** Unique identifier (UUID) */
+    id: string;
+    /** Workspace slug where the query belongs */
+    workspaceSlug: string;
+    /** Structure's record slug (e.g., "employee") */
+    recordSlug: string;
+    /** Human-readable name (unique within workspace) */
+    name: string;
+    /** Optional description */
+    description?: string;
+    /** Query definition object */
+    queryDefinition: SmartQueryDefinition;
+    /** Status (active, archived) */
+    status: string;
+    /**
+     * Typed parameter declarations for `${var}` placeholders in the query
+     * body. Present on Phase 4 saved queries; `null`/absent on rows that have
+     * not yet been migrated, in which case execute falls back to legacy
+     * untyped string substitution. Re-exported from `@centrali/query` so the
+     * SDK and server share one shape.
+     */
+    variables?: Record<string, QueryVariableDefinition> | null;
+    /** User ID who created the query */
+    createdBy: string;
+    /** User ID who last updated the query */
+    updatedBy: string;
+    /** ISO timestamp of creation */
+    createdAt: string;
+    /** ISO timestamp of last update */
+    updatedAt: string;
+}
+
+/**
+ * Query definition format for smart queries.
+ * Supports filtering, selection, joins, sorting, and pagination.
+ */
+export interface SmartQueryDefinition {
+    /** Fields to select from the structure */
+    select?: string[];
+    /** Filter conditions */
+    where?: SmartQueryWhereClause;
+    /** Join to another structure */
+    join?: SmartQueryJoin;
+    /** Sorting specification */
+    sort?: SmartQuerySort[];
+    /** Maximum number of results */
+    limit?: number;
+    /** Number of results to skip */
+    skip?: number;
+}
+
+/**
+ * Where clause for smart query filtering.
+ * Supports comparison operators and logical operators.
+ */
+export interface SmartQueryWhereClause {
+    /** Field-level conditions */
+    [field: string]: SmartQueryFieldCondition | SmartQueryWhereClause[] | undefined;
+    /** Logical AND of multiple conditions */
+    $and?: SmartQueryWhereClause[];
+    /** Logical OR of multiple conditions */
+    $or?: SmartQueryWhereClause[];
+}
+
+/**
+ * Field-level condition operators for smart query filtering.
+ */
+export interface SmartQueryFieldCondition {
+    /** Equality */
+    $eq?: any;
+    /** Not equal */
+    $ne?: any;
+    /** Greater than */
+    $gt?: number;
+    /** Greater than or equal */
+    $gte?: number;
+    /** Less than */
+    $lt?: number;
+    /** Less than or equal */
+    $lte?: number;
+    /** String starts with */
+    $startsWith?: string;
+    /** String ends with */
+    $endsWith?: string;
+    /** String contains */
+    $contains?: string;
+    /** Regex pattern match */
+    $regex?: string;
+    /** Value in array */
+    $in?: any[];
+    /** Value not in array */
+    $nin?: any[];
+    /** Field exists check */
+    $exists?: boolean;
+    /** JSONB type check */
+    $type?: string;
+}
+
+/**
+ * Join definition for smart queries.
+ */
+export interface SmartQueryJoin {
+    /** Target structure slug to join */
+    foreignSlug: string;
+    /** Field in the main structure */
+    localField: string;
+    /** Field in the foreign structure */
+    foreignField: string;
+    /** Fields to select from the joined structure */
+    select?: string[];
+}
+
+/**
+ * Sort specification for smart queries.
+ */
+export interface SmartQuerySort {
+    /** Field to sort by */
+    field: string;
+    /** Sort direction */
+    direction: 'asc' | 'desc';
+}
+
+
+/**
+ * Options for listing smart queries.
+ */
+export interface ListSmartQueryOptions {
+    /** Page number (default: 1) */
+    page?: number;
+    /** Results per page (default: 20) */
+    limit?: number;
+    /** Search term */
+    search?: string;
+    /** Sort field */
+    sort?: string;
+    /** Sort direction */
+    sortDirection?: 'asc' | 'desc';
+}
+
+/**
+ * A scalar value bindable to a saved-query parameter slot, including `Date`
+ * for `datetime` declarations. `Date` works because axios JSON-serializes it
+ * to an ISO-8601 string before the request leaves the client — the server
+ * never sees a `Date` object and does not perform type coercion.
+ */
+export type SavedQueryScalarBinding = ScalarValue | Date;
+
+/**
+ * Runtime values bound to a saved query's typed parameters at execution time.
+ *
+ * Each key matches a declaration in the saved query's `variables` map.
+ * Scalars cover `string`/`number`/`boolean`/`datetime`/`id`/`reference`;
+ * arrays — including `array<datetime>` — cover `{ array: ... }` declarations
+ * (the shared contract is recursive, so `Date[]` and `string[]` etc. are all
+ * valid bindings).
+ *
+ * Phase 4 typed substitution validates each value against its declared type
+ * by JS `typeof` (no coercion — `"123"` is rejected for `number`). `Date` is
+ * serialized to ISO-8601 over the wire and then accepted as a `datetime`
+ * string. Pre-Phase-4 (untyped) saved queries stringify every value before
+ * substitution; the SDK does not narrow that path.
+ */
+export type ExecuteSavedQueryValues = Record<
+    string,
+    SavedQueryScalarBinding | SavedQueryScalarBinding[]
+>;
+
+/**
+ * Options for executing a saved query.
+ */
+export interface ExecuteSmartQueryOptions {
+    /**
+     * Values bound to the saved query's `${var}` placeholders. Use canonical
+     * `${variableName}` syntax in the persisted query body, then pass values
+     * here at execution time.
+     *
+     * On Phase 4 typed saved queries (rows that declare `variables`), the
+     * server validates these against the typed declarations by JS `typeof`
+     * (no coercion). On legacy untyped rows, every value is stringified
+     * before substitution.
+     *
+     * @example
+     * ```ts
+     * // Query definition with parameter: { where: { userId: { eq: "${currentUserId}" } } }
+     * const results = await client.savedQueries.execute('orders', 'query-id', {
+     *   variables: { currentUserId: 'user_123' }
+     * });
+     *
+     * // Typed datetime + array binding (Phase 4)
+     * await client.savedQueries.execute('orders', 'query-id', {
+     *   variables: { since: new Date('2026-01-01'), statuses: ['open', 'paid'] },
+     * });
+     * ```
+     */
+    variables?: ExecuteSavedQueryValues;
+}
+
+/**
+ * Result from executing a smart query with metadata.
+ */
+export interface SmartQueryExecuteResult<T = any> {
+    /** Query results */
+    result: T[];
+    /** Metadata about the execution */
+    meta?: {
+        /** Variables that were used in the query */
+        variablesUsed?: string[];
+    };
+}
+// =====================================================
+// Smart Query CRUD Types (Configuration-as-Code)
+// =====================================================
+
+/**
+ * Input for creating a new saved query.
+ *
+ * Phase 4 callers should set `query` (canonical `QueryDefinition` — eq/gte/lte
+ * operators, `${var}` placeholders) and optionally `variables` to declare the
+ * parameter types. Pre-Phase-4 callers may still set `queryDefinition` (legacy
+ * `$eq`/`$gte` shape) — the SDK routes those to the legacy slug-based create
+ * endpoint, which does not accept typed variable declarations.
+ */
+export interface CreateSmartQueryInput {
+    name: string;
+    description?: string;
+    /** Canonical query body (Phase 4). Required for typed `variables`. */
+    query?: QueryDefinition;
+    /**
+     * @deprecated Use `query` (canonical `QueryDefinition`). The legacy
+     *   `SmartQueryDefinition` shape continues to work via the legacy
+     *   slug-based endpoint but cannot carry typed `variables` declarations.
+     */
+    queryDefinition?: SmartQueryDefinition;
+    /**
+     * Optional typed parameter declarations. When present, every `${var}`
+     * placeholder in `query` must be declared, and execute-time values are
+     * validated against these types by JS `typeof` (no server-side coercion).
+     * Requires `query` (canonical).
+     */
+    variables?: Record<string, QueryVariableDefinition> | null;
+}
+
+/**
+ * Input for updating an existing saved query.
+ */
+export interface UpdateSmartQueryInput {
+    name?: string;
+    description?: string;
+    /** Canonical query body (Phase 4). Routes through the canonical PUT. */
+    query?: QueryDefinition;
+    /**
+     * @deprecated Use `query` (canonical). The legacy shape routes through
+     *   the legacy slug-based PUT.
+     */
+    queryDefinition?: SmartQueryDefinition;
+    /**
+     * Replace the typed parameter declarations. Pass `null` to clear them
+     * (the query reverts to the legacy untyped path); omit the field
+     * entirely to leave the existing declarations untouched. Only honored on
+     * the canonical PUT path (i.e. when paired with `query`).
+     */
+    variables?: Record<string, QueryVariableDefinition> | null;
+}
+
+/**
+ * Input for test-executing a saved query definition without saving.
+ *
+ * Set `query` for canonical authoring; `queryDefinition` stays as a legacy
+ * fallback. When `variableDeclarations` is provided, the canonical test path
+ * validates `variables` against those declarations the same way an executed
+ * saved query would.
+ */
+export interface TestSmartQueryInput {
+    /** Canonical query body (Phase 4). */
+    query?: QueryDefinition;
+    /**
+     * @deprecated Use `query` (canonical).
+     */
+    queryDefinition?: SmartQueryDefinition;
+    variables?: ExecuteSavedQueryValues;
+    /**
+     * Typed parameter declarations the author is editing in the same draft.
+     * When provided, the test path validates `variables` against these
+     * declarations the same way an executed saved query would.
+     */
+    variableDeclarations?: Record<string, QueryVariableDefinition>;
+}

package/src/types/structures.ts

@@ -0,0 +1,203 @@
+// =====================================================
+// Structure Types (Configuration-as-Code)
+// =====================================================
+
+/**
+ * Property type identifiers for structure properties.
+ */
+export type PropertyType = 'string' | 'number' | 'boolean' | 'datetime' | 'array' | 'object' | 'reference';
+
+/**
+ * Schema discovery mode for a structure.
+ */
+export type SchemaDiscoveryMode = 'strict' | 'schemaless' | 'auto-evolving';
+
+/**
+ * Base property definition shared by all property types.
+ */
+export interface BasePropertyDefinition {
+    id?: string;
+    name: string;
+    type: PropertyType;
+    description?: string;
+    required?: boolean;
+    nullable?: boolean;
+    default?: any;
+    enum?: any[];
+    isUnique?: boolean;
+    immutable?: boolean;
+}
+
+/**
+ * String property definition.
+ */
+export interface StringPropertyDefinition extends BasePropertyDefinition {
+    type: 'string';
+    minLength?: number;
+    maxLength?: number;
+    pattern?: string;
+    renderAs?: 'textarea' | 'secret' | 'color' | 'code' | 'html' | 'markdown';
+    not?: any[];
+    isSecret?: boolean;
+}
+
+/**
+ * Number property definition.
+ */
+export interface NumberPropertyDefinition extends BasePropertyDefinition {
+    type: 'number';
+    minimum?: number;
+    maximum?: number;
+    exclusiveMinimum?: boolean;
+    exclusiveMaximum?: boolean;
+    multipleOf?: number;
+    expression?: string;
+    computedMode?: 'persisted' | 'virtual';
+    autoIncrement?: { startAt: number; incrementBy?: number };
+}
+
+/**
+ * Boolean property definition.
+ */
+export interface BooleanPropertyDefinition extends BasePropertyDefinition {
+    type: 'boolean';
+}
+
+/**
+ * DateTime property definition.
+ */
+export interface DateTimePropertyDefinition extends BasePropertyDefinition {
+    type: 'datetime';
+    earliestDate?: string;
+    latestDate?: string;
+    exclusiveEarliest?: boolean;
+    exclusiveLatest?: boolean;
+    expression?: string;
+    computedMode?: 'persisted' | 'virtual';
+}
+
+/**
+ * Array property definition.
+ */
+export interface ArrayPropertyDefinition extends BasePropertyDefinition {
+    type: 'array';
+    items: { type: string };
+    minItems?: number;
+    maxItems?: number;
+    uniqueItems?: boolean;
+    itemSchema?: PropertyDefinition[];
+    strictProperties?: boolean;
+}
+
+/**
+ * Object property definition.
+ */
+export interface ObjectPropertyDefinition extends BasePropertyDefinition {
+    type: 'object';
+    properties?: PropertyDefinition[];
+    requiredProperties?: string[];
+    strictProperties?: boolean;
+}
+
+/**
+ * Reference property definition for foreign key-like relationships.
+ */
+export interface ReferencePropertyDefinition extends BasePropertyDefinition {
+    type: 'reference';
+    target: string;
+    targetField?: string;
+    displayField?: string;
+    relationship: 'many-to-one' | 'one-to-one' | 'many-to-many';
+    onDelete: 'restrict' | 'cascade' | 'set_null';
+}
+
+/**
+ * Union of all property definition types.
+ */
+export type PropertyDefinition =
+    | StringPropertyDefinition
+    | NumberPropertyDefinition
+    | BooleanPropertyDefinition
+    | DateTimePropertyDefinition
+    | ArrayPropertyDefinition
+    | ObjectPropertyDefinition
+    | ReferencePropertyDefinition;
+
+/**
+ * Full structure definition.
+ */
+export interface Structure {
+    id: string;
+    name: string;
+    workspaceSlug: string;
+    recordSlug: string;
+    description?: string;
+    properties: PropertyDefinition[];
+    defaultSearchField?: string;
+    metadata?: {
+        recordWritesLocked?: boolean;
+        structureWritesLocked?: boolean;
+        lastMigrationId?: string;
+        migrationInProgress?: boolean;
+        migrationJobId?: string;
+        migrationStartedAt?: string;
+        migrationStartedBy?: string;
+    };
+    status: 'active' | 'inactive';
+    schemaDiscoveryMode: SchemaDiscoveryMode;
+    enableVersioning: boolean;
+    isDeleted: boolean;
+    createdBy: string;
+    lastUpdatedBy: string;
+    createdAt: string;
+    updatedAt: string;
+    tags?: string[];
+}
+
+/**
+ * Input for creating a new structure.
+ */
+export interface CreateStructureInput {
+    name: string;
+    recordSlug: string;
+    description?: string;
+    properties?: PropertyDefinition[];
+    enableVersioning?: boolean;
+    schemaDiscoveryMode?: SchemaDiscoveryMode;
+    tags?: string[];
+}
+
+/**
+ * Input for updating an existing structure.
+ */
+export interface UpdateStructureInput {
+    name?: string;
+    description?: string;
+    properties?: PropertyDefinition[];
+    enableVersioning?: boolean;
+    tags?: string[];
+    /** Default TTL in seconds for new records in this structure. Set to null to clear. */
+    defaultTtlSeconds?: number | null;
+}
+
+/**
+ * Options for listing structures.
+ */
+export interface ListStructuresOptions {
+    page?: number;
+    limit?: number;
+}
+
+/**
+ * Options for listing collections (alias for ListStructuresOptions).
+ */
+export type ListCollectionsOptions = ListStructuresOptions;
+
+/**
+ * Input for validating a structure definition.
+ */
+export interface ValidateStructureInput {
+    name?: string;
+    slug?: string;
+    properties?: PropertyDefinition[];
+}

package/src/types/triggers.ts

@@ -0,0 +1,122 @@
+// =====================================================
+// Trigger Types
+// =====================================================
+
+/**
+ * Trigger execution types supported by Centrali.
+ */
+export type TriggerExecutionType = 'on-demand' | 'event-driven' | 'scheduled' | 'http-trigger';
+
+/**
+ * Function trigger definition.
+ */
+export interface FunctionTrigger {
+    id: string;
+    name: string;
+    description?: string;
+    workspaceSlug: string;
+    functionId: string;
+    executionType: TriggerExecutionType;
+    triggerMetadata: Record<string, any>;
+    schedulerJobId?: string;
+    enabled: boolean;
+    createdBy: string;
+    updatedBy: string;
+    createdAt?: string;
+    updatedAt?: string;
+}
+
+/**
+ * Options for invoking an on-demand trigger.
+ */
+export interface InvokeTriggerOptions {
+    /** Custom payload/parameters to pass to the trigger execution */
+    payload?: Record<string, any>;
+}
+
+/**
+ * Options for invoking a synchronous compute endpoint.
+ */
+export interface InvokeEndpointOptions {
+    /** HTTP method (default: 'POST'). Must be in the trigger's allowedMethods. */
+    method?: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH';
+    /** Request body payload (sent as JSON). Ignored for GET/DELETE. */
+    payload?: Record<string, any>;
+    /** Additional request headers (e.g., X-API-Key for apiKey auth). */
+    headers?: Record<string, string>;
+    /** Query string parameters. */
+    query?: Record<string, string>;
+}
+
+/**
+ * Response from a synchronous compute endpoint invocation.
+ */
+export interface EndpointResponse<T = any> {
+    /** HTTP status code from the compute function */
+    status: number;
+    /** Response body from the compute function */
+    data: T;
+    /** Response headers */
+    headers: Record<string, string>;
+}
+
+// =====================================================
+// Trigger CRUD Types (Configuration-as-Code)
+// =====================================================
+
+/**
+ * Input for creating a new function trigger.
+ */
+export interface CreateTriggerInput {
+    name: string;
+    functionId: string;
+    executionType: TriggerExecutionType;
+    description?: string;
+    triggerMetadata?: Record<string, any>;
+    enabled?: boolean;
+}
+
+/**
+ * Input for updating an existing function trigger.
+ */
+export interface UpdateTriggerInput {
+    name?: string;
+    description?: string;
+    enabled?: boolean;
+    triggerMetadata?: Record<string, any>;
+}
+
+/**
+ * Options for listing all triggers (not filtered by type).
+ */
+export interface ListAllTriggersOptions {
+    page?: number;
+    limit?: number;
+    functionId?: string;
+    executionType?: TriggerExecutionType;
+    includeHealth?: boolean;
+}
+
+/**
+ * Health status of a trigger.
+ */
+export type TriggerHealthStatus = 'healthy' | 'warning' | 'error' | 'dead' | 'never_run' | 'paused';
+
+/**
+ * Health metrics for a trigger.
+ */
+export interface TriggerHealthMetrics {
+    lastRunAt: string | null;
+    successCount: number;
+    failureCount: number;
+    avgExecutionTimeMs: number;
+    totalRuns: number;
+}
+
+/**
+ * Trigger with health metrics included.
+ */
+export interface TriggerWithHealth extends FunctionTrigger {
+    health: TriggerHealthMetrics;
+    healthStatus: TriggerHealthStatus;
+}