{"_id":"@builtbyecho/agent-storage-sdk","_rev":"6-13b6784f0fd423342ae434ab26025555","name":"@builtbyecho/agent-storage-sdk","dist-tags":{"latest":"0.1.4"},"versions":{"0.1.0":{"name":"@builtbyecho/agent-storage-sdk","version":"0.1.0","keywords":["agent-storage","x402","sdk","base","usdc","agents","storage"],"author":{"name":"BuiltByEcho"},"license":"MIT","_id":"@builtbyecho/agent-storage-sdk@0.1.0","maintainers":[{"name":"builtbyecho","email":"echo-token@agentmail.to"}],"homepage":"https://github.com/BuiltByEcho/agent-storage","bugs":{"url":"https://github.com/BuiltByEcho/agent-storage/issues"},"dist":{"shasum":"f3e8905096de8b1dc2fca1681bfec150db2e2723","tarball":"https://registry.npmjs.org/@builtbyecho/agent-storage-sdk/-/agent-storage-sdk-0.1.0.tgz","fileCount":18,"integrity":"sha512-Vh7+YRcHnrC99qAuWT+JWUv9lg7W70Rhej+i8EsW5ZGJVjnQjQ0+dGJ4tSnzVZgaR6Hf+QskKW6UrbOwFrv5/w==","signatures":[{"sig":"MEQCIQC1vRvC1pRNTkvSi3n+s3c2GG8uvdZmccg17mnrO1fRgQIfP8pfaLiun05ZoknX1KOeQpmrUg0l5oyRUm6Z4CoXsg==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":23624},"main":"dist/index.js","types":"dist/index.d.ts","engines":{"node":">=20"},"exports":{".":{"types":"./dist/index.d.ts","default":"./dist/index.js"}},"gitHead":"b01c9c851029f4018f266923628ceb007cce87e7","scripts":{"lint":"tsc --noEmit","test":"vitest run","build":"tsc","prepublishOnly":"npm run lint && npm test && npm run build"},"_npmUser":{"name":"builtbyecho","email":"echo-token@agentmail.to"},"deprecated":"Renamed to @builtbyecho/vaultline-sdk. Use npm install @builtbyecho/vaultline-sdk.","repository":{"url":"git+https://github.com/BuiltByEcho/agent-storage.git","type":"git"},"_npmVersion":"11.12.1","description":"TypeScript SDK for AgentStorage — x402-native file storage for agents","directories":{},"sideEffects":false,"_nodeVersion":"24.15.0","dependencies":{"viem":"^2.28.0","@x402/evm":"^2.11.0","@x402/core":"^2.11.0"},"_hasShrinkwrap":false,"devDependencies":{"vitest":"^3.1.0","typescript":"^5.8.0"},"_npmOperationalInternal":{"tmp":"tmp/agent-storage-sdk_0.1.0_1778646090590_0.4235323794538728","host":"s3://npm-registry-packages-npm-production"}},"0.1.1":{"name":"@builtbyecho/agent-storage-sdk","version":"0.1.1","keywords":["agent-storage","x402","sdk","base","usdc","agents","storage"],"author":{"name":"BuiltByEcho"},"license":"MIT","_id":"@builtbyecho/agent-storage-sdk@0.1.1","maintainers":[{"name":"builtbyecho","email":"echo-token@agentmail.to"}],"homepage":"https://github.com/BuiltByEcho/agent-storage","bugs":{"url":"https://github.com/BuiltByEcho/agent-storage/issues"},"dist":{"shasum":"9b03bed0da6745886c58311ec4cc48d8ab24fca0","tarball":"https://registry.npmjs.org/@builtbyecho/agent-storage-sdk/-/agent-storage-sdk-0.1.1.tgz","fileCount":22,"integrity":"sha512-rNSlwHi/zD5L9c0efXjQinh5RK9t3qph/qugiBuh5gX0t8tiNIH32QPxnX5ZsgThF4tWP9Ac638l3FE/YPCZDA==","signatures":[{"sig":"MEYCIQCOqUK0CM0ZtehcJUR6EWF9nMNyPYCG4xTBmGOjELW6pgIhAL2TCFBOUdqP/rG7kkdG+0Zi3CLe5qPobqHA9SNUlfI1","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":32819},"main":"dist/index.js","types":"dist/index.d.ts","engines":{"node":">=20"},"exports":{".":{"types":"./dist/index.d.ts","default":"./dist/index.js"}},"gitHead":"76e7a68f3d2f97e50aac6d4e7a7e05787516e84c","scripts":{"lint":"tsc --noEmit","test":"vitest run","build":"tsc","prepublishOnly":"npm run lint && npm test && npm run build"},"_npmUser":{"name":"builtbyecho","email":"echo-token@agentmail.to"},"deprecated":"Renamed to @builtbyecho/vaultline-sdk. Use npm install @builtbyecho/vaultline-sdk.","repository":{"url":"git+https://github.com/BuiltByEcho/agent-storage.git","type":"git"},"_npmVersion":"11.12.1","description":"TypeScript SDK for AgentStorage — x402-native file storage for agents with typed errors and request timeouts","directories":{},"sideEffects":false,"_nodeVersion":"24.15.0","dependencies":{"viem":"^2.28.0","@x402/evm":"^2.11.0","@x402/core":"^2.11.0"},"_hasShrinkwrap":false,"devDependencies":{"vitest":"^3.1.0","typescript":"^5.8.0"},"_npmOperationalInternal":{"tmp":"tmp/agent-storage-sdk_0.1.1_1778648632490_0.7721456644776103","host":"s3://npm-registry-packages-npm-production"}},"0.1.2":{"name":"@builtbyecho/agent-storage-sdk","version":"0.1.2","keywords":["vaultline","agent-storage","x402","sdk","base","usdc","agents","storage"],"author":{"name":"BuiltByEcho"},"license":"MIT","_id":"@builtbyecho/agent-storage-sdk@0.1.2","maintainers":[{"name":"builtbyecho","email":"echo-token@agentmail.to"}],"homepage":"https://builtbyecho.xyz/#vaultline","bugs":{"url":"https://github.com/BuiltByEcho/agent-storage/issues"},"dist":{"shasum":"893d027b78958d91052edff525ddce4ba9fdffe3","tarball":"https://registry.npmjs.org/@builtbyecho/agent-storage-sdk/-/agent-storage-sdk-0.1.2.tgz","fileCount":22,"integrity":"sha512-8vcMXIlrNc0S5HGzYNlAUhBqRwohc9Hj6WjItkeGCk250yPgLpQen9XBHG2pWgmzSvtNRnSFowgY10gKXiLQLQ==","signatures":[{"sig":"MEYCIQCnGs96UIv4KsdA+96E96UkxEhRRllS1pVG2E13tpxk4gIhAOlNV+VjFDBc6BCoG4RZZreqS1JG2RmDSJ+8uNWl0KJM","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":33137},"main":"dist/index.js","types":"dist/index.d.ts","engines":{"node":">=20"},"exports":{".":{"types":"./dist/index.d.ts","default":"./dist/index.js"}},"gitHead":"cf75d01913f495d16cbfa4f5068aa826507b512f","scripts":{"lint":"tsc --noEmit","test":"vitest run","build":"tsc","prepublishOnly":"npm run lint && npm test && npm run build"},"_npmUser":{"name":"builtbyecho","email":"echo-token@agentmail.to"},"deprecated":"Renamed to @builtbyecho/vaultline-sdk. Use npm install @builtbyecho/vaultline-sdk.","repository":{"url":"git+https://github.com/BuiltByEcho/agent-storage.git","type":"git"},"_npmVersion":"11.12.1","description":"TypeScript SDK for Vaultline — x402-native file storage for agents with typed errors and request timeouts","directories":{},"sideEffects":false,"_nodeVersion":"24.15.0","dependencies":{"viem":"^2.28.0","@x402/evm":"^2.11.0","@x402/core":"^2.11.0"},"_hasShrinkwrap":false,"devDependencies":{"vitest":"^3.1.0","typescript":"^5.8.0"},"_npmOperationalInternal":{"tmp":"tmp/agent-storage-sdk_0.1.2_1778685178439_0.7087405082494926","host":"s3://npm-registry-packages-npm-production"}},"0.1.3":{"name":"@builtbyecho/agent-storage-sdk","version":"0.1.3","keywords":["vaultline","agent-storage","x402","sdk","base","usdc","agents","storage"],"author":{"name":"BuiltByEcho"},"license":"MIT","_id":"@builtbyecho/agent-storage-sdk@0.1.3","maintainers":[{"name":"builtbyecho","email":"echo-token@agentmail.to"}],"homepage":"https://builtbyecho.xyz/#vaultline","bugs":{"url":"https://github.com/BuiltByEcho/agent-storage/issues"},"dist":{"shasum":"d67c21863b0479d7bb2688e560508140051ac747","tarball":"https://registry.npmjs.org/@builtbyecho/agent-storage-sdk/-/agent-storage-sdk-0.1.3.tgz","fileCount":22,"integrity":"sha512-2Z1n6oSJIX9mbyxp6ZrlNW06xALffu4ySXaPnNRWIxBtzyEIYNpYW6dJIsOYk7/R6BOLp7Th49O4Bxk8dP+l2Q==","signatures":[{"sig":"MEUCIQDTAstbXmK8Jz9OX0c48ozr+DR0vQermkW1RfBvLzsjwwIgDJ1OAIxxXJ9Sk4ofkuSQbSO4pMVoONwG3R/HpNOtv9o=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@builtbyecho%2fagent-storage-sdk@0.1.3","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":33529},"main":"dist/index.js","types":"dist/index.d.ts","engines":{"node":">=20"},"exports":{".":{"types":"./dist/index.d.ts","default":"./dist/index.js"}},"gitHead":"6d17d9c5042543de5bba6114aeb152eac4675fc9","scripts":{"test":"node -e \"import('./dist/index.js').then(() => console.log('agent-storage-sdk import ok'))\"","smoke":"npm test","prepublishOnly":"npm test"},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:09883b5e-7be7-4361-8601-0f6f9d634afa"}},"overrides":{"ws":"^8.21.0","esbuild":"^0.28.1"},"repository":{"url":"git+https://github.com/BuiltByEcho/vaultline.git","type":"git","directory":"packages/agent-storage-sdk"},"_npmVersion":"11.17.0","description":"TypeScript SDK for Vaultline — x402-native file storage for agents with typed errors and request timeouts","directories":{},"sideEffects":false,"_nodeVersion":"22.22.3","dependencies":{"viem":"^2.28.0","@x402/evm":"^2.11.0","@x402/core":"^2.11.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"vitest":"^3.1.0","typescript":"^5.8.0"},"_npmOperationalInternal":{"tmp":"tmp/agent-storage-sdk_0.1.3_1782173864560_0.5387630885073356","host":"s3://npm-registry-packages-npm-production"}},"0.1.4":{"name":"@builtbyecho/agent-storage-sdk","version":"0.1.4","description":"TypeScript SDK for Vaultline — x402-native file storage for agents with typed errors and request timeouts","main":"dist/index.js","types":"dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","default":"./dist/index.js"}},"sideEffects":false,"scripts":{"test":"node -e \"import('./dist/index.js').then(() => console.log('agent-storage-sdk import ok'))\"","smoke":"npm test","prepublishOnly":"npm test"},"keywords":["vaultline","agent-storage","x402","sdk","base","usdc","agents","storage","builtbyecho","agent-tooling","developer-tools"],"author":{"name":"BuiltByEcho"},"license":"MIT","homepage":"https://builtbyecho.xyz/#vaultline","repository":{"type":"git","url":"git+https://github.com/BuiltByEcho/vaultline.git","directory":"packages/agent-storage-sdk"},"bugs":{"url":"https://github.com/BuiltByEcho/agent-storage/issues"},"engines":{"node":">=20"},"dependencies":{"@x402/core":"^2.11.0","@x402/evm":"^2.11.0","viem":"^2.28.0"},"overrides":{"ws":"^8.21.0","esbuild":"^0.28.1"},"devDependencies":{"typescript":"^5.8.0","vitest":"^3.1.0"},"publishConfig":{"access":"public"},"gitHead":"e511c7a327343bc15764ed5e8770606087ee6aca","_id":"@builtbyecho/agent-storage-sdk@0.1.4","_nodeVersion":"22.23.1","_npmVersion":"11.18.0","dist":{"integrity":"sha512-o5FAm75CvlOXfMo7PzPEdSScUiaxdOWv8qL474Wrq6hvWZm3OMkOcONUgvD2l2fbVSEzPDWYMSX50pbLftaY7w==","shasum":"7bd084980727ad07edce42707677bad68f53c3f6","tarball":"https://registry.npmjs.org/@builtbyecho/agent-storage-sdk/-/agent-storage-sdk-0.1.4.tgz","fileCount":22,"unpackedSize":34139,"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@builtbyecho%2fagent-storage-sdk@0.1.4","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIGPUR9RsharprtUZ30q/wmFOTOxDnmq5HIziXuG5cDKpAiEArq7/9QcAUAiq9lok9BSN8lj6d0FqpKWJCqt9JHahinE="}]},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:09883b5e-7be7-4361-8601-0f6f9d634afa"}},"directories":{},"maintainers":[{"name":"builtbyecho","email":"builtbyecho@agentmail.to"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/agent-storage-sdk_0.1.4_1783255415982_0.4287784244752868"},"_hasShrinkwrap":false}},"time":{"created":"2026-05-13T04:21:30.470Z","modified":"2026-07-05T12:43:36.400Z","0.1.0":"2026-05-13T04:21:30.737Z","0.1.1":"2026-05-13T05:03:52.630Z","0.1.2":"2026-05-13T15:12:58.596Z","0.1.3":"2026-06-23T00:17:44.695Z","0.1.4":"2026-07-05T12:43:36.144Z"},"bugs":{"url":"https://github.com/BuiltByEcho/agent-storage/issues"},"author":{"name":"BuiltByEcho"},"license":"MIT","homepage":"https://builtbyecho.xyz/#vaultline","keywords":["vaultline","agent-storage","x402","sdk","base","usdc","agents","storage","builtbyecho","agent-tooling","developer-tools"],"repository":{"type":"git","url":"git+https://github.com/BuiltByEcho/vaultline.git","directory":"packages/agent-storage-sdk"},"description":"TypeScript SDK for Vaultline — x402-native file storage for agents with typed errors and request timeouts","maintainers":[{"name":"builtbyecho","email":"builtbyecho@agentmail.to"}],"readme":"# @builtbyecho/agent-storage-sdk\n\nTypeScript SDK for **Vaultline** — x402-native storage rails for autonomous agents.\n\nLive API: `https://storage.builtbyecho.xyz`\n\nThis SDK removes the biggest friction points for developers:\n- x402 pay-and-retry handling\n- wallet-auth header creation for private storage\n- typed failures you can safely catch in agents and CLIs\n- default request timeouts so long-running agent workflows do not hang forever\n\n## Fits in the Echo agent toolchain\n\nUse `@builtbyecho/agent-storage-sdk` when an agent needs to store files, handoffs, generated artifacts, or private workspace data behind wallet-aware access rules. It is the storage primitive that can sit underneath public build logs, private agent memory, and x402-native workflows.\n\nThis is the file/storage layer for Echo builds: agents can upload, read back, catch typed failures, and avoid hanging forever on network calls.\n\n## Refresh smoke\n\n```bash\nnpm test\nnpm run smoke\nnpm pack --dry-run --json\n```\n\n## Current status\n\nLive tiers supported by the SDK:\n- `open`\n- `private`\n\nPlanned later:\n- `encrypted` *(coming soon)*\n\n## Install\n\n```bash\nnpm install @builtbyecho/agent-storage-sdk viem\n```\n\n## Quick start\n\n```ts\nimport { privateKeyToAccount } from 'viem/accounts';\nimport { AgentStorageClient } from '@builtbyecho/agent-storage-sdk';\n\nconst account = privateKeyToAccount(process.env.X402_PAYER_PRIVATE_KEY as `0x${string}`);\n\nconst client = new AgentStorageClient({\n  baseUrl: 'https://storage.builtbyecho.xyz',\n  account,\n  timeoutMs: 30_000,\n});\n```\n\n## Open upload\n\n```ts\nconst result = await client.upload('workspace/demo.txt', 'hello from sdk', {\n  contentType: 'text/plain',\n});\n\nconsole.log(result.data);\n```\n\n## Private upload\n\n```ts\nconst result = await client.upload('workspace/secret.txt', 'private notes', {\n  tier: 'private',\n  contentType: 'text/plain',\n  allowedWallets: ['0x1234567890123456789012345678901234567890'],\n});\n```\n\n## Private read\n\n```ts\nconst result = await client.downloadText('workspace/secret.txt', {\n  tier: 'private',\n});\n\nconsole.log(result.text);\n```\n\n## Typed errors\n\nSDK helper methods throw `AgentStorageError` for non-2xx responses after any x402 retry is complete. The parsed JSON/text response body is attached for logging, retries, and agent decision-making.\n\n```ts\nimport { AgentStorageClient, AgentStorageError } from '@builtbyecho/agent-storage-sdk';\n\ntry {\n  await client.downloadText('workspace/missing.txt');\n} catch (error) {\n  if (error instanceof AgentStorageError && error.status === 404) {\n    console.log('not found', error.body);\n  } else {\n    throw error;\n  }\n}\n```\n\n## Timeouts\n\nRequests default to a 30 second timeout using `AbortSignal.timeout`. Override per client, or pass `0` to disable.\n\n```ts\nconst client = new AgentStorageClient({\n  baseUrl: 'https://storage.builtbyecho.xyz',\n  account,\n  timeoutMs: 10_000,\n});\n```\n\n## What the SDK handles automatically\n\n- `402 Payment Required` parsing\n- x402 payment payload creation\n- retry with payment headers\n- private-tier wallet auth headers\n- typed error creation with parsed response bodies\n- default request timeouts\n\n## Pricing notes\n\n- reads under `1 MB` are free\n- paid reads above the free threshold have a `$0.001` minimum to avoid dust-sized x402 payments\n- write and storage pricing are exposed by the live API metadata/routes\n\n## Notes\n\n- use `open` for shared/public-by-key files\n- use `private` for wallet-restricted files\n- do not treat `encrypted` as a live tier yet\n\n## Release Automation\n\nThis package is published from GitHub Actions using npm Trusted Publishing with provenance. Releases are built on GitHub-hosted runners and no long-lived npm publish token is required.\n","readmeFilename":"README.md"}