@ankhorage/data-sources 1.0.1 → 2.0.0

package/src/discovery/index.test.ts

@@ -1,11 +1,11 @@
-import { describe, expect, it } from 'bun:test';
+import { expect, it } from 'bun:test';
 
 import {
   createOpenApiDiscoveryCandidates,
-  discoverOpenApiDataSource,
+  discoverOpenApi,
   type ExternalApiFetch,
   type ExternalApiFetchResponse,
-  introspectGraphQlDataSource,
+  introspectGraphQlApi,
 } from './index';
 
 function jsonResponse(value: unknown, status = 200): ExternalApiFetchResponse {
@@ -50,84 +50,85 @@ function graphQlPayload() {
   } as const;
 }
 
-describe('external API discovery', () => {
-  it('creates direct and conventional candidates and rejects unsafe URLs', () => {
-    const candidates = createOpenApiDiscoveryCandidates('https://api.example.com/service');
-    expect(candidates).toContain('https://api.example.com/service');
-    expect(candidates).toContain('https://api.example.com/service/openapi.json');
-    expect(candidates).toContain('https://api.example.com/openapi.json');
-    expect(createOpenApiDiscoveryCandidates('file:///tmp/openapi.json')).toEqual([]);
-    expect(
-      createOpenApiDiscoveryCandidates('https://user:secret@example.com/openapi.json'),
-    ).toEqual([]);
-  });
+it('creates OpenAPI discovery candidates and rejects unsafe URLs', () => {
+  const candidates = createOpenApiDiscoveryCandidates('https://api.example.com/service');
+  expect(candidates).toContain('https://api.example.com/service');
+  expect(candidates).toContain('https://api.example.com/service/openapi.json');
+  expect(candidates).toContain('https://api.example.com/openapi.json');
+  expect(createOpenApiDiscoveryCandidates('file:///tmp/openapi.json')).toEqual([]);
+  expect(createOpenApiDiscoveryCandidates('https://user:secret@example.com/openapi.json')).toEqual(
+    [],
+  );
+});
 
-  it('discovers OpenAPI into an external REST source', async () => {
-    const result = await discoverOpenApiDataSource({
-      id: 'inventory',
-      url: 'https://api.example.com/openapi.json',
-      fetch: () => Promise.resolve(jsonResponse(openApiDocument())),
-    });
-    expect(result.ok).toBe(true);
-    if (result.ok) {
-      expect(result.data).toMatchObject({ kind: 'api', origin: 'external', protocol: 'rest' });
-      expect(result.data.openApi?.url).toBe('https://api.example.com/openapi.json');
-      expect(result.attempts[0]?.outcome).toBe('matched');
-    }
+it('discovers an external REST API', async () => {
+  const result = await discoverOpenApi({
+    id: 'inventory',
+    url: 'https://api.example.com/openapi.json',
+    fetch: () => Promise.resolve(jsonResponse(openApiDocument())),
   });
+  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?.url).toBe('https://api.example.com/openapi.json');
+    expect(result.attempts[0]?.outcome).toBe('matched');
+  }
+});
 
-  it('falls back to conventional locations and keeps diagnostics safe', async () => {
-    const calls: string[] = [];
-    const fetch: ExternalApiFetch = (url) => {
-      calls.push(url);
-      return Promise.resolve(
-        url.endsWith('/service/openapi.json')
-          ? jsonResponse(openApiDocument())
-          : jsonResponse({ private: 'hidden' }, 404),
-      );
-    };
-    const result = await discoverOpenApiDataSource({
-      id: 'inventory',
-      url: 'https://api.example.com/service',
-      conventionalPaths: ['openapi.json'],
-      fetch,
-    });
-    expect(result.ok).toBe(true);
-    expect(calls).toEqual([
-      'https://api.example.com/service',
-      'https://api.example.com/service/openapi.json',
-    ]);
-    expect(JSON.stringify(result)).not.toContain('hidden');
+it('falls back to OpenAPI conventional locations without leaking response data', async () => {
+  const calls: string[] = [];
+  const fetch: ExternalApiFetch = (url) => {
+    calls.push(url);
+    return Promise.resolve(
+      url.endsWith('/service/openapi.json')
+        ? jsonResponse(openApiDocument())
+        : jsonResponse({ private: 'hidden' }, 404),
+    );
+  };
+  const result = await discoverOpenApi({
+    id: 'inventory',
+    url: 'https://api.example.com/service',
+    conventionalPaths: ['openapi.json'],
+    fetch,
   });
+  expect(result.ok).toBe(true);
+  expect(calls).toEqual([
+    'https://api.example.com/service',
+    'https://api.example.com/service/openapi.json',
+  ]);
+  expect(JSON.stringify(result)).not.toContain('hidden');
+});
 
-  it('introspects GraphQL without echoing trusted headers', async () => {
-    const result = await introspectGraphQlDataSource({
-      id: 'catalog',
-      endpointUrl: 'https://api.example.com/graphql',
-      headers: { authorization: 'Bearer server-only' },
-      fetch: () => Promise.resolve(jsonResponse(graphQlPayload())),
-    });
-    expect(result.ok).toBe(true);
-    if (result.ok) {
-      expect(result.data).toMatchObject({ kind: 'api', origin: 'external', protocol: 'graphql' });
-      expect(result.data.endpoints.graphql?.operations['query.items']).toBeDefined();
-      expect(JSON.stringify(result)).not.toContain('server-only');
-    }
+it('introspects GraphQL without echoing trusted headers', async () => {
+  const result = await introspectGraphQlApi({
+    id: 'catalog',
+    endpointUrl: 'https://api.example.com/graphql',
+    headers: { authorization: 'Bearer server-only' },
+    fetch: () => Promise.resolve(jsonResponse(graphQlPayload())),
   });
+  expect(result.ok).toBe(true);
+  if (result.ok) {
+    expect(result.data).toMatchObject({ origin: 'external', protocol: 'graphql' });
+    expect('kind' in result.data).toBe(false);
+    expect(result.data.endpoints.graphql?.operations['query.items']).toBeDefined();
+    expect(JSON.stringify(result)).not.toContain('server-only');
+  }
+});
 
-  it('reports transport and response-shape failures safely', async () => {
-    const http = await introspectGraphQlDataSource({
-      id: 'catalog',
-      endpointUrl: 'https://api.example.com/graphql',
-      fetch: () => Promise.resolve(jsonResponse({ secret: 'hidden' }, 403)),
-    });
-    const shape = await introspectGraphQlDataSource({
-      id: 'catalog',
-      endpointUrl: 'https://api.example.com/graphql',
-      fetch: () => Promise.resolve(jsonResponse({ data: {} })),
-    });
-    expect(http).toMatchObject({ ok: false, status: 403 });
-    expect(JSON.stringify(http)).not.toContain('hidden');
-    expect(shape.ok).toBe(false);
+it('reports GraphQL transport and response-shape failures safely', async () => {
+  const http = await introspectGraphQlApi({
+    id: 'catalog',
+    endpointUrl: 'https://api.example.com/graphql',
+    fetch: () => Promise.resolve(jsonResponse({ secret: 'hidden' }, 403)),
+  });
+  const shape = await introspectGraphQlApi({
+    id: 'catalog',
+    endpointUrl: 'https://api.example.com/graphql',
+    fetch: () => Promise.resolve(jsonResponse({ data: {} })),
   });
+  expect(http).toMatchObject({ ok: false, status: 403 });
+  expect(JSON.stringify(http)).not.toContain('hidden');
+  expect(shape.ok).toBe(false);
+  if (!shape.ok) expect(shape.diagnostics[0]?.apiId).toBe('catalog');
 });

package/src/discovery/index.ts

@@ -2,16 +2,23 @@ import type {
   CredentialRef,
   DataContractValue,
   DataSourceDiagnostic,
-  ExternalGraphQlApiDataSourceConfig,
-  ExternalRestApiDataSourceConfig,
+  ExternalGraphQlApiDefinition,
+  ExternalRestApiDefinition,
 } from '@ankhorage/contracts/data';
 
 import {
-  createGraphQlDataSource,
+  createGraphQlApi,
   createGraphQlIntrospectionRequest,
   type GraphQlIntrospectionResult,
 } from '../graphql';
 import { importOpenApiDocument, type OpenApiDocumentObject } from '../openapi';
+import {
+  isSuccessfulStatus,
+  normalizeCandidateUrl,
+  parseHttpUrl,
+  parseJsonResponse,
+  readRecord,
+} from './http';
 
 export const DEFAULT_OPENAPI_DISCOVERY_PATHS = [
   'openapi.json',
@@ -50,7 +57,7 @@ export interface OpenApiDiscoveryAttempt {
   readonly status?: number;
 }
 
-export interface DiscoverOpenApiDataSourceInput {
+export interface DiscoverOpenApiInput {
   readonly id: string;
   readonly url: string;
   readonly fetch: ExternalApiFetch;
@@ -62,10 +69,10 @@ export interface DiscoverOpenApiDataSourceInput {
   readonly conventionalPaths?: readonly string[];
 }
 
-export type DiscoverOpenApiDataSourceResult =
+export type DiscoverOpenApiResult =
   | {
       readonly ok: true;
-      readonly data: ExternalRestApiDataSourceConfig;
+      readonly data: ExternalRestApiDefinition;
       readonly documentUrl: string;
       readonly attempts: readonly OpenApiDiscoveryAttempt[];
       readonly diagnostics: readonly DataSourceDiagnostic[];
@@ -76,7 +83,7 @@ export type DiscoverOpenApiDataSourceResult =
       readonly diagnostics: readonly DataSourceDiagnostic[];
     };
 
-export interface IntrospectGraphQlDataSourceInput {
+export interface IntrospectGraphQlApiInput {
   readonly id: string;
   readonly endpointUrl: string;
   readonly fetch: ExternalApiFetch;
@@ -88,10 +95,10 @@ export interface IntrospectGraphQlDataSourceInput {
   readonly metadata?: DataContractValue;
 }
 
-export type IntrospectGraphQlDataSourceResult =
+export type IntrospectGraphQlApiResult =
   | {
       readonly ok: true;
-      readonly data: ExternalGraphQlApiDataSourceConfig;
+      readonly data: ExternalGraphQlApiDefinition;
       readonly diagnostics: readonly DataSourceDiagnostic[];
     }
   | {
@@ -121,9 +128,7 @@ export function createOpenApiDiscoveryCandidates(
   return [...new Set(candidates)];
 }
 
-export async function discoverOpenApiDataSource(
-  input: DiscoverOpenApiDataSourceInput,
-): Promise<DiscoverOpenApiDataSourceResult> {
+export async function discoverOpenApi(input: DiscoverOpenApiInput): Promise<DiscoverOpenApiResult> {
   const candidates = createOpenApiDiscoveryCandidates(input.url, input.conventionalPaths);
   if (candidates.length === 0) {
     return discoveryFailure(input.id, [], 'OpenAPI discovery requires a valid HTTP or HTTPS URL.');
@@ -152,29 +157,18 @@ export async function discoverOpenApiDataSource(
   );
 }
 
-export async function introspectGraphQlDataSource(
-  input: IntrospectGraphQlDataSourceInput,
-): Promise<IntrospectGraphQlDataSourceResult> {
+export async function introspectGraphQlApi(
+  input: IntrospectGraphQlApiInput,
+): Promise<IntrospectGraphQlApiResult> {
   const endpoint = parseHttpUrl(input.endpointUrl);
   if (endpoint === undefined) {
     return graphqlFailure(input.id, 'GraphQL introspection requires a valid HTTP or HTTPS URL.');
   }
 
-  let response: ExternalApiFetchResponse;
-  try {
-    response = await input.fetch(normalizeCandidateUrl(endpoint), {
-      method: 'POST',
-      headers: {
-        accept: 'application/json',
-        'content-type': 'application/json',
-        ...(input.headers ?? {}),
-      },
-      body: JSON.stringify(createGraphQlIntrospectionRequest()),
-    });
-  } catch {
+  const response = await fetchGraphQlIntrospection(input, endpoint);
+  if (response === undefined) {
     return graphqlFailure(input.id, 'GraphQL introspection request failed.', 'network-error');
   }
-
   if (!isSuccessfulStatus(response.status)) {
     return {
       ...graphqlFailure(
@@ -195,7 +189,7 @@ export async function introspectGraphQlDataSource(
     );
   }
 
-  const result = createGraphQlDataSource({
+  const result = createGraphQlApi({
     id: input.id,
     endpointUrl: normalizeCandidateUrl(endpoint),
     credential: input.credential,
@@ -206,19 +200,37 @@ export async function introspectGraphQlDataSource(
     schemaVersion: input.schemaVersion,
     metadata: input.metadata,
   });
-
   return result.ok
     ? { ok: true, data: result.data, diagnostics: result.diagnostics ?? [] }
     : { ok: false, diagnostics: result.diagnostics };
 }
 
+async function fetchGraphQlIntrospection(
+  input: IntrospectGraphQlApiInput,
+  endpoint: URL,
+): Promise<ExternalApiFetchResponse | undefined> {
+  try {
+    return await input.fetch(normalizeCandidateUrl(endpoint), {
+      method: 'POST',
+      headers: {
+        accept: 'application/json',
+        'content-type': 'application/json',
+        ...(input.headers ?? {}),
+      },
+      body: JSON.stringify(createGraphQlIntrospectionRequest()),
+    });
+  } catch {
+    return undefined;
+  }
+}
+
 interface OpenApiProbeResult {
   readonly attempt: OpenApiDiscoveryAttempt;
   readonly result?: ReturnType<typeof importOpenApiDocument>;
 }
 
 async function probeOpenApiCandidate(
-  input: DiscoverOpenApiDataSourceInput,
+  input: DiscoverOpenApiInput,
   candidate: string,
 ): Promise<OpenApiProbeResult> {
   let response: ExternalApiFetchResponse;
@@ -265,35 +277,6 @@ async function probeOpenApiCandidate(
   };
 }
 
-function parseHttpUrl(rawUrl: string): URL | undefined {
-  try {
-    const parsed = new URL(rawUrl.trim());
-    if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') return undefined;
-    if (parsed.username.length > 0 || parsed.password.length > 0) return undefined;
-    return parsed;
-  } catch {
-    return undefined;
-  }
-}
-
-function normalizeCandidateUrl(url: URL): string {
-  const normalized = new URL(url.toString());
-  normalized.hash = '';
-  return normalized.toString();
-}
-
-function isSuccessfulStatus(status: number): boolean {
-  return status >= 200 && status < 300;
-}
-
-async function parseJsonResponse(response: ExternalApiFetchResponse): Promise<unknown> {
-  try {
-    return JSON.parse(await response.text()) as unknown;
-  } catch {
-    return undefined;
-  }
-}
-
 function isOpenApiDocument(value: unknown): value is OpenApiDocumentObject {
   const record = readRecord(value);
   return (
@@ -310,31 +293,25 @@ function readGraphQlIntrospection(value: unknown): GraphQlIntrospectionResult |
   return data;
 }
 
-function readRecord(value: unknown): Readonly<Record<string, unknown>> | undefined {
-  return typeof value === 'object' && value !== null && !Array.isArray(value)
-    ? (value as Readonly<Record<string, unknown>>)
-    : undefined;
-}
-
 function discoveryFailure(
-  dataSourceId: string,
+  apiId: string,
   attempts: readonly OpenApiDiscoveryAttempt[],
   message: string,
-): DiscoverOpenApiDataSourceResult {
+): DiscoverOpenApiResult {
   return {
     ok: false,
     attempts,
-    diagnostics: [{ code: 'missing-schema', dataSourceId, message, severity: 'error' }],
+    diagnostics: [{ code: 'missing-schema', apiId, message, severity: 'error' }],
   };
 }
 
 function graphqlFailure(
-  dataSourceId: string,
+  apiId: string,
   message: string,
   code: DataSourceDiagnostic['code'] = 'invalid-config',
-): Extract<IntrospectGraphQlDataSourceResult, { readonly ok: false }> {
+): Extract<IntrospectGraphQlApiResult, { readonly ok: false }> {
   return {
     ok: false,
-    diagnostics: [{ code, dataSourceId, message, severity: 'error' }],
+    diagnostics: [{ code, apiId, message, severity: 'error' }],
   };
 }

package/src/graphql/index.test.ts

@@ -1,7 +1,7 @@
 import { describe, expect, it } from 'bun:test';
 
 import {
-  createGraphQlDataSource,
+  createGraphQlApi,
   createGraphQlIntrospectionRequest,
   type GraphQlIntrospectionResult,
   normalizeGraphQlIntrospectionOperations,
@@ -46,7 +46,7 @@ function introspection(): GraphQlIntrospectionResult {
   };
 }
 
-describe('GraphQL normalization', () => {
+describe('GraphQL API normalization', () => {
   it('creates the standard introspection request and stable IDs', () => {
     expect(createGraphQlIntrospectionRequest().query).toContain('__schema');
     expect(normalizeGraphQlOperationId('query', 'Posts')).toBe('query.posts');
@@ -59,25 +59,23 @@ describe('GraphQL normalization', () => {
     );
   });
 
-  it('creates an external GraphQL API source', () => {
-    const result = createGraphQlDataSource({
+  it('creates a canonical external GraphQL API', () => {
+    const result = createGraphQlApi({
       id: 'content',
       endpointUrl: 'https://example.com/graphql',
       introspection: introspection(),
     });
     expect(result.ok).toBe(true);
     if (result.ok) {
-      expect(result.data).toMatchObject({
-        kind: 'api',
-        origin: 'external',
-        protocol: 'graphql',
-      });
+      expect(result.data).toMatchObject({ origin: 'external', protocol: 'graphql' });
+      expect('kind' in result.data).toBe(false);
+      expect(result.data.endpoints.graphql?.baseUrl).toBeUndefined();
       expect(result.data.endpoints.graphql?.operations['query.posts']?.intent).toBe('read');
     }
   });
 
   it('supports manual operations and validates endpoint URLs', () => {
-    const manual = createGraphQlDataSource({
+    const manual = createGraphQlApi({
       id: 'manual',
       endpointUrl: 'https://example.com/graphql',
       introspectionEnabled: false,
@@ -89,8 +87,9 @@ describe('GraphQL normalization', () => {
         },
       ],
     });
-    const invalid = createGraphQlDataSource({ id: 'broken', endpointUrl: ' ' });
+    const invalid = createGraphQlApi({ id: 'broken', endpointUrl: ' ' });
     expect(manual.ok).toBe(true);
     expect(invalid.ok).toBe(false);
+    if (!invalid.ok) expect(invalid.diagnostics[0]?.apiId).toBe('broken');
   });
 });