{"_id":"@caterpillar-labs/zeos-zfilesystem","_rev":"3-e6e0f3870c1ab80d07faed6d8e219ab6","name":"@caterpillar-labs/zeos-zfilesystem","dist-tags":{"latest":"0.1.1"},"versions":{"0.1.0":{"name":"@caterpillar-labs/zeos-zfilesystem","version":"0.1.0","keywords":["zeos","zfilesystem","cloak","eosio","antelope","filesystem","sdk"],"author":{"name":"Caterpillar Labs"},"license":"MIT","_id":"@caterpillar-labs/zeos-zfilesystem@0.1.0","maintainers":[{"name":"thybow","email":"tmilville.pro@gmail.com"}],"homepage":"https://github.com/Caterpillar-Labs/zeos-zfilesystem#readme","bugs":{"url":"https://github.com/Caterpillar-Labs/zeos-zfilesystem/issues"},"dist":{"shasum":"bb7d973ffa509d051ab9e86f4ac84922feccb6c1","tarball":"https://registry.npmjs.org/@caterpillar-labs/zeos-zfilesystem/-/zeos-zfilesystem-0.1.0.tgz","fileCount":15,"integrity":"sha512-oyF9kBWywzD4/1crGCNow1K/PaSp0dgmtYaB7ezYIlhXtN/ykUCdqkW6BQl0W2j6fiN4+mHaig7FEM0JFUNkMQ==","signatures":[{"sig":"MEQCIFUd77NcmlmmOi+kF23j4KMUEyDsz6EjqcM62DQ9IYy3AiAA+G5NG9mbYP8CuuvJaMpwt6kClP/hwY7StlzZH30cBg==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":2417680},"main":"./dist/index.cjs","type":"module","types":"./dist/index.d.ts","module":"./dist/index.mjs","browser":"./dist/zeos-zfilesystem.js","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.mjs","require":"./dist/index.cjs"},"./global":"./dist/zeos-zfilesystem.global.js","./browser":{"types":"./dist/index.d.ts","import":"./dist/zeos-zfilesystem.js"},"./package.json":"./package.json"},"gitHead":"bb71cbf838e41b579b3684bb402364d504084d93","scripts":{"test":"vitest run","build":"tsup","clean":"rm -rf dist coverage","typecheck":"tsc --noEmit","test:watch":"vitest","prepublishOnly":"npm run clean && npm run typecheck && npm run test && npm run build"},"_npmUser":{"name":"thybow","email":"tmilville.pro@gmail.com"},"repository":{"url":"git+https://github.com/Caterpillar-Labs/zeos-zfilesystem.git","type":"git"},"_npmVersion":"11.12.1","description":"Protocol SDK for Zeos zfilesystem: URI scheme, encodings, on-chain read/decode, and transaction action builders.","directories":{},"sideEffects":false,"_nodeVersion":"26.0.0","dependencies":{},"publishConfig":{"access":"public","registry":"https://registry.npmjs.org/"},"_hasShrinkwrap":false,"devDependencies":{"tsup":"^8.0.0","vitest":"^3.0.0","typescript":"^5.0.0","@types/node":"^20.0.0","@wharfkit/antelope":"^1.0.13"},"peerDependencies":{"@wharfkit/antelope":"^1.0.13"},"_npmOperationalInternal":{"tmp":"tmp/zeos-zfilesystem_0.1.0_1780526801439_0.9276051281103208","host":"s3://npm-registry-packages-npm-production"}},"0.1.1":{"name":"@caterpillar-labs/zeos-zfilesystem","version":"0.1.1","keywords":["zeos","zfilesystem","cloak","eosio","antelope","filesystem","sdk"],"author":{"name":"Caterpillar Labs"},"license":"MIT","_id":"@caterpillar-labs/zeos-zfilesystem@0.1.1","maintainers":[{"name":"thybow","email":"tmilville.pro@gmail.com"}],"homepage":"https://github.com/Caterpillar-Labs/zeos-zfilesystem#readme","bugs":{"url":"https://github.com/Caterpillar-Labs/zeos-zfilesystem/issues"},"dist":{"shasum":"8c2a9a7e6e42db6a255425c2e6e33393a2cf2e0b","tarball":"https://registry.npmjs.org/@caterpillar-labs/zeos-zfilesystem/-/zeos-zfilesystem-0.1.1.tgz","fileCount":15,"integrity":"sha512-ZNzX8nqo3qhrTwrv+DtgWoAPWyQBOqMoZycab3W41Z40OMsL4UsKSISfmBjohlD6x4Ti3a3Q0F0uIWR/h3tslg==","signatures":[{"sig":"MEQCIGMetH2YPnf/A/sBJXq3HszqlujZisv2tdagHHYT4Sm9AiAgzsnTMe55OYrKzvZWZ3oXlHGgnyKOIDOB+SdyW6lfYQ==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":2416778},"main":"./dist/index.cjs","type":"module","types":"./dist/index.d.ts","module":"./dist/index.mjs","browser":"./dist/zeos-zfilesystem.js","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.mjs","require":"./dist/index.cjs"},"./global":"./dist/zeos-zfilesystem.global.js","./browser":{"types":"./dist/index.d.ts","import":"./dist/zeos-zfilesystem.js"},"./package.json":"./package.json"},"gitHead":"4efdbf55fb9c2dc1e06290410f42f8abc980d2d7","scripts":{"test":"vitest run","build":"tsup","clean":"rm -rf dist coverage","typecheck":"tsc --noEmit","test:watch":"vitest","prepublishOnly":"npm run clean && npm run typecheck && npm run test && npm run build"},"_npmUser":{"name":"thybow","email":"tmilville.pro@gmail.com"},"repository":{"url":"git+https://github.com/Caterpillar-Labs/zeos-zfilesystem.git","type":"git"},"_npmVersion":"11.12.1","description":"Protocol SDK for Zeos zfilesystem: URI scheme, encodings, on-chain read/decode, and transaction action builders.","directories":{},"sideEffects":false,"_nodeVersion":"26.0.0","dependencies":{},"publishConfig":{"access":"public","registry":"https://registry.npmjs.org/"},"_hasShrinkwrap":false,"devDependencies":{"tsup":"^8.0.0","vitest":"^3.0.0","typescript":"^5.0.0","@types/node":"^20.0.0","@wharfkit/antelope":"^1.0.13"},"peerDependencies":{"@wharfkit/antelope":"^1.0.13"},"_npmOperationalInternal":{"tmp":"tmp/zeos-zfilesystem_0.1.1_1780527290861_0.589708332518055","host":"s3://npm-registry-packages-npm-production"}}},"time":{"created":"2026-06-03T22:46:41.218Z","modified":"2026-06-04T00:12:29.404Z","0.1.0":"2026-06-03T22:46:41.603Z","0.1.1":"2026-06-03T22:54:51.006Z"},"bugs":{"url":"https://github.com/Caterpillar-Labs/zeos-zfilesystem/issues"},"author":{"name":"Caterpillar Labs"},"license":"MIT","homepage":"https://github.com/Caterpillar-Labs/zeos-zfilesystem#readme","keywords":["zeos","zfilesystem","cloak","eosio","antelope","filesystem","sdk"],"repository":{"url":"git+https://github.com/Caterpillar-Labs/zeos-zfilesystem.git","type":"git"},"description":"Protocol SDK for Zeos zfilesystem: URI scheme, encodings, on-chain read/decode, and transaction action builders.","maintainers":[{"email":"tmilville.pro@gmail.com","name":"thybow"},{"email":"matthias.schoenebeck@gmail.com","name":"mschoenebeck"}],"readme":"# @caterpillar-labs/zeos-zfilesystem\n\nProtocol SDK for the Zeos **zfilesystem** contract: URI scheme, data encodings, on-chain read/decode, virtual directory tree, and EOSIO action builders.\n\nPublished under [Caterpillar-Labs](https://github.com/Caterpillar-Labs) alongside [`zeos-link`](https://github.com/Caterpillar-Labs/zeos-link).\n\nnpm: `@caterpillar-labs/zeos-zfilesystem` (replaces deprecated unscoped `zeos-zfilesystem`).\n\nThis package is **UI-free** and **wallet-free**. Bring your own RPC client (`ZfsChainClient`) and transaction signer.\n\n---\n\n## TL;DR for humans and AI agents\n\nUse this package when a web app or script needs to:\n\n- parse or build `zfilesystem` asset URIs,\n- list virtual directories from flat on-chain filenames,\n- read/decode file bytes from chain traces,\n- build `upload` / `rename` / `erase` EOSIO actions.\n\nCore flow:\n\n```ts\nimport {\n  parseZFilesystemAssetUri,\n  createFetchZfsChainClient,\n  fetchFilesZFilesystem,\n  buildUploadActions,\n  chunkFile,\n} from \"@caterpillar-labs/zeos-zfilesystem\";\n\nconst parsed = parseZFilesystemAssetUri(\"jungle4://fs@zfilesystem:/alice/readme.txt\");\n\nconst client = createFetchZfsChainClient({ rpcUrl: \"https://your-node.example\" });\nconst files = await fetchFilesZFilesystem({\n  client,\n  contract: \"zfilesystem\",\n  owner: \"alice\",\n});\n\nconst uploadActions = buildUploadActions({\n  contract: \"zfilesystem\",\n  owner: \"alice\",\n  filename: \"docs/guide.html\",\n  encoding: \"b122\",\n  chunks: await chunkFile(file, 128_000),\n});\n```\n\nImportant:\n\n- Peer dependency: `@wharfkit/antelope` (ABI decode for block traces).\n- The SDK builds neutral EOSIO actions; signing/submitting is your app's job.\n- Chunk bytes live in block traces (top-level `upload` actions), not in RAM.\n- On-chain filenames are flat paths (`icons/a.png`); directories are client-side only.\n\n---\n\n## Installation\n\n```bash\nnpm install @caterpillar-labs/zeos-zfilesystem @wharfkit/antelope\n```\n\n---\n\n## Usage with npm / bundlers\n\n```ts\nimport { parseZFilesystemAssetUri, listZfsDirectoryChildren } from \"@caterpillar-labs/zeos-zfilesystem\";\n```\n\n---\n\n## Usage as a browser ES module\n\nCopy the built browser file into your public assets and import it directly:\n\n```html\n<script type=\"module\">\n  import { parseZFilesystemAssetUri } from \"/zeos-zfilesystem.js\";\n\n  const parsed = parseZFilesystemAssetUri(\"jungle4://fs@zfilesystem:/alice/readme.txt\");\n</script>\n```\n\nWhen installed from npm, the browser ESM build is available at:\n\n```txt\nnode_modules/@caterpillar-labs/zeos-zfilesystem/dist/zeos-zfilesystem.js\n```\n\nOr via the export subpath:\n\n```ts\nimport { parseZFilesystemAssetUri } from \"@caterpillar-labs/zeos-zfilesystem/browser\";\n```\n\n---\n\n## Usage as a global browser script\n\n```html\n<script src=\"/zeos-zfilesystem.global.js\"></script>\n<script>\n  const parsed = ZEOSZFilesystem.parseZFilesystemAssetUri(\"jungle4://fs@zfilesystem:/alice/readme.txt\");\n</script>\n```\n\nPrefer the ESM build for modern apps.\n\n---\n\n## URI scheme\n\n```txt\n<chainName>://fs@<contract>:/<owner>/<relative/path>\n```\n\nExamples:\n\n- `jungle4://fs@zfilesystem:/alice/readme.txt`\n- `vaulta://fs@zfilesystem:/bob/icons/logo.png`\n\n```typescript\nimport { parseZFilesystemAssetUri, buildZFilesystemAssetUriFromContext } from \"@caterpillar-labs/zeos-zfilesystem\";\n\nconst parsed = parseZFilesystemAssetUri(\"jungle4://fs@zfilesystem:/alice/readme.txt\");\n\nconst uri = buildZFilesystemAssetUriFromContext(\n  { chainName: \"jungle4\", rpcUrl: \"https://...\", zfilesystemContract: \"zfilesystem\" },\n  \"alice\",\n  \"readme.txt\",\n);\n```\n\n---\n\n## Chain client\n\n```typescript\nimport {\n  createFetchZfsChainClient,\n  fetchFilesZFilesystem,\n  fetchFileContentZFilesystemWithEncoding,\n} from \"@caterpillar-labs/zeos-zfilesystem\";\n\nconst client = createFetchZfsChainClient({ rpcUrl: \"https://your-node.example\" });\n\nconst files = await fetchFilesZFilesystem({\n  client,\n  contract: \"zfilesystem\",\n  owner: \"alice\",\n});\n\nconst content = await fetchFileContentZFilesystemWithEncoding({\n  client,\n  contract: \"zfilesystem\",\n  owner: \"alice\",\n  filename: \"readme.txt\",\n  chunkIds: files.find((f) => f.filename === \"readme.txt\")?.chunks ?? [],\n});\n```\n\nImplement `ZfsChainClient` to plug into your own RPC layer (failover, auth, etc.).\n\n---\n\n## Upload / rename / erase (action builders)\n\n```typescript\nimport { buildUploadActions, buildRenameAction, buildEraseAction, chunkFile } from \"@caterpillar-labs/zeos-zfilesystem\";\n\nconst chunks = await chunkFile(file, 128_000);\n\nconst uploadActions = buildUploadActions({\n  contract: \"zfilesystem\",\n  owner: \"alice\",\n  filename: \"docs/guide.html\",\n  encoding: \"b122\",\n  chunks,\n});\n\nconst renameAction = buildRenameAction({\n  contract: \"zfilesystem\",\n  owner: \"alice\",\n  filename: \"old.txt\",\n  newFilename: \"new.txt\",\n});\n\nconst eraseAction = buildEraseAction({\n  contract: \"zfilesystem\",\n  owner: \"alice\",\n  filename: \"old.txt\",\n});\n```\n\n---\n\n## Encodings\n\n| Prefix | Format |\n|--------|--------|\n| `b64:` | Base64 |\n| `hex:` | Hexadecimal |\n| `b122:` | Base122 (compact binary transport) |\n\n```typescript\nimport { zfsEncodeDataBytes } from \"@caterpillar-labs/zeos-zfilesystem\";\n\nconst encoded = zfsEncodeDataBytes(new TextEncoder().encode(\"hello\"), \"b122\");\n```\n\n---\n\n## Virtual directory tree\n\n```typescript\nimport { listZfsDirectoryChildren } from \"@caterpillar-labs/zeos-zfilesystem\";\n\nconst { directories, files } = listZfsDirectoryChildren(\n  [\"readme.txt\", \"icons/a.png\", \"icons/b.png\"],\n  \"icons\",\n);\n```\n\n---\n\n## Contract alignment\n\nActions and tables match `zfilesystem` in the Zeos contracts reference:\n\n- Actions: `upload`, `rename`, `erase`\n- Table: `fs` (scope: owner)\n- Legacy table: `chunks` (optional, for older deployments)\n\n---\n\n## What this SDK does not do\n\nThis SDK does **not**:\n\n- manage React state or explorer UI,\n- sign or submit transactions,\n- choose the app's active network,\n- replace server-side authorization.\n\nKeep those responsibilities in your app.\n\n---\n\n## Development\n\nInstall dependencies:\n\n```bash\nnpm install\n```\n\nTypecheck:\n\n```bash\nnpm run typecheck\n```\n\nRun tests:\n\n```bash\nnpm test\n```\n\nBuild:\n\n```bash\nnpm run build\n```\n\nThe build outputs:\n\n```txt\ndist/index.mjs\ndist/index.cjs\ndist/index.d.ts\ndist/index.d.cts\ndist/zeos-zfilesystem.js\ndist/zeos-zfilesystem.min.js\ndist/zeos-zfilesystem.global.js\n```\n\nExamples: see [`examples/README.md`](examples/README.md).\n\n---\n\n## Smoke test package exports\n\nFrom outside the repo:\n\n```bash\nmkdir /tmp/zeos-zfilesystem-smoke\ncd /tmp/zeos-zfilesystem-smoke\nnpm init -y\nnpm install @caterpillar-labs/zeos-zfilesystem @wharfkit/antelope\n```\n\nTest ESM:\n\n```bash\nnode -e \"import('@caterpillar-labs/zeos-zfilesystem').then(m => console.log(typeof m.parseZFilesystemAssetUri))\"\n```\n\nExpected:\n\n```txt\nfunction\n```\n\nTest CJS:\n\n```bash\nnode -e \"const m = require('@caterpillar-labs/zeos-zfilesystem'); console.log(typeof m.parseZFilesystemAssetUri)\"\n```\n\nExpected:\n\n```txt\nfunction\n```\n\n---\n\n## Publishing\n\nBefore publishing:\n\n```bash\nnpm run typecheck\nnpm test\nnpm run build\nnpm pack --dry-run\n```\n\nPublish:\n\n```bash\nnpm publish\n```\n\nTag release:\n\n```bash\ngit tag v0.1.0\ngit push origin main --tags\n```\n\n---\n\n## License\n\nMIT\n","readmeFilename":"README.md"}