@ankhorage/data-sources 0.5.5 → 1.0.0

package/src/discovery/index.ts

@@ -0,0 +1,340 @@
+import type {
+  CredentialRef,
+  DataContractValue,
+  DataSourceDiagnostic,
+  ExternalGraphQlApiDataSourceConfig,
+  ExternalRestApiDataSourceConfig,
+} 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: ExternalRestApiDataSourceConfig;
+      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: ExternalGraphQlApiDataSourceConfig;
+      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) continue;
+    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.');
+  }
+
+  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 {
+    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 introspection = readGraphQlIntrospection(await parseJsonResponse(response));
+  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 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,
+  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/{managed-api → generated-api}/index.test.ts

@@ -1,30 +1,34 @@
+import type { GeneratedApiDefinition } from '@ankhorage/contracts/data';
 import { describe, expect, it } from 'bun:test';
 
 import {
-  createManagedApiDataSource,
-  createManagedApiOperationId,
-  createManagedApiResourceSchema,
-  getManagedApiOperations,
-  type ManagedApiGenerationDefinition,
-  normalizeManagedApiDataSource,
+  createGeneratedApiDataSource,
+  createGeneratedApiOperationId,
+  createGeneratedApiResourceSchema,
+  normalizeGeneratedApiDataSource,
 } from './index';
 
 function assertSerializable<TValue>(value: TValue): void {
   expect(JSON.parse(JSON.stringify(value))).toEqual(value);
 }
 
-function createPostsApiDefinition(): ManagedApiGenerationDefinition {
+function createPostsApiDefinition(): GeneratedApiDefinition {
   return {
     id: 'posts-api',
+    protocol: 'rest',
     name: 'Posts API',
-    adapter: {
+    basePath: '/api',
+    database: {
       id: 'primary-db',
       kind: 'database',
       packageName: '@ankhorage/supabase-db',
     },
     resources: [
       {
-        name: 'posts',
+        id: 'posts',
+        name: 'Posts',
+        path: '/posts',
+        operations: ['list', 'read', 'create', 'update', 'delete'],
         collection: {
           name: 'posts',
           schema: 'public',
@@ -37,93 +41,78 @@ function createPostsApiDefinition(): ManagedApiGenerationDefinition {
             { name: 'metadata', type: 'json' },
           ],
         },
+        seed: [{ id: 'seed-1', title: 'Hello' }],
         policies: [{ id: 'posts-policy' }],
       },
     ],
   };
 }
 
-describe('managed API generation helpers', () => {
+describe('generated API normalization', () => {
   it('generates deterministic operation IDs', () => {
-    expect(createManagedApiOperationId('posts', 'list')).toBe('posts.list');
-    expect(createManagedApiOperationId('posts', 'delete')).toBe('posts.delete');
-  });
-
-  it('uses all CRUD operations by default', () => {
-    const [resource] = createPostsApiDefinition().resources;
-
-    expect(resource).toBeDefined();
-    if (resource !== undefined) {
-      expect(getManagedApiOperations(resource)).toEqual([
-        'list',
-        'read',
-        'create',
-        'update',
-        'delete',
-      ]);
-    }
+    expect(createGeneratedApiOperationId('posts', 'list')).toBe('posts.list');
+    expect(createGeneratedApiOperationId('posts', 'delete')).toBe('posts.delete');
   });
 
   it('generates a serializable resource schema from a DB collection', () => {
     const [resource] = createPostsApiDefinition().resources;
-
     expect(resource).toBeDefined();
-    if (resource !== undefined) {
-      const schema = createManagedApiResourceSchema(resource.collection);
-
-      assertSerializable(schema);
-      expect(schema.type).toBe('object');
-      expect(schema.properties?.id?.format).toBe('uuid');
-      expect(schema.properties?.createdAt?.format).toBe('date-time');
-      expect(schema.properties?.metadata?.type).toBe('object');
-      expect(schema.required).toEqual(['id', 'title']);
-    }
+    if (resource === undefined) return;
+
+    const schema = createGeneratedApiResourceSchema(resource.collection);
+    assertSerializable(schema);
+    expect(schema.type).toBe('object');
+    expect(schema.properties?.id?.format).toBe('uuid');
+    expect(schema.properties?.createdAt?.format).toBe('date-time');
+    expect(schema.properties?.metadata?.type).toBe('object');
+    expect(schema.required).toEqual(['id', 'title']);
   });
 
-  it('generates list/read/create/update/delete endpoint configs', () => {
-    const source = normalizeManagedApiDataSource(createPostsApiDefinition());
+  it('normalizes generated REST desired state into canonical API operations', () => {
+    const source = normalizeGeneratedApiDataSource(createPostsApiDefinition());
 
     assertSerializable(source);
-    expect(source.kind).toBe('managed-api');
+    expect(source.kind).toBe('api');
+    expect(source.origin).toBe('generated');
+    expect(source.protocol).toBe('rest');
+    expect(source.generatedApiId).toBe('posts-api');
     expect(source.adapter.id).toBe('primary-db');
     expect(source.endpoints.posts?.kind).toBe('database');
+    expect(source.endpoints.posts?.path).toBe('/posts');
     expect(source.endpoints.posts?.operations['posts.list']?.intent).toBe('read');
-    expect(source.endpoints.posts?.operations['posts.read']?.intent).toBe('read');
     expect(source.endpoints.posts?.operations['posts.create']?.intent).toBe('create');
     expect(source.endpoints.posts?.operations['posts.update']?.intent).toBe('update');
     expect(source.endpoints.posts?.operations['posts.delete']?.intent).toBe('delete');
     expect(source.endpoints.posts?.operations['posts.read']?.request?.parameters?.[0]?.name).toBe(
       'id',
     );
-    expect(
-      source.endpoints.posts?.operations['posts.list']?.request?.parameters?.map(
-        (parameter) => parameter.name,
-      ),
-    ).toEqual(['limit', 'offset']);
   });
 
-  it('creates diagnostic result for valid managed APIs', () => {
-    const result = createManagedApiDataSource(createPostsApiDefinition());
+  it('creates a diagnostic result for valid generated APIs', () => {
+    const result = createGeneratedApiDataSource(createPostsApiDefinition());
 
     expect(result.ok).toBe(true);
     if (result.ok) {
-      expect(result.data.resources[0]?.name).toBe('posts');
+      expect(result.data.endpoints.posts?.operations['posts.list']).toBeDefined();
       expect(result.diagnostics).toEqual([]);
     }
   });
 
-  it('supports multiple managed APIs backed by different adapter refs', () => {
-    const postsApi = normalizeManagedApiDataSource(createPostsApiDefinition());
-    const analyticsApi = normalizeManagedApiDataSource({
+  it('supports multiple generated APIs backed by different database adapters', () => {
+    const postsApi = normalizeGeneratedApiDataSource(createPostsApiDefinition());
+    const analyticsApi = normalizeGeneratedApiDataSource({
       id: 'analytics-api',
-      adapter: {
+      protocol: 'rest',
+      basePath: '/analytics',
+      database: {
         id: 'analytics-db',
         kind: 'database',
         packageName: '@ankhorage/postgres-db',
       },
       resources: [
         {
-          name: 'events',
+          id: 'events',
+          path: '/events',
           operations: ['list'],
           collection: {
             name: 'events',
@@ -138,26 +127,30 @@ describe('managed API generation helpers', () => {
     });
 
     assertSerializable([postsApi, analyticsApi]);
-    expect(postsApi.id).toBe('posts-api');
-    expect(analyticsApi.id).toBe('analytics-api');
     expect(postsApi.adapter.id).toBe('primary-db');
     expect(analyticsApi.adapter.id).toBe('analytics-db');
     expect(analyticsApi.endpoints.events?.operations['events.list']?.intent).toBe('read');
     expect(analyticsApi.endpoints.events?.operations['events.read']).toBeUndefined();
   });
 
-  it('reports missing resources and missing primary key diagnostics', () => {
-    const emptyResult = createManagedApiDataSource({
+  it('reports missing resources, invalid paths and missing primary keys', () => {
+    const emptyResult = createGeneratedApiDataSource({
       id: 'empty-api',
-      adapter: { id: 'db', kind: 'database' },
+      protocol: 'rest',
+      basePath: 'api',
+      database: { id: 'db', kind: 'database' },
       resources: [],
     });
-    const missingPrimaryKeyResult = createManagedApiDataSource({
+    const missingPrimaryKeyResult = createGeneratedApiDataSource({
       id: 'broken-api',
-      adapter: { id: 'db', kind: 'database' },
+      protocol: 'rest',
+      basePath: '/api',
+      database: { id: 'db', kind: 'database' },
       resources: [
         {
-          name: 'posts',
+          id: 'posts',
+          path: 'posts',
+          operations: ['read'],
           collection: {
             name: 'posts',
             fields: [{ name: 'title', type: 'text' }],
@@ -167,15 +160,14 @@ describe('managed API generation helpers', () => {
     });
 
     expect(emptyResult.ok).toBe(false);
-    if (!emptyResult.ok) {
-      expect(emptyResult.diagnostics.map((diagnostic) => diagnostic.path)).toContain('resources');
-    }
-
     expect(missingPrimaryKeyResult.ok).toBe(false);
     if (!missingPrimaryKeyResult.ok) {
       expect(missingPrimaryKeyResult.diagnostics.map((diagnostic) => diagnostic.path)).toContain(
         'resources.posts.collection.primaryKey',
       );
+      expect(missingPrimaryKeyResult.diagnostics.map((diagnostic) => diagnostic.path)).toContain(
+        'resources.posts.path',
+      );
     }
   });
 });