@ankhorage/data-sources 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @ankhorage/data-sources
 
+## 0.3.0
+
+### Minor Changes
+
+- f4266e8: Add managed API generation helpers that derive normalized database endpoint and CRUD operation configs from provider-neutral adapter references and collection definitions.
+
 ## 0.2.0
 
 ### Minor Changes

package/README.md

@@ -3,7 +3,7 @@
 
 # @ankhorage/data-sources
 
-![license: MIT](././paradox/badges/license.svg) ![npm: v0.0.0](././paradox/badges/npm.svg) ![runtime: bun](././paradox/badges/runtime.svg) ![typescript: strict](././paradox/badges/typescript.svg) ![eslint: checked](././paradox/badges/eslint.svg) ![prettier: checked](././paradox/badges/prettier.svg) ![build: checked](././paradox/badges/build.svg) ![tests: checked](././paradox/badges/tests.svg) ![docs: paradox](././paradox/badges/docs.svg)
+![license: MIT](././paradox/badges/license.svg) ![npm: v0.2.0](././paradox/badges/npm.svg) ![runtime: bun](././paradox/badges/runtime.svg) ![typescript: strict](././paradox/badges/typescript.svg) ![eslint: checked](././paradox/badges/eslint.svg) ![prettier: checked](././paradox/badges/prettier.svg) ![build: checked](././paradox/badges/build.svg) ![tests: checked](././paradox/badges/tests.svg) ![docs: paradox](././paradox/badges/docs.svg)
 
 Provider-neutral data source and endpoint system for APIs, databases, and runtime bindings.
 
@@ -15,11 +15,13 @@ Provider-neutral data source and endpoint system for APIs, databases, and runtim
 - [Architecture overview](././paradox/diagrams/architecture-overview.mmd)
 - [Module relationships](././paradox/diagrams/module-relationships.mmd)
 - [Export graph](././paradox/diagrams/export-graph.mmd)
+- [createManagedApiResourceSchema sequence](././paradox/diagrams/sequences/create-managed-api-resource-schema.mmd)
 - [createManualRestDataSource sequence](././paradox/diagrams/sequences/create-manual-rest-data-source.mmd)
 - [normalizeGraphQlIntrospectionOperations sequence](././paradox/diagrams/sequences/normalize-graph-ql-introspection-operations.mmd)
 - [normalizeGraphQlIntrospectionSchemas sequence](././paradox/diagrams/sequences/normalize-graph-ql-introspection-schemas.mmd)
 - [normalizeManualRestDataSource sequence](././paradox/diagrams/sequences/normalize-manual-rest-data-source.mmd)
 - [normalizeOpenApiSchema sequence](././paradox/diagrams/sequences/normalize-open-api-schema.mmd)
+- [validateManagedApiDefinition sequence](././paradox/diagrams/sequences/validate-managed-api-definition.mmd)
 - [validateManualRestDataSource sequence](././paradox/diagrams/sequences/validate-manual-rest-data-source.mmd)
 
 ## Architecture preview
@@ -35,6 +37,8 @@ graph TD
   module_src_graphql_index_ts["src/graphql/index.ts"]
   package__ankhorage_data_sources -.-> module_src_graphql_index_ts
   module_src_index_ts["src/index.ts"]
+  module_src_managed_api_index_ts["src/managed-api/index.ts"]
+  package__ankhorage_data_sources -.-> module_src_managed_api_index_ts
   module_src_openapi_index_ts["src/openapi/index.ts"]
   package__ankhorage_data_sources -.-> module_src_openapi_index_ts
   module_src_rest_index_ts["src/rest/index.ts"]

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 import type { DataSourceConfig, DataSourceKind } from '@ankhorage/contracts/data';
 export * from './graphql';
+export * from './managed-api';
 export * from './openapi';
 export * from './rest';
 export declare const DATA_SOURCES_PACKAGE_NAME: "@ankhorage/data-sources";

package/dist/index.d.ts.map

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

package/dist/index.js

@@ -1,4 +1,5 @@
 export * from './graphql';
+export * from './managed-api';
 export * from './openapi';
 export * from './rest';
 export const DATA_SOURCES_PACKAGE_NAME = '@ankhorage/data-sources';

package/dist/index.js.map

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

package/dist/managed-api/index.d.ts

@@ -0,0 +1,30 @@
+import type { AdapterRef, DataEndpointConfig, DataOperationConfig, DataSchema, DataSourceDiagnostic, DataSourceDiagnosticResult, ManagedApiDataSourceConfig, OperationId } from '@ankhorage/contracts/data';
+import type { DbCollectionDefinition } from '@ankhorage/contracts/db';
+export declare const MANAGED_API_CRUD_OPERATIONS: readonly ["list", "read", "create", "update", "delete"];
+export type ManagedApiCrudOperation = (typeof MANAGED_API_CRUD_OPERATIONS)[number];
+export interface ManagedApiOperationPolicyRef {
+    readonly id: string;
+    readonly operation?: string;
+}
+export interface ManagedApiGenerationResourceDefinition {
+    readonly name: string;
+    readonly collection: DbCollectionDefinition;
+    readonly operations?: readonly ManagedApiCrudOperation[];
+    readonly policies?: readonly ManagedApiOperationPolicyRef[];
+}
+export interface ManagedApiGenerationDefinition {
+    readonly id: string;
+    readonly adapter: AdapterRef;
+    readonly name?: string;
+    readonly description?: string;
+    readonly resources: readonly ManagedApiGenerationResourceDefinition[];
+}
+export declare function createManagedApiDataSource(definition: ManagedApiGenerationDefinition): DataSourceDiagnosticResult<ManagedApiDataSourceConfig>;
+export declare function validateManagedApiDefinition(definition: ManagedApiGenerationDefinition): readonly DataSourceDiagnostic[];
+export declare function normalizeManagedApiDataSource(definition: ManagedApiGenerationDefinition): ManagedApiDataSourceConfig;
+export declare function createManagedApiEndpoint(definition: ManagedApiGenerationDefinition, resource: ManagedApiGenerationResourceDefinition, operations?: readonly ManagedApiCrudOperation[]): DataEndpointConfig;
+export declare function createManagedApiOperation(definition: ManagedApiGenerationDefinition, resource: ManagedApiGenerationResourceDefinition, operation: ManagedApiCrudOperation): DataOperationConfig;
+export declare function getManagedApiOperations(resource: ManagedApiGenerationResourceDefinition): readonly ManagedApiCrudOperation[];
+export declare function createManagedApiOperationId(resourceName: string, operation: ManagedApiCrudOperation): OperationId;
+export declare function createManagedApiResourceSchema(collection: DbCollectionDefinition): DataSchema;
+//# sourceMappingURL=index.d.ts.map

