@wealthfolio/addon-sdk 3.6.2 → 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
@@ -70,12 +72,15 @@ mkdir src && touch src/index.ts
 
 ```typescript
 // src/index.ts
-import { createRoot, type Root } from 'react-dom/client';
-import { getAddonContext, type AddonContext } from '@wealthfolio/addon-sdk';
+import type { AddonContext } from '@wealthfolio/addon-sdk';
 import { MyComponent } from './MyComponent';
 
+let addonContext: AddonContext | undefined;
+
+const MyAddonRoute = () => <MyComponent ctx={addonContext!} />;
+
 export default function enable(context: AddonContext) {
-  let root: Root | null = null;
+  addonContext = context;
 
   // Add navigation item
   const navItem = context.sidebar.addItem({
@@ -87,11 +92,9 @@ export default function enable(context: AddonContext) {
 
   // Register route
   context.router.add({
+    id: 'my-addon',
     path: '/addons/my-addon',
-    render: ({ root: routeRoot }) => {
-      root ??= createRoot(routeRoot);
-      root.render(<MyComponent ctx={context} />);
-    },
+    component: MyAddonRoute,
   });
 
   // Log activation
@@ -99,8 +102,7 @@ export default function enable(context: AddonContext) {
 
   // Cleanup on disable
   context.onDisable(() => {
-    root?.unmount();
-    root = null;
+    addonContext = undefined;
     navItem.remove();
     context.api.logger.info('My addon deactivated');
   });
@@ -122,15 +124,15 @@ pnpm add @wealthfolio/addon-sdk @tanstack/react-query
 
 ### Requirements
 
-- **Node.js**: >= 18.0.0
-- **React**: ^18.0.0 (peer dependency)
+- **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**: 1.0.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:
@@ -179,6 +186,46 @@ my-portfolio-addon/
 └── vite.config.ts        # Build configuration
 ```
 
+### Packaged assets
+
+Static files below `assets/` and generated files below `dist/assets/` are
+indexed automatically; they do not need to be declared in `manifest.json`.
+JavaScript chunks and CSS in those directories remain runtime code/styles. Load
+other files through the add-on context so the host can keep the opaque iframe
+offline:
+
+This API requires Wealthfolio 3.7 or newer. Set `sdkVersion` and
+`minWealthfolioVersion` to `3.7.0` when using it. No permission is required.
+
+```typescript
+export default async function enable(context: AddonContext) {
+  const logoUrl = await context.assets.getUrl('assets/logo.png');
+  const configBlob = await context.assets.getBlob('assets/config.json');
+  const config = JSON.parse(await configBlob.text());
+
+  // Use logoUrl in an <img>, CSS-in-JS value, or component prop.
+}
+```
+
+The registry also provides `list()` for public path/MIME/size metadata and
+`has(path)` for feature checks. It never exposes host paths or opaque internal
+identifiers. `context.assets` is unrelated to the financial-instrument API at
+`context.api.assets`.
+
+Packaged URLs in extracted CSS are resolved automatically and relative to the
+CSS file. For example, `dist/addon.css` can use `url("./assets/background.png")`
+for `dist/assets/background.png`. `data:` and `blob:` URLs remain unchanged. CSS
+`@import` and remote URLs are not supported; bundle imported CSS and use the
+brokered network API for remote data.
+
+JavaScript image imports that compile to relative HTTP URLs cannot work in the
+opaque Blob runtime. Use `context.assets.getUrl()` instead. Blob URLs are cached
+for the add-on lifetime and revoked automatically when it is disabled. Package
+limits remain 5 MiB per file, 25 MiB uncompressed in total, and 256 entries.
+Asset roots must be directories; symlinks are rejected. See the
+[v3.6 to v3.7 migration guide](../../docs/addons/addon-migration-guide-v3.6-to-v3.7.md)
+for compatibility and troubleshooting.
+
 ## 📋 Manifest Configuration
 
 Create a `manifest.json` file in your addon root:
@@ -193,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": "1.0.0",
-  "minWealthfolioVersion": "1.0.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"],
@@ -207,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"
     }
   ]
 }
@@ -233,7 +290,7 @@ Create a `manifest.json` file in your addon root:
 | `permissions`           | `Permission[]` | Security permissions required          |
 | `minWealthfolioVersion` | `string`       | Minimum Wealthfolio version required   |
 | `keywords`              | `string[]`     | Keywords for discoverability           |
-| `icon`                  | `string`       | Addon icon (base64 or relative path)   |
+| `icon`                  | `string`       | Addon icon value supported by the host |
 
 ## 🔨 Development Guide
 
