@ankhorage/data-sources 0.6.0 → 1.0.1

package/src/graphql/index.test.ts

@@ -9,11 +9,7 @@ import {
   normalizeGraphQlOperationId,
 } from './index';
 
-function assertSerializable<TValue>(value: TValue): void {
-  expect(JSON.parse(JSON.stringify(value))).toEqual(value);
-}
-
-function createIntrospection(): GraphQlIntrospectionResult {
+function introspection(): GraphQlIntrospectionResult {
   return {
     __schema: {
       queryType: { name: 'Query' },
@@ -25,36 +21,15 @@ function createIntrospection(): GraphQlIntrospectionResult {
           fields: [
             {
               name: 'posts',
-              description: 'List posts.',
-              args: [
-                {
-                  name: 'limit',
-                  type: { kind: 'SCALAR', name: 'Int' },
-                  defaultValue: '20',
-                },
-              ],
-              type: {
-                kind: 'LIST',
-                ofType: { kind: 'OBJECT', name: 'Post' },
-              },
+              args: [],
+              type: { kind: 'LIST', ofType: { kind: 'OBJECT', name: 'Post' } },
             },
           ],
         },
         {
           kind: 'OBJECT',
           name: 'Mutation',
-          fields: [
-            {
-              name: 'createPost',
-              args: [
-                {
-                  name: 'title',
-                  type: { kind: 'NON_NULL', ofType: { kind: 'SCALAR', name: 'String' } },
-                },
-              ],
-              type: { kind: 'OBJECT', name: 'Post' },
-            },
-          ],
+          fields: [{ name: 'createPost', args: [], type: { kind: 'OBJECT', name: 'Post' } }],
         },
         {
           kind: 'OBJECT',
@@ -64,10 +39,6 @@ function createIntrospection(): GraphQlIntrospectionResult {
               name: 'id',
               type: { kind: 'NON_NULL', ofType: { kind: 'SCALAR', name: 'ID' } },
             },
-            {
-              name: 'title',
-              type: { kind: 'SCALAR', name: 'String' },
-            },
           ],
         },
       ],
@@ -75,128 +46,51 @@ function createIntrospection(): GraphQlIntrospectionResult {
   };
 }
 
-describe('GraphQL introspection normalization', () => {
-  it('creates the standard introspection request', () => {
-    const request = createGraphQlIntrospectionRequest();
-
-    expect(request.operationName).toBe('AnkhorageGraphQlIntrospection');
-    expect(request.query).toContain('__schema');
-  });
-
-  it('normalizes operation ids', () => {
+describe('GraphQL normalization', () => {
+  it('creates the standard introspection request and stable IDs', () => {
+    expect(createGraphQlIntrospectionRequest().query).toContain('__schema');
     expect(normalizeGraphQlOperationId('query', 'Posts')).toBe('query.posts');
-    expect(normalizeGraphQlOperationId('mutation', 'Create Post')).toBe('mutation.create-post');
   });
 
-  it('normalizes schemas from introspection results', () => {
-    const schemas = normalizeGraphQlIntrospectionSchemas(createIntrospection());
-
-    assertSerializable(schemas);
-    expect(schemas?.Post?.properties?.id?.type).toBe('string');
-    expect(schemas?.Post?.required).toContain('id');
-  });
-
-  it('normalizes query and mutation operations from introspection results', () => {
-    const operations = normalizeGraphQlIntrospectionOperations(createIntrospection());
-
-    assertSerializable(operations);
-    expect(operations.map((operation) => operation.id)).toEqual([
-      'query.posts',
-      'mutation.createpost',
-    ]);
-    expect(operations[0]?.variables?.properties?.limit?.type).toBe('integer');
-    expect(operations[1]?.variables?.required).toContain('title');
+  it('normalizes introspection schemas and operations', () => {
+    expect(normalizeGraphQlIntrospectionSchemas(introspection())?.Post?.required).toContain('id');
+    expect(normalizeGraphQlIntrospectionOperations(introspection()).map((item) => item.id)).toEqual(
+      ['query.posts', 'mutation.createpost'],
+    );
   });
 
-  it('creates a serializable GraphQL data source from introspection', () => {
+  it('creates an external GraphQL API source', () => {
     const result = createGraphQlDataSource({
-      id: 'content-graphql',
-      endpointUrl: 'https://content.example.com/graphql',
-      introspection: createIntrospection(),
-      schemaVersion: '2026-05-19',
-      credential: {
-        id: 'content-token',
-        kind: 'bearer',
-      },
+      id: 'content',
+      endpointUrl: 'https://example.com/graphql',
+      introspection: introspection(),
     });
-
     expect(result.ok).toBe(true);
     if (result.ok) {
-      assertSerializable(result.data);
-      expect(result.data.kind).toBe('graphql');
-      expect(result.data.endpointUrl).toBe('https://content.example.com/graphql');
-      expect(result.data.introspection?.enabled).toBe(true);
+      expect(result.data).toMatchObject({
+        kind: 'api',
+        origin: 'external',
+        protocol: 'graphql',
+      });
       expect(result.data.endpoints.graphql?.operations['query.posts']?.intent).toBe('read');
-      expect(result.data.endpoints.graphql?.operations['mutation.createpost']?.intent).toBe(
-        'action',
-      );
-      expect(
-        result.data.endpoints.graphql?.operations['mutation.createpost']?.request?.schema?.required,
-      ).toContain('title');
     }
   });
 
-  it('creates a data source with manual GraphQL operations when introspection is unavailable', () => {
-    const result = createGraphQlDataSource({
-      id: 'manual-graphql',
-      endpointUrl: 'https://manual.example.com/graphql',
+  it('supports manual operations and validates endpoint URLs', () => {
+    const manual = createGraphQlDataSource({
+      id: 'manual',
+      endpointUrl: 'https://example.com/graphql',
       introspectionEnabled: false,
       operations: [
         {
           id: 'query.viewer',
           kind: 'query',
-          name: 'viewer',
           document: 'query Viewer { viewer { id } }',
-          variables: { type: 'object' },
-          response: {
-            type: 'object',
-            properties: {
-              viewer: { type: 'object' },
-            },
-          },
-          selectionPath: '$.data.viewer',
         },
       ],
     });
-
-    expect(result.ok).toBe(true);
-    if (result.ok) {
-      const metadata = result.data.endpoints.graphql?.operations['query.viewer']?.metadata;
-
-      expect(metadata).toBeDefined();
-      if (metadata !== undefined && typeof metadata === 'object' && !Array.isArray(metadata)) {
-        expect(metadata.selectionPath).toBe('$.data.viewer');
-      }
-      expect(result.diagnostics).toEqual([]);
-    }
-  });
-
-  it('reports invalid endpoint URLs and disabled-introspection mismatches', () => {
-    const result = createGraphQlDataSource({
-      id: 'broken-graphql',
-      endpointUrl: ' ',
-      introspectionEnabled: false,
-      introspection: createIntrospection(),
-    });
-
-    expect(result.ok).toBe(false);
-    if (!result.ok) {
-      const paths = result.diagnostics.map((diagnostic) => diagnostic.path);
-
-      expect(paths).toContain('endpointUrl');
-      expect(paths).toContain('introspection');
-    }
-  });
-
-  it('reports missing introspection as info for manual operation workflows', () => {
-    const result = createGraphQlDataSource({
-      id: 'manual-graphql',
-      endpointUrl: 'https://manual.example.com/graphql',
-    });
-
-    expect(result.ok).toBe(true);
-    if (result.ok) {
-      expect(result.diagnostics?.map((diagnostic) => diagnostic.code)).toContain('missing-schema');
-    }
+    const invalid = createGraphQlDataSource({ id: 'broken', endpointUrl: ' ' });
+    expect(manual.ok).toBe(true);
+    expect(invalid.ok).toBe(false);
   });
 });

package/src/graphql/index.ts

@@ -9,7 +9,7 @@ import type {
   DataSchemaRegistry,
   DataSourceDiagnostic,
   DataSourceDiagnosticResult,
-  GraphQlDataSourceConfig,
+  ExternalGraphQlApiDataSourceConfig,
   OperationId,
 } from '@ankhorage/contracts/data';
 
@@ -46,7 +46,6 @@ export const GRAPHQL_INTROSPECTION_QUERY = `query AnkhorageGraphQlIntrospection
 }`;
 
 export type GraphQlOperationKind = 'mutation' | 'query' | 'subscription';
-
 type DataContractRecord = Record<string, DataContractValue>;
 
 export interface GraphQlIntrospectionTypeRef {
@@ -137,17 +136,16 @@ export function normalizeGraphQlOperationId(kind: GraphQlOperationKind, name: st
     .replace(/[^A-Za-z0-9]+/g, '-')
     .replace(/^-+|-+$/g, '')
     .toLowerCase();
-
   return normalizedName.length > 0 ? `${kind}.${normalizedName}` : `${kind}.operation`;
 }
 
 export function createGraphQlDataSource(
   definition: GraphQlDataSourceDefinition,
-): DataSourceDiagnosticResult<GraphQlDataSourceConfig> {
+): DataSourceDiagnosticResult<ExternalGraphQlApiDataSourceConfig> {
   const diagnostics = validateGraphQlDataSource(definition);
-  const hasErrors = diagnostics.some((diagnostic) => diagnostic.severity === 'error');
-
-  if (hasErrors) return { ok: false, diagnostics };
+  if (diagnostics.some((diagnostic) => diagnostic.severity === 'error')) {
+    return { ok: false, diagnostics };
+  }
 
   return {
     ok: true,
@@ -197,13 +195,12 @@ export function validateGraphQlDataSource(
 
 export function normalizeGraphQlDataSource(
   definition: GraphQlDataSourceDefinition,
-): GraphQlDataSourceConfig {
+): ExternalGraphQlApiDataSourceConfig {
   const schemas = normalizeGraphQlIntrospectionSchemas(definition.introspection);
-  const introspectionOperations = normalizeGraphQlIntrospectionOperations(definition.introspection);
-  const manualOperations = definition.operations ?? [];
+  const discovered = normalizeGraphQlIntrospectionOperations(definition.introspection);
   const operations: Record<OperationId, DataOperationConfig> = {};
 
-  for (const operation of [...introspectionOperations, ...manualOperations]) {
+  for (const operation of [...discovered, ...(definition.operations ?? [])]) {
     operations[operation.id] = normalizeGraphQlOperation(operation);
   }
 
@@ -213,21 +210,19 @@ export function normalizeGraphQlDataSource(
     baseUrl: definition.endpointUrl,
     credential: definition.credential,
     operations,
-    metadata: {
-      source: 'graphql',
-    },
+    metadata: { source: 'graphql' },
   };
 
   return {
     id: definition.id,
-    kind: 'graphql',
+    kind: 'api',
+    origin: 'external',
+    protocol: 'graphql',
     name: definition.name,
     description: definition.description,
     endpointUrl: definition.endpointUrl,
     credential: definition.credential,
-    endpoints: {
-      graphql: endpoint,
-    },
+    endpoints: { graphql: endpoint },
     schemas,
     introspection: {
       enabled: definition.introspectionEnabled ?? definition.introspection !== undefined,
@@ -244,12 +239,10 @@ export function normalizeGraphQlIntrospectionSchemas(
   if (types.length === 0) return undefined;
 
   const schemas: Record<string, DataSchema> = {};
-
   for (const type of types) {
     if (type.name === undefined || type.name === null || type.name.startsWith('__')) continue;
     schemas[type.name] = normalizeGraphQlType(type);
   }
-
   return schemas;
 }
 
@@ -261,11 +254,9 @@ export function normalizeGraphQlIntrospectionOperations(
 
   const types = schema.types?.filter(isNamedGraphQlType) ?? [];
   const operations: GraphQlOperationDefinition[] = [];
-
   appendRootOperations(operations, 'query', schema.queryType?.name, types);
   appendRootOperations(operations, 'mutation', schema.mutationType?.name, types);
   appendRootOperations(operations, 'subscription', schema.subscriptionType?.name, types);
-
   return operations;
 }
 
@@ -276,8 +267,8 @@ function appendRootOperations(
   types: readonly GraphQlIntrospectionType[],
 ): void {
   if (rootTypeName === undefined || rootTypeName === null) return;
-
   const rootType = types.find((type) => type.name === rootTypeName);
+
   for (const field of rootType?.fields ?? []) {
     operations.push({
       id: normalizeGraphQlOperationId(kind, field.name),
@@ -287,21 +278,14 @@ function appendRootOperations(
       variables: normalizeGraphQlVariablesSchema(field.args ?? []),
       response: normalizeGraphQlTypeRef(field.type),
       selectionPath: `$.data.${field.name}`,
-      metadata: {
-        rootType: rootTypeName,
-        source: 'introspection',
-      },
+      metadata: { rootType: rootTypeName, source: 'introspection' },
     });
   }
 }
 
 function normalizeGraphQlOperation(operation: GraphQlOperationDefinition): DataOperationConfig {
   const response: DataOperationResponse | undefined =
-    operation.response === undefined
-      ? undefined
-      : {
-          schema: operation.response,
-        };
+    operation.response === undefined ? undefined : { schema: operation.response };
 
   return {
     id: operation.id,
@@ -310,17 +294,14 @@ function normalizeGraphQlOperation(operation: GraphQlOperationDefinition): DataO
     description: operation.description,
     protocol: 'graphql',
     intent: mapGraphQlOperationKindToIntent(operation.kind),
-    request: {
-      schema: operation.variables,
-    },
+    request: { schema: operation.variables },
     response,
     metadata: createGraphQlOperationMetadata(operation),
   };
 }
 
 function mapGraphQlOperationKindToIntent(kind: GraphQlOperationKind): DataOperationIntent {
-  if (kind === 'query' || kind === 'subscription') return 'read';
-  return 'action';
+  return kind === 'query' || kind === 'subscription' ? 'read' : 'action';
 }
 
 function normalizeGraphQlVariablesSchema(
@@ -349,7 +330,6 @@ function normalizeGraphQlType(type: GraphQlIntrospectionType): DataSchema {
   if (type.kind === 'OBJECT' || type.kind === 'INTERFACE' || type.kind === 'INPUT_OBJECT') {
     return normalizeGraphQlObjectType(type);
   }
-
   if (type.kind === 'ENUM') {
     return {
       type: 'string',
@@ -358,7 +338,6 @@ function normalizeGraphQlType(type: GraphQlIntrospectionType): DataSchema {
       enum: type.enumValues?.map((value) => value.name),
     };
   }
-
   if (type.kind === 'SCALAR') {
     return {
       ...normalizeGraphQlNamedScalar(type.name),
@@ -366,19 +345,14 @@ function normalizeGraphQlType(type: GraphQlIntrospectionType): DataSchema {
       description: type.description ?? undefined,
     };
   }
-
   if (type.kind === 'UNION') {
     return {
       title: type.name ?? undefined,
       description: type.description ?? undefined,
-      anyOf: type.possibleTypes?.map((possibleType) => normalizeGraphQlTypeRef(possibleType)),
+      anyOf: type.possibleTypes?.map(normalizeGraphQlTypeRef),
     };
   }
-
-  return {
-    title: type.name ?? undefined,
-    description: type.description ?? undefined,
-  };
+  return { title: type.name ?? undefined, description: type.description ?? undefined };
 }
 
 function normalizeGraphQlObjectType(type: GraphQlIntrospectionType): DataSchema {
@@ -387,14 +361,11 @@ function normalizeGraphQlObjectType(type: GraphQlIntrospectionType): DataSchema
   const required: string[] = [];
 
   for (const field of fields ?? []) {
-    const fieldType = 'type' in field ? field.type : undefined;
-    if (fieldType === undefined) continue;
-
+    const fieldType = field.type;
     properties[field.name] = {
       ...normalizeGraphQlTypeRef(fieldType),
       description: field.description ?? undefined,
     };
-
     if (isGraphQlNonNull(fieldType)) required.push(field.name);
   }
 
@@ -409,27 +380,13 @@ function normalizeGraphQlObjectType(type: GraphQlIntrospectionType): DataSchema
 
 function normalizeGraphQlTypeRef(type: GraphQlIntrospectionTypeRef): DataSchema {
   if (type.kind === 'NON_NULL' && type.ofType !== undefined && type.ofType !== null) {
-    return {
-      ...normalizeGraphQlTypeRef(type.ofType),
-      nullable: false,
-    };
+    return { ...normalizeGraphQlTypeRef(type.ofType), nullable: false };
   }
-
   if (type.kind === 'LIST' && type.ofType !== undefined && type.ofType !== null) {
-    return {
-      type: 'array',
-      items: normalizeGraphQlTypeRef(type.ofType),
-    };
+    return { type: 'array', items: normalizeGraphQlTypeRef(type.ofType) };
   }
-
-  if (type.kind === 'SCALAR') {
-    return normalizeGraphQlNamedScalar(type.name);
-  }
-
-  if (type.name !== undefined && type.name !== null) {
-    return { ref: { id: type.name } };
-  }
-
+  if (type.kind === 'SCALAR') return normalizeGraphQlNamedScalar(type.name);
+  if (type.name !== undefined && type.name !== null) return { ref: { id: type.name } };
   return {};
 }
 
@@ -438,11 +395,7 @@ function normalizeGraphQlNamedScalar(name: string | null | undefined): DataSchem
   if (name === 'Float') return { type: 'number' };
   if (name === 'ID' || name === 'String') return { type: 'string' };
   if (name === 'Int') return { type: 'integer' };
-
-  return {
-    type: 'string',
-    format: name ?? undefined,
-  };
+  return { type: 'string', format: name ?? undefined };
 }
 
 function isGraphQlNonNull(type: GraphQlIntrospectionTypeRef): boolean {
@@ -456,27 +409,14 @@ function isNamedGraphQlType(type: GraphQlIntrospectionType): boolean {
 function createGraphQlOperationMetadata(operation: GraphQlOperationDefinition): DataContractRecord {
   const metadata = toMetadataRecord(operation.metadata);
   metadata.kind = operation.kind;
-
-  if (operation.document !== undefined) {
-    metadata.document = operation.document;
-  }
-
-  if (operation.selectionPath !== undefined) {
-    metadata.selectionPath = operation.selectionPath;
-  }
-
+  if (operation.document !== undefined) metadata.document = operation.document;
+  if (operation.selectionPath !== undefined) metadata.selectionPath = operation.selectionPath;
   return metadata;
 }
 
 function toMetadataRecord(value: DataContractValue | undefined): DataContractRecord {
   if (!isDataContractRecord(value)) return {};
-
-  const metadata: DataContractRecord = {};
-  for (const [key, item] of Object.entries(value)) {
-    metadata[key] = item;
-  }
-
-  return metadata;
+  return { ...value };
 }
 
 function isDataContractRecord(value: DataContractValue | undefined): value is DataContractRecord {

package/src/index.test.ts

@@ -1,39 +1,46 @@
-import type { RestDataSourceConfig } from '@ankhorage/contracts/data';
+import type { ExternalRestApiDataSourceConfig } from '@ankhorage/contracts/data';
 import { describe, expect, it } from 'bun:test';
 
 import {
   DATA_SOURCES_PACKAGE_NAME,
   getDataSourceKind,
   getDataSourcesPackageInfo,
+  isSupportedApiOrigin,
+  isSupportedApiProtocol,
   isSupportedDataSourceKind,
-  SUPPORTED_DATA_SOURCE_KINDS,
 } from './index';
 
-describe('data-sources package baseline', () => {
-  it('exports package metadata', () => {
-    const info = getDataSourcesPackageInfo();
-
-    expect(info.packageName).toBe(DATA_SOURCES_PACKAGE_NAME);
-    expect(info.supportedKinds).toEqual(SUPPORTED_DATA_SOURCE_KINDS);
+describe('data-sources package model', () => {
+  it('exports orthogonal package capabilities', () => {
+    expect(getDataSourcesPackageInfo()).toEqual({
+      packageName: DATA_SOURCES_PACKAGE_NAME,
+      supportedKinds: ['api', 'database'],
+      supportedApiOrigins: ['external', 'generated'],
+      supportedApiProtocols: ['graphql', 'rest'],
+    });
   });
 
-  it('recognizes supported shared contract data-source kinds', () => {
-    expect(isSupportedDataSourceKind('rest')).toBe(true);
-    expect(isSupportedDataSourceKind('openapi')).toBe(true);
-    expect(isSupportedDataSourceKind('graphql')).toBe(true);
-    expect(isSupportedDataSourceKind('managed-api')).toBe(true);
+  it('recognizes only canonical source dimensions', () => {
+    expect(isSupportedDataSourceKind('api')).toBe(true);
     expect(isSupportedDataSourceKind('database')).toBe(true);
-    expect(isSupportedDataSourceKind('studio')).toBe(false);
+    expect(isSupportedDataSourceKind('managed-api')).toBe(false);
+    expect(isSupportedDataSourceKind('openapi')).toBe(false);
+    expect(isSupportedApiOrigin('external')).toBe(true);
+    expect(isSupportedApiOrigin('generated')).toBe(true);
+    expect(isSupportedApiProtocol('rest')).toBe(true);
+    expect(isSupportedApiProtocol('graphql')).toBe(true);
   });
 
-  it('consumes data-source contracts from @ankhorage/contracts', () => {
-    const source: RestDataSourceConfig = {
+  it('consumes canonical contracts from @ankhorage/contracts', () => {
+    const source: ExternalRestApiDataSourceConfig = {
       id: 'cms',
-      kind: 'rest',
+      kind: 'api',
+      origin: 'external',
+      protocol: 'rest',
       baseUrl: 'https://cms.example.com',
       endpoints: {},
     };
 
-    expect(getDataSourceKind(source)).toBe('rest');
+    expect(getDataSourceKind(source)).toBe('api');
   });
 });

package/src/index.ts

@@ -1,36 +1,57 @@
-import type { DataSourceConfig, DataSourceKind } from '@ankhorage/contracts/data';
+import type {
+  ApiOrigin,
+  ApiProtocol,
+  DataSourceConfig,
+  DataSourceKind,
+} from '@ankhorage/contracts/data';
 
 export * from './discovery';
+export * from './generated-api';
 export * from './graphql';
-export * from './managed-api';
 export * from './openapi';
 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',
-  'managed-api',
-  'openapi',
   'rest',
-] as const satisfies readonly DataSourceKind[];
+] 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((supportedKind) => supportedKind === kind);
+  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 {