Create list blob example (#10)

* Create list blob example

* [tables] Add list blob example

* Add an example to store AI generated images on shelby (#11)

* add example to store ai generated images on shelby

* address comments

* fmt

---------

Co-authored-by: Maayan <[email protected]>

Author: affinity-matrix

README.md

@@ -31,6 +31,7 @@ This Turborepo includes the following example applications:
 | `@shelby-protocol/ai-image-generation` | Shelby AI image generation example | [`apps/ai-image-generation`](./apps/ai-image-generation) |
 | `@shelby-protocol/cross-chain-accounts` | Shelby cross chain accounts example | [`apps/cross-chain-accounts`](./apps/cross-chain-accounts) |
 | `@shelby-protocol/download-example` | An example app to demonstrate downloading blobs using the Shelby SDK | [`apps/download-blob`](./apps/download-blob) |
+| `@shelby-protocol/list-example` | An example app to demonstrate listing blobs using the Shelby SDK | [`apps/list-blob`](./apps/list-blob) |
 | `@shelby-protocol/upload-example` | An example app to demonstrate uploading blobs using the Shelby SDK | [`apps/upload-blob`](./apps/upload-blob) |
 
 <!-- APPS_TABLE_END -->

apps/list-blob/.env.example

@@ -0,0 +1,2 @@
+SHELBY_ACCOUNT_ADDRESS=0xYourAccountAddressHere
+SHELBY_API_KEY=AG-YourApiKeyHere

apps/list-blob/README.md

@@ -0,0 +1,110 @@
+# Shelby List Blob Example
+
+An example application demonstrating how to list blobs from the Shelby protocol using the Shelby SDK. This app retrieves and displays all blobs that have been uploaded to a Shelby account.
+
+## Prerequisites
+
+- Node.js >= 22
+- pnpm package manager
+- A Shelby account with uploaded blobs
+- Shelby API key
+
+## Installation
+
+1. Clone the repository and navigate to the list-blob directory:
+   ```bash
+   cd apps/list-blob
+   ```
+
+2. Install dependencies:
+   ```bash
+   pnpm install
+   ```
+
+## Environment Variables
+
+Create a `.env` file in the root of this project directory with the following required environment variables. You can copy the `.env.example` file as a starting point:
+
+```bash
+cp .env.example .env
+```
+
+Then update the values in your `.env` file:
+
+```env
+SHELBY_ACCOUNT_ADDRESS=your_account_address_here
+SHELBY_API_KEY=your_api_key_here
+```
+
+More information on obtaining an API key on the [Shelby docs site](https://docs.shelby.xyz/sdks/typescript/acquire-api-keys).
+
+## Usage
+
+Run the example using the `bloblist` script:
+
+```bash
+pnpm bloblist
+```
+
+This will execute the TypeScript file directly using tsx with the environment variables from your `.env` file.
+
+### Alternative Execution
+
+You can also run the TypeScript file directly using tsx:
+
+```bash
+npx tsx --env-file=.env src/index.ts
+```
+
+## How It Works
+
+1. **Environment Validation**: The app first validates that all required environment variables are set
+2. **Client Initialization**: Creates a Shelby client instance connected to the Shelbynet network
+3. **Account Setup**: Uses the account address from the environment variable
+4. **Blob Listing**: Retrieves a list of all blobs associated with the specified Shelby account
+5. **Display Results**: Shows blob metadata including name, size, and expiration date
+
+## Output
+
+When successful, this example will:
+- Connect to the Shelby network
+- Retrieve all blobs from the specified account
+- Display the total number of blobs found
+- For each blob, show:
+  - Blob name
+  - File size in bytes
+  - Expiration timestamp
+
+Example output:
+```
+Found 3 blob(s)
+· whitepaper.pdf — 1024567 bytes, expires: 2025-10-16T15:30:00.000Z
+· document.txt — 2048 bytes, expires: 2025-10-17T10:45:00.000Z
+· image.png — 512000 bytes, expires: 2025-10-18T08:20:00.000Z
+```
+
+## Troubleshooting
+
+### Common Issues
+
+1. **SHELBY_ACCOUNT_ADDRESS is not set in .env**
+   - Ensure you have created a `.env` file with the required variables
+   - Check that the variable name is spelled correctly
+   - Verify the account address format is valid
+
+2. **SHELBY_API_KEY is not set in .env**
+   - Verify your API key is correctly set in the `.env` file
+   - Ensure there are no extra spaces or quotes around the API key
+
+3. **No blobs found**
+   - Verify that the account address contains uploaded blobs
+   - Check that you're using the correct account address
+   - Ensure blobs haven't expired
+
+4. **Rate limit exceeded (429)**
+   - Wait a moment before retrying
+   - Consider implementing exponential backoff for production use
+
+5. **Server errors (500)**
+   - This indicates an issue with the Shelby service
+   - Contact Shelby support if this occurs repeatedly

apps/list-blob/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@shelby-protocol/list-example",
+  "version": "1.0.0",
+  "description": "An example app to demonstrate listing blobs using the Shelby SDK",
+  "type": "module",
+  "scripts": {
+    "bloblist": "tsx --env-file=.env src/index.ts",
+    "lint": "biome check .",
+    "fmt": "biome check . --write"
+  },
+  "keywords": [
+    "shelby",
+    "sdk",
+    "blob",
+    "storage"
+  ],
+  "author": "Akasha <[email protected]>",
+  "license": "MIT",
+  "dependencies": {
+    "@aptos-labs/ts-sdk": "^5.1.1",
+    "@shelby-protocol/sdk": "^0.0.4"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "2.2.4",
+    "tsx": "^4.20.5",
+    "typescript": "^5.9.2",
+    "vitest": "^3.2.4"
+  },
+  "engines": {
+    "node": ">=22"
+  }
+}

apps/list-blob/src/index.ts

@@ -0,0 +1,30 @@
+import { AccountAddress, Network } from "@aptos-labs/ts-sdk";
+import { ShelbyNodeClient } from "@shelby-protocol/sdk/node";
+
+if (!process.env.SHELBY_API_KEY) {
+  throw new Error("Missing SHELBY_API_KEY");
+}
+if (!process.env.SHELBY_ACCOUNT_ADDRESS) {
+  throw new Error("Missing SHELBY_ACCOUNT_ADDRESS");
+}
+
+// 1) Initialize a Shelby client (auth via API key; target shelbynet).
+const client = new ShelbyNodeClient({
+  network: Network.SHELBYNET,
+  apiKey: process.env.SHELBY_API_KEY, // ensure .env is loaded
+});
+
+// 2) Parse the account address you'll download from.
+//    ⚠️ This should be the *same account* that previously uploaded blobs.
+const account = AccountAddress.fromString(process.env.SHELBY_ACCOUNT_ADDRESS);
+
+// 3) Ask Shelby for a list of the account's blobs.
+const blobs = await client.coordination.getAccountBlobs({ account });
+
+// 4) For each blob, show its metadata.
+console.log(`Found ${blobs.length} blob(s)`);
+for (const blob of blobs) {
+  console.log(
+    `· ${blob.name} — ${blob.size} bytes, expires: ${new Date(blob.expirationMicros / 1000).toISOString()}`,
+  );
+}

apps/list-blob/tsconfig.json

@@ -0,0 +1,25 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "allowSyntheticDefaultImports": true,
+    "esModuleInterop": true,
+    "allowJs": true,
+    "strict": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "noEmit": false,
+    "lib": ["ES2022", "DOM"],
+    "types": ["node", "vitest/globals"]
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "**/*.test.ts"]
+}