@@ -244,9 +301,12 @@ example:
 
 ```typescript
 // src/addon.tsx
-import { createRoot, type Root } from 'react-dom/client';
 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
@@ -264,7 +324,6 @@ const enable: AddonEnableFunction = (context) => {
 
   // Store references to items for cleanup
   const addedItems: Array<{ remove: () => void }> = [];
-  let root: Root | null = null;
 
   try {
     // Add sidebar navigation item with a host-supported icon token
@@ -279,11 +338,11 @@ const enable: AddonEnableFunction = (context) => {
 
     context.api.logger.debug('Sidebar navigation item added successfully');
 
-    // Create wrapper component with shared QueryClient
+    // Create wrapper component with this addon's QueryClient
     const InvestmentFeesTrackerWrapper = () => {
-      const sharedQueryClient = context.api.query.getClient();
+      const addonQueryClient = context.api.query.getClient() as QueryClient;
       return (
-        <QueryClientProvider client={sharedQueryClient}>
+        <QueryClientProvider client={addonQueryClient}>
           <InvestmentFeesTrackerAddon ctx={context} />
         </QueryClientProvider>
       );
@@ -291,11 +350,9 @@ const enable: AddonEnableFunction = (context) => {
 
     // Register route
     context.router.add({
+      id: 'investment-fees-tracker',
       path: '/addons/investment-fees-tracker',
-      render: ({ root: routeRoot }) => {
-        root ??= createRoot(routeRoot);
-        root.render(<InvestmentFeesTrackerWrapper />);
-      },
+      component: InvestmentFeesTrackerWrapper,
     });
 
     context.api.logger.debug('Route registered successfully');
@@ -310,10 +367,6 @@ const enable: AddonEnableFunction = (context) => {
   context.onDisable(() => {
     context.api.logger.info('🛑 Investment Fees Tracker addon is being disabled');
 
-    // Unmount the addon's React root
-    root?.unmount();
-    root = null;
-
     // Remove all sidebar items
     addedItems.forEach(item => {
       try {
@@ -333,32 +386,28 @@ export default enable;
 
 ### Key Features Demonstrated
 
-1. **Shared Query Client**: Uses `context.api.query.getClient()` for consistent
-   data fetching
-2. **UI Icons**: Leverages `@wealthfolio/ui` for consistent iconography
+1. **Addon Query Client**: Uses `context.api.query.getClient()` for local data
+   fetching with host invalidation bridging
+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
-6. **Sandbox Rendering**: Mounts into the route root with `createRoot` and
-   unmounts on disable
-
-````
+6. **Sandbox Rendering**: Lets the sandbox host own and update the React root
 
 ### Advanced Component Example
 
 ```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;
 }
 
 export function FeesPage({ ctx }: FeesPageProps) {
-  // Use React Query for data fetching with the shared client
+  // Use React Query for data fetching with this addon's client
   const { data: accounts, isLoading: accountsLoading } = useQuery({
     queryKey: ['accounts'],
     queryFn: () => ctx.api.accounts.getAll()
@@ -386,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 (
@@ -447,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>
             ))}
@@ -499,17 +545,20 @@ export default FeesPage;
 }
 
 export default AnalyticsDashboard;
-````
+```
 
 ### Using Hooks and State Management
 
 ```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,
@@ -523,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 {
@@ -551,7 +599,7 @@ export function usePortfolioData(accountId?: string) {
     }
 
     fetchData();
-  }, [accountId]);
+  }, [accountId, ctx]);
 
   return { holdings, performance, loading, error };
 }
@@ -565,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
 
@@ -585,7 +643,7 @@ cash flows.
   "permissions": [
     {
       "category": "portfolio",
-      "functions": ["getHoldings", "getHolding", "calculatePerformanceSummary"],
+      "functions": ["getHoldings", "getHolding"],
       "purpose": "Display detailed portfolio analytics and performance metrics"
     },
     {
@@ -595,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"
     }
   ]
 }
@@ -604,6 +667,20 @@ cash flows.
 
 ## 🛠️ Build Configuration
 
+Wealthfolio 3.7 supports Chrome/Edge 107+, Firefox 104+, and Safari 16+. The
+desktop app requires macOS 12+ and the native mobile app requires iOS/iPadOS
+16+. On macOS 12, apply current macOS and Safari updates so the system WKWebView
+meets the Safari 16 floor. Addons run inside the platform system WebView, so
+build against this browser floor rather than relying on the browser used during
+development.
+
+Files below `assets/` and `dist/assets/` are private to the addon package. Use
+`ctx.assets.list()`, `ctx.assets.getBlob(path)`, and `ctx.assets.getUrl(path)`
+to access them. Packaged images, fonts, media, CSS, and WebAssembly are
+supported; Worker and service-worker entry points, popups, direct network
+requests, and remote CSS imports are not. Use the host's brokered APIs,
+including `ctx.api.network.request()`, for declared external access.
+
 ### Vite Configuration
 
 Create a `vite.config.ts` for optimal bundling:
