@ankhorage/contracts 1.7.0 → 1.9.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ankhorage/contracts",
-  "version": "1.7.0",
+  "version": "1.9.0",
   "main": "./dist/index.js",
   "dependencies": {
     "@ankhorage/color-theory": "^0.0.7"
@@ -21,6 +21,14 @@
       "types": "./dist/auth.d.ts",
       "default": "./dist/auth.js"
     },
+    "./bindings": {
+      "types": "./dist/bindings.d.ts",
+      "default": "./dist/bindings.js"
+    },
+    "./data": {
+      "types": "./dist/data/index.d.ts",
+      "default": "./dist/data/index.js"
+    },
     "./db": {
       "types": "./dist/db.d.ts",
       "default": "./dist/db.js"

package/src/bindings.test.ts

@@ -0,0 +1,96 @@
+import { describe, expect, it } from 'bun:test';
+
+import type {
+  BindingValueSource,
+  DbCollectionQueryBinding,
+  NodePropBinding,
+  UiNode,
+} from './index';
+
+describe('binding contracts', () => {
+  it('serializes a node prop bound to state', () => {
+    const binding: NodePropBinding = {
+      prop: 'value',
+      valueFrom: {
+        source: 'state',
+        path: 'forms.contact.values.firstname',
+      },
+      transform: 'trim',
+    };
+    const node: UiNode = {
+      id: 'firstname-input',
+      type: 'Input',
+      props: {
+        label: 'Firstname',
+      },
+      bindings: [binding],
+    };
+
+    expect(JSON.parse(JSON.stringify(node))).toEqual(node);
+    expect(node.bindings?.[0]?.valueFrom.source).toBe('state');
+  });
+
+  it('serializes a node prop bound to a DB collection query', () => {
+    const query: DbCollectionQueryBinding = {
+      collection: 'posts',
+      schema: 'public',
+      columns: ['id', 'title', 'published'],
+      filters: [{ field: 'published', operator: 'eq', value: true }],
+      sort: [{ field: 'created_at', direction: 'desc' }],
+      page: { limit: 10, offset: 0 },
+      refresh: 'live',
+    };
+    const node: UiNode = {
+      id: 'posts-list',
+      type: 'CollectionList',
+      bindings: [
+        {
+          prop: 'items',
+          valueFrom: {
+            source: 'db.collection',
+            query,
+          },
+        },
+      ],
+    };
+
+    expect(JSON.parse(JSON.stringify(node))).toEqual(node);
+    expect(node.bindings?.[0]?.valueFrom.source).toBe('db.collection');
+  });
+
+  it('supports literal, context, and event value sources', () => {
+    const sources: readonly BindingValueSource[] = [
+      { source: 'literal', value: { fallback: 'Untitled' } },
+      { source: 'context', path: 'auth.user.displayName' },
+      { source: 'event', path: 'payload.values.search' },
+    ];
+
+    expect(JSON.parse(JSON.stringify(sources))).toEqual(sources);
+    expect(sources.map((source) => source.source)).toEqual(['literal', 'context', 'event']);
+  });
+
+  it('supports static, focus, poll, and live refresh intent', () => {
+    const refreshModes = ['static', 'focus', 'poll', 'live'] as const;
+    const bindings = refreshModes.map(
+      (refresh): NodePropBinding => ({
+        prop: `items.${refresh}`,
+        valueFrom: {
+          source: 'db.collection',
+          query: {
+            collection: 'posts',
+            refresh,
+            pollIntervalMs: refresh === 'poll' ? 30_000 : undefined,
+          },
+        },
+      }),
+    );
+
+    expect(JSON.parse(JSON.stringify(bindings))).toEqual(bindings);
+    expect(bindings.map((binding) => binding.valueFrom.source)).toEqual([
+      'db.collection',
+      'db.collection',
+      'db.collection',
+      'db.collection',
+    ]);
+  });
+});

package/src/bindings.ts

@@ -0,0 +1,54 @@
+import type { DbFilter, DbPage, DbSort } from './db';
+
+export type BindingValue =
+  | string
+  | number
+  | boolean
+  | null
+  | readonly BindingValue[]
+  | {
+      readonly [key: string]: BindingValue;
+    };
+
+export type BindingRefreshMode = 'focus' | 'live' | 'poll' | 'static';
+
+export interface DbCollectionQueryBinding {
+  readonly collection: string;
+  readonly schema?: string;
+  readonly columns?: readonly string[];
+  readonly filters?: readonly DbFilter[];
+  readonly sort?: readonly DbSort[];
+  readonly page?: DbPage;
+  readonly refresh?: BindingRefreshMode;
+  readonly pollIntervalMs?: number;
+}
+
+export type BindingValueSource =
+  | {
+      readonly source: 'context';
+      readonly path: string;
+    }
+  | {
+      readonly source: 'db.collection';
+      readonly query: DbCollectionQueryBinding;
+    }
+  | {
+      readonly source: 'event';
+      readonly path: string;
+    }
+  | {
+      readonly source: 'literal';
+      readonly value: BindingValue;
+    }
+  | {
+      readonly source: 'state';
+      readonly path: string;
+    };
+
+export type BindingValueTransform = 'lowercase' | 'trim' | 'uppercase';
+
+export interface NodePropBinding {
+  readonly prop: string;
+  readonly valueFrom: BindingValueSource;
+  readonly transform?: BindingValueTransform | readonly BindingValueTransform[];
+}

package/src/data/data.test.ts

@@ -0,0 +1,305 @@
+import { describe, expect, it } from 'bun:test';
+
+import type {
+  DataSourceConfig,
+  DataSourceDiagnostic,
+  GraphQlDataSourceConfig,
+  ManagedApiDataSourceConfig,
+  OpenApiDataSourceConfig,
+  RestDataSourceConfig,
+} from './index';
+
+function assertSerializable<TValue>(value: TValue): void {
+  expect(JSON.parse(JSON.stringify(value))).toEqual(value);
+}
+
+describe('data source contracts', () => {
+  it('serializes a manual REST data source with read and create operations', () => {
+    const source: RestDataSourceConfig = {
+      id: 'cms-rest',
+      kind: 'rest',
+      name: 'CMS REST API',
+      baseUrl: 'https://cms.example.com',
+      credential: {
+        id: 'cms-api-key',
+        kind: 'apiKey',
+        label: 'CMS API key',
+      },
+      schemas: {
+        post: {
+          type: 'object',
+          required: ['id', 'title'],
+          properties: {
+            id: { type: 'string' },
+            title: { type: 'string' },
+            published: { type: 'boolean', default: false },
+          },
+        },
+      },
+      endpoints: {
+        posts: {
+          id: 'posts',
+          kind: 'http',
+          path: '/posts',
+          operations: {
+            'posts.list': {
+              id: 'posts.list',
+              endpointId: 'posts',
+              protocol: 'http',
+              intent: 'read',
+              method: 'GET',
+              path: '/posts',
+              request: {
+                parameters: [
+                  {
+                    name: 'limit',
+                    location: 'query',
+                    schema: { type: 'integer', default: 20 },
+                  },
+                ],
+              },
+              response: {
+                status: 200,
+                schema: {
+                  type: 'array',
+                  items: { ref: { id: 'post' } },
+                },
+              },
+              pagination: {
+                kind: 'limit-offset',
+                limitParameter: 'limit',
+                offsetParameter: 'offset',
+              },
+            },
+            'posts.create': {
+              id: 'posts.create',
+              endpointId: 'posts',
+              protocol: 'http',
+              intent: 'create',
+              method: 'POST',
+              path: '/posts',
+              request: {
+                contentType: 'application/json',
+                schema: { ref: { id: 'post' } },
+              },
+              response: {
+                status: 201,
+                schemaRef: { id: 'post' },
+              },
+            },
+          },
+        },
+      },
+    };
+
+    assertSerializable(source);
+    expect(source.endpoints.posts?.operations['posts.list']?.intent).toBe('read');
+    expect(source.endpoints.posts?.operations['posts.create']?.intent).toBe('create');
+  });
+
+  it('serializes an imported OpenAPI data source', () => {
+    const source: OpenApiDataSourceConfig = {
+      id: 'shop-openapi',
+      kind: 'openapi',
+      name: 'Shop OpenAPI',
+      baseUrl: 'https://shop.example.com/api',
+      import: {
+        url: 'https://shop.example.com/openapi.json',
+        version: '2026-05-19',
+      },
+      endpoints: {
+        products: {
+          id: 'products',
+          kind: 'http',
+          path: '/products/{productId}',
+          operations: {
+            getProduct: {
+              id: 'getProduct',
+              endpointId: 'products',
+              protocol: 'http',
+              intent: 'read',
+              method: 'GET',
+              path: '/products/{productId}',
+              request: {
+                parameters: [
+                  {
+                    name: 'productId',
+                    location: 'path',
+                    required: true,
+                    schema: { type: 'string' },
+                  },
+                ],
+              },
+              response: {
+                status: 200,
+                schema: {
+                  type: 'object',
+                  properties: {
+                    id: { type: 'string' },
+                    name: { type: 'string' },
+                    price: { type: 'number' },
+                  },
+                },
+              },
+            },
+          },
+        },
+      },
+    };
+
+    assertSerializable(source);
+    expect(source.import?.url).toContain('openapi.json');
+    expect(
+      source.endpoints.products?.operations.getProduct?.request?.parameters?.[0]?.location,
+    ).toBe('path');
+  });
+
+  it('serializes a GraphQL data source with query and mutation operations', () => {
+    const source: GraphQlDataSourceConfig = {
+      id: 'content-graphql',
+      kind: 'graphql',
+      endpointUrl: 'https://content.example.com/graphql',
+      introspection: {
+        enabled: true,
+        schemaVersion: '2026-05-19',
+      },
+      endpoints: {
+        graphql: {
+          id: 'graphql',
+          kind: 'graphql',
+          operations: {
+            PostsQuery: {
+              id: 'PostsQuery',
+              endpointId: 'graphql',
+              protocol: 'graphql',
+              intent: 'read',
+              request: {
+                schema: {
+                  type: 'object',
+                  properties: {
+                    search: { type: 'string' },
+                  },
+                },
+              },
+              response: {
+                schema: {
+                  type: 'object',
+                  properties: {
+                    posts: {
+                      type: 'array',
+                      items: { type: 'object' },
+                    },
+                  },
+                },
+              },
+            },
+            CreatePost: {
+              id: 'CreatePost',
+              endpointId: 'graphql',
+              protocol: 'graphql',
+              intent: 'create',
+              request: {
+                schema: {
+                  type: 'object',
+                  required: ['title'],
+                  properties: {
+                    title: { type: 'string' },
+                  },
+                },
+              },
+              response: {
+                schema: {
+                  type: 'object',
+                  properties: {
+                    createPost: { type: 'object' },
+                  },
+                },
+              },
+            },
+          },
+        },
+      },
+    };
+
+    assertSerializable(source);
+    expect(source.endpoints.graphql?.operations.PostsQuery?.protocol).toBe('graphql');
+    expect(source.endpoints.graphql?.operations.CreatePost?.intent).toBe('create');
+  });
+
+  it('serializes a managed API backed by a database adapter reference', () => {
+    const source: ManagedApiDataSourceConfig = {
+      id: 'app-managed-api',
+      kind: 'managed-api',
+      name: 'App managed API',
+      adapter: {
+        id: 'primary-db',
+        kind: 'database',
+        packageName: '@ankhorage/supabase-db',
+      },
+      resources: [
+        {
+          name: 'posts',
+          collection: {
+            name: 'posts',
+            schema: 'public',
+            primaryKey: 'id',
+            fields: [
+              { name: 'id', type: 'uuid', required: true, unique: true },
+              { name: 'title', type: 'text', required: true },
+              { name: 'published', type: 'boolean', defaultValue: false },
+            ],
+          },
+          operations: ['list', 'read', 'create', 'update', 'delete'],
+        },
+      ],
+      endpoints: {
+        posts: {
+          id: 'posts',
+          kind: 'database',
+          operations: {
+            'posts.list': {
+              id: 'posts.list',
+              endpointId: 'posts',
+              protocol: 'database',
+              intent: 'read',
+            },
+            'posts.delete': {
+              id: 'posts.delete',
+              endpointId: 'posts',
+              protocol: 'database',
+              intent: 'delete',
+            },
+          },
+        },
+      },
+    };
+
+    assertSerializable(source);
+    expect(source.adapter.kind).toBe('database');
+    expect(source.resources[0]?.collection.fields.map((field) => field.name)).toEqual([
+      'id',
+      'title',
+      'published',
+    ]);
+  });
+
+  it('accepts a provider-neutral data source registry and diagnostics', () => {
+    const source: DataSourceConfig = {
+      id: 'public-rest',
+      kind: 'rest',
+      baseUrl: 'https://public.example.com',
+      endpoints: {},
+    };
+    const diagnostic: DataSourceDiagnostic = {
+      code: 'missing-operation',
+      severity: 'error',
+      message: 'Operation not found.',
+      dataSourceId: 'public-rest',
+      endpointId: 'posts',
+      operationId: 'posts.list',
+    };
+
+    assertSerializable({ source, diagnostic });
+    expect(diagnostic.code).toBe('missing-operation');
+  });
+});

package/src/data/diagnostics.ts

@@ -0,0 +1,41 @@
+import type { DataSourceId, EndpointId, OperationId } from './ids';
+
+export type DataDiagnosticSeverity = 'error' | 'info' | 'warning';
+
+export type DataDiagnosticCode =
+  | 'ambiguous-server'
+  | 'duplicate-operation-id'
+  | 'invalid-config'
+  | 'missing-adapter'
+  | 'missing-credential'
+  | 'missing-data-source'
+  | 'missing-endpoint'
+  | 'missing-operation'
+  | 'missing-schema'
+  | 'network-error'
+  | 'parse-error'
+  | 'unsupported-auth-scheme'
+  | 'unsupported-schema'
+  | (string & {});
+
+export interface DataSourceDiagnostic {
+  readonly code: DataDiagnosticCode;
+  readonly message: string;
+  readonly severity: DataDiagnosticSeverity;
+  readonly dataSourceId?: DataSourceId;
+  readonly endpointId?: EndpointId;
+  readonly operationId?: OperationId;
+  readonly path?: string;
+  readonly hint?: string;
+}
+
+export type DataSourceDiagnosticResult<TData> =
+  | {
+      readonly ok: true;
+      readonly data: TData;
+      readonly diagnostics?: readonly DataSourceDiagnostic[];
+    }
+  | {
+      readonly ok: false;
+      readonly diagnostics: readonly DataSourceDiagnostic[];
+    };

package/src/data/endpoints.ts

@@ -0,0 +1,20 @@
+import type { EndpointId, OperationId } from './ids';
+import type { DataOperationConfig } from './operations';
+import type { CredentialRef } from './refs';
+import type { DataContractValue } from './values';
+
+export type DataEndpointKind = 'database' | 'graphql' | 'http' | (string & {});
+
+export interface DataEndpointConfig {
+  readonly id: EndpointId;
+  readonly kind: DataEndpointKind;
+  readonly name?: string;
+  readonly description?: string;
+  readonly baseUrl?: string;
+  readonly path?: string;
+  readonly credential?: CredentialRef;
+  readonly operations: Readonly<Record<OperationId, DataOperationConfig>>;
+  readonly metadata?: DataContractValue;
+}
+
+export type DataEndpointRegistry = Readonly<Record<EndpointId, DataEndpointConfig>>;

package/src/data/ids.ts

@@ -0,0 +1,6 @@
+export type DataSourceId = string;
+export type EndpointId = string;
+export type OperationId = string;
+export type SchemaId = string;
+export type CredentialId = string;
+export type AdapterId = string;

package/src/data/index.ts

@@ -0,0 +1,8 @@
+export * from './diagnostics';
+export * from './endpoints';
+export * from './ids';
+export * from './operations';
+export * from './refs';
+export * from './schemas';
+export * from './sources';
+export * from './values';

package/src/data/operations.ts

@@ -0,0 +1,66 @@
+import type { EndpointId, OperationId } from './ids';
+import type { CredentialRef } from './refs';
+import type { DataSchemaSlot } from './schemas';
+import type { DataContractValue } from './values';
+
+export type DataOperationIntent = 'action' | 'create' | 'delete' | 'read' | 'update';
+
+export type DataOperationMethod =
+  | 'DELETE'
+  | 'GET'
+  | 'HEAD'
+  | 'OPTIONS'
+  | 'PATCH'
+  | 'POST'
+  | 'PUT'
+  | (string & {});
+
+export type DataOperationProtocol = 'database' | 'graphql' | 'http' | (string & {});
+
+export type DataOperationParameterLocation = 'body' | 'cookie' | 'header' | 'path' | 'query';
+
+export interface DataOperationParameter extends DataSchemaSlot {
+  readonly name: string;
+  readonly location: DataOperationParameterLocation;
+  readonly required?: boolean;
+  readonly description?: string;
+  readonly default?: DataContractValue;
+}
+
+export interface DataOperationRequest extends DataSchemaSlot {
+  readonly parameters?: readonly DataOperationParameter[];
+  readonly contentType?: string;
+}
+
+export interface DataOperationResponse extends DataSchemaSlot {
+  readonly status?: number | string;
+  readonly contentType?: string;
+  readonly description?: string;
+}
+
+export interface DataOperationPagination {
+  readonly kind: 'cursor' | 'limit-offset' | 'page' | 'unknown' | (string & {});
+  readonly cursorPath?: string;
+  readonly limitParameter?: string;
+  readonly offsetParameter?: string;
+  readonly pageParameter?: string;
+  readonly pageSizeParameter?: string;
+}
+
+export interface DataOperationConfig {
+  readonly id: OperationId;
+  readonly endpointId?: EndpointId;
+  readonly name?: string;
+  readonly description?: string;
+  readonly protocol: DataOperationProtocol;
+  readonly intent: DataOperationIntent;
+  readonly method?: DataOperationMethod;
+  readonly path?: string;
+  readonly request?: DataOperationRequest;
+  readonly response?: DataOperationResponse;
+  readonly pagination?: DataOperationPagination;
+  readonly credential?: CredentialRef;
+  readonly metadata?: DataContractValue;
+}
+
+export type DataOperationRegistry = Readonly<Record<OperationId, DataOperationConfig>>;

package/src/data/refs.ts

@@ -0,0 +1,21 @@
+import type { AdapterId, CredentialId } from './ids';
+import type { DataContractValue } from './values';
+
+export type CredentialKind = 'apiKey' | 'basic' | 'bearer' | 'custom' | 'oauth2';
+
+export interface CredentialRef {
+  readonly id: CredentialId;
+  readonly kind: CredentialKind | (string & {});
+  readonly label?: string;
+  readonly scope?: string;
+}
+
+export type AdapterKind = 'auth' | 'database' | 'storage' | 'transport' | (string & {});
+
+export interface AdapterRef {
+  readonly id: AdapterId;
+  readonly kind: AdapterKind;
+  readonly packageName?: string;
+  readonly exportName?: string;
+  readonly config?: DataContractValue;
+}

package/src/data/schemas.ts

@@ -0,0 +1,46 @@
+import type { SchemaId } from './ids';
+import type { DataContractValue } from './values';
+
+export type DataSchemaPrimitiveType =
+  | 'array'
+  | 'boolean'
+  | 'integer'
+  | 'null'
+  | 'number'
+  | 'object'
+  | 'string';
+
+export interface DataSchemaRef {
+  readonly id: SchemaId;
+}
+
+export interface DataSchemaProperty {
+  readonly description?: string;
+  readonly schema: DataSchema;
+}
+
+export interface DataSchema {
+  readonly type?: DataSchemaPrimitiveType | readonly DataSchemaPrimitiveType[];
+  readonly title?: string;
+  readonly description?: string;
+  readonly enum?: readonly DataContractValue[];
+  readonly const?: DataContractValue;
+  readonly default?: DataContractValue;
+  readonly format?: string;
+  readonly nullable?: boolean;
+  readonly required?: readonly string[];
+  readonly properties?: Readonly<Record<string, DataSchema>>;
+  readonly additionalProperties?: boolean | DataSchema;
+  readonly items?: DataSchema;
+  readonly allOf?: readonly DataSchema[];
+  readonly anyOf?: readonly DataSchema[];
+  readonly oneOf?: readonly DataSchema[];
+  readonly ref?: DataSchemaRef;
+}
+
+export type DataSchemaRegistry = Readonly<Record<SchemaId, DataSchema>>;
+
+export interface DataSchemaSlot {
+  readonly schema?: DataSchema;
+  readonly schemaRef?: DataSchemaRef;
+}