package/dist/managed-api/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/managed-api/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,UAAU,EAEV,kBAAkB,EAClB,mBAAmB,EAGnB,UAAU,EACV,oBAAoB,EACpB,0BAA0B,EAC1B,0BAA0B,EAE1B,WAAW,EACZ,MAAM,2BAA2B,CAAC;AACnC,OAAO,KAAK,EACV,sBAAsB,EAGvB,MAAM,yBAAyB,CAAC;AAEjC,eAAO,MAAM,2BAA2B,yDAA0D,CAAC;AAEnG,MAAM,MAAM,uBAAuB,GAAG,CAAC,OAAO,2BAA2B,CAAC,CAAC,MAAM,CAAC,CAAC;AAEnF,MAAM,WAAW,4BAA4B;IAC3C,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED,MAAM,WAAW,sCAAsC;IACrD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,UAAU,EAAE,sBAAsB,CAAC;IAC5C,QAAQ,CAAC,UAAU,CAAC,EAAE,SAAS,uBAAuB,EAAE,CAAC;IACzD,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,4BAA4B,EAAE,CAAC;CAC7D;AAED,MAAM,WAAW,8BAA8B;IAC7C,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,OAAO,EAAE,UAAU,CAAC;IAC7B,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,SAAS,EAAE,SAAS,sCAAsC,EAAE,CAAC;CACvE;AAED,wBAAgB,0BAA0B,CACxC,UAAU,EAAE,8BAA8B,GACzC,0BAA0B,CAAC,0BAA0B,CAAC,CAWxD;AAED,wBAAgB,4BAA4B,CAC1C,UAAU,EAAE,8BAA8B,GACzC,SAAS,oBAAoB,EAAE,CAsDjC;AAED,wBAAgB,6BAA6B,CAC3C,UAAU,EAAE,8BAA8B,GACzC,0BAA0B,CA6B5B;AAED,wBAAgB,wBAAwB,CACtC,UAAU,EAAE,8BAA8B,EAC1C,QAAQ,EAAE,sCAAsC,EAChD,UAAU,GAAE,SAAS,uBAAuB,EAAsC,GACjF,kBAAkB,CAmBpB;AAED,wBAAgB,yBAAyB,CACvC,UAAU,EAAE,8BAA8B,EAC1C,QAAQ,EAAE,sCAAsC,EAChD,SAAS,EAAE,uBAAuB,GACjC,mBAAmB,CAsBrB;AAED,wBAAgB,uBAAuB,CACrC,QAAQ,EAAE,sCAAsC,GAC/C,SAAS,uBAAuB,EAAE,CAEpC;AAED,wBAAgB,2BAA2B,CACzC,YAAY,EAAE,MAAM,EACpB,SAAS,EAAE,uBAAuB,GACjC,WAAW,CAEb;AAED,wBAAgB,8BAA8B,CAAC,UAAU,EAAE,sBAAsB,GAAG,UAAU,CAe7F"}

package/dist/managed-api/index.js

