@ankhorage/data-sources 0.5.5 → 1.0.0

package/src/openapi/index.test.ts

@@ -8,289 +8,79 @@ import {
   type OpenApiDocumentObject,
 } from './index';
 
-function assertSerializable<TValue>(value: TValue): void {
-  expect(JSON.parse(JSON.stringify(value))).toEqual(value);
-}
-
-function createPetStoreDocument(): OpenApiDocumentObject {
+function document(): OpenApiDocumentObject {
   return {
     openapi: '3.1.0',
-    info: {
-      title: 'Pet Store',
-      version: '2026-05-19',
-      description: 'Example API.',
-    },
-    servers: [
-      {
-        url: 'https://api.example.com',
-      },
-    ],
+    info: { title: 'Pet Store', version: '2026-08-06' },
+    servers: [{ url: 'https://api.example.com' }],
     components: {
       schemas: {
         Pet: {
           type: 'object',
-          required: ['id', 'name'],
-          properties: {
-            id: { type: 'string' },
-            name: { type: 'string' },
-            age: { type: 'integer' },
-          },
+          required: ['id'],
+          properties: { id: { type: 'string' }, name: { type: 'string' } },
         },
       },
     },
     paths: {
       '/pets': {
-        get: {
-          operationId: 'listPets',
-          summary: 'List pets',
-          parameters: [
-            {
-              name: 'limit',
-              in: 'query',
-              schema: { type: 'integer', default: 20 },
-            },
-          ],
-          responses: {
-            '200': {
-              description: 'Pets',
-              content: {
-                'application/json': {
-                  schema: {
-                    type: 'array',
-                    items: { $ref: '#/components/schemas/Pet' },
-                  },
-                },
-              },
-            },
-          },
-        },
-        post: {
-          operationId: 'createPet',
-          summary: 'Create pet',
-          requestBody: {
-            required: true,
-            content: {
-              'application/json': {
-                schema: { $ref: '#/components/schemas/Pet' },
-              },
-            },
-          },
-          responses: {
-            '201': {
-              description: 'Created pet',
-              content: {
-                'application/json': {
-                  schema: { $ref: '#/components/schemas/Pet' },
-                },
-              },
-            },
-          },
-        },
-      },
-      '/pets/{petId}': {
-        parameters: [
-          {
-            name: 'petId',
-            in: 'path',
-            required: true,
-            schema: { type: 'string' },
-          },
-        ],
-        get: {
-          operationId: 'getPet',
-          responses: {
-            '200': {
-              description: 'Pet',
-              content: {
-                'application/json': {
-                  schema: { $ref: '#/components/schemas/Pet' },
-                },
-              },
-            },
-          },
-        },
-        patch: {
-          operationId: 'updatePet',
-          requestBody: {
-            content: {
-              'application/json': {
-                schema: { $ref: '#/components/schemas/Pet' },
-              },
-            },
-          },
-          responses: {
-            '200': {
-              description: 'Updated pet',
-              content: {
-                'application/json': {
-                  schema: { $ref: '#/components/schemas/Pet' },
-                },
-              },
-            },
-          },
-        },
-        delete: {
-          operationId: 'deletePet',
-          responses: {
-            '204': {
-              description: 'Deleted pet',
-            },
-          },
-        },
+        get: { operationId: 'listPets', responses: { '200': { description: 'Pets' } } },
+        post: { operationId: 'createPet', responses: { '201': { description: 'Pet' } } },
       },
     },
   };
 }
 
-describe('OpenAPI import normalization', () => {
-  it('normalizes deterministic endpoint and operation ids', () => {
+describe('OpenAPI normalization', () => {
+  it('normalizes endpoint, operation and schema shapes', () => {
     expect(normalizeOpenApiEndpointId('/pets/{petId}')).toBe('pets-petid');
     expect(normalizeOpenApiOperationId('get', '/pets/{petId}')).toBe('get-pets-petid');
-    expect(normalizeOpenApiOperationId('get', '/', '')).toBe('get-root');
-  });
-
-  it('normalizes OpenAPI schemas into data schemas', () => {
-    const schema = normalizeOpenApiSchema({
-      type: 'object',
-      properties: {
-        id: { type: 'string' },
-        tags: { type: 'array', items: { type: 'string' } },
-      },
-      required: ['id'],
-    });
-
-    assertSerializable(schema);
-    expect(schema.type).toBe('object');
-    expect(schema.properties?.tags?.items?.type).toBe('string');
+    expect(normalizeOpenApiSchema({ type: 'array', items: { type: 'string' } }).items?.type).toBe(
+      'string',
+    );
   });
 
-  it('imports a minimal OpenAPI document into a normalized OpenAPI data source', () => {
+  it('imports OpenAPI as an external REST source with OpenAPI metadata', () => {
     const result = importOpenApiDocument({
       id: 'pet-store',
-      document: createPetStoreDocument(),
+      document: document(),
       documentUrl: 'https://api.example.com/openapi.json',
-      credential: {
-        id: 'pet-store-token',
-        kind: 'bearer',
-      },
     });
-
     expect(result.ok).toBe(true);
     if (result.ok) {
-      assertSerializable(result.data);
-      expect(result.data.kind).toBe('openapi');
-      expect(result.data.baseUrl).toBe('https://api.example.com');
-      expect(result.data.import?.version).toBe('2026-05-19');
-      expect(result.data.schemas?.Pet?.properties?.name?.type).toBe('string');
+      expect(result.data).toMatchObject({ kind: 'api', origin: 'external', protocol: 'rest' });
+      expect(result.data.openApi?.version).toBe('2026-08-06');
       expect(result.data.endpoints.pets?.operations.listpets?.intent).toBe('read');
       expect(result.data.endpoints.pets?.operations.createpet?.intent).toBe('create');
-      expect(
-        result.data.endpoints['pets-petid']?.operations.getpet?.request?.parameters?.[0]?.name,
-      ).toBe('petId');
-      expect(result.data.endpoints['pets-petid']?.operations.updatepet?.intent).toBe('update');
-      expect(result.data.endpoints['pets-petid']?.operations.deletepet?.intent).toBe('delete');
     }
   });
 
-  it('uses an explicit baseUrl override and reports ambiguous servers', () => {
-    const document: OpenApiDocumentObject = {
-      ...createPetStoreDocument(),
-      servers: [{ url: 'https://first.example.com' }, { url: 'https://second.example.com' }],
-    };
+  it('uses an explicit base URL and reports ambiguous servers', () => {
     const result = importOpenApiDocument({
       id: 'pet-store',
-      document,
-      baseUrl: 'https://override.example.com',
-    });
-
-    expect(result.ok).toBe(true);
-    if (result.ok) {
-      expect(result.data.baseUrl).toBe('https://override.example.com');
-      expect(result.diagnostics).toEqual([]);
-    }
-  });
-
-  it('reports ambiguous server diagnostics when no baseUrl override exists', () => {
-    const document: OpenApiDocumentObject = {
-      ...createPetStoreDocument(),
-      servers: [{ url: 'https://first.example.com' }, { url: 'https://second.example.com' }],
-    };
-    const result = importOpenApiDocument({ id: 'pet-store', document });
-
-    expect(result.ok).toBe(true);
-    if (result.ok) {
-      expect(result.data.baseUrl).toBe('https://first.example.com');
-      expect(result.diagnostics?.map((diagnostic) => diagnostic.code)).toContain(
-        'ambiguous-server',
-      );
-    }
-  });
-
-  it('deduplicates duplicate operation IDs deterministically', () => {
-    const document: OpenApiDocumentObject = {
-      openapi: '3.1.0',
-      paths: {
-        '/one': {
-          get: { operationId: 'duplicate', responses: { '200': { description: 'OK' } } },
-        },
-        '/two': {
-          get: { operationId: 'duplicate', responses: { '200': { description: 'OK' } } },
-        },
+      document: {
+        ...document(),
+        servers: [{ url: 'https://one.example.com' }, { url: 'https://two.example.com' }],
       },
-    };
-    const result = importOpenApiDocument({
-      id: 'duplicates',
-      document,
-      baseUrl: 'https://api.example.com',
+      baseUrl: 'https://override.example.com',
     });
-
     expect(result.ok).toBe(true);
-    if (result.ok) {
-      expect(result.data.endpoints.one?.operations.duplicate?.id).toBe('duplicate');
-      expect(result.data.endpoints.two?.operations['duplicate-2']?.id).toBe('duplicate-2');
-      expect(result.diagnostics?.map((diagnostic) => diagnostic.code)).toContain(
-        'duplicate-operation-id',
-      );
-    }
+    if (result.ok) expect(result.data.baseUrl).toBe('https://override.example.com');
   });
 
-  it('returns an error diagnostic when paths are missing', () => {
-    const result = importOpenApiDocument({
-      id: 'empty',
-      document: { openapi: '3.1.0' },
-      baseUrl: 'https://api.example.com',
-    });
-
-    expect(result.ok).toBe(false);
-    if (!result.ok) {
-      expect(result.diagnostics.map((diagnostic) => diagnostic.code)).toContain('invalid-config');
-    }
-  });
-
-  it('reports unsupported schema types as warnings', () => {
-    const result = importOpenApiDocument({
-      id: 'unsupported-schema',
-      baseUrl: 'https://api.example.com',
-      document: {
-        openapi: '3.1.0',
-        components: {
-          schemas: {
-            Weird: { type: 'file' },
-          },
-        },
-        paths: {
-          '/weird': {
-            get: { responses: { '200': { description: 'OK' } } },
-          },
-        },
-      },
-    });
-
-    expect(result.ok).toBe(true);
-    if (result.ok) {
-      expect(result.diagnostics?.map((diagnostic) => diagnostic.code)).toContain(
-        'unsupported-schema',
-      );
-    }
+  it('requires a resolvable base URL and paths', () => {
+    expect(
+      importOpenApiDocument({
+        id: 'no-server',
+        document: { openapi: '3.1.0', paths: { '/x': { get: {} } } },
+      }).ok,
+    ).toBe(false);
+    expect(
+      importOpenApiDocument({
+        id: 'no-paths',
+        baseUrl: 'https://example.com',
+        document: { openapi: '3.1.0' },
+      }).ok,
+    ).toBe(false);
   });
 });

package/src/openapi/index.ts

@@ -14,7 +14,7 @@ import type {
   DataSourceDiagnostic,
   DataSourceDiagnosticResult,
   EndpointId,
-  OpenApiDataSourceConfig,
+  ExternalRestApiDataSourceConfig,
   OperationId,
 } from '@ankhorage/contracts/data';
 
@@ -121,7 +121,7 @@ export interface OpenApiImportInput {
   readonly metadata?: DataContractValue;
 }
 
-export type OpenApiImportResult = DataSourceDiagnosticResult<OpenApiDataSourceConfig>;
+export type OpenApiImportResult = DataSourceDiagnosticResult<ExternalRestApiDataSourceConfig>;
 
 export function importOpenApiDocument(input: OpenApiImportInput): OpenApiImportResult {
   const diagnostics: DataSourceDiagnostic[] = [];
@@ -132,9 +132,8 @@ export function importOpenApiDocument(input: OpenApiImportInput): OpenApiImportR
     diagnostics,
   );
   const endpoints = normalizeOpenApiEndpoints(input, baseUrl, diagnostics);
-  const hasErrors = diagnostics.some((diagnostic) => diagnostic.severity === 'error');
 
-  if (hasErrors) {
+  if (baseUrl === undefined || diagnostics.some((diagnostic) => diagnostic.severity === 'error')) {
     return { ok: false, diagnostics };
   }
 
@@ -142,14 +141,16 @@ export function importOpenApiDocument(input: OpenApiImportInput): OpenApiImportR
     ok: true,
     data: {
       id: input.id,
-      kind: 'openapi',
+      kind: 'api',
+      origin: 'external',
+      protocol: 'rest',
       name: input.name ?? input.document.info?.title,
       description: input.description ?? input.document.info?.description,
       baseUrl,
       credential: input.credential,
       endpoints,
       schemas,
-      import: {
+      openApi: {
         url: input.documentUrl,
         documentId: input.documentId,
         version: input.document.info?.version,
@@ -171,7 +172,6 @@ export function normalizeOpenApiOperationId(
     .replace(/[^A-Za-z0-9]+/g, '-')
     .replace(/^-+|-+$/g, '')
     .toLowerCase();
-
   return normalized.length > 0 ? normalized : `${method}-root`;
 }
 
@@ -181,13 +181,10 @@ export function normalizeOpenApiEndpointId(path: string): EndpointId {
     .replace(/[^A-Za-z0-9]+/g, '-')
     .replace(/^-+|-+$/g, '')
     .toLowerCase();
-
   return normalized.length > 0 ? normalized : 'root';
 }
 
 export function normalizeOpenApiSchema(schema: OpenApiSchemaObject): DataSchema {
-  const additionalProperties = normalizeAdditionalProperties(schema.additionalProperties);
-
   return {
     ref: normalizeOpenApiSchemaRef(schema.$ref),
     type: normalizeSchemaType(schema.type),
@@ -200,7 +197,7 @@ export function normalizeOpenApiSchema(schema: OpenApiSchemaObject): DataSchema
     nullable: schema.nullable,
     required: schema.required,
     properties: normalizeSchemaRecord(schema.properties),
-    additionalProperties,
+    additionalProperties: normalizeAdditionalProperties(schema.additionalProperties),
     items: schema.items === undefined ? undefined : normalizeOpenApiSchema(schema.items),
     allOf: normalizeSchemaList(schema.allOf),
     anyOf: normalizeSchemaList(schema.anyOf),
@@ -212,18 +209,16 @@ function resolveOpenApiBaseUrl(
   input: OpenApiImportInput,
   diagnostics: DataSourceDiagnostic[],
 ): string | undefined {
-  if (input.baseUrl !== undefined) return input.baseUrl;
+  if (input.baseUrl !== undefined && input.baseUrl.trim().length > 0) return input.baseUrl;
 
   const servers = input.document.servers ?? [];
-
   if (servers.length === 0) {
     diagnostics.push({
       code: 'ambiguous-server',
       dataSourceId: input.id,
-      message:
-        'OpenAPI document does not define a server URL and no baseUrl override was provided.',
+      message: 'OpenAPI import requires a server URL or an explicit baseUrl override.',
       path: 'servers',
-      severity: 'warning',
+      severity: 'error',
     });
     return undefined;
   }
@@ -247,7 +242,6 @@ function normalizeOpenApiSchemas(
   diagnostics: DataSourceDiagnostic[],
 ): DataSchemaRegistry | undefined {
   if (schemas === undefined) return undefined;
-
   const registry: Record<string, DataSchema> = {};
 
   for (const [schemaId, schema] of Object.entries(schemas)) {
@@ -259,7 +253,6 @@ function normalizeOpenApiSchemas(
       diagnostics,
     );
   }
-
   return registry;
 }
 
@@ -269,7 +262,6 @@ function normalizeOpenApiEndpoints(
   diagnostics: DataSourceDiagnostic[],
 ): Record<EndpointId, DataEndpointConfig> {
   const { paths } = input.document;
-
   if (paths === undefined || Object.keys(paths).length === 0) {
     diagnostics.push({
       code: 'invalid-config',
@@ -308,8 +300,6 @@ function normalizeOpenApiEndpoints(
         operationId,
         diagnostics,
       );
-      const request = normalizeOpenApiRequest(operation.requestBody, parameters);
-      const response = normalizeOpenApiResponse(operation.responses);
 
       operations[operationId] = {
         id: operationId,
@@ -320,8 +310,8 @@ function normalizeOpenApiEndpoints(
         intent: mapOpenApiMethodToIntent(method),
         method: method.toUpperCase(),
         path,
-        request,
-        response,
+        request: normalizeOpenApiRequest(operation.requestBody, parameters),
+        response: normalizeOpenApiResponse(operation.responses),
         metadata: {
           deprecated: operation.deprecated ?? false,
           source: 'openapi',
@@ -352,7 +342,6 @@ function resolveUniqueOperationId(
   diagnostics: DataSourceDiagnostic[],
 ): OperationId {
   const normalized = normalizeOpenApiOperationId(method, path, operationId);
-
   if (!operationIds.has(normalized)) {
     operationIds.add(normalized);
     return normalized;
@@ -360,7 +349,6 @@ function resolveUniqueOperationId(
 
   let suffix = 2;
   let uniqueId: OperationId = `${normalized}-${suffix}`;
-
   while (operationIds.has(uniqueId)) {
     suffix += 1;
     uniqueId = `${normalized}-${suffix}`;
@@ -376,7 +364,6 @@ function resolveUniqueOperationId(
     path: `paths.${path}.${method}.operationId`,
     severity: 'warning',
   });
-
   return uniqueId;
 }
 
@@ -388,12 +375,10 @@ function normalizeOpenApiParameters(
   diagnostics: DataSourceDiagnostic[],
 ): readonly DataOperationParameter[] | undefined {
   if (parameters.length === 0) return undefined;
-
   const normalized: DataOperationParameter[] = [];
 
   for (const parameter of parameters) {
     const location = normalizeParameterLocation(parameter.in);
-
     if (location === undefined) {
       diagnostics.push({
         code: 'invalid-config',
@@ -428,7 +413,6 @@ function normalizeParameterLocation(location: string): DataOperationParameterLoc
   ) {
     return location;
   }
-
   return undefined;
 }
 
@@ -437,9 +421,7 @@ function normalizeOpenApiRequest(
   parameters: readonly DataOperationParameter[] | undefined,
 ): DataOperationRequest | undefined {
   const content = firstContentEntry(requestBody?.content);
-
   if (requestBody === undefined && parameters === undefined) return undefined;
-
   return {
     contentType: content?.contentType,
     parameters,
@@ -451,13 +433,11 @@ function normalizeOpenApiResponse(
   responses: Readonly<Record<string, OpenApiResponseObject>> | undefined,
 ): DataOperationResponse | undefined {
   if (responses === undefined) return undefined;
-
   const status = chooseResponseStatus(Object.keys(responses));
   if (status === undefined) return undefined;
 
   const response = responses[status];
   const content = firstContentEntry(response?.content);
-
   return {
     status,
     contentType: content?.contentType,
@@ -470,10 +450,8 @@ function firstContentEntry(
   content: Readonly<Record<string, OpenApiMediaTypeObject>> | undefined,
 ): { readonly contentType: string; readonly schema?: OpenApiSchemaObject } | undefined {
   if (content === undefined) return undefined;
-
   const [entry] = Object.entries(content);
   if (entry === undefined) return undefined;
-
   const [contentType, media] = entry;
   return { contentType, schema: media.schema };
 }
@@ -492,52 +470,37 @@ function mapOpenApiMethodToIntent(method: OpenApiHttpMethod): DataOperationInten
 
 function normalizeOpenApiSchemaRef(ref: string | undefined): { readonly id: string } | undefined {
   if (ref === undefined) return undefined;
-
   const prefix = '#/components/schemas/';
-  if (ref.startsWith(prefix)) return { id: ref.slice(prefix.length) };
-
-  return { id: ref };
+  return { id: ref.startsWith(prefix) ? ref.slice(prefix.length) : ref };
 }
 
 function normalizeSchemaRecord(
   record: Readonly<Record<string, OpenApiSchemaObject>> | undefined,
 ): Readonly<Record<string, DataSchema>> | undefined {
   if (record === undefined) return undefined;
-
-  const normalized: Record<string, DataSchema> = {};
-
-  for (const [key, schema] of Object.entries(record)) {
-    normalized[key] = normalizeOpenApiSchema(schema);
-  }
-
-  return normalized;
+  return Object.fromEntries(
+    Object.entries(record).map(([key, schema]) => [key, normalizeOpenApiSchema(schema)]),
+  );
 }
 
 function normalizeSchemaList(
   list: readonly OpenApiSchemaObject[] | undefined,
 ): readonly DataSchema[] | undefined {
-  return list?.map((schema) => normalizeOpenApiSchema(schema));
+  return list?.map(normalizeOpenApiSchema);
 }
 
 function normalizeAdditionalProperties(
-  additionalProperties: boolean | OpenApiSchemaObject | undefined,
+  value: boolean | OpenApiSchemaObject | undefined,
 ): boolean | DataSchema | undefined {
-  if (additionalProperties === undefined || typeof additionalProperties === 'boolean') {
-    return additionalProperties;
-  }
-
-  return normalizeOpenApiSchema(additionalProperties);
+  if (value === undefined || typeof value === 'boolean') return value;
+  return normalizeOpenApiSchema(value);
 }
 
 function normalizeSchemaType(
   type: string | readonly string[] | undefined,
 ): DataSchemaPrimitiveType | readonly DataSchemaPrimitiveType[] | undefined {
   if (type === undefined) return undefined;
-
-  if (typeof type === 'string') {
-    return isDataSchemaPrimitive(type) ? type : undefined;
-  }
-
+  if (typeof type === 'string') return isDataSchemaPrimitive(type) ? type : undefined;
   return type.filter(isDataSchemaPrimitive);
 }
 
@@ -569,7 +532,6 @@ function collectUnsupportedSchemaDiagnostics(
       diagnostics,
     );
   }
-
   if (schema.items !== undefined) {
     collectUnsupportedSchemaDiagnostics(schema.items, dataSourceId, `${path}.items`, diagnostics);
   }