@ankhorage/contracts 7.9.0 → 8.0.1

package/src/appManifest.test.ts

@@ -43,6 +43,41 @@ function createManifest(): Record<string, unknown> {
       storage: { provider: 'auto', buckets: ['media'] },
       state: { provider: 'legend', persistence: 'local' },
       networking: { domain: 'example.test', cdn: false },
+      apis: [
+        {
+          id: 'nutrition',
+          origin: 'external',
+          protocol: 'rest',
+          baseUrl: 'https://api.ankhorage.com/v1/nutrition',
+          schemas: {
+            Product: {
+              type: 'object',
+              required: ['id', 'name'],
+              properties: {
+                id: { type: 'string', format: 'uuid' },
+                name: { type: 'string' },
+              },
+            },
+          },
+          endpoints: {
+            products: {
+              id: 'products',
+              kind: 'http',
+              path: '/products',
+              operations: {
+                'products.list': {
+                  id: 'products.list',
+                  endpointId: 'products',
+                  protocol: 'http',
+                  intent: 'read',
+                  method: 'GET',
+                  path: '/products',
+                },
+              },
+            },
+          },
+        },
+      ],
       modules: ['expo-localization'],
       modulesConfig: { localization: { defaultLocale: 'en' } },
     },
@@ -76,52 +111,22 @@ function createManifest(): Record<string, unknown> {
         dataLoaders: [
           {
             kind: 'operation',
-            id: 'load-users',
-            operation: { dataSourceId: 'external', endpointId: 'main', operationId: 'list' },
+            id: 'load-products',
+            operation: { apiId: 'nutrition', endpointId: 'products', operationId: 'products.list' },
           },
         ],
         requires: {
           permissions: [{ permission: 'camera' }],
-          capabilities: [{ capability: 'barcodeScanner' }],
+          capabilities: [{ capability: 'barcodeScanner' }, { capability: 'ebookReader' }],
         },
       },
     },