@@ -0,0 +1,257 @@
+export const MANAGED_API_CRUD_OPERATIONS = ['list', 'read', 'create', 'update', 'delete'];
+export function createManagedApiDataSource(definition) {
+    const diagnostics = validateManagedApiDefinition(definition);
+    const hasErrors = diagnostics.some((diagnostic) => diagnostic.severity === 'error');
+    if (hasErrors)
+        return { ok: false, diagnostics };
+    return {
+        ok: true,
+        data: normalizeManagedApiDataSource(definition),
+        diagnostics,
+    };
+}
+export function validateManagedApiDefinition(definition) {
+    const diagnostics = [];
+    if (definition.resources.length === 0) {
+        diagnostics.push({
+            code: 'invalid-config',
+            dataSourceId: definition.id,
+            message: 'Managed API generation requires at least one resource.',
+            path: 'resources',
+            severity: 'error',
+        });
+    }
+    for (const resource of definition.resources) {
+        if (resource.name.trim().length === 0) {
+            diagnostics.push({
+                code: 'invalid-config',
+                dataSourceId: definition.id,
+                endpointId: resource.name,
+                message: 'Managed API resource names must be non-empty.',
+                path: 'resources.name',
+                severity: 'error',
+            });
+        }
+        if (resource.collection.name.trim().length === 0) {
+            diagnostics.push({
+                code: 'invalid-config',
+                dataSourceId: definition.id,
+                endpointId: resource.name,
+                message: 'Managed API resource collections must have a non-empty name.',
+                path: `resources.${resource.name}.collection.name`,
+                severity: 'error',
+            });
+        }
+        const primaryKey = resolveManagedApiPrimaryKey(resource.collection);
+        if (primaryKey === undefined &&
+            getManagedApiOperations(resource).some((operation) => operation !== 'list')) {
+            diagnostics.push({
+                code: 'invalid-config',
+                dataSourceId: definition.id,
+                endpointId: resource.name,
+                message: 'Managed API resources need a primaryKey field when generating read/create/update/delete operations.',
+                path: `resources.${resource.name}.collection.primaryKey`,
+                severity: 'error',
+            });
+        }
+    }
+    return diagnostics;
+}
+export function normalizeManagedApiDataSource(definition) {
+    const resources = [];
+    const endpoints = {};
+    const schemas = {};
+    for (const resource of definition.resources) {
+        const operations = getManagedApiOperations(resource);
+        const resourceConfig = {
+            name: resource.name,
+            collection: resource.collection,
+            operations,
+            metadata: createManagedApiResourceMetadata(resource),
+        };
+        resources.push(resourceConfig);
+        endpoints[resource.name] = createManagedApiEndpoint(definition, resource, operations);
+        schemas[resource.name] = createManagedApiResourceSchema(resource.collection);
+    }
+    return {
+        id: definition.id,
+        kind: 'managed-api',
+        name: definition.name,
+        description: definition.description,
+        adapter: definition.adapter,
+        resources,
+        endpoints,
+        schemas,
+    };
+}
+export function createManagedApiEndpoint(definition, resource, operations = getManagedApiOperations(resource)) {
+    const operationConfigs = {};
+    for (const operation of operations) {
+        const operationConfig = createManagedApiOperation(definition, resource, operation);
+        operationConfigs[operationConfig.id] = operationConfig;
+    }
+    return {
+        id: resource.name,
+        kind: 'database',
+        operations: operationConfigs,
+        metadata: {
+            adapterId: definition.adapter.id,
+            collection: resource.collection.name,
+            schema: resource.collection.schema ?? null,
+            source: 'managed-api',
+        },
+    };
+}
+export function createManagedApiOperation(definition, resource, operation) {
+    const operationId = createManagedApiOperationId(resource.name, operation);
+    const primaryKey = resolveManagedApiPrimaryKey(resource.collection);
+    const primaryKeyParameter = primaryKey === undefined ? undefined : createPrimaryKeyParameter(primaryKey);
+    return {
+        id: operationId,
+        endpointId: resource.name,
+        name: createManagedApiOperationName(resource.name, operation),
+        protocol: 'database',
+        intent: mapManagedApiOperationIntent(operation),
+        request: createManagedApiOperationRequest(resource.collection, operation, primaryKeyParameter),
+        response: createManagedApiOperationResponse(resource.collection, operation),
+        metadata: {
+            adapterId: definition.adapter.id,
+            collection: resource.collection.name,
+            operation,
+            schema: resource.collection.schema ?? null,
+            source: 'managed-api',
+        },
+    };
+}
+export function getManagedApiOperations(resource) {
+    return resource.operations ?? MANAGED_API_CRUD_OPERATIONS;
+}
+export function createManagedApiOperationId(resourceName, operation) {
+    return `${resourceName}.${operation}`;
+}
+export function createManagedApiResourceSchema(collection) {
+    const properties = {};
+    const required = [];
+    for (const field of collection.fields) {
+        properties[field.name] = createManagedApiFieldSchema(field);
+        if (field.required === true)
+            required.push(field.name);
+    }
+    return {
+        type: 'object',
+        title: collection.name,
+        required: required.length > 0 ? required : undefined,
+        properties,
+    };
+}
+function createManagedApiResourceMetadata(resource) {
+    if (resource.policies === undefined)
+        return undefined;
+    return {
+        policies: resource.policies.map((policy) => {
+            const metadata = {
+                id: policy.id,
+            };
+            if (policy.operation !== undefined) {
+                metadata.operation = policy.operation;
+            }
+            return metadata;
+        }),
+    };
+}
+function createManagedApiOperationName(resourceName, operation) {
+    return `${operation} ${resourceName}`;
+}
+function mapManagedApiOperationIntent(operation) {
+    if (operation === 'list' || operation === 'read')
+        return 'read';
+    if (operation === 'create')
+        return 'create';
+    if (operation === 'update')
+        return 'update';
+    return 'delete';
+}
+function createManagedApiOperationRequest(collection, operation, primaryKeyParameter) {
+    if (operation === 'list') {
+        return {
+            parameters: [
+                {
+                    name: 'limit',
+                    location: 'query',
+                    schema: { type: 'integer' },
+                },
+                {
+                    name: 'offset',
+                    location: 'query',
+                    schema: { type: 'integer' },
+                },
+            ],
+        };
+    }
+    if (operation === 'read' || operation === 'delete') {
+        return primaryKeyParameter === undefined ? undefined : { parameters: [primaryKeyParameter] };
+    }
+    const parameters = operation === 'update' && primaryKeyParameter !== undefined ? [primaryKeyParameter] : undefined;
+    return {
+        parameters,
+        schema: createManagedApiResourceSchema(collection),
+    };
+}
+function createManagedApiOperationResponse(collection, operation) {
+    const resourceSchema = createManagedApiResourceSchema(collection);
+    if (operation === 'list') {
+        return {
+            schema: {
+                type: 'array',
+                items: resourceSchema,
+            },
+        };
+    }
+    if (operation === 'delete') {
+        return {
+            schema: {
+                type: 'object',
+                properties: {
+                    deleted: { type: 'boolean' },
+                },
+            },
+        };
+    }
+    return { schema: resourceSchema };
+}
+function createPrimaryKeyParameter(primaryKey) {
+    return {
+        name: primaryKey,
+        location: 'path',
+        required: true,
+        schema: {
+            type: 'string',
+        },
+    };
+}
+function resolveManagedApiPrimaryKey(collection) {
+    if (collection.primaryKey !== undefined)
+        return collection.primaryKey;
+    return collection.fields.find((field) => field.unique === true)?.name;
+}
+function createManagedApiFieldSchema(field) {
+    const schema = mapDbFieldTypeToDataSchema(field.type);
+    return {
+        ...schema,
+        default: field.defaultValue,
+    };
+}
+function mapDbFieldTypeToDataSchema(type) {
+    if (type === 'boolean')
+        return { type: 'boolean' };
+    if (type === 'datetime')
+        return { type: 'string', format: 'date-time' };
+    if (type === 'json')
+        return { type: 'object' };
+    if (type === 'number')
+        return { type: 'number' };
+    if (type === 'uuid')
+        return { type: 'string', format: 'uuid' };
+    return { type: 'string' };
+}
+//# sourceMappingURL=index.js.map

