@ecency/sdk 1.5.7 → 1.5.9

package/README.md

@@ -2,12 +2,212 @@
 
 Framework-agnostic data layer for Hive apps with first-class React Query support.
 
-## What’s Inside
+## What's Inside
 
 - Query and mutation option builders powered by [@tanstack/react-query](https://tanstack.com/query)
 - Modular APIs: accounts, posts, communities, market, wallet, notifications, analytics, integrations, core, auth, bridge, games, hive-engine, operations, points, private-api, promotions, proposals, resource-credits, search, spk, witnesses
 - Central configuration via `CONFIG` / `ConfigManager` (RPC client, QueryClient)
 
+## Why React Query?
+
+The Ecency SDK is built on **React Query** (TanStack Query) to provide a production-ready data synchronization layer out of the box. React Query transforms how Hive applications handle server state, eliminating common pitfalls and dramatically improving user experience.
+
+### Key Benefits
+
+#### 1. **Automatic Caching & Deduplication**
+Multiple components can request the same data without redundant network calls. React Query automatically:
+- Caches responses by query key
+- Deduplicates concurrent requests
+- Shares cached data across components instantly
+
+```ts
+// Both components use the same query - only 1 API call is made
+// Component A
+useQuery(getAccountFullQueryOptions("ecency"));
+
+// Component B (rendered simultaneously)
+useQuery(getAccountFullQueryOptions("ecency")); // ← Uses cached data
+```
+
+#### 2. **Background Synchronization**
+Data automatically stays fresh without manual refetching. React Query:
+- Refetches stale data on window focus
+- Updates data on network reconnection
+- Supports configurable background polling
+- Prevents showing outdated information
+
+```ts
+// Data refetches automatically when user returns to tab
+const { data } = useQuery({
+  ...getPostsRankedQueryOptions("trending", "", "", 20),
+  staleTime: 60000, // Consider fresh for 60s
+  refetchInterval: 120000 // Poll every 2 minutes
+});
+```
+
+#### 3. **Optimistic Updates**
+Instant UI feedback before blockchain confirmation:
+
+```ts
+const { mutateAsync } = useAccountUpdate(username, auth);
+
+await mutateAsync(
+  { metadata: newProfile },
+  {
+    // Update UI immediately
+    onMutate: (variables) => {
+      queryClient.setQueryData(
+        getAccountFullQueryOptions(username).queryKey,
+        (old) => ({ ...old, ...variables.metadata })
+      );
+    },
+    // Rollback on error
+    onError: (err, variables, context) => {
+      queryClient.setQueryData(
+        getAccountFullQueryOptions(username).queryKey,
+        context.previousData
+      );
+    }
+  }
+);
+```
+
+#### 4. **SSR & Prefetching**
+First-class server-side rendering support:
+
+```tsx
+// Next.js App Router example
+export async function generateMetadata({ params }) {
+  const queryClient = new QueryClient();
+
+  // Prefetch on server
+  await queryClient.prefetchQuery(
+    getAccountFullQueryOptions(params.username)
+  );
+
+  // Data is hydrated on client instantly
+  return { title: /* ... */ };
+}
+```
+
+#### 5. **Loading & Error States**
+Built-in state management eliminates boilerplate:
+
+```ts
+const { data, isLoading, error, isRefetching } = useQuery(
+  getAccountFullQueryOptions("ecency")
+);
+
+if (isLoading) return <Spinner />;
+if (error) return <ErrorMessage error={error} />;
+
+return <Profile data={data} isRefreshing={isRefetching} />;
+```
+
+#### 6. **Dependent Queries**
+Chain queries with automatic dependency tracking:
+
+```ts
+// Step 1: Fetch account
+const { data: account } = useQuery(getAccountFullQueryOptions(username));
+
+// Step 2: Fetch wallet only after account loads
+const { data: wallet } = useQuery({
+  ...getAccountWalletAssetInfoQueryOptions(username, "HIVE"),
+  enabled: !!account // Wait for account
+});
+```
+
+#### 7. **Pagination & Infinite Scroll**
+Built-in pagination utilities:
+
+```ts
+const {
+  data,
+  fetchNextPage,
+  hasNextPage,
+  isFetchingNextPage
+} = useInfiniteQuery(
+  getPostsRankedInfiniteQueryOptions("trending", "hive-engine")
+);
+
+// Automatically manages page state and cursor tracking
+```
+
+### Why This Matters for Hive Apps
+
+Hive applications face unique challenges:
+- **High API latency**: Blockchain RPC calls can be slow (100-500ms)
+- **Rate limits**: Excessive requests can hit node rate limits
+- **Stale data**: Blockchain data changes frequently (new posts, votes, transfers)
+- **Complex state**: Managing loading states, errors, and cache invalidation manually is error-prone
+
+The Ecency SDK with React Query solves all of these:
+
+✅ **Reduced API calls** by 70-90% through intelligent caching
+✅ **Instant UI updates** with optimistic mutations
+✅ **Zero manual cache management** - React Query handles invalidation
+✅ **Better UX** with background updates and retry logic
+✅ **Faster perceived performance** with prefetching and SSR
+✅ **Less code** - no custom loading/error/caching logic needed
+
+### How Other Apps Can Benefit
+
+Any Hive application can leverage this SDK to:
+
+1. **Drop custom data fetching code** - Use pre-built query options for all common Hive operations
+2. **Share cache across features** - One query for account data serves entire app
+3. **Add real-time features** easily with `refetchInterval` and optimistic updates
+4. **Improve SEO** with SSR-ready queries that prefetch on server
+5. **Reduce bundle size** - Share the SDK's type-safe queries instead of custom fetch logic
+
+**Example: Building a Hive blog reader**
+
+```tsx
+import { useQuery, useInfiniteQuery } from "@tanstack/react-query";
+import {
+  getAccountFullQueryOptions,
+  getPostQueryOptions,
+  getPostsRankedInfiniteQueryOptions
+} from "@ecency/sdk";
+
+// Profile page - automatic caching
+function ProfilePage({ username }) {
+  const { data: account, isLoading } = useQuery(
+    getAccountFullQueryOptions(username)
+  );
+  // ✅ Cached automatically, shared across components
+  // ✅ Refetches on window focus
+  // ✅ Handles loading/error states
+}
+
+// Feed page - infinite scroll
+function FeedPage() {
+  const { data, fetchNextPage, hasNextPage } = useInfiniteQuery(
+    getPostsRankedInfiniteQueryOptions("trending")
+  );
+  // ✅ Automatic pagination
+  // ✅ Background updates
+  // ✅ Deduplicates concurrent requests
+}
+
+// Post page - dependent queries
+function PostPage({ author, permlink }) {
+  const { data: post } = useQuery(
+    getPostQueryOptions(author, permlink)
+  );
+
+  const { data: authorAccount } = useQuery({
+    ...getAccountFullQueryOptions(post?.author),
+    enabled: !!post // Wait for post to load
+  });
+  // ✅ Efficient dependent loading
+  // ✅ Shares cache with ProfilePage above
+}
+```
+
+**Zero manual cache management. Zero custom fetch logic. Production-ready data layer.**
+
 ## Installation
 
 ```sh

package/dist/browser/index.js

@@ -43,6 +43,20 @@ function useBroadcastMutation(mutationKey = [], username, operations, onSuccess
     }
   });
 }
+var isDevelopment = (() => {
+  try {
+    return false;
+  } catch {
+    return false;
+  }
+})();
+var getHeliusApiKey = () => {
+  try {
+    return "fb1e2935-f911-4b1d-8e1c-3863f6879d42";
+  } catch {
+    return void 0;
+  }
+};
 var CONFIG = {
   privateApiHost: "https://ecency.com",
   imageHost: "https://images.ecency.com",
@@ -66,7 +80,7 @@ var CONFIG = {
       consoleOnFailover: true
     }
   ),
-  heliusApiKey: process.env.VITE_HELIUS_API_KEY,
+  heliusApiKey: getHeliusApiKey(),
   queryClient: new QueryClient(),
   plausibleHost: "https://pl.ecency.com",
   spkNode: "https://spk.good-karma.xyz",
@@ -158,35 +172,47 @@ var ConfigManager;
     return { safe: true };
   }
   function safeCompileRegex(pattern, maxLength = 200) {
-    const isDevelopment = typeof process !== "undefined" && false;
     try {
       if (!pattern) {
-        if (isDevelopment) ;
+        if (isDevelopment) {
+          console.warn(`[SDK] DMCA pattern rejected: empty pattern`);
+        }
         return null;
       }
       if (pattern.length > maxLength) {
-        if (isDevelopment) ;
+        if (isDevelopment) {
+          console.warn(`[SDK] DMCA pattern rejected: length ${pattern.length} exceeds max ${maxLength} - pattern: ${pattern.substring(0, 50)}...`);
+        }
         return null;
       }
       const staticAnalysis = analyzeRedosRisk(pattern);
       if (!staticAnalysis.safe) {
-        if (isDevelopment) ;
+        if (isDevelopment) {
+          console.warn(`[SDK] DMCA pattern rejected: static analysis failed (${staticAnalysis.reason}) - pattern: ${pattern.substring(0, 50)}...`);
+        }
         return null;
       }
       let regex;
       try {
         regex = new RegExp(pattern);
       } catch (compileErr) {
-        if (isDevelopment) ;
+        if (isDevelopment) {
+          console.warn(`[SDK] DMCA pattern rejected: compilation failed - pattern: ${pattern.substring(0, 50)}...`, compileErr);
+        }
         return null;
       }
       const runtimeTest = testRegexPerformance(regex);
       if (!runtimeTest.safe) {
-        if (isDevelopment) ;
+        if (isDevelopment) {
+          console.warn(`[SDK] DMCA pattern rejected: runtime test failed (${runtimeTest.reason}) - pattern: ${pattern.substring(0, 50)}...`);
+        }
         return null;
       }
       return regex;
     } catch (err) {
+      if (isDevelopment) {
+        console.warn(`[SDK] DMCA pattern rejected: unexpected error - pattern: ${pattern.substring(0, 50)}...`, err);
+      }
       return null;
     }
   }
@@ -197,7 +223,6 @@ var ConfigManager;
     CONFIG.dmcaTagRegexes = tags.map((pattern) => safeCompileRegex(pattern)).filter((r) => r !== null);
     CONFIG.dmcaPatternRegexes = [];
     const rejectedTagCount = tags.length - CONFIG.dmcaTagRegexes.length;
-    const isDevelopment = typeof process !== "undefined" && false;
     if (!CONFIG._dmcaInitialized && isDevelopment) {
       console.log(`[SDK] DMCA configuration loaded:`);
       console.log(`  - Accounts: ${accounts.length}`);