@ankhorage/data-sources 0.6.0 → 1.0.0

package/src/rest/index.test.ts

@@ -9,77 +9,13 @@ import {
   normalizeManualRestMethod,
 } from './index';
 
-function assertSerializable<TValue>(value: TValue): void {
-  expect(JSON.parse(JSON.stringify(value))).toEqual(value);
-}
-
-function createBlogDefinition(): ManualRestDataSourceDefinition {
+function definition(): ManualRestDataSourceDefinition {
   return {
     id: 'blog-api',
-    name: 'Blog API',
     baseUrl: 'https://api.example.com',
-    credential: {
-      id: 'blog-api-token',
-      kind: 'bearer',
-      label: 'Blog API token',
-    },
-    schemas: {
-      post: {
-        type: 'object',
-        required: ['id', 'title'],
-        properties: {
-          id: { type: 'string' },
-          title: { type: 'string' },
-          published: { type: 'boolean' },
-        },
-      },
-    },
     endpoints: [
       {
         id: 'posts',
-        path: '/posts',
-        operations: [
-          {
-            id: 'posts.list',
-            method: 'GET',
-            intent: 'read',
-            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',
-            },
-          },
-          {
-            id: 'posts.create',
-            method: 'POST',
-            intent: 'create',
-            request: {
-              contentType: 'application/json',
-              schemaRef: { id: 'post' },
-            },
-            response: {
-              status: 201,
-              schemaRef: { id: 'post' },
-            },
-          },
-        ],
-      },
-      {
-        id: 'post',
         path: '/posts/{postId}',
         operations: [
           {
@@ -94,144 +30,57 @@ function createBlogDefinition(): ManualRestDataSourceDefinition {
                 schema: { type: 'string' },
               },
             ],
-            response: {
-              status: 200,
-              schemaRef: { id: 'post' },
-            },
-          },
-          {
-            id: 'posts.update',
-            method: 'PATCH',
-            intent: 'update',
-            parameters: [
-              {
-                name: 'postId',
-                location: 'path',
-                required: true,
-                schema: { type: 'string' },
-              },
-            ],
-            request: {
-              contentType: 'application/json',
-              schemaRef: { id: 'post' },
-            },
-            response: {
-              status: 200,
-              schemaRef: { id: 'post' },
-            },
-          },
-          {
-            id: 'posts.delete',
-            method: 'DELETE',
-            intent: 'delete',
-            parameters: [
-              {
-                name: 'postId',
-                location: 'path',
-                required: true,
-                schema: { type: 'string' },
-              },
-            ],
-            response: {
-              status: 204,
-            },
           },
+          { id: 'posts.create', method: 'POST', intent: 'create', path: '/posts' },
         ],
       },
     ],
   };
 }
 