package/dist/managed-api/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/managed-api/index.ts"],"names":[],"mappings":"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","sourcesContent":["import type {\n  AdapterRef,\n  DataContractValue,\n  DataEndpointConfig,\n  DataOperationConfig,\n  DataOperationIntent,\n  DataOperationParameter,\n  DataSchema,\n  DataSourceDiagnostic,\n  DataSourceDiagnosticResult,\n  ManagedApiDataSourceConfig,\n  ManagedApiResourceConfig,\n  OperationId,\n} from '@ankhorage/contracts/data';\nimport type {\n  DbCollectionDefinition,\n  DbFieldDefinition,\n  DbFieldType,\n} from '@ankhorage/contracts/db';\n\nexport const MANAGED_API_CRUD_OPERATIONS = ['list', 'read', 'create', 'update', 'delete'] as const;\n\nexport type ManagedApiCrudOperation = (typeof MANAGED_API_CRUD_OPERATIONS)[number];\n\nexport interface ManagedApiOperationPolicyRef {\n  readonly id: string;\n  readonly operation?: string;\n}\n\nexport interface ManagedApiGenerationResourceDefinition {\n  readonly name: string;\n  readonly collection: DbCollectionDefinition;\n  readonly operations?: readonly ManagedApiCrudOperation[];\n  readonly policies?: readonly ManagedApiOperationPolicyRef[];\n}\n\nexport interface ManagedApiGenerationDefinition {\n  readonly id: string;\n  readonly adapter: AdapterRef;\n  readonly name?: string;\n  readonly description?: string;\n  readonly resources: readonly ManagedApiGenerationResourceDefinition[];\n}\n\nexport function createManagedApiDataSource(\n  definition: ManagedApiGenerationDefinition,\n): DataSourceDiagnosticResult<ManagedApiDataSourceConfig> {\n  const diagnostics = validateManagedApiDefinition(definition);\n  const hasErrors = diagnostics.some((diagnostic) => diagnostic.severity === 'error');\n\n  if (hasErrors) return { ok: false, diagnostics };\n\n  return {\n    ok: true,\n    data: normalizeManagedApiDataSource(definition),\n    diagnostics,\n  };\n}\n\nexport function validateManagedApiDefinition(\n  definition: ManagedApiGenerationDefinition,\n): readonly DataSourceDiagnostic[] {\n  const diagnostics: DataSourceDiagnostic[] = [];\n\n  if (definition.resources.length === 0) {\n    diagnostics.push({\n      code: 'invalid-config',\n      dataSourceId: definition.id,\n      message: 'Managed API generation requires at least one resource.',\n      path: 'resources',\n      severity: 'error',\n    });\n  }\n\n  for (const resource of definition.resources) {\n    if (resource.name.trim().length === 0) {\n      diagnostics.push({\n        code: 'invalid-config',\n        dataSourceId: definition.id,\n        endpointId: resource.name,\n        message: 'Managed API resource names must be non-empty.',\n        path: 'resources.name',\n        severity: 'error',\n      });\n    }\n\n    if (resource.collection.name.trim().length === 0) {\n      diagnostics.push({\n        code: 'invalid-config',\n        dataSourceId: definition.id,\n        endpointId: resource.name,\n        message: 'Managed API resource collections must have a non-empty name.',\n        path: `resources.${resource.name}.collection.name`,\n        severity: 'error',\n      });\n    }\n\n    const primaryKey = resolveManagedApiPrimaryKey(resource.collection);\n    if (\n      primaryKey === undefined &&\n      getManagedApiOperations(resource).some((operation) => operation !== 'list')\n    ) {\n      diagnostics.push({\n        code: 'invalid-config',\n        dataSourceId: definition.id,\n        endpointId: resource.name,\n        message:\n          'Managed API resources need a primaryKey field when generating read/create/update/delete operations.',\n        path: `resources.${resource.name}.collection.primaryKey`,\n        severity: 'error',\n      });\n    }\n  }\n\n  return diagnostics;\n}\n\nexport function normalizeManagedApiDataSource(\n  definition: ManagedApiGenerationDefinition,\n): ManagedApiDataSourceConfig {\n  const resources: ManagedApiResourceConfig[] = [];\n  const endpoints: Record<string, DataEndpointConfig> = {};\n  const schemas: Record<string, DataSchema> = {};\n\n  for (const resource of definition.resources) {\n    const operations = getManagedApiOperations(resource);\n    const resourceConfig: ManagedApiResourceConfig = {\n      name: resource.name,\n      collection: resource.collection,\n      operations,\n      metadata: createManagedApiResourceMetadata(resource),\n    };\n\n    resources.push(resourceConfig);\n    endpoints[resource.name] = createManagedApiEndpoint(definition, resource, operations);\n    schemas[resource.name] = createManagedApiResourceSchema(resource.collection);\n  }\n\n  return {\n    id: definition.id,\n    kind: 'managed-api',\n    name: definition.name,\n    description: definition.description,\n    adapter: definition.adapter,\n    resources,\n    endpoints,\n    schemas,\n  };\n}\n\nexport function createManagedApiEndpoint(\n  definition: ManagedApiGenerationDefinition,\n  resource: ManagedApiGenerationResourceDefinition,\n  operations: readonly ManagedApiCrudOperation[] = getManagedApiOperations(resource),\n): DataEndpointConfig {\n  const operationConfigs: Record<OperationId, DataOperationConfig> = {};\n\n  for (const operation of operations) {\n    const operationConfig = createManagedApiOperation(definition, resource, operation);\n    operationConfigs[operationConfig.id] = operationConfig;\n  }\n\n  return {\n    id: resource.name,\n    kind: 'database',\n    operations: operationConfigs,\n    metadata: {\n      adapterId: definition.adapter.id,\n      collection: resource.collection.name,\n      schema: resource.collection.schema ?? null,\n      source: 'managed-api',\n    },\n  };\n}\n\nexport function createManagedApiOperation(\n  definition: ManagedApiGenerationDefinition,\n  resource: ManagedApiGenerationResourceDefinition,\n  operation: ManagedApiCrudOperation,\n): DataOperationConfig {\n  const operationId = createManagedApiOperationId(resource.name, operation);\n  const primaryKey = resolveManagedApiPrimaryKey(resource.collection);\n  const primaryKeyParameter =\n    primaryKey === undefined ? undefined : createPrimaryKeyParameter(primaryKey);\n\n  return {\n    id: operationId,\n    endpointId: resource.name,\n    name: createManagedApiOperationName(resource.name, operation),\n    protocol: 'database',\n    intent: mapManagedApiOperationIntent(operation),\n    request: createManagedApiOperationRequest(resource.collection, operation, primaryKeyParameter),\n    response: createManagedApiOperationResponse(resource.collection, operation),\n    metadata: {\n      adapterId: definition.adapter.id,\n      collection: resource.collection.name,\n      operation,\n      schema: resource.collection.schema ?? null,\n      source: 'managed-api',\n    },\n  };\n}\n\nexport function getManagedApiOperations(\n  resource: ManagedApiGenerationResourceDefinition,\n): readonly ManagedApiCrudOperation[] {\n  return resource.operations ?? MANAGED_API_CRUD_OPERATIONS;\n}\n\nexport function createManagedApiOperationId(\n  resourceName: string,\n  operation: ManagedApiCrudOperation,\n): OperationId {\n  return `${resourceName}.${operation}`;\n}\n\nexport function createManagedApiResourceSchema(collection: DbCollectionDefinition): DataSchema {\n  const properties: Record<string, DataSchema> = {};\n  const required: string[] = [];\n\n  for (const field of collection.fields) {\n    properties[field.name] = createManagedApiFieldSchema(field);\n    if (field.required === true) required.push(field.name);\n  }\n\n  return {\n    type: 'object',\n    title: collection.name,\n    required: required.length > 0 ? required : undefined,\n    properties,\n  };\n}\n\nfunction createManagedApiResourceMetadata(\n  resource: ManagedApiGenerationResourceDefinition,\n): DataContractValue | undefined {\n  if (resource.policies === undefined) return undefined;\n\n  return {\n    policies: resource.policies.map((policy) => {\n      const metadata: Record<string, DataContractValue> = {\n        id: policy.id,\n      };\n\n      if (policy.operation !== undefined) {\n        metadata.operation = policy.operation;\n      }\n\n      return metadata;\n    }),\n  };\n}\n\nfunction createManagedApiOperationName(\n  resourceName: string,\n  operation: ManagedApiCrudOperation,\n): string {\n  return `${operation} ${resourceName}`;\n}\n\nfunction mapManagedApiOperationIntent(operation: ManagedApiCrudOperation): DataOperationIntent {\n  if (operation === 'list' || operation === 'read') return 'read';\n  if (operation === 'create') return 'create';\n  if (operation === 'update') return 'update';\n  return 'delete';\n}\n\nfunction createManagedApiOperationRequest(\n  collection: DbCollectionDefinition,\n  operation: ManagedApiCrudOperation,\n  primaryKeyParameter: DataOperationParameter | undefined,\n): DataOperationConfig['request'] {\n  if (operation === 'list') {\n    return {\n      parameters: [\n        {\n          name: 'limit',\n          location: 'query',\n          schema: { type: 'integer' },\n        },\n        {\n          name: 'offset',\n          location: 'query',\n          schema: { type: 'integer' },\n        },\n      ],\n    };\n  }\n\n  if (operation === 'read' || operation === 'delete') {\n    return primaryKeyParameter === undefined ? undefined : { parameters: [primaryKeyParameter] };\n  }\n\n  const parameters =\n    operation === 'update' && primaryKeyParameter !== undefined ? [primaryKeyParameter] : undefined;\n\n  return {\n    parameters,\n    schema: createManagedApiResourceSchema(collection),\n  };\n}\n\nfunction createManagedApiOperationResponse(\n  collection: DbCollectionDefinition,\n  operation: ManagedApiCrudOperation,\n): DataOperationConfig['response'] {\n  const resourceSchema = createManagedApiResourceSchema(collection);\n\n  if (operation === 'list') {\n    return {\n      schema: {\n        type: 'array',\n        items: resourceSchema,\n      },\n    };\n  }\n\n  if (operation === 'delete') {\n    return {\n      schema: {\n        type: 'object',\n        properties: {\n          deleted: { type: 'boolean' },\n        },\n      },\n    };\n  }\n\n  return { schema: resourceSchema };\n}\n\nfunction createPrimaryKeyParameter(primaryKey: string): DataOperationParameter {\n  return {\n    name: primaryKey,\n    location: 'path',\n    required: true,\n    schema: {\n      type: 'string',\n    },\n  };\n}\n\nfunction resolveManagedApiPrimaryKey(collection: DbCollectionDefinition): string | undefined {\n  if (collection.primaryKey !== undefined) return collection.primaryKey;\n  return collection.fields.find((field) => field.unique === true)?.name;\n}\n\nfunction createManagedApiFieldSchema(field: DbFieldDefinition): DataSchema {\n  const schema: DataSchema = mapDbFieldTypeToDataSchema(field.type);\n\n  return {\n    ...schema,\n    default: field.defaultValue,\n  };\n}\n\nfunction mapDbFieldTypeToDataSchema(type: DbFieldType): DataSchema {\n  if (type === 'boolean') return { type: 'boolean' };\n  if (type === 'datetime') return { type: 'string', format: 'date-time' };\n  if (type === 'json') return { type: 'object' };\n  if (type === 'number') return { type: 'number' };\n  if (type === 'uuid') return { type: 'string', format: 'uuid' };\n  return { type: 'string' };\n}\n"]}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ankhorage/data-sources",
   "type": "module",
