{"_id":"@agent-relay/relayfile-sdk","_rev":"2-3f47b32adf337bd5951b907d74a4c89f","name":"@agent-relay/relayfile-sdk","dist-tags":{"latest":"0.1.2"},"versions":{"0.1.0":{"name":"@agent-relay/relayfile-sdk","version":"0.1.0","license":"Apache-2.0","_id":"@agent-relay/relayfile-sdk@0.1.0","maintainers":[{"name":"willwashburn","email":"will.washburn@gmail.com"},{"name":"khaliqgant","email":"khaliqgant@gmail.com"}],"homepage":"https://github.com/AgentWorkforce/relayfile#readme","bugs":{"url":"https://github.com/AgentWorkforce/relayfile/issues"},"dist":{"shasum":"399b8afb1725572f3a48b10d90a4e9e8af586d2c","tarball":"https://registry.npmjs.org/@agent-relay/relayfile-sdk/-/relayfile-sdk-0.1.0.tgz","fileCount":18,"integrity":"sha512-SbS5kT4rIYLj0ves54V/jBM3e3qqQUpoo0uBtq/Eou+51ygprI58cZ/GD7nepbHHs2fmK5NzGYEJLgUewmlAUg==","signatures":[{"sig":"MEUCIQC3U3z19ar5VMXsqwBKIWpYSSASJvvz2AWtUc88d4A81wIgCoCdxZol7EH6M33vzx5jAiAneOtS0P47cCqo8CUnXTk=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":79665},"main":"./dist/index.js","type":"module","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"gitHead":"054895287847122ea6994b4e9bf7418a1778f592","scripts":{"build":"tsc -p tsconfig.json","clean":"rm -rf dist","prepublishOnly":"npm run build"},"_npmUser":{"name":"khaliqgant","email":"khaliqgant@gmail.com"},"repository":{"url":"git+https://github.com/AgentWorkforce/relayfile.git","type":"git","directory":"sdk/relayfile-sdk"},"_npmVersion":"10.9.4","description":"TypeScript SDK for the RelayFile filesystem-over-REST API.","directories":{},"_nodeVersion":"22.22.0","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"typescript":"^5.7.3"},"_npmOperationalInternal":{"tmp":"tmp/relayfile-sdk_0.1.0_1771419448545_0.44820390279847366","host":"s3://npm-registry-packages-npm-production"}},"0.1.2":{"name":"@agent-relay/relayfile-sdk","version":"0.1.2","description":"TypeScript SDK for the RelayFile filesystem-over-REST API.","license":"Apache-2.0","type":"module","main":"./dist/index.js","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"scripts":{"build":"tsc -p tsconfig.json","clean":"rm -rf dist","prepublishOnly":"npm run build"},"publishConfig":{"access":"public"},"repository":{"type":"git","url":"git+https://github.com/AgentWorkforce/relayfile.git","directory":"sdk/relayfile-sdk"},"devDependencies":{"typescript":"^5.7.3"},"gitHead":"31da20d17d2eb647786ff48f82f3f50596c09852","_id":"@agent-relay/relayfile-sdk@0.1.2","bugs":{"url":"https://github.com/AgentWorkforce/relayfile/issues"},"homepage":"https://github.com/AgentWorkforce/relayfile#readme","_nodeVersion":"20.20.0","_npmVersion":"11.10.0","dist":{"integrity":"sha512-FnpEuoTNcXxiIvTzOElD3NWrQn/fEwzaG7quGTY6Zqmid6OpOrDSQKkjyWXqsmXINhRGbnDXiaRe54z2FrvrTA==","shasum":"c899c094dbd64e2c455871dd4c754f18676165f5","tarball":"https://registry.npmjs.org/@agent-relay/relayfile-sdk/-/relayfile-sdk-0.1.2.tgz","fileCount":18,"unpackedSize":79665,"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@agent-relay%2frelayfile-sdk@0.1.2","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIGXUwl/amvE3DanZMEPFFVoEvjuzrXUo9+I3bDtot89bAiEAqMWvMToQ5xyaq9d3sxA5SLQyZDFAd10/h3Dk5JYOnjY="}]},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:751f6939-906d-43f1-9800-021a804ce065"}},"directories":{},"maintainers":[{"name":"willwashburn","email":"will.washburn@gmail.com"},{"name":"khaliqgant","email":"khaliqgant@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/relayfile-sdk_0.1.2_1771420723024_0.3569566187930717"},"_hasShrinkwrap":false}},"time":{"created":"2026-02-18T12:57:28.413Z","modified":"2026-02-18T13:18:43.502Z","0.1.0":"2026-02-18T12:57:28.724Z","0.1.2":"2026-02-18T13:18:43.165Z"},"bugs":{"url":"https://github.com/AgentWorkforce/relayfile/issues"},"license":"Apache-2.0","homepage":"https://github.com/AgentWorkforce/relayfile#readme","repository":{"type":"git","url":"git+https://github.com/AgentWorkforce/relayfile.git","directory":"sdk/relayfile-sdk"},"description":"TypeScript SDK for the RelayFile filesystem-over-REST API.","maintainers":[{"name":"willwashburn","email":"will.washburn@gmail.com"},{"name":"khaliqgant","email":"khaliqgant@gmail.com"}],"readme":"# @agent-relay/relayfile-sdk\n\nTypeScript SDK for the RelayFile API contract in `openapi/relayfile-v1.openapi.yaml`.\n\n## Install\n\n```bash\nnpm install @agent-relay/relayfile-sdk\n```\n\n## Usage\n\n```ts\nimport { InvalidStateError, QueueFullError, RelayFileClient, RevisionConflictError } from \"@agent-relay/relayfile-sdk\";\n\nconst client = new RelayFileClient({\n  baseUrl: \"https://relayfile.agent-relay.com\",\n  token: () => process.env.RELAYFILE_TOKEN ?? \"\",\n  retry: {\n    maxRetries: 3,\n    baseDelayMs: 100,\n    maxDelayMs: 2000,\n    jitterRatio: 0.2\n  }\n});\n\nconst workspaceId = \"ws_123\";\n\nconst controller = new AbortController();\nconst tree = await client.listTree(workspaceId, {\n  path: \"/notion\",\n  depth: 2,\n  signal: controller.signal\n});\nconst file = await client.readFile(workspaceId, \"/notion/Engineering/Auth.md\");\nconst query = await client.queryFiles(workspaceId, {\n  path: \"/notion\",\n  provider: \"notion\",\n  relation: \"db:investments\",\n  properties: { stage: \"active\" },\n  limit: 25\n});\nconst events = await client.getEvents(workspaceId, { provider: \"notion\", limit: 50 });\nconst ops = await client.listOps(workspaceId, { status: \"dead_lettered\", action: \"file_upsert\", provider: \"notion\", limit: 20 });\nconst sync = await client.getSyncStatus(workspaceId, { provider: \"notion\" });\nconst ingress = await client.getSyncIngressStatus(workspaceId, { provider: \"notion\" });\nconst adminIngress = await client.getAdminIngressStatus({ provider: \"notion\", alertProfile: \"balanced\", deadLetterThreshold: 2, nonZeroOnly: true, maxAlerts: 50, includeWorkspaces: true, includeAlerts: true });\nconst adminSync = await client.getAdminSyncStatus({ provider: \"notion\", nonZeroOnly: true, includeWorkspaces: true, limit: 100, lagSecondsThreshold: 45, maxAlerts: 50, includeAlerts: true });\nconst deadLetters = await client.getSyncDeadLetters(workspaceId, { provider: \"notion\", limit: 20 });\nconsole.log(events.events.length);\nconsole.log(query.items.length);\nconsole.log(ops.items.length);\nconsole.log(sync.providers[0]?.status, sync.providers[0]?.failureCodes, sync.providers[0]?.deadLetteredEnvelopes, sync.providers[0]?.deadLetteredOps);\nconsole.log(ingress.queueDepth, ingress.droppedTotal);\nconsole.log(ingress.queueUtilization, ingress.oldestPendingAgeSeconds);\nconsole.log(ingress.coalescedTotal, ingress.suppressedTotal, ingress.staleTotal);\nconsole.log(ingress.dedupeRate, ingress.coalesceRate);\nconsole.log(ingress.deadLetterByProvider);\nconsole.log(ingress.ingressByProvider[\"notion\"]?.pendingTotal, ingress.ingressByProvider[\"notion\"]?.oldestPendingAgeSeconds);\nconsole.log(adminIngress.alertProfile, adminIngress.effectiveAlertProfile, adminIngress.workspaceCount, adminIngress.returnedWorkspaceCount, adminIngress.nextCursor, adminIngress.pendingTotal, adminIngress.thresholds.deadLetter, adminIngress.alertTotals.critical, adminIngress.alertsTruncated, adminIngress.alerts.length, Object.keys(adminIngress.workspaces));\nconsole.log(adminSync.workspaceCount, adminSync.returnedWorkspaceCount, adminSync.nextCursor, adminSync.providerStatusCount, adminSync.errorCount, adminSync.failureCodes, adminSync.thresholds.lagSeconds, adminSync.alertTotals.critical, adminSync.alertsTruncated, adminSync.alerts.length);\nconsole.log(deadLetters.items.length);\nif (deadLetters.items.length > 0) {\n  const detail = await client.getSyncDeadLetter(workspaceId, deadLetters.items[0].envelopeId);\n  console.log(detail.lastError);\n  await client.replaySyncDeadLetter(workspaceId, deadLetters.items[0].envelopeId);\n  await client.ackSyncDeadLetter(workspaceId, deadLetters.items[0].envelopeId);\n}\nif (ops.items.length > 0) {\n  await client.replayOp(workspaceId, ops.items[0].opId);\n  await client.replayAdminOp(ops.items[0].opId);\n}\nawait client.replayAdminEnvelope(\"env_123\");\n\ntry {\n  const write = await client.writeFile({\n    workspaceId,\n    path: file.path,\n    baseRevision: file.revision,\n    content: file.content + \"\\n\\nUpdated by agent.\",\n    contentType: \"text/markdown\",\n    semantics: {\n      properties: { stage: \"active\" },\n      relations: [\"db:investments\"],\n      permissions: [\"scope:fs:read\"],\n      comments: [\"comment_123\"]\n    }\n  });\n  console.log(write.opId);\n} catch (err) {\n  if (err instanceof RevisionConflictError) {\n    console.error(\"conflict\", err.currentRevision);\n  }\n  if (err instanceof QueueFullError) {\n    console.error(\"ingress saturated, retry in\", err.retryAfterSeconds ?? 1, \"seconds\");\n  }\n  if (err instanceof InvalidStateError) {\n    console.error(\"cannot replay in current state\");\n  }\n  throw err;\n}\n```\n\n## Notes\n\n- All requests send `X-Correlation-Id` automatically if not provided.\n- Requests retry transient `429/5xx` and network errors with jittered exponential backoff.\n- Most option/input shapes accept `signal?: AbortSignal` for request cancellation.\n- `writeFile` and `deleteFile` require optimistic concurrency via revision preconditions.\n- `RevisionConflictError` is thrown for HTTP `409` conflict responses.\n- `QueueFullError` is thrown for HTTP `429` with `code=queue_full` and surfaces `retryAfterSeconds`.\n- `InvalidStateError` is thrown for HTTP `409` with `code=invalid_state` (for replay preconditions).\n- `replayAdminEnvelope` and `replayAdminOp` call admin replay endpoints and require a token with `admin:replay`.\n- `getBackendStatus`, `getAdminIngressStatus`, and `getAdminSyncStatus` are admin APIs and require `admin:read` (or `admin:replay`).\n","readmeFilename":"README.md"}