@ankhorage/contracts 4.0.0 → 4.0.2

package/src/bindings.ts

@@ -94,14 +94,6 @@ export type BindingInputValue =
 
 export type BindingInputMap = Readonly<Record<string, BindingInputValue>>;
 
-export interface ApiScreenDataLoaderDefinition {
-  readonly kind: 'api';
-  readonly apiId: string;
-  readonly mode: 'byId' | 'list' | 'one' | 'random';
-  readonly targetPath: string;
-  readonly id?: string | number;
-}
-
 export interface OperationScreenDataLoaderDefinition {
   readonly kind: 'operation';
   readonly id?: string;
@@ -109,9 +101,7 @@ export interface OperationScreenDataLoaderDefinition {
   readonly input?: BindingInputMap;
 }
 
-export type ScreenDataLoaderDefinition =
-  | ApiScreenDataLoaderDefinition
-  | OperationScreenDataLoaderDefinition;
+export type ScreenDataLoaderDefinition = OperationScreenDataLoaderDefinition;
 
 export type BindingConditionOperator = 'eq' | 'exists' | 'neq' | 'notExists';
 

package/src/data/apis.test.ts

@@ -1,146 +1,69 @@
-import { describe, expect, test } from 'bun:test';
+import { describe, expect, it } from 'bun:test';
 
-import type {
-  AppApiDefinition,
-  AppApiEndpointDefinition,
-  AppApiManifest,
-  AppGeneratedApiDefinition,
-} from './apis';
-import { APP_API_ENDPOINT_INTENTS, APP_API_ENDPOINT_METHODS, APP_API_KINDS } from './apis';
+import type { GeneratedApiDefinition, GeneratedApiRegistry } from './apis';
+import { GENERATED_API_CRUD_OPERATIONS } from './apis';
 
-const crudEndpoints = [
-  {
-    id: 'players.list',
-    method: 'GET',
-    path: '/',
-    intent: 'list',
-  },
-  {
-    id: 'players.create',
-    method: 'POST',
-    path: '/',
-    intent: 'create',
-  },
-  {
-    id: 'players.read',
-    method: 'GET',
-    path: '/{id}',
-    intent: 'read',
-  },
-  {
-    id: 'players.update',
-    method: 'PATCH',
-    path: '/{id}',
-    intent: 'update',
-  },
-  {
-    id: 'players.delete',
-    method: 'DELETE',
-    path: '/{id}',
-    intent: 'delete',
-  },
-] satisfies readonly AppApiEndpointDefinition[];
+function assertSerializable<TValue>(value: TValue): void {
+  expect(JSON.parse(JSON.stringify(value))).toEqual(value);
+}
 
-describe('app API authoring contracts', () => {
-  test('exports stable API authoring constants', () => {
-    expect(APP_API_KINDS).toEqual(['external', 'generated']);
-    expect(APP_API_ENDPOINT_METHODS).toEqual([
-      'DELETE',
-      'GET',
-      'HEAD',
-      'OPTIONS',
-      'PATCH',
-      'POST',
-      'PUT',
-    ]);
-    expect(APP_API_ENDPOINT_INTENTS).toEqual([
-      'create',
-      'custom',
-      'delete',
-      'list',
-      'read',
-      'update',
-    ]);
-  });
-
-  test('serializes generated APIs with a CRUD preset and explicit custom endpoints', () => {
-    const generatedApi: AppGeneratedApiDefinition = {
-      id: 'players',
-      kind: 'generated',
-      label: 'Players',
-      basePath: '/api/players',
-      preset: 'crud',
-      resource: {
-        kind: 'collection',
+function createGeneratedApi(): GeneratedApiDefinition {
+  return {
+    id: 'catalog-api',
+    protocol: 'rest',
+    name: 'Catalog API',
+    description: 'Generated CRUD API for catalog resources.',
+    basePath: '/api/catalog',
+    database: {
+      id: 'primary-db',
+      kind: 'database',
+      packageName: '@ankhorage/supabase-db',
+    },
+    auth: {
+      required: true,
+      roles: ['editor'],
+    },
+    resources: [
+      {
+        id: 'products',
+        name: 'Products',
+        path: '/products',
         collection: {
-          name: 'players',
+          name: 'products',
+          schema: 'public',
           primaryKey: 'id',
           fields: [
-            { name: 'id', type: 'uuid', required: true },
+            { name: 'id', type: 'uuid', required: true, unique: true },
             { name: 'name', type: 'text', required: true },
-            { name: 'score', type: 'number' },
+            { name: 'price', type: 'number', required: true },
           ],
         },
-        seed: [
-          {
-            id: 'player-1',
-            name: 'Ada',
-            score: 42,
-          },
+        operations: GENERATED_API_CRUD_OPERATIONS,
+        seed: [{ id: 'product-1', name: 'Keyboard', price: 120 }],
+        policies: [
+          { id: 'catalog.read', operation: 'list' },
+          { id: 'catalog.write', operation: 'create' },
         ],
       },
-      endpoints: [
-        ...crudEndpoints,
-        {
-          id: 'players.leaderboard',
-          method: 'GET',
-          path: '/leaderboard',
-          intent: 'custom',
-        },
-      ],
-    };
-    const manifest: AppApiManifest = {
-      apis: {
-        players: generatedApi,
-      },
-    };
+    ],
+  };
+}
 
-    expect(JSON.parse(JSON.stringify(manifest))).toEqual({
-      apis: {
-        players: generatedApi,
-      },
-    });
-    expect(manifest.apis?.players?.endpoints.map((endpoint) => endpoint.path)).toEqual([
-      '/',
-      '/',
-      '/{id}',
-      '/{id}',
-      '/{id}',
-      '/leaderboard',
-    ]);
+describe('generated API desired-state contracts', () => {
+  it('serializes generated REST/CRUD resources independently of runtime operations', () => {
+    const api = createGeneratedApi();
+
+    assertSerializable(api);
+    expect(api.database.kind).toBe('database');
+    expect(api.resources[0]?.operations).toEqual(GENERATED_API_CRUD_OPERATIONS);
+    expect(api.resources[0]?.seed?.[0]?.name).toBe('Keyboard');
   });
 
-  test('serializes external APIs without generated resource definitions', () => {
-    const externalApi: AppApiDefinition = {
-      id: 'stripe',
-      kind: 'external',
-      label: 'Stripe',
-      basePath: '/api/stripe',
-      baseUrl: 'https://api.stripe.com',
-      endpoints: [
-        {
-          id: 'stripe.createCheckoutSession',
-          method: 'POST',
-          path: '/checkout/sessions',
-          intent: 'custom',
-          auth: {
-            required: true,
-            permissions: ['payments:create'],
-          },
-        },
-      ],
-    };
+  it('stores generated APIs in a dedicated canonical registry', () => {
+    const api = createGeneratedApi();
+    const registry: GeneratedApiRegistry = { [api.id]: api };
 
-    expect(JSON.parse(JSON.stringify(externalApi))).toEqual(externalApi);
+    assertSerializable(registry);
+    expect(registry['catalog-api']?.protocol).toBe('rest');
   });
 });

package/src/data/apis.ts

@@ -1,39 +1,21 @@
 import type { DbCollectionDefinition } from '../db';
-import type { DataOperationRequest, DataOperationResponse } from './operations';
+import type { DatabaseAdapterRef } from './refs';
 import type { DataContractValue } from './values';
 
-export const APP_API_KINDS = ['external', 'generated'] as const;
-export type AppApiKind = (typeof APP_API_KINDS)[number];
-
-export const APP_API_GENERATED_PRESETS = ['crud'] as const;
-export type AppApiGeneratedPreset = (typeof APP_API_GENERATED_PRESETS)[number];
-
-export const APP_API_ENDPOINT_METHODS = [
-  'DELETE',
-  'GET',
-  'HEAD',
-  'OPTIONS',
-  'PATCH',
-  'POST',
-  'PUT',
-] as const;
-export type AppApiEndpointMethod = (typeof APP_API_ENDPOINT_METHODS)[number];
-
-export const APP_API_ENDPOINT_INTENTS = [
-  'create',
-  'custom',
-  'delete',
+export const GENERATED_API_CRUD_OPERATIONS = [
   'list',
   'read',
+  'create',
   'update',
+  'delete',
 ] as const;
-export type AppApiEndpointIntent = (typeof APP_API_ENDPOINT_INTENTS)[number];
+export type GeneratedApiCrudOperation = (typeof GENERATED_API_CRUD_OPERATIONS)[number];
 
-export type AppApiId = string;
-export type AppApiEndpointId = string;
-export type AppApiSeedRecord = Readonly<Record<string, DataContractValue>>;
+export type GeneratedApiId = string;
+export type GeneratedApiResourceId = string;
+export type GeneratedApiSeedRecord = Readonly<Record<string, DataContractValue>>;
 
-export interface AppApiAuthRequirement {
+export interface GeneratedApiAuthRequirement {
   readonly required?: boolean;
   readonly roles?: readonly string[];
   readonly permissions?: readonly string[];
@@ -41,65 +23,40 @@ export interface AppApiAuthRequirement {
   readonly metadata?: DataContractValue;
 }
 
-export interface AppApiCollectionResourceDefinition {
-  readonly kind: 'collection';
-  readonly collection: DbCollectionDefinition;
-  readonly seed?: readonly AppApiSeedRecord[];
-  readonly metadata?: DataContractValue;
+export interface GeneratedApiOperationPolicyRef {
+  readonly id: string;
+  readonly operation?: GeneratedApiCrudOperation;
 }
 
-export type AppApiResourceDefinition = AppApiCollectionResourceDefinition;
-
-export interface AppApiEndpointDefinition {
-  readonly id: AppApiEndpointId;
-  readonly label?: string;
+export interface GeneratedApiResourceDefinition {
+  readonly id: GeneratedApiResourceId;
+  readonly name?: string;
   readonly description?: string;
-  readonly method: AppApiEndpointMethod;
-  /**
-   * Path relative to the API base path. Use `/` for the base collection endpoint.
-   */
   readonly path: string;
-  readonly intent?: AppApiEndpointIntent;
-  readonly request?: DataOperationRequest;
-  readonly response?: DataOperationResponse;
-  readonly auth?: AppApiAuthRequirement;
+  readonly collection: DbCollectionDefinition;
+  readonly operations: readonly GeneratedApiCrudOperation[];
+  readonly seed?: readonly GeneratedApiSeedRecord[];
+  readonly policies?: readonly GeneratedApiOperationPolicyRef[];
   readonly metadata?: DataContractValue;
 }
 
-interface AppApiDefinitionBase {
-  readonly id: AppApiId;
-  readonly kind: AppApiKind;
-  readonly label?: string;
+/**
+ * Canonical desired state for an API authored and generated by Ankhorage.
+ *
+ * The initial supported generated implementation is REST/CRUD backed by an
+ * existing database adapter. Runtime and binding consumers use the normalized
+ * generated API data-source projection instead of reading this definition.
+ */
+export interface GeneratedApiDefinition {
+  readonly id: GeneratedApiId;
+  readonly protocol: 'rest';
+  readonly name?: string;
   readonly description?: string;
   readonly basePath: string;
-  readonly endpoints: readonly AppApiEndpointDefinition[];
-  readonly auth?: AppApiAuthRequirement;
+  readonly database: DatabaseAdapterRef;
+  readonly resources: readonly GeneratedApiResourceDefinition[];
+  readonly auth?: GeneratedApiAuthRequirement;
   readonly metadata?: DataContractValue;
 }
 
-export interface AppGeneratedApiDefinition extends AppApiDefinitionBase {
-  readonly kind: 'generated';
-  /**
-   * Preset used by authoring tools to seed standard endpoints. The resulting
-   * serialized API still stores concrete `endpoints[]` so custom endpoints can
-   * live next to generated CRUD operations.
-   */
-  readonly preset?: AppApiGeneratedPreset;
-  readonly resource?: AppApiResourceDefinition;
-}
-
-export interface AppExternalApiDefinition extends AppApiDefinitionBase {
-  readonly kind: 'external';
-  readonly baseUrl?: string;
-  readonly openApiUrl?: string;
-}
-
-export type AppApiDefinition = AppExternalApiDefinition | AppGeneratedApiDefinition;
-
-export type AppApiRegistry = Readonly<Record<AppApiId, AppApiDefinition>>;
-
-export interface AppDataManifest {
-  readonly apis?: AppApiRegistry;
-}
-
-export type AppApiManifest = AppDataManifest;
+export type GeneratedApiRegistry = Readonly<Record<GeneratedApiId, GeneratedApiDefinition>>;