@ankhorage/data-sources 0.0.0 → 0.1.0

package/dist/rest/index.js

@@ -0,0 +1,158 @@
+const REST_METHODS = ['DELETE', 'GET', 'HEAD', 'OPTIONS', 'PATCH', 'POST', 'PUT'];
+export function isManualRestMethod(method) {
+    return REST_METHODS.some((restMethod) => restMethod === method);
+}
+export function normalizeManualRestMethod(method) {
+    return method.toUpperCase();
+}
+export function extractRestPathParams(path) {
+    const params = new Set();
+    const bracedParamPattern = /\{([A-Za-z_][A-Za-z0-9_]*)\}/g;
+    const colonParamPattern = /(^|\/):([A-Za-z_][A-Za-z0-9_]*)/g;
+    for (const match of path.matchAll(bracedParamPattern)) {
+        const [, param] = match;
+        if (param !== undefined)
+            params.add(param);
+    }
+    for (const match of path.matchAll(colonParamPattern)) {
+        const [, , param] = match;
+        if (param !== undefined)
+            params.add(param);
+    }
+    return [...params];
+}
+export function validateManualRestDataSource(definition) {
+    const diagnostics = [];
+    if (definition.baseUrl.trim().length === 0) {
+        diagnostics.push({
+            code: 'invalid-config',
+            dataSourceId: definition.id,
+            message: 'Manual REST data source requires a non-empty baseUrl.',
+            path: 'baseUrl',
+            severity: 'error',
+        });
+    }
+    for (const endpoint of definition.endpoints) {
+        if (!endpoint.path.startsWith('/')) {
+            diagnostics.push({
+                code: 'invalid-config',
+                dataSourceId: definition.id,
+                endpointId: endpoint.id,
+                message: 'Manual REST endpoint paths must start with `/`.',
+                path: `endpoints.${endpoint.id}.path`,
+                severity: 'error',
+            });
+        }
+        for (const operation of endpoint.operations) {
+            const normalizedMethod = normalizeManualRestMethod(operation.method);
+            const operationPath = operation.path ?? endpoint.path;
+            const templateParams = extractRestPathParams(operationPath);
+            const pathParameters = operation.parameters?.filter((parameter) => parameter.location === 'path') ?? [];
+            const pathParameterNames = new Set(pathParameters.map((parameter) => parameter.name));
+            if (!isManualRestMethod(normalizedMethod)) {
+                diagnostics.push({
+                    code: 'invalid-config',
+                    dataSourceId: definition.id,
+                    endpointId: endpoint.id,
+                    operationId: operation.id,
+                    message: `Manual REST operation method must be one of ${REST_METHODS.join(', ')}.`,
+                    path: `endpoints.${endpoint.id}.operations.${operation.id}.method`,
+                    severity: 'error',
+                });
+            }
+            for (const templateParam of templateParams) {
+                if (!pathParameterNames.has(templateParam)) {
+                    diagnostics.push({
+                        code: 'invalid-config',
+                        dataSourceId: definition.id,
+                        endpointId: endpoint.id,
+                        operationId: operation.id,
+                        message: `Path template parameter '${templateParam}' must have a matching path parameter definition.`,
+                        path: `endpoints.${endpoint.id}.operations.${operation.id}.parameters`,
+                        severity: 'error',
+                    });
+                }
+            }
+            for (const pathParameter of pathParameters) {
+                if (!templateParams.includes(pathParameter.name)) {
+                    diagnostics.push({
+                        code: 'invalid-config',
+                        dataSourceId: definition.id,
+                        endpointId: endpoint.id,
+                        operationId: operation.id,
+                        message: `Path parameter '${pathParameter.name}' is not referenced by the operation path template.`,
+                        path: `endpoints.${endpoint.id}.operations.${operation.id}.parameters.${pathParameter.name}`,
+                        severity: 'error',
+                    });
+                }
+            }
+        }
+    }
+    return diagnostics;
+}
+export function createManualRestDataSource(definition) {
+    const diagnostics = validateManualRestDataSource(definition);
+    const hasErrors = diagnostics.some((diagnostic) => diagnostic.severity === 'error');
+    if (hasErrors) {
+        return { ok: false, diagnostics };
+    }
+    return {
+        ok: true,
+        data: normalizeManualRestDataSource(definition),
+        diagnostics,
+    };
+}
+export function normalizeManualRestDataSource(definition) {
+    const endpoints = {};
+    for (const endpoint of definition.endpoints) {
+        const operations = {};
+        for (const operation of endpoint.operations) {
+            const operationPath = operation.path ?? endpoint.path;
+            const { parameters } = operation;
+            const request = operation.request === undefined && parameters === undefined
+                ? undefined
+                : {
+                    ...operation.request,
+                    parameters,
+                };
+            operations[operation.id] = {
+                id: operation.id,
+                endpointId: endpoint.id,
+                name: operation.name,
+                description: operation.description,
+                protocol: 'http',
+                intent: operation.intent,
+                method: normalizeManualRestMethod(operation.method),
+                path: operationPath,
+                request,
+                response: operation.response,
+                pagination: operation.pagination,
+                credential: operation.credential,
+                metadata: operation.metadata,
+            };
+        }
+        endpoints[endpoint.id] = {
+            id: endpoint.id,
+            kind: 'http',
+            name: endpoint.name,
+            description: endpoint.description,
+            baseUrl: definition.baseUrl,
+            path: endpoint.path,
+            credential: endpoint.credential,
+            operations,
+            metadata: endpoint.metadata,
+        };
+    }
+    return {
+        id: definition.id,
+        kind: 'rest',
+        name: definition.name,
+        description: definition.description,
+        baseUrl: definition.baseUrl,
+        credential: definition.credential,
+        endpoints,
+        schemas: definition.schemas,
+        metadata: definition.metadata,
+    };
+}
+//# sourceMappingURL=index.js.map

