@ankhorage/data-sources 0.5.5 → 0.6.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @ankhorage/data-sources
 
+## 0.6.0
+
+### Minor Changes
+
+- 4922dcd: Add transport-injected OpenAPI URL discovery and GraphQL introspection primitives for canonical external data-source authoring.
+
 ## 0.5.5
 
 ### Patch Changes

package/README.md

@@ -3,7 +3,7 @@
 
 # @ankhorage/data-sources
 
-![license: MIT](././paradox/badges/license.svg) ![npm: v0.5.3](././paradox/badges/npm.svg) ![runtime: bun](././paradox/badges/runtime.svg) ![typescript: strict](././paradox/badges/typescript.svg) ![eslint: checked](././paradox/badges/eslint.svg) ![prettier: checked](././paradox/badges/prettier.svg) ![build: checked](././paradox/badges/build.svg) ![tests: checked](././paradox/badges/tests.svg) ![docs: paradox](././paradox/badges/docs.svg)
+![license: MIT](././paradox/badges/license.svg) ![npm: v0.5.5](././paradox/badges/npm.svg) ![runtime: bun](././paradox/badges/runtime.svg) ![typescript: strict](././paradox/badges/typescript.svg) ![eslint: checked](././paradox/badges/eslint.svg) ![prettier: checked](././paradox/badges/prettier.svg) ![build: checked](././paradox/badges/build.svg) ![tests: checked](././paradox/badges/tests.svg) ![docs: paradox](././paradox/badges/docs.svg)
 
 Provider-neutral data source and endpoint system for APIs, databases, and runtime bindings.
 
@@ -17,6 +17,7 @@ Provider-neutral data source and endpoint system for APIs, databases, and runtim
 - [Export graph](././paradox/diagrams/export-graph.mmd)
 - [createManagedApiResourceSchema sequence](././paradox/diagrams/sequences/create-managed-api-resource-schema.mmd)
 - [createManualRestDataSource sequence](././paradox/diagrams/sequences/create-manual-rest-data-source.mmd)
+- [createOpenApiDiscoveryCandidates sequence](././paradox/diagrams/sequences/create-open-api-discovery-candidates.mmd)
 - [normalizeGraphQlIntrospectionOperations sequence](././paradox/diagrams/sequences/normalize-graph-ql-introspection-operations.mmd)
 - [normalizeGraphQlIntrospectionSchemas sequence](././paradox/diagrams/sequences/normalize-graph-ql-introspection-schemas.mmd)
 - [normalizeManualRestDataSource sequence](././paradox/diagrams/sequences/normalize-manual-rest-data-source.mmd)
@@ -37,6 +38,12 @@ graph TD
   module_src_ankh_provider_ts["src/ankh.provider.ts"]
   package__ankhorage_data_sources -.-> module_src_ankh_provider_ts
   module_src_ankh_provider_ts --> module_src_index_ts
+  module_src_cli_index_ts["src/cli/index.ts"]
+  package__ankhorage_data_sources -.-> module_src_cli_index_ts
+  module_src_discovery_index_ts["src/discovery/index.ts"]
+  package__ankhorage_data_sources -.-> module_src_discovery_index_ts
+  module_src_discovery_index_ts --> module_src_graphql_index_ts
+  module_src_discovery_index_ts --> module_src_openapi_index_ts
   module_src_graphql_index_ts["src/graphql/index.ts"]
   package__ankhorage_data_sources -.-> module_src_graphql_index_ts
   module_src_index_ts["src/index.ts"]

package/dist/discovery/index.d.ts

@@ -0,0 +1,64 @@
+import type { CredentialRef, DataContractValue, DataSourceDiagnostic, GraphQlDataSourceConfig, OpenApiDataSourceConfig } from '@ankhorage/contracts/data';
+export declare const DEFAULT_OPENAPI_DISCOVERY_PATHS: readonly ["openapi.json", "swagger.json", "api/openapi.json", "v3/api-docs"];
+export interface ExternalApiFetchInit {
+    readonly method: 'GET' | 'POST';
+    readonly headers: Readonly<Record<string, string>>;
+    readonly body?: string;
+}
+export interface ExternalApiFetchResponse {
+    readonly status: number;
+    text(): Promise<string>;
+}
+export type ExternalApiFetch = (url: string, init: ExternalApiFetchInit) => Promise<ExternalApiFetchResponse>;
+export type OpenApiDiscoveryAttemptOutcome = 'http-error' | 'invalid-document' | 'matched' | 'network-error' | 'parse-error' | 'unsupported-document';
+export interface OpenApiDiscoveryAttempt {
+    readonly url: string;
+    readonly outcome: OpenApiDiscoveryAttemptOutcome;
+    readonly status?: number;
+}
+export interface DiscoverOpenApiDataSourceInput {
+    readonly id: string;
+    readonly url: string;
+    readonly fetch: ExternalApiFetch;
+    readonly baseUrl?: string;
+    readonly credential?: CredentialRef;
+    readonly name?: string;
+    readonly description?: string;
+    readonly metadata?: DataContractValue;
+    readonly conventionalPaths?: readonly string[];
+}
+export type DiscoverOpenApiDataSourceResult = {
+    readonly ok: true;
+    readonly data: OpenApiDataSourceConfig;
+    readonly documentUrl: string;
+    readonly attempts: readonly OpenApiDiscoveryAttempt[];
+    readonly diagnostics: readonly DataSourceDiagnostic[];
+} | {
+    readonly ok: false;
+    readonly attempts: readonly OpenApiDiscoveryAttempt[];
+    readonly diagnostics: readonly DataSourceDiagnostic[];
+};
+export interface IntrospectGraphQlDataSourceInput {
+    readonly id: string;
+    readonly endpointUrl: string;
+    readonly fetch: ExternalApiFetch;
+    readonly headers?: Readonly<Record<string, string>>;
+    readonly credential?: CredentialRef;
+    readonly name?: string;
+    readonly description?: string;
+    readonly schemaVersion?: string;
+    readonly metadata?: DataContractValue;
+}
+export type IntrospectGraphQlDataSourceResult = {
+    readonly ok: true;
+    readonly data: GraphQlDataSourceConfig;
+    readonly diagnostics: readonly DataSourceDiagnostic[];
+} | {
+    readonly ok: false;
+    readonly diagnostics: readonly DataSourceDiagnostic[];
+    readonly status?: number;
+};
+export declare function createOpenApiDiscoveryCandidates(rawUrl: string, conventionalPaths?: readonly string[]): readonly string[];
+export declare function discoverOpenApiDataSource(input: DiscoverOpenApiDataSourceInput): Promise<DiscoverOpenApiDataSourceResult>;
+export declare function introspectGraphQlDataSource(input: IntrospectGraphQlDataSourceInput): Promise<IntrospectGraphQlDataSourceResult>;
+//# sourceMappingURL=index.d.ts.map

