@ankhorage/contracts 4.0.1 → 5.0.0

package/src/bindings.test.ts

@@ -1,7 +1,6 @@
 import { describe, expect, it } from 'bun:test';
 
 import type {
-  ApiScreenDataLoaderDefinition,
   AppManifest,
   BindingInputMap,
   BindingValueSource,
@@ -161,37 +160,28 @@ describe('component data-binding contracts', () => {
     expect(binding.target.kind).toBe('action');
   });
 
-  it('serializes supported screen data-loader definitions for api and operation loaders', () => {
-    const loaders: readonly ScreenDataLoaderDefinition[] = [
-      {
-        kind: 'api',
-        apiId: 'catalog',
-        mode: 'byId',
-        targetPath: 'apis.catalog.current',
-        id: 'product-1',
-      } satisfies ApiScreenDataLoaderDefinition,
-      {
-        kind: 'operation',
-        id: 'product-detail',
-        operation: {
-          dataSourceId: 'nutrition-api',
-          endpointId: 'products',
-          operationId: 'nutrition.products.getById',
-        },
-        input: {
-          id: {
-            kind: 'source',
-            source: {
-              kind: 'context',
-              path: 'route.params.id',
-            },
+  it('serializes canonical operation screen data loaders', () => {
+    const loader: ScreenDataLoaderDefinition = {
+      kind: 'operation',
+      id: 'product-detail',
+      operation: {
+        dataSourceId: 'nutrition-api',
+        endpointId: 'products',
+        operationId: 'nutrition.products.getById',
+      },
+      input: {
+        id: {
+          kind: 'source',
+          source: {
+            kind: 'context',
+            path: 'route.params.id',
           },
         },
-      } satisfies OperationScreenDataLoaderDefinition,
-    ];
+      },
+    } satisfies OperationScreenDataLoaderDefinition;
 
-    assertSerializable(loaders);
-    expect(loaders.map((loader) => loader.kind)).toEqual(['api', 'operation']);
+    assertSerializable(loader);
+    expect(loader.kind).toBe('operation');
   });
 
   it('serializes scanner lookup and conditional navigation intent using existing generic bindings', () => {

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/contracts.test.ts

@@ -26,6 +26,7 @@ import {
   type FormSubmitEventDto,
   type ImageAssetSource,
   NAVIGATOR_TYPES,
+  type RouteDefinition,
   type SplashScreenSpec,
   STATE_PERSISTENCE_MODES,
   STATE_PROVIDERS,
@@ -115,6 +116,27 @@ describe('contracts', () => {
     expect(category).toBe('developer_tools');
   });
 
+  it('serializes canonical primary-navigation visibility on routes', () => {
+    const visibleRoute: RouteDefinition = {
+      name: 'home',
+      path: '/',
+      screenId: 'home-screen',
+    };
+    const hiddenRoute: RouteDefinition = {
+      name: 'settings',
+      path: '/settings',
+      screenId: 'settings-screen',
+      showInPrimaryNavigation: false,
+    };
+
+    expect(JSON.parse(JSON.stringify({ visibleRoute, hiddenRoute }))).toEqual({
+      visibleRoute,
+      hiddenRoute,
+    });
+    expect(visibleRoute.showInPrimaryNavigation).toBeUndefined();
+    expect(hiddenRoute.showInPrimaryNavigation).toBe(false);
+  });
+
   it('accepts the current serialized theme config shape', () => {
     const theme: ThemeConfig = {
       id: 'theme-default',
@@ -253,7 +275,7 @@ describe('contracts', () => {
     expect(names.includes('color-theory.ts')).toBe(false);
   });
 
-  it('removes all old tone/mood/recommendation symbols from src recursively', async () => {
+  it('removes obsolete contract symbols from src recursively', async () => {
     const banned = [
       'Color' + 'Tone',
       'color' + 'Tone',
@@ -263,6 +285,7 @@ describe('contracts', () => {
       'APP_' + 'MOODS',
       'suggested' + 'Color' + 'Tone',
       'APP_CATEGORY_' + 'THEME_RECOMMENDATIONS',
+      'hide' + 'InTabBar',
     ];
 
     const srcFiles = await collectTypeScriptFiles(join(process.cwd(), 'src'));

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