Pocketbook Docs

Appearance

Changelog

All notable changes to the Pocketbook project are documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

[Latest Updates] - 2024-2025 ​

Added ​

API & Configuration ​

  • Centralized API Configuration System (src/config/api.ts)

    • Automatic environment detection (development vs production)
    • Support for VITE_API_BASE_URL environment variable override
    • Auto-detection of production domains (www.pocketbook.studio, pocketbook.studio)
    • Falls back to relative URLs for preview environments
    • See: API_CONFIGURATION.md

  • API Debug Utilities (src/utils/testApiConnection.ts)

    • window.testApiConnection() - Test all API endpoints
    • window.testBulkMintEndpoint(apiKey?, jwtToken?) - Test bulk mint with authentication
    • window.checkServiceWorkerStatus() - Check service worker status
    • window.clearPocketbookCache() - Clear service worker cache

Authentication & Security ​

  • Authentication Debug Utility (src/utils/debugAuth.ts)

    • Browser console debugging tool accessible via window.debugAuth()
    • Provides detailed Dynamic authentication state inspection
    • JWT token inspection and validation
    • Actionable troubleshooting suggestions

  • Allowlist Status Tracking

    • Added allowlistStatus field to user models: 'pending' | 'success' | 'failed'
    • Added allowlistError field for error message tracking
    • Added lastAllowlistAttempt timestamp for monitoring
    • Added allowlistRetryCount field for tracking retry attempts
    • See: ALLOWLIST_FIX_SUMMARY.md

  • Allowlist Retry System

    • Background retry job for failed allowlist additions (src/services/allowlistRetryJob.ts)
    • Configurable max retries and batch size
    • Automatic recovery for transient failures
    • Manual intervention tracking for persistent failures

  • Allowlist API Endpoints (src/server/routes/allowlistRoutes.ts)

    • GET /api/v1/allowlist/check/:address - Check allowlist status
    • POST /api/v1/allowlist/wait-for-confirmation - Poll for confirmation

  • Client-Side Allowlist Verification (src/hooks/useAllowlistCheck.ts)

    • React hook for checking allowlist status
    • checkAllowlist() for quick status checks
    • waitForAllowlist() with polling until allowlisted or timeout
    • Auto-check on component mount option

Database & Data Management ​

  • RegularUser Collection (src/server/models/RegularUser.ts)

    • New consolidated collection for standard users
    • Merges data from former EnterpriseUser, UserContact, and UserCreation collections
    • Includes identity, contact, creation tracking, and profile data
    • Optimized indexes for efficient lookups
    • See: DATABASE_CONSOLIDATION.md

  • Unified User Operations (src/server/utils/userOperations.ts)

    • Type-safe user lookup functions
    • findUserById() - Works with both user types
    • findUserByWalletAddress() - Universal wallet lookup
    • isEnterpriseUser() - Type guard for enterprise users

  • Gift Transfer Indexes

    • Dedicated indexes for pending certificate gifts
    • senderAddress + status + createdAt for sender dashboards
    • claimToken + status for claim validation
    • expiresAt + status for expiration sweeps
    • Sparse indexes on transactionHash and userOperationHash for audit lookups

Scripts & Tooling ​

  • Diagnostic Scripts

    • scripts/checkAllowlistStatus.js - Check if address is allowlisted
    • scripts/checkFailedAllowlistUsers.js - Find users with failed allowlist additions
    • scripts/addAllowlistAddress.js - Manually add address to allowlist
    • scripts/runAllowlistRetryJob.js - Run retry job for failed allowlist additions

  • Emergency Disk Cleanup Script (emergency-disk-cleanup.sh)

    • Cleans system temporary files and logs
    • Removes npm cache and old node_modules
    • Cleans Docker containers if present
    • Reports available disk space

  • Enhanced Production Build Script (fix-production-build-v2.sh)

    • Automated disk space checking and management
    • Optimized dependency installation (--no-audit --no-fund)
    • Critical dependency verification (jszip, viem, typescript)
    • Incremental builds to save memory
    • Detailed error reporting

  • Production Build Command

    • npm run build:production script in package.json
    • Automatically sets VITE_API_BASE_URL=https://api.pocketbook.studio

  • Gift Index Sync Script

    • npm run db:sync-gift-indexes for synchronizing indexes in existing environments

Changed ​

API & Infrastructure ​

  • API Base URL Configuration

    • Updated all dashboard API services to use centralized getApiBaseUrl()
    • Services updated:
      • src/services/dashboardApi.ts
      • src/hooks/useWalletPulse.ts
      • src/hooks/useWalletConcentration.ts
      • src/hooks/useNewReturningWallets.ts
      • src/hooks/useDailyActiveWallets.ts
      • src/hooks/useCohortMatrix.ts
      • src/components/IPFSUploadTest.tsx
      • src/client/utils/apiClient.ts
      • src/utils/apiClient.ts

  • Service Worker API Handling (public/service-worker.js)

    • API calls now always pass through to network (never cached)
    • Service worker throws errors for API failures instead of returning offline content
    • Updated cache version to force refresh (3.2.1751486825-api-fix-v2)
    • Special handling for /api/ endpoints
    • See: API_ISSUES_FIX_SUMMARY.md

