@wealthfolio/addon-sdk 3.7.0 → 3.8.0

package/README.md

@@ -42,6 +42,8 @@ integrations, and visualizations.
 - **ESM Support**: Modern ECMAScript modules with tree-shaking support
 - **Comprehensive Logging**: Built-in logging system with multiple levels
 - **Event System**: Subscribe to application events and state changes
+- **Spend Categorization**: Manage reusable expense, income, and savings rules
+- **Localization**: Follow the host locale with scoped addon translations
 - **Performance Optimized**: Lightweight bundle with minimal overhead
 - **Developer Tools**: Built-in debugging and development utilities
 - **Backwards Compatible**: Stable API with semantic versioning
@@ -125,12 +127,12 @@ pnpm add @wealthfolio/addon-sdk @tanstack/react-query
 - **Node.js**: >= 20.0.0
 - **React**: ^19.2.4 (peer dependency and host-provided version)
 - **TypeScript**: ^5.0.0 (recommended for development)
-- **React Query**: ^4.0.0 or ^5.0.0 (for data fetching)
+- **React Query**: ^5.90.0 (for data fetching)
 
 ### Package Information
 
 - **Package Name**: `@wealthfolio/addon-sdk`
-- **Current Version**: 3.7.0
+- **Current Version**: 3.8.0
 - **Bundle Format**: ESM (ECMAScript Modules)
 - **Type Definitions**: Included (TypeScript ready)
 - **License**: MIT
@@ -140,23 +142,28 @@ pnpm add @wealthfolio/addon-sdk @tanstack/react-query
 
 ### Import Methods
 
-The SDK supports multiple import patterns:
+The SDK supports a public entry point plus focused subpath imports:
 
 ```typescript
-// Default import (recommended)
-import { getAddonContext } from '@wealthfolio/addon-sdk';
-
-// Named imports
-import { AddonContext, PermissionLevel } from '@wealthfolio/addon-sdk';
-
-// Type-only imports
-import type { AddonManifest, Permission } from '@wealthfolio/addon-sdk';
-
-// Subpath imports
-import type { PortfolioHolding } from '@wealthfolio/addon-sdk/types';
-import { PERMISSION_CATEGORIES } from '@wealthfolio/addon-sdk/permissions';
+// Public entry point (recommended)
+import type {
+  AddonContext,
+  AddonManifest,
+  Holding,
+  Permission,
+  RiskLevel,
+} from '@wealthfolio/addon-sdk';
+import { PERMISSION_CATEGORIES } from '@wealthfolio/addon-sdk';
+
+// Optional module-specific subpath imports
+import type { AddonManifest as Manifest } from '@wealthfolio/addon-sdk/manifest';
+import type { Permission as AddonPermission } from '@wealthfolio/addon-sdk/permissions';
 ```
 
+The `/types` subpath contains core context, routing, sidebar, and event types.
+Financial data types such as `Account`, `Activity`, and `Holding` are exported
+from the package root.
+
 ## 🏗️ Project Structure
 
 Create your addon with the following recommended structure:
@@ -233,11 +240,16 @@ Create a `manifest.json` file in your addon root:
   "homepage": "https://github.com/yourname/investment-fees-tracker",
   "license": "MIT",
   "main": "dist/addon.js",
-  "sdkVersion": "3.7.0",
-  "minWealthfolioVersion": "3.7.0",
+  "sdkVersion": "3.8.0",
+  "minWealthfolioVersion": "3.8.0",
   "keywords": ["portfolio", "fees", "tracking", "analytics"],
   "icon": "data:image/svg+xml;base64,...",
   "permissions": [
+    {
+      "category": "accounts",
+      "functions": ["getAll"],
+      "purpose": "List accounts whose holdings will be analyzed"
+    },
     {
       "category": "portfolio",
       "functions": ["getHoldings"],
@@ -247,6 +259,11 @@ Create a `manifest.json` file in your addon root:
       "category": "activities",
       "functions": ["getAll"],
       "purpose": "Analyze transaction history for fee calculations"
+    },
+    {
+      "category": "performance",
+      "functions": ["calculateSummary"],
+      "purpose": "Calculate account performance alongside fee totals"
     }
   ]
 }
