{"_id":"@aura-labs.ai/scout","_rev":"2-fa97d7dd80264ffe4847d8bfea4cd2cd","name":"@aura-labs.ai/scout","dist-tags":{"latest":"0.2.0"},"versions":{"0.2.0":{"name":"@aura-labs.ai/scout","version":"0.2.0","keywords":["aura","agentic-commerce","ai-agent","shopping-agent","scout"],"author":{"name":"AURA Labs"},"license":"BSL-1.1","_id":"@aura-labs.ai/scout@0.2.0","maintainers":[{"name":"marcmassar","email":"marc@aura-labs.ai"}],"homepage":"https://aura-labs.ai/docs/scout","bugs":{"url":"https://github.com/aura-labs-ai/aura-labs/issues"},"bin":{"scout-cli":"bin/scout-cli.js","aura-scout":"bin/scout-cli.js"},"dist":{"shasum":"97ddb5cb0cd801c94ecdcc623d45c17994332e39","tarball":"https://registry.npmjs.org/@aura-labs.ai/scout/-/scout-0.2.0.tgz","fileCount":28,"integrity":"sha512-WtwBQh8xXw5Mwbi6YzElzqJOGzvICeT0imwWyGxzfgjGGQPZkhD7som+O/Q5LjUlIc0nu1RF1O9W2dLGHFSk/g==","signatures":[{"sig":"MEYCIQD8GBU09fUiUo9HVh7kLv5IjdhWYXu2ky8cn8CdevIkrAIhAMa/PpN3V0k1Y46tMQCAGQ5Y4wI20legk7IKx7qnfwsz","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":263192},"main":"src/index.js","type":"module","types":"src/index.d.ts","engines":{"node":">=18.0.0"},"exports":{".":{"types":"./src/index.d.ts","import":"./src/index.js"},"./ap2":{"import":"./src/ap2/mandates.js"},"./mcp":{"import":"./src/mcp/client.js"},"./tap":{"import":"./src/tap/visa.js"}},"scripts":{"cli":"node bin/scout-cli.js","test":"node --test src/**/*.test.js","example":"node examples/basic-purchase.js","test:ap2":"node --test src/tests/scenarios/ap2-scenarios.test.js","test:mcp":"node --test src/tests/scenarios/mcp-scenarios.test.js","test:tap":"node --test src/tests/scenarios/tap-scenarios.test.js","test:protocols":"node src/tests/run-protocol-tests.js","test:scenarios":"node src/tests/scenarios/index.js","test:integration":"node --test src/tests/scenarios/integration-scenarios.test.js","example:protocols":"node examples/protocol-integration.js"},"_npmUser":{"name":"marcmassar","email":"marc@aura-labs.ai"},"repository":{"url":"git+https://github.com/aura-labs-ai/aura-labs.git","type":"git"},"_npmVersion":"11.11.0","description":"Scout SDK for AURA - Build buying agents that participate in agentic commerce","directories":{},"_nodeVersion":"25.8.0","dependencies":{"@aura-labs.ai/nlp":"^0.1.0","@aura-labs.ai/sdk-common":"^0.1.0"},"_hasShrinkwrap":false,"devDependencies":{"@types/node":"^20.11.0"},"_npmOperationalInternal":{"tmp":"tmp/scout_0.2.0_1773247405100_0.8404270835723013","host":"s3://npm-registry-packages-npm-production"},"deprecated":"Package no longer supported. Contact Support at https://www.npmjs.com/support for more info."}},"time":{"created":"2026-03-11T16:43:24.996Z","modified":"2026-07-02T19:29:34.735Z","0.2.0":"2026-03-11T16:43:25.255Z"},"bugs":{"url":"https://github.com/aura-labs-ai/aura-labs/issues"},"author":{"name":"AURA Labs"},"license":"BSL-1.1","homepage":"https://aura-labs.ai/docs/scout","keywords":["aura","agentic-commerce","ai-agent","shopping-agent","scout"],"repository":{"url":"git+https://github.com/aura-labs-ai/aura-labs.git","type":"git"},"description":"Scout SDK for AURA - Build buying agents that participate in agentic commerce","maintainers":[{"name":"marcmassar","email":"marc@aura-labs.ai"}],"readme":"# @aura-labs.ai/scout\n\nScout SDK for AURA — Build buying agents that participate in agentic commerce.\n\n## What is a Scout?\n\nA Scout is a user-sovereign buying agent in the AURA ecosystem. Scouts:\n- Express purchase intent in natural language\n- Discover products through AURA Core's neutral broker\n- Evaluate offers against user-defined constraints\n- Commit to transactions while preserving privacy\n\n## Installation\n\n```bash\nnpm install @aura-labs.ai/scout\n```\n\n## Quick Start\n\n```javascript\nimport { createScout } from '@aura-labs.ai/scout';\n\n// Zero-config — auto-generates Ed25519 identity and registers with Core\nconst scout = createScout();\nawait scout.ready();\n\n// Express purchase intent with constraints\nconst session = await scout.intent('I need 500 widgets', {\n  maxBudget: 50000,\n  deliveryBy: new Date('2026-03-01'),\n});\n\n// Wait for offers (polling)\nconst offers = await session.waitForOffers();\n\n// Commit to best offer that meets constraints\nif (session.bestOffer) {\n  const tx = await session.commit(session.bestOffer.id);\n  console.log('Transaction:', tx.id);\n}\n```\n\n## CLI Tool\n\nThe SDK includes a CLI for testing:\n\n```bash\n# Interactive mode (zero-config, uses Ed25519 keys)\nnpx @aura-labs.ai/scout\n\n# Single intent mode\nnpx @aura-labs.ai/scout --intent \"I need office supplies\" --max-budget 500\n```\n\n**HTTPS Enforcement:** The CLI requires HTTPS for all Core API connections. Plaintext HTTP is only permitted for `localhost` and `127.0.0.1` during local development. Use `--core-url https://...` or set `AURA_CORE_URL` with an HTTPS URL.\n\n## Constraint Engine\n\nDefine hard constraints (must be met) and soft preferences (influence ranking):\n\n```javascript\nconst session = await scout.intent('Buy enterprise software licenses', {\n  // Hard constraints - offers that don't meet these are filtered out\n  maxBudget: 100000,\n  deliveryBy: new Date('2026-06-01'),\n  hardConstraints: [\n    { field: 'compliance', operator: 'eq', value: 'SOC2' },\n  ],\n\n  // Soft preferences - influence offer scoring\n  softPreferences: [\n    { field: 'support', operator: 'eq', value: '24/7', weight: 10 },\n    { field: 'rating', operator: 'gte', value: 4.5, weight: 5 },\n  ],\n});\n```\n\n### Constraint Operators\n\nOnly the following operators are accepted. Unknown operators are rejected (fail-closed) to prevent constraint bypass:\n\n| Operator | Description |\n|----------|-------------|\n| `eq` | Equal to |\n| `ne` | Not equal to |\n| `gt` | Greater than |\n| `gte` | Greater than or equal |\n| `lt` | Less than |\n| `lte` | Less than or equal |\n| `contains` | String contains |\n| `in` | Value in array |\n\n## API Reference\n\n### `createScout(config)`\n\nCreate a new Scout instance. Authentication is handled via Ed25519 public key registration — no API keys required.\n\n```javascript\nconst scout = createScout({\n  coreUrl: 'https://aura-labsai-production.up.railway.app', // optional, defaults to production\n  timeout: 30000, // optional, ms\n  storage: customStorageAdapter, // optional, defaults to in-memory\n  constraints: {}, // optional, default constraints\n});\n\n// Initialize and register with AURA Core (idempotent)\nawait scout.ready();\n```\n\n### `scout.ping()`\n\nRead-only connectivity check. Verifies Core is reachable and its dependencies are healthy. Does not require `ready()` — works on a freshly created instance. No auth headers sent.\n\n```javascript\nconst health = await scout.ping();\n\n// When Core is healthy:\n// { status: 'ok', core: { status: 'ready', checks: { database: {...}, redis: {...} } }, latency_ms: 42, timestamp: '...' }\n\n// When Core is alive but degraded (503):\n// { status: 'degraded', core: { status: 'not_ready', checks: {...} }, latency_ms: 105, timestamp: '...' }\n\n// When Core is unreachable:\n// { status: 'error', code: 'CORE_UNREACHABLE', message: '...', latency_ms: 30000, timestamp: '...' }\n\n// When Core times out:\n// { status: 'error', code: 'CORE_TIMEOUT', message: '...', latency_ms: 30000, timestamp: '...' }\n```\n\nActivity events: `ping.success` (Core responded), `ping.failed` (network error or timeout). Summary counters available via `scout.activity.getSummary().ping`.\n\n### `scout.intent(text, options)`\n\nCreate a commerce session with purchase intent.\n\n```javascript\nconst session = await scout.intent('I want to buy...', {\n  maxBudget: number,\n  deliveryBy: Date,\n  hardConstraints: Constraint[],\n  softPreferences: Constraint[],\n});\n```\n\n### `session.waitForOffers(options)`\n\nPoll for offers until available.\n\n```javascript\nconst offers = await session.waitForOffers({\n  timeout: 30000, // max wait time\n  interval: 2000, // poll interval\n});\n```\n\n### `session.commit(offerId)`\n\nCommit to an offer.\n\n```javascript\nconst transaction = await session.commit(offer.id);\n```\n\n### `session.validOffers`\n\nGet offers that meet all hard constraints.\n\n### `session.bestOffer`\n\nGet highest-scoring valid offer.\n\n## Error Handling\n\n```javascript\nimport { ScoutError, AuthenticationError, SessionError } from '@aura-labs.ai/scout';\n\ntry {\n  await scout.intent('...');\n} catch (error) {\n  if (error instanceof AuthenticationError) {\n    console.log('Invalid API key');\n  } else if (error instanceof SessionError) {\n    console.log('Session error:', error.message);\n  }\n}\n```\n\n## Key Storage\n\nEd25519 private keys are persisted across restarts using pluggable storage adapters from `@aura-labs.ai/sdk-common`. The `createStorage()` factory auto-detects the best adapter for the current platform:\n\n| Platform | Adapter | Details |\n|----------|---------|---------|\n| **macOS** | `KeychainStorage` | Hardware-backed encryption at rest via Secure Enclave on Apple Silicon. Uses the `security` CLI — zero native dependencies. |\n| **Linux / Windows** | `FileStorage` | JSON file at `~/.aura/keys.json` with `0600` permissions (owner read/write only). |\n| **Testing** | `MemoryStorage` | In-memory, ephemeral. No persistence. |\n\n```javascript\nimport { createScout, createStorage } from '@aura-labs.ai/scout';\n\n// Auto-detect (recommended)\nconst scout = createScout({ storage: createStorage() });\n\n// Force file-based storage\nconst scout = createScout({ storage: createStorage({ type: 'file' }) });\n\n// Force Keychain (macOS only — throws on other platforms)\nconst scout = createScout({ storage: createStorage({ type: 'keychain' }) });\n\n// Custom file path\nconst scout = createScout({ storage: createStorage({ type: 'file', path: '/custom/keys.json' }) });\n```\n\nOverride the default file path with the `AURA_KEY_PATH` environment variable.\n\n## Environment Variables\n\n| Variable | Description | Default |\n|----------|-------------|---------|\n| `AURA_CORE_URL` | Core API URL (optional) | `https://aura-labsai-production.up.railway.app` |\n| `AURA_KEY_PATH` | Custom path for file-based key storage | `~/.aura/keys.json` |\n\n## Authentication\n\nScout uses **Ed25519 public key cryptography** for identity. When you call `scout.ready()`:\n1. An Ed25519 key pair is auto-generated (or loaded from storage)\n2. The Scout registers with AURA Core via `POST /agents/register` using proof-of-possession (signed request)\n3. Core assigns an agent ID, which is persisted for future sessions\n4. All subsequent requests are signed with the private key for identity verification\n\nNo API keys or other credentials are required.\n\n## License\n\nBusiness Source License 1.1 — See [LICENSE](LICENSE) for details.\n","readmeFilename":"README.md"}