{"_id":"@aaep/typescript-producer","name":"@aaep/typescript-producer","dist-tags":{"latest":"1.0.1"},"versions":{"1.0.1":{"name":"@aaep/typescript-producer","version":"1.0.1","description":"AAEP producer example in TypeScript / Node.js — manual loop pattern with full safety machinery","keywords":["aaep","accessibility","agent","typescript","nodejs","screen-reader","assistive-technology"],"homepage":"https://aaep-protocol.org","repository":{"type":"git","url":"git+https://github.com/Ramseyxlil/aaep.git","directory":"examples/producers/typescript-minimal"},"bugs":{"url":"https://github.com/Ramseyxlil/aaep/issues"},"license":"MIT","author":{"name":"Abdulrafiu Izuafa","email":"Abdulrafiu@izusoft.tech","url":"https://aaep-protocol.org"},"type":"module","main":"./dist/index.js","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"},"./emitter":{"types":"./dist/emitter.d.ts","import":"./dist/emitter.js"},"./agent":{"types":"./dist/agent.d.ts","import":"./dist/agent.js"},"./types":{"types":"./dist/types.d.ts","import":"./dist/types.js"}},"bin":{"aaep-ts-server":"dist/server.js"},"scripts":{"build":"tsc","watch":"tsc --watch","demo":"tsx src/agent.ts","server":"tsx src/server.ts","test":"vitest run","test:watch":"vitest","lint":"tsc --noEmit","clean":"rm -rf dist"},"engines":{"node":">=18.0.0"},"dependencies":{},"devDependencies":{"@types/node":"^20.10.0","tsx":"^4.7.0","typescript":"^5.3.0","vitest":"^1.2.0"},"publishConfig":{"access":"public"},"gitHead":"64c5f934bb1c5a774a95f92d438379620b8aa233","_id":"@aaep/typescript-producer@1.0.1","_nodeVersion":"24.13.0","_npmVersion":"11.6.2","dist":{"integrity":"sha512-Pth+FNO75QCVRGHshKwmlxkoskSILBbdBt5/R/tHQIaK3CkRpsYUgPMaPQbClIipdPsPLeH0uD/EwBYaFrdR6A==","shasum":"a59a1fb1bf0d62f66edba4e139698feea90918fd","tarball":"https://registry.npmjs.org/@aaep/typescript-producer/-/typescript-producer-1.0.1.tgz","fileCount":26,"unpackedSize":110464,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIA5xHNyHOMrxWWyDZ9mHfFXBf9PuvvXq1mhbPn0C+BstAiAcz7j3VKzeNf8kJiGzb+Xl6FeV/fHfrryPL9r0pNAakw=="}]},"_npmUser":{"name":"abdulrafiu","email":"izuafa123abdulrafiu@gmail.com"},"directories":{},"maintainers":[{"name":"abdulrafiu","email":"izuafa123abdulrafiu@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/typescript-producer_1.0.1_1780397104991_0.31498512676592827"},"_hasShrinkwrap":false}},"time":{"created":"2026-06-02T10:45:04.824Z","1.0.1":"2026-06-02T10:45:05.147Z","modified":"2026-06-02T10:45:05.400Z"},"maintainers":[{"name":"abdulrafiu","email":"izuafa123abdulrafiu@gmail.com"}],"description":"AAEP producer example in TypeScript / Node.js — manual loop pattern with full safety machinery","homepage":"https://aaep-protocol.org","keywords":["aaep","accessibility","agent","typescript","nodejs","screen-reader","assistive-technology"],"repository":{"type":"git","url":"git+https://github.com/Ramseyxlil/aaep.git","directory":"examples/producers/typescript-minimal"},"author":{"name":"Abdulrafiu Izuafa","email":"Abdulrafiu@izusoft.tech","url":"https://aaep-protocol.org"},"bugs":{"url":"https://github.com/Ramseyxlil/aaep/issues"},"license":"MIT","readme":"# TypeScript Minimal Producer Example\n\nA minimal but complete AAEP producer implementation in TypeScript, designed for Node.js (18+). Demonstrates the manual loop pattern with full safety machinery and HTTP/SSE transport.\n\nIf you're building AAEP producers in the TypeScript/Node.js ecosystem — whether for browser-side agents, Electron-based AT software, or Node backend agents — this is the example to copy.\n\n---\n\n## What this example demonstrates\n\n- A complete AAEP emitter implemented in idiomatic TypeScript\n- Strict type definitions for every event type (matching the JSON Schemas)\n- Native Node.js streams and `fetch` (no framework dependency)\n- HTTP/SSE transport using Node's `http` module\n- The same safety machinery as the Python examples: irreversible+high MUST default reject, secret redaction, critical urgency on errored events\n- Confirmation flow with `Promise`-based blocking\n- Streaming output with sentence-boundary coalescing\n- All 12 core AAEP event types emitted from a typical agent session\n- Conformance Level 2 compatible\n\n---\n\n## When to use this example\n\n**Pick this pattern when:**\n- You're building agents in Node.js, TypeScript, or modern JavaScript\n- You need AAEP support in browser-side agent UIs\n- You're building AT software in Electron, Tauri, or similar frameworks\n- You want strict type definitions for AAEP events in your codebase\n\n**Pick a Python example when:** your agent stack is Python.\n\n---\n\n## Installation\n\n```bash\ncd examples/producers/typescript-minimal\nnpm install\nnpm run build\n```\n\nRequires Node.js 18 or newer.\n\n---\n\n## Quick start\n\n```typescript\nimport { AAEPEmitter, AgentLoop, makeId } from 'aaep-typescript-producer';\n\n// Step 1: create an emitter with your transport\nconst emitter = new AAEPEmitter({\n    sendEvent: (event) => {\n        // Forward to subscribers (HTTP/SSE, WebSocket, etc.)\n        console.log(JSON.stringify(event));\n    },\n    agentId: 'my-agent',\n    agentName: 'My Agent',\n});\n\n// Step 2: create an agent loop\nconst agent = new AgentLoop(emitter);\n\n// Step 3: run a session\nconst sessionId = await agent.run('Tell me about retirement planning.');\n```\n\nThe agent emits AAEP events through the configured transport as it runs. The same safety guarantees as Python: irreversible actions trigger confirmation events, errors emit critical-urgency terminal events, streaming output coalesces at sentence boundaries.\n\n---\n\n## Running the included demo\n\n```bash\nnpm run demo\n```\n\nRuns three scenarios (basic query, tool use, irreversible tool with confirmation) and prints every emitted AAEP event in real time.\n\n---\n\n## Running the conformance suite against it\n\n```bash\n# Terminal 1: start the server (port 8084)\nnpm run server\n\n# Terminal 2: run the Python conformance suite against the TypeScript server\naaep-conformance producer --endpoint http://localhost:8084 --level 2\n```\n\nThe Python `aaep-conformance` package can verify any HTTP/SSE AAEP producer regardless of implementation language. Cross-language conformance is mechanically demonstrated.\n\n---\n\n## Project layout\n\n```\ntypescript-minimal/\n├── README.md\n├── package.json\n├── tsconfig.json\n├── src/\n│   ├── index.ts         # Public API exports\n│   ├── types.ts         # TypeScript types matching the AAEP schemas\n│   ├── emitter.ts       # AAEPEmitter class\n│   ├── coalescer.ts     # StreamCoalescer for sentence-boundary buffering\n│   ├── agent.ts         # AgentLoop with mock LLM\n│   └── server.ts        # HTTP/SSE server\n└── test/\n    ├── emitter.test.ts\n    └── coalescer.test.ts\n```\n\n---\n\n## Key design decisions\n\n### 1. Strict TypeScript types\n\nEvery AAEP event has a corresponding TypeScript interface (`SessionStartedEvent`, `ToolInvokedEvent`, etc.). The emitter methods are strongly typed so editor autocomplete shows valid field names and the compiler catches missing required fields. Types match the JSON Schemas exactly.\n\n### 2. No framework dependencies\n\nThe example uses only the Node.js standard library plus type definitions. No Express, no Fastify, no agent framework — just the language and runtime. This makes the integration pattern clear and ensures the example survives ecosystem churn.\n\n### 3. Runtime safety enforcement (same as Python)\n\nThe `awaitConfirmation` method throws if called with `irreversible: true`, `riskLevel: 'high'`, and `defaultDecision: 'accept'`. This matches the JSON Schema's if/then rule AND the Python emitter's runtime check. The safety contract is enforced at every layer.\n\n### 4. Promise-based confirmation blocking\n\nJavaScript doesn't have Python's `asyncio.Future`, but `Promise` works the same way. `awaitConfirmation()` returns a reply token; calling code does `await emitter.waitForDecision(token)` to block until the subscriber replies via `submitReply()`.\n\n### 5. Compatible with browser-side agents\n\nThe emitter code is environment-agnostic (no Node-specific imports in `emitter.ts`). You can use the same `AAEPEmitter` in a browser bundle for browser-side agents. Only `server.ts` is Node-specific.\n\n---\n\n## Cross-language conformance verification\n\nThis example demonstrates that **AAEP is genuinely language-agnostic**. The same `aaep-conformance` Python tool that verifies the Python examples also verifies this TypeScript example without modification.\n\nTo prove this end-to-end:\n\n```bash\n# Run all 5 servers simultaneously\npython -m aaep_minimal_producer.server --port 8080 &     # Python manual loop\npython -m aaep_langchain.server --port 8081 &            # LangChain callback\npython -m aaep_anthropic_sdk.server --port 8082 &        # Anthropic SDK\npython -m aaep_maf.server --port 8083 &                  # Microsoft Agent Framework\nnpm run server &                                         # TypeScript (port 8084)\n\n# Run conformance against all 5\nfor port in 8080 8081 8082 8083 8084; do\n  aaep-conformance producer --endpoint http://localhost:$port --level 2\ndone\n```\n\nIf all 5 pass Level 2, AAEP is interoperable across 4 Python integration patterns AND TypeScript. That's the mechanical proof of \"AAEP is language-agnostic\" — not a claim, a result.\n\n---\n\n## See also\n\n- [`../python-minimal/`](../python-minimal/) — the Python reference (same machinery, different language)\n- [Implementer's Guide §3.7](../../../guides/IMPLEMENTERS_GUIDE.md) — TypeScript integration specifics\n- [Node.js SSE documentation](https://nodejs.org/api/http.html) — upstream reference for the transport\n","readmeFilename":"README.md","_rev":"1-c122722f2f2e3fd38f9c7fcdc4663019"}