@ankhorage/data-sources 0.6.0 → 1.0.0

package/src/discovery/index.test.ts

@@ -4,44 +4,28 @@ 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)),
-  };
+  return { status, text: () => Promise.resolve(JSON.stringify(value)) };
 }
 
-function createOpenApiDocument() {
+function openApiDocument() {
   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' } },
-                },
-              },
-            },
-          },
-        },
+        get: { operationId: 'listItems', responses: { '200': { description: 'Items' } } },
       },
     },
   } as const;
 }
 
-function createGraphQlPayload() {
+function graphQlPayload() {
   return {
     data: {
       __schema: {
@@ -56,11 +40,7 @@ function createGraphQlPayload() {
               {
                 name: 'items',
                 args: [],
-                type: {
-                  kind: 'LIST',
-                  name: null,
-                  ofType: { kind: 'SCALAR', name: 'String' },
-                },
+                type: { kind: 'LIST', ofType: { kind: 'SCALAR', name: 'String' } },
               },
             ],
           },
@@ -71,139 +51,83 @@ function createGraphQlPayload() {
 }
 
 describe('external API discovery', () => {
-  it('creates direct, service-relative, and origin-relative OpenAPI candidates', () => {
+  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(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()));
-    };
-
+  it('discovers OpenAPI into an external REST source', async () => {
     const result = await discoverOpenApiDataSource({
       id: 'inventory',
       url: 'https://api.example.com/openapi.json',
-      fetch,
+      fetch: () => Promise.resolve(jsonResponse(openApiDocument())),
     });
-
     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,
-        },
-      ]);
+      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('falls back to a conventional OpenAPI location', async () => {
+  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 === 'https://api.example.com/service/openapi.json'
-          ? jsonResponse(createOpenApiDocument())
-          : jsonResponse({ message: 'not a schema' }, 404),
+        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',
     ]);
-    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');
+    expect(JSON.stringify(result)).not.toContain('hidden');
   });
 
-  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()));
-    };
-
+  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,
+      fetch: () => Promise.resolve(jsonResponse(graphQlPayload())),
     });
-
     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).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('reports GraphQL transport and response-shape failures without response bodies', async () => {
-    const httpFailure = await introspectGraphQlDataSource({
+  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)),
     });
-    expect(httpFailure).toMatchObject({ ok: false, status: 403 });
-    expect(JSON.stringify(httpFailure)).not.toContain('hidden');
-
-    const shapeFailure = await introspectGraphQlDataSource({
+    const shape = 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');
+    expect(http).toMatchObject({ ok: false, status: 403 });
+    expect(JSON.stringify(http)).not.toContain('hidden');
+    expect(shape.ok).toBe(false);
   });
 });

package/src/discovery/index.ts

@@ -2,8 +2,8 @@ import type {
   CredentialRef,
   DataContractValue,
   DataSourceDiagnostic,
-  GraphQlDataSourceConfig,
-  OpenApiDataSourceConfig,
+  ExternalGraphQlApiDataSourceConfig,
+  ExternalRestApiDataSourceConfig,
 } from '@ankhorage/contracts/data';
 
 import {
@@ -65,7 +65,7 @@ export interface DiscoverOpenApiDataSourceInput {
 export type DiscoverOpenApiDataSourceResult =
   | {
       readonly ok: true;
-      readonly data: OpenApiDataSourceConfig;
+      readonly data: ExternalRestApiDataSourceConfig;
       readonly documentUrl: string;
       readonly attempts: readonly OpenApiDiscoveryAttempt[];
       readonly diagnostics: readonly DataSourceDiagnostic[];
@@ -91,7 +91,7 @@ export interface IntrospectGraphQlDataSourceInput {
 export type IntrospectGraphQlDataSourceResult =
   | {
       readonly ok: true;
-      readonly data: GraphQlDataSourceConfig;
+      readonly data: ExternalGraphQlApiDataSourceConfig;
       readonly diagnostics: readonly DataSourceDiagnostic[];
     }
   | {
@@ -133,17 +133,16 @@ export async function discoverOpenApiDataSource(
   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 };
-    }
+    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(
@@ -161,7 +160,6 @@ export async function introspectGraphQlDataSource(
     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), {
@@ -171,7 +169,7 @@ export async function introspectGraphQlDataSource(
         'content-type': 'application/json',
         ...(input.headers ?? {}),
       },
-      body: JSON.stringify(request),
+      body: JSON.stringify(createGraphQlIntrospectionRequest()),
     });
   } catch {
     return graphqlFailure(input.id, 'GraphQL introspection request failed.', 'network-error');
@@ -188,8 +186,7 @@ export async function introspectGraphQlDataSource(
     };
   }
 
-  const parsed = await parseJsonResponse(response);
-  const introspection = readGraphQlIntrospection(parsed);
+  const introspection = readGraphQlIntrospection(await parseJsonResponse(response));
   if (introspection === undefined) {
     return graphqlFailure(
       input.id,
@@ -228,27 +225,20 @@ async function probeOpenApiCandidate(
   try {
     response = await input.fetch(candidate, {
       method: 'GET',
-      headers: {
-        accept: 'application/json, application/vnd.oai.openapi+json',
-      },
+      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 },
-    };
+    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 },
-    };
+    return { attempt: { url: candidate, outcome: 'parse-error', status: response.status } };
   }
-
   if (!isOpenApiDocument(parsed)) {
     return {
       attempt: { url: candidate, outcome: 'unsupported-document', status: response.status },
@@ -265,7 +255,6 @@ async function probeOpenApiCandidate(
     description: input.description,
     metadata: input.metadata,
   });
-
   return {
     attempt: {
       url: candidate,
@@ -321,12 +310,10 @@ function readGraphQlIntrospection(value: unknown): GraphQlIntrospectionResult |
   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;
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+    ? (value as Readonly<Record<string, unknown>>)
+    : undefined;
 }
 
 function discoveryFailure(

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',
+      );
     }
   });
 });