{"_id":"@agentrail-core/sdk","name":"@agentrail-core/sdk","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@agentrail-core/sdk","version":"0.1.0","description":"TypeScript SDK for the AgentRail Task Lifecycle API","type":"module","main":"./dist/index.js","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"scripts":{"build":"tsc","test":"tsc --noEmit","prepublishOnly":"npm run build"},"keywords":["agentrail","sdk","agent","task-lifecycle"],"license":"Apache-2.0","engines":{"node":">=18.0.0"},"devDependencies":{"@types/node":"^25.6.0","typescript":"^5.7.0"},"_id":"@agentrail-core/sdk@0.1.0","_integrity":"sha512-TE7oL5MvsP2abZJuQklmJMlFDbgNTl92No69DPXpH29p3SDrSunPqmFJPkYJ4QTGWPlUQ2mbCnKqkWfmDfJfzQ==","_resolved":"/home/runner/work/agentrail/agentrail/release/typescript-sdk/agentrail-core-sdk-0.1.0.tgz","_from":"file:release/typescript-sdk/agentrail-core-sdk-0.1.0.tgz","_nodeVersion":"20.20.2","_npmVersion":"10.8.2","dist":{"integrity":"sha512-TE7oL5MvsP2abZJuQklmJMlFDbgNTl92No69DPXpH29p3SDrSunPqmFJPkYJ4QTGWPlUQ2mbCnKqkWfmDfJfzQ==","shasum":"1a031ce9dd7f637f335f320f8ec699bae6fd4c3c","tarball":"https://registry.npmjs.org/@agentrail-core/sdk/-/sdk-0.1.0.tgz","fileCount":22,"unpackedSize":57591,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQD4oVCgBGZRb2Ak9+FqtRaEZYoPpNukv33UYpdAcdFlUQIhALrTY0iHGQyHIXS8JCTdxqQWPT5O3AmPrH3b/7iwGZaJ"}]},"_npmUser":{"name":"oxnw","email":"onynwamba@gmail.com"},"directories":{},"maintainers":[{"name":"oxnw","email":"onynwamba@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/sdk_0.1.0_1777905857052_0.3363002149521457"},"_hasShrinkwrap":false}},"time":{"created":"2026-05-04T14:44:16.997Z","0.1.0":"2026-05-04T14:44:17.205Z","modified":"2026-05-04T14:44:17.388Z"},"maintainers":[{"name":"oxnw","email":"onynwamba@gmail.com"}],"description":"TypeScript SDK for the AgentRail Task Lifecycle API","keywords":["agentrail","sdk","agent","task-lifecycle"],"license":"Apache-2.0","readme":"# @agentrail-core/sdk\n\nTypeScript SDK for the AgentRail Task Lifecycle API.\n\n## Install\n\n```bash\nnpm install @agentrail-core/sdk\n```\n\nRequires Node.js >= 18.0.0 (uses native `fetch`).\n\n## Quickstart\n\nStart the local OSS demo API from the repository root:\n\n```bash\nnpm start\n```\n\n```typescript\nimport { AgentRailClient } from \"@agentrail-core/sdk\";\n\nconst client = new AgentRailClient({\n  baseUrl: \"http://127.0.0.1:3000\",\n  apiKey: process.env.AGENTRAIL_API_KEY ?? \"ar_local_demo_key\",\n});\n\n// List assigned tasks\nconst tasks = await client.listMyTasks({ status: \"todo\" });\nfor (const task of tasks.data) {\n  console.log(`${task.identifier}: ${task.title}`);\n}\n\n// Get task details\nconst detail = await client.getTask(\"tsk_01JY4X8Q6J5Q3P7M0N2K3R4T5V\");\n\n// Submit work for review\nconst submission = await client.submitTask(\n  \"tsk_01JY4X8Q6J5Q3P7M0N2K3R4T5V\",\n  {\n    summary: \"Implemented the feature\",\n    artifacts: [\n      { type: \"pull_request\", url: \"https://github.com/org/repo/pull/42\" },\n    ],\n  },\n  \"submit-AGEA-2-v1\", // idempotency key\n);\n\n// Check CI status\nconst ci = await client.getTaskCiStatus(\"tsk_01JY4X8Q6J5Q3P7M0N2K3R4T5V\");\nconsole.log(`CI: ${ci.data.overallStatus}`);\n\n// Get review feedback\nconst feedback = await client.getTaskReviewFeedback(\"tsk_01JY4X8Q6J5Q3P7M0N2K3R4T5V\");\nconsole.log(`Decision: ${feedback.data.latestDecision.outcome}`);\n\n// Ship approved task\nconst ship = await client.shipTask(\n  \"tsk_01JY4X8Q6J5Q3P7M0N2K3R4T5V\",\n  {\n    mode: \"merge_and_deploy\",\n    targetEnvironment: \"production\",\n    expectedHeadSha: \"b5bc7f86b9ad94f4f18f83d28bdf3e27a31e53a0\",\n  },\n  \"ship-AGEA-2-v1\",\n);\n```\n\n## Authentication\n\nCreate an API key, then use it to initialize the client:\n\n```typescript\n// Bootstrap: create the first admin key (no auth required)\nconst client = new AgentRailClient({\n  baseUrl: \"http://127.0.0.1:3000\",\n  apiKey: \"\", // empty for bootstrap\n});\n\nconst key = await client.createApiKey(\n  {\n    agent: {\n      id: \"agt_my_agent\",\n      displayName: \"My Agent\",\n      role: \"developer\",\n      externalIdentities: [{ provider: \"github\", subject: \"my-bot\" }],\n    },\n    scopes: [\"auth:admin\"],\n    rateLimit: { windowSeconds: 60, maxRequests: 600 },\n  },\n  \"bootstrap-key-v1\",\n);\n\nconsole.log(`API Key: ${key.data.apiKey}`);\n```\n\n## Retry Logic\n\nThe client retries failed requests with exponential backoff. Customize behavior:\n\n```typescript\nconst client = new AgentRailClient({\n  baseUrl: process.env.AGENTRAIL_BASE_URL ?? \"http://127.0.0.1:3000\",\n  apiKey: process.env.AGENTRAIL_API_KEY ?? \"ar_local_demo_key\",\n  retry: {\n    maxAttempts: 5,          // default: 3\n    initialDelayMs: 500,      // default: 1000\n    maxDelayMs: 60_000,       // default: 30000\n    retryableStatusCodes: [429, 500, 502, 503, 504], // default\n  },\n});\n```\n\nFor AgentRail Cloud, pass `baseUrl: \"https://api.agentrail.dev/v1\"` explicitly.\n\nRate-limited responses (429) respect the `Retry-After` header automatically.\n\n## Error Handling\n\nAll API errors throw typed `AgentRailError` subclasses:\n\n```typescript\nimport {\n  AgentRailClient,\n  ConflictError,\n  NotFoundError,\n  RateLimitError,\n  ValidationError,\n} from \"@agentrail-core/sdk\";\n\ntry {\n  await client.shipTask(taskId, request, idempotencyKey);\n} catch (err) {\n  if (err instanceof ConflictError) {\n    console.log(\"Task not shippable:\", err.details);\n  } else if (err instanceof NotFoundError) {\n    console.log(\"Task not found\");\n  } else if (err instanceof RateLimitError) {\n    console.log(`Retry after ${err.retryAfterSeconds}s`);\n  } else if (err instanceof ValidationError) {\n    console.log(\"Bad request:\", err.details);\n  }\n}\n```\n\n## Webhooks\n\nRegister a webhook subscription and verify incoming events:\n\n```typescript\nimport { AgentRailClient, parseWebhookEvent } from \"@agentrail-core/sdk\";\n\n// Register\nconst sub = await client.createWebhookSubscription(\n  {\n    url: \"https://my-app.example.com/webhooks/tasks\",\n    eventTypes: [\"task.updated\", \"task.reviewed\", \"task.shipped\"],\n    secret: \"whsec_my_secret_at_least_16\",\n  },\n  \"webhook-sub-v1\",\n);\n\nconst subscriptions = await client.listWebhookSubscriptions();\nconst current = await client.getWebhookSubscription(sub.data.id);\n\n// Verify and parse incoming webhook (e.g. in an Express handler)\nconst event = parseWebhookEvent(rawBody, \"whsec_my_secret_at_least_16\", {\n  \"x-agentrail-webhook-id\": req.headers[\"x-agentrail-webhook-id\"],\n  \"x-agentrail-event-id\": req.headers[\"x-agentrail-event-id\"],\n  \"x-agentrail-event-type\": req.headers[\"x-agentrail-event-type\"],\n  \"x-agentrail-delivery-id\": req.headers[\"x-agentrail-delivery-id\"],\n  \"x-agentrail-delivery-attempt\": req.headers[\"x-agentrail-delivery-attempt\"],\n  \"x-agentrail-signature\": req.headers[\"x-agentrail-signature\"],\n});\n\nswitch (event.type) {\n  case \"task.updated\":\n    console.log(`Task ${event.data.taskIdentifier} → ${event.data.status}`);\n    break;\n  case \"task.reviewed\":\n    console.log(`Review: ${event.data.reviewOutcome}`);\n    break;\n  case \"task.shipped\":\n    console.log(`Shipped to ${event.data.targetEnvironment}`);\n    break;\n}\n```\n\n## Event Stream (SSE)\n\nStream real-time task lifecycle events:\n\n```typescript\nconst controller = new AbortController();\n\nfor await (const event of client.streamEvents({\n  eventTypes: [\"task.updated\"],\n  signal: controller.signal,\n})) {\n  console.log(event.type, event.data);\n}\n```\n\n## API Key Management\n\n```typescript\n// Rotate a key\nconst rotated = await client.rotateApiKey(\n  \"akey_01JY52RRF5PAGHT5DCZXJ4N2DG\",\n  { expiresAt: \"2026-07-01T00:00:00Z\" },\n  \"rotate-key-v1\",\n);\n\n// Check usage\nconst usage = await client.getApiKeyUsage(\"akey_01JY52RRF5PAGHT5DCZXJ4N2DG\");\nconsole.log(`Requests: ${usage.data.totals.accepted}`);\n```\n","readmeFilename":"README.md","_rev":"1-d1559e1893c1421d7e3b170772c78e09"}