-    generatedApis: {
-      users: {
-        id: 'users',
-        protocol: 'rest',
-        basePath: '/users',
-        database: { id: 'primary', kind: 'database' },
-        resources: [
-          {
-            id: 'users',
-            path: '/users',
-            collection: {
-              name: 'users',
-              fields: [{ name: 'id', type: 'uuid', required: true }],
-              primaryKey: 'id',
-            },
-            operations: ['list', 'read'],
-          },
-        ],
-      },
-    },
     dataSources: {
-      external: {
-        id: 'external',
-        kind: 'api',
-        origin: 'external',
-        protocol: 'rest',
-        baseUrl: 'https://example.test',
-        endpoints: {
-          main: {
-            id: 'main',
-            kind: 'http',
-            operations: {
-              list: { id: 'list', protocol: 'rest', intent: 'read', path: '/users' },
-            },
-          },
-        },
+      primary: {
+        id: 'primary',
+        kind: 'database',
+        adapter: { id: 'primary-db', kind: 'database' },
+        endpoints: {},
       },
     },
     dataBindings: {
@@ -134,14 +139,13 @@ function createManifest(): Record<string, unknown> {
       },
     },
     settings: {
-      apiBaseUrl: 'https://example.test/api',
       localization: { defaultLocale: 'en', locales: ['en', 'de'] },
     },
   };
 }
 
 describe('AppManifest runtime parsing', () => {
-  it('accepts the canonical manifest including optional nested sections', () => {
+  it('accepts the canonical manifest including infra APIs', () => {
     const manifest = createManifest();
 
     expect(isAppManifest(manifest)).toBe(true);
@@ -167,6 +171,58 @@ describe('AppManifest runtime parsing', () => {
     });
   });
 
+  it('rejects duplicate canonical API ids', () => {
+    const manifest = createManifest();
+    const infra = manifest.infra as Record<string, unknown>;
+    const apis = infra.apis as Record<string, unknown>[];
+    apis.push(structuredClone(apis[0]));
+
+    expect(isAppManifest(manifest)).toBe(false);
+  });
+
+  it('rejects generatedApis as removed parallel API state', () => {
+    const manifest = createManifest();
+    manifest.generatedApis = {};
+
+    expect(isAppManifest(manifest)).toBe(false);
+  });
+
+  it('rejects API-flavoured dataSources', () => {
+    const manifest = createManifest();
+    manifest.dataSources = {
+      external: {
+        id: 'external',
+        kind: 'api',
+        origin: 'external',
+        protocol: 'rest',
+        baseUrl: 'https://example.test',
+        endpoints: {},
+      },
+    };
+
+    expect(isAppManifest(manifest)).toBe(false);
+  });
+
+  it('rejects old dataSourceId API binding references', () => {
+    const manifest = createManifest();
+    const screens = manifest.screens as Record<string, Record<string, unknown>>;
+    const loaders = screens.home?.dataLoaders as Record<string, unknown>[];
+    loaders[0] = {
+      kind: 'operation',
+      operation: { dataSourceId: 'nutrition', operationId: 'products.list' },
+    };
+
+    expect(isAppManifest(manifest)).toBe(false);
+  });
+
+  it('rejects settings.apiBaseUrl as removed parallel API state', () => {
+    const manifest = createManifest();
+    const settings = manifest.settings as Record<string, unknown>;
+    settings.apiBaseUrl = 'https://example.test/api';
+
+    expect(isAppManifest(manifest)).toBe(false);
+  });
+
   it('rejects transient media URLs at the manifest boundary', () => {
     const manifest = createManifest();
     const media = manifest.media as Record<string, Record<string, Record<string, unknown>>>;

package/src/appManifest.ts

@@ -1,7 +1,6 @@
 import { isComponentDataBindingRegistry } from './appManifest/bindings';
 import { isDataSourceRegistry } from './appManifest/dataSources';
 import { isAppDeployManifest } from './appManifest/deploy';
-import { isGeneratedApiRegistry } from './appManifest/generatedApis';
 import { isInfraManifest } from './appManifest/infra';
 import { isMediaManifest } from './appManifest/media';
 import {
@@ -11,7 +10,7 @@ import {
   isSplashScreenSpec,
   isThemeConfig,
 } from './appManifest/screens';
-import { isOptionalString, isRecord, isStringArray } from './appManifest/shared';
+import { isRecord, isStringArray } from './appManifest/shared';
 import type { AppManifest } from './types';
 
 export type AppManifestParseResult =
@@ -29,7 +28,6 @@ const APP_MANIFEST_KEY_POLICY = {
   infra: 'required',
   navigator: 'required',
   screens: 'required',
-  generatedApis: 'optional',
   dataSources: 'optional',
   dataBindings: 'optional',
   settings: 'required',
@@ -53,6 +51,7 @@ export function isAppManifest(value: unknown): value is AppManifest {
   return (
     isRecord(value) &&
     hasRequiredManifestKeys(value) &&
+    !('generatedApis' in value) &&
     isManifestMetadata(value.metadata) &&
     Array.isArray(value.themes) &&
     value.themes.every(isThemeConfig) &&
@@ -64,7 +63,6 @@ export function isAppManifest(value: unknown): value is AppManifest {
     isInfraManifest(value.infra) &&
     isNavigatorSpec(value.navigator) &&
     isScreenRegistry(value.screens) &&
-    (value.generatedApis === undefined || isGeneratedApiRegistry(value.generatedApis)) &&
     (value.dataSources === undefined || isDataSourceRegistry(value.dataSources)) &&
     (value.dataBindings === undefined || isComponentDataBindingRegistry(value.dataBindings)) &&
     isAppSettings(value.settings)
@@ -84,9 +82,9 @@ function isActiveThemeMode(value: unknown): boolean {
 function isAppSettings(value: unknown): boolean {
   return (
     isRecord(value) &&
+    !('apiBaseUrl' in value) &&
     isRecord(value.localization) &&
     typeof value.localization.defaultLocale === 'string' &&
-    isStringArray(value.localization.locales) &&
-    isOptionalString(value.apiBaseUrl)
+    isStringArray(value.localization.locales)
   );
 }

package/src/bindings.test.ts

@@ -26,7 +26,7 @@ describe('component data-binding contracts', () => {
           source: {
             kind: 'operation',
             operation: {
-              dataSourceId: 'cms',
+              apiId: 'cms',
               endpointId: 'pages',
               operationId: 'pages.getHome',
             },
@@ -66,7 +66,7 @@ describe('component data-binding contracts', () => {
       {
         kind: 'operation',
         operation: {
-          dataSourceId: 'search-api',
+          apiId: 'search-api',
           operationId: 'search.query',
         },
         path: '$.results',
@@ -83,7 +83,7 @@ describe('component data-binding contracts', () => {
     ]);
   });
 
-  it('serializes an event binding that executes a data-source operation', () => {
+  it('serializes an event binding that executes an API operation', () => {
     const input: BindingInputMap = {
       email: {
         kind: 'source',
@@ -122,7 +122,7 @@ describe('component data-binding contracts', () => {
       target: {
         kind: 'operation',
         operation: {
-          dataSourceId: 'contact-api',
+          apiId: 'contact-api',
           endpointId: 'messages',
           operationId: 'messages.create',
         },
@@ -165,7 +165,7 @@ describe('component data-binding contracts', () => {
       kind: 'operation',
       id: 'product-detail',
       operation: {
-        dataSourceId: 'nutrition-api',
+        apiId: 'nutrition',
         endpointId: 'products',
         operationId: 'nutrition.products.getById',
       },
@@ -186,7 +186,7 @@ describe('component data-binding contracts', () => {
 
   it('serializes scanner lookup and conditional navigation intent using existing generic bindings', () => {
     const productLookupOperation = {
-      dataSourceId: 'nutrition-api',
+      apiId: 'nutrition',
       endpointId: 'products',
       operationId: 'products.lookupByBarcode',
     } as const;
@@ -308,7 +308,7 @@ describe('component data-binding contracts', () => {
 
   it('serializes repeated container nodes with generic item-context bindings', () => {
     const productsListOperation = {
-      dataSourceId: 'catalog-api',
+      apiId: 'catalog-api',
       endpointId: 'products',
       operationId: 'products.list',
     } as const;
@@ -439,7 +439,7 @@ describe('component data-binding contracts', () => {
               target: {
                 kind: 'operation',
                 operation: {
-                  dataSourceId: 'contact-api',
+                  apiId: 'contact-api',
                   operationId: 'messages.create',
                 },
               },
@@ -453,12 +453,12 @@ describe('component data-binding contracts', () => {
     expect(bindings['submit-button']?.events?.press?.[0]?.target.kind).toBe('operation');
   });
 
-  it('serializes app-level dataSources and dataBindings on the manifest', () => {
+  it('serializes app-level APIs and dataBindings on the manifest', () => {
     const propBinding: PropBinding = {
       source: {
         kind: 'operation',
         operation: {
-          dataSourceId: 'cms',
+          apiId: 'cms',
           endpointId: 'pages',
           operationId: 'pages.getHome',
         },
@@ -490,6 +490,31 @@ describe('component data-binding contracts', () => {
       ],
       activeThemeId: 'default',
       infra: {
+        apis: [
+          {
+            id: 'cms',
+            origin: 'external',
+            protocol: 'rest',
+            baseUrl: 'https://cms.example.com',
+            endpoints: {
+              pages: {
+                id: 'pages',
+                kind: 'http',
+                path: '/pages/home',
+                operations: {
+                  'pages.getHome': {
+                    id: 'pages.getHome',
+                    endpointId: 'pages',
+                    protocol: 'http',
+                    intent: 'read',
+                    method: 'GET',
+                    path: '/pages/home',
+                  },
+                },
+              },
+            },
+          },
+        ],
         modules: [],
       },
       navigator: {
@@ -517,30 +542,6 @@ describe('component data-binding contracts', () => {
           },
         },
       },
-      dataSources: {
-        cms: {
-          id: 'cms',
-          kind: 'rest',
-          baseUrl: 'https://cms.example.com',
-          endpoints: {
-            pages: {
-              id: 'pages',
-              kind: 'http',
-              path: '/pages/home',
-              operations: {
-                'pages.getHome': {
-                  id: 'pages.getHome',
-                  endpointId: 'pages',
-                  protocol: 'http',
-                  intent: 'read',
-                  method: 'GET',
-                  path: '/pages/home',
-                },
-              },
-            },
-          },
-        },
-      },
       dataBindings: {
         'hero-title': {
           componentId: 'hero-title',
@@ -555,19 +556,11 @@ describe('component data-binding contracts', () => {
           defaultLocale: 'en',
           locales: ['en'],
         },
-        authFlow: {
-          signInRoute: '/sign-in',
-          signUpRoute: '/sign-up',
-          signOutRoute: '/sign-out',
-          forgotPasswordRoute: '/forgot-password',
-          postSignInRoute: '/',
-          unauthorizedRoute: '/sign-in',
-        },
       },
     };
 
     assertSerializable(manifest);
     expect(manifest.dataBindings?.['hero-title']?.props?.children?.source.kind).toBe('operation');
-    expect(manifest.dataSources?.cms?.kind).toBe('rest');
+    expect(manifest.infra.apis?.[0]?.id).toBe('cms');
   });
 });

package/src/bindings.ts

@@ -1,4 +1,4 @@
-import type { DataSourceId, EndpointId, OperationId } from './data';
+import type { ApiId, EndpointId, OperationId } from './data';
 
 export type ComponentInstanceId = string;
 export type ComponentTypeId = string;
@@ -18,7 +18,7 @@ export type BindingDataPath = string;
 export type BindingValueTransform = 'lowercase' | 'trim' | 'uppercase';
 
 export interface BindingOperationRef {
-  readonly dataSourceId: DataSourceId;
+  readonly apiId: ApiId;
   readonly operationId: OperationId;
   readonly endpointId?: EndpointId;
 }

package/src/data/apis.test.ts

@@ -1,69 +1,79 @@
 import { describe, expect, it } from 'bun:test';
 
-import type { GeneratedApiDefinition, GeneratedApiRegistry } from './apis';
-import { GENERATED_API_CRUD_OPERATIONS } from './apis';
+import type {
+  ApiDefinitionList,
+  ExternalRestApiDefinition,
+  InternalRestApiDefinition,
+} from './apis';
 
 function assertSerializable<TValue>(value: TValue): void {
   expect(JSON.parse(JSON.stringify(value))).toEqual(value);
 }
 
-function createGeneratedApi(): GeneratedApiDefinition {
+function createNutritionApi(): ExternalRestApiDefinition {
   return {
-    id: 'catalog-api',
+    id: 'nutrition',
+    origin: 'external',
     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'],
+    name: 'Nutrition API',
+    baseUrl: 'https://api.ankhorage.com/v1/nutrition',
+    schemas: {
+      Product: {
+        type: 'object',
+        required: ['id', 'name'],
+        properties: {
+          id: { type: 'string', format: 'uuid' },
+          name: { type: 'string' },
+        },
+      },
     },
-    resources: [
-      {
+    endpoints: {
+      products: {
         id: 'products',
-        name: 'Products',
+        kind: 'http',
         path: '/products',
-        collection: {
-          name: 'products',
-          schema: 'public',
-          primaryKey: 'id',
-          fields: [
-            { name: 'id', type: 'uuid', required: true, unique: true },
-            { name: 'name', type: 'text', required: true },
-            { name: 'price', type: 'number', required: true },
-          ],
+        operations: {
+          'products.list': {
+            id: 'products.list',
+            endpointId: 'products',
+            protocol: 'http',
+            intent: 'read',
+            method: 'GET',
+            path: '/products',
+          },
         },
-        operations: GENERATED_API_CRUD_OPERATIONS,
-        seed: [{ id: 'product-1', name: 'Keyboard', price: 120 }],
-        policies: [
-          { id: 'catalog.read', operation: 'list' },
-          { id: 'catalog.write', operation: 'create' },
-        ],
       },
-    ],
+    },
   };
 }
 
-describe('generated API desired-state contracts', () => {
-  it('serializes generated REST/CRUD resources independently of runtime operations', () => {
-    const api = createGeneratedApi();
+describe('canonical API contracts', () => {
+  it('serializes external REST schemas, endpoints, and operations', () => {
+    const api = createNutritionApi();
 
     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');
+    expect(api.baseUrl).toBe('https://api.ankhorage.com/v1/nutrition');
+    expect(api.endpoints.products?.operations['products.list']?.method).toBe('GET');
   });
 
-  it('stores generated APIs in a dedicated canonical registry', () => {
-    const api = createGeneratedApi();
-    const registry: GeneratedApiRegistry = { [api.id]: api };
+  it('stores canonical APIs as an ordered infra list', () => {
+    const apis: ApiDefinitionList = [createNutritionApi()];
 
-    assertSerializable(registry);
-    expect(registry['catalog-api']?.protocol).toBe('rest');
+    assertSerializable(apis);
+    expect(apis[0]?.id).toBe('nutrition');
+  });
+
+  it('reserves an internal REST API identity without persistence implementation', () => {
+    const api: InternalRestApiDefinition = {
+      id: 'future-internal-api',
+      origin: 'internal',
+      protocol: 'rest',
+      basePath: '/v1/internal',
+      endpoints: {},
+    };
+
+    assertSerializable(api);
+    expect('database' in api).toBe(false);
+    expect('adapter' in api).toBe(false);
   });
 });

package/src/data/apis.ts

@@ -1,62 +1,65 @@
-import type { DbCollectionDefinition } from '../db';
-import type { DatabaseAdapterRef } from './refs';
+import type { DataEndpointRegistry } from './endpoints';
+import type { ApiId } from './ids';
+import type { CredentialRef } from './refs';
+import type { DataSchemaRegistry } from './schemas';
 import type { DataContractValue } from './values';
 
-export const GENERATED_API_CRUD_OPERATIONS = [
-  'list',
-  'read',
-  'create',
-  'update',
-  'delete',
-] as const;
-export type GeneratedApiCrudOperation = (typeof GENERATED_API_CRUD_OPERATIONS)[number];
-
-export type GeneratedApiId = string;
-export type GeneratedApiResourceId = string;
-export type GeneratedApiSeedRecord = Readonly<Record<string, DataContractValue>>;
-
-export interface GeneratedApiAuthRequirement {
-  readonly required?: boolean;
-  readonly roles?: readonly string[];
-  readonly permissions?: readonly string[];
-  readonly policy?: string;
+export type ApiOrigin = 'external' | 'internal';
+export type ApiProtocol = 'graphql' | 'rest';
+
+export interface ApiBaseDefinition {
+  readonly id: ApiId;
+  readonly origin: ApiOrigin;
+  readonly protocol: ApiProtocol;
+  readonly name?: string;
+  readonly description?: string;
+  readonly credential?: CredentialRef;
+  readonly endpoints: DataEndpointRegistry;
+  readonly schemas?: DataSchemaRegistry;
   readonly metadata?: DataContractValue;
 }
 
-export interface GeneratedApiOperationPolicyRef {
-  readonly id: string;
-  readonly operation?: GeneratedApiCrudOperation;
+export interface OpenApiDocumentRef {
+  readonly url?: string;
+  readonly documentId?: string;
+  readonly version?: string;
 }
 
-export interface GeneratedApiResourceDefinition {
-  readonly id: GeneratedApiResourceId;
-  readonly name?: string;
-  readonly description?: string;
-  readonly path: string;
-  readonly collection: DbCollectionDefinition;
-  readonly operations: readonly GeneratedApiCrudOperation[];
-  readonly seed?: readonly GeneratedApiSeedRecord[];
-  readonly policies?: readonly GeneratedApiOperationPolicyRef[];
-  readonly metadata?: DataContractValue;
+export interface ExternalRestApiDefinition extends ApiBaseDefinition {
+  readonly origin: 'external';
+  readonly protocol: 'rest';
+  readonly baseUrl: string;
+  readonly openApi?: OpenApiDocumentRef;
+}
+
+export interface GraphQlIntrospectionConfig {
+  readonly enabled: boolean;
+  readonly schemaVersion?: string;
+}
+
+export interface ExternalGraphQlApiDefinition extends ApiBaseDefinition {
+  readonly origin: 'external';
+  readonly protocol: 'graphql';
+  readonly endpointUrl: string;
+  readonly introspection?: GraphQlIntrospectionConfig;
 }
 
 /**
- * Canonical desired state for an API authored and generated by Ankhorage.
+ * Consumer-facing identity for an Ankhorage-owned API.
  *
- * 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.
+ * Internal API generation/execution is intentionally not part of the current
+ * contract. `basePath` reserves the portable API-facing location only; later
+ * infrastructure/runtime packages may implement it without changing bindings.
  */
-export interface GeneratedApiDefinition {
-  readonly id: GeneratedApiId;
+export interface InternalRestApiDefinition extends ApiBaseDefinition {
+  readonly origin: 'internal';
   readonly protocol: 'rest';
-  readonly name?: string;
-  readonly description?: string;
   readonly basePath: string;
-  readonly database: DatabaseAdapterRef;
-  readonly resources: readonly GeneratedApiResourceDefinition[];
-  readonly auth?: GeneratedApiAuthRequirement;
-  readonly metadata?: DataContractValue;
 }
 
-export type GeneratedApiRegistry = Readonly<Record<GeneratedApiId, GeneratedApiDefinition>>;
+export type ApiDefinition =
+  | ExternalGraphQlApiDefinition
+  | ExternalRestApiDefinition
+  | InternalRestApiDefinition;
+
+export type ApiDefinitionList = readonly ApiDefinition[];