{"_id":"@alignment_agents/broker-protocol","_rev":"2-42a50e59e231be4eed8bbeecd8f8033e","name":"@alignment_agents/broker-protocol","dist-tags":{"latest":"0.1.1"},"versions":{"0.1.0":{"name":"@alignment_agents/broker-protocol","version":"0.1.0","keywords":["alignment-broker","agentic-commerce","ai-agents","protocol","brand-agent","consumer-agent","broker","sdk"],"author":{"name":"Alignment AI","email":"hello@alignmenttech.ai"},"license":"MIT","_id":"@alignment_agents/broker-protocol@0.1.0","maintainers":[{"name":"alignment_ai","email":"agents@alignmenttech.ai"}],"homepage":"https://alignmenttech.ai/docs/agentic-commerce/protocol","bugs":{"url":"https://github.com/Alignment-GEOAI/alignment-workspace/issues"},"dist":{"shasum":"62d75543c2fa304bea7f221e7d454da904403523","tarball":"https://registry.npmjs.org/@alignment_agents/broker-protocol/-/broker-protocol-0.1.0.tgz","fileCount":47,"integrity":"sha512-/LdNyjeT9HDc77fYh4KxQVuHSLKDwrCqT7RoRFceJMCYMKGB4LIeygZWb8i96AloEBBcW3nfjK/FvE+creZoPA==","signatures":[{"sig":"MEUCIQCHgLhpznRXs3bBW5nlla/k8hzNJ7QDXYNlUBPN3vbaSQIgLL5PIxztUWxdL0bQeZIOIVK/1bs78/q/xXGZf1OEI3g=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":142025},"main":"./dist/cjs/index.cjs","type":"module","types":"./dist/index.d.ts","module":"./dist/index.js","engines":{"node":">=18.0.0"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","require":"./dist/cjs/index.cjs"}},"gitHead":"b7895d5a3865222350fc11f137469ba86eec5785","scripts":{"test":"node --experimental-vm-modules node_modules/.bin/jest","build":"tsc -p tsconfig.json && tsc -p tsconfig.cjs.json","typecheck":"tsc --noEmit","prepublishOnly":"npm run build"},"_npmUser":{"name":"alignment_ai","email":"agents@alignmenttech.ai"},"repository":{"url":"git+https://github.com/Alignment-GEOAI/alignment-workspace.git","type":"git","directory":"01.Alignment AI/08-Alignment-Agentic Commerce/sdk/broker-protocol-ts"},"_npmVersion":"10.8.2","description":"TypeScript SDK for the Alignment Broker Protocol v0.1 — agent-to-agent commerce infrastructure","directories":{},"_nodeVersion":"20.20.2","_hasShrinkwrap":false,"devDependencies":{"typescript":"^5.4.5"},"_npmOperationalInternal":{"tmp":"tmp/broker-protocol_0.1.0_1779139010829_0.10203743042975932","host":"s3://npm-registry-packages-npm-production"}},"0.1.1":{"name":"@alignment_agents/broker-protocol","version":"0.1.1","description":"TypeScript SDK for the Alignment Broker Protocol v0.1 — agent-to-agent commerce infrastructure","author":{"name":"Alignment AI","email":"hello@alignmenttech.ai"},"license":"MIT","homepage":"https://alignmenttech.ai/docs/agentic-commerce/protocol","repository":{"type":"git","url":"git+https://github.com/Alignment-GEOAI/alignment-workspace.git","directory":"01.Alignment AI/08-Alignment-Agentic Commerce/sdk/broker-protocol-ts"},"keywords":["alignment-broker","agentic-commerce","ai-agents","protocol","brand-agent","consumer-agent","broker","sdk"],"type":"module","exports":{".":{"import":"./dist/index.js","require":"./dist/cjs/index.cjs","types":"./dist/index.d.ts"}},"main":"./dist/cjs/index.cjs","module":"./dist/index.js","types":"./dist/index.d.ts","scripts":{"build":"tsc -p tsconfig.json && tsc -p tsconfig.cjs.json","typecheck":"tsc --noEmit","test":"node --experimental-vm-modules node_modules/.bin/jest","prepublishOnly":"npm run build"},"devDependencies":{"typescript":"^5.4.5"},"engines":{"node":">=18.0.0"},"_id":"@alignment_agents/broker-protocol@0.1.1","gitHead":"7ae668355d86f2279d5b26dfe9cf1e5206633a6e","bugs":{"url":"https://github.com/Alignment-GEOAI/alignment-workspace/issues"},"_nodeVersion":"20.20.2","_npmVersion":"10.8.2","dist":{"integrity":"sha512-nXUSDK6K7l98Xd+t4ZNC1e/ljDpfds5KttYZkcVOucFW6N9a+mowSqOp2lSrQ7Qq+qf3T5HnYhxcurUkwZx/Ew==","shasum":"2f89c48bdbff2b9e43d4cc2074f1adb9a561fb58","tarball":"https://registry.npmjs.org/@alignment_agents/broker-protocol/-/broker-protocol-0.1.1.tgz","fileCount":47,"unpackedSize":142378,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQDDbCBmCJl3Dsow+fwoTPPvbaVyUVSWsXEhEOixEjCmFwIhAJSUV2OwNET4WHHYwoNC4JYgyJL4+hBG+tXgdPg3zdaj"}]},"_npmUser":{"name":"alignment_ai","email":"agents@alignmenttech.ai"},"directories":{},"maintainers":[{"name":"alignment_ai","email":"agents@alignmenttech.ai"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/broker-protocol_0.1.1_1779139829861_0.34137488668771065"},"_hasShrinkwrap":false}},"time":{"created":"2026-05-18T21:16:50.702Z","modified":"2026-05-18T21:30:30.133Z","0.1.0":"2026-05-18T21:16:50.992Z","0.1.1":"2026-05-18T21:30:30.017Z"},"bugs":{"url":"https://github.com/Alignment-GEOAI/alignment-workspace/issues"},"author":{"name":"Alignment AI","email":"hello@alignmenttech.ai"},"license":"MIT","homepage":"https://alignmenttech.ai/docs/agentic-commerce/protocol","keywords":["alignment-broker","agentic-commerce","ai-agents","protocol","brand-agent","consumer-agent","broker","sdk"],"repository":{"type":"git","url":"git+https://github.com/Alignment-GEOAI/alignment-workspace.git","directory":"01.Alignment AI/08-Alignment-Agentic Commerce/sdk/broker-protocol-ts"},"description":"TypeScript SDK for the Alignment Broker Protocol v0.1 — agent-to-agent commerce infrastructure","maintainers":[{"name":"alignment_ai","email":"agents@alignmenttech.ai"}],"readme":"# @alignment_agents/broker-protocol\n\n> TypeScript SDK for the **Alignment Broker Protocol v0.1** — agent-to-agent commerce infrastructure.\n\n[![npm version](https://img.shields.io/npm/v/@alignment_agents/broker-protocol.svg)](https://www.npmjs.com/package/@alignment_agents/broker-protocol)\n[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)\n\n---\n\n## Overview\n\nThe Alignment Broker is the neutral settlement layer between **Consumer Agents** (shopping bots, voice assistants, phone-OS agents) and **Brand Agents** (product catalog endpoints). This SDK lets you build either side.\n\n```\nConsumer Agent  ──query──▶  Alignment Broker  ──fan-out──▶  Brand Agents\n                ◀─quotes──                    ◀─quote────\n                ──commit──▶                   ──commit──▶\n```\n\nRanking is deterministic and transparent — no paid placement:\n\n| Factor | Weight |\n|--------|--------|\n| Price match | 30% |\n| Trust score | 25% |\n| Semantic match | 20% |\n| Estimated delivery | 15% |\n| Inventory confidence | 10% |\n\n---\n\n## Installation\n\n```bash\nnpm install @alignment_agents/broker-protocol\n```\n\nRequires Node.js ≥ 18. Ships as **ESM + CommonJS** dual format with full TypeScript declarations.\n\n---\n\n## Quick Start — Consumer Agent\n\n```typescript\nimport { AlignmentBroker } from \"@alignment_agents/broker-protocol\";\n\nconst broker = new AlignmentBroker({ apiKey: \"ak_…\" });\n\n// 1. Query — find matching products across all Brand Agents\nconst result = await broker.query({\n  consumer_agent_id: \"did:alignment:acme:whatsapp-bot-1\",\n  intent: {\n    raw: \"waterproof running shoes under $150\",\n    structured: {\n      category: \"footwear\",\n      constraints: { waterproof: true, price_max: 150 },\n    },\n  },\n  user_context: {\n    region:           \"US\",\n    currency:         \"USD\",\n    ship_to_country:  \"US\",\n  },\n});\n\n// 2. Inspect ranked quotes (transparent 5-factor score)\nconst top = result.ranked_quotes[0];\nconsole.log(top.product.price, top.broker_score, top.ranking_factors);\n\n// 3. Commit — confirm the purchase\nconst tx = await broker.commit({\n  quote_id:          top.quote_id,\n  consumer_agent_id: \"did:alignment:acme:whatsapp-bot-1\",\n  shipping: {\n    name:           \"Jane Doe\",\n    address_line_1: \"123 Main St\",\n    city:           \"San Francisco\",\n    region:         \"CA\",\n    postal_code:    \"94105\",\n    country:        \"US\",\n  },\n  payment_token: \"tok_visa_4242\",   // tokenized payment, never raw PAN\n  user_consent: {\n    ts:                new Date().toISOString(),\n    agent_attestation: \"user-confirmed-on-whatsapp\",\n  },\n});\n\nconsole.log(\"Transaction ID:\", tx.transaction_id);\nconsole.log(\"Settlement:\", tx.settlement);\n```\n\n---\n\n## Quick Start — Brand Agent Server\n\n```typescript\nimport { generateWellKnown, assertBrokerKey } from \"@alignment_agents/broker-protocol\";\nimport type { BrokerQuoteRequest, BrokerQuoteResponse } from \"@alignment_agents/broker-protocol\";\n\n// 1. Serve your .well-known/agent.json discovery document\nconst wellKnown = generateWellKnown({\n  agentId:   \"did:alignment:my-brand:prod-1\",\n  operator:  \"My Brand Inc.\",\n  baseUrl:   \"https://agents.my-brand.com\",\n  currencies: [\"USD\", \"EUR\"],\n  shipTo:    [\"US\", \"CA\", \"GB\"],\n});\n\n// 2. Handle /v1/quote calls from the Broker\nasync function handleQuote(req: BrokerQuoteRequest, brokerKey: string): Promise<BrokerQuoteResponse> {\n  assertBrokerKey(brokerKey, process.env.BROKER_KEY!); // timing-safe validation\n\n  return {\n    brand_id:    \"did:alignment:my-brand:prod-1\",\n    quote_id:    crypto.randomUUID(),\n    price_usd:   129.99,\n    currency:    \"USD\",\n    product_id:  \"shoe-wr-001\",\n    title:       \"TrailRunner Pro — Waterproof\",\n    in_stock:    true,\n    eta_days:    3,\n    expires_at:  new Date(Date.now() + 5 * 60_000).toISOString(),\n  };\n}\n```\n\n---\n\n## API Reference\n\n### `new AlignmentBroker(config)`\n\n| Option | Type | Default | Description |\n|--------|------|---------|-------------|\n| `apiKey` | `string` | — | Your Consumer Agent API key (`ak_…`) |\n| `baseUrl` | `string` | `https://api.alignmenttech.ai` | Broker API base URL |\n| `timeoutMs` | `number` | `15000` | Request timeout |\n| `fetch` | `typeof fetch` | global fetch | Custom fetch implementation |\n\n### Methods\n\n| Method | Description |\n|--------|-------------|\n| `broker.query(req)` | Fan-out intent query → ranked quotes (p95 200–600 ms) |\n| `broker.commit(req)` | Confirm a quote → transaction + settlement |\n| `broker.getQuery(queryId)` | Replay / inspect a past query |\n| `broker.registerConsumerAgent(req)` | Register a new Consumer Agent |\n| `broker.registerBrandAgent(req)` | Register a new Brand Agent |\n| `broker.setApiKey(key)` | Update API key at runtime |\n\n### Error Classes\n\n```typescript\nimport {\n  QuoteExpiredError,    // 409 — quote TTL elapsed (re-query)\n  OutOfStockError,      // 410 — inventory gone\n  AlreadyCommittedError,// 409 — quote already used\n  RateLimitedError,     // 429 — slow down\n} from \"@alignment_agents/broker-protocol\";\n```\n\n---\n\n## Get Your API Key\n\n1. Sign up at [alignmenttech.ai](https://alignmenttech.ai)\n2. Navigate to **Agentic Commerce → Integration**\n3. Copy your Consumer Agent API key\n\n---\n\n## License\n\nMIT © [Alignment AI](https://alignmenttech.ai)\n","readmeFilename":"README.md"}