package/dist/rest/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/rest/index.ts"],"names":[],"mappings":"AAmBA,MAAM,YAAY,GAAG,CAAC,QAAQ,EAAE,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,CAAU,CAAC;AAwC3F,MAAM,UAAU,kBAAkB,CAAC,MAAc;IAC/C,OAAO,YAAY,CAAC,IAAI,CAAC,CAAC,UAAU,EAAE,EAAE,CAAC,UAAU,KAAK,MAAM,CAAC,CAAC;AAClE,CAAC;AAED,MAAM,UAAU,yBAAyB,CAAC,MAAc;IACtD,OAAO,MAAM,CAAC,WAAW,EAAE,CAAC;AAC9B,CAAC;AAED,MAAM,UAAU,qBAAqB,CAAC,IAAY;IAChD,MAAM,MAAM,GAAG,IAAI,GAAG,EAAU,CAAC;IACjC,MAAM,kBAAkB,GAAG,+BAA+B,CAAC;IAC3D,MAAM,iBAAiB,GAAG,kCAAkC,CAAC;IAE7D,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,QAAQ,CAAC,kBAAkB,CAAC,EAAE,CAAC;QACtD,MAAM,CAAC,EAAE,KAAK,CAAC,GAAG,KAAK,CAAC;QACxB,IAAI,KAAK,KAAK,SAAS;YAAE,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;IAC7C,CAAC;IAED,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,QAAQ,CAAC,iBAAiB,CAAC,EAAE,CAAC;QACrD,MAAM,CAAC,EAAE,AAAD,EAAG,KAAK,CAAC,GAAG,KAAK,CAAC;QAC1B,IAAI,KAAK,KAAK,SAAS;YAAE,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;IAC7C,CAAC;IAED,OAAO,CAAC,GAAG,MAAM,CAAC,CAAC;AACrB,CAAC;AAED,MAAM,UAAU,4BAA4B,CAC1C,UAA0C;IAE1C,MAAM,WAAW,GAA2B,EAAE,CAAC;IAE/C,IAAI,UAAU,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC3C,WAAW,CAAC,IAAI,CAAC;YACf,IAAI,EAAE,gBAAgB;YACtB,YAAY,EAAE,UAAU,CAAC,EAAE;YAC3B,OAAO,EAAE,uDAAuD;YAChE,IAAI,EAAE,SAAS;YACf,QAAQ,EAAE,OAAO;SAClB,CAAC,CAAC;IACL,CAAC;IAED,KAAK,MAAM,QAAQ,IAAI,UAAU,CAAC,SAAS,EAAE,CAAC;QAC5C,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;YACnC,WAAW,CAAC,IAAI,CAAC;gBACf,IAAI,EAAE,gBAAgB;gBACtB,YAAY,EAAE,UAAU,CAAC,EAAE;gBAC3B,UAAU,EAAE,QAAQ,CAAC,EAAE;gBACvB,OAAO,EAAE,iDAAiD;gBAC1D,IAAI,EAAE,aAAa,QAAQ,CAAC,EAAE,OAAO;gBACrC,QAAQ,EAAE,OAAO;aAClB,CAAC,CAAC;QACL,CAAC;QAED,KAAK,MAAM,SAAS,IAAI,QAAQ,CAAC,UAAU,EAAE,CAAC;YAC5C,MAAM,gBAAgB,GAAG,yBAAyB,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;YACrE,MAAM,aAAa,GAAG,SAAS,CAAC,IAAI,IAAI,QAAQ,CAAC,IAAI,CAAC;YACtD,MAAM,cAAc,GAAG,qBAAqB,CAAC,aAAa,CAAC,CAAC;YAC5D,MAAM,cAAc,GAClB,SAAS,CAAC,UAAU,EAAE,MAAM,CAAC,CAAC,SAAS,EAAE,EAAE,CAAC,SAAS,CAAC,QAAQ,KAAK,MAAM,CAAC,IAAI,EAAE,CAAC;YACnF,MAAM,kBAAkB,GAAG,IAAI,GAAG,CAAC,cAAc,CAAC,GAAG,CAAC,CAAC,SAAS,EAAE,EAAE,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC;YAEtF,IAAI,CAAC,kBAAkB,CAAC,gBAAgB,CAAC,EAAE,CAAC;gBAC1C,WAAW,CAAC,IAAI,CAAC;oBACf,IAAI,EAAE,gBAAgB;oBACtB,YAAY,EAAE,UAAU,CAAC,EAAE;oBAC3B,UAAU,EAAE,QAAQ,CAAC,EAAE;oBACvB,WAAW,EAAE,SAAS,CAAC,EAAE;oBACzB,OAAO,EAAE,+CAA+C,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG;oBAClF,IAAI,EAAE,aAAa,QAAQ,CAAC,EAAE,eAAe,SAAS,CAAC,EAAE,SAAS;oBAClE,QAAQ,EAAE,OAAO;iBAClB,CAAC,CAAC;YACL,CAAC;YAED,KAAK,MAAM,aAAa,IAAI,cAAc,EAAE,CAAC;gBAC3C,IAAI,CAAC,kBAAkB,CAAC,GAAG,CAAC,aAAa,CAAC,EAAE,CAAC;oBAC3C,WAAW,CAAC,IAAI,CAAC;wBACf,IAAI,EAAE,gBAAgB;wBACtB,YAAY,EAAE,UAAU,CAAC,EAAE;wBAC3B,UAAU,EAAE,QAAQ,CAAC,EAAE;wBACvB,WAAW,EAAE,SAAS,CAAC,EAAE;wBACzB,OAAO,EAAE,4BAA4B,aAAa,mDAAmD;wBACrG,IAAI,EAAE,aAAa,QAAQ,CAAC,EAAE,eAAe,SAAS,CAAC,EAAE,aAAa;wBACtE,QAAQ,EAAE,OAAO;qBAClB,CAAC,CAAC;gBACL,CAAC;YACH,CAAC;YAED,KAAK,MAAM,aAAa,IAAI,cAAc,EAAE,CAAC;gBAC3C,IAAI,CAAC,cAAc,CAAC,QAAQ,CAAC,aAAa,CAAC,IAAI,CAAC,EAAE,CAAC;oBACjD,WAAW,CAAC,IAAI,CAAC;wBACf,IAAI,EAAE,gBAAgB;wBACtB,YAAY,EAAE,UAAU,CAAC,EAAE;wBAC3B,UAAU,EAAE,QAAQ,CAAC,EAAE;wBACvB,WAAW,EAAE,SAAS,CAAC,EAAE;wBACzB,OAAO,EAAE,mBAAmB,aAAa,CAAC,IAAI,qDAAqD;wBACnG,IAAI,EAAE,aAAa,QAAQ,CAAC,EAAE,eAAe,SAAS,CAAC,EAAE,eAAe,aAAa,CAAC,IAAI,EAAE;wBAC5F,QAAQ,EAAE,OAAO;qBAClB,CAAC,CAAC;gBACL,CAAC;YACH,CAAC;QACH,CAAC;IACH,CAAC;IAED,OAAO,WAAW,CAAC;AACrB,CAAC;AAED,MAAM,UAAU,0BAA0B,CACxC,UAA0C;IAE1C,MAAM,WAAW,GAAG,4BAA4B,CAAC,UAAU,CAAC,CAAC;IAC7D,MAAM,SAAS,GAAG,WAAW,CAAC,IAAI,CAAC,CAAC,UAAU,EAAE,EAAE,CAAC,UAAU,CAAC,QAAQ,KAAK,OAAO,CAAC,CAAC;IAEpF,IAAI,SAAS,EAAE,CAAC;QACd,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,WAAW,EAAE,CAAC;IACpC,CAAC;IAED,OAAO;QACL,EAAE,EAAE,IAAI;QACR,IAAI,EAAE,6BAA6B,CAAC,UAAU,CAAC;QAC/C,WAAW;KACZ,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,6BAA6B,CAC3C,UAA0C;IAE1C,MAAM,SAAS,GAA2C,EAAE,CAAC;IAE7D,KAAK,MAAM,QAAQ,IAAI,UAAU,CAAC,SAAS,EAAE,CAAC;QAC5C,MAAM,UAAU,GAA6C,EAAE,CAAC;QAEhE,KAAK,MAAM,SAAS,IAAI,QAAQ,CAAC,UAAU,EAAE,CAAC;YAC5C,MAAM,aAAa,GAAG,SAAS,CAAC,IAAI,IAAI,QAAQ,CAAC,IAAI,CAAC;YACtD,MAAM,EAAE,UAAU,EAAE,GAAG,SAAS,CAAC;YACjC,MAAM,OAAO,GACX,SAAS,CAAC,OAAO,KAAK,SAAS,IAAI,UAAU,KAAK,SAAS;gBACzD,CAAC,CAAC,SAAS;gBACX,CAAC,CAAC;oBACE,GAAG,SAAS,CAAC,OAAO;oBACpB,UAAU;iBACX,CAAC;YAER,UAAU,CAAC,SAAS,CAAC,EAAE,CAAC,GAAG;gBACzB,EAAE,EAAE,SAAS,CAAC,EAAE;gBAChB,UAAU,EAAE,QAAQ,CAAC,EAAE;gBACvB,IAAI,EAAE,SAAS,CAAC,IAAI;gBACpB,WAAW,EAAE,SAAS,CAAC,WAAW;gBAClC,QAAQ,EAAE,MAAM;gBAChB,MAAM,EAAE,SAAS,CAAC,MAAM;gBACxB,MAAM,EAAE,yBAAyB,CAAC,SAAS,CAAC,MAAM,CAAC;gBACnD,IAAI,EAAE,aAAa;gBACnB,OAAO;gBACP,QAAQ,EAAE,SAAS,CAAC,QAAQ;gBAC5B,UAAU,EAAE,SAAS,CAAC,UAAU;gBAChC,UAAU,EAAE,SAAS,CAAC,UAAU;gBAChC,QAAQ,EAAE,SAAS,CAAC,QAAQ;aAC7B,CAAC;QACJ,CAAC;QAED,SAAS,CAAC,QAAQ,CAAC,EAAE,CAAC,GAAG;YACvB,EAAE,EAAE,QAAQ,CAAC,EAAE;YACf,IAAI,EAAE,MAAM;YACZ,IAAI,EAAE,QAAQ,CAAC,IAAI;YACnB,WAAW,EAAE,QAAQ,CAAC,WAAW;YACjC,OAAO,EAAE,UAAU,CAAC,OAAO;YAC3B,IAAI,EAAE,QAAQ,CAAC,IAAI;YACnB,UAAU,EAAE,QAAQ,CAAC,UAAU;YAC/B,UAAU;YACV,QAAQ,EAAE,QAAQ,CAAC,QAAQ;SAC5B,CAAC;IACJ,CAAC;IAED,OAAO;QACL,EAAE,EAAE,UAAU,CAAC,EAAE;QACjB,IAAI,EAAE,MAAM;QACZ,IAAI,EAAE,UAAU,CAAC,IAAI;QACrB,WAAW,EAAE,UAAU,CAAC,WAAW;QACnC,OAAO,EAAE,UAAU,CAAC,OAAO;QAC3B,UAAU,EAAE,UAAU,CAAC,UAAU;QACjC,SAAS;QACT,OAAO,EAAE,UAAU,CAAC,OAAO;QAC3B,QAAQ,EAAE,UAAU,CAAC,QAAQ;KAC9B,CAAC;AACJ,CAAC","sourcesContent":["import type {\n  CredentialRef,\n  DataContractValue,\n  DataEndpointConfig,\n  DataOperationConfig,\n  DataOperationIntent,\n  DataOperationMethod,\n  DataOperationPagination,\n  DataOperationParameter,\n  DataOperationRequest,\n  DataOperationResponse,\n  DataSchemaRegistry,\n  DataSourceDiagnostic,\n  DataSourceDiagnosticResult,\n  EndpointId,\n  OperationId,\n  RestDataSourceConfig,\n} from '@ankhorage/contracts/data';\n\nconst REST_METHODS = ['DELETE', 'GET', 'HEAD', 'OPTIONS', 'PATCH', 'POST', 'PUT'] as const;\n\nexport type ManualRestMethod = (typeof REST_METHODS)[number];\n\nexport interface ManualRestOperationDefinition {\n  readonly id: OperationId;\n  readonly intent: DataOperationIntent;\n  readonly method: string;\n  readonly name?: string;\n  readonly description?: string;\n  readonly path?: string;\n  readonly credential?: CredentialRef;\n  readonly parameters?: readonly DataOperationParameter[];\n  readonly request?: DataOperationRequest;\n  readonly response?: DataOperationResponse;\n  readonly pagination?: DataOperationPagination;\n  readonly metadata?: DataContractValue;\n}\n\nexport interface ManualRestEndpointDefinition {\n  readonly id: EndpointId;\n  readonly path: string;\n  readonly name?: string;\n  readonly description?: string;\n  readonly credential?: CredentialRef;\n  readonly operations: readonly ManualRestOperationDefinition[];\n  readonly metadata?: DataContractValue;\n}\n\nexport interface ManualRestDataSourceDefinition {\n  readonly id: string;\n  readonly baseUrl: string;\n  readonly name?: string;\n  readonly description?: string;\n  readonly credential?: CredentialRef;\n  readonly endpoints: readonly ManualRestEndpointDefinition[];\n  readonly schemas?: DataSchemaRegistry;\n  readonly metadata?: DataContractValue;\n}\n\nexport function isManualRestMethod(method: string): method is ManualRestMethod {\n  return REST_METHODS.some((restMethod) => restMethod === method);\n}\n\nexport function normalizeManualRestMethod(method: string): DataOperationMethod {\n  return method.toUpperCase();\n}\n\nexport function extractRestPathParams(path: string): readonly string[] {\n  const params = new Set<string>();\n  const bracedParamPattern = /\\{([A-Za-z_][A-Za-z0-9_]*)\\}/g;\n  const colonParamPattern = /(^|\\/):([A-Za-z_][A-Za-z0-9_]*)/g;\n\n  for (const match of path.matchAll(bracedParamPattern)) {\n    const [, param] = match;\n    if (param !== undefined) params.add(param);\n  }\n\n  for (const match of path.matchAll(colonParamPattern)) {\n    const [, , param] = match;\n    if (param !== undefined) params.add(param);\n  }\n\n  return [...params];\n}\n\nexport function validateManualRestDataSource(\n  definition: ManualRestDataSourceDefinition,\n): readonly DataSourceDiagnostic[] {\n  const diagnostics: DataSourceDiagnostic[] = [];\n\n  if (definition.baseUrl.trim().length === 0) {\n    diagnostics.push({\n      code: 'invalid-config',\n      dataSourceId: definition.id,\n      message: 'Manual REST data source requires a non-empty baseUrl.',\n      path: 'baseUrl',\n      severity: 'error',\n    });\n  }\n\n  for (const endpoint of definition.endpoints) {\n    if (!endpoint.path.startsWith('/')) {\n      diagnostics.push({\n        code: 'invalid-config',\n        dataSourceId: definition.id,\n        endpointId: endpoint.id,\n        message: 'Manual REST endpoint paths must start with `/`.',\n        path: `endpoints.${endpoint.id}.path`,\n        severity: 'error',\n      });\n    }\n\n    for (const operation of endpoint.operations) {\n      const normalizedMethod = normalizeManualRestMethod(operation.method);\n      const operationPath = operation.path ?? endpoint.path;\n      const templateParams = extractRestPathParams(operationPath);\n      const pathParameters =\n        operation.parameters?.filter((parameter) => parameter.location === 'path') ?? [];\n      const pathParameterNames = new Set(pathParameters.map((parameter) => parameter.name));\n\n      if (!isManualRestMethod(normalizedMethod)) {\n        diagnostics.push({\n          code: 'invalid-config',\n          dataSourceId: definition.id,\n          endpointId: endpoint.id,\n          operationId: operation.id,\n          message: `Manual REST operation method must be one of ${REST_METHODS.join(', ')}.`,\n          path: `endpoints.${endpoint.id}.operations.${operation.id}.method`,\n          severity: 'error',\n        });\n      }\n\n      for (const templateParam of templateParams) {\n        if (!pathParameterNames.has(templateParam)) {\n          diagnostics.push({\n            code: 'invalid-config',\n            dataSourceId: definition.id,\n            endpointId: endpoint.id,\n            operationId: operation.id,\n            message: `Path template parameter '${templateParam}' must have a matching path parameter definition.`,\n            path: `endpoints.${endpoint.id}.operations.${operation.id}.parameters`,\n            severity: 'error',\n          });\n        }\n      }\n\n      for (const pathParameter of pathParameters) {\n        if (!templateParams.includes(pathParameter.name)) {\n          diagnostics.push({\n            code: 'invalid-config',\n            dataSourceId: definition.id,\n            endpointId: endpoint.id,\n            operationId: operation.id,\n            message: `Path parameter '${pathParameter.name}' is not referenced by the operation path template.`,\n            path: `endpoints.${endpoint.id}.operations.${operation.id}.parameters.${pathParameter.name}`,\n            severity: 'error',\n          });\n        }\n      }\n    }\n  }\n\n  return diagnostics;\n}\n\nexport function createManualRestDataSource(\n  definition: ManualRestDataSourceDefinition,\n): DataSourceDiagnosticResult<RestDataSourceConfig> {\n  const diagnostics = validateManualRestDataSource(definition);\n  const hasErrors = diagnostics.some((diagnostic) => diagnostic.severity === 'error');\n\n  if (hasErrors) {\n    return { ok: false, diagnostics };\n  }\n\n  return {\n    ok: true,\n    data: normalizeManualRestDataSource(definition),\n    diagnostics,\n  };\n}\n\nexport function normalizeManualRestDataSource(\n  definition: ManualRestDataSourceDefinition,\n): RestDataSourceConfig {\n  const endpoints: Record<EndpointId, DataEndpointConfig> = {};\n\n  for (const endpoint of definition.endpoints) {\n    const operations: Record<OperationId, DataOperationConfig> = {};\n\n    for (const operation of endpoint.operations) {\n      const operationPath = operation.path ?? endpoint.path;\n      const { parameters } = operation;\n      const request: DataOperationRequest | undefined =\n        operation.request === undefined && parameters === undefined\n          ? undefined\n          : {\n              ...operation.request,\n              parameters,\n            };\n\n      operations[operation.id] = {\n        id: operation.id,\n        endpointId: endpoint.id,\n        name: operation.name,\n        description: operation.description,\n        protocol: 'http',\n        intent: operation.intent,\n        method: normalizeManualRestMethod(operation.method),\n        path: operationPath,\n        request,\n        response: operation.response,\n        pagination: operation.pagination,\n        credential: operation.credential,\n        metadata: operation.metadata,\n      };\n    }\n\n    endpoints[endpoint.id] = {\n      id: endpoint.id,\n      kind: 'http',\n      name: endpoint.name,\n      description: endpoint.description,\n      baseUrl: definition.baseUrl,\n      path: endpoint.path,\n      credential: endpoint.credential,\n      operations,\n      metadata: endpoint.metadata,\n    };\n  }\n\n  return {\n    id: definition.id,\n    kind: 'rest',\n    name: definition.name,\n    description: definition.description,\n    baseUrl: definition.baseUrl,\n    credential: definition.credential,\n    endpoints,\n    schemas: definition.schemas,\n    metadata: definition.metadata,\n  };\n}\n"]}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ankhorage/data-sources",
   "type": "module",
