@sage-protocol/sdk 0.1.6 → 0.1.7

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).

package/dist/browser/index.mjs

@@ -20,7 +20,7 @@ var require_package = __commonJS({
   "package.json"(exports, module) {
     module.exports = {
       name: "@sage-protocol/sdk",
-      version: "0.1.6",
+      version: "0.1.4",
       description: "Backend-agnostic SDK for interacting with the Sage Protocol (governance, SubDAOs, tokens).",
       main: "dist/index.cjs",
       module: "dist/index.mjs",
@@ -56,10 +56,10 @@ var require_package = __commonJS({
       ],
       sideEffects: false,
       browser: {
+        child_process: false,
         fs: false,
-        path: false,
         os: false,
-        child_process: false
+        path: false
       },
       repository: {
         type: "git",
@@ -88,6 +88,18 @@ var require_package = __commonJS({
         sinon: "^17.0.1",
         tsup: "^8.1.0",
         typescript: "^5.4.0"
+      },
+      peerDependencies: {
+        react: "^18.0.0 || ^19.0.0",
+        swr: "^2.0.0"
+      },
+      peerDependenciesMeta: {
+        react: {
+          optional: true
+        },
+        swr: {
+          optional: true
+        }
       }
     };
   }
@@ -250,19 +262,20 @@ var require_abi = __commonJS({
     var PersonalLicenseReceipt = [
       "function balanceOf(address account, uint256 id) view returns (uint256)"
     ];
-    var TreasuryWrapper = [
-      "function execute(address,uint256,bytes,bytes32) returns (bool)",
-      "function allowedTargets(address) view returns (bool)",
-      "function allowedSelectors(bytes4) view returns (bool)",
-      "function owners(address) view returns (bool)",
-      "function ownerCount() view returns (uint256)",
-      "function registry() view returns (address)",
-      "event TreasuryAction(address indexed caller, address indexed target, uint256 value, bytes data, bytes32 refId)",
-      "event AllowedTargetUpdated(address indexed target, bool allowed)",
-      "event AllowedSelectorUpdated(bytes4 indexed selector, bool allowed)",
-      "event OwnerAdded(address indexed owner)",
-      "event OwnerRemoved(address indexed owner)",
-      "event TokensSwept(address indexed token, address indexed to, uint256 amount)"
+    var SageTreasury = [
+      "function totalReserves() view returns (uint256)",
+      "function totalPOL() view returns (uint256)",
+      "function totalDebt() view returns (uint256)",
+      "function canonicalPool() view returns (address)",
+      "function routerOrVault() view returns (address)",
+      "function maxWithdrawalRate() view returns (uint256)",
+      "function emergencyWithdrawalLimit() view returns (uint256)",
+      "function getReserveTokens() view returns (address[])",
+      "function getReserve(address token) view returns (address tokenAddress,uint256 amount,uint256 value,bool isLP,bool isActive)",
+      "function pendingWithdrawals(uint256) view returns (address token,address recipient,uint256 amount,uint256 value,address requester,uint256 balanceBefore,uint256 recipientBalanceBefore,uint256 depositSnapshot,bool isLP,bool isEmergency,bool exists)",
+      "function nextWithdrawalId() view returns (uint256)",
+      "function manualPrices(address token) view returns (uint256 price,uint256 expiresAt,bool active)",
+      "function lpContributions(address,address) view returns (uint256)"
     ];
     var GovernanceBoostMerkle = [
       "function getProposalConfig(uint256) view returns (tuple(uint256 proposalId,address token,uint256 totalAmount,uint64 startTime,uint64 endTime,uint256 merkleRoot))",
@@ -274,6 +287,29 @@ var require_abi = __commonJS({
       "function create(uint256 proposalId, address token, uint256 perVoter, uint256 maxVoters)",
       "function fund(uint256 proposalId, uint256 amount)"
     ];
+    var BondDepository = [
+      // Core getters
+      "function payoutToken() view returns (address)",
+      "function principalToken() view returns (address)",
+      "function treasury() view returns (address)",
+      // Terms
+      "function terms() view returns (tuple(uint256 controlVariable,uint256 minimumPrice,uint256 maxPayout,uint256 maxDebt,uint256 vestingTerm,uint256 fee))",
+      "function totalDebt(address) view returns (uint256)",
+      // Pricing
+      "function bondPrice() view returns (uint256)",
+      "function bondPrice(address) view returns (uint256)",
+      "function bondPriceInUSD() view returns (uint256)",
+      "function currentDebt() view returns (uint256)",
+      "function debtRatio() view returns (uint256)",
+      "function standardizedDebtRatio() view returns (uint256)",
+      // User views
+      "function bondInfo(address) view returns (tuple(uint256 payout,uint256 vesting,uint256 lastBlock,uint256 pricePaid))",
+      "function pendingPayout(address) view returns (uint256)",
+      "function percentVestedFor(address) view returns (uint256)",
+      // Actions
+      "function deposit(uint256 _amount, uint256 _maxPrice) returns (uint256 payout_)",
+      "function redeem(address _recipient, bool _stake) returns (uint256)"
+    ];
     var Events = {
       ProposalCreated: "event ProposalCreated(uint256 id, address proposer, address[] targets, uint256[] values, string[] signatures, bytes[] calldatas, uint256 startBlock, uint256 endBlock, string description)"
     };
@@ -292,10 +328,10 @@ var require_abi = __commonJS({
       PersonalLibraryFacet,
       PersonalMarketplace,
       PersonalLicenseReceipt,
-      TreasuryWrapper,
-      // Protocol treasury (replaces SageTreasury)
+      SageTreasury,
       GovernanceBoostMerkle,
       GovernanceBoostDirect,
+      BondDepository,
       Events
     };
   }