package/dist/discovery/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/discovery/index.ts"],"names":[],"mappings":"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"}

package/dist/discovery/index.js

@@ -0,0 +1,204 @@
+import { createGraphQlDataSource, createGraphQlIntrospectionRequest, } from '../graphql';
+import { importOpenApiDocument } from '../openapi';
+export const DEFAULT_OPENAPI_DISCOVERY_PATHS = [
+    'openapi.json',
+    'swagger.json',
+    'api/openapi.json',
+    'v3/api-docs',
+];
+export function createOpenApiDiscoveryCandidates(rawUrl, conventionalPaths = DEFAULT_OPENAPI_DISCOVERY_PATHS) {
+    const parsed = parseHttpUrl(rawUrl);
+    if (parsed === undefined)
+        return [];
+    const exact = normalizeCandidateUrl(parsed);
+    const serviceBase = new URL(exact);
+    if (!serviceBase.pathname.endsWith('/'))
+        serviceBase.pathname = `${serviceBase.pathname}/`;
+    const candidates = [exact];
+    for (const path of conventionalPaths) {
+        const normalizedPath = path.replace(/^\/+/, '');
+        candidates.push(normalizeCandidateUrl(new URL(normalizedPath, serviceBase)));
+        candidates.push(normalizeCandidateUrl(new URL(normalizedPath, `${parsed.origin}/`)));
+    }
+    return [...new Set(candidates)];
+}
+export async function discoverOpenApiDataSource(input) {
+    const candidates = createOpenApiDiscoveryCandidates(input.url, input.conventionalPaths);
+    if (candidates.length === 0) {
+        return discoveryFailure(input.id, [], 'OpenAPI discovery requires a valid HTTP or HTTPS URL.');
+    }
+    const attempts = [];
+    for (const candidate of candidates) {
+        const probed = await probeOpenApiCandidate(input, candidate);
+        attempts.push(probed.attempt);
+        if (probed.result !== undefined) {
+            return probed.result.ok
+                ? {
+                    ok: true,
+                    data: probed.result.data,
+                    documentUrl: candidate,
+                    attempts,
+                    diagnostics: probed.result.diagnostics ?? [],
+                }
+                : { ok: false, attempts, diagnostics: probed.result.diagnostics };
+        }
+    }
+    return discoveryFailure(input.id, attempts, 'No supported OpenAPI document was found at the supplied URL or conventional locations.');
+}
+export async function introspectGraphQlDataSource(input) {
+    const endpoint = parseHttpUrl(input.endpointUrl);
+    if (endpoint === undefined) {
+        return graphqlFailure(input.id, 'GraphQL introspection requires a valid HTTP or HTTPS URL.');
+    }
+    const request = createGraphQlIntrospectionRequest();
+    let response;
+    try {
+        response = await input.fetch(normalizeCandidateUrl(endpoint), {
+            method: 'POST',
+            headers: {
+                accept: 'application/json',
+                'content-type': 'application/json',
+                ...(input.headers ?? {}),
+            },
+            body: JSON.stringify(request),
+        });
+    }
+    catch {
+        return graphqlFailure(input.id, 'GraphQL introspection request failed.', 'network-error');
+    }
+    if (!isSuccessfulStatus(response.status)) {
+        return {
+            ...graphqlFailure(input.id, `GraphQL introspection returned HTTP status ${response.status}.`, 'network-error'),
+            status: response.status,
+        };
+    }
+    const parsed = await parseJsonResponse(response);
+    const introspection = readGraphQlIntrospection(parsed);
+    if (introspection === undefined) {
+        return graphqlFailure(input.id, 'GraphQL introspection response did not contain data.__schema.', 'parse-error');
+    }
+    const result = createGraphQlDataSource({
+        id: input.id,
+        endpointUrl: normalizeCandidateUrl(endpoint),
+        credential: input.credential,
+        name: input.name,
+        description: input.description,
+        introspection,
+        introspectionEnabled: true,
+        schemaVersion: input.schemaVersion,
+        metadata: input.metadata,
+    });
+    return result.ok
+        ? { ok: true, data: result.data, diagnostics: result.diagnostics ?? [] }
+        : { ok: false, diagnostics: result.diagnostics };
+}
+async function probeOpenApiCandidate(input, candidate) {
+    let response;
+    try {
+        response = await input.fetch(candidate, {
+            method: 'GET',
+            headers: {
+                accept: 'application/json, application/vnd.oai.openapi+json',
+            },
+        });
+    }
+    catch {
+        return { attempt: { url: candidate, outcome: 'network-error' } };
+    }
+    if (!isSuccessfulStatus(response.status)) {
+        return {
+            attempt: { url: candidate, outcome: 'http-error', status: response.status },
+        };
+    }
+    const parsed = await parseJsonResponse(response);
+    if (parsed === undefined) {
+        return {
+            attempt: { url: candidate, outcome: 'parse-error', status: response.status },
+        };
+    }
+    if (!isOpenApiDocument(parsed)) {
+        return {
+            attempt: { url: candidate, outcome: 'unsupported-document', status: response.status },
+        };
+    }
+    const result = importOpenApiDocument({
+        id: input.id,
+        document: parsed,
+        baseUrl: input.baseUrl,
+        credential: input.credential,
+        documentUrl: candidate,
+        name: input.name,
+        description: input.description,
+        metadata: input.metadata,
+    });
+    return {
+        attempt: {
+            url: candidate,
+            outcome: result.ok ? 'matched' : 'invalid-document',
+            status: response.status,
+        },
+        result,
+    };
+}
+function parseHttpUrl(rawUrl) {
+    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) {
+    const normalized = new URL(url.toString());
+    normalized.hash = '';
+    return normalized.toString();
+}
+function isSuccessfulStatus(status) {
+    return status >= 200 && status < 300;
+}
+async function parseJsonResponse(response) {
+    try {
+        return JSON.parse(await response.text());
+    }
+    catch {
+        return undefined;
+    }
+}
+function isOpenApiDocument(value) {
+    const record = readRecord(value);
+    return (record !== undefined &&
+        typeof record.openapi === 'string' &&
+        readRecord(record.paths) !== undefined);
+}
+function readGraphQlIntrospection(value) {
+    const payload = readRecord(value);
+    const data = readRecord(payload?.data);
+    if (readRecord(data?.__schema) === undefined)
+        return undefined;
+    return data;
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function readRecord(value) {
+    return isRecord(value) ? value : undefined;
+}
+function discoveryFailure(dataSourceId, attempts, message) {
+    return {
+        ok: false,
+        attempts,
+        diagnostics: [{ code: 'missing-schema', dataSourceId, message, severity: 'error' }],
+    };
+}
+function graphqlFailure(dataSourceId, message, code = 'invalid-config') {
+    return {
+        ok: false,
+        diagnostics: [{ code, dataSourceId, message, severity: 'error' }],
+    };
+}
+//# sourceMappingURL=index.js.map

package/dist/discovery/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/discovery/index.ts"],"names":[],"mappings":"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","sourcesContent":["import type {\n  CredentialRef,\n  DataContractValue,\n  DataSourceDiagnostic,\n  GraphQlDataSourceConfig,\n  OpenApiDataSourceConfig,\n} from '@ankhorage/contracts/data';\n\nimport {\n  createGraphQlDataSource,\n  createGraphQlIntrospectionRequest,\n  type GraphQlIntrospectionResult,\n} from '../graphql';\nimport { importOpenApiDocument, type OpenApiDocumentObject } from '../openapi';\n\nexport const DEFAULT_OPENAPI_DISCOVERY_PATHS = [\n  'openapi.json',\n  'swagger.json',\n  'api/openapi.json',\n  'v3/api-docs',\n] as const;\n\nexport interface ExternalApiFetchInit {\n  readonly method: 'GET' | 'POST';\n  readonly headers: Readonly<Record<string, string>>;\n  readonly body?: string;\n}\n\nexport interface ExternalApiFetchResponse {\n  readonly status: number;\n  text(): Promise<string>;\n}\n\nexport type ExternalApiFetch = (\n  url: string,\n  init: ExternalApiFetchInit,\n) => Promise<ExternalApiFetchResponse>;\n\nexport type OpenApiDiscoveryAttemptOutcome =\n  | 'http-error'\n  | 'invalid-document'\n  | 'matched'\n  | 'network-error'\n  | 'parse-error'\n  | 'unsupported-document';\n\nexport interface OpenApiDiscoveryAttempt {\n  readonly url: string;\n  readonly outcome: OpenApiDiscoveryAttemptOutcome;\n  readonly status?: number;\n}\n\nexport interface DiscoverOpenApiDataSourceInput {\n  readonly id: string;\n  readonly url: string;\n  readonly fetch: ExternalApiFetch;\n  readonly baseUrl?: string;\n  readonly credential?: CredentialRef;\n  readonly name?: string;\n  readonly description?: string;\n  readonly metadata?: DataContractValue;\n  readonly conventionalPaths?: readonly string[];\n}\n\nexport type DiscoverOpenApiDataSourceResult =\n  | {\n      readonly ok: true;\n      readonly data: OpenApiDataSourceConfig;\n      readonly documentUrl: string;\n      readonly attempts: readonly OpenApiDiscoveryAttempt[];\n      readonly diagnostics: readonly DataSourceDiagnostic[];\n    }\n  | {\n      readonly ok: false;\n      readonly attempts: readonly OpenApiDiscoveryAttempt[];\n      readonly diagnostics: readonly DataSourceDiagnostic[];\n    };\n\nexport interface IntrospectGraphQlDataSourceInput {\n  readonly id: string;\n  readonly endpointUrl: string;\n  readonly fetch: ExternalApiFetch;\n  readonly headers?: Readonly<Record<string, string>>;\n  readonly credential?: CredentialRef;\n  readonly name?: string;\n  readonly description?: string;\n  readonly schemaVersion?: string;\n  readonly metadata?: DataContractValue;\n}\n\nexport type IntrospectGraphQlDataSourceResult =\n  | {\n      readonly ok: true;\n      readonly data: GraphQlDataSourceConfig;\n      readonly diagnostics: readonly DataSourceDiagnostic[];\n    }\n  | {\n      readonly ok: false;\n      readonly diagnostics: readonly DataSourceDiagnostic[];\n      readonly status?: number;\n    };\n\nexport function createOpenApiDiscoveryCandidates(\n  rawUrl: string,\n  conventionalPaths: readonly string[] = DEFAULT_OPENAPI_DISCOVERY_PATHS,\n): readonly string[] {\n  const parsed = parseHttpUrl(rawUrl);\n  if (parsed === undefined) return [];\n\n  const exact = normalizeCandidateUrl(parsed);\n  const serviceBase = new URL(exact);\n  if (!serviceBase.pathname.endsWith('/')) serviceBase.pathname = `${serviceBase.pathname}/`;\n\n  const candidates = [exact];\n  for (const path of conventionalPaths) {\n    const normalizedPath = path.replace(/^\\/+/, '');\n    candidates.push(normalizeCandidateUrl(new URL(normalizedPath, serviceBase)));\n    candidates.push(normalizeCandidateUrl(new URL(normalizedPath, `${parsed.origin}/`)));\n  }\n\n  return [...new Set(candidates)];\n}\n\nexport async function discoverOpenApiDataSource(\n  input: DiscoverOpenApiDataSourceInput,\n): Promise<DiscoverOpenApiDataSourceResult> {\n  const candidates = createOpenApiDiscoveryCandidates(input.url, input.conventionalPaths);\n  if (candidates.length === 0) {\n    return discoveryFailure(input.id, [], 'OpenAPI discovery requires a valid HTTP or HTTPS URL.');\n  }\n\n  const attempts: OpenApiDiscoveryAttempt[] = [];\n  for (const candidate of candidates) {\n    const probed = await probeOpenApiCandidate(input, candidate);\n    attempts.push(probed.attempt);\n    if (probed.result !== undefined) {\n      return probed.result.ok\n        ? {\n            ok: true,\n            data: probed.result.data,\n            documentUrl: candidate,\n            attempts,\n            diagnostics: probed.result.diagnostics ?? [],\n          }\n        : { ok: false, attempts, diagnostics: probed.result.diagnostics };\n    }\n  }\n\n  return discoveryFailure(\n    input.id,\n    attempts,\n    'No supported OpenAPI document was found at the supplied URL or conventional locations.',\n  );\n}\n\nexport async function introspectGraphQlDataSource(\n  input: IntrospectGraphQlDataSourceInput,\n): Promise<IntrospectGraphQlDataSourceResult> {\n  const endpoint = parseHttpUrl(input.endpointUrl);\n  if (endpoint === undefined) {\n    return graphqlFailure(input.id, 'GraphQL introspection requires a valid HTTP or HTTPS URL.');\n  }\n\n  const request = createGraphQlIntrospectionRequest();\n  let response: ExternalApiFetchResponse;\n  try {\n    response = await input.fetch(normalizeCandidateUrl(endpoint), {\n      method: 'POST',\n      headers: {\n        accept: 'application/json',\n        'content-type': 'application/json',\n        ...(input.headers ?? {}),\n      },\n      body: JSON.stringify(request),\n    });\n  } catch {\n    return graphqlFailure(input.id, 'GraphQL introspection request failed.', 'network-error');\n  }\n\n  if (!isSuccessfulStatus(response.status)) {\n    return {\n      ...graphqlFailure(\n        input.id,\n        `GraphQL introspection returned HTTP status ${response.status}.`,\n        'network-error',\n      ),\n      status: response.status,\n    };\n  }\n\n  const parsed = await parseJsonResponse(response);\n  const introspection = readGraphQlIntrospection(parsed);\n  if (introspection === undefined) {\n    return graphqlFailure(\n      input.id,\n      'GraphQL introspection response did not contain data.__schema.',\n      'parse-error',\n    );\n  }\n\n  const result = createGraphQlDataSource({\n    id: input.id,\n    endpointUrl: normalizeCandidateUrl(endpoint),\n    credential: input.credential,\n    name: input.name,\n    description: input.description,\n    introspection,\n    introspectionEnabled: true,\n    schemaVersion: input.schemaVersion,\n    metadata: input.metadata,\n  });\n\n  return result.ok\n    ? { ok: true, data: result.data, diagnostics: result.diagnostics ?? [] }\n    : { ok: false, diagnostics: result.diagnostics };\n}\n\ninterface OpenApiProbeResult {\n  readonly attempt: OpenApiDiscoveryAttempt;\n  readonly result?: ReturnType<typeof importOpenApiDocument>;\n}\n\nasync function probeOpenApiCandidate(\n  input: DiscoverOpenApiDataSourceInput,\n  candidate: string,\n): Promise<OpenApiProbeResult> {\n  let response: ExternalApiFetchResponse;\n  try {\n    response = await input.fetch(candidate, {\n      method: 'GET',\n      headers: {\n        accept: 'application/json, application/vnd.oai.openapi+json',\n      },\n    });\n  } catch {\n    return { attempt: { url: candidate, outcome: 'network-error' } };\n  }\n\n  if (!isSuccessfulStatus(response.status)) {\n    return {\n      attempt: { url: candidate, outcome: 'http-error', status: response.status },\n    };\n  }\n\n  const parsed = await parseJsonResponse(response);\n  if (parsed === undefined) {\n    return {\n      attempt: { url: candidate, outcome: 'parse-error', status: response.status },\n    };\n  }\n\n  if (!isOpenApiDocument(parsed)) {\n    return {\n      attempt: { url: candidate, outcome: 'unsupported-document', status: response.status },\n    };\n  }\n\n  const result = importOpenApiDocument({\n    id: input.id,\n    document: parsed,\n    baseUrl: input.baseUrl,\n    credential: input.credential,\n    documentUrl: candidate,\n    name: input.name,\n    description: input.description,\n    metadata: input.metadata,\n  });\n\n  return {\n    attempt: {\n      url: candidate,\n      outcome: result.ok ? 'matched' : 'invalid-document',\n      status: response.status,\n    },\n    result,\n  };\n}\n\nfunction parseHttpUrl(rawUrl: string): URL | undefined {\n  try {\n    const parsed = new URL(rawUrl.trim());\n    if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') return undefined;\n    if (parsed.username.length > 0 || parsed.password.length > 0) return undefined;\n    return parsed;\n  } catch {\n    return undefined;\n  }\n}\n\nfunction normalizeCandidateUrl(url: URL): string {\n  const normalized = new URL(url.toString());\n  normalized.hash = '';\n  return normalized.toString();\n}\n\nfunction isSuccessfulStatus(status: number): boolean {\n  return status >= 200 && status < 300;\n}\n\nasync function parseJsonResponse(response: ExternalApiFetchResponse): Promise<unknown> {\n  try {\n    return JSON.parse(await response.text()) as unknown;\n  } catch {\n    return undefined;\n  }\n}\n\nfunction isOpenApiDocument(value: unknown): value is OpenApiDocumentObject {\n  const record = readRecord(value);\n  return (\n    record !== undefined &&\n    typeof record.openapi === 'string' &&\n    readRecord(record.paths) !== undefined\n  );\n}\n\nfunction readGraphQlIntrospection(value: unknown): GraphQlIntrospectionResult | undefined {\n  const payload = readRecord(value);\n  const data = readRecord(payload?.data);\n  if (readRecord(data?.__schema) === undefined) return undefined;\n  return data;\n}\n\nfunction isRecord(value: unknown): value is Readonly<Record<string, unknown>> {\n  return typeof value === 'object' && value !== null && !Array.isArray(value);\n}\n\nfunction readRecord(value: unknown): Readonly<Record<string, unknown>> | undefined {\n  return isRecord(value) ? value : undefined;\n}\n\nfunction discoveryFailure(\n  dataSourceId: string,\n  attempts: readonly OpenApiDiscoveryAttempt[],\n  message: string,\n): DiscoverOpenApiDataSourceResult {\n  return {\n    ok: false,\n    attempts,\n    diagnostics: [{ code: 'missing-schema', dataSourceId, message, severity: 'error' }],\n  };\n}\n\nfunction graphqlFailure(\n  dataSourceId: string,\n  message: string,\n  code: DataSourceDiagnostic['code'] = 'invalid-config',\n): Extract<IntrospectGraphQlDataSourceResult, { readonly ok: false }> {\n  return {\n    ok: false,\n    diagnostics: [{ code, dataSourceId, message, severity: 'error' }],\n  };\n}\n"]}

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 import type { DataSourceConfig, DataSourceKind } from '@ankhorage/contracts/data';
+export * from './discovery';
 export * from './graphql';
 export * from './managed-api';
 export * from './openapi';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAElF,cAAc,WAAW,CAAC;AAC1B,cAAc,eAAe,CAAC;AAC9B,cAAc,WAAW,CAAC;AAC1B,cAAc,QAAQ,CAAC;AACvB,cAAc,eAAe,CAAC;AAE9B,eAAO,MAAM,yBAAyB,EAAG,yBAAkC,CAAC;AAE5E,eAAO,MAAM,2BAA2B,oEAMM,CAAC;AAE/C,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,WAAW,EAAE,OAAO,yBAAyB,CAAC;IACvD,QAAQ,CAAC,cAAc,EAAE,OAAO,2BAA2B,CAAC;CAC7D;AAED,wBAAgB,yBAAyB,IAAI,sBAAsB,CAKlE;AAED,wBAAgB,yBAAyB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,IAAI,cAAc,CAE9E;AAED,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,gBAAgB,GAAG,cAAc,CAE1E"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAElF,cAAc,aAAa,CAAC;AAC5B,cAAc,WAAW,CAAC;AAC1B,cAAc,eAAe,CAAC;AAC9B,cAAc,WAAW,CAAC;AAC1B,cAAc,QAAQ,CAAC;AACvB,cAAc,eAAe,CAAC;AAE9B,eAAO,MAAM,yBAAyB,EAAG,yBAAkC,CAAC;AAE5E,eAAO,MAAM,2BAA2B,oEAMM,CAAC;AAE/C,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,WAAW,EAAE,OAAO,yBAAyB,CAAC;IACvD,QAAQ,CAAC,cAAc,EAAE,OAAO,2BAA2B,CAAC;CAC7D;AAED,wBAAgB,yBAAyB,IAAI,sBAAsB,CAKlE;AAED,wBAAgB,yBAAyB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,IAAI,cAAc,CAE9E;AAED,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,gBAAgB,GAAG,cAAc,CAE1E"}

package/dist/index.js

@@ -1,3 +1,4 @@
+export * from './discovery';
 export * from './graphql';
 export * from './managed-api';
 export * from './openapi';

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAEA,cAAc,WAAW,CAAC;AAC1B,cAAc,eAAe,CAAC;AAC9B,cAAc,WAAW,CAAC;AAC1B,cAAc,QAAQ,CAAC;AACvB,cAAc,eAAe,CAAC;AAE9B,MAAM,CAAC,MAAM,yBAAyB,GAAG,yBAAkC,CAAC;AAE5E,MAAM,CAAC,MAAM,2BAA2B,GAAG;IACzC,UAAU;IACV,SAAS;IACT,aAAa;IACb,SAAS;IACT,MAAM;CACsC,CAAC;AAO/C,MAAM,UAAU,yBAAyB;IACvC,OAAO;QACL,WAAW,EAAE,yBAAyB;QACtC,cAAc,EAAE,2BAA2B;KAC5C,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,yBAAyB,CAAC,IAAY;IACpD,OAAO,2BAA2B,CAAC,IAAI,CAAC,CAAC,aAAa,EAAE,EAAE,CAAC,aAAa,KAAK,IAAI,CAAC,CAAC;AACrF,CAAC;AAED,MAAM,UAAU,iBAAiB,CAAC,MAAwB;IACxD,OAAO,MAAM,CAAC,IAAI,CAAC;AACrB,CAAC","sourcesContent":["import type { DataSourceConfig, DataSourceKind } from '@ankhorage/contracts/data';\n\nexport * from './graphql';\nexport * from './managed-api';\nexport * from './openapi';\nexport * from './rest';\nexport * from './test-runner';\n\nexport const DATA_SOURCES_PACKAGE_NAME = '@ankhorage/data-sources' as const;\n\nexport const SUPPORTED_DATA_SOURCE_KINDS = [\n  'database',\n  'graphql',\n  'managed-api',\n  'openapi',\n  'rest',\n] as const satisfies readonly DataSourceKind[];\n\nexport interface DataSourcesPackageInfo {\n  readonly packageName: typeof DATA_SOURCES_PACKAGE_NAME;\n  readonly supportedKinds: typeof SUPPORTED_DATA_SOURCE_KINDS;\n}\n\nexport function getDataSourcesPackageInfo(): DataSourcesPackageInfo {\n  return {\n    packageName: DATA_SOURCES_PACKAGE_NAME,\n    supportedKinds: SUPPORTED_DATA_SOURCE_KINDS,\n  };\n}\n\nexport function isSupportedDataSourceKind(kind: string): kind is DataSourceKind {\n  return SUPPORTED_DATA_SOURCE_KINDS.some((supportedKind) => supportedKind === kind);\n}\n\nexport function getDataSourceKind(source: DataSourceConfig): DataSourceKind {\n  return source.kind;\n}\n"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAEA,cAAc,aAAa,CAAC;AAC5B,cAAc,WAAW,CAAC;AAC1B,cAAc,eAAe,CAAC;AAC9B,cAAc,WAAW,CAAC;AAC1B,cAAc,QAAQ,CAAC;AACvB,cAAc,eAAe,CAAC;AAE9B,MAAM,CAAC,MAAM,yBAAyB,GAAG,yBAAkC,CAAC;AAE5E,MAAM,CAAC,MAAM,2BAA2B,GAAG;IACzC,UAAU;IACV,SAAS;IACT,aAAa;IACb,SAAS;IACT,MAAM;CACsC,CAAC;AAO/C,MAAM,UAAU,yBAAyB;IACvC,OAAO;QACL,WAAW,EAAE,yBAAyB;QACtC,cAAc,EAAE,2BAA2B;KAC5C,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,yBAAyB,CAAC,IAAY;IACpD,OAAO,2BAA2B,CAAC,IAAI,CAAC,CAAC,aAAa,EAAE,EAAE,CAAC,aAAa,KAAK,IAAI,CAAC,CAAC;AACrF,CAAC;AAED,MAAM,UAAU,iBAAiB,CAAC,MAAwB;IACxD,OAAO,MAAM,CAAC,IAAI,CAAC;AACrB,CAAC","sourcesContent":["import type { DataSourceConfig, DataSourceKind } from '@ankhorage/contracts/data';\n\nexport * from './discovery';\nexport * from './graphql';\nexport * from './managed-api';\nexport * from './openapi';\nexport * from './rest';\nexport * from './test-runner';\n\nexport const DATA_SOURCES_PACKAGE_NAME = '@ankhorage/data-sources' as const;\n\nexport const SUPPORTED_DATA_SOURCE_KINDS = [\n  'database',\n  'graphql',\n  'managed-api',\n  'openapi',\n  'rest',\n] as const satisfies readonly DataSourceKind[];\n\nexport interface DataSourcesPackageInfo {\n  readonly packageName: typeof DATA_SOURCES_PACKAGE_NAME;\n  readonly supportedKinds: typeof SUPPORTED_DATA_SOURCE_KINDS;\n}\n\nexport function getDataSourcesPackageInfo(): DataSourcesPackageInfo {\n  return {\n    packageName: DATA_SOURCES_PACKAGE_NAME,\n    supportedKinds: SUPPORTED_DATA_SOURCE_KINDS,\n  };\n}\n\nexport function isSupportedDataSourceKind(kind: string): kind is DataSourceKind {\n  return SUPPORTED_DATA_SOURCE_KINDS.some((supportedKind) => supportedKind === kind);\n}\n\nexport function getDataSourceKind(source: DataSourceConfig): DataSourceKind {\n  return source.kind;\n}\n"]}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ankhorage/data-sources",
   "type": "module",
-  "version": "0.5.5",
+  "version": "0.6.0",
   "description": "Headless toolkit for importing, generating, normalizing, and testing Ankhorage data-source configs.",
   "homepage": "https://github.com/ankhorage/data-sources#readme",
   "bugs": {
@@ -25,7 +25,7 @@
     "typescript"
   ],
   "dependencies": {
-    "@ankhorage/contracts": "^1.18.3"
+    "@ankhorage/contracts": "^4.0.1"
   },
   "ankh": {
     "category": "data-sources",

package/src/discovery/index.test.ts

@@ -0,0 +1,209 @@
+import { describe, expect, it } from 'bun:test';
+
+import {
+  createOpenApiDiscoveryCandidates,
+  discoverOpenApiDataSource,
+  type ExternalApiFetch,
+  type ExternalApiFetchInit,
+  type ExternalApiFetchResponse,
+  introspectGraphQlDataSource,
+} from './index';
+
+function jsonResponse(value: unknown, status = 200): ExternalApiFetchResponse {
+  return {
+    status,
+    text: () => Promise.resolve(JSON.stringify(value)),
+  };
+}
+
+function createOpenApiDocument() {
+  return {
+    openapi: '3.1.0',
+    info: { title: 'Inventory API', version: '1.0.0' },
+    servers: [{ url: 'https://api.example.com' }],
+    paths: {
+      '/items': {
+        get: {
+          operationId: 'listItems',
+          responses: {
+            '200': {
+              description: 'Items',
+              content: {
+                'application/json': {
+                  schema: { type: 'array', items: { type: 'string' } },
+                },
+              },
+            },
+          },
+        },
+      },
+    },
+  } as const;
+}
+
+function createGraphQlPayload() {
+  return {
+    data: {
+      __schema: {
+        queryType: { name: 'Query' },
+        mutationType: null,
+        subscriptionType: null,
+        types: [
+          {
+            kind: 'OBJECT',
+            name: 'Query',
+            fields: [
+              {
+                name: 'items',
+                args: [],
+                type: {
+                  kind: 'LIST',
+                  name: null,
+                  ofType: { kind: 'SCALAR', name: 'String' },
+                },
+              },
+            ],
+          },
+        ],
+      },
+    },
+  } as const;
+}
+
+describe('external API discovery', () => {
+  it('creates direct, service-relative, and origin-relative OpenAPI candidates', () => {
+    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(candidates).toContain('https://api.example.com/service/v3/api-docs');
+    expect(candidates).toContain('https://api.example.com/v3/api-docs');
+  });
+
+  it('rejects non-http URLs and URLs containing inline credentials', () => {
+    expect(createOpenApiDiscoveryCandidates('file:///tmp/openapi.json')).toEqual([]);
+    expect(
+      createOpenApiDiscoveryCandidates('https://user:secret@example.com/openapi.json'),
+    ).toEqual([]);
+  });
+
+  it('imports a directly supplied OpenAPI document URL', async () => {
+    const calls: string[] = [];
+    const fetch: ExternalApiFetch = (url) => {
+      calls.push(url);
+      return Promise.resolve(jsonResponse(createOpenApiDocument()));
+    };
+
+    const result = await discoverOpenApiDataSource({
+      id: 'inventory',
+      url: 'https://api.example.com/openapi.json',
+      fetch,
+    });
+
+    expect(result.ok).toBe(true);
+    expect(calls).toEqual(['https://api.example.com/openapi.json']);
+    if (result.ok) {
+      expect(result.documentUrl).toBe('https://api.example.com/openapi.json');
+      expect(result.data.kind).toBe('openapi');
+      expect(result.data.endpoints.items?.operations.listitems?.intent).toBe('read');
+      expect(result.attempts).toEqual([
+        {
+          url: 'https://api.example.com/openapi.json',
+          outcome: 'matched',
+          status: 200,
+        },
+      ]);
+    }
+  });
+
+  it('falls back to a conventional OpenAPI location', async () => {
+    const calls: string[] = [];
+    const fetch: ExternalApiFetch = (url) => {
+      calls.push(url);
+      return Promise.resolve(
+        url === 'https://api.example.com/service/openapi.json'
+          ? jsonResponse(createOpenApiDocument())
+          : jsonResponse({ message: 'not a schema' }, 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',
+    ]);
+    if (result.ok) {
+      expect(result.documentUrl).toBe('https://api.example.com/service/openapi.json');
+      expect(result.attempts.map((attempt) => attempt.outcome)).toEqual(['http-error', 'matched']);
+    }
+  });
+
+  it('returns safe diagnostics when no OpenAPI document can be discovered', async () => {
+    const fetch: ExternalApiFetch = () =>
+      Promise.resolve(jsonResponse({ error: 'private detail' }, 404));
+    const result = await discoverOpenApiDataSource({
+      id: 'missing',
+      url: 'https://api.example.com',
+      conventionalPaths: [],
+      fetch,
+    });
+
+    expect(result.ok).toBe(false);
+    expect(result.diagnostics[0]).toMatchObject({
+      code: 'missing-schema',
+      dataSourceId: 'missing',
+      severity: 'error',
+    });
+    expect(JSON.stringify(result)).not.toContain('private detail');
+  });
+
+  it('executes GraphQL introspection and normalizes discovered operations', async () => {
+    let capturedInit: ExternalApiFetchInit | undefined;
+    const fetch: ExternalApiFetch = (_url, init) => {
+      capturedInit = init;
+      return Promise.resolve(jsonResponse(createGraphQlPayload()));
+    };
+
+    const result = await introspectGraphQlDataSource({
+      id: 'catalog',
+      endpointUrl: 'https://api.example.com/graphql',
+      headers: { authorization: 'Bearer server-only' },
+      fetch,
+    });
+
+    expect(result.ok).toBe(true);
+    expect(capturedInit?.method).toBe('POST');
+    expect(capturedInit?.body).toContain('AnkhorageGraphQlIntrospection');
+    if (result.ok) {
+      expect(result.data.kind).toBe('graphql');
+      expect(result.data.endpoints.graphql?.operations['query.items']).toBeDefined();
+      expect(JSON.stringify(result)).not.toContain('server-only');
+    }
+  });
+
+  it('reports GraphQL transport and response-shape failures without response bodies', async () => {
+    const httpFailure = await introspectGraphQlDataSource({
+      id: 'catalog',
+      endpointUrl: 'https://api.example.com/graphql',
+      fetch: () => Promise.resolve(jsonResponse({ secret: 'hidden' }, 403)),
+    });
+    expect(httpFailure).toMatchObject({ ok: false, status: 403 });
+    expect(JSON.stringify(httpFailure)).not.toContain('hidden');
+
+    const shapeFailure = await introspectGraphQlDataSource({
+      id: 'catalog',
+      endpointUrl: 'https://api.example.com/graphql',
+      fetch: () => Promise.resolve(jsonResponse({ data: {} })),
+    });
+    expect(shapeFailure.ok).toBe(false);
+    expect(shapeFailure.diagnostics[0]?.code).toBe('parse-error');
+  });
+});

package/src/discovery/index.ts

@@ -0,0 +1,353 @@
+import type {
+  CredentialRef,
+  DataContractValue,
+  DataSourceDiagnostic,
+  GraphQlDataSourceConfig,
+  OpenApiDataSourceConfig,
+} from '@ankhorage/contracts/data';
+
+import {
+  createGraphQlDataSource,
+  createGraphQlIntrospectionRequest,
+  type GraphQlIntrospectionResult,
+} from '../graphql';
+import { importOpenApiDocument, type OpenApiDocumentObject } from '../openapi';
+
+export const DEFAULT_OPENAPI_DISCOVERY_PATHS = [
+  'openapi.json',
+  'swagger.json',
+  'api/openapi.json',
+  'v3/api-docs',
+] as const;
+
+export interface ExternalApiFetchInit {
+  readonly method: 'GET' | 'POST';
+  readonly headers: Readonly<Record<string, string>>;
+  readonly body?: string;
+}
+
+export interface ExternalApiFetchResponse {
+  readonly status: number;
+  text(): Promise<string>;
+}
+
+export type ExternalApiFetch = (
+  url: string,
+  init: ExternalApiFetchInit,
+) => Promise<ExternalApiFetchResponse>;
+
+export type OpenApiDiscoveryAttemptOutcome =
+  | 'http-error'
+  | 'invalid-document'
+  | 'matched'
+  | 'network-error'
+  | 'parse-error'
+  | 'unsupported-document';
+
+export interface OpenApiDiscoveryAttempt {
+  readonly url: string;
+  readonly outcome: OpenApiDiscoveryAttemptOutcome;
+  readonly status?: number;
+}
+
+export interface DiscoverOpenApiDataSourceInput {
+  readonly id: string;
+  readonly url: string;
+  readonly fetch: ExternalApiFetch;
+  readonly baseUrl?: string;
+  readonly credential?: CredentialRef;
+  readonly name?: string;
+  readonly description?: string;
+  readonly metadata?: DataContractValue;
+  readonly conventionalPaths?: readonly string[];
+}
+
+export type DiscoverOpenApiDataSourceResult =
+  | {
+      readonly ok: true;
+      readonly data: OpenApiDataSourceConfig;
+      readonly documentUrl: string;
+      readonly attempts: readonly OpenApiDiscoveryAttempt[];
+      readonly diagnostics: readonly DataSourceDiagnostic[];
+    }
+  | {
+      readonly ok: false;
+      readonly attempts: readonly OpenApiDiscoveryAttempt[];
+      readonly diagnostics: readonly DataSourceDiagnostic[];
+    };
+
+export interface IntrospectGraphQlDataSourceInput {
+  readonly id: string;
+  readonly endpointUrl: string;
+  readonly fetch: ExternalApiFetch;
+  readonly headers?: Readonly<Record<string, string>>;
+  readonly credential?: CredentialRef;
+  readonly name?: string;
+  readonly description?: string;
+  readonly schemaVersion?: string;
+  readonly metadata?: DataContractValue;
+}
+
+export type IntrospectGraphQlDataSourceResult =
+  | {
+      readonly ok: true;
+      readonly data: GraphQlDataSourceConfig;
+      readonly diagnostics: readonly DataSourceDiagnostic[];
+    }
+  | {
+      readonly ok: false;
+      readonly diagnostics: readonly DataSourceDiagnostic[];
+      readonly status?: number;
+    };
+
+export function createOpenApiDiscoveryCandidates(
+  rawUrl: string,
+  conventionalPaths: readonly string[] = DEFAULT_OPENAPI_DISCOVERY_PATHS,
+): readonly string[] {
+  const parsed = parseHttpUrl(rawUrl);
+  if (parsed === undefined) return [];
+
+  const exact = normalizeCandidateUrl(parsed);
+  const serviceBase = new URL(exact);
+  if (!serviceBase.pathname.endsWith('/')) serviceBase.pathname = `${serviceBase.pathname}/`;
+
+  const candidates = [exact];
+  for (const path of conventionalPaths) {
+    const normalizedPath = path.replace(/^\/+/, '');
+    candidates.push(normalizeCandidateUrl(new URL(normalizedPath, serviceBase)));
+    candidates.push(normalizeCandidateUrl(new URL(normalizedPath, `${parsed.origin}/`)));
+  }
+
+  return [...new Set(candidates)];
+}
+
+export async function discoverOpenApiDataSource(
+  input: DiscoverOpenApiDataSourceInput,
+): Promise<DiscoverOpenApiDataSourceResult> {
+  const candidates = createOpenApiDiscoveryCandidates(input.url, input.conventionalPaths);
+  if (candidates.length === 0) {
+    return discoveryFailure(input.id, [], 'OpenAPI discovery requires a valid HTTP or HTTPS URL.');
+  }
+
+  const attempts: OpenApiDiscoveryAttempt[] = [];
+  for (const candidate of candidates) {
+    const probed = await probeOpenApiCandidate(input, candidate);
+    attempts.push(probed.attempt);
+    if (probed.result !== undefined) {
+      return probed.result.ok
+        ? {
+            ok: true,
+            data: probed.result.data,
+            documentUrl: candidate,
+            attempts,
+            diagnostics: probed.result.diagnostics ?? [],
+          }
+        : { ok: false, attempts, diagnostics: probed.result.diagnostics };
+    }
+  }
+
+  return discoveryFailure(
+    input.id,
+    attempts,
+    'No supported OpenAPI document was found at the supplied URL or conventional locations.',
+  );
+}
+
+export async function introspectGraphQlDataSource(
+  input: IntrospectGraphQlDataSourceInput,
+): Promise<IntrospectGraphQlDataSourceResult> {
+  const endpoint = parseHttpUrl(input.endpointUrl);
+  if (endpoint === undefined) {
+    return graphqlFailure(input.id, 'GraphQL introspection requires a valid HTTP or HTTPS URL.');
+  }
+
+  const request = createGraphQlIntrospectionRequest();
+  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(request),
+    });
+  } catch {
+    return graphqlFailure(input.id, 'GraphQL introspection request failed.', 'network-error');
+  }
+
+  if (!isSuccessfulStatus(response.status)) {
+    return {
+      ...graphqlFailure(
+        input.id,
+        `GraphQL introspection returned HTTP status ${response.status}.`,
+        'network-error',
+      ),
+      status: response.status,
+    };
+  }
+
+  const parsed = await parseJsonResponse(response);
+  const introspection = readGraphQlIntrospection(parsed);
+  if (introspection === undefined) {
+    return graphqlFailure(
+      input.id,
+      'GraphQL introspection response did not contain data.__schema.',
+      'parse-error',
+    );
+  }
+
+  const result = createGraphQlDataSource({
+    id: input.id,
+    endpointUrl: normalizeCandidateUrl(endpoint),
+    credential: input.credential,
+    name: input.name,
+    description: input.description,
+    introspection,
+    introspectionEnabled: true,
+    schemaVersion: input.schemaVersion,
+    metadata: input.metadata,
+  });
+
+  return result.ok
+    ? { ok: true, data: result.data, diagnostics: result.diagnostics ?? [] }
+    : { ok: false, diagnostics: result.diagnostics };
+}
+
+interface OpenApiProbeResult {
+  readonly attempt: OpenApiDiscoveryAttempt;
+  readonly result?: ReturnType<typeof importOpenApiDocument>;
+}
+
+async function probeOpenApiCandidate(
+  input: DiscoverOpenApiDataSourceInput,
+  candidate: string,
+): Promise<OpenApiProbeResult> {
+  let response: ExternalApiFetchResponse;
+  try {
+    response = await input.fetch(candidate, {
+      method: 'GET',
+      headers: {
+        accept: 'application/json, application/vnd.oai.openapi+json',
+      },
+    });
+  } catch {
+    return { attempt: { url: candidate, outcome: 'network-error' } };
+  }
+
+  if (!isSuccessfulStatus(response.status)) {
+    return {
+      attempt: { url: candidate, outcome: 'http-error', status: response.status },
+    };
+  }
+
+  const parsed = await parseJsonResponse(response);
+  if (parsed === undefined) {
+    return {
+      attempt: { url: candidate, outcome: 'parse-error', status: response.status },
+    };
+  }
+
+  if (!isOpenApiDocument(parsed)) {
+    return {
+      attempt: { url: candidate, outcome: 'unsupported-document', status: response.status },
+    };
+  }
+
+  const result = importOpenApiDocument({
+    id: input.id,
+    document: parsed,
+    baseUrl: input.baseUrl,
+    credential: input.credential,
+    documentUrl: candidate,
+    name: input.name,
+    description: input.description,
+    metadata: input.metadata,
+  });
+
+  return {
+    attempt: {
+      url: candidate,
+      outcome: result.ok ? 'matched' : 'invalid-document',
+      status: response.status,
+    },
+    result,
+  };
+}
+
+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 (
+    record !== undefined &&
+    typeof record.openapi === 'string' &&
+    readRecord(record.paths) !== undefined
+  );
+}
+
+function readGraphQlIntrospection(value: unknown): GraphQlIntrospectionResult | undefined {
+  const payload = readRecord(value);
+  const data = readRecord(payload?.data);
+  if (readRecord(data?.__schema) === undefined) return undefined;
+  return data;
+}
+
+function isRecord(value: unknown): value is Readonly<Record<string, unknown>> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function readRecord(value: unknown): Readonly<Record<string, unknown>> | undefined {
+  return isRecord(value) ? value : undefined;
+}
+
+function discoveryFailure(
+  dataSourceId: string,
+  attempts: readonly OpenApiDiscoveryAttempt[],
+  message: string,
+): DiscoverOpenApiDataSourceResult {
+  return {
+    ok: false,
+    attempts,
+    diagnostics: [{ code: 'missing-schema', dataSourceId, message, severity: 'error' }],
+  };
+}
+
+function graphqlFailure(
+  dataSourceId: string,
+  message: string,
+  code: DataSourceDiagnostic['code'] = 'invalid-config',
+): Extract<IntrospectGraphQlDataSourceResult, { readonly ok: false }> {
+  return {
+    ok: false,
+    diagnostics: [{ code, dataSourceId, message, severity: 'error' }],
+  };
+}

package/src/index.ts

@@ -1,5 +1,6 @@
 import type { DataSourceConfig, DataSourceKind } from '@ankhorage/contracts/data';
 
+export * from './discovery';
 export * from './graphql';
 export * from './managed-api';
 export * from './openapi';