{"_id":"@alkdev/operations","name":"@alkdev/operations","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@alkdev/operations","version":"0.1.0","description":"Typed operations registry, call protocol, and adapters (MCP, OpenAPI)","type":"module","main":"./dist/index.cjs","module":"./dist/index.js","types":"./dist/index.d.ts","exports":{".":{"import":{"types":"./dist/index.d.ts","default":"./dist/index.js"},"require":{"types":"./dist/index.d.cts","default":"./dist/index.cjs"}},"./from-mcp":{"import":{"types":"./dist/from-mcp.d.ts","default":"./dist/from-mcp.js"},"require":{"types":"./dist/from-mcp.d.cts","default":"./dist/from-mcp.cjs"}},"./from-typemap":{"import":{"types":"./dist/from-typemap.d.ts","default":"./dist/from-typemap.js"},"require":{"types":"./dist/from-typemap.d.cts","default":"./dist/from-typemap.cjs"}},"./from-openapi":{"import":{"types":"./dist/from-openapi.d.ts","default":"./dist/from-openapi.js"},"require":{"types":"./dist/from-openapi.d.cts","default":"./dist/from-openapi.cjs"}}},"publishConfig":{"access":"public"},"repository":{"type":"git","url":"git+https://git.alk.dev/alkdev/operations.git"},"homepage":"https://git.alk.dev/alkdev/operations","bugs":{"url":"https://git.alk.dev/alkdev/operations/issues"},"scripts":{"build":"tsup","build:tsc":"tsc --noEmit","test":"vitest run","test:watch":"vitest","test:coverage":"vitest run --coverage","lint":"tsc --noEmit","prepublishOnly":"npm run build"},"keywords":["operations","registry","call-protocol","mcp","openapi","typebox"],"license":"MIT OR Apache-2.0","dependencies":{"@alkdev/pubsub":"^0.1.0","@alkdev/typebox":"^0.34.49","@logtape/logtape":"^2.0.0"},"peerDependencies":{"@alkdev/typemap":"^0.10.0","@modelcontextprotocol/sdk":"^1.0.0"},"peerDependenciesMeta":{"@modelcontextprotocol/sdk":{"optional":true},"@alkdev/typemap":{"optional":true}},"devDependencies":{"@alkdev/typemap":"^0.10.1","@modelcontextprotocol/sdk":"^1.12.1","@types/node":"^22.0.0","@vitest/coverage-v8":"^3.2.4","tsup":"^8.5.1","typescript":"^5.7.0","valibot":"^1.4.0","vitest":"^3.1.0"},"engines":{"node":">=18.0.0"},"gitHead":"1b2114703ae04844c926dbe06989bb30ef036eea","_id":"@alkdev/operations@0.1.0","_nodeVersion":"25.8.1","_npmVersion":"11.11.0","dist":{"integrity":"sha512-01rLA0fAHh0gVvJ3x/3MWZcXdwiojWML5IaKUEHiLZOLE3P64sH1Fkxu1nHGIkuxOx7NF11GzVmoAjlDYfUP3Q==","shasum":"14a7cbd46a5fcb667580c553b4cf4305800c2f5e","tarball":"https://registry.npmjs.org/@alkdev/operations/-/operations-0.1.0.tgz","fileCount":26,"unpackedSize":214830,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIEiVn5dOY0u1cv7ynZa5Yje5SXmyKgSapTDG+MjQtD7DAiEA0NX+zyc7o38jCERKIYKaSzL4Za9LYlhzOTVmFtA27KA="}]},"_npmUser":{"name":"alkdev","email":"admin@alk.dev"},"directories":{},"maintainers":[{"name":"alkdev","email":"admin@alk.dev"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/operations_0.1.0_1779002077048_0.5259676126258479"},"_hasShrinkwrap":false}},"time":{"created":"2026-05-17T07:14:36.925Z","0.1.0":"2026-05-17T07:14:37.225Z","modified":"2026-05-17T07:14:37.424Z"},"maintainers":[{"name":"alkdev","email":"admin@alk.dev"}],"description":"Typed operations registry, call protocol, and adapters (MCP, OpenAPI)","homepage":"https://git.alk.dev/alkdev/operations","keywords":["operations","registry","call-protocol","mcp","openapi","typebox"],"repository":{"type":"git","url":"git+https://git.alk.dev/alkdev/operations.git"},"bugs":{"url":"https://git.alk.dev/alkdev/operations/issues"},"license":"MIT OR Apache-2.0","readme":"# @alkdev/operations\n\nTyped operations registry, call protocol, and adapters (MCP, OpenAPI).\n\nEvery API endpoint, agent action, and tool is an **operation** with a TypeBox schema, access control metadata, and a handler. The registry stores specs and handlers independently. The call protocol provides unified event-based invocation — `call` and `subscribe` use the same events, same `PendingRequestMap`. Adapters generate operations from OpenAPI specs, MCP servers, and filesystem manifests.\n\n## Install\n\n```bash\nnpm install @alkdev/operations\n```\n\nOptional peer dependencies (only if you need them):\n\n```bash\nnpm install @alkdev/typemap       # for Zod/Valibot schema adapters\nnpm install @modelcontextprotocol/sdk  # for MCP client integration\n```\n\n## Quick Start\n\n```ts\nimport { Type } from \"@alkdev/typebox\";\nimport { OperationRegistry, OperationType } from \"@alkdev/operations\";\n\nconst registry = new OperationRegistry();\n\nregistry.register({\n  name: \"create\",\n  namespace: \"task\",\n  version: \"1.0.0\",\n  type: OperationType.MUTATION,\n  description: \"Create a new task\",\n  inputSchema: Type.Object({\n    title: Type.String(),\n    priority: Type.Optional(Type.Union([Type.Literal(\"low\"), Type.Literal(\"high\")])),\n  }),\n  outputSchema: Type.Object({\n    id: Type.String(),\n    title: Type.String(),\n  }),\n  accessControl: { requiredScopes: [\"task:write\"] },\n  handler: async (input) => {\n    return { id: crypto.randomUUID(), title: input.title };\n  },\n});\n\nconst result = await registry.execute(\n  \"task.create\",\n  { title: \"Ship it\", priority: \"high\" },\n  { identity: { id: \"user-1\", scopes: [\"task:write\"] } },\n);\n\nconsole.log(result.data);\n```\n\n## Core Concepts\n\n- **OperationSpec** — serializable descriptor: name, namespace, type, schemas, access control\n- **OperationHandler** — the function that runs when the operation is called\n- **OperationRegistry** — register specs and handlers, execute operations, validate I/O\n- **PendingRequestMap** — event-based call protocol: `call()`, `respond()`, `emitError()`, `abort()`\n- **ResponseEnvelope** — universal result wrapper with transport metadata (`local`, `http`, `mcp`)\n- **buildEnv()** — generate a nested call surface for inter-operation composition\n\n## Entry Points\n\n| Import | Purpose |\n|--------|---------|\n| `@alkdev/operations` | Core: registry, call protocol, envelopes, env, validation, errors, FromSchema |\n| `@alkdev/operations/from-mcp` | MCP client integration (requires `@modelcontextprotocol/sdk`) |\n| `@alkdev/operations/from-openapi` | OpenAPI integration |\n| `@alkdev/operations/from-typemap` | Zod/Valibot schema adapters (requires `@alkdev/typemap`) |\n\n## Guides\n\n| Guide | Topic |\n|-------|-------|\n| [Registry](docs/registry.md) | Defining, registering, and executing operations |\n| [Call Protocol](docs/call-protocol.md) | PendingRequestMap, CallHandler, call/subscribe events |\n| [Subscriptions](docs/subscriptions.md) | Real-time streaming with async generators |\n| [Response Envelopes](docs/response-envelopes.md) | Universal result wrapper and transport metadata |\n| [Access Control](docs/access-control.md) | Scope and resource-based authorization |\n| [Composition](docs/env-and-composition.md) | Inter-operation calls with buildEnv |\n| [Error Handling](docs/errors.md) | CallError, infrastructure codes, mapError |\n| [Adapters](docs/adapters.md) | MCP, OpenAPI, FromSchema, scanner, typemap |\n| [Validation](docs/validation.md) | Schema validation helpers |\n\n## API Reference\n\nFor detailed type signatures, see [docs/architecture/api-surface.md](docs/architecture/api-surface.md).\n\n## License\n\nMIT OR Apache-2.0","readmeFilename":"README.md","_rev":"1-ecedf78e534d326b56ec24dd4012c5d6"}