@constructive-io/sdk 0.20.6 → 0.20.8

package/esm/public/orm/client.js

@@ -1,4 +1,6 @@
 import { createFetch } from '@constructive-io/graphql-query/runtime';
+import { RealtimeManager } from './realtime';
+export { RealtimeManager } from './realtime';
 /**
  * Default adapter that uses fetch for HTTP requests.
  *
@@ -73,6 +75,7 @@ export class GraphQLRequestError extends Error {
 }
 export class OrmClient {
     adapter;
+    realtimeManager;
     constructor(config) {
         if (config.adapter) {
             this.adapter = config.adapter;
@@ -83,10 +86,24 @@ export class OrmClient {
         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.
@@ -103,4 +120,26 @@ export class OrmClient {
     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/public/orm/index.d.ts

@@ -569,10 +569,15 @@ export declare function createClient(config: OrmClientConfig): {
         } & import("./select-types").StrictSelect<S, import("./input-types").SetFieldOrderPayloadSelect>) => import("./query-builder").QueryBuilder<{
             setFieldOrder: import("./select-types").InferSelectResult<import("./input-types").SetFieldOrderPayload, S> | null;
         }>;
-        appendSmartTags: <S extends import("./input-types").AppendSmartTagsPayloadSelect>(args: import("./mutation").AppendSmartTagsVariables, options: {
+        appendFieldSmartTags: <S extends import("./input-types").AppendFieldSmartTagsPayloadSelect>(args: import("./mutation").AppendFieldSmartTagsVariables, options: {
             select: S;
-        } & import("./select-types").StrictSelect<S, import("./input-types").AppendSmartTagsPayloadSelect>) => import("./query-builder").QueryBuilder<{
-            appendSmartTags: import("./select-types").InferSelectResult<import("./input-types").AppendSmartTagsPayload, S> | null;
+        } & import("./select-types").StrictSelect<S, import("./input-types").AppendFieldSmartTagsPayloadSelect>) => import("./query-builder").QueryBuilder<{
+            appendFieldSmartTags: import("./select-types").InferSelectResult<import("./input-types").AppendFieldSmartTagsPayload, S> | null;
+        }>;
+        appendTableSmartTags: <S extends import("./input-types").AppendTableSmartTagsPayloadSelect>(args: import("./mutation").AppendTableSmartTagsVariables, options: {
+            select: S;
+        } & import("./select-types").StrictSelect<S, import("./input-types").AppendTableSmartTagsPayloadSelect>) => import("./query-builder").QueryBuilder<{
+            appendTableSmartTags: import("./select-types").InferSelectResult<import("./input-types").AppendTableSmartTagsPayload, S> | null;
         }>;
         provisionUniqueConstraint: <S extends import("./input-types").ProvisionUniqueConstraintPayloadSelect>(args: import("./mutation").ProvisionUniqueConstraintVariables, options: {
             select: S;

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

@@ -19201,7 +19201,12 @@ export interface SetFieldOrderInput {
     clientMutationId?: string;
     fieldIds?: string[];
 }
-export interface AppendSmartTagsInput {
+export interface AppendFieldSmartTagsInput {
+    clientMutationId?: string;
+    pFieldId?: string;
+    pTags?: Record<string, unknown>;
+}
+export interface AppendTableSmartTagsInput {
     clientMutationId?: string;
     pTableId?: string;
     pTags?: Record<string, unknown>;
@@ -27717,10 +27722,16 @@ export interface SetFieldOrderPayload {
 export type SetFieldOrderPayloadSelect = {
     clientMutationId?: boolean;
 };
-export interface AppendSmartTagsPayload {
+export interface AppendFieldSmartTagsPayload {
+    clientMutationId?: string | null;
+}
+export type AppendFieldSmartTagsPayloadSelect = {
+    clientMutationId?: boolean;
+};
+export interface AppendTableSmartTagsPayload {
     clientMutationId?: string | null;
 }
-export type AppendSmartTagsPayloadSelect = {
+export type AppendTableSmartTagsPayloadSelect = {
     clientMutationId?: boolean;
 };
 export interface ProvisionUniqueConstraintPayload {

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

@@ -6,7 +6,7 @@
 import { OrmClient } from '../client';
 import { QueryBuilder } from '../query-builder';
 import type { InferSelectResult, StrictSelect } from '../select-types';
-import type { SendAccountDeletionEmailInput, SignOutInput, AcceptDatabaseTransferInput, CancelDatabaseTransferInput, RejectDatabaseTransferInput, DisconnectAccountInput, RevokeApiKeyInput, RevokeSessionInput, VerifyPasswordInput, VerifyTotpInput, SubmitAppInviteCodeInput, SubmitOrgInviteCodeInput, CheckPasswordInput, ConfirmDeleteAccountInput, SetPasswordInput, VerifyEmailInput, FreezeObjectsInput, InitEmptyRepoInput, ConstructBlueprintInput, ProvisionNewUserInput, ResetPasswordInput, RemoveNodeAtPathInput, CopyTemplateToBlueprintInput, ProvisionSpatialRelationInput, BootstrapUserInput, SetFieldOrderInput, AppendSmartTagsInput, ProvisionUniqueConstraintInput, ProvisionFullTextSearchInput, ProvisionIndexInput, SetDataAtPathInput, SetPropsAndCommitInput, ProvisionDatabaseWithUserInput, InsertNodeAtPathInput, UpdateNodeAtPathInput, SetAndCommitInput, ProvisionRelationInput, ApplyRlsInput, SignInCrossOriginInput, CreateUserDatabaseInput, ExtendTokenExpiresInput, CreateApiKeyInput, SendVerificationEmailInput, ForgotPasswordInput, SignUpInput, RequestCrossOriginTokenInput, SignInInput, ProvisionTableInput, ProvisionBucketInput, SendAccountDeletionEmailPayload, SignOutPayload, AcceptDatabaseTransferPayload, CancelDatabaseTransferPayload, RejectDatabaseTransferPayload, DisconnectAccountPayload, RevokeApiKeyPayload, RevokeSessionPayload, VerifyPasswordPayload, VerifyTotpPayload, SubmitAppInviteCodePayload, SubmitOrgInviteCodePayload, CheckPasswordPayload, ConfirmDeleteAccountPayload, SetPasswordPayload, VerifyEmailPayload, FreezeObjectsPayload, InitEmptyRepoPayload, ConstructBlueprintPayload, ProvisionNewUserPayload, ResetPasswordPayload, RemoveNodeAtPathPayload, CopyTemplateToBlueprintPayload, ProvisionSpatialRelationPayload, BootstrapUserPayload, SetFieldOrderPayload, AppendSmartTagsPayload, ProvisionUniqueConstraintPayload, ProvisionFullTextSearchPayload, ProvisionIndexPayload, SetDataAtPathPayload, SetPropsAndCommitPayload, ProvisionDatabaseWithUserPayload, InsertNodeAtPathPayload, UpdateNodeAtPathPayload, SetAndCommitPayload, ProvisionRelationPayload, ApplyRlsPayload, SignInCrossOriginPayload, CreateUserDatabasePayload, ExtendTokenExpiresPayload, CreateApiKeyPayload, SendVerificationEmailPayload, ForgotPasswordPayload, SignUpPayload, RequestCrossOriginTokenPayload, SignInPayload, ProvisionTablePayload, ProvisionBucketPayload, SendAccountDeletionEmailPayloadSelect, SignOutPayloadSelect, AcceptDatabaseTransferPayloadSelect, CancelDatabaseTransferPayloadSelect, RejectDatabaseTransferPayloadSelect, DisconnectAccountPayloadSelect, RevokeApiKeyPayloadSelect, RevokeSessionPayloadSelect, VerifyPasswordPayloadSelect, VerifyTotpPayloadSelect, SubmitAppInviteCodePayloadSelect, SubmitOrgInviteCodePayloadSelect, CheckPasswordPayloadSelect, ConfirmDeleteAccountPayloadSelect, SetPasswordPayloadSelect, VerifyEmailPayloadSelect, FreezeObjectsPayloadSelect, InitEmptyRepoPayloadSelect, ConstructBlueprintPayloadSelect, ProvisionNewUserPayloadSelect, ResetPasswordPayloadSelect, RemoveNodeAtPathPayloadSelect, CopyTemplateToBlueprintPayloadSelect, ProvisionSpatialRelationPayloadSelect, BootstrapUserPayloadSelect, SetFieldOrderPayloadSelect, AppendSmartTagsPayloadSelect, ProvisionUniqueConstraintPayloadSelect, ProvisionFullTextSearchPayloadSelect, ProvisionIndexPayloadSelect, SetDataAtPathPayloadSelect, SetPropsAndCommitPayloadSelect, ProvisionDatabaseWithUserPayloadSelect, InsertNodeAtPathPayloadSelect, UpdateNodeAtPathPayloadSelect, SetAndCommitPayloadSelect, ProvisionRelationPayloadSelect, ApplyRlsPayloadSelect, SignInCrossOriginPayloadSelect, CreateUserDatabasePayloadSelect, ExtendTokenExpiresPayloadSelect, CreateApiKeyPayloadSelect, SendVerificationEmailPayloadSelect, ForgotPasswordPayloadSelect, SignUpPayloadSelect, RequestCrossOriginTokenPayloadSelect, SignInPayloadSelect, ProvisionTablePayloadSelect, ProvisionBucketPayloadSelect } from '../input-types';
+import type { SendAccountDeletionEmailInput, SignOutInput, AcceptDatabaseTransferInput, CancelDatabaseTransferInput, RejectDatabaseTransferInput, DisconnectAccountInput, RevokeApiKeyInput, RevokeSessionInput, VerifyPasswordInput, VerifyTotpInput, SubmitAppInviteCodeInput, SubmitOrgInviteCodeInput, CheckPasswordInput, ConfirmDeleteAccountInput, SetPasswordInput, VerifyEmailInput, FreezeObjectsInput, InitEmptyRepoInput, ConstructBlueprintInput, ProvisionNewUserInput, ResetPasswordInput, RemoveNodeAtPathInput, CopyTemplateToBlueprintInput, ProvisionSpatialRelationInput, BootstrapUserInput, SetFieldOrderInput, AppendFieldSmartTagsInput, AppendTableSmartTagsInput, ProvisionUniqueConstraintInput, ProvisionFullTextSearchInput, ProvisionIndexInput, SetDataAtPathInput, SetPropsAndCommitInput, ProvisionDatabaseWithUserInput, InsertNodeAtPathInput, UpdateNodeAtPathInput, SetAndCommitInput, ProvisionRelationInput, ApplyRlsInput, SignInCrossOriginInput, CreateUserDatabaseInput, ExtendTokenExpiresInput, CreateApiKeyInput, SendVerificationEmailInput, ForgotPasswordInput, SignUpInput, RequestCrossOriginTokenInput, SignInInput, ProvisionTableInput, ProvisionBucketInput, SendAccountDeletionEmailPayload, SignOutPayload, AcceptDatabaseTransferPayload, CancelDatabaseTransferPayload, RejectDatabaseTransferPayload, DisconnectAccountPayload, RevokeApiKeyPayload, RevokeSessionPayload, VerifyPasswordPayload, VerifyTotpPayload, SubmitAppInviteCodePayload, SubmitOrgInviteCodePayload, CheckPasswordPayload, ConfirmDeleteAccountPayload, SetPasswordPayload, VerifyEmailPayload, FreezeObjectsPayload, InitEmptyRepoPayload, ConstructBlueprintPayload, ProvisionNewUserPayload, ResetPasswordPayload, RemoveNodeAtPathPayload, CopyTemplateToBlueprintPayload, ProvisionSpatialRelationPayload, BootstrapUserPayload, SetFieldOrderPayload, AppendFieldSmartTagsPayload, AppendTableSmartTagsPayload, ProvisionUniqueConstraintPayload, ProvisionFullTextSearchPayload, ProvisionIndexPayload, SetDataAtPathPayload, SetPropsAndCommitPayload, ProvisionDatabaseWithUserPayload, InsertNodeAtPathPayload, UpdateNodeAtPathPayload, SetAndCommitPayload, ProvisionRelationPayload, ApplyRlsPayload, SignInCrossOriginPayload, CreateUserDatabasePayload, ExtendTokenExpiresPayload, CreateApiKeyPayload, SendVerificationEmailPayload, ForgotPasswordPayload, SignUpPayload, RequestCrossOriginTokenPayload, SignInPayload, ProvisionTablePayload, ProvisionBucketPayload, SendAccountDeletionEmailPayloadSelect, SignOutPayloadSelect, AcceptDatabaseTransferPayloadSelect, CancelDatabaseTransferPayloadSelect, RejectDatabaseTransferPayloadSelect, DisconnectAccountPayloadSelect, RevokeApiKeyPayloadSelect, RevokeSessionPayloadSelect, VerifyPasswordPayloadSelect, VerifyTotpPayloadSelect, SubmitAppInviteCodePayloadSelect, SubmitOrgInviteCodePayloadSelect, CheckPasswordPayloadSelect, ConfirmDeleteAccountPayloadSelect, SetPasswordPayloadSelect, VerifyEmailPayloadSelect, FreezeObjectsPayloadSelect, InitEmptyRepoPayloadSelect, ConstructBlueprintPayloadSelect, ProvisionNewUserPayloadSelect, ResetPasswordPayloadSelect, RemoveNodeAtPathPayloadSelect, CopyTemplateToBlueprintPayloadSelect, ProvisionSpatialRelationPayloadSelect, BootstrapUserPayloadSelect, SetFieldOrderPayloadSelect, AppendFieldSmartTagsPayloadSelect, AppendTableSmartTagsPayloadSelect, ProvisionUniqueConstraintPayloadSelect, ProvisionFullTextSearchPayloadSelect, ProvisionIndexPayloadSelect, SetDataAtPathPayloadSelect, SetPropsAndCommitPayloadSelect, ProvisionDatabaseWithUserPayloadSelect, InsertNodeAtPathPayloadSelect, UpdateNodeAtPathPayloadSelect, SetAndCommitPayloadSelect, ProvisionRelationPayloadSelect, ApplyRlsPayloadSelect, SignInCrossOriginPayloadSelect, CreateUserDatabasePayloadSelect, ExtendTokenExpiresPayloadSelect, CreateApiKeyPayloadSelect, SendVerificationEmailPayloadSelect, ForgotPasswordPayloadSelect, SignUpPayloadSelect, RequestCrossOriginTokenPayloadSelect, SignInPayloadSelect, ProvisionTablePayloadSelect, ProvisionBucketPayloadSelect } from '../input-types';
 export interface SendAccountDeletionEmailVariables {
     input: SendAccountDeletionEmailInput;
 }
@@ -97,8 +97,11 @@ export interface BootstrapUserVariables {
 export interface SetFieldOrderVariables {
     input: SetFieldOrderInput;
 }
-export interface AppendSmartTagsVariables {
-    input: AppendSmartTagsInput;
+export interface AppendFieldSmartTagsVariables {
+    input: AppendFieldSmartTagsInput;
+}
+export interface AppendTableSmartTagsVariables {
+    input: AppendTableSmartTagsInput;
 }
 /**
  * Variables for provisionUniqueConstraint
@@ -343,10 +346,15 @@ export declare function createMutationOperations(client: OrmClient): {
     } & StrictSelect<S, SetFieldOrderPayloadSelect>) => QueryBuilder<{
         setFieldOrder: InferSelectResult<SetFieldOrderPayload, S> | null;
     }>;
-    appendSmartTags: <S extends AppendSmartTagsPayloadSelect>(args: AppendSmartTagsVariables, options: {
+    appendFieldSmartTags: <S extends AppendFieldSmartTagsPayloadSelect>(args: AppendFieldSmartTagsVariables, options: {
+        select: S;
+    } & StrictSelect<S, AppendFieldSmartTagsPayloadSelect>) => QueryBuilder<{
+        appendFieldSmartTags: InferSelectResult<AppendFieldSmartTagsPayload, S> | null;
+    }>;
+    appendTableSmartTags: <S extends AppendTableSmartTagsPayloadSelect>(args: AppendTableSmartTagsVariables, options: {
         select: S;
-    } & StrictSelect<S, AppendSmartTagsPayloadSelect>) => QueryBuilder<{
-        appendSmartTags: InferSelectResult<AppendSmartTagsPayload, S> | null;
+    } & StrictSelect<S, AppendTableSmartTagsPayloadSelect>) => QueryBuilder<{
+        appendTableSmartTags: InferSelectResult<AppendTableSmartTagsPayload, S> | null;
     }>;
     provisionUniqueConstraint: <S extends ProvisionUniqueConstraintPayloadSelect>(args: ProvisionUniqueConstraintVariables, options: {
         select: S;

package/esm/public/orm/mutation/index.js

@@ -314,17 +314,29 @@ export function createMutationOperations(client) {
                 },
             ], connectionFieldsMap, 'SetFieldOrderPayload'),
         }),
-        appendSmartTags: (args, options) => new QueryBuilder({
+        appendFieldSmartTags: (args, options) => new QueryBuilder({
             client,
             operation: 'mutation',
-            operationName: 'AppendSmartTags',
-            fieldName: 'appendSmartTags',
-            ...buildCustomDocument('mutation', 'AppendSmartTags', 'appendSmartTags', options.select, args, [
+            operationName: 'AppendFieldSmartTags',
+            fieldName: 'appendFieldSmartTags',
+            ...buildCustomDocument('mutation', 'AppendFieldSmartTags', 'appendFieldSmartTags', options.select, args, [
                 {
                     name: 'input',
-                    type: 'AppendSmartTagsInput!',
+                    type: 'AppendFieldSmartTagsInput!',
                 },
-            ], connectionFieldsMap, 'AppendSmartTagsPayload'),
+            ], connectionFieldsMap, 'AppendFieldSmartTagsPayload'),
+        }),
+        appendTableSmartTags: (args, options) => new QueryBuilder({
+            client,
+            operation: 'mutation',
+            operationName: 'AppendTableSmartTags',
+            fieldName: 'appendTableSmartTags',
+            ...buildCustomDocument('mutation', 'AppendTableSmartTags', 'appendTableSmartTags', options.select, args, [
+                {
+                    name: 'input',
+                    type: 'AppendTableSmartTagsInput!',
+                },
+            ], connectionFieldsMap, 'AppendTableSmartTagsPayload'),
         }),
         provisionUniqueConstraint: (args, options) => new QueryBuilder({
             client,

package/esm/public/orm/realtime.d.ts

@@ -0,0 +1,142 @@
+/**
+ * Realtime Manager - WebSocket subscription support
+ * @generated by @constructive-io/graphql-codegen
+ * DO NOT EDIT - changes will be overwritten
+ */
+interface WsGraphQLError {
+    readonly message: string;
+    readonly [key: string]: unknown;
+}
+interface WsExecutionResult<TData = Record<string, unknown>> {
+    data?: TData | null;
+    errors?: readonly WsGraphQLError[];
+    extensions?: Record<string, unknown>;
+}
+interface WsSink<T> {
+    next(value: T): void;
+    error(error: unknown): void;
+    complete(): void;
+}
+/**
+ * Minimal interface matching the graphql-ws Client.
+ * Consumers pass a concrete instance via RealtimeConfig.client.
+ */
+export interface WsClient {
+    subscribe<TData = Record<string, unknown>>(payload: {
+        query: string;
+        variables?: Record<string, unknown>;
+    }, sink: WsSink<WsExecutionResult<TData>>): () => void;
+    dispose(): void;
+}
+/** The DML operation that triggered the subscription event */
+export type SubscriptionOperation = 'INSERT' | 'UPDATE' | 'DELETE';
+/** Connection state of the WebSocket */
+export type ConnectionState = 'disconnected' | 'connecting' | 'connected' | 'reconnecting';
+/** Listener for connection state changes */
+export type ConnectionStateListener = (state: ConnectionState) => void;
+/** Function returned by subscribe() to cancel the subscription */
+export type Unsubscribe = () => void;
+/**
+ * A realtime subscription event delivered to the client.
+ *
+ * @typeParam T - The row type of the subscribed table
+ */
+export interface SubscriptionEvent<T> {
+    /** The DML operation that triggered this event */
+    operation: SubscriptionOperation;
+    /** The current row data (null for DELETE if row is no longer visible) */
+    data: T | null;
+    /** Previous field values (populated on UPDATE when available) */
+    previousValues?: Partial<T>;
+    /** Server-side timestamp of when the change occurred */
+    timestamp: string;
+}
+/**
+ * Options for creating a subscription.
+ *
+ * @typeParam T - The row type of the subscribed table
+ * @typeParam TFilter - The filter type for the table
+ */
+export interface SubscribeOptions<T, TFilter = Record<string, unknown>> {
+    /** Server-side filter to limit which events are delivered */
+    filter?: TFilter;
+    /** Called when a subscription event is received */
+    onEvent: (event: SubscriptionEvent<T>) => void;
+    /** Called when the subscription encounters an error */
+    onError?: (error: Error) => void;
+    /** Called when the subscription completes (server-initiated close) */
+    onComplete?: () => void;
+}
+/**
+ * Metadata about a subscription field, used internally to map
+ * table names to GraphQL subscription field names and types.
+ */
+export interface SubscriptionFieldMeta {
+    /** The GraphQL subscription field name (e.g., 'onContactChanged') */
+    fieldName: string;
+    /** The table name in the source schema (e.g., 'contact') */
+    tableName: string;
+    /** The data field name inside the subscription payload (e.g., 'contact') */
+    dataFieldName: string;
+}
+/**
+ * Configuration for the realtime (WebSocket) connection.
+ * Pass this as the `realtime` option in OrmClientConfig.
+ *
+ * @example
+ * ```ts
+ * import { createClient } from 'graphql-ws';
+ *
+ * const client = createOrmClient({
+ *   endpoint: 'https://api.example.com/graphql',
+ *   realtime: {
+ *     client: createClient({ url: 'wss://api.example.com/graphql' }),
+ *   },
+ * });
+ * ```
+ */
+export interface RealtimeConfig {
+    /**
+     * A graphql-ws Client instance (or any object satisfying WsClient).
+     * The consumer creates this themselves, giving full control over
+     * connection options, auth, and transport.
+     *
+     * @example
+     * ```ts
+     * import { createClient } from 'graphql-ws';
+     * const wsClient = createClient({ url: 'wss://...' });
+     * ```
+     */
+    client: WsClient;
+}
+/**
+ * Manages a graphql-ws WebSocket client and multiplexes
+ * subscriptions over it. Created by OrmClient when `realtime`
+ * config is provided.
+ */
+export declare class RealtimeManager {
+    private wsClient;
+    private connectionState;
+    private stateListeners;
+    private activeSubscriptions;
+    constructor(config: RealtimeConfig);
+    /**
+     * Subscribe to a GraphQL subscription operation.
+     * Models call this with typed metadata and documents.
+     */
+    subscribe<T>(meta: SubscriptionFieldMeta, document: string, variables: Record<string, unknown>, options: {
+        onEvent: (event: SubscriptionEvent<T>) => void;
+        onError?: (error: Error) => void;
+        onComplete?: () => void;
+    }): Unsubscribe;
+    /** Register a listener for connection state changes */
+    onConnectionStateChange(listener: ConnectionStateListener): Unsubscribe;
+    /** Get current connection state */
+    getConnectionState(): ConnectionState;
+    /** Number of active subscriptions */
+    getActiveSubscriptionCount(): number;
+    /** Dispose the manager and close the WebSocket connection */
+    dispose(): void;
+    private setConnectionState;
+}
+export {};

