@sage-protocol/sdk 0.1.6 → 0.1.8

package/README.md

@@ -68,9 +68,297 @@ Module Overview
 | `treasury` | Reserve/POL snapshot, pending withdrawals, liquidity plans | Treasury analytics, Safe operators |
 | `boost` | Merkle/Direct boost readers + builders | Incentive distribution tooling |
 | `subgraph` | GraphQL helpers for proposals/libraries | Historical analytics |
+| `services` | High-level SubgraphService + IPFSService with retry/caching | Web app, CLI integration |
 | `adapters` | Normalized governance adapters (OZ) | UI layers needing a unified model |
 | `errors` | `SageSDKError` codes | Consistent downstream error handling |
 
+### Service Layer
+
+The SDK provides high-level service classes with built-in retry logic, caching, and error handling for production applications.
+
+**SubgraphService** - GraphQL queries with automatic retry and caching
+
+```js
+import { services, serviceErrors } from '@sage-protocol/sdk';
+
+// Initialize service
+const subgraphService = new services.SubgraphService({
+  url: 'https://api.studio.thegraph.com/query/your-subgraph',
+  timeout: 10000,      // 10s timeout (default)
+  retries: 3,          // 3 retry attempts with exponential backoff (default)
+  cache: {
+    enabled: true,     // Enable caching (default: true)
+    ttl: 30000,        // 30s cache TTL (default)
+    maxSize: 100,      // Max 100 cache entries (default)
+  },
+});
+
+// Fetch SubDAOs with caching
+const subdaos = await subgraphService.getSubDAOs({ limit: 50, skip: 0 });
+
+// Fetch proposals with filters
+const proposals = await subgraphService.getProposals({
+  governor: '0xGovernor',
+  states: ['ACTIVE', 'PENDING'],
+  fromTimestamp: 1640000000,
+  limit: 20,
+  cache: true,  // Use cache (default: true)
+});
+
+// Get single proposal by ID
+const proposal = await subgraphService.getProposalById('0x123...', { cache: true });
+
+// Fetch libraries
+const libraries = await subgraphService.getLibraries({
+  subdao: '0xSubDAO',
+  limit: 50,
+});
+
+// Fetch prompts by tag
+const prompts = await subgraphService.getPromptsByTag({
+  tagsHash: '0xabc123...',
+  registry: '0xRegistry',
+  limit: 50,
+});
+
+// Cache management
+subgraphService.clearCache();
+const stats = subgraphService.getCacheStats();
+// → { enabled: true, size: 12, maxSize: 100 }
+```
+
+**IPFSService** - Parallel gateway fetching with caching
+
+```js
+import { services, serviceErrors } from '@sage-protocol/sdk';
+import { ethers } from 'ethers';
+
+// Initialize service
+const ipfsService = new services.IPFSService({
+  workerBaseUrl: 'https://api.sageprotocol.io',
+  gateway: 'https://ipfs.io',
+  signer: ethers.Wallet.fromPhrase('...'), // Optional: for worker auth
+  timeout: 15000,      // 15s timeout (default)
+  retries: 2,          // 2 retry attempts (default)
+  cache: {
+    enabled: true,     // Enable caching (default: true)
+    ttl: 300000,       // 5min cache TTL for immutable CIDs (default)
+    maxSize: 50,       // Max 50 cache entries (default)
+  },
+});
+
+// Fetch content by CID (parallel gateway race)
+// Tries multiple gateways in parallel, returns first success
+const content = await ipfsService.fetchByCID('QmTest123...', {
+  cache: true,
+  timeout: 5000,       // 5s timeout per gateway
+  extraGateways: ['https://cloudflare-ipfs.com', 'https://gateway.pinata.cloud'],
+});
+
+// Upload content to IPFS worker
+const cid = await ipfsService.upload(
+  { title: 'My Prompt', content: '...' },
+  { name: 'prompt.json', warm: true }
+);
+// → 'QmNewContent123...'
+
+// Pin CIDs to worker
+await ipfsService.pin(['QmTest1...', 'QmTest2...'], { warm: false });
+
+// Warm gateways (prefetch)
+await ipfsService.warm('QmTest123...', {
+  gateways: ['https://ipfs.io', 'https://cloudflare-ipfs.com'],
+});
+
+// Cache management
+ipfsService.clearCache();
+const stats = ipfsService.getCacheStats();
+```
+
+**Error Handling**
+
+```js
+import { services, serviceErrors } from '@sage-protocol/sdk';
+
+try {
+  const subdaos = await subgraphService.getSubDAOs({ limit: 50 });
+} catch (error) {
+  if (error instanceof serviceErrors.SubgraphError) {
+    console.error(`Subgraph error [${error.code}]:`, error.message);
+    console.log('Retryable:', error.retryable);
+    // Codes: TIMEOUT, NETWORK, INVALID_RESPONSE, NOT_FOUND, QUERY_FAILED
+  }
+}
+
+try {
+  const content = await ipfsService.fetchByCID('QmTest...');
+} catch (error) {
+  if (error instanceof serviceErrors.IPFSError) {
+    console.error(`IPFS error [${error.code}]:`, error.message);
+    // Codes: TIMEOUT, PIN_FAILED, INVALID_CID, NOT_FOUND, GATEWAY_FAILED, UPLOAD_FAILED
+  }
+}
+
+// Format user-friendly error messages
+const friendlyMsg = serviceErrors.formatErrorMessage(error);
+```
+
+**Utility Exports**
+
+```js
+import { serviceUtils } from '@sage-protocol/sdk';
+
+// Simple in-memory cache with TTL
+const cache = new serviceUtils.SimpleCache({
+  enabled: true,
+  ttl: 60000,      // 1 minute
+  maxSize: 200,
+});
+cache.set('key', { data: 'value' });
+const val = cache.get('key');
+
+// Exponential backoff retry
+const result = await serviceUtils.retryWithBackoff(
+  async () => {
+    // Your async operation
+    return await fetchData();
+  },
+  {
+    attempts: 3,
+    baseDelay: 1000,   // Start at 1s
+    maxDelay: 10000,   // Cap at 10s
+    onRetry: ({ attempt, totalAttempts, delay, error }) => {
+      console.log(`Retry ${attempt}/${totalAttempts} after ${delay}ms:`, error.message);
+    },
+  }
+);
+```
+
+**Performance Notes**
+
+- **Parallel Gateway Fetching**: IPFSService fetches from multiple IPFS gateways simultaneously (Promise.race pattern), reducing typical fetch times from 7-28s to 1-2s (10-14x improvement)
+- **In-Memory Caching**: Both services cache results in memory with configurable TTL to reduce redundant network calls
+- **Exponential Backoff**: Automatic retry with exponential backoff (1s → 2s → 4s delays) for transient failures
+- **Edge Runtime Compatible**: Uses `fetch()` instead of axios, compatible with Cloudflare Pages and Vercel Edge
+
+**React Integration**
+
+The SDK provides React hooks built on SWR for seamless integration in React applications:
+
+**Prerequisites**:
+```bash
+# Install peer dependencies
+npm install react swr
+# or
+yarn add react swr
+```
+
+**Usage**:
+
+```js
+import { services, hooks } from '@sage-protocol/sdk';
+
+// Initialize services (once, typically in a context provider)
+const subgraphService = new services.SubgraphService({
+  url: 'https://api.studio.thegraph.com/query/your-subgraph',
+});
+
+const ipfsService = new services.IPFSService({
+  workerBaseUrl: 'https://api.sageprotocol.io',
+  gateway: 'https://ipfs.io',
+  signer: yourSigner, // Optional for uploads
+});
+
+// Use hooks in components
+function SubDAOList() {
+  const { data: subdaos, error, isLoading } = hooks.useSubDAOs(subgraphService, {
+    limit: 50,
+  });
+
+  if (isLoading) return <div>Loading...</div>;
+  if (error) return <div>Error: {error.message}</div>;
+
+  return (
+    <ul>
+      {subdaos.map(subdao => (
+        <li key={subdao.id}>{subdao.name}</li>
+      ))}
+    </ul>
+  );
+}
+
+function ProposalList({ governorAddress }) {
+  const { data: proposals } = hooks.useProposals(subgraphService, {
+    governor: governorAddress,
+    states: ['ACTIVE', 'PENDING'],
+    limit: 20,
+    refreshInterval: 30000, // Auto-refresh every 30s
+  });
+
+  return (
+    <ul>
+      {proposals?.map(proposal => (
+        <li key={proposal.id}>{proposal.description}</li>
+      ))}
+    </ul>
+  );
+}
+
+function PromptViewer({ cid }) {
+  const { data: content, isLoading } = hooks.useFetchCID(ipfsService, cid, {
+    extraGateways: ['https://cloudflare-ipfs.com'],
+  });
+
+  if (isLoading) return <div>Loading prompt...</div>;
+
+  return <pre>{JSON.stringify(content, null, 2)}</pre>;
+}
+
+function UploadForm() {
+  const { upload, isUploading, error, data: cid } = hooks.useUpload(ipfsService);
+
+  const handleSubmit = async (e) => {
+    e.preventDefault();
+    const content = { title: 'My Prompt', content: '...' };
+    try {
+      const newCid = await upload(content, { name: 'prompt.json' });
+      console.log('Uploaded:', newCid);
+    } catch (err) {
+      console.error('Upload failed:', err);
+    }
+  };
+
+  return (
+    <form onSubmit={handleSubmit}>
+      <button type="submit" disabled={isUploading}>
+        {isUploading ? 'Uploading...' : 'Upload'}
+      </button>
+      {error && <div>Error: {error.message}</div>}
+      {cid && <div>Uploaded to: {cid}</div>}
+    </form>
+  );
+}
+```
+
+**Available Hooks**:
+
+| Hook | Description | Returns |
+|------|-------------|---------|
+| `useSubDAOs(service, options)` | Fetch SubDAOs from subgraph | `{ data, error, isLoading, mutate }` |
+| `useProposals(service, options)` | Fetch proposals from subgraph | `{ data, error, isLoading, mutate }` |
+| `useFetchCID(service, cid, options)` | Fetch IPFS content by CID | `{ data, error, isLoading, mutate }` |
+| `useUpload(service)` | Upload content to IPFS | `{ upload, isUploading, error, data, reset }` |
+
+**Hook Options**:
+
+All data-fetching hooks support SWR options:
+- `refreshInterval` - Auto-refresh interval in ms
+- `revalidateOnFocus` - Revalidate when window focused
+- `revalidateOnReconnect` - Revalidate on network reconnect
+- `cache` - Use service-level caching
+
+**Note**: Hooks are optional and only available when `react` and `swr` peer dependencies are installed.
+
 ### Examples
 
 - [Legacy base mini app hook](examples/base-mini-app/README.md) – React-friendly context mirroring the former in-repo app (now maintained externally).