@@ -285,7 +302,11 @@ example:
 ```typescript
 // src/addon.tsx
 import { QueryClientProvider } from '@tanstack/react-query';
-import type { AddonContext, AddonEnableFunction } from '@wealthfolio/addon-sdk';
+import type {
+  AddonContext,
+  AddonEnableFunction,
+  QueryClient,
+} from '@wealthfolio/addon-sdk';
 import FeesPage from './pages/fees-page';
 
 // Main addon component
@@ -319,7 +340,7 @@ const enable: AddonEnableFunction = (context) => {
 
     // Create wrapper component with this addon's QueryClient
     const InvestmentFeesTrackerWrapper = () => {
-      const addonQueryClient = context.api.query.getClient();
+      const addonQueryClient = context.api.query.getClient() as QueryClient;
       return (
         <QueryClientProvider client={addonQueryClient}>
           <InvestmentFeesTrackerAddon ctx={context} />
@@ -367,7 +388,7 @@ export default enable;
 
 1. **Addon Query Client**: Uses `context.api.query.getClient()` for local data
    fetching with host invalidation bridging
-2. **UI Icons**: Leverages `@wealthfolio/ui` for consistent iconography
+2. **UI Icons**: Uses a host-supported icon token for consistent navigation
 3. **Error Handling**: Comprehensive error handling with logging
 4. **Resource Management**: Proper cleanup of sidebar items and event listeners
 5. **TypeScript**: Full type safety with proper imports
@@ -377,10 +398,9 @@ export default enable;
 
 ```typescript
 // components/FeesPage.tsx
-import React, { useEffect, useState } from 'react';
+import React, { useEffect } from 'react';
 import { useQuery } from '@tanstack/react-query';
 import type { AddonContext } from '@wealthfolio/addon-sdk';
