@3mate/walrus-sponsor-sdk 0.2.1 → 0.3.0

package/dist/cli.js

@@ -444,6 +444,7 @@ COMMANDS
   fund <id> --coin <id>
 
   url <blob_id>               Print aggregator URL
+  docs                        Print full documentation (for AI agents)
 
 FLAGS
   --pretty                    Pretty-print JSON output
@@ -456,6 +457,143 @@ EXAMPLES
   krilly cost --size 1048576 --epochs 3
 `);
 }
+function docs() {
+  console.log(`
+# Krilly \u2014 Walrus Sponsor Service SDK & CLI
+# Full documentation for AI agents and developers
+# https://walrus-sponsor.krill.tube/docs
+
+## What is this?
+Krilly is the SDK and CLI for the Walrus Sponsor Service \u2014 sponsored decentralized
+blob storage on the Walrus network (built on Sui blockchain). You upload files,
+the platform pays for storage, and the blob is stored permanently on Walrus.
+
+## Key Concepts
+- WAL: Native token of Walrus, used to pay for storage. 1 WAL = 1,000,000,000 FROST.
+- Epoch: Storage time unit. 1 epoch \u2248 14 days on mainnet. Max 53 epochs.
+- SponsoredBlob: On-chain Sui object wrapping a Walrus blob with creator/sponsor tracking.
+- creator_address: Any valid Sui address (0x + 64 hex). The owner of the blob.
+  The creator does NOT need a wallet or tokens \u2014 the sponsor pays.
+- blob_id: Walrus content ID (Base64 string). Used for reading/downloading.
+- object_id / sponsored_blob_id: On-chain object ID (0x...). Used for management ops.
+- Workspace: Billing boundary with its own balance and API keys.
+
+## Setup
+1. Get an API key from https://walrus-sponsor.krill.tube (sign in \u2192 create workspace \u2192 API Keys)
+2. Run: krilly config set-key <your_api_key>
+
+## CLI Commands
+
+### Upload a file
+  krilly upload <file_path> --creator <sui_address> [--epochs <n>] [--deletable]
+  Example: krilly upload ./photo.jpg --creator 0x123...abc --epochs 5
+  Returns: JSON with blob_id, sponsored_blob_id, tx_digest, wal_cost, status
+
+### List blobs
+  krilly blobs [--status active|expired|deleted] [--limit <n>] [--offset <n>] [--pretty]
+  Example: krilly blobs --status active --limit 10 --pretty
+
+### Get blob details
+  krilly blob <object_id>
+  Example: krilly blob 0xabc...
+
+### Estimate cost
+  krilly cost --size <bytes> --epochs <n> [--pretty]
+  Example: krilly cost --size 1048576 --epochs 3 --pretty
+
+### Get download URL
+  krilly url <blob_id>
+  Returns a public aggregator URL. No auth needed to read blobs.
+
+### Check service
+  krilly health
+  krilly epoch
+
+### Delete blob (advanced \u2014 requires on-chain object IDs)
+  krilly delete <sponsored_blob_id> --system-object <walrus_system_object_id>
+
+### Extend storage (advanced \u2014 requires on-chain object IDs)
+  krilly extend <sponsored_blob_id> --epochs <n> --system-object <id> --payment-coin <id>
+
+### Fund blob (advanced \u2014 requires on-chain coin ID)
+  krilly fund <sponsored_blob_id> --coin <funds_coin_id>
+
+## SDK (programmatic usage in Node.js / TypeScript)
+
+  import { WalrusSponsor } from "krilly";
+
+  const client = new WalrusSponsor({
+    apiKey: "sbk_live_...",
+    baseUrl: "https://walrus-sponsor.krill.tube", // optional, this is the default
+  });
+
+  // Upload
+  const result = await client.upload("./file.txt", {
+    creatorAddress: "0x...",
+    epochs: 3,
+    deletable: true,
+  });
+  console.log(result.blobId, result.sponsoredBlobId);
+
+  // Upload from buffer
+  const result2 = await client.upload(
+    { data: Buffer.from("hello"), filename: "hello.txt", contentType: "text/plain" },
+    { creatorAddress: "0x...", epochs: 1 }
+  );
+
+  // List blobs
+  const { blobs, total } = await client.blobs({ status: "active", limit: 50 });
+
+  // Get blob details
+  const blob = await client.blob("0xabc...");
+
+  // Estimate cost
+  const cost = await client.storageCost(1048576, 3);
+  console.log(cost.total_cost, cost.storage_cost, cost.write_cost);
+
+  // Get download URL (no network call)
+  const url = client.getBlobUrl(result.blobId);
+
+  // Health check
+  const health = await client.health();
+
+  // Epoch info
+  const epoch = await client.epoch();
+
+## REST API (for non-JS languages)
+  Base URL: https://walrus-sponsor.krill.tube
+  Auth: Bearer token in Authorization header
+
+  POST /v1/upload          \u2014 Upload file (multipart form: file, creator_address, epochs, deletable)
+  GET  /v1/blobs           \u2014 List blobs (?status=active&limit=20)
+  GET  /v1/blobs/:id       \u2014 Get blob by object_id
+  GET  /v1/storage-cost    \u2014 Estimate cost (?size=1048576&epochs=3)
+  POST /v1/delete          \u2014 Delete blob (requires sponsored_blob_id, walrus_system_object_id)
+  POST /v1/extend          \u2014 Extend storage (requires sponsored_blob_id, epochs, walrus_system_object_id, payment_coin_id)
+  POST /v1/fund            \u2014 Add WAL to blob (requires sponsored_blob_id, funds_coin_id)
+  GET  /health             \u2014 Health check (no auth)
+  GET  /epoch              \u2014 Current epoch info (no auth)
+
+  Rate limit: 60 requests/minute per API key. Returns X-RateLimit-* headers.
+
+## Error Handling
+  - 400: Missing or invalid parameters
+  - 401: Invalid or missing API key
+  - 402: Insufficient workspace balance
+  - 429: Rate limited (retry after X-RateLimit-Reset)
+  - 500: Server error
+  - 502: Publisher or storage node unavailable
+
+## Tips for AI Agents
+  - Install with: npm install -g krilly-cli (for CLI) or npm install krilly (for SDK)
+  - Ask the user for their API key, then run: krilly config set-key <key>
+  - For uploads: you need a file path and a creator_address (any valid Sui 0x address)
+  - Reading blobs is free and public \u2014 use krilly url <blob_id> to get the download link
+  - Check costs before uploading: krilly cost --size <bytes> --epochs <n>
+  - Add --pretty flag for readable JSON output
+  - Full docs: https://walrus-sponsor.krill.tube/docs
+`);
+}
 async function main() {
   const args = process.argv.slice(2);
   if (args.length === 0 || args.includes("--help") || args.includes("-h")) {
@@ -470,6 +608,10 @@ async function main() {
       case "config":
         handleConfig(rest, pretty);
         return;
+      case "docs": {
+        docs();
+        return;
+      }
       case "health": {
         const client = getClient();
         out(await client.health(), pretty);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@3mate/walrus-sponsor-sdk",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "Walrus Sponsor SDK & CLI — upload, manage, and extend sponsored blobs on Walrus",
   "main": "dist/index.js",
   "module": "dist/index.mjs",