@ankhorage/data-sources 0.0.0 → 0.2.0

package/src/graphql/index.test.ts

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

package/src/graphql/index.ts

@@ -0,0 +1,486 @@
+import type {
+  CredentialRef,
+  DataContractValue,
+  DataEndpointConfig,
+  DataOperationConfig,
+  DataOperationIntent,
+  DataOperationResponse,
+  DataSchema,
+  DataSchemaRegistry,
+  DataSourceDiagnostic,
+  DataSourceDiagnosticResult,
+  GraphQlDataSourceConfig,
+  OperationId,
+} from '@ankhorage/contracts/data';
+
+export const GRAPHQL_INTROSPECTION_QUERY = `query AnkhorageGraphQlIntrospection {
+  __schema {
+    queryType { name }
+    mutationType { name }
+    subscriptionType { name }
+    types {
+      kind
+      name
+      description
+      fields {
+        name
+        description
+        args {
+          name
+          description
+          type { kind name ofType { kind name ofType { kind name ofType { kind name } } } }
+          defaultValue
+        }
+        type { kind name ofType { kind name ofType { kind name ofType { kind name } } } }
+      }
+      inputFields {
+        name
+        description
+        type { kind name ofType { kind name ofType { kind name ofType { kind name } } } }
+        defaultValue
+      }
+      enumValues { name description }
+      possibleTypes { kind name }
+    }
+  }
+}`;
+
+export type GraphQlOperationKind = 'mutation' | 'query' | 'subscription';
+
+type DataContractRecord = Record<string, DataContractValue>;
+
+export interface GraphQlIntrospectionTypeRef {
+  readonly kind: string;
+  readonly name?: string | null;
+  readonly ofType?: GraphQlIntrospectionTypeRef | null;
+}
+
+export interface GraphQlIntrospectionInputValue {
+  readonly name: string;
+  readonly description?: string | null;
+  readonly type: GraphQlIntrospectionTypeRef;
+  readonly defaultValue?: string | null;
+}
+
+export interface GraphQlIntrospectionField {
+  readonly name: string;
+  readonly description?: string | null;
+  readonly args?: readonly GraphQlIntrospectionInputValue[] | null;
+  readonly type: GraphQlIntrospectionTypeRef;
+}
+
+export interface GraphQlIntrospectionEnumValue {
+  readonly name: string;
+  readonly description?: string | null;
+}
+
+export interface GraphQlIntrospectionType {
+  readonly kind: string;
+  readonly name?: string | null;
+  readonly description?: string | null;
+  readonly fields?: readonly GraphQlIntrospectionField[] | null;
+  readonly inputFields?: readonly GraphQlIntrospectionInputValue[] | null;
+  readonly enumValues?: readonly GraphQlIntrospectionEnumValue[] | null;
+  readonly possibleTypes?: readonly GraphQlIntrospectionTypeRef[] | null;
+}
+
+export interface GraphQlIntrospectionSchema {
+  readonly queryType?: { readonly name?: string | null } | null;
+  readonly mutationType?: { readonly name?: string | null } | null;
+  readonly subscriptionType?: { readonly name?: string | null } | null;
+  readonly types?: readonly GraphQlIntrospectionType[] | null;
+}
+
+export interface GraphQlIntrospectionResult {
+  readonly __schema?: GraphQlIntrospectionSchema;
+}
+
+export interface GraphQlOperationDefinition {
+  readonly id: OperationId;
+  readonly kind: GraphQlOperationKind;
+  readonly name?: string;
+  readonly description?: string;
+  readonly document?: string;
+  readonly variables?: DataSchema;
+  readonly response?: DataSchema;
+  readonly selectionPath?: string;
+  readonly metadata?: DataContractValue;
+}
+
+export interface GraphQlDataSourceDefinition {
+  readonly id: string;
+  readonly endpointUrl: string;
+  readonly name?: string;
+  readonly description?: string;
+  readonly credential?: CredentialRef;
+  readonly introspection?: GraphQlIntrospectionResult;
+  readonly introspectionEnabled?: boolean;
+  readonly schemaVersion?: string;
+  readonly operations?: readonly GraphQlOperationDefinition[];
+  readonly metadata?: DataContractValue;
+}
+
+export interface GraphQlIntrospectionRequest {
+  readonly query: typeof GRAPHQL_INTROSPECTION_QUERY;
+  readonly operationName: 'AnkhorageGraphQlIntrospection';
+}
+
+export function createGraphQlIntrospectionRequest(): GraphQlIntrospectionRequest {
+  return {
+    query: GRAPHQL_INTROSPECTION_QUERY,
+    operationName: 'AnkhorageGraphQlIntrospection',
+  };
+}
+
+export function normalizeGraphQlOperationId(kind: GraphQlOperationKind, name: string): OperationId {
+  const normalizedName = name
+    .replace(/[^A-Za-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .toLowerCase();
+
+  return normalizedName.length > 0 ? `${kind}.${normalizedName}` : `${kind}.operation`;
+}
+
+export function createGraphQlDataSource(
+  definition: GraphQlDataSourceDefinition,
+): DataSourceDiagnosticResult<GraphQlDataSourceConfig> {
+  const diagnostics = validateGraphQlDataSource(definition);
+  const hasErrors = diagnostics.some((diagnostic) => diagnostic.severity === 'error');
+
+  if (hasErrors) return { ok: false, diagnostics };
+
+  return {
+    ok: true,
+    data: normalizeGraphQlDataSource(definition),
+    diagnostics,
+  };
+}
+
+export function validateGraphQlDataSource(
+  definition: GraphQlDataSourceDefinition,
+): readonly DataSourceDiagnostic[] {
+  const diagnostics: DataSourceDiagnostic[] = [];
+
+  if (definition.endpointUrl.trim().length === 0) {
+    diagnostics.push({
+      code: 'invalid-config',
+      dataSourceId: definition.id,
+      message: 'GraphQL data source requires a non-empty endpointUrl.',
+      path: 'endpointUrl',
+      severity: 'error',
+    });
+  }
+
+  if (definition.introspectionEnabled === false && definition.introspection !== undefined) {
+    diagnostics.push({
+      code: 'invalid-config',
+      dataSourceId: definition.id,
+      message: 'GraphQL introspection data was provided while introspection is disabled.',
+      path: 'introspection',
+      severity: 'warning',
+    });
+  }
+
+  if (definition.introspectionEnabled !== false && definition.introspection === undefined) {
+    diagnostics.push({
+      code: 'missing-schema',
+      dataSourceId: definition.id,
+      message:
+        'GraphQL introspection result was not provided. Manual operations can still be used.',
+      path: 'introspection',
+      severity: 'info',
+    });
+  }
+
+  return diagnostics;
+}
+
+export function normalizeGraphQlDataSource(
+  definition: GraphQlDataSourceDefinition,
+): GraphQlDataSourceConfig {
+  const schemas = normalizeGraphQlIntrospectionSchemas(definition.introspection);
+  const introspectionOperations = normalizeGraphQlIntrospectionOperations(definition.introspection);
+  const manualOperations = definition.operations ?? [];
+  const operations: Record<OperationId, DataOperationConfig> = {};
+
+  for (const operation of [...introspectionOperations, ...manualOperations]) {
+    operations[operation.id] = normalizeGraphQlOperation(operation);
+  }
+
+  const endpoint: DataEndpointConfig = {
+    id: 'graphql',
+    kind: 'graphql',
+    baseUrl: definition.endpointUrl,
+    credential: definition.credential,
+    operations,
+    metadata: {
+      source: 'graphql',
+    },
+  };
+
+  return {
+    id: definition.id,
+    kind: 'graphql',
+    name: definition.name,
+    description: definition.description,
+    endpointUrl: definition.endpointUrl,
+    credential: definition.credential,
+    endpoints: {
+      graphql: endpoint,
+    },
+    schemas,
+    introspection: {
+      enabled: definition.introspectionEnabled ?? definition.introspection !== undefined,
+      schemaVersion: definition.schemaVersion,
+    },
+    metadata: definition.metadata,
+  };
+}
+
+export function normalizeGraphQlIntrospectionSchemas(
+  introspection: GraphQlIntrospectionResult | undefined,
+): DataSchemaRegistry | undefined {
+  const types = introspection?.__schema?.types?.filter(isNamedGraphQlType) ?? [];
+  if (types.length === 0) return undefined;
+
+  const schemas: Record<string, DataSchema> = {};
+
+  for (const type of types) {
+    if (type.name === undefined || type.name === null || type.name.startsWith('__')) continue;
+    schemas[type.name] = normalizeGraphQlType(type);
+  }
+
+  return schemas;
+}
+
+export function normalizeGraphQlIntrospectionOperations(
+  introspection: GraphQlIntrospectionResult | undefined,
+): readonly GraphQlOperationDefinition[] {
+  const schema = introspection?.__schema;
+  if (schema === undefined) return [];
+
+  const types = schema.types?.filter(isNamedGraphQlType) ?? [];
+  const operations: GraphQlOperationDefinition[] = [];
+
+  appendRootOperations(operations, 'query', schema.queryType?.name, types);
+  appendRootOperations(operations, 'mutation', schema.mutationType?.name, types);
+  appendRootOperations(operations, 'subscription', schema.subscriptionType?.name, types);
+
+  return operations;
+}
+
+function appendRootOperations(
+  operations: GraphQlOperationDefinition[],
+  kind: GraphQlOperationKind,
+  rootTypeName: string | null | undefined,
+  types: readonly GraphQlIntrospectionType[],
+): void {
+  if (rootTypeName === undefined || rootTypeName === null) return;
+
+  const rootType = types.find((type) => type.name === rootTypeName);
+  for (const field of rootType?.fields ?? []) {
+    operations.push({
+      id: normalizeGraphQlOperationId(kind, field.name),
+      kind,
+      name: field.name,
+      description: field.description ?? undefined,
+      variables: normalizeGraphQlVariablesSchema(field.args ?? []),
+      response: normalizeGraphQlTypeRef(field.type),
+      selectionPath: `$.data.${field.name}`,
+      metadata: {
+        rootType: rootTypeName,
+        source: 'introspection',
+      },
+    });
+  }
+}
+
+function normalizeGraphQlOperation(operation: GraphQlOperationDefinition): DataOperationConfig {
+  const response: DataOperationResponse | undefined =
+    operation.response === undefined
+      ? undefined
+      : {
+          schema: operation.response,
+        };
+
+  return {
+    id: operation.id,
+    endpointId: 'graphql',
+    name: operation.name,
+    description: operation.description,
+    protocol: 'graphql',
+    intent: mapGraphQlOperationKindToIntent(operation.kind),
+    request: {
+      schema: operation.variables,
+    },
+    response,
+    metadata: createGraphQlOperationMetadata(operation),
+  };
+}
+
+function mapGraphQlOperationKindToIntent(kind: GraphQlOperationKind): DataOperationIntent {
+  if (kind === 'query' || kind === 'subscription') return 'read';
+  return 'action';
+}
+
+function normalizeGraphQlVariablesSchema(
+  args: readonly GraphQlIntrospectionInputValue[],
+): DataSchema {
+  const properties: Record<string, DataSchema> = {};
+  const required: string[] = [];
+
+  for (const arg of args) {
+    properties[arg.name] = {
+      ...normalizeGraphQlTypeRef(arg.type),
+      description: arg.description ?? undefined,
+      default: arg.defaultValue ?? undefined,
+    };
+    if (isGraphQlNonNull(arg.type)) required.push(arg.name);
+  }
+
+  return {
+    type: 'object',
+    required: required.length > 0 ? required : undefined,
+    properties,
+  };
+}
+
+function normalizeGraphQlType(type: GraphQlIntrospectionType): DataSchema {
+  if (type.kind === 'OBJECT' || type.kind === 'INTERFACE' || type.kind === 'INPUT_OBJECT') {
+    return normalizeGraphQlObjectType(type);
+  }
+
+  if (type.kind === 'ENUM') {
+    return {
+      type: 'string',
+      title: type.name ?? undefined,
+      description: type.description ?? undefined,
+      enum: type.enumValues?.map((value) => value.name),
+    };
+  }
+
+  if (type.kind === 'SCALAR') {
+    return {
+      ...normalizeGraphQlNamedScalar(type.name),
+      title: type.name ?? undefined,
+      description: type.description ?? undefined,
+    };
+  }
+
+  if (type.kind === 'UNION') {
+    return {
+      title: type.name ?? undefined,
+      description: type.description ?? undefined,
+      anyOf: type.possibleTypes?.map((possibleType) => normalizeGraphQlTypeRef(possibleType)),
+    };
+  }
+
+  return {
+    title: type.name ?? undefined,
+    description: type.description ?? undefined,
+  };
+}
+
+function normalizeGraphQlObjectType(type: GraphQlIntrospectionType): DataSchema {
+  const fields = type.kind === 'INPUT_OBJECT' ? type.inputFields : type.fields;
+  const properties: Record<string, DataSchema> = {};
+  const required: string[] = [];
+
+  for (const field of fields ?? []) {
+    const fieldType = 'type' in field ? field.type : undefined;
+    if (fieldType === undefined) continue;
+
+    properties[field.name] = {
+      ...normalizeGraphQlTypeRef(fieldType),
+      description: field.description ?? undefined,
+    };
+
+    if (isGraphQlNonNull(fieldType)) required.push(field.name);
+  }
+
+  return {
+    type: 'object',
+    title: type.name ?? undefined,
+    description: type.description ?? undefined,
+    required: required.length > 0 ? required : undefined,
+    properties,
+  };
+}
+
+function normalizeGraphQlTypeRef(type: GraphQlIntrospectionTypeRef): DataSchema {
+  if (type.kind === 'NON_NULL' && type.ofType !== undefined && type.ofType !== null) {
+    return {
+      ...normalizeGraphQlTypeRef(type.ofType),
+      nullable: false,
+    };
+  }
+
+  if (type.kind === 'LIST' && type.ofType !== undefined && type.ofType !== null) {
+    return {
+      type: 'array',
+      items: normalizeGraphQlTypeRef(type.ofType),
+    };
+  }
+
+  if (type.kind === 'SCALAR') {
+    return normalizeGraphQlNamedScalar(type.name);
+  }
+
+  if (type.name !== undefined && type.name !== null) {
+    return { ref: { id: type.name } };
+  }
+
+  return {};
+}
+
+function normalizeGraphQlNamedScalar(name: string | null | undefined): DataSchema {
+  if (name === 'Boolean') return { type: 'boolean' };
+  if (name === 'Float') return { type: 'number' };
+  if (name === 'ID' || name === 'String') return { type: 'string' };
+  if (name === 'Int') return { type: 'integer' };
+
+  return {
+    type: 'string',
+    format: name ?? undefined,
+  };
+}
+
+function isGraphQlNonNull(type: GraphQlIntrospectionTypeRef): boolean {
+  return type.kind === 'NON_NULL';
+}
+
+function isNamedGraphQlType(type: GraphQlIntrospectionType): boolean {
+  return type.name !== undefined && type.name !== null;
+}
+
+function createGraphQlOperationMetadata(operation: GraphQlOperationDefinition): DataContractRecord {
+  const metadata = toMetadataRecord(operation.metadata);
+  metadata.kind = operation.kind;
+
+  if (operation.document !== undefined) {
+    metadata.document = operation.document;
+  }
+
+  if (operation.selectionPath !== undefined) {
+    metadata.selectionPath = operation.selectionPath;
+  }
+
+  return metadata;
+}
+
+function toMetadataRecord(value: DataContractValue | undefined): DataContractRecord {
+  if (!isDataContractRecord(value)) return {};
+
+  const metadata: DataContractRecord = {};
+  for (const [key, item] of Object.entries(value)) {
+    metadata[key] = item;
+  }
+
+  return metadata;
+}
+
+function isDataContractRecord(value: DataContractValue | undefined): value is DataContractRecord {
+  return (
+    value !== undefined && typeof value === 'object' && value !== null && !Array.isArray(value)
+  );
+}

package/src/index.ts

@@ -1,5 +1,9 @@
 import type { DataSourceConfig, DataSourceKind } from '@ankhorage/contracts/data';
 
+export * from './graphql';
+export * from './openapi';
+export * from './rest';
+
 export const DATA_SOURCES_PACKAGE_NAME = '@ankhorage/data-sources' as const;
 
 export const SUPPORTED_DATA_SOURCE_KINDS = [