icpay-bucket

TypeScript client for ICPay Bucket — on-chain encrypted file storage on the Internet Computer.

Canister: 6vbhm-nqaaa-aaaan-q6muq-cai · Version: 1.1.1

Docs: Package guide · API reference

Install

npm install icpay-bucket

Quick start

import { BucketClient } from "icpay-bucket"

const client = new BucketClient({ apiKey: process.env.BUCKET_API_KEY })

const up = await client.uploadFile({
  bucketId: "icp",          // bucket name or internal id
  path: "/hello.txt",
  data: new TextEncoder().encode("hello world\n"),
  contentType: "text/plain",
})
if ("err" in up) throw new Error(up.err)

console.log(client.publicUrl("icp", "/hello.txt"))
await client.listFiles("icp", 0, 20, process.env.BUCKET_API_KEY)
await client.deleteFile("icp", "/hello.txt")

Authentication

| Caller | Access | |---|---| | Bucket owner (Internet Identity) | All methods | | Read API key | listFiles, downloadFile, getFile, fileExists, listFolder, searchFiles, getFileMetadata | | Write API key | Upload, updateFile, moveFile, copyFile, tags, metadata, beginFileUpload, chunks | | Delete API key | deleteFile, bulkDeleteFiles |

Pass apiKey on each call, or set new BucketClient({ apiKey: "icp_cloud_…" }).

API reference

All methods return { ok: T } | { err: string }.

Buckets (owner)

| Method | Description | |---|---| | getBucketPrice(capacityGB) | Price quote for a tier | | createBucket(name, capacityGB, visibility) | Create bucket | | listBuckets() | List your buckets | | getBucket(id) | Bucket details | | getBucketStats(id) | Usage stats | | getRenewQuote(bucketId) | Renewal quote | | renewBucket(bucketId) | Renew plan | | updateBucket(bucketId, name?, visibility?) | Rename or change visibility | | deleteBucket(bucketId) | Delete bucket | | getBucketCycleStatus() | Canister cycle health (public) |

Upload

| Method | Description | |---|---| | uploadFile({ bucketId, path, data, contentType, apiKey? }) | Single call, ≤ ~1.85 MB | | beginFileUpload(bucketId, path, contentType, totalSize, apiKey?) | Start chunked session | | uploadFileChunk(uploadId, data) | Append chunk (legacy) | | uploadFileChunkIndexed(uploadId, chunkIndex, data) | Indexed chunk | | completeFileUpload(uploadId, apiKey?) | Finalize chunked upload | | getUpload(uploadId) | Session status (owner principal) | | cancelUpload(uploadId) | Cancel session (owner principal) |

Read

| Method | Description | |---|---| | downloadFile(bucketId, path, apiKey?) | File bytes | | getPublicFileUrl(bucketId, path) | Canister CDN URL | | listFiles(bucketId, page, pageSize, apiKey?) | Paginated file list | | getFile(bucketId, path, apiKey?) | File metadata record | | fileExists(bucketId, path, apiKey?) | Boolean check | | listFolder(bucketId, prefix, page, pageSize, apiKey?) | Files under prefix | | searchFiles(bucketId, query, page, pageSize, apiKey?) | Search by name | | getFileMetadata(bucketId, path, apiKey?) | JSON metadata string | | publicUrl(bucketName, path) | Local CDN URL helper (no call) |

Write

| Method | Description | |---|---| | updateFile(bucketId, path, { name?, contentType?, metadata?, apiKey? }) | Update fields | | moveFile(bucketId, source, dest, apiKey?) | Move file | | copyFile(bucketId, source, dest, apiKey?) | Copy file | | deleteFile(bucketId, path, apiKey?) | Delete file | | setFileTags(bucketId, path, tags, apiKey?) | Replace tags | | addFileTags(bucketId, path, tags, apiKey?) | Add tags | | removeFileTags(bucketId, path, tags, apiKey?) | Remove tags | | setFileMetadata(bucketId, path, metadata, apiKey?) | Set JSON metadata |

Bulk (max 20 per call)

| Method | Description | |---|---| | bulkDeleteFiles(bucketId, paths, apiKey?) | Delete many | | bulkMoveFiles(bucketId, operations, apiKey?) | { source, destination }[] | | bulkCopyFiles(bucketId, operations, apiKey?) | { source, destination }[] |

API keys (owner)

| Method | Description | |---|---| | createApiKey(bucketId, name, permissions) | Create key (secret shown once) | | listApiKeys(bucketId) | List keys | | getApiKey(bucketId, keyId) | Key details | | updateApiKey(bucketId, keyId, { name?, permissions? }) | Update key | | regenerateApiKey(bucketId, keyId) | New secret | | revokeApiKey(bucketId, keyId) | Revoke key |

Public CDN

Public buckets are served on the IC raw HTTP gateway:

https://6vbhm-nqaaa-aaaan-q6muq-cai.raw.icp0.io/cloud/{bucketName}{path}

Example: https://6vbhm-nqaaa-aaaan-q6muq-cai.raw.icp0.io/cloud/icp/hello.txt

Notes

• Paths must start with / and use an allowed extension (.txt, .webp, .pdf, …). Destinations like /file.txt.copy are rejected — use /file-copy.txt.
• bucketId accepts the public bucket name ("icp") or internal id on most methods.
• getUpload / cancelUpload require the bucket owner's Internet Identity principal (API key alone is not enough).

License

MIT