@constructive-io/sdk 1.19.2 → 1.19.4

package/esm/modules/orm/mutation/index.d.ts

@@ -9,7 +9,7 @@ import type { InferSelectResult, StrictSelect } from '../select-types';
 import type { ConstructBlueprintInput, CopyTemplateToBlueprintInput, ProvisionBucketInput, ConstructBlueprintPayload, CopyTemplateToBlueprintPayload, ProvisionBucketPayload, ConstructBlueprintPayloadSelect, CopyTemplateToBlueprintPayloadSelect, ProvisionBucketPayloadSelect } from '../input-types';
 /**
  * Variables for constructBlueprint
- * Executes a blueprint definition by delegating to provision_* procedures. Creates a blueprint_construction record to track the attempt. Eight phases: (0) entity_type_provision for each membership_type entry — provisions entity tables, membership modules, and security. When a prefix already exists (e.g., 'org'), the entry extends the existing entity type instead of creating a new one; if a storage[] key is present, it provisions entity-scoped storage for that type. (0.5) scope-based storage: each storage[] entry has an optional scope ('app' or 'org' only). App-scoped storage seeds buckets at migration time. Org-scoped storage resolves the org membership type, creates org_buckets/org_files with owner_id, and seeds buckets per-entity via an AFTER INSERT trigger on the users table. When function_module is installed, a private functions bucket is auto-injected into org-scoped or entity-scoped storage entries. (1) provision_table() for each table with nodes[], fields[], policies[], and grants (table-level indexes/fts/unique_constraints/check_constraints are deferred). After provisioning, optional smart_tags (jsonb object) on the table entry are applied via metaschema.append_table_smart_tags(), and optional smart_tags on individual field entries are applied via metaschema.append_field_smart_tags(). (2) provision_relation() for each relation, (3) provision_index() for top-level + deferred indexes, (4) provision_full_text_search() for top-level + deferred FTS, (5) provision_unique_constraint() for top-level + deferred unique constraints, (6) provision_check_constraint() for top-level + deferred check constraints, (7) seed achievements from definition.achievements[] — resolves events_module by entity_prefix and creates INSERT actions for levels, level_requirements, and achievement_rewards tables. Phase 0 entity tables are added to the table_map so subsequent phases can reference them by name. Table-level entries are deferred to phases 3-6 so they can reference columns created by relations in phase 2. Returns the construction record ID on success, NULL on failure.
+ * Executes a blueprint definition by delegating to provision_* procedures. Creates a blueprint_construction record to track the attempt. Eight phases: (0) entity_type_provision for each membership_type entry — provisions entity tables, membership modules, and security. When a prefix already exists (e.g., 'org'), the entry extends the existing entity type instead of creating a new one; if a storage[] key is present, it provisions entity-scoped storage for that type. (0.5) scope-based storage: each storage[] entry has an optional scope ('app' or 'org' only). App-scoped storage seeds buckets at migration time. Org-scoped storage resolves the org membership type, creates org_buckets/org_files with owner_id, and seeds buckets per-entity via an AFTER INSERT trigger on the users table. When function_module is installed, a private functions bucket is auto-injected into org-scoped or entity-scoped storage entries. (1) provision_table() for each table with nodes[], fields[], policies[], and grants (table-level indexes/fts/unique_constraints/check_constraints are deferred). A table entry either names its table (table_name plus optional schema_name) or references one an installed module generated ("module": {"type": "agent", "scope": "org", "table": "message"}), which resolves through the module row's recorded table ids and raises when it matches nothing instead of creating an empty table. After provisioning, optional smart_tags (jsonb object) on the table entry are applied via metaschema.append_table_smart_tags(), and optional smart_tags on individual field entries are applied via metaschema.append_field_smart_tags(). (2) provision_relation() for each relation, (3) provision_index() for top-level + deferred indexes, (4) provision_full_text_search() for top-level + deferred FTS, (5) provision_unique_constraint() for top-level + deferred unique constraints, (6) provision_check_constraint() for top-level + deferred check constraints, (7) seed achievements from definition.achievements[] — resolves events_module by entity_prefix and creates INSERT actions for levels, level_requirements, and achievement_rewards tables. Phase 0 entity tables are added to the table_map so subsequent phases can reference them by name. Table-level entries are deferred to phases 3-6 so they can reference columns created by relations in phase 2. Returns the construction record ID on success, NULL on failure.
  */
 export interface ConstructBlueprintVariables {
     input: ConstructBlueprintInput;
@@ -23,10 +23,11 @@ export interface CopyTemplateToBlueprintVariables {
 }
 /**
  * Variables for provisionBucket
- * Provision an S3 bucket for a logical bucket in the database.
-Reads the bucket config via RLS, then creates and configures
-the S3 bucket with the appropriate privacy policies, CORS rules,
-and lifecycle settings.
+ * Reconcile an S3 bucket for a logical bucket in the database.
+Reads the bucket config via RLS, then enqueues the same
+storage:provision_bucket job used by the INSERT trigger. This is
+idempotent for an already-reconciled bucket; enqueue failures become
+GraphQL errors.
  */
 export interface ProvisionBucketVariables {
     input: ProvisionBucketInput;

package/esm/objects/orm/input-types.d.ts

@@ -718,26 +718,19 @@ export type InsertNodesAtPathsPayloadSelect = {
     result?: boolean;
 };
 export interface ProvisionBucketPayload {
-    /** The access type applied */
-    accessType: string;
-    /** The S3 bucket name that was provisioned */
-    bucketName: string;
-    /** The S3 endpoint (null for AWS S3 default) */
-    endpoint?: string | null;
-    /** Error message if provisioning failed */
-    error?: string | null;
-    /** The storage provider used */
-    provider: string;
-    /** Whether provisioning succeeded */
-    success: boolean;
+    /** The logical bucket row that was queued for reconciliation. */
+    bucketId: string;
+    bucketKey: string;
+    /** The reconciler job enqueued to provision this bucket. */
+    jobId: string;
+    /** The physical bucket name already recorded, or null when reconciliation has not completed. */
+    physicalName?: string | null;
 }
 export type ProvisionBucketPayloadSelect = {
-    accessType?: boolean;
-    bucketName?: boolean;
-    endpoint?: boolean;
-    error?: boolean;
-    provider?: boolean;
-    success?: boolean;
+    bucketId?: boolean;
+    bucketKey?: boolean;
+    jobId?: boolean;
+    physicalName?: boolean;
 };
 export interface SetAndCommitPayload {
     clientMutationId?: string | null;

package/esm/objects/orm/mutation/index.d.ts

@@ -18,10 +18,11 @@ export interface InsertNodesAtPathsVariables {
 }
 /**
  * Variables for provisionBucket
- * Provision an S3 bucket for a logical bucket in the database.
-Reads the bucket config via RLS, then creates and configures
-the S3 bucket with the appropriate privacy policies, CORS rules,
-and lifecycle settings.
+ * Reconcile an S3 bucket for a logical bucket in the database.
+Reads the bucket config via RLS, then enqueues the same
+storage:provision_bucket job used by the INSERT trigger. This is
+idempotent for an already-reconciled bucket; enqueue failures become
+GraphQL errors.
  */
 export interface ProvisionBucketVariables {
     input: ProvisionBucketInput;

package/esm/remote/index.d.ts

@@ -0,0 +1,5 @@
+/**
+ * GraphQL SDK - auto-generated, do not edit
+ * @generated by @constructive-io/graphql-codegen
+ */
+export * from './orm';

package/esm/remote/index.js

@@ -0,0 +1,5 @@
+/**
+ * GraphQL SDK - auto-generated, do not edit
+ * @generated by @constructive-io/graphql-codegen
+ */
+export * from './orm';

package/esm/remote/orm/client.d.ts

@@ -0,0 +1,97 @@
+/**
+ * ORM Client - Runtime GraphQL executor
+ * @generated by @constructive-io/graphql-codegen
+ * DO NOT EDIT - changes will be overwritten
+ */
+import type { GraphQLAdapter, GraphQLError, QueryResult } from '@constructive-io/graphql-query/runtime';
+import type { ConnectionState, ConnectionStateListener, RealtimeConfig, SubscriptionEvent, SubscriptionFieldMeta, Unsubscribe } from './realtime';
+export type { GraphQLAdapter, GraphQLError, QueryResult, } from '@constructive-io/graphql-query/runtime';
+export type { ConnectionState, ConnectionStateListener, RealtimeConfig, SubscribeOptions, SubscriptionEvent, SubscriptionFieldMeta, SubscriptionOperation, Unsubscribe, WsClient, } from './realtime';
+export { RealtimeManager } from './realtime';
+/**
+ * Default adapter that uses fetch for HTTP requests.
+ *
+ * When no custom fetch is provided, uses @constructive-io/fetch which
+ * handles *.localhost DNS rewriting and Host header preservation in
+ * Node.js. Pass a custom fetch to override for test mocking or custom
+ * proxy/credentials.
+ */
+export declare class FetchAdapter implements GraphQLAdapter {
+    private endpoint;
+    private headers;
+    private fetchFn;
+    constructor(endpoint: string, headers?: Record<string, string>, fetchFn?: typeof globalThis.fetch);
+    execute<T>(document: string, variables?: Record<string, unknown>): Promise<QueryResult<T>>;
+    setHeaders(headers: Record<string, string>): void;
+    getEndpoint(): string;
+}
+/**
+ * Configuration for creating an ORM client.
+ * Either provide endpoint (and optional headers/fetch) for HTTP requests,
+ * or provide a custom adapter for alternative execution strategies.
+ */
+export interface OrmClientConfig {
+    /** GraphQL endpoint URL (required if adapter not provided) */
+    endpoint?: string;
+    /** Default headers for HTTP requests (only used with endpoint) */
+    headers?: Record<string, string>;
+    /**
+     * Custom fetch implementation. Defaults to createFetch() from
+     * @constructive-io/graphql-query/runtime which handles *.localhost
+     * DNS and Host headers in Node.js. Pass your own for test mocking
+     * or custom proxy/credentials.
+     */
+    fetch?: typeof globalThis.fetch;
+    /** Custom adapter for GraphQL execution (overrides endpoint/headers/fetch) */
+    adapter?: GraphQLAdapter;
+    /**
+     * Optional realtime (WebSocket) configuration.
+     * When provided, enables subscription methods on models.
+     * The WebSocket connection is created lazily on first subscribe().
+     */
+    realtime?: RealtimeConfig;
+}
+/**
+ * Error thrown when GraphQL request fails
+ */
+export declare class GraphQLRequestError extends Error {
+    readonly errors: GraphQLError[];
+    readonly data: unknown;
+    constructor(errors: GraphQLError[], data?: unknown);
+}
+export declare class OrmClient {
+    private adapter;
+    private realtimeManager?;
+    constructor(config: OrmClientConfig);
+    execute<T>(document: string, variables?: Record<string, unknown>): Promise<QueryResult<T>>;
+    /**
+     * Subscribe to a GraphQL subscription operation.
+     * Used by generated model subscribe() methods.
+     * @throws Error if realtime is not configured
+     */
+    subscribe<T>(meta: SubscriptionFieldMeta, document: string, variables: Record<string, unknown>, options: {
+        onEvent: (event: SubscriptionEvent<T>) => void;
+        onError?: (error: Error) => void;
+        onComplete?: () => void;
+    }): Unsubscribe;
+    /**
+     * Set headers for requests.
+     * Only works if the adapter supports headers.
+     */
+    setHeaders(headers: Record<string, string>): void;
+    /**
+     * Get the endpoint URL.
+     * Returns empty string if the adapter doesn't have an endpoint.
+     */
+    getEndpoint(): string;
+    /** Get current WebSocket connection state */
+    getConnectionState(): ConnectionState;
+    /** Register a listener for WebSocket connection state changes */
+    onConnectionStateChange(listener: ConnectionStateListener): Unsubscribe;
+    /** Number of active subscriptions */
+    getActiveSubscriptionCount(): number;
+    /** Whether realtime is configured */
+    get isRealtimeEnabled(): boolean;
+    /** Dispose the realtime manager (close WebSocket) */
+    dispose(): void;
+}

package/esm/remote/orm/client.js

@@ -0,0 +1,155 @@
+import { createFetch } from '@constructive-io/graphql-query/runtime';
+import { RealtimeManager } from './realtime';
+export { RealtimeManager } from './realtime';
+/**
+ * Default adapter that uses fetch for HTTP requests.
+ *
+ * When no custom fetch is provided, uses @constructive-io/fetch which
+ * handles *.localhost DNS rewriting and Host header preservation in
+ * Node.js. Pass a custom fetch to override for test mocking or custom
+ * proxy/credentials.
+ */
+export class FetchAdapter {
+    endpoint;
+    headers;
+    fetchFn;
+    constructor(endpoint, headers, fetchFn) {
+        this.endpoint = endpoint;
+        this.headers = headers ?? {};
+        this.fetchFn = (fetchFn ?? createFetch()).bind(globalThis);
+    }
+    async execute(document, variables) {
+        const response = await this.fetchFn(this.endpoint, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                Accept: 'application/json',
+                ...this.headers,
+            },
+            body: JSON.stringify({
+                query: document,
+                variables: variables ?? {},
+            }),
+        });
+        if (!response.ok) {
+            return {
+                ok: false,
+                data: null,
+                errors: [{ message: `HTTP ${response.status}: ${response.statusText}` }],
+            };
+        }
+        const json = (await response.json());
+        if (json.errors && json.errors.length > 0) {
+            return {
+                ok: false,
+                data: null,
+                errors: json.errors,
+            };
+        }
+        return {
+            ok: true,
+            data: json.data,
+            errors: undefined,
+        };
+    }
+    setHeaders(headers) {
+        this.headers = { ...this.headers, ...headers };
+    }
+    getEndpoint() {
+        return this.endpoint;
+    }
+}
+/**
+ * Describe a single GraphQL error, falling back to its `extensions.code` when
+ * the server omits `message` so the error never renders as an empty string.
+ */
+function describeGraphQLError(error) {
+    if (error.message)
+        return error.message;
+    const code = error.extensions?.code;
+    return typeof code === 'string' ? code : 'Unknown error';
+}
+/**
+ * Error thrown when GraphQL request fails
+ */
+export class GraphQLRequestError extends Error {
+    errors;
+    data;
+    constructor(errors, data = null) {
+        const messages = errors.map(describeGraphQLError).join('; ');
+        super(`GraphQL Error: ${messages}`);
+        this.errors = errors;
+        this.data = data;
+        this.name = 'GraphQLRequestError';
+    }
+}
+export class OrmClient {
+    adapter;
+    realtimeManager;
+    constructor(config) {
+        if (config.adapter) {
+            this.adapter = config.adapter;
+        }
+        else if (config.endpoint) {
+            this.adapter = new FetchAdapter(config.endpoint, config.headers, config.fetch);
+        }
+        else {
+            throw new Error('OrmClientConfig requires either an endpoint or a custom adapter');
+        }
+        if (config.realtime) {
+            this.realtimeManager = new RealtimeManager(config.realtime);
+        }
+    }
+    async execute(document, variables) {
+        return this.adapter.execute(document, variables);
+    }
+    /**
+     * Subscribe to a GraphQL subscription operation.
+     * Used by generated model subscribe() methods.
+     * @throws Error if realtime is not configured
+     */
+    subscribe(meta, document, variables, options) {
+        if (!this.realtimeManager) {
+            throw new Error('Realtime not configured. Pass a `realtime` option to createClient() to enable subscriptions.');
+        }
+        return this.realtimeManager.subscribe(meta, document, variables, options);
+    }
+    /**
+     * Set headers for requests.
+     * Only works if the adapter supports headers.
+     */
+    setHeaders(headers) {
+        if (this.adapter.setHeaders) {
+            this.adapter.setHeaders(headers);
+        }
+    }
+    /**
+     * Get the endpoint URL.
+     * Returns empty string if the adapter doesn't have an endpoint.
+     */
+    getEndpoint() {
+        return this.adapter.getEndpoint?.() ?? '';
+    }
+    /** Get current WebSocket connection state */
+    getConnectionState() {
+        return this.realtimeManager?.getConnectionState() ?? 'disconnected';
+    }
+    /** Register a listener for WebSocket connection state changes */
+    onConnectionStateChange(listener) {
+        if (!this.realtimeManager)
+            return () => { };
+        return this.realtimeManager.onConnectionStateChange(listener);
+    }
+    /** Number of active subscriptions */
+    getActiveSubscriptionCount() {
+        return this.realtimeManager?.getActiveSubscriptionCount() ?? 0;
+    }
+    /** Whether realtime is configured */
+    get isRealtimeEnabled() {
+        return this.realtimeManager !== undefined;
+    }
+    /** Dispose the realtime manager (close WebSocket) */
+    dispose() {
+        this.realtimeManager?.dispose();
+    }
+}

package/esm/remote/orm/index.d.ts

@@ -0,0 +1,50 @@
+import type { OrmClientConfig } from './client';
+import { MachineModel } from './models/machine';
+import { MachineMessageModel } from './models/machineMessage';
+import { MachineSessionModel } from './models/machineSession';
+export type { OrmClientConfig, QueryResult, GraphQLError, GraphQLAdapter } from './client';
+export { GraphQLRequestError, FetchAdapter } from './client';
+export { QueryBuilder } from './query-builder';
+export * from './select-types';
+export * from './models';
+export { createMutationOperations } from './mutation';
+/**
+ * Create an ORM client instance
+ *
+ * @example
+ * ```typescript
+ * const db = createClient({
+ *   endpoint: 'https://api.example.com/graphql',
+ *   headers: { Authorization: 'Bearer token' },
+ * });
+ *
+ * // Query users
+ * const users = await db.user.findMany({
+ *   select: { id: true, name: true },
+ *   first: 10,
+ * }).execute();
+ *
+ * // Create a user
+ * const newUser = await db.user.create({
+ *   data: { name: 'John', email: 'john@example.com' },
+ *   select: { id: true },
+ * }).execute();
+ * ```
+ */
+export declare function createClient(config: OrmClientConfig): {
+    machine: MachineModel;
+    machineMessage: MachineMessageModel;
+    machineSession: MachineSessionModel;
+    mutation: {
+        machinesEnroll: <S extends import("./input-types").MachinesEnrollPayloadSelect>(args: import("./mutation").MachinesEnrollVariables, options: {
+            select: S;
+        } & import("./select-types").StrictSelect<S, import("./input-types").MachinesEnrollPayloadSelect>) => import("./query-builder").QueryBuilder<{
+            machinesEnroll: import("./select-types").InferSelectResult<import("./input-types").MachinesEnrollPayload, S> | null;
+        }>;
+        provisionBucket: <S extends import("./input-types").ProvisionBucketPayloadSelect>(args: import("./mutation").ProvisionBucketVariables, options: {
+            select: S;
+        } & import("./select-types").StrictSelect<S, import("./input-types").ProvisionBucketPayloadSelect>) => import("./query-builder").QueryBuilder<{
+            provisionBucket: import("./select-types").InferSelectResult<import("./input-types").ProvisionBucketPayload, S> | null;
+        }>;
+    };
+};

package/esm/remote/orm/index.js

@@ -0,0 +1,47 @@
+/**
+ * ORM Client - createClient factory
+ * @generated by @constructive-io/graphql-codegen
+ * DO NOT EDIT - changes will be overwritten
+ */
+import { OrmClient } from './client';
+import { MachineModel } from './models/machine';
+import { MachineMessageModel } from './models/machineMessage';
+import { MachineSessionModel } from './models/machineSession';
+import { createMutationOperations } from './mutation';
+export { GraphQLRequestError, FetchAdapter } from './client';
+export { QueryBuilder } from './query-builder';
+export * from './select-types';
+export * from './models';
+export { createMutationOperations } from './mutation';
+/**
+ * Create an ORM client instance
+ *
+ * @example
+ * ```typescript
+ * const db = createClient({
+ *   endpoint: 'https://api.example.com/graphql',
+ *   headers: { Authorization: 'Bearer token' },
+ * });
+ *
+ * // Query users
+ * const users = await db.user.findMany({
+ *   select: { id: true, name: true },
+ *   first: 10,
+ * }).execute();
+ *
+ * // Create a user
+ * const newUser = await db.user.create({
+ *   data: { name: 'John', email: 'john@example.com' },
+ *   select: { id: true },
+ * }).execute();
+ * ```
+ */
+export function createClient(config) {
+    const client = new OrmClient(config);
+    return {
+        machine: new MachineModel(client),
+        machineMessage: new MachineMessageModel(client),
+        machineSession: new MachineSessionModel(client),
+        mutation: createMutationOperations(client),
+    };
+}