@@ -616,6 +693,7 @@ import { resolve } from 'path';
 export default defineConfig({
   plugins: [react()],
   build: {
+    target: ['chrome107', 'edge107', 'firefox104', 'safari16'],
     lib: {
       entry: resolve(__dirname, 'src/index.ts'),
       name: 'MyPortfolioAddon',
@@ -750,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
 
@@ -761,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)`
 
@@ -777,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 shared QueryClient instance                           | 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)
@@ -856,51 +958,51 @@ 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');
 ```
 
-### Shared QueryClient Integration
+### Addon QueryClient Integration
 
-The SDK provides access to Wealthfolio's shared React Query client for
-consistent data fetching and caching:
+The sandbox provides one React Query client per addon. Its cache is reused
+across that addon's route renders, not shared with the host or other addons.
+Invalidate/refetch operations are mirrored to the host:
 
 ```typescript
-// Access the shared QueryClient instance
-const sharedQueryClient = 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={sharedQueryClient}>
-      <MyAddonComponent />
+    <QueryClientProvider client={addonQueryClient}>
+      <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
   });
 
@@ -908,15 +1010,24 @@ function MyAddonComponent() {
 }
 ```
 
-**Benefits of Shared QueryClient:**
+**Benefits of the sandbox-scoped QueryClient:**
 
-- **Consistent Caching**: Share cache with the main application
-- **Performance**: Avoid duplicate API calls across addons
-- **Synchronization**: Real-time updates when data changes
-- **Memory Efficiency**: Single cache instance for all data
+- **Isolation**: Cached financial data and observers do not leak across addons
+- **Route continuity**: One cache is retained across the addon's pages
+- **Coordination**: Addon invalidations/refetches are also sent to the host
+- **Lifecycle cleanup**: The cache is cleared with the addon sandbox
+
+Host-originated invalidations do not mutate the addon cache automatically. Use
+the relevant `ctx.api.events` subscription and invalidate locally when the addon
+must react to changes initiated elsewhere.
 
 ## 🔄 Migration Guide
 
+For Wealthfolio 3.7, see the
+[v3.6 to v3.7 migration guide](../../docs/addons/addon-migration-guide-v3.6-to-v3.7.md).
+It covers backward compatibility, the private asset registry, CSS behavior, and
+the required development-tools upgrade.
+
 ### From v1.0.0 to v1.1.0
 
 #### Context Access
@@ -925,9 +1036,14 @@ function MyAddonComponent() {
 // 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
@@ -1008,6 +1124,7 @@ import { resolve } from 'path';
 export default defineConfig({
   plugins: [react()],
   build: {
+    target: ['chrome107', 'edge107', 'firefox104', 'safari16'],
     lib: {
       entry: resolve(__dirname, 'src/index.ts'),
       name: 'MyPortfolioAddon',
@@ -1153,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
@@ -1186,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();
@@ -1199,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;
   }
@@ -1270,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
+  });
 }
 ```
 
@@ -1290,6 +1397,7 @@ function usePortfolioData(accountId: string) {
 // vite.config.ts - optimize chunks
 export default defineConfig({
   build: {
+    target: ['chrome107', 'edge107', 'firefox104', 'safari16'],
     rollupOptions: {
       output: {
         manualChunks: {
@@ -1382,7 +1490,8 @@ We follow [Semantic Versioning](https://semver.org/) (SemVer):
 
 | SDK Version | Wealthfolio Version | Node.js   | React   |
 | ----------- | ------------------- | --------- | ------- |
-| 1.0.x       | >= 1.0.0            | >= 18.0.0 | ^18.0.0 |
+| 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 |
 
 ### Installation from Registry
@@ -1394,10 +1503,10 @@ We follow [Semantic Versioning](https://semver.org/) (SemVer):
 npm install @wealthfolio/addon-sdk
 
 # Specific version
-npm install @wealthfolio/addon-sdk@1.0.0
+npm install @wealthfolio/addon-sdk@3.8.0
 
 # Version range
-npm install @wealthfolio/addon-sdk@^1.0.0
+npm install @wealthfolio/addon-sdk@^3.8.0
 ```
 
 #### Beta/Preview Releases
@@ -1633,6 +1742,7 @@ npm list react react-dom
 // vite.config.ts
 export default defineConfig({
   build: {
+    target: ['chrome107', 'edge107', 'firefox104', 'safari16'],
     rollupOptions: {
       external: ['react', 'react-dom', '@wealthfolio/addon-sdk'],
     },
@@ -1652,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
@@ -1722,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}`);
 }
 ```
 
@@ -1744,6 +1849,7 @@ const HeavyComponent = lazy(() => import('./HeavyComponent'));
 // vite.config.ts
 export default defineConfig({
   build: {
+    target: ['chrome107', 'edge107', 'firefox104', 'safari16'],
     rollupOptions: {
       output: {
         manualChunks: {