@ankhorage/data-sources 1.0.1 → 2.0.0

package/src/rest/index.ts

@@ -13,7 +13,7 @@ import type {
   DataSourceDiagnostic,
   DataSourceDiagnosticResult,
   EndpointId,
-  ExternalRestApiDataSourceConfig,
+  ExternalRestApiDefinition,
   OperationId,
 } from '@ankhorage/contracts/data';
 
@@ -46,7 +46,7 @@ export interface ManualRestEndpointDefinition {
   readonly metadata?: DataContractValue;
 }
 
-export interface ManualRestDataSourceDefinition {
+export interface ManualRestApiDefinition {
   readonly id: string;
   readonly baseUrl: string;
   readonly name?: string;
@@ -83,16 +83,16 @@ export function extractRestPathParams(path: string): readonly string[] {
   return [...params];
 }
 
-export function validateManualRestDataSource(
-  definition: ManualRestDataSourceDefinition,
+export function validateManualRestApi(
+  definition: ManualRestApiDefinition,
 ): readonly DataSourceDiagnostic[] {
   const diagnostics: DataSourceDiagnostic[] = [];
 
   if (definition.baseUrl.trim().length === 0) {
     diagnostics.push({
       code: 'invalid-config',
-      dataSourceId: definition.id,
-      message: 'Manual REST data source requires a non-empty baseUrl.',
+      apiId: definition.id,
+      message: 'Manual REST API requires a non-empty baseUrl.',
       path: 'baseUrl',
       severity: 'error',
     });
@@ -102,7 +102,7 @@ export function validateManualRestDataSource(
     if (!endpoint.path.startsWith('/')) {
       diagnostics.push({
         code: 'invalid-config',
-        dataSourceId: definition.id,
+        apiId: definition.id,
         endpointId: endpoint.id,
         message: 'Manual REST endpoint paths must start with `/`.',
         path: `endpoints.${endpoint.id}.path`,
@@ -118,69 +118,30 @@ export function validateManualRestDataSource(
   return diagnostics;
 }
 
-export function createManualRestDataSource(
-  definition: ManualRestDataSourceDefinition,
-): DataSourceDiagnosticResult<ExternalRestApiDataSourceConfig> {
-  const diagnostics = validateManualRestDataSource(definition);
+export function createManualRestApi(
+  definition: ManualRestApiDefinition,
+): DataSourceDiagnosticResult<ExternalRestApiDefinition> {
+  const diagnostics = validateManualRestApi(definition);
   if (diagnostics.some((diagnostic) => diagnostic.severity === 'error')) {
     return { ok: false, diagnostics };
   }
 
   return {
     ok: true,
-    data: normalizeManualRestDataSource(definition),
+    data: normalizeManualRestApi(definition),
     diagnostics,
   };
 }
 
-export function normalizeManualRestDataSource(
-  definition: ManualRestDataSourceDefinition,
-): ExternalRestApiDataSourceConfig {
-  const endpoints: Record<EndpointId, DataEndpointConfig> = {};
-
-  for (const endpoint of definition.endpoints) {
-    const operations: Record<OperationId, DataOperationConfig> = {};
-
-    for (const operation of endpoint.operations) {
-      const { parameters } = operation;
-      const request: DataOperationRequest | undefined =
-        operation.request === undefined && parameters === undefined
-          ? undefined
-          : { ...operation.request, parameters };
-
-      operations[operation.id] = {
-        id: operation.id,
-        endpointId: endpoint.id,
-        name: operation.name,
-        description: operation.description,
-        protocol: 'http',
-        intent: operation.intent,
-        method: normalizeManualRestMethod(operation.method),
-        path: operation.path ?? endpoint.path,
-        request,
-        response: operation.response,
-        pagination: operation.pagination,
-        credential: operation.credential,
-        metadata: operation.metadata,
-      };
-    }
-
-    endpoints[endpoint.id] = {
-      id: endpoint.id,
-      kind: 'http',
-      name: endpoint.name,
-      description: endpoint.description,
-      baseUrl: definition.baseUrl,
-      path: endpoint.path,
-      credential: endpoint.credential,
-      operations,
-      metadata: endpoint.metadata,
-    };
-  }
+export function normalizeManualRestApi(
+  definition: ManualRestApiDefinition,
+): ExternalRestApiDefinition {
+  const endpoints = Object.fromEntries(
+    definition.endpoints.map((endpoint) => [endpoint.id, normalizeManualRestEndpoint(endpoint)]),
+  );
 
   return {
     id: definition.id,
-    kind: 'api',
     origin: 'external',
     protocol: 'rest',
     name: definition.name,
@@ -193,8 +154,53 @@ export function normalizeManualRestDataSource(
   };
 }
 
+function normalizeManualRestEndpoint(endpoint: ManualRestEndpointDefinition): DataEndpointConfig {
+  const operations = Object.fromEntries(
+    endpoint.operations.map((operation) => [
+      operation.id,
+      normalizeManualRestOperation(endpoint, operation),
+    ]),
+  );
+  return {
+    id: endpoint.id,
+    kind: 'http',
+    name: endpoint.name,
+    description: endpoint.description,
+    path: endpoint.path,
+    credential: endpoint.credential,
+    operations,
+    metadata: endpoint.metadata,
+  };
+}
+
+function normalizeManualRestOperation(
+  endpoint: ManualRestEndpointDefinition,
+  operation: ManualRestOperationDefinition,
+): DataOperationConfig {
+  const { parameters } = operation;
+  const request: DataOperationRequest | undefined =
+    operation.request === undefined && parameters === undefined
+      ? undefined
+      : { ...operation.request, parameters };
+  return {
+    id: operation.id,
+    endpointId: endpoint.id,
+    name: operation.name,
+    description: operation.description,
+    protocol: 'http',
+    intent: operation.intent,
+    method: normalizeManualRestMethod(operation.method),
+    path: operation.path ?? endpoint.path,
+    request,
+    response: operation.response,
+    pagination: operation.pagination,
+    credential: operation.credential,
+    metadata: operation.metadata,
+  };
+}
+
 function validateManualRestOperation(
-  definition: ManualRestDataSourceDefinition,
+  definition: ManualRestApiDefinition,
   endpoint: ManualRestEndpointDefinition,
   operation: ManualRestOperationDefinition,
   diagnostics: DataSourceDiagnostic[],
@@ -209,7 +215,7 @@ function validateManualRestOperation(
   if (!isManualRestMethod(method)) {
     diagnostics.push({
       code: 'invalid-config',
-      dataSourceId: definition.id,
+      apiId: definition.id,
       endpointId: endpoint.id,
       operationId: operation.id,
       message: `Manual REST operation method must be one of ${REST_METHODS.join(', ')}.`,
@@ -222,7 +228,7 @@ function validateManualRestOperation(
     if (pathParameterNames.has(templateParam)) continue;
     diagnostics.push({
       code: 'invalid-config',
-      dataSourceId: definition.id,
+      apiId: definition.id,
       endpointId: endpoint.id,
       operationId: operation.id,
       message: `Path template parameter '${templateParam}' must have a matching path parameter definition.`,
@@ -235,7 +241,7 @@ function validateManualRestOperation(
     if (templateParams.includes(pathParameter.name)) continue;
     diagnostics.push({
       code: 'invalid-config',
-      dataSourceId: definition.id,
+      apiId: definition.id,
       endpointId: endpoint.id,
       operationId: operation.id,
       message: `Path parameter '${pathParameter.name}' is not referenced by the operation path template.`,

package/src/test-runner/index.test.ts

@@ -1,12 +1,37 @@
-import type { DataSourceConfig } from '@ankhorage/contracts/data';
-import { describe, expect, it } from 'bun:test';
+import type { ApiDefinition, ExternalRestApiDefinition } from '@ankhorage/contracts/data';
+import { expect, it } from 'bun:test';
 
 import { buildEndpointTestRequest, type EndpointTestFetch, testEndpoint } from './index';
 
-function restSource(): DataSourceConfig {
+function nutritionApi(): ExternalRestApiDefinition {
+  return {
+    id: 'nutrition',
+    origin: 'external',
+    protocol: 'rest',
+    baseUrl: 'https://api.ankhorage.com/v1/nutrition',
+    endpoints: {
+      products: {
+        id: 'products',
+        kind: 'http',
+        path: '/products',
+        operations: {
+          'products.list': {
+            id: 'products.list',
+            endpointId: 'products',
+            protocol: 'http',
+            intent: 'read',
+            method: 'GET',
+            path: '/products',
+          },
+        },
+      },
+    },
+  };
+}
+
+function parameterApi(): ExternalRestApiDefinition {
   return {
     id: 'cms',
-    kind: 'api',
     origin: 'external',
     protocol: 'rest',
     baseUrl: 'https://cms.example.com',
@@ -15,7 +40,6 @@ function restSource(): DataSourceConfig {
       posts: {
         id: 'posts',
         kind: 'http',
-        path: '/posts/{postId}',
         operations: {
           'posts.get': {
             id: 'posts.get',
@@ -26,13 +50,9 @@ function restSource(): DataSourceConfig {
             path: '/posts/{postId}',
             request: {
               parameters: [
-                {
-                  name: 'postId',
-                  location: 'path',
-                  required: true,
-                  schema: { type: 'string' },
-                },
+                { name: 'postId', location: 'path', required: true, schema: { type: 'string' } },
                 { name: 'preview', location: 'query', schema: { type: 'boolean' } },
+                { name: 'x-locale', location: 'header', schema: { type: 'string' } },
               ],
             },
           },
@@ -43,6 +63,13 @@ function restSource(): DataSourceConfig {
             intent: 'create',
             method: 'POST',
             path: '/posts',
+            request: {
+              contentType: 'application/json',
+              parameters: [
+                { name: 'title', location: 'body', required: true, schema: { type: 'string' } },
+                { name: 'published', location: 'body', schema: { type: 'boolean' } },
+              ],
+            },
           },
         },
       },
@@ -50,10 +77,9 @@ function restSource(): DataSourceConfig {
   };
 }
 
-function graphQlSource(): DataSourceConfig {
+function graphQlApi(): ApiDefinition {
   return {
     id: 'content',
-    kind: 'api',
     origin: 'external',
     protocol: 'graphql',
     endpointUrl: 'https://content.example.com/graphql',
@@ -75,124 +101,131 @@ function graphQlSource(): DataSourceConfig {
   };
 }
 
-describe('endpoint test runner', () => {
-  it('builds REST dry runs with params and credential headers', async () => {
-    const result = await buildEndpointTestRequest({
-      dataSource: restSource(),
-      endpointId: 'posts',
-      operationId: 'posts.get',
-      dryRun: true,
-      values: { postId: 'post 1', preview: true },
-      credentialResolver: () => ({ headers: { authorization: 'Bearer token' } }),
-    });
-    expect(result.ok).toBe(true);
-    if (result.ok) {
-      expect(result.request.url).toBe('https://cms.example.com/posts/post%201?preview=true');
-      expect(result.request.headers.authorization).toBe('Bearer token');
-    }
+it('builds the canonical Nutrition products URL', async () => {
+  const result = await buildEndpointTestRequest({
+    api: nutritionApi(),
+    endpointId: 'products',
+    operationId: 'products.list',
+    dryRun: true,
   });
+  expect(result.ok).toBe(true);
+  if (result.ok) {
+    expect(result.request.apiId).toBe('nutrition');
+    expect(result.request.method).toBe('GET');
+    expect(result.request.url).toBe('https://api.ankhorage.com/v1/nutrition/products');
+  }
+});
 
-  it('executes REST requests and parses responses', async () => {
-    const fetch: EndpointTestFetch = () =>
-      Promise.resolve({ status: 200, text: () => Promise.resolve('{"id":"post-1"}') });
-    const result = await testEndpoint({
-      dataSource: restSource(),
-      endpointId: 'posts',
-      operationId: 'posts.get',
-      values: { postId: 'post-1' },
-      credentialResolver: () => ({ headers: { authorization: 'Bearer token' } }),
-      fetch,
+it('serializes path, query and header parameters with credentials', async () => {
+  const result = await buildEndpointTestRequest({
+    api: parameterApi(),
+    endpointId: 'posts',
+    operationId: 'posts.get',
+    dryRun: true,
+    values: { postId: 'post 1', preview: true, 'x-locale': 'de-CH' },
+    credentialResolver: () => ({ headers: { authorization: 'Bearer token' } }),
+  });
+  expect(result.ok).toBe(true);
+  if (result.ok) {
+    expect(result.request.url).toBe('https://cms.example.com/posts/post%201?preview=true');
+    expect(result.request.headers).toEqual({
+      authorization: 'Bearer token',
+      'x-locale': 'de-CH',
     });
-    expect(result.ok).toBe(true);
-    if (result.ok) expect(result.data).toEqual({ id: 'post-1' });
+  }
+});
+
+it('serializes body parameters without provider-specific handling', async () => {
+  const result = await buildEndpointTestRequest({
+    api: parameterApi(),
+    endpointId: 'posts',
+    operationId: 'posts.create',
+    dryRun: true,
+    values: { title: 'Hello', published: true },
+    credentialResolver: () => ({ headers: {} }),
   });
+  expect(result.ok).toBe(true);
+  if (result.ok) {
+    expect(result.request.body).toBe('{"title":"Hello","published":true}');
+    expect(result.request.headers['content-type']).toBe('application/json');
+  }
+});
 
-  it('returns HTTP, network, credential and input diagnostics', async () => {
-    const http = await testEndpoint({
-      dataSource: restSource(),
-      endpointId: 'posts',
-      operationId: 'posts.get',
-      values: { postId: 'missing' },
-      credentialResolver: () => ({ headers: {} }),
-      fetch: () => Promise.resolve({ status: 404, text: () => Promise.resolve('{}') }),
-    });
-    const network = await testEndpoint({
-      dataSource: restSource(),
-      endpointId: 'posts',
-      operationId: 'posts.get',
-      values: { postId: 'x' },
-      credentialResolver: () => ({ headers: {} }),
-      fetch: () => Promise.reject(new Error('Connection failed')),
-    });
-    const credential = await buildEndpointTestRequest({
-      dataSource: restSource(),
-      endpointId: 'posts',
-      operationId: 'posts.get',
-      values: { postId: 'x' },
-    });
-    const input = await buildEndpointTestRequest({
-      dataSource: restSource(),
-      endpointId: 'posts',
-      operationId: 'posts.get',
-      credentialResolver: () => ({ headers: {} }),
-    });
-    expect(http.ok).toBe(false);
-    expect(network.ok).toBe(false);
-    expect(credential.ok).toBe(false);
-    expect(input.ok).toBe(false);
+it('executes external REST requests and parses responses', async () => {
+  const fetch: EndpointTestFetch = () =>
+    Promise.resolve({ status: 200, text: () => Promise.resolve('{"products":[]}') });
+  const result = await testEndpoint({
+    api: nutritionApi(),
+    endpointId: 'products',
+    operationId: 'products.list',
+    fetch,
   });
+  expect(result.ok).toBe(true);
+  if (result.ok) expect(result.data).toEqual({ products: [] });
+});
 
-  it('builds POST bodies and GraphQL requests', async () => {
-    const post = await buildEndpointTestRequest({
-      dataSource: restSource(),
-      endpointId: 'posts',
-      operationId: 'posts.create',
-      dryRun: true,
-      values: { body: { title: 'Hello' } },
-      credentialResolver: () => ({ headers: {} }),
-    });
-    const graphql = await buildEndpointTestRequest({
-      dataSource: graphQlSource(),
-      endpointId: 'graphql',
-      operationId: 'query.viewer',
-      dryRun: true,
-      values: { variables: { id: 'viewer-1' } },
-    });
-    expect(post.ok).toBe(true);
-    if (post.ok) expect(post.request.body).toBe('{"title":"Hello"}');
-    expect(graphql.ok).toBe(true);
-    if (graphql.ok) expect(graphql.request.url).toBe('https://content.example.com/graphql');
+it('builds GraphQL requests through the same canonical API input', async () => {
+  const result = await buildEndpointTestRequest({
+    api: graphQlApi(),
+    endpointId: 'graphql',
+    operationId: 'query.viewer',
+    dryRun: true,
+    values: { variables: { id: 'viewer-1' } },
   });
+  expect(result.ok).toBe(true);
+  if (result.ok) {
+    expect(result.request.url).toBe('https://content.example.com/graphql');
+    expect(result.request.method).toBe('POST');
+  }
+});
 
-  it('does not pretend database-backed generated operations are HTTP endpoints', async () => {
-    const source: DataSourceConfig = {
-      id: 'catalog',
-      kind: 'api',
-      origin: 'generated',
-      protocol: 'rest',
-      generatedApiId: 'catalog',
-      adapter: { id: 'db', kind: 'database' },
-      endpoints: {
-        products: {
-          id: 'products',
-          kind: 'database',
-          operations: {
-            'products.list': {
-              id: 'products.list',
-              endpointId: 'products',
-              protocol: 'database',
-              intent: 'read',
-            },
+it('rejects internal APIs during phase 1', async () => {
+  const internal: ApiDefinition = {
+    id: 'future-api',
+    origin: 'internal',
+    protocol: 'rest',
+    basePath: '/v1/future',
+    endpoints: {},
+  };
+  const result = await buildEndpointTestRequest({
+    api: internal,
+    endpointId: 'products',
+    operationId: 'products.list',
+  });
+  expect(result.ok).toBe(false);
+  if (!result.ok) {
+    expect(result.diagnostics[0]?.apiId).toBe('future-api');
+    expect(result.diagnostics[0]?.message).toContain('not executable in API phase 1');
+  }
+});
+
+it('never treats database protocol operations as API HTTP operations', async () => {
+  const api: ExternalRestApiDefinition = {
+    id: 'broken-api',
+    origin: 'external',
+    protocol: 'rest',
+    baseUrl: 'https://example.com',
+    endpoints: {
+      products: {
+        id: 'products',
+        kind: 'http',
+        operations: {
+          'products.list': {
+            id: 'products.list',
+            endpointId: 'products',
+            protocol: 'database',
+            intent: 'read',
+            path: '/products',
           },
         },
       },
-    };
-    const result = await buildEndpointTestRequest({
-      dataSource: source,
-      endpointId: 'products',
-      operationId: 'products.list',
-    });
-    expect(result.ok).toBe(false);
-    if (!result.ok) expect(result.diagnostics[0]?.message).toContain('adapter executor');
+    },
+  };
+  const result = await buildEndpointTestRequest({
+    api,
+    endpointId: 'products',
+    operationId: 'products.list',
   });
+  expect(result.ok).toBe(false);
+  if (!result.ok) expect(result.diagnostics[0]?.message).toContain("protocol 'database'");
 });