Preview

When a zip finishes uploading to a bucket with preview on, Code Buckets unpacks it into the bucket's code tree. The Console's Files tab shows that tree with a search box and a highlighted viewer; the API gives you the same tree and files.

What gets unpacked

• If every file in the zip sits inside one top folder (like storefront-main/, the usual shape of downloaded zips), that folder is dropped so your files start at the root. The object's preview.stripped_folder says which.
• Files up to 2 MB each go into the tree, up to about 96 MB and 20,000 files per zip. Bigger files, and anything past those limits, stay safely in the stored zip; preview.skipped counts them and preview.skipped_examples names some.
• Paths that try to leave the tree (../), .git/, __MACOSX/ and .DS_Store are skipped. Password-protected zip entries can't be previewed.

The object's preview.status ends as ready, partial (some files kept in the zip only) or failed (the zip couldn't be read; it's still stored).

Reading the tree

curl "$CB/v1/buckets/BUCKET_ID/tree" \
  -H "Authorization: Bearer $CLATTER_API_KEY" -H "X-Clatter-Account: $CLATTER_ACCOUNT_ID"

{
  "object": "tree",
  "ref": "9b1f0c5e2a7d43e8b6c1f0a9d2e5b7c4a1f3e8d0",
  "files": [
    { "path": "README.md", "type": "file", "size": 1840 },
    { "path": "src", "type": "dir" },
    { "path": "src/index.ts", "type": "file", "size": 5121 }
  ],
  "truncated": false
}

Reading a file

curl "$CB/v1/buckets/BUCKET_ID/files/src/index.ts?ref=9b1f0c5e2a7d43e8b6c1f0a9d2e5b7c4a1f3e8d0" \
  -H "Authorization: Bearer $CLATTER_API_KEY" -H "X-Clatter-Account: $CLATTER_ACCOUNT_ID"

The response has content (UTF-8 text, or base64 for binary files) and a language (typescript, python, json, …) you can hand to a highlighter. Add download=1 for the raw bytes.

Turning preview off

Set "preview": false when you create or update a bucket to keep its code only in encrypted zips. New zips are then stored without being unpacked (preview.status: "off"); download them to read them.