-describe('manual REST data-source helpers', () => {
-  it('normalizes REST methods', () => {
+describe('manual REST normalization', () => {
+  it('normalizes methods and path parameters', () => {
     expect(normalizeManualRestMethod('get')).toBe('GET');
     expect(isManualRestMethod('GET')).toBe(true);
     expect(isManualRestMethod('TRACE')).toBe(false);
-  });
-
-  it('extracts braced and colon path parameters', () => {
     expect(extractRestPathParams('/posts/{postId}/comments/:commentId')).toEqual([
       'postId',
       'commentId',
     ]);
   });
 
-  it('normalizes list, get, create, update, and delete operations', () => {
-    const source = normalizeManualRestDataSource(createBlogDefinition());
-
-    assertSerializable(source);
-    expect(source.kind).toBe('rest');
-    expect(source.endpoints.posts?.operations['posts.list']?.intent).toBe('read');
-    expect(source.endpoints.post?.operations['posts.get']?.method).toBe('GET');
+  it('creates an external REST API source', () => {
+    const source = normalizeManualRestDataSource(definition());
+    expect(source).toMatchObject({ kind: 'api', origin: 'external', protocol: 'rest' });
+    expect(source.endpoints.posts?.operations['posts.get']?.method).toBe('GET');
     expect(source.endpoints.posts?.operations['posts.create']?.intent).toBe('create');
-    expect(source.endpoints.post?.operations['posts.update']?.intent).toBe('update');
-    expect(source.endpoints.post?.operations['posts.delete']?.intent).toBe('delete');
   });
 
-  it('returns an ok diagnostic result for valid manual definitions', () => {
-    const result = createManualRestDataSource(createBlogDefinition());
-
-    expect(result.ok).toBe(true);
-    if (result.ok) {
-      expect(
-        result.data.endpoints.post?.operations['posts.get']?.request?.parameters?.[0]?.name,
-      ).toBe('postId');
-      expect(result.diagnostics).toEqual([]);
-    }
+  it('returns canonical diagnostic results', () => {
+    const valid = createManualRestDataSource(definition());
+    const invalid = createManualRestDataSource({ ...definition(), baseUrl: ' ' });
+    expect(valid.ok).toBe(true);
+    expect(invalid.ok).toBe(false);
   });
 
-  it('reports missing base URL', () => {
+  it('reports unsupported methods and missing path parameters', () => {
+    const broken = definition();
     const result = createManualRestDataSource({
-      ...createBlogDefinition(),
-      baseUrl: ' ',
-    });
-
-    expect(result.ok).toBe(false);
-    if (!result.ok) {
-      expect(result.diagnostics.map((diagnostic) => diagnostic.path)).toContain('baseUrl');
-    }
-  });
-
-  it('reports invalid methods and path-template mismatches', () => {
-    const result = createManualRestDataSource({
-      id: 'broken-api',
-      baseUrl: 'https://api.example.com',
+      ...broken,
       endpoints: [
         {
           id: 'broken',
-          path: 'broken/{id}',
-          operations: [
-            {
-              id: 'broken.trace',
-              method: 'TRACE',
-              intent: 'read',
-              parameters: [
-                {
-                  name: 'unusedId',
-                  location: 'path',
-                  schema: { type: 'string' },
-                },
-              ],
-            },
-          ],
+          path: '/broken/{id}',
+          operations: [{ id: 'broken.trace', method: 'TRACE', intent: 'read' }],
         },
       ],
     });
-
     expect(result.ok).toBe(false);
     if (!result.ok) {
-      const messages = result.diagnostics.map((diagnostic) => diagnostic.message);
-
-      expect(messages).toContain('Manual REST endpoint paths must start with `/`.');
-      expect(messages).toContain(
-        'Manual REST operation method must be one of DELETE, GET, HEAD, OPTIONS, PATCH, POST, PUT.',
-      );
-      expect(messages).toContain(
-        "Path template parameter 'id' must have a matching path parameter definition.",
-      );
-      expect(messages).toContain(
-        "Path parameter 'unusedId' is not referenced by the operation path template.",
-      );
+      expect(result.diagnostics.map((diagnostic) => diagnostic.code)).toEqual([
+        'invalid-config',
+        'invalid-config',
+      ]);
     }
   });
 });

package/src/rest/index.ts

@@ -13,8 +13,8 @@ import type {
   DataSourceDiagnostic,
   DataSourceDiagnosticResult,
   EndpointId,
+  ExternalRestApiDataSourceConfig,
   OperationId,
-  RestDataSourceConfig,
 } from '@ankhorage/contracts/data';
 
 const REST_METHODS = ['DELETE', 'GET', 'HEAD', 'OPTIONS', 'PATCH', 'POST', 'PUT'] as const;
@@ -111,52 +111,7 @@ export function validateManualRestDataSource(
     }
 
     for (const operation of endpoint.operations) {
-      const normalizedMethod = normalizeManualRestMethod(operation.method);
-      const operationPath = operation.path ?? endpoint.path;
-      const templateParams = extractRestPathParams(operationPath);
-      const pathParameters =
-        operation.parameters?.filter((parameter) => parameter.location === 'path') ?? [];
-      const pathParameterNames = new Set(pathParameters.map((parameter) => parameter.name));
-
-      if (!isManualRestMethod(normalizedMethod)) {
-        diagnostics.push({
-          code: 'invalid-config',
-          dataSourceId: definition.id,
-          endpointId: endpoint.id,
-          operationId: operation.id,
-          message: `Manual REST operation method must be one of ${REST_METHODS.join(', ')}.`,
-          path: `endpoints.${endpoint.id}.operations.${operation.id}.method`,
-          severity: 'error',
-        });
-      }
-
-      for (const templateParam of templateParams) {
-        if (!pathParameterNames.has(templateParam)) {
-          diagnostics.push({
-            code: 'invalid-config',
-            dataSourceId: definition.id,
-            endpointId: endpoint.id,
-            operationId: operation.id,
-            message: `Path template parameter '${templateParam}' must have a matching path parameter definition.`,
-            path: `endpoints.${endpoint.id}.operations.${operation.id}.parameters`,
-            severity: 'error',
-          });
-        }
-      }
-
-      for (const pathParameter of pathParameters) {
-        if (!templateParams.includes(pathParameter.name)) {
-          diagnostics.push({
-            code: 'invalid-config',
-            dataSourceId: definition.id,
-            endpointId: endpoint.id,
-            operationId: operation.id,
-            message: `Path parameter '${pathParameter.name}' is not referenced by the operation path template.`,
-            path: `endpoints.${endpoint.id}.operations.${operation.id}.parameters.${pathParameter.name}`,
-            severity: 'error',
-          });
-        }
-      }
+      validateManualRestOperation(definition, endpoint, operation, diagnostics);
     }
   }
 
@@ -165,11 +120,9 @@ export function validateManualRestDataSource(
 
 export function createManualRestDataSource(
   definition: ManualRestDataSourceDefinition,
-): DataSourceDiagnosticResult<RestDataSourceConfig> {
+): DataSourceDiagnosticResult<ExternalRestApiDataSourceConfig> {
   const diagnostics = validateManualRestDataSource(definition);
-  const hasErrors = diagnostics.some((diagnostic) => diagnostic.severity === 'error');
-
-  if (hasErrors) {
+  if (diagnostics.some((diagnostic) => diagnostic.severity === 'error')) {
     return { ok: false, diagnostics };
   }
 
@@ -182,22 +135,18 @@ export function createManualRestDataSource(
 
 export function normalizeManualRestDataSource(
   definition: ManualRestDataSourceDefinition,
-): RestDataSourceConfig {
+): ExternalRestApiDataSourceConfig {
   const endpoints: Record<EndpointId, DataEndpointConfig> = {};
 
   for (const endpoint of definition.endpoints) {
     const operations: Record<OperationId, DataOperationConfig> = {};
 
     for (const operation of endpoint.operations) {
-      const operationPath = operation.path ?? endpoint.path;
       const { parameters } = operation;
       const request: DataOperationRequest | undefined =
         operation.request === undefined && parameters === undefined
           ? undefined
-          : {
-              ...operation.request,
-              parameters,
-            };
+          : { ...operation.request, parameters };
 
       operations[operation.id] = {
         id: operation.id,
@@ -207,7 +156,7 @@ export function normalizeManualRestDataSource(
         protocol: 'http',
         intent: operation.intent,
         method: normalizeManualRestMethod(operation.method),
-        path: operationPath,
+        path: operation.path ?? endpoint.path,
         request,
         response: operation.response,
         pagination: operation.pagination,
@@ -231,7 +180,9 @@ export function normalizeManualRestDataSource(
 
   return {
     id: definition.id,
-    kind: 'rest',
+    kind: 'api',
+    origin: 'external',
+    protocol: 'rest',
     name: definition.name,
     description: definition.description,
     baseUrl: definition.baseUrl,
@@ -241,3 +192,55 @@ export function normalizeManualRestDataSource(
     metadata: definition.metadata,
   };
 }
+
+function validateManualRestOperation(
+  definition: ManualRestDataSourceDefinition,
+  endpoint: ManualRestEndpointDefinition,
+  operation: ManualRestOperationDefinition,
+  diagnostics: DataSourceDiagnostic[],
+): void {
+  const method = normalizeManualRestMethod(operation.method);
+  const path = operation.path ?? endpoint.path;
+  const templateParams = extractRestPathParams(path);
+  const pathParameters =
+    operation.parameters?.filter((parameter) => parameter.location === 'path') ?? [];
+  const pathParameterNames = new Set(pathParameters.map((parameter) => parameter.name));
+
+  if (!isManualRestMethod(method)) {
+    diagnostics.push({
+      code: 'invalid-config',
+      dataSourceId: definition.id,
+      endpointId: endpoint.id,
+      operationId: operation.id,
+      message: `Manual REST operation method must be one of ${REST_METHODS.join(', ')}.`,
+      path: `endpoints.${endpoint.id}.operations.${operation.id}.method`,
+      severity: 'error',
+    });
+  }
+
+  for (const templateParam of templateParams) {
+    if (pathParameterNames.has(templateParam)) continue;
+    diagnostics.push({
+      code: 'invalid-config',
+      dataSourceId: definition.id,
+      endpointId: endpoint.id,
+      operationId: operation.id,
+      message: `Path template parameter '${templateParam}' must have a matching path parameter definition.`,
+      path: `endpoints.${endpoint.id}.operations.${operation.id}.parameters`,
+      severity: 'error',
+    });
+  }
+
+  for (const pathParameter of pathParameters) {
+    if (templateParams.includes(pathParameter.name)) continue;
+    diagnostics.push({
+      code: 'invalid-config',
+      dataSourceId: definition.id,
+      endpointId: endpoint.id,
+      operationId: operation.id,
+      message: `Path parameter '${pathParameter.name}' is not referenced by the operation path template.`,
+      path: `endpoints.${endpoint.id}.operations.${operation.id}.parameters.${pathParameter.name}`,
+      severity: 'error',
+    });
+  }
+}