-  "version": "0.2.0",
+  "version": "0.3.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,6 +1,7 @@
 import type { DataSourceConfig, DataSourceKind } from '@ankhorage/contracts/data';
 
 export * from './graphql';
+export * from './managed-api';
 export * from './openapi';
 export * from './rest';
 

package/src/managed-api/index.test.ts

@@ -0,0 +1,181 @@
+import { describe, expect, it } from 'bun:test';
+
+import {
+  createManagedApiDataSource,
+  createManagedApiOperationId,
+  createManagedApiResourceSchema,
+  getManagedApiOperations,
+  type ManagedApiGenerationDefinition,
+  normalizeManagedApiDataSource,
+} from './index';
+
+function assertSerializable<TValue>(value: TValue): void {
+  expect(JSON.parse(JSON.stringify(value))).toEqual(value);
+}
+
+function createPostsApiDefinition(): ManagedApiGenerationDefinition {
+  return {
+    id: 'posts-api',
+    name: 'Posts API',
+    adapter: {
+      id: 'primary-db',
+      kind: 'database',
+      packageName: '@ankhorage/supabase-db',
+    },
+    resources: [
+      {
+        name: 'posts',
+        collection: {
+          name: 'posts',
+          schema: 'public',
+          primaryKey: 'id',
+          fields: [
+            { name: 'id', type: 'uuid', required: true, unique: true },
+            { name: 'title', type: 'text', required: true },
+            { name: 'published', type: 'boolean', defaultValue: false },
+            { name: 'createdAt', type: 'datetime' },
+            { name: 'metadata', type: 'json' },
+          ],
+        },
+        policies: [{ id: 'posts-policy' }],
+      },
+    ],
+  };
+}
+
+describe('managed API generation helpers', () => {
+  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',
+      ]);
+    }
+  });
+
+  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']);
+    }
+  });
+
+  it('generates list/read/create/update/delete endpoint configs', () => {
+    const source = normalizeManagedApiDataSource(createPostsApiDefinition());
+
+    assertSerializable(source);
+    expect(source.kind).toBe('managed-api');
+    expect(source.adapter.id).toBe('primary-db');
+    expect(source.endpoints.posts?.kind).toBe('database');
+    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());
+
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.data.resources[0]?.name).toBe('posts');
+      expect(result.diagnostics).toEqual([]);
+    }
+  });
+
+  it('supports multiple managed APIs backed by different adapter refs', () => {
+    const postsApi = normalizeManagedApiDataSource(createPostsApiDefinition());
+    const analyticsApi = normalizeManagedApiDataSource({
+      id: 'analytics-api',
+      adapter: {
+        id: 'analytics-db',
+        kind: 'database',
+        packageName: '@ankhorage/postgres-db',
+      },
+      resources: [
+        {
+          name: 'events',
+          operations: ['list'],
+          collection: {
+            name: 'events',
+            primaryKey: 'id',
+            fields: [
+              { name: 'id', type: 'uuid', required: true, unique: true },
+              { name: 'name', type: 'text', required: true },
+            ],
+          },
+        },
+      ],
+    });
+
+    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({
+      id: 'empty-api',
+      adapter: { id: 'db', kind: 'database' },
+      resources: [],
+    });
+    const missingPrimaryKeyResult = createManagedApiDataSource({
+      id: 'broken-api',
+      adapter: { id: 'db', kind: 'database' },
+      resources: [
+        {
+          name: 'posts',
+          collection: {
+            name: 'posts',
+            fields: [{ name: 'title', type: 'text' }],
+          },
+        },
+      ],
+    });
+
+    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',
+      );
+    }
+  });
+});