-  "version": "0.0.0",
+  "version": "0.1.0",
   "description": "Headless toolkit for importing, generating, normalizing, and testing Ankhorage data-source configs.",
   "homepage": "https://github.com/ankhorage/data-sources#readme",
   "bugs": {

package/src/index.ts

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

package/src/openapi/index.test.ts

@@ -0,0 +1,296 @@
+import { describe, expect, it } from 'bun:test';
+
+import {
+  importOpenApiDocument,
+  normalizeOpenApiEndpointId,
+  normalizeOpenApiOperationId,
+  normalizeOpenApiSchema,
+  type OpenApiDocumentObject,
+} from './index';
+
+function assertSerializable<TValue>(value: TValue): void {
+  expect(JSON.parse(JSON.stringify(value))).toEqual(value);
+}
+
+function createPetStoreDocument(): OpenApiDocumentObject {
+  return {
+    openapi: '3.1.0',
+    info: {
+      title: 'Pet Store',
+      version: '2026-05-19',
+      description: 'Example API.',
+    },
+    servers: [
+      {
+        url: 'https://api.example.com',
+      },
+    ],
+    components: {
+      schemas: {
+        Pet: {
+          type: 'object',
+          required: ['id', 'name'],
+          properties: {
+            id: { type: 'string' },
+            name: { type: 'string' },
+            age: { type: 'integer' },
+          },
+        },
+      },
+    },
+    paths: {
+      '/pets': {
+        get: {
+          operationId: 'listPets',
+          summary: 'List pets',
+          parameters: [
+            {
+              name: 'limit',
+              in: 'query',
+              schema: { type: 'integer', default: 20 },
+            },
+          ],
+          responses: {
+            '200': {
+              description: 'Pets',
+              content: {
+                'application/json': {
+                  schema: {
+                    type: 'array',
+                    items: { $ref: '#/components/schemas/Pet' },
+                  },
+                },
+              },
+            },
+          },
+        },
+        post: {
+          operationId: 'createPet',
+          summary: 'Create pet',
+          requestBody: {
+            required: true,
+            content: {
+              'application/json': {
+                schema: { $ref: '#/components/schemas/Pet' },
+              },
+            },
+          },
+          responses: {
+            '201': {
+              description: 'Created pet',
+              content: {
+                'application/json': {
+                  schema: { $ref: '#/components/schemas/Pet' },
+                },
+              },
+            },
+          },
+        },
+      },
+      '/pets/{petId}': {
+        parameters: [
+          {
+            name: 'petId',
+            in: 'path',
+            required: true,
+            schema: { type: 'string' },
+          },
+        ],
+        get: {
+          operationId: 'getPet',
+          responses: {
+            '200': {
+              description: 'Pet',
+              content: {
+                'application/json': {
+                  schema: { $ref: '#/components/schemas/Pet' },
+                },
+              },
+            },
+          },
+        },
+        patch: {
+          operationId: 'updatePet',
+          requestBody: {
+            content: {
+              'application/json': {
+                schema: { $ref: '#/components/schemas/Pet' },
+              },
+            },
+          },
+          responses: {
+            '200': {
+              description: 'Updated pet',
+              content: {
+                'application/json': {
+                  schema: { $ref: '#/components/schemas/Pet' },
+                },
+              },
+            },
+          },
+        },
+        delete: {
+          operationId: 'deletePet',
+          responses: {
+            '204': {
+              description: 'Deleted pet',
+            },
+          },
+        },
+      },
+    },
+  };
+}
+
+describe('OpenAPI import normalization', () => {
+  it('normalizes deterministic endpoint and operation ids', () => {
+    expect(normalizeOpenApiEndpointId('/pets/{petId}')).toBe('pets-petid');
+    expect(normalizeOpenApiOperationId('get', '/pets/{petId}')).toBe('get-pets-petid');
+    expect(normalizeOpenApiOperationId('get', '/', '')).toBe('get-root');
+  });
+
+  it('normalizes OpenAPI schemas into data schemas', () => {
+    const schema = normalizeOpenApiSchema({
+      type: 'object',
+      properties: {
+        id: { type: 'string' },
+        tags: { type: 'array', items: { type: 'string' } },
+      },
+      required: ['id'],
+    });
+
+    assertSerializable(schema);
+    expect(schema.type).toBe('object');
+    expect(schema.properties?.tags?.items?.type).toBe('string');
+  });
+
+  it('imports a minimal OpenAPI document into a normalized OpenAPI data source', () => {
+    const result = importOpenApiDocument({
+      id: 'pet-store',
+      document: createPetStoreDocument(),
+      documentUrl: 'https://api.example.com/openapi.json',
+      credential: {
+        id: 'pet-store-token',
+        kind: 'bearer',
+      },
+    });
+
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      assertSerializable(result.data);
+      expect(result.data.kind).toBe('openapi');
+      expect(result.data.baseUrl).toBe('https://api.example.com');
+      expect(result.data.import?.version).toBe('2026-05-19');
+      expect(result.data.schemas?.Pet?.properties?.name?.type).toBe('string');
+      expect(result.data.endpoints.pets?.operations.listpets?.intent).toBe('read');
+      expect(result.data.endpoints.pets?.operations.createpet?.intent).toBe('create');
+      expect(
+        result.data.endpoints['pets-petid']?.operations.getpet?.request?.parameters?.[0]?.name,
+      ).toBe('petId');
+      expect(result.data.endpoints['pets-petid']?.operations.updatepet?.intent).toBe('update');
+      expect(result.data.endpoints['pets-petid']?.operations.deletepet?.intent).toBe('delete');
+    }
+  });
+
+  it('uses an explicit baseUrl override and reports ambiguous servers', () => {
+    const document: OpenApiDocumentObject = {
+      ...createPetStoreDocument(),
+      servers: [{ url: 'https://first.example.com' }, { url: 'https://second.example.com' }],
+    };
+    const result = importOpenApiDocument({
+      id: 'pet-store',
+      document,
+      baseUrl: 'https://override.example.com',
+    });
+
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.data.baseUrl).toBe('https://override.example.com');
+      expect(result.diagnostics).toEqual([]);
+    }
+  });
+
+  it('reports ambiguous server diagnostics when no baseUrl override exists', () => {
+    const document: OpenApiDocumentObject = {
+      ...createPetStoreDocument(),
+      servers: [{ url: 'https://first.example.com' }, { url: 'https://second.example.com' }],
+    };
+    const result = importOpenApiDocument({ id: 'pet-store', document });
+
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.data.baseUrl).toBe('https://first.example.com');
+      expect(result.diagnostics?.map((diagnostic) => diagnostic.code)).toContain(
+        'ambiguous-server',
+      );
+    }
+  });
+
+  it('deduplicates duplicate operation IDs deterministically', () => {
+    const document: OpenApiDocumentObject = {
+      openapi: '3.1.0',
+      paths: {
+        '/one': {
+          get: { operationId: 'duplicate', responses: { '200': { description: 'OK' } } },
+        },
+        '/two': {
+          get: { operationId: 'duplicate', responses: { '200': { description: 'OK' } } },
+        },
+      },
+    };
+    const result = importOpenApiDocument({
+      id: 'duplicates',
+      document,
+      baseUrl: 'https://api.example.com',
+    });
+
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.data.endpoints.one?.operations.duplicate?.id).toBe('duplicate');
+      expect(result.data.endpoints.two?.operations['duplicate-2']?.id).toBe('duplicate-2');
+      expect(result.diagnostics?.map((diagnostic) => diagnostic.code)).toContain(
+        'duplicate-operation-id',
+      );
+    }
+  });
+
+  it('returns an error diagnostic when paths are missing', () => {
+    const result = importOpenApiDocument({
+      id: 'empty',
+      document: { openapi: '3.1.0' },
+      baseUrl: 'https://api.example.com',
+    });
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.diagnostics.map((diagnostic) => diagnostic.code)).toContain('invalid-config');
+    }
+  });
+
+  it('reports unsupported schema types as warnings', () => {
+    const result = importOpenApiDocument({
+      id: 'unsupported-schema',
+      baseUrl: 'https://api.example.com',
+      document: {
+        openapi: '3.1.0',
+        components: {
+          schemas: {
+            Weird: { type: 'file' },
+          },
+        },
+        paths: {
+          '/weird': {
+            get: { responses: { '200': { description: 'OK' } } },
+          },
+        },
+      },
+    });
+
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.diagnostics?.map((diagnostic) => diagnostic.code)).toContain(
+        'unsupported-schema',
+      );
+    }
+  });
+});