@ankhorage/contracts 1.8.0 → 1.10.0

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;
+}

package/src/data/sources.ts

@@ -0,0 +1,72 @@
+import type { DbCollectionDefinition } from '../db';
+import type { DataEndpointRegistry } from './endpoints';
+import type { DataSourceId } from './ids';
+import type { AdapterRef, CredentialRef } from './refs';
+import type { DataSchemaRegistry } from './schemas';
+import type { DataContractValue } from './values';
+
+export type DataSourceKind = 'database' | 'graphql' | 'managed-api' | 'openapi' | 'rest';
+
+export interface DataSourceBaseConfig {
+  readonly id: DataSourceId;
+  readonly kind: DataSourceKind;
+  readonly name?: string;
+  readonly description?: string;
+  readonly credential?: CredentialRef;
+  readonly endpoints: DataEndpointRegistry;
+  readonly schemas?: DataSchemaRegistry;
+  readonly metadata?: DataContractValue;
+}
+
+export interface RestDataSourceConfig extends DataSourceBaseConfig {
+  readonly kind: 'rest';
+  readonly baseUrl: string;
+}
+
+export interface OpenApiImportRef {
+  readonly url?: string;
+  readonly documentId?: string;
+  readonly version?: string;
+}
+
+export interface OpenApiDataSourceConfig extends DataSourceBaseConfig {
+  readonly kind: 'openapi';
+  readonly baseUrl?: string;
+  readonly import?: OpenApiImportRef;
+}
+
+export interface GraphQlDataSourceConfig extends DataSourceBaseConfig {
+  readonly kind: 'graphql';
+  readonly endpointUrl: string;
+  readonly introspection?: {
+    readonly enabled: boolean;
+    readonly schemaVersion?: string;
+  };
+}
+
+export interface DatabaseDataSourceConfig extends DataSourceBaseConfig {
+  readonly kind: 'database';
+  readonly adapter: AdapterRef;
+}
+
+export interface ManagedApiResourceConfig {
+  readonly name: string;
+  readonly collection: DbCollectionDefinition;
+  readonly operations?: readonly ('create' | 'delete' | 'list' | 'read' | 'update')[];
+  readonly metadata?: DataContractValue;
+}
+
+export interface ManagedApiDataSourceConfig extends DataSourceBaseConfig {
+  readonly kind: 'managed-api';
+  readonly adapter: AdapterRef;
+  readonly resources: readonly ManagedApiResourceConfig[];
+}
+
+export type DataSourceConfig =
+  | DatabaseDataSourceConfig
+  | GraphQlDataSourceConfig
+  | ManagedApiDataSourceConfig
+  | OpenApiDataSourceConfig
+  | RestDataSourceConfig;
+
+export type DataSourceRegistry = Readonly<Record<DataSourceId, DataSourceConfig>>;

package/src/data/values.ts

@@ -0,0 +1,11 @@
+export type DataContractValue =
+  | string
+  | number
+  | boolean
+  | null
+  | readonly DataContractValue[]
+  | {
+      readonly [key: string]: DataContractValue;
+    };
+
+export type DataPath = string;

package/src/index.ts

@@ -1,6 +1,8 @@
 export * from './auth';
 export * from './bindings';
+export * from './data';
 export * from './db';
 export * from './state';
 export * from './storage';
 export * from './types';
+export * from './ui';