package/src/managed-api/index.ts

@@ -0,0 +1,364 @@
+import type {
+  AdapterRef,
+  DataContractValue,
+  DataEndpointConfig,
+  DataOperationConfig,
+  DataOperationIntent,
+  DataOperationParameter,
+  DataSchema,
+  DataSourceDiagnostic,
+  DataSourceDiagnosticResult,
+  ManagedApiDataSourceConfig,
+  ManagedApiResourceConfig,
+  OperationId,
+} from '@ankhorage/contracts/data';
+import type {
+  DbCollectionDefinition,
+  DbFieldDefinition,
+  DbFieldType,
+} from '@ankhorage/contracts/db';
+
+export const MANAGED_API_CRUD_OPERATIONS = ['list', 'read', 'create', 'update', 'delete'] as const;
+
+export type ManagedApiCrudOperation = (typeof MANAGED_API_CRUD_OPERATIONS)[number];
+
+export interface ManagedApiOperationPolicyRef {
+  readonly id: string;
+  readonly operation?: string;
+}
+
+export interface ManagedApiGenerationResourceDefinition {
+  readonly name: string;
+  readonly collection: DbCollectionDefinition;
+  readonly operations?: readonly ManagedApiCrudOperation[];
+  readonly policies?: readonly ManagedApiOperationPolicyRef[];
+}
+
+export interface ManagedApiGenerationDefinition {
+  readonly id: string;
+  readonly adapter: AdapterRef;
+  readonly name?: string;
+  readonly description?: string;
+  readonly resources: readonly ManagedApiGenerationResourceDefinition[];
+}
+
+export function createManagedApiDataSource(
+  definition: ManagedApiGenerationDefinition,
+): DataSourceDiagnosticResult<ManagedApiDataSourceConfig> {
+  const diagnostics = validateManagedApiDefinition(definition);
+  const hasErrors = diagnostics.some((diagnostic) => diagnostic.severity === 'error');
+
+  if (hasErrors) return { ok: false, diagnostics };
+
+  return {
+    ok: true,
+    data: normalizeManagedApiDataSource(definition),
+    diagnostics,
+  };
+}
+
+export function validateManagedApiDefinition(
+  definition: ManagedApiGenerationDefinition,
+): readonly DataSourceDiagnostic[] {
+  const diagnostics: DataSourceDiagnostic[] = [];
+
+  if (definition.resources.length === 0) {
+    diagnostics.push({
+      code: 'invalid-config',
+      dataSourceId: definition.id,
+      message: 'Managed API generation requires at least one resource.',
+      path: 'resources',
+      severity: 'error',
+    });
+  }
+
+  for (const resource of definition.resources) {
+    if (resource.name.trim().length === 0) {
+      diagnostics.push({
+        code: 'invalid-config',
+        dataSourceId: definition.id,
+        endpointId: resource.name,
+        message: 'Managed API resource names must be non-empty.',
+        path: 'resources.name',
+        severity: 'error',
+      });
+    }
+
+    if (resource.collection.name.trim().length === 0) {
+      diagnostics.push({
+        code: 'invalid-config',
+        dataSourceId: definition.id,
+        endpointId: resource.name,
+        message: 'Managed API resource collections must have a non-empty name.',
+        path: `resources.${resource.name}.collection.name`,
+        severity: 'error',
+      });
+    }
+
+    const primaryKey = resolveManagedApiPrimaryKey(resource.collection);
+    if (
+      primaryKey === undefined &&
+      getManagedApiOperations(resource).some((operation) => operation !== 'list')
+    ) {
+      diagnostics.push({
+        code: 'invalid-config',
+        dataSourceId: definition.id,
+        endpointId: resource.name,
+        message:
+          'Managed API resources need a primaryKey field when generating read/create/update/delete operations.',
+        path: `resources.${resource.name}.collection.primaryKey`,
+        severity: 'error',
+      });
+    }
+  }
+
+  return diagnostics;
+}
+
+export function normalizeManagedApiDataSource(
+  definition: ManagedApiGenerationDefinition,
+): ManagedApiDataSourceConfig {
+  const resources: ManagedApiResourceConfig[] = [];
+  const endpoints: Record<string, DataEndpointConfig> = {};
+  const schemas: Record<string, DataSchema> = {};
+
+  for (const resource of definition.resources) {
+    const operations = getManagedApiOperations(resource);
+    const resourceConfig: ManagedApiResourceConfig = {
+      name: resource.name,
+      collection: resource.collection,
+      operations,
+      metadata: createManagedApiResourceMetadata(resource),
+    };
+
+    resources.push(resourceConfig);
+    endpoints[resource.name] = createManagedApiEndpoint(definition, resource, operations);
+    schemas[resource.name] = createManagedApiResourceSchema(resource.collection);
+  }
+
+  return {
+    id: definition.id,
+    kind: 'managed-api',
+    name: definition.name,
+    description: definition.description,
+    adapter: definition.adapter,
+    resources,
+    endpoints,
+    schemas,
+  };
+}
+
+export function createManagedApiEndpoint(
+  definition: ManagedApiGenerationDefinition,
+  resource: ManagedApiGenerationResourceDefinition,
+  operations: readonly ManagedApiCrudOperation[] = getManagedApiOperations(resource),
+): DataEndpointConfig {
+  const operationConfigs: Record<OperationId, DataOperationConfig> = {};
+
+  for (const operation of operations) {
+    const operationConfig = createManagedApiOperation(definition, resource, operation);
+    operationConfigs[operationConfig.id] = operationConfig;
+  }
+
+  return {
+    id: resource.name,
+    kind: 'database',
+    operations: operationConfigs,
+    metadata: {
+      adapterId: definition.adapter.id,
+      collection: resource.collection.name,
+      schema: resource.collection.schema ?? null,
+      source: 'managed-api',
+    },
+  };
+}
+
+export function createManagedApiOperation(
+  definition: ManagedApiGenerationDefinition,
+  resource: ManagedApiGenerationResourceDefinition,
+  operation: ManagedApiCrudOperation,
+): DataOperationConfig {
+  const operationId = createManagedApiOperationId(resource.name, operation);
+  const primaryKey = resolveManagedApiPrimaryKey(resource.collection);
+  const primaryKeyParameter =
+    primaryKey === undefined ? undefined : createPrimaryKeyParameter(primaryKey);
+
+  return {
+    id: operationId,
+    endpointId: resource.name,
+    name: createManagedApiOperationName(resource.name, operation),
+    protocol: 'database',
+    intent: mapManagedApiOperationIntent(operation),
+    request: createManagedApiOperationRequest(resource.collection, operation, primaryKeyParameter),
+    response: createManagedApiOperationResponse(resource.collection, operation),
+    metadata: {
+      adapterId: definition.adapter.id,
+      collection: resource.collection.name,
+      operation,
+      schema: resource.collection.schema ?? null,
+      source: 'managed-api',
+    },
+  };
+}
+
+export function getManagedApiOperations(
+  resource: ManagedApiGenerationResourceDefinition,
+): readonly ManagedApiCrudOperation[] {
+  return resource.operations ?? MANAGED_API_CRUD_OPERATIONS;
+}
+
+export function createManagedApiOperationId(
+  resourceName: string,
+  operation: ManagedApiCrudOperation,
+): OperationId {
+  return `${resourceName}.${operation}`;
+}
+
+export function createManagedApiResourceSchema(collection: DbCollectionDefinition): DataSchema {
+  const properties: Record<string, DataSchema> = {};
+  const required: string[] = [];
+
+  for (const field of collection.fields) {
+    properties[field.name] = createManagedApiFieldSchema(field);
+    if (field.required === true) required.push(field.name);
+  }
+
+  return {
+    type: 'object',
+    title: collection.name,
+    required: required.length > 0 ? required : undefined,
+    properties,
+  };
+}
+
+function createManagedApiResourceMetadata(
+  resource: ManagedApiGenerationResourceDefinition,
+): DataContractValue | undefined {
+  if (resource.policies === undefined) return undefined;
+
+  return {
+    policies: resource.policies.map((policy) => {
+      const metadata: Record<string, DataContractValue> = {
+        id: policy.id,
+      };
+
+      if (policy.operation !== undefined) {
+        metadata.operation = policy.operation;
+      }
+
+      return metadata;
+    }),
+  };
+}
+
+function createManagedApiOperationName(
+  resourceName: string,
+  operation: ManagedApiCrudOperation,
+): string {
+  return `${operation} ${resourceName}`;
+}
+
+function mapManagedApiOperationIntent(operation: ManagedApiCrudOperation): DataOperationIntent {
+  if (operation === 'list' || operation === 'read') return 'read';
+  if (operation === 'create') return 'create';
+  if (operation === 'update') return 'update';
+  return 'delete';
+}
+
+function createManagedApiOperationRequest(
+  collection: DbCollectionDefinition,
+  operation: ManagedApiCrudOperation,
+  primaryKeyParameter: DataOperationParameter | undefined,
+): DataOperationConfig['request'] {
+  if (operation === 'list') {
+    return {
+      parameters: [
+        {
+          name: 'limit',
+          location: 'query',
+          schema: { type: 'integer' },
+        },
+        {
+          name: 'offset',
+          location: 'query',
+          schema: { type: 'integer' },
+        },
+      ],
+    };
+  }
+
+  if (operation === 'read' || operation === 'delete') {
+    return primaryKeyParameter === undefined ? undefined : { parameters: [primaryKeyParameter] };
+  }
+
+  const parameters =
+    operation === 'update' && primaryKeyParameter !== undefined ? [primaryKeyParameter] : undefined;
+
+  return {
+    parameters,
+    schema: createManagedApiResourceSchema(collection),
+  };
+}
+
+function createManagedApiOperationResponse(
+  collection: DbCollectionDefinition,
+  operation: ManagedApiCrudOperation,
+): DataOperationConfig['response'] {
+  const resourceSchema = createManagedApiResourceSchema(collection);
+
+  if (operation === 'list') {
+    return {
+      schema: {
+        type: 'array',
+        items: resourceSchema,
+      },
+    };
+  }
+
+  if (operation === 'delete') {
+    return {
+      schema: {
+        type: 'object',
+        properties: {
+          deleted: { type: 'boolean' },
+        },
+      },
+    };
+  }
+
+  return { schema: resourceSchema };
+}
+
+function createPrimaryKeyParameter(primaryKey: string): DataOperationParameter {
+  return {
+    name: primaryKey,
+    location: 'path',
+    required: true,
+    schema: {
+      type: 'string',
+    },
+  };
+}
+
+function resolveManagedApiPrimaryKey(collection: DbCollectionDefinition): string | undefined {
+  if (collection.primaryKey !== undefined) return collection.primaryKey;
+  return collection.fields.find((field) => field.unique === true)?.name;
+}
+
+function createManagedApiFieldSchema(field: DbFieldDefinition): DataSchema {
+  const schema: DataSchema = mapDbFieldTypeToDataSchema(field.type);
+
+  return {
+    ...schema,
+    default: field.defaultValue,
+  };
+}
+
+function mapDbFieldTypeToDataSchema(type: DbFieldType): DataSchema {
+  if (type === 'boolean') return { type: 'boolean' };
+  if (type === 'datetime') return { type: 'string', format: 'date-time' };
+  if (type === 'json') return { type: 'object' };
+  if (type === 'number') return { type: 'number' };
+  if (type === 'uuid') return { type: 'string', format: 'uuid' };
+  return { type: 'string' };
+}