chore: bump version to 0.2.1 in package.json, enhance error handling in SDK with structured error types, and update README for improved guidance

Author: iammatthias

README.md

@@ -451,30 +451,104 @@ try {
 
 ### Error Handling Best Practices
 
+The SDK provides structured error handling with specific error types and helpful suggestions:
+
 ```typescript
-import { ValidationError } from '@pinata/grapevine-sdk';
+import { 
+  ValidationError, 
+  ContentError, 
+  AuthError, 
+  ApiError, 
+  ErrorCode 
+} from '@pinata/grapevine-sdk';
 
 try {
-  const feed = await grapevine.feeds.create(feedData);
-  console.log('Feed created successfully:', feed.id);
+  const entry = await grapevine.entries.create('feed-id', {
+    content_base64: base64Data,
+    title: 'My Entry'
+  });
+  console.log('Entry created successfully:', entry.id);
 } catch (error) {
-  if (error instanceof ValidationError) {
-    // Client-side validation error - fix the input data
+  if (error instanceof ContentError) {
+    // Content validation or processing error
+    console.error('Content error:', error.message);
+    console.log('Suggestion:', error.suggestion);
+    
+    if (error.code === ErrorCode.CONTENT_EMPTY) {
+      // Handle empty content case
+      console.log('Content was empty or undefined');
+    } else if (error.code === ErrorCode.BASE64_INVALID) {
+      // Handle invalid base64 format
+      console.log('Base64 format is invalid');
+    }
+  } else if (error instanceof AuthError) {
+    // Authentication/wallet error
+    console.error('Auth error:', error.message);
+    
+    if (error.code === ErrorCode.AUTH_NO_WALLET) {
+      // Prompt user to connect wallet
+      console.log('Please connect your wallet first');
+    }
+  } else if (error instanceof ApiError) {
+    // API request failed
+    console.error(`API error (${error.status}):`, error.message);
+    
+    if (error.status === 402) {
+      console.log('Payment required for this operation');
+    } else if (error.status === 404) {
+      console.log('Resource not found - check your IDs');
+    }
+  } else if (error instanceof ValidationError) {
+    // Field validation error (from validation.ts)
     console.error('Validation error:', error.message);
-    // Show user-friendly error message in UI
-  } else if (error.message.includes('402')) {
-    // Payment required
-    console.error('Payment required for this operation');
-  } else if (error.message.includes('Invalid category_id')) {
-    // Server-side category validation (category doesn't exist)
-    console.error('Category no longer exists, please select a different category');
   } else {
-    // Other API or network errors
-    console.error('API error:', error.message);
+    // Unexpected error
+    console.error('Unexpected error:', error.message);
+  }
+  
+  // All SDK errors include helpful context
+  if (error.getDetailedMessage) {
+    console.log('Detailed help:');
+    console.log(error.getDetailedMessage());
   }
 }
 ```
 
+#### Error Types
+
+- **`ContentError`**: Issues with content validation, base64 encoding, or processing
+- **`AuthError`**: Authentication, wallet, or private key issues  
+- **`ConfigError`**: Configuration conflicts or invalid settings
+- **`ApiError`**: HTTP request failures, server errors, payment required
+- **`ValidationError`**: Field validation errors (legacy from validation.ts)
+
+#### Common Content Error Solutions
+
+```typescript
+// ❌ Wrong - undefined base64 content
+try {
+  await grapevine.entries.create('feed-id', {
+    content_base64: undefined  // This will throw ContentError.CONTENT_EMPTY
+  });
+} catch (error) {
+  if (error instanceof ContentError && error.code === ErrorCode.CONTENT_EMPTY) {
+    console.log(error.suggestion); // "Ensure your base64 conversion succeeded..."
+    console.log(error.example);    // Shows code example
+  }
+}
+
+// ✅ Correct - check conversion result
+const base64Data = await convertFileToBase64(file);
+if (!base64Data) {
+  throw new Error('Failed to convert file to base64');
+}
+
+await grapevine.entries.create('feed-id', {
+  content_base64: base64Data,
+  title: 'My File'
+});
+```
+
 ### Validation Rules Reference
 
 | Field Type | Validation Rules | Example Error |

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pinata/grapevine-sdk",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "Easy-to-use SDK for the Grapevine API - Create and manage content feeds with x402 micropayments",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

src/adapters/private-key-adapter.ts

@@ -2,6 +2,7 @@ import { createWalletClient, http, type WalletClient } from 'viem';
 import { privateKeyToAccount } from 'viem/accounts';
 import { base, baseSepolia } from 'viem/chains';
 import type { WalletAdapter } from './wallet-adapter.js';
+import { AuthError } from '../errors.js';
 
 /**
  * Wallet adapter implementation for private key authentication
@@ -13,7 +14,7 @@ export class PrivateKeyAdapter implements WalletAdapter {
 
   constructor(privateKey: string, isTestnet: boolean) {
     if (!privateKey.startsWith('0x')) {
-      throw new Error('Private key must start with 0x');
+      throw AuthError.invalidPrivateKey(privateKey);
     }
 
     this.account = privateKeyToAccount(privateKey as `0x${string}`);

src/adapters/wagmi-adapter.ts

@@ -1,5 +1,6 @@
 import type { WalletClient } from 'viem';
 import type { WalletAdapter } from './wallet-adapter.js';
+import { AuthError, ErrorCode } from '../errors.js';
 
 /**
  * Wallet adapter implementation for wagmi wallet clients
@@ -11,13 +12,37 @@ export class WagmiAdapter implements WalletAdapter {
 
   constructor(walletClient: WalletClient) {
     if (!walletClient) {
-      throw new Error('WalletClient is required');
+      throw new AuthError(
+        'WalletClient is required for WagmiAdapter',
+        ErrorCode.AUTH_INVALID_KEY,
+        {
+          suggestion: 'Provide a valid WalletClient instance from wagmi',
+          example: `import { useWalletClient } from 'wagmi';
+import { WagmiAdapter } from '@pinata/grapevine-sdk';
+
+const { data: walletClient } = useWalletClient();
+if (walletClient) {
+  const adapter = new WagmiAdapter(walletClient);
+}`
+        }
+      );
     }
 
     // Extract address from wallet client account
     const address = walletClient.account?.address;
     if (!address) {
-      throw new Error('Wallet address not available from wallet client account');
+      throw new AuthError(
+        'Wallet address not available from wallet client',
+        ErrorCode.AUTH_NO_WALLET,
+        {
+          suggestion: 'Ensure the wallet is connected and has an account',
+          example: `// Make sure wallet is connected first
+if (!walletClient.account?.address) {
+  // Connect wallet first
+  await connect({ connector: ... });
+}`
+        }
+      );
     }
 
     this.walletClient = walletClient;
@@ -26,7 +51,14 @@ export class WagmiAdapter implements WalletAdapter {
     // Get chain ID from wallet client
     const chainId = this.walletClient.chain?.id;
     if (!chainId) {
-      throw new Error('Chain ID not available from wallet client');
+      throw new AuthError(
+        'Chain ID not available from wallet client',
+        ErrorCode.CONFIG_INVALID,
+        {
+          suggestion: 'Ensure the wallet is connected to a supported network (Base or Base Sepolia)',
+          context: { supportedChainIds: [8453, 84532] }
+        }
+      );
     }
 
     // Map chain IDs: 84532 = Base Sepolia, 8453 = Base Mainnet

src/client.ts

@@ -4,6 +4,7 @@ import { FeedsResource } from './resources/feeds.js';
 import { EntriesResource } from './resources/entries.js';
 import type { GrapevineConfig, Category } from './types.js';
 import type { WalletAdapter } from './adapters/wallet-adapter.js';
+import { AuthError, ConfigError, ApiError } from './errors.js';
 
 interface RequestOptions {
   method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
@@ -39,13 +40,13 @@ export class GrapevineClient {
 
     // Initialize auth if private key or wallet adapter is provided
     if (config.privateKey && config.walletAdapter) {
-      throw new Error('Cannot provide both privateKey and walletAdapter');
+      throw ConfigError.conflictingConfig('privateKey', 'walletAdapter');
     }
 
     // Validate private key format if provided
     if (config.privateKey) {
       if (typeof config.privateKey !== 'string' || !config.privateKey.startsWith('0x') || config.privateKey.length !== 66) {
-        throw new Error('Invalid private key format. Must be 66 characters starting with 0x');
+        throw AuthError.invalidPrivateKey(config.privateKey);
       }
       this.initializeAuth(config.privateKey);
     } else if (config.walletAdapter) {
@@ -71,7 +72,7 @@ export class GrapevineClient {
    */
   initializeAuth(privateKey: string): void {
     if (!privateKey.startsWith('0x')) {
-      throw new Error('Private key must start with 0x');
+      throw AuthError.invalidPrivateKey(privateKey);
     }
 
     this.authManager = new AuthManager(privateKey, this.apiUrl, this.isTestnet);
@@ -145,7 +146,7 @@ export class GrapevineClient {
     // Add auth headers if required
     if (options.requiresAuth) {
       if (!this.authManager) {
-        throw new Error('Authentication required but no wallet configured. Use setWalletClient() to configure a wallet first.');
+        throw AuthError.noWallet();
       }
       authHeaders = await this.authManager.getAuthHeaders();
       Object.assign(headers, authHeaders);
@@ -187,7 +188,7 @@ export class GrapevineClient {
     // Check for errors
     if (!response.ok && response.status !== 204) {
       const errorText = await response.text();
-      throw new Error(`API request failed (${response.status}): ${errorText}`);
+      throw ApiError.requestFailed(response.status, errorText, url);
     }
 
     return response;
@@ -213,7 +214,7 @@ export class GrapevineClient {
    */
   getWalletAddress(): string {
     if (!this.authManager) {
-      throw new Error('No wallet configured. Use setWalletClient() to configure a wallet first.');
+      throw AuthError.noWallet();
     }
     return this.authManager.walletAddress;
   }