package/esm/public/orm/realtime.js

@@ -0,0 +1,100 @@
+/**
+ * Realtime Manager - WebSocket subscription support
+ * @generated by @constructive-io/graphql-codegen
+ * DO NOT EDIT - changes will be overwritten
+ */
+// Minimal type shims so this module compiles without graphql-ws
+// installed.  Consumers supply a WsClient via RealtimeConfig;
+// the SDK itself never imports or requires graphql-ws.
+// ============================================================================
+// RealtimeManager
+// ============================================================================
+/**
+ * Manages a graphql-ws WebSocket client and multiplexes
+ * subscriptions over it. Created by OrmClient when `realtime`
+ * config is provided.
+ */
+export class RealtimeManager {
+    wsClient;
+    connectionState = 'disconnected';
+    stateListeners = new Set();
+    activeSubscriptions = 0;
+    constructor(config) {
+        this.wsClient = config.client;
+    }
+    /**
+     * Subscribe to a GraphQL subscription operation.
+     * Models call this with typed metadata and documents.
+     */
+    subscribe(meta, document, variables, options) {
+        this.activeSubscriptions++;
+        let disposed = false;
+        const cleanup = this.wsClient.subscribe({ query: document, variables }, {
+            next: (result) => {
+                if (disposed)
+                    return;
+                if (result.errors) {
+                    options.onError?.(new Error(result.errors.map((e) => e.message).join('; ')));
+                    return;
+                }
+                const payload = result.data?.[meta.fieldName];
+                if (!payload)
+                    return;
+                const event = {
+                    operation: payload.event ?? 'UPDATE',
+                    data: payload[meta.dataFieldName] ?? null,
+                    previousValues: payload.previousValues,
+                    timestamp: payload.timestamp ?? new Date().toISOString(),
+                };
+                options.onEvent(event);
+            },
+            error: (err) => {
+                if (disposed)
+                    return;
+                options.onError?.(err instanceof Error ? err : new Error(String(err)));
+            },
+            complete: () => {
+                if (disposed)
+                    return;
+                options.onComplete?.();
+            },
+        });
+        return () => {
+            if (disposed)
+                return;
+            disposed = true;
+            this.activeSubscriptions--;
+            cleanup();
+        };
+    }
+    /** Register a listener for connection state changes */
+    onConnectionStateChange(listener) {
+        this.stateListeners.add(listener);
+        return () => {
+            this.stateListeners.delete(listener);
+        };
+    }
+    /** Get current connection state */
+    getConnectionState() {
+        return this.connectionState;
+    }
+    /** Number of active subscriptions */
+    getActiveSubscriptionCount() {
+        return this.activeSubscriptions;
+    }
+    /** Dispose the manager and close the WebSocket connection */
+    dispose() {
+        this.wsClient.dispose();
+        this.stateListeners.clear();
+        this.activeSubscriptions = 0;
+        this.setConnectionState('disconnected');
+    }
+    setConnectionState(state) {
+        if (this.connectionState === state)
+            return;
+        this.connectionState = state;
+        for (const listener of this.stateListeners) {
+            listener(state);
+        }
+    }
+}

package/objects/orm/client.d.ts

@@ -4,7 +4,10 @@
  * 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.
  *
@@ -41,6 +44,12 @@ export interface OrmClientConfig {
     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
@@ -52,8 +61,19 @@ export declare class GraphQLRequestError extends Error {
 }
 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.
@@ -64,4 +84,14 @@ export declare class OrmClient {
      * 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/objects/orm/client.js

@@ -1,7 +1,10 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.OrmClient = exports.GraphQLRequestError = exports.FetchAdapter = void 0;
+exports.OrmClient = exports.GraphQLRequestError = exports.FetchAdapter = exports.RealtimeManager = void 0;
 const runtime_1 = require("@constructive-io/graphql-query/runtime");
+const realtime_1 = require("./realtime");
+var realtime_2 = require("./realtime");
+Object.defineProperty(exports, "RealtimeManager", { enumerable: true, get: function () { return realtime_2.RealtimeManager; } });
 /**
  * Default adapter that uses fetch for HTTP requests.
  *
@@ -78,6 +81,7 @@ class GraphQLRequestError extends Error {
 exports.GraphQLRequestError = GraphQLRequestError;
 class OrmClient {
     adapter;
+    realtimeManager;
     constructor(config) {
         if (config.adapter) {
             this.adapter = config.adapter;
@@ -88,10 +92,24 @@ class OrmClient {
         else {
             throw new Error('OrmClientConfig requires either an endpoint or a custom adapter');
         }
+        if (config.realtime) {
+            this.realtimeManager = new realtime_1.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.
@@ -108,5 +126,27 @@ class OrmClient {
     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();
+    }
 }
 exports.OrmClient = OrmClient;