-import type { Holding, Account, Activity } from '@wealthfolio/addon-sdk/types';
 
 interface FeesPageProps {
   ctx: AddonContext;
@@ -415,25 +435,20 @@ export function FeesPage({ ctx }: FeesPageProps) {
 
   // Calculate total fees from activities
   const totalFees = React.useMemo(() => {
-    if (!activities?.data) return 0;
+    if (!activities) return 0;
 
-    return activities.data.reduce((total, activity) => {
+    return activities.reduce((total, activity) => {
       // Look for fee-related activities or transaction costs
-      const fee = activity.fee || 0;
+      const fee = Number(activity.fee ?? 0);
       return total + fee;
     }, 0);
   }, [activities]);
 
   useEffect(() => {
     if (!isLoading) {
-      ctx.api.logger.info('Fees data loaded successfully', {
-        accountsCount: accounts?.length,
-        holdingsCount: holdings?.length,
-        activitiesCount: activities?.data?.length,
-        totalFees
-      });
+      ctx.api.logger.info("Fees data loaded successfully");
     }
-  }, [isLoading, accounts, holdings, activities, totalFees, ctx.api.logger]);
+  }, [isLoading, ctx.api.logger]);
 
   if (isLoading) {
     return (
@@ -476,14 +491,16 @@ export function FeesPage({ ctx }: FeesPageProps) {
         <div className="bg-white p-6 rounded-lg shadow border">
           <h2 className="text-xl font-semibold mb-4">Recent Fee Activities</h2>
           <div className="space-y-3">
-            {activities?.data?.slice(0, 5).map((activity) => (
+            {activities?.slice(0, 5).map((activity) => (
               <div key={activity.id} className="flex justify-between items-center py-2 border-b">
                 <div>
                   <p className="font-medium">{activity.activityType}</p>
-                  <p className="text-sm text-gray-600">{activity.date}</p>
+                  <p className="text-sm text-gray-600">
+                    {activity.date.toLocaleDateString()}
+                  </p>
                 </div>
                 <span className="text-red-600 font-medium">
-                  ${(activity.fee || 0).toFixed(2)}
+                  ${Number(activity.fee ?? 0).toFixed(2)}
                 </span>
               </div>
             ))}
@@ -535,10 +552,13 @@ export default AnalyticsDashboard;
 ```typescript
 // hooks/usePortfolioData.ts
 import { useState, useEffect } from 'react';
-import { getAddonContext } from '@wealthfolio/addon-sdk';
-import type { Holding, PerformanceResult } from '@wealthfolio/addon-sdk/types';
+import type {
+  AddonContext,
+  Holding,
+  PerformanceResult,
+} from '@wealthfolio/addon-sdk';
 
-export function usePortfolioData(accountId?: string) {
+export function usePortfolioData(ctx: AddonContext, accountId?: string) {
   const [holdings, setHoldings] = useState<Holding[]>([]);
   const [performance, setPerformance] = useState<PerformanceResult | null>(
     null,
@@ -552,26 +572,25 @@ export function usePortfolioData(accountId?: string) {
         setLoading(true);
         setError(null);
 
-        const ctx = getAddonContext();
+        if (!accountId) {
+          setHoldings([]);
+          setPerformance(null);
+          return;
+        }
 
-        const holdingsData = await ctx.api.portfolio.getHoldings(
-          accountId || '',
-        );
+        const holdingsData = await ctx.api.portfolio.getHoldings(accountId);
         setHoldings(holdingsData);
 
-        if (accountId) {
-          const performanceData =
-            await ctx.api.portfolio.calculatePerformanceSummary({
-              itemType: 'account',
-              itemId: accountId,
-            });
-          console.log(
-            performanceData.returns.twr,
-            performanceData.returns.irr,
-            performanceData.risk.maxDrawdown,
-          );
-          setPerformance(performanceData);
-        }
+        const performanceData = await ctx.api.performance.calculateSummary({
+          itemType: 'account',
+          itemId: accountId,
+        });
+        console.log(
+          performanceData.returns.twr,
+          performanceData.returns.irr,
+          performanceData.risk.maxDrawdown,
+        );
+        setPerformance(performanceData);
       } catch (err) {
         setError(err instanceof Error ? err.message : 'Unknown error');
       } finally {
@@ -580,7 +599,7 @@ export function usePortfolioData(accountId?: string) {
     }
 
     fetchData();
-  }, [accountId]);
+  }, [accountId, ctx]);
 
   return { holdings, performance, loading, error };
 }
@@ -594,18 +613,28 @@ cash flows.
 
 ### Permission Categories
 
-| Category             | Risk Level | Description                     |
-| -------------------- | ---------- | ------------------------------- |
-| `ui`                 | Low        | Add navigation items and routes |
-| `market-data`        | Low        | Access market prices and quotes |
-| `events`             | Low        | Listen to application events    |
-| `currency`           | Low        | Access exchange rates           |
-| `portfolio`          | Medium     | Access holdings and valuations  |
-| `files`              | Medium     | File dialog operations          |
-| `financial-planning` | Medium     | Goals and contribution limits   |
-| `activities`         | High       | Transaction history access      |
-| `accounts`           | High       | Account management              |
-| `settings`           | High       | Application configuration       |
+| Category              | Risk Level | Description                                  |
+| --------------------- | ---------- | -------------------------------------------- |
+| `market-data`         | Low        | Search and synchronize market data           |
+| `quotes`              | Low        | Read and update quotes                       |
+| `events`              | Low        | Listen to application events                 |
+| `currency`            | Low        | Access exchange rates                        |
+| `assets`              | Medium     | Read and update financial asset profiles     |
+| `performance`         | Medium     | Calculate portfolio performance              |
+| `spending`            | Medium     | View categories and manage spending rules    |
+| `financial-planning`  | Medium     | Manage goals and allocations                 |
+| `contribution-limits` | Medium     | Manage contribution limits                   |
+| `files`               | Medium     | Open host file dialogs                       |
+| `settings`            | Medium     | Access application configuration             |
+| `portfolio`           | High       | Access holdings and valuations               |
+| `activities`          | High       | Access and modify transaction history        |
+| `accounts`            | High       | Access and create accounts                   |
+| `snapshots`           | High       | Access and modify holdings snapshots         |
+| `network`             | High       | Request declared external HTTPS hosts        |
+| `secrets`             | High       | Store and use secrets through the OS keyring |
+
+`ui`, `navigation`, `query`, `toast`, `logger`, and `storage` are baseline
+capabilities and must not be declared as permissions.
 
 ### Declaring Permissions
 
@@ -614,7 +643,7 @@ cash flows.
   "permissions": [
     {
       "category": "portfolio",
-      "functions": ["getHoldings", "getHolding", "calculatePerformanceSummary"],
+      "functions": ["getHoldings", "getHolding"],
       "purpose": "Display detailed portfolio analytics and performance metrics"
     },
     {
@@ -624,8 +653,13 @@ cash flows.
     },
     {
       "category": "market-data",
-      "functions": ["searchTicker", "getQuoteHistory"],
+      "functions": ["searchTicker"],
       "purpose": "Show price charts and enable ticker search functionality"
+    },
+    {
+      "category": "spending",
+      "functions": ["getCategories", "saveRule"],
+      "purpose": "Save categorization rules selected by the user"
     }
   ]
 }
@@ -794,7 +828,6 @@ Add an item to the application sidebar.
   `chart-bar`, or `calendar-dots`
 - `config.route` (string): Navigation route
 - `config.order` (number): Display order (optional)
-- `config.onClick` (function): Click handler (optional)
 
 **Returns:** `SidebarItemHandle` with `remove()` method
 
@@ -805,8 +838,10 @@ Register a new route in the application.
 **Parameters:**
 
 - `route.path` (string): Route path pattern
-- `route.render` (function): `({ root, location }) => void` — mount your React
-  root into the provided `root` element
+- `route.component` (component): Preferred; the host mounts the React component
+  and passes the current `location`
+- `route.render` (function): Legacy imperative alternative receiving
+  `{ root, location }`
 
 #### `onDisable(callback)`
 
@@ -821,49 +856,72 @@ Register cleanup callback for addon disable.
 All data access is performed through the context's `api` property:
 
 ```typescript
-const ctx = getAddonContext();
+// Use the ctx parameter supplied to enable(ctx), or pass it to this helper.
 
 // Portfolio data
 const holdings = await ctx.api.portfolio.getHoldings(accountId);
 const accounts = await ctx.api.accounts.getAll();
 
 // Market data
-const quotes = await ctx.api.marketData.getQuoteHistory(symbol);
-const profile = await ctx.api.marketData.getAssetProfile(assetId);
+const symbols = await ctx.api.market.searchTicker('AAPL');
+const quotes = await ctx.api.quotes.getHistory(assetId);
+const profile = await ctx.api.assets.getProfile(assetId);
 
 // Financial planning
 const goals = await ctx.api.goals.getAll();
-const limits = await ctx.api.financialPlanning.getContributionLimit();
+const limits = await ctx.api.contributionLimits.getAll();
+
+// Historical exchange rates and spend categorization (Wealthfolio 3.8+)
+const rates = await ctx.api.exchangeRates.getRatesForDates([
+  { fromCurrency: 'USD', toCurrency: 'EUR', date: '2026-09-04' },
+]);
+const spendCategories = await ctx.api.spending.getCategories('expense');
 
 // Settings
-const settings = await ctx.api.getSettings();
+const settings = await ctx.api.settings.get();
 
 // Logging and debugging
 ctx.api.logger.info('Operation completed successfully');
-ctx.api.logger.error('Error occurred:', error);
-ctx.api.logger.debug('Debug info:', debugData);
+ctx.api.logger.error(`Error occurred: ${String(error)}`);
+ctx.api.logger.debug(`Debug info: ${JSON.stringify(debugData)}`);
 ```
 
 ### Available API Methods
 
-| Method                                          | Description                                               | Permission Required  |
-| ----------------------------------------------- | --------------------------------------------------------- | -------------------- |
-| `portfolio.getHoldings(accountId)`              | Get portfolio holdings for account                        | `portfolio`          |
-| `portfolio.getHolding(accountId, assetId)`      | Get specific holding                                      | `portfolio`          |
-| `portfolio.calculatePerformanceSummary(params)` | Calculate performance metrics                             | `portfolio`          |
-| `portfolio.getIncomeSummary()`                  | Get income summary data                                   | `portfolio`          |
-| `accounts.getAll()`                             | Get all account information                               | `accounts`           |
-| `accounts.create(account)`                      | Create new account                                        | `accounts`           |
-| `activities.getAll(accountId?)`                 | Get activity history (optionally filtered to one account) | `activities`         |
-| `activities.create(activity)`                   | Create new activity                                       | `activities`         |
-| `marketData.getQuoteHistory(symbol)`            | Get historical quotes                                     | `market-data`        |
-| `marketData.getAssetProfile(assetId)`           | Get asset profile                                         | `market-data`        |
-| `marketData.searchTicker(query)`                | Search for tickers                                        | `market-data`        |
-| `goals.getAll()`                                | Get financial goals                                       | `financial-planning` |
-| `goals.getFunding(goalId)`                      | Get funding rules for a goal                              | `financial-planning` |
-| `goals.saveFunding(goalId, rules)`              | Save funding rules for a goal                             | `financial-planning` |
-| `settings.get()`                                | Get app settings                                          | `settings`           |
-| `query.getClient()`                             | Get this addon's QueryClient                              | None                 |
+| Method                                     | Description                                 | Permission Required   |
+| ------------------------------------------ | ------------------------------------------- | --------------------- |
+| `portfolio.getHoldings(accountId)`         | Get portfolio holdings for an account       | `portfolio`           |
+| `portfolio.getHolding(accountId, assetId)` | Get a specific holding                      | `portfolio`           |
+| `performance.calculateSummary(params)`     | Calculate performance metrics               | `performance`         |
+| `accounts.getAll()`                        | Get all account information                 | `accounts`            |
+| `accounts.create(account)`                 | Create an account                           | `accounts`            |
+| `activities.getAll(accountId?)`            | Get activity history                        | `activities`          |
+| `activities.create(activity)`              | Create an activity                          | `activities`          |
+| `market.searchTicker(query)`               | Search for tickers                          | `market-data`         |
+| `assets.getProfile(assetId)`               | Get a financial asset profile               | `assets`              |
+| `quotes.getHistory(assetId)`               | Get historical quotes                       | `quotes`              |
+| `exchangeRates.getRatesForDates(pairs)`    | Resolve dated exchange rates                | `currency`            |
+| `spending.isEnabled()`                     | Check whether Spending is enabled           | `spending`            |
+| `spending.getCategories(kind?)`            | List expense, income, or savings categories | `spending`            |
+| `spending.getRules()`                      | List this addon's categorization rules      | `spending`            |
+| `spending.saveRule(rule)`                  | Create or update an addon-owned rule        | `spending`            |
+| `spending.deleteRule(ruleKey)`             | Delete an addon-owned rule                  | `spending`            |
+| `spending.rerunRules(onlyUncategorized?)`  | Re-run categorization rules                 | `spending`            |
+| `goals.getAll()`                           | Get financial goals                         | `financial-planning`  |
+| `contributionLimits.getAll()`              | Get contribution limits                     | `contribution-limits` |
+| `settings.get()`                           | Get application settings                    | `settings`            |
+| `query.getClient()`                        | Get this addon's QueryClient                | None                  |
+
+The Spending and dated exchange-rate APIs require Wealthfolio 3.8 or newer. See
+the [complete API reference](../../docs/addons/addon-api-reference.md).
+
+### Localization
+
+Wealthfolio 3.8 addons can register private translation bundles with
+`registerTranslations()` and read them from React components with
+`useAddonTranslation()`. Addons using these exports must set
+`minWealthfolioVersion` to `3.8.0` or newer. See the
+[localization guide](../../docs/addons/addon-localization.md).
 
 > Tip: `activities.getAll` accepts an optional account ID string to scope
 > results to a single account. The SDK normalizes this for both desktop (Tauri)
@@ -900,21 +958,14 @@ const response = await ctx.api.activities.search(
 The SDK provides a comprehensive logging system:
 
 ```typescript
-const ctx = getAddonContext();
+// Use the ctx parameter supplied to enable(ctx), or pass it to this helper.
 
-// Log levels: 'error', 'warn', 'info', 'debug'
-ctx.api.logger.error('Critical error occurred', { error, context });
-ctx.api.logger.warn('Warning message', additionalData);
+// Each method accepts one string message.
+ctx.api.logger.error(`Critical error occurred: ${String(error)}`);
+ctx.api.logger.warn(`Warning message: ${String(additionalData)}`);
 ctx.api.logger.info('Information message');
-ctx.api.logger.debug('Debug information', debugObject);
-
-// Set log level (for development)
-ctx.api.logger.setLevel('debug');
-
-// Check if logging level is enabled
-if (ctx.api.logger.isLevelEnabled('debug')) {
-  ctx.api.logger.debug('Expensive debug operation', expensiveData);
-}
+ctx.api.logger.debug(`Debug information: ${JSON.stringify(debugObject)}`);
+ctx.api.logger.trace('Detailed trace message');
 ```
 
 ### Addon QueryClient Integration
@@ -924,28 +975,34 @@ across that addon's route renders, not shared with the host or other addons.
 Invalidate/refetch operations are mirrored to the host:
 
 ```typescript
-// Access this addon's QueryClient instance
-const addonQueryClient = context.api.query.getClient();
+import { QueryClientProvider, useQuery } from '@tanstack/react-query';
+import type { AddonContext, QueryClient } from '@wealthfolio/addon-sdk';
 
 // Wrap your components with QueryClientProvider
-const MyAddonWrapper = () => {
+const MyAddonWrapper = ({ ctx }: { ctx: AddonContext }) => {
+  const addonQueryClient = ctx.api.query.getClient() as QueryClient;
+
   return (
     <QueryClientProvider client={addonQueryClient}>
-      <MyAddonComponent />
+      <MyAddonComponent ctx={ctx} />
     </QueryClientProvider>
   );
 };
 
 // Use React Query hooks in your components
-function MyAddonComponent() {
+function MyAddonComponent({ ctx }: { ctx: AddonContext }) {
   const { data: accounts, isLoading } = useQuery({
     queryKey: ['accounts'],
     queryFn: () => ctx.api.accounts.getAll()
   });
 
+  const selectedAccountId = accounts?.[0]?.id;
   const { data: holdings } = useQuery({
     queryKey: ['holdings', selectedAccountId],
-    queryFn: () => ctx.api.portfolio.getHoldings(selectedAccountId),
+    queryFn: () =>
+      selectedAccountId
+        ? ctx.api.portfolio.getHoldings(selectedAccountId)
+        : Promise.resolve([]),
     enabled: !!selectedAccountId
   });
 
@@ -979,9 +1036,14 @@ the required development-tools upgrade.
 // Before
 import ctx from '@wealthfolio/addon-sdk';
 
-// After (recommended)
-import { getAddonContext } from '@wealthfolio/addon-sdk';
-const ctx = getAddonContext();
+// Current SDK
+import type { AddonEnableFunction } from '@wealthfolio/addon-sdk';
+
+const enable: AddonEnableFunction = (ctx) => {
+  // Pass ctx to components, hooks, and helper functions that need host APIs.
+};
+
+export default enable;
 ```
 
 #### Type Imports
@@ -1208,9 +1270,9 @@ npm publish --tag beta
 
 ```typescript
 // In your addon
-const ctx = getAddonContext();
-ctx.api.logger.setLevel('debug');
-ctx.api.logger.debug('Debug information:', data);
+function logDebug(ctx: AddonContext, data: unknown) {
+  ctx.api.logger.debug(`Debug information: ${JSON.stringify(data)}`);
+}
 ```
 
 #### 2. Development Console
@@ -1241,11 +1303,9 @@ if (process.env.NODE_ENV === 'development') {
 #### 1. Error Handling
 
 ```typescript
-import { getAddonContext } from '@wealthfolio/addon-sdk';
-
-async function fetchPortfolioData() {
-  const ctx = getAddonContext();
+import type { AddonContext } from '@wealthfolio/addon-sdk';
 
+async function fetchPortfolioData(ctx: AddonContext) {
   try {
     // Get all accounts first, then holdings for each
     const accounts = await ctx.api.accounts.getAll();
@@ -1254,14 +1314,8 @@ async function fetchPortfolioData() {
     ).then((results) => results.flat());
     return holdings;
   } catch (error) {
-    ctx.api.logger.error('Failed to fetch holdings:', error);
-
-    // Handle different error types
-    if (error.code === 'PERMISSION_DENIED') {
-      // Show permission error to user
-    } else if (error.code === 'NETWORK_ERROR') {
-      // Handle network issues
-    }
+    const message = error instanceof Error ? error.message : String(error);
+    ctx.api.logger.error(`Failed to fetch holdings: ${message}`);
 
     throw error;
   }
@@ -1325,17 +1379,15 @@ const HeavyChart = lazy(() => import('./components/HeavyChart'));
 
 ```typescript
 // Use React Query or SWR for caching
-import { useQuery } from 'react-query';
+import { useQuery } from '@tanstack/react-query';
 
 function usePortfolioData(accountId: string) {
-  return useQuery(
-    ['portfolio', accountId],
-    () => ctx.api.portfolio.getHoldings(accountId),
-    {
-      staleTime: 5 * 60 * 1000, // 5 minutes
-      cacheTime: 10 * 60 * 1000, // 10 minutes
-    },
-  );
+  return useQuery({
+    queryKey: ['portfolio', accountId],
+    queryFn: () => ctx.api.portfolio.getHoldings(accountId),
+    staleTime: 5 * 60 * 1000, // 5 minutes
+    gcTime: 10 * 60 * 1000, // 10 minutes
+  });
 }
 ```
 
@@ -1438,6 +1490,7 @@ We follow [Semantic Versioning](https://semver.org/) (SemVer):
 
 | SDK Version | Wealthfolio Version | Node.js   | React   |
 | ----------- | ------------------- | --------- | ------- |
+| 3.8.x       | >= 3.8.0            | >= 20.0.0 | ^19.2.4 |
 | 3.7.x       | >= 3.7.0            | >= 20.0.0 | ^19.2.4 |
 | 0.9.x       | >= 0.9.0            | >= 16.0.0 | ^17.0.0 |
 
@@ -1450,10 +1503,10 @@ We follow [Semantic Versioning](https://semver.org/) (SemVer):
 npm install @wealthfolio/addon-sdk
 
 # Specific version
-npm install @wealthfolio/addon-sdk@3.7.0
+npm install @wealthfolio/addon-sdk@3.8.0
 
 # Version range
-npm install @wealthfolio/addon-sdk@^3.7.0
+npm install @wealthfolio/addon-sdk@^3.8.0
 ```
 
 #### Beta/Preview Releases
@@ -1709,31 +1762,29 @@ export default defineConfig({
   "permissions": [
     {
       "category": "portfolio",
-      "functions": ["holdings"],
+      "functions": ["getHoldings"],
       "purpose": "Access portfolio data for analytics"
     }
   ]
 }
 ```
 
-#### 6. Context Not Available
+#### 6. Context Not Available in a Component or Helper
 
-**Error**: `getAddonContext() returns undefined`
+**Error**: A component or helper cannot access the addon context.
 
 **Solutions**:
 
 ```typescript
-// Ensure you're calling it within addon context
-function MyComponent() {
-  useEffect(() => {
-    // Call context inside useEffect or event handlers
-    const ctx = getAddonContext();
-    // ... use context
-  }, []);
+import type { AddonContext, AddonEnableFunction } from '@wealthfolio/addon-sdk';
+
+function MyComponent({ ctx }: { ctx: AddonContext }) {
+  return <button onClick={() => ctx.api.toast.success('Ready')}>Test API</button>;
 }
 
-// Don't call at module level
-// const ctx = getAddonContext(); // ❌ Wrong
+const enable: AddonEnableFunction = (ctx) => {
+  // Capture ctx for a route wrapper, or pass it directly to helpers/components.
+};
 ```
 
 ### Development Environment Issues
@@ -1779,13 +1830,10 @@ ls -la dist/  # Should update when you save files
 try {
   const accounts = await ctx.api.accounts.getAll();
   const data = await ctx.api.portfolio.getHoldings(accounts[0]?.id);
-  ctx.api.logger.info('Data loaded successfully', { count: data.length });
+  ctx.api.logger.info(`Data loaded successfully (${data.length} holdings)`);
 } catch (error) {
-  ctx.api.logger.error('API call failed', {
-    error: error.message,
-    stack: error.stack,
-    timestamp: new Date().toISOString(),
-  });
+  const message = error instanceof Error ? error.message : String(error);
+  ctx.api.logger.error(`API call failed: ${message}`);
 }
 ```