Database & Architecture ​

  • EnterpriseUser Collection Enhanced (src/server/models/EnterpriseUser.ts)

    • Consolidated with contact and creation data
    • Added email, phone, and hashed phone fields
    • Added creation tracking fields (messageId, eoa, kernelAddress, allowlistTxHash)
    • Added creationStatus, creationError, retryCount fields
    • Improved type definitions and validations

  • User Collection Migration

    • From 3-collection architecture to 2-collection architecture
    • 90% reduction in database queries for user operations
    • Faster authentication with single lookup vs multiple joins
    • Better caching of complete user objects

Authentication & User Experience ​

  • Dashboard Authentication State Handling (src/components/Dashboard.tsx)

    • Fixed race condition between user authentication and wallet initialization
    • Split loading states:
      • "Wallet Not Connected" modal for unauthenticated users
      • "Initializing Wallet..." spinner for authenticated users with pending wallet
    • Added CSS keyframes animation for loading spinner
    • Improved state debugging with console logs

  • Logout Functionality

    • "Return to Login" button now properly calls Dynamic's handleLogOut()
    • Clears session completely before navigation
    • Proper error handling for logout failures

Billing & Invoicing ​

  • Voucher Invoice Consolidation (server/routes/billingRoutes.js)
    • "Voucher Created" events now consolidated by date
    • Single line item per day with aggregated quantity and amount
    • Direct mint events remain itemized with full details
    • Added metadata: consolidated: true, eventCount, dateKey
    • Cleaner invoice display with maintained accuracy
    • See: VOUCHER_CONSOLIDATION_SUMMARY.md

Error Handling & Reliability ​

  • Allowlist Service Improvements (src/services/allowlistService.ts)

    • Increased confirmation depth from 1 to 3 blocks for better finality
    • Added verification after transaction confirms
    • Implemented retry logic with exponential backoff (3 retries: 2s, 4s, 8s)
    • Enhanced error messages and logging

  • User Creation Handler (src/services/handleUserCreated.ts)

    • No longer silently swallows allowlist errors
    • Updates user record with allowlist status
    • Logs critical warnings for failed allowlist additions
    • Provides manual fix commands in logs

Fixed ​

API & Connectivity ​

  • Service Worker Interference ✅

    • Problem: Service worker returning "Offline" responses for API calls
    • Symptoms: Certificate search returning "Offline co", bulk mint failing
    • Fix: Updated service worker to never cache API endpoints
    • See: API_ISSUES_FIX_SUMMARY.md

  • Hardcoded API URLs ✅

    • Problem: Frontend using localhost:4000 in production
    • Symptoms: Network errors when deployed to production
    • Fix: Implemented centralized API configuration with environment detection
    • See: API_CONFIGURATION.md

Build & Deployment ​

  • TypeScript Build Errors ✅

    • Problem: Missing type declarations for jszip and viem modules
    • Symptoms: TS2307: Cannot find module 'jszip', property type errors
    • Fix: Added @types/jszip dependency, fixed type casting in zipExtractor.ts
    • See: BUILD_FIX_SUMMARY.md

  • Production Server Disk Space Exhaustion ✅

    • Problem: EC2 instance running out of storage during npm install
    • Symptoms: ENOSPC: no space left on device, missing dependencies
    • Fix: Created emergency cleanup scripts and optimized build process
    • Recommendations: Increased EBS volume, CloudWatch monitoring, automated cleanup

  • CORS Configuration ✅

    • Problem: DELETE requests blocked by CORS policy
    • Symptoms: Certificate voucher deletion failing from www.pocketbook.studio
    • Fix: Updated Nginx map to explicitly allow specific origins instead of regex
    • Changed from "~^https?://(www\.)?pocketbook\.studio$" to explicit origin mapping
    • See: CORS_FIX_DEPLOYMENT_README.md

Authentication & Access Control ​

  • Wallet Connection Race Condition ✅

    • Problem: Users seeing "Wallet Not Connected" despite successful authentication
    • Symptoms: Dashboard showing modal after Dynamic login completes
    • Root Cause: Dashboard checking !userAddress before wallet context fully initialized
    • Fix: Split authentication states with proper loading indicators
    • See: AUTHENTICATION_FIX_SUMMARY.md

  • Allowlist Permission Issues ⚠️

    • Problem: New users not added to smart contract allowlist
    • Symptoms: Users cannot mint certificates from vouchers
    • Root Cause: ALLOWLIST_SIGNER_KEY lacks admin permissions on contract
    • Fix: Implemented retry system, status tracking, and manual intervention paths
    • Required: Grant admin permissions to signer address on contract
    • See: ALLOWLIST_FIX_SUMMARY.md

Infrastructure ​

Deployment & Configuration ​

  • Environment Variable Management

    • Development: VITE_API_BASE_URL optional (auto-detects localhost:4000)
    • Production: VITE_API_BASE_URL=https://api.pocketbook.studio
    • Vercel: Environment variable configuration in dashboard

  • Nginx Configuration (config/nginx/api.pocketbook.studio.conf)

    • Updated CORS mapping for explicit origin matching
    • Backup created: api.pocketbook.studio.conf.backup.20251022_152028
    • Reload command: sudo systemctl reload nginx

  • Build Scripts

    • Production: scripts/build-production.sh
    • Emergency cleanup: emergency-disk-cleanup.sh
    • Enhanced build fix: fix-production-build-v2.sh

Database Operations ​

  • User Collection Indexes

    • Both RegularUser and EnterpriseUser collections include:
      • userId (primary lookup)
      • email (unique)
      • walletAddress (unique)
      • smartAccountAddress (unique)
      • phoneHash (privacy-preserving)
      • accountStatus
      • creationStatus

  • Data Validation

    • Ethereum address regex validation
    • Email normalization (lowercase, trimming)
    • E.164 phone format validation
    • SHA-256 privacy hashing with tenant salt

  • Migration Process

    • Automatic backups before migration
    • Data integrity preservation
    • Relationship maintenance
    • Rollback procedures documented

Security ​

Access Control ​

  • Allowlist Smart Contract Integration

    • 3-block confirmation for transaction finality
    • Post-transaction verification of allowlist status
    • Retry logic for transient failures
    • Manual intervention path for permission issues

  • Privacy Enhancements

    • Phone number hashing with SHA-256
    • Tenant-specific salt for hashing
    • Canonical phone number processing before hashing

Authentication ​

  • JWT Token Management
    • Proper session clearing on logout
    • Token validation in debug utilities
    • Secure storage inspection tools

Error Prevention ​

  • Silent Failure Elimination
    • Critical errors now logged prominently
    • Manual intervention commands provided
    • Database status tracking for all operations

Migration Guides ​

For detailed migration instructions, see:

Deployment Notes ​

Critical Production Setup ​

  1. API Server Configuration

    • Ensure production API server is running at https://api.pocketbook.studio
    • Set environment variable: VITE_API_BASE_URL=https://api.pocketbook.studio
    • Configure PM2 or equivalent process manager

  2. Smart Contract Permissions

    • Grant admin permissions to allowlist signer address
    • Verify signer has proper access on contract 0x322A88614F19c5B18F96694b74f1eb74334c9B2e

  3. Nginx Configuration

    • Apply updated CORS configuration
    • Test configuration: sudo nginx -t
    • Reload: sudo systemctl reload nginx

  4. Database Operations

    • Run user collection migration if upgrading from 3-collection architecture
    • Sync gift transfer indexes: npm run db:sync-gift-indexes
    • Set up cron job for allowlist retry: */5 * * * * node scripts/runAllowlistRetryJob.js

  5. Monitoring

    • CloudWatch alerts for disk usage > 80%
    • Monitor logs for "CRITICAL: Failed to add regular user" messages
    • Track allowlist retry job execution

EC2 Server Recommendations ​

  • EBS Volume: Minimum 20GB (resize if needed)
  • Automated Cleanup: Implement regular cleanup scripts
  • CI/CD: Deploy pre-built artifacts instead of building on server
  • Dependency Installation: Use --no-audit --no-fund flags for space efficiency

Known Issues ​

Production API Server ⚠️ ​

  • Status: Production API server may need manual startup
  • Impact: All production API calls fail if server is down
  • Fix: pm2 start dist/server-production.js --name pocketbook-api
  • Monitoring: Set up health check monitoring

Bulk Mint Authentication ⚠️ ​

  • Status: Requires authentication (API key or JWT token)
  • Impact: Bulk mint operations fail without proper auth headers
  • Fix: Implement authentication in client-side bulk mint calls
  • Options: API key (x-api-key header) or JWT (Authorization: Bearer header)

Allowlist Signer Permissions ⚠️ ​

  • Status: Requires admin permissions on smart contract
  • Impact: New users cannot be added to allowlist
  • Fix: Grant admin role to signer address on contract
  • Workaround: Manual addition via scripts/addAllowlistAddress.js

Support ​

For issues or questions:

  • Check browser console for debug information
  • Run window.debugAuth() for authentication issues
  • Run window.testApiConnection() for API connectivity issues
  • Review relevant fix summary documents in project root
  • Monitor server logs for critical errors

Maintained by: Pocketbook Development Team Last Updated: November 2024

Released under the MIT License.

Copyright © 2025 Pocketbook Studio