@ankhorage/data-sources 1.0.1 → 2.0.1

package/src/graphql/types.ts

@@ -0,0 +1,79 @@
+import type {
+  CredentialRef,
+  DataContractValue,
+  DataSchema,
+  OperationId,
+} from '@ankhorage/contracts/data';
+
+export type GraphQlOperationKind = 'mutation' | 'query' | 'subscription';
+
+export interface GraphQlIntrospectionTypeRef {
+  readonly kind: string;
+  readonly name?: string | null;
+  readonly ofType?: GraphQlIntrospectionTypeRef | null;
+}
+
+export interface GraphQlIntrospectionInputValue {
+  readonly name: string;
+  readonly description?: string | null;
+  readonly type: GraphQlIntrospectionTypeRef;
+  readonly defaultValue?: string | null;
+}
+
+export interface GraphQlIntrospectionField {
+  readonly name: string;
+  readonly description?: string | null;
+  readonly args?: readonly GraphQlIntrospectionInputValue[] | null;
+  readonly type: GraphQlIntrospectionTypeRef;
+}
+
+export interface GraphQlIntrospectionEnumValue {
+  readonly name: string;
+  readonly description?: string | null;
+}
+
+export interface GraphQlIntrospectionType {
+  readonly kind: string;
+  readonly name?: string | null;
+  readonly description?: string | null;
+  readonly fields?: readonly GraphQlIntrospectionField[] | null;
+  readonly inputFields?: readonly GraphQlIntrospectionInputValue[] | null;
+  readonly enumValues?: readonly GraphQlIntrospectionEnumValue[] | null;
+  readonly possibleTypes?: readonly GraphQlIntrospectionTypeRef[] | null;
+}
+
+export interface GraphQlIntrospectionSchema {
+  readonly queryType?: { readonly name?: string | null } | null;
+  readonly mutationType?: { readonly name?: string | null } | null;
+  readonly subscriptionType?: { readonly name?: string | null } | null;
+  readonly types?: readonly GraphQlIntrospectionType[] | null;
+}
+
+export interface GraphQlIntrospectionResult {
+  readonly __schema?: GraphQlIntrospectionSchema;
+}
+
+export interface GraphQlOperationDefinition {
+  readonly id: OperationId;
+  readonly kind: GraphQlOperationKind;
+  readonly name?: string;
+  readonly description?: string;
+  readonly document?: string;
+  readonly variables?: DataSchema;
+  readonly response?: DataSchema;
+  readonly selectionPath?: string;
+  readonly metadata?: DataContractValue;
+}
+
+export interface GraphQlApiDefinition {
+  readonly id: string;
+  readonly endpointUrl: string;
+  readonly name?: string;
+  readonly description?: string;
+  readonly credential?: CredentialRef;
+  readonly introspection?: GraphQlIntrospectionResult;
+  readonly introspectionEnabled?: boolean;
+  readonly schemaVersion?: string;
+  readonly operations?: readonly GraphQlOperationDefinition[];
+  readonly metadata?: DataContractValue;
+}

package/src/index.test.ts

@@ -1,4 +1,7 @@
-import type { ExternalRestApiDataSourceConfig } from '@ankhorage/contracts/data';
+import type {
+  DatabaseDataSourceConfig,
+  ExternalRestApiDefinition,
+} from '@ankhorage/contracts/data';
 import { describe, expect, it } from 'bun:test';
 
 import {
@@ -11,36 +14,41 @@ import {
 } from './index';
 
 describe('data-sources package model', () => {
-  it('exports orthogonal package capabilities', () => {
+  it('exports canonical API and database capabilities separately', () => {
     expect(getDataSourcesPackageInfo()).toEqual({
       packageName: DATA_SOURCES_PACKAGE_NAME,
-      supportedKinds: ['api', 'database'],
-      supportedApiOrigins: ['external', 'generated'],
+      supportedKinds: ['database'],
+      supportedApiOrigins: ['external'],
       supportedApiProtocols: ['graphql', 'rest'],
     });
   });
 
-  it('recognizes only canonical source dimensions', () => {
-    expect(isSupportedDataSourceKind('api')).toBe(true);
+  it('recognizes only currently executable API origins', () => {
     expect(isSupportedDataSourceKind('database')).toBe(true);
-    expect(isSupportedDataSourceKind('managed-api')).toBe(false);
-    expect(isSupportedDataSourceKind('openapi')).toBe(false);
+    expect(isSupportedDataSourceKind('api')).toBe(false);
     expect(isSupportedApiOrigin('external')).toBe(true);
-    expect(isSupportedApiOrigin('generated')).toBe(true);
+    expect(isSupportedApiOrigin('internal')).toBe(false);
+    expect(isSupportedApiOrigin('generated')).toBe(false);
     expect(isSupportedApiProtocol('rest')).toBe(true);
     expect(isSupportedApiProtocol('graphql')).toBe(true);
   });
 
-  it('consumes canonical contracts from @ankhorage/contracts', () => {
-    const source: ExternalRestApiDataSourceConfig = {
+  it('consumes canonical API contracts from @ankhorage/contracts', () => {
+    const api: ExternalRestApiDefinition = {
       id: 'cms',
-      kind: 'api',
       origin: 'external',
       protocol: 'rest',
       baseUrl: 'https://cms.example.com',
       endpoints: {},
     };
+    const source: DatabaseDataSourceConfig = {
+      id: 'primary-db',
+      kind: 'database',
+      adapter: { id: 'database-adapter', kind: 'database' },
+      endpoints: {},
+    };
 
-    expect(getDataSourceKind(source)).toBe('api');
+    expect(api.origin).toBe('external');
+    expect(getDataSourceKind(source)).toBe('database');
   });
 });

package/src/index.ts

@@ -1,59 +1,6 @@
-import type {
-  ApiOrigin,
-  ApiProtocol,
-  DataSourceConfig,
-  DataSourceKind,
-} from '@ankhorage/contracts/data';
-
 export * from './discovery';
-export * from './generated-api';
 export * from './graphql';
 export * from './openapi';
+export * from './packageInfo';
 export * from './rest';
 export * from './test-runner';
-
-export const DATA_SOURCES_PACKAGE_NAME = '@ankhorage/data-sources' as const;
-export const SUPPORTED_DATA_SOURCE_KINDS = [
-  'api',
-  'database',
-] as const satisfies readonly DataSourceKind[];
-export const SUPPORTED_API_ORIGINS = [
-  'external',
-  'generated',
-] as const satisfies readonly ApiOrigin[];
-export const SUPPORTED_API_PROTOCOLS = [
-  'graphql',
-  'rest',
-] as const satisfies readonly ApiProtocol[];
-
-export interface DataSourcesPackageInfo {
-  readonly packageName: typeof DATA_SOURCES_PACKAGE_NAME;
-  readonly supportedKinds: typeof SUPPORTED_DATA_SOURCE_KINDS;
-  readonly supportedApiOrigins: typeof SUPPORTED_API_ORIGINS;
-  readonly supportedApiProtocols: typeof SUPPORTED_API_PROTOCOLS;
-}
-
-export function getDataSourcesPackageInfo(): DataSourcesPackageInfo {
-  return {
-    packageName: DATA_SOURCES_PACKAGE_NAME,
-    supportedKinds: SUPPORTED_DATA_SOURCE_KINDS,
-    supportedApiOrigins: SUPPORTED_API_ORIGINS,
-    supportedApiProtocols: SUPPORTED_API_PROTOCOLS,
-  };
-}
-
-export function isSupportedDataSourceKind(kind: string): kind is DataSourceKind {
-  return SUPPORTED_DATA_SOURCE_KINDS.some((supported) => supported === kind);
-}
-
-export function isSupportedApiOrigin(origin: string): origin is ApiOrigin {
-  return SUPPORTED_API_ORIGINS.some((supported) => supported === origin);
-}
-
-export function isSupportedApiProtocol(protocol: string): protocol is ApiProtocol {
-  return SUPPORTED_API_PROTOCOLS.some((supported) => supported === protocol);
-}
-
-export function getDataSourceKind(source: DataSourceConfig): DataSourceKind {
-  return source.kind;
-}

package/src/openapi/endpoints.ts

@@ -0,0 +1,124 @@
+import type {
+  DataEndpointConfig,
+  DataSourceDiagnostic,
+  EndpointId,
+  OperationId,
+} from '@ankhorage/contracts/data';
+
+import { normalizeOpenApiOperation } from './operation';
+import type {
+  OpenApiHttpMethod,
+  OpenApiImportInput,
+  OpenApiOperationObject,
+  OpenApiPathItemObject,
+} from './types';
+
+const OPENAPI_HTTP_METHODS = [
+  'delete',
+  'get',
+  'head',
+  'options',
+  'patch',
+  'post',
+  'put',
+] as const satisfies readonly OpenApiHttpMethod[];
+
+export function normalizeOpenApiEndpointId(path: string): EndpointId {
+  const normalized = path
+    .replace(/\{([^}]+)\}/g, '$1')
+    .replace(/[^A-Za-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .toLowerCase();
+  return normalized.length > 0 ? normalized : 'root';
+}
+
+export function normalizeOpenApiEndpoints(
+  input: OpenApiImportInput,
+  diagnostics: DataSourceDiagnostic[],
+): Record<EndpointId, DataEndpointConfig> {
+  const { paths } = input.document;
+  if (paths === undefined || Object.keys(paths).length === 0) {
+    diagnostics.push({
+      code: 'invalid-config',
+      apiId: input.id,
+      message: 'OpenAPI document must define at least one path.',
+      path: 'paths',
+      severity: 'error',
+    });
+    return {};
+  }
+
+  const operationIds = new Set<OperationId>();
+  return Object.fromEntries(
+    Object.entries(paths).map(([path, pathItem]) => {
+      const endpointId = normalizeOpenApiEndpointId(path);
+      return [
+        endpointId,
+        normalizeOpenApiEndpoint(input, path, pathItem, endpointId, operationIds, diagnostics),
+      ];
+    }),
+  );
+}
+
+function normalizeOpenApiEndpoint(
+  input: OpenApiImportInput,
+  path: string,
+  pathItem: OpenApiPathItemObject,
+  endpointId: EndpointId,
+  operationIds: Set<OperationId>,
+  diagnostics: DataSourceDiagnostic[],
+): DataEndpointConfig {
+  const operations = Object.fromEntries(
+    getOpenApiOperations(pathItem).map(([method, operation]) => {
+      const normalized = normalizeOpenApiOperation(
+        input,
+        endpointId,
+        path,
+        method,
+        operation,
+        pathItem,
+        operationIds,
+        diagnostics,
+      );
+      return [normalized.id, normalized];
+    }),
+  );
+  return {
+    id: endpointId,
+    kind: 'http',
+    path,
+    credential: input.credential,
+    operations,
+  };
+}
+
+function getOpenApiOperations(
+  pathItem: OpenApiPathItemObject,
+): readonly [OpenApiHttpMethod, OpenApiOperationObject][] {
+  return OPENAPI_HTTP_METHODS.flatMap((method) => {
+    const operation = getOpenApiOperation(pathItem, method);
+    return operation === undefined ? [] : [[method, operation]];
+  });
+}
+
+function getOpenApiOperation(
+  pathItem: OpenApiPathItemObject,
+  method: OpenApiHttpMethod,
+): OpenApiOperationObject | undefined {
+  switch (method) {
+    case 'delete':
+      return pathItem.delete;
+    case 'get':
+      return pathItem.get;
+    case 'head':
+      return pathItem.head;
+    case 'options':
+      return pathItem.options;
+    case 'patch':
+      return pathItem.patch;
+    case 'post':
+      return pathItem.post;
+    case 'put':
+      return pathItem.put;
+  }
+}

package/src/openapi/index.test.ts

@@ -1,4 +1,4 @@
-import { describe, expect, it } from 'bun:test';
+import { expect, it } from 'bun:test';
 
 import {
   importOpenApiDocument,
@@ -31,56 +31,56 @@ function document(): OpenApiDocumentObject {
   };
 }
 
-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(normalizeOpenApiSchema({ type: 'array', items: { type: 'string' } }).items?.type).toBe(
-      'string',
-    );
-  });
+it('normalizes OpenAPI endpoint, operation and schema shapes', () => {
+  expect(normalizeOpenApiEndpointId('/pets/{petId}')).toBe('pets-petid');
+  expect(normalizeOpenApiOperationId('get', '/pets/{petId}')).toBe('get-pets-petid');
+  expect(normalizeOpenApiSchema({ type: 'array', items: { type: 'string' } }).items?.type).toBe(
+    'string',
+  );
+});
 
-  it('imports OpenAPI as an external REST source with OpenAPI metadata', () => {
-    const result = importOpenApiDocument({
-      id: 'pet-store',
-      document: document(),
-      documentUrl: 'https://api.example.com/openapi.json',
-    });
-    expect(result.ok).toBe(true);
-    if (result.ok) {
-      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');
-    }
+it('imports OpenAPI as a canonical external REST API', () => {
+  const result = importOpenApiDocument({
+    id: 'pet-store',
+    document: document(),
+    documentUrl: 'https://api.example.com/openapi.json',
   });
+  expect(result.ok).toBe(true);
+  if (result.ok) {
+    expect(result.data).toMatchObject({ origin: 'external', protocol: 'rest' });
+    expect('kind' in result.data).toBe(false);
+    expect(result.data.openApi?.version).toBe('2026-08-06');
+    expect(result.data.endpoints.pets?.baseUrl).toBeUndefined();
+    expect(result.data.endpoints.pets?.operations.listpets?.intent).toBe('read');
+    expect(result.data.endpoints.pets?.operations.createpet?.intent).toBe('create');
+  }
+});
 
-  it('uses an explicit base URL and reports ambiguous servers', () => {
-    const result = importOpenApiDocument({
-      id: 'pet-store',
-      document: {
-        ...document(),
-        servers: [{ url: 'https://one.example.com' }, { url: 'https://two.example.com' }],
-      },
-      baseUrl: 'https://override.example.com',
-    });
-    expect(result.ok).toBe(true);
-    if (result.ok) expect(result.data.baseUrl).toBe('https://override.example.com');
+it('uses an explicit OpenAPI base URL with ambiguous servers', () => {
+  const result = importOpenApiDocument({
+    id: 'pet-store',
+    document: {
+      ...document(),
+      servers: [{ url: 'https://one.example.com' }, { url: 'https://two.example.com' }],
+    },
+    baseUrl: 'https://override.example.com',
   });
+  expect(result.ok).toBe(true);
+  if (result.ok) expect(result.data.baseUrl).toBe('https://override.example.com');
+});
 
-  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);
+it('requires a resolvable OpenAPI base URL and paths', () => {
+  const noServer = importOpenApiDocument({
+    id: 'no-server',
+    document: { openapi: '3.1.0', paths: { '/x': { get: {} } } },
+  });
+  const noPaths = importOpenApiDocument({
+    id: 'no-paths',
+    baseUrl: 'https://example.com',
+    document: { openapi: '3.1.0' },
   });
+  expect(noServer.ok).toBe(false);
+  if (!noServer.ok) expect(noServer.diagnostics[0]?.apiId).toBe('no-server');
+  expect(noPaths.ok).toBe(false);
+  if (!noPaths.ok) expect(noPaths.diagnostics[0]?.apiId).toBe('no-paths');
 });