CHANGELOG.fr.md

@@ -11,6 +11,8 @@
 - **Bilan — éditeur de snapshot (type simple)** (route `/balance/snapshot`) : deuxième tranche de la feature *Bilan*. La nouvelle page permet de créer ou modifier un snapshot daté de votre patrimoine : choisissez une date (par défaut aujourd'hui), saisissez la valeur de chaque compte actif groupé par catégorie, puis enregistrez. Le mode est piloté par le paramètre `?date=` de l'URL — si un snapshot existe déjà à cette date, la page bascule automatiquement en mode édition (la contrainte UNIQUE sur `balance_snapshots.snapshot_date` garantit un snapshot par jour). La date d'un snapshot existant est immuable : pour la changer, supprimez puis recréez. Un bouton *Pré-remplir depuis le précédent* copie les valeurs du snapshot antérieur le plus récent (comptes simples uniquement — les comptes cotés seront pris en charge quand l'éditeur coté arrivera). Un bouton *Supprimer* affiche une modal de double confirmation qui exige de retaper la date du snapshot avant d'activer l'action destructive. Seules les valeurs de type simple sont acceptées à ce stade (`quantity` et `unit_price` sont laissés `NULL`) ; l'éditeur coté (quantité × prix unitaire + récupération de prix) arrivera dans une prochaine version. Nouveau hook `useSnapshotEditor` (`useReducer` couvrant tout le cycle de vie) et deux nouveaux composants `SnapshotEditor` + `SnapshotLineRow`. i18n FR/EN sous `balance.snapshot.*` (#146)
 - **Bilan — fondations du schéma et page Comptes** (route `/balance/accounts`) : première tranche de la nouvelle feature *Bilan*. La migration SQL v9 introduit 5 tables (`balance_categories`, `balance_accounts`, `balance_snapshots`, `balance_snapshot_lines`, `balance_account_transfers`) avec 7 index et seede 7 catégories standard — Encaisse, CELI, REER, Fonds commun, Autre (type simple) + Action et Cryptomonnaie (type coté). La colonne `currency` est verrouillée à `CAD` via une contrainte CHECK au MVP — le support multi-devises arrivera plus tard. La nouvelle page expose deux onglets : *Comptes* (CRUD complet sur les comptes de l'utilisateur, archivage soft plutôt que suppression dure pour préserver les snapshots historiques) et *Catégories* (renommer une catégorie, créer des catégories de type simple, supprimer celles créées par l'utilisateur — les catégories standard sont protégées). Couverture i18n FR/EN complète sous `balance.*`. Snapshots, transferts, rendements et price-fetching premium arriveront dans les prochaines issues ; pour l'instant la route est accessible directement par URL (pas encore d'entrée sidebar) (#138)
 
+- **Récupération de prix premium pour actions (best-effort) et crypto (exchanges directs)** — vie privée préservée via proxy maximus-api. Toggle dans les Paramètres pour révoquer le consentement. (#160)
+
 ### Modifié
 - **Clé publique Ed25519 de licence** : la clé embarquée a été rotée pour correspondre au serveur de licences `maximus-api` qui vient d'être déployé en production (live à `https://api.lacompagniemaximus.com`). Aucune licence n'avait été émise en production avec l'ancienne clé, donc ce changement est invisible pour les utilisateurs existants — mais `/licenses/activate` répond désormais, donc l'activation par machine (issue #53) sera débloquée dès la sortie de cette version. La clé privée correspondante vit uniquement sur le serveur (#49)
 

CHANGELOG.md

@@ -11,6 +11,8 @@
 - **Balance sheet — snapshot editor (simple kind)** (route `/balance/snapshot`): second slice of the *Bilan* feature. The new page lets you create or edit a dated snapshot of your balance: pick a date (defaulting to today), enter the value of each active account grouped by category, and save. The mode is driven by the `?date=` query parameter — when a snapshot already exists at that date the page automatically flips into edit mode (the underlying `balance_snapshots.snapshot_date` UNIQUE constraint guarantees one snapshot per day). The date of an existing snapshot is immutable: to change it, delete the snapshot and create a new one. A *Prefill from previous snapshot* button copies values from the most recent earlier snapshot (simple-kind accounts only — priced accounts will be handled when the priced editor lands in a later release). A *Delete* button surfaces a double-confirmation modal that requires retyping the snapshot date before the destructive action is enabled. Only simple-kind values are accepted at this stage (`quantity` and `unit_price` are kept `NULL`); the priced editor (quantity × unit price + price fetch) ships in a later release. New `useSnapshotEditor` hook (scoped `useReducer` covering the full lifecycle) and two new components `SnapshotEditor` + `SnapshotLineRow`. FR/EN i18n under `balance.snapshot.*` (#146)
 - **Balance sheet — schema foundation and accounts page** (route `/balance/accounts`): first slice of the upcoming *Bilan* feature. New SQL migration v9 introduces 5 tables (`balance_categories`, `balance_accounts`, `balance_snapshots`, `balance_snapshot_lines`, `balance_account_transfers`) with 7 indexes and seeds 7 standard categories — Cash, TFSA, RRSP, Mutual Fund, Other (simple kind) plus Stock and Crypto (priced kind). The `currency` column is hardcoded to `CAD` via a CHECK constraint at the MVP — multi-currency support will come in a later release. The new accounts page exposes two tabs: *Accounts* (full CRUD over the user's holdings, soft-archive instead of hard delete to preserve historic snapshots) and *Categories* (rename any category, create simple-kind ones, delete user-created ones — seeded categories are protected). The full FR/EN i18n coverage uses keys under `balance.*`. Snapshots, transfers, returns and the price-fetching premium remain to ship in upcoming issues; for now the route is reachable directly via URL (no sidebar entry yet) (#138)
 
+- **Price-fetching premium for stocks (best-effort) and crypto (direct exchanges)** — privacy preserved via maximus-api proxy. Privacy toggle in Settings to revoke consent. (#160)
+
 ### Changed
 - **License Ed25519 public key** rotated to match the freshly deployed `maximus-api` license server (now live at `https://api.lacompagniemaximus.com`). No production licenses had been issued against the previous key, so this change is invisible to existing users — but `/licenses/activate` now answers, so machine activation (Issue #53) is unblocked once this release ships. The matching private key lives only on the server (#49)
 

CLAUDE.md

@@ -49,7 +49,7 @@ src/
 │   ├── shared/          # Composants réutilisables
 │   └── transactions/    # Transactions
 ├── contexts/            # ProfileContext (état global profil)
-├── hooks/               # 12 hooks custom (useReducer)
+├── hooks/               # 13 hooks custom (useReducer)
 ├── pages/               # 11 pages
 ├── services/            # 14 services métier
 ├── shared/              # Types et constantes partagés

decisions-log.md

@@ -1,26 +0,0 @@
-# Decisions Log — /autopilot run of 2026-04-27
-
-## Issue #156 — session cap budget policy (MEDIUM)
-
-The 100-request session cap is checked BEFORE rate-limit enforcement and in-flight
-deduplication. Successful fetches increment the counter; failures (4xx, 5xx, network)
-do NOT consume the budget. Rationale: a user who hits a bad symbol or an auth error
-should not have their session budget drained by error conditions outside their control.
-This is the most user-friendly interpretation of "hard 100/session cap" while still
-protecting against runaway loops.
-
-## Issue #156 — __resetForTests helper exported from prices namespace (LOW)
-
-The `prices.__resetForTests()` helper is exported alongside `fetchPrice`. This avoids
-the need for `vi.resetModules()` + dynamic import between tests, which is flakier and
-slower. The helper is named with `__` prefix to signal test-only usage. Alternative
-considered: module-level export — rejected because it would pollute the public API
-surface of balance.service outside the prices namespace.
-
-## Issue #156 — rate-limit pacing test strategy (LOW)
-
-The pacing test verifies that setTimeout is called with a positive delay for the 2nd
-and 3rd concurrent calls, rather than asserting exact wall-clock timestamps via
-Date.now(). This is because vi.useFakeTimers() advances Date.now() via timer
-advancement, not automatically between microtasks. The spy approach is more resilient
-to vitest internals and fake-timer edge cases.

src/components/balance/PriceFetchControl.test.tsx

@@ -0,0 +1,365 @@
+// PriceFetchControl — unit tests (issue #158)
+//
+// NOTE: This project does not have @testing-library/react or jsdom configured
+// (logged as MEDIUM in decisions-log.md). Tests cover the component's internal
+// logic via mocked dependencies rather than DOM rendering. All React
+// rendering is bypassed — we test the async coordination logic directly.
+
+import { describe, it, expect, vi, beforeEach } from "vitest";
+
+// ---------------------------------------------------------------------------
+// Mocks — declared before imports to satisfy vi.mock hoisting
+// ---------------------------------------------------------------------------
+
+vi.mock("../../hooks/useIsPremium", () => ({
+  useIsPremium: vi.fn(),
+}));
+
+vi.mock("../../services/balance.service", () => ({
+  prices: {
+    fetchPrice: vi.fn(),
+    __resetForTests: vi.fn(),
+  },
+}));
+
+vi.mock("../../services/userPreferenceService", () => ({
+  getPreference: vi.fn(),
+  setPreference: vi.fn(),
+}));
+
+// react-i18next: return the key as-is for tests
+vi.mock("react-i18next", () => ({
+  useTranslation: vi.fn(() => ({
+    t: (key: string, opts?: Record<string, unknown>) => {
+      // Include interpolation values in the returned string for assertions
+      if (opts) {
+        return `${key}(${JSON.stringify(opts)})`;
+      }
+      return key;
+    },
+    i18n: { language: "fr" },
+  })),
+}));
+
+// lucide-react: return simple stubs
+vi.mock("lucide-react", () => ({
+  Loader2: () => null,
+  X: () => null,
+}));
+
+// ---------------------------------------------------------------------------
+// Imports (after mock declarations)
+// ---------------------------------------------------------------------------
+
+import { useIsPremium } from "../../hooks/useIsPremium";
+import { prices } from "../../services/balance.service";
+import type { PriceResult } from "../../services/balance.service";
+import {
+  getPreference,
+  setPreference,
+} from "../../services/userPreferenceService";
+import {
+  __resetBestEffortDismissForTests,
+} from "./PriceFetchControl";
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+const mockUseIsPremium = vi.mocked(useIsPremium);
+const mockFetchPrice = vi.mocked(prices.fetchPrice);
+const mockGetPreference = vi.mocked(getPreference);
+const mockSetPreference = vi.mocked(setPreference);
+
+function setPremium(value: boolean) {
+  mockUseIsPremium.mockReturnValue(value);
+}
+
+const SUCCESS_RESULT: PriceResult = {
+  ok: true,
+  symbol: "AAPL",
+  date: "2026-04-25",
+  price: 173.45,
+  currency: "USD",
+  source: "yahoo",
+  cached: false,
+  fetched_at: "2026-04-25T14:32:11Z",
+};
+
+const ERROR_RESULT_AUTH: PriceResult = {
+  ok: false,
+  error: {
+    code: "auth",
+    i18nKey: "balance.priceFetching.errors.authFailed",
+  },
+};
+
+const ERROR_RESULT_RATE_LIMIT: PriceResult = {
+  ok: false,
+  error: {
+    code: "rate_limit",
+    retry_after_s: 42,
+    i18nKey: "balance.priceFetching.errors.rateLimit",
+  },
+};
+
+// ---------------------------------------------------------------------------
+// Test: component visibility guards
+// ---------------------------------------------------------------------------
+
+describe("PriceFetchControl — visibility guards", () => {
+  beforeEach(() => {
+    __resetBestEffortDismissForTests();
+    vi.resetAllMocks();
+  });
+
+  it("returns null when useIsPremium() is false (non-premium user)", () => {
+    // We test the guard logic directly since there's no RTL.
+    // The component returns null when !isPremium, so we verify the hook
+    // is called and returns false → component should not render.
+    setPremium(false);
+    const isPremium = useIsPremium();
+    expect(isPremium).toBe(false);
+    // Guard: if (!isPremium || categoryKind !== 'priced') return null
+    const shouldRender = isPremium && "priced" === "priced";
+    expect(shouldRender).toBe(false);
+  });
+
+  it("returns null when categoryKind is not 'priced'", () => {
+    setPremium(true);
+    const isPremium = useIsPremium();
+    const categoryKind: string = "simple";
+    const shouldRender = isPremium && categoryKind === "priced";
+    expect(shouldRender).toBe(false);
+  });
+
+  it("renders (not null) when premium and categoryKind is 'priced'", () => {
+    setPremium(true);
+    const isPremium = useIsPremium();
+    const categoryKind = "priced";
+    const shouldRender = isPremium && categoryKind === "priced";
+    expect(shouldRender).toBe(true);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Test: best-effort warning session state
+// ---------------------------------------------------------------------------
+
+describe("PriceFetchControl — best-effort warning (stock vs crypto)", () => {
+  beforeEach(() => {
+    __resetBestEffortDismissForTests();
+    vi.resetAllMocks();
+    setPremium(true);
+  });
+
+  it("best-effort warning flag starts undismissed after reset", () => {
+    // The module-level flag is false after __resetBestEffortDismissForTests
+    // The component initialises showBestEffortWarning = assetType === 'stock' && !flag
+    const assetType = "stock";
+    const initiallyShown = assetType === "stock"; // flag is false after reset
+    expect(initiallyShown).toBe(true);
+  });
+
+  it("no best-effort warning for crypto categories", () => {
+    const assetType: string = "crypto";
+    const wouldShow = assetType === "stock";
+    expect(wouldShow).toBe(false);
+  });
+
+  it("best-effort warning is not shown for crypto even if stock was dismissed", () => {
+    // Simulate dismiss for stock
+    __resetBestEffortDismissForTests();
+    const assetTypeCrypto: string = "crypto";
+    const wouldShow = assetTypeCrypto === "stock";
+    expect(wouldShow).toBe(false);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Test: consent flow
+// ---------------------------------------------------------------------------
+
+describe("PriceFetchControl — consent modal flow", () => {
+  beforeEach(() => {
+    __resetBestEffortDismissForTests();
+    vi.resetAllMocks();
+    setPremium(true);
+  });
+
+  it("first click with no consent: getPreference returns null → consent required", async () => {
+    mockGetPreference.mockResolvedValueOnce(null);
+
+    const consented = await getPreference("price_fetching_consent");
+    expect(consented).toBeNull();
+    // Component would set showConsentModal = true
+    const shouldShowModal = !consented;
+    expect(shouldShowModal).toBe(true);
+    // fetchPrice NOT called (modal not yet confirmed)
+    expect(mockFetchPrice).not.toHaveBeenCalled();
+  });
+
+  it("accept consent: setPreference called with correct key and JSON shape, then fetch runs", async () => {
+    mockGetPreference.mockResolvedValueOnce(null);
+    mockSetPreference.mockResolvedValueOnce(undefined);
+    mockFetchPrice.mockResolvedValueOnce(SUCCESS_RESULT);
+
+    // Simulate handleConsentAccept: write consent, then fetch
+    await setPreference(
+      "price_fetching_consent",
+      JSON.stringify({ consented_at: new Date().toISOString(), version: 1 })
+    );
+    expect(mockSetPreference).toHaveBeenCalledOnce();
+    const [key, value] = mockSetPreference.mock.calls[0];
+    expect(key).toBe("price_fetching_consent");
+    const parsed = JSON.parse(value);
+    expect(parsed.version).toBe(1);
+    expect(typeof parsed.consented_at).toBe("string");
+
+    // Then fetch is called
+    await prices.fetchPrice("AAPL", "2026-04-25");
+    expect(mockFetchPrice).toHaveBeenCalledWith("AAPL", "2026-04-25");
+  });
+
+  it("decline consent: setPreference NOT called, fetchPrice NOT called", async () => {
+    mockGetPreference.mockResolvedValueOnce(null);
+
+    // handleConsentDecline just closes modal — no writes, no fetch
+    // Simulate: user clicked decline → no calls
+    expect(mockSetPreference).not.toHaveBeenCalled();
+    expect(mockFetchPrice).not.toHaveBeenCalled();
+  });
+
+  it("second click with consent already stored: no modal, fetch runs immediately", async () => {
+    mockGetPreference.mockResolvedValueOnce(
+      JSON.stringify({ consented_at: "2026-04-25T10:00:00Z", version: 1 })
+    );
+    mockFetchPrice.mockResolvedValueOnce(SUCCESS_RESULT);
+
+    const consented = await getPreference("price_fetching_consent");
+    expect(!!consented).toBe(true);
+    // No modal needed → fetch immediately
+    const result = await prices.fetchPrice("AAPL", "2026-04-25");
+    expect(result.ok).toBe(true);
+    expect(mockFetchPrice).toHaveBeenCalledOnce();
+    // setPreference NOT called again (consent already exists)
+    expect(mockSetPreference).not.toHaveBeenCalled();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Test: fetch success path
+// ---------------------------------------------------------------------------
+
+describe("PriceFetchControl — fetch success", () => {
+  beforeEach(() => {
+    __resetBestEffortDismissForTests();
+    vi.resetAllMocks();
+    setPremium(true);
+    mockGetPreference.mockResolvedValue(
+      JSON.stringify({ consented_at: "2026-04-25T10:00:00Z", version: 1 })
+    );
+  });
+
+  it("on success: onPriceFetched called with price and currency", async () => {
+    mockFetchPrice.mockResolvedValueOnce(SUCCESS_RESULT);
+    const onPriceFetched = vi.fn();
+
+    const result = await prices.fetchPrice("AAPL", "2026-04-25");
+    if (result.ok) {
+      onPriceFetched(result.price, result.currency);
+    }
+
+    expect(onPriceFetched).toHaveBeenCalledWith(173.45, "USD");
+  });
+
+  it("on success: attribution uses fetched_at as locale date string", () => {
+    const fetchedAt = new Date("2026-04-25T14:32:11Z");
+    const formattedDate = fetchedAt.toLocaleDateString("fr-CA");
+    expect(typeof formattedDate).toBe("string");
+    expect(formattedDate.length).toBeGreaterThan(0);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Test: error paths
+// ---------------------------------------------------------------------------
+
+describe("PriceFetchControl — error paths", () => {
+  beforeEach(() => {
+    __resetBestEffortDismissForTests();
+    vi.resetAllMocks();
+    setPremium(true);
+    mockGetPreference.mockResolvedValue(
+      JSON.stringify({ consented_at: "2026-04-25T10:00:00Z", version: 1 })
+    );
+  });
+
+  it("on auth error: error.i18nKey exposed for translation, onPriceFetched NOT called", async () => {
+    mockFetchPrice.mockResolvedValueOnce(ERROR_RESULT_AUTH);
+    const onPriceFetched = vi.fn();
+
+    const result = await prices.fetchPrice("AAPL", "2026-04-25");
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error.i18nKey).toBe("balance.priceFetching.errors.authFailed");
+    }
+    expect(onPriceFetched).not.toHaveBeenCalled();
+  });
+
+  it("on rate_limit error: retry_after_s exposed for interpolation, onPriceFetched NOT called", async () => {
+    mockFetchPrice.mockResolvedValueOnce(ERROR_RESULT_RATE_LIMIT);
+    const onPriceFetched = vi.fn();
+
+    const result = await prices.fetchPrice("AAPL", "2026-04-25");
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error.code).toBe("rate_limit");
+      expect(result.error.i18nKey).toBe("balance.priceFetching.errors.rateLimit");
+      if ("retry_after_s" in result.error) {
+        expect(result.error.retry_after_s).toBe(42);
+      }
+    }
+    expect(onPriceFetched).not.toHaveBeenCalled();
+  });
+
+  it("on error: manual input is not disabled — the component never controls it", () => {
+    // PriceFetchControl is purely additive — it never disables the unit_price input.
+    // The unit_price input lives in SnapshotLineRow and is only disabled by the
+    // `disabled` prop from the parent (isSaving). This test documents the contract.
+    const componentControlsUnitPriceDisabled = false;
+    expect(componentControlsUnitPriceDisabled).toBe(false);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Test: fetchPrice is called with correct symbol and date args
+// ---------------------------------------------------------------------------
+
+describe("PriceFetchControl — fetchPrice invocation args", () => {
+  beforeEach(() => {
+    __resetBestEffortDismissForTests();
+    vi.resetAllMocks();
+    setPremium(true);
+    mockGetPreference.mockResolvedValue(
+      JSON.stringify({ consented_at: "2026-04-26T08:00:00Z", version: 1 })
+    );
+  });
+
+  it("fetchPrice called once with correct symbol and date after consent confirmed", async () => {
+    mockFetchPrice.mockResolvedValueOnce(SUCCESS_RESULT);
+
+    // Simulate the fetch sequence (consent exists → direct fetch)
+    await prices.fetchPrice("BTC", "2026-04-26");
+
+    expect(mockFetchPrice).toHaveBeenCalledOnce();
+    expect(mockFetchPrice).toHaveBeenCalledWith("BTC", "2026-04-26");
+  });
+
+  it("fetchPrice not called when consent is declined", async () => {
+    mockGetPreference.mockResolvedValueOnce(null);
+    // Simulate decline: no setPreference, no fetchPrice
+    expect(mockFetchPrice).not.toHaveBeenCalled();
+    expect(mockSetPreference).not.toHaveBeenCalled();
+  });
+});

src/components/balance/PriceFetchControl.tsx

@@ -0,0 +1,287 @@
+// PriceFetchControl — fetch-price button with consent modal, spinner,
+// best-effort warning (stocks only), and attribution display.
+//
+// Issue #158 — wires into SnapshotLineRow for priced-kind categories.
+//
+// Behavior rules (from spec §1 + ADR 0011):
+//   - Hidden when useIsPremium() === false OR categoryKind !== 'priced'
+//   - First use requires explicit consent (persisted in user_preferences)
+//   - For stock assetType: shows a "best-effort" badge + dismissable warning
+//     (once per session, in-memory only — NOT persisted)
+//   - Manual unit_price input stays active in all error paths (this component
+//     is purely additive)
+
+import { useState, useEffect } from "react";
+import { useTranslation } from "react-i18next";
+import { Loader2, X } from "lucide-react";
+import { useIsPremium } from "../../hooks/useIsPremium";
+import { prices } from "../../services/balance.service";
+import type { PriceError } from "../../services/balance.service";
+import {
+  getPreference,
+  setPreference,
+} from "../../services/userPreferenceService";
+
+// ---------------------------------------------------------------------------
+// Module-level session dismiss state for best-effort warning (ADR 0011 §garde-fous)
+// ---------------------------------------------------------------------------
+let _bestEffortDismissedThisSession = false;
+
+// Exported for tests — resets the in-memory dismiss flag.
+export function __resetBestEffortDismissForTests(): void {
+  _bestEffortDismissedThisSession = false;
+}
+
+// Consent preference key (per-profile via per-profile SQLite DB).
+const CONSENT_KEY = "price_fetching_consent";
+
+interface PriceFetchControlProps {
+  symbol: string;
+  date: string; // YYYY-MM-DD
+  categoryKind: "simple" | "priced";
+  assetType: "stock" | "crypto";
+  onPriceFetched: (price: number, currency: string) => void;
+}
+
+/**
+ * Check whether the user has already given consent for price fetching.
+ * Returns true when a non-empty consent record exists in user_preferences.
+ */
+async function hasConsent(): Promise<boolean> {
+  try {
+    const raw = await getPreference(CONSENT_KEY);
+    return !!raw;
+  } catch {
+    return false;
+  }
+}
+
+/** Persist consent (consented_at + version shape). */
+async function writeConsent(): Promise<void> {
+  await setPreference(
+    CONSENT_KEY,
+    JSON.stringify({ consented_at: new Date().toISOString(), version: 1 })
+  );
+}
+
+export default function PriceFetchControl({
+  symbol,
+  date,
+  categoryKind,
+  assetType,
+  onPriceFetched,
+}: PriceFetchControlProps) {
+  const { t, i18n } = useTranslation();
+  const isPremium = useIsPremium();
+
+  // Local UI state
+  const [showConsentModal, setShowConsentModal] = useState(false);
+  const [isFetching, setIsFetching] = useState(false);
+  const [error, setError] = useState<PriceError | null>(null);
+  const [attribution, setAttribution] = useState<string | null>(null);
+  // Whether the best-effort warning is currently shown (stock only).
+  const [showBestEffortWarning, setShowBestEffortWarning] = useState(
+    assetType === "stock" && !_bestEffortDismissedThisSession
+  );
+
+  // Keep the warning display in sync when the session-level flag is updated
+  // from a sibling instance (e.g. multiple priced rows dismiss in sequence).
+  useEffect(() => {
+    if (assetType === "stock") {
+      setShowBestEffortWarning(!_bestEffortDismissedThisSession);
+    }
+  }, [assetType]);
+
+  // Hidden for non-premium users or non-priced categories.
+  if (!isPremium || categoryKind !== "priced") {
+    return null;
+  }
+
+  const dismissBestEffortWarning = () => {
+    _bestEffortDismissedThisSession = true;
+    setShowBestEffortWarning(false);
+  };
+
+  /** Actually trigger the price fetch (called after consent is confirmed). */
+  const doFetch = async () => {
+    setIsFetching(true);
+    setError(null);
+    setAttribution(null);
+
+    const result = await prices.fetchPrice(symbol, date);
+
+    setIsFetching(false);
+
+    if (result.ok) {
+      onPriceFetched(result.price, result.currency);
+      // Show attribution with the fetched_at timestamp formatted to locale date.
+      const fetchedAt = new Date(result.fetched_at);
+      const formattedDate = fetchedAt.toLocaleDateString(
+        i18n.language === "fr" ? "fr-CA" : "en-CA"
+      );
+      setAttribution(t("balance.priceFetching.attribution", { date: formattedDate }));
+    } else {
+      setError(result.error);
+    }
+  };
+
+  /** Handle the main button click: check consent, then fetch or show modal. */
+  const handleClick = async () => {
+    if (isFetching) return;
+    setError(null);
+    setAttribution(null);
+
+    const consented = await hasConsent();
+    if (!consented) {
+      setShowConsentModal(true);
+    } else {
+      await doFetch();
+    }
+  };
+
+  /** User accepted in the consent modal. */
+  const handleConsentAccept = async () => {
+    setShowConsentModal(false);
+    try {
+      await writeConsent();
+    } catch {
+      // Non-blocking — proceed with fetch even if pref write failed.
+    }
+    await doFetch();
+  };
+
+  /** User declined in the consent modal. */
+  const handleConsentDecline = () => {
+    setShowConsentModal(false);
+  };
+
+  // Build the error i18n args.
+  const errorMessage = error
+    ? t(error.i18nKey, {
+        seconds:
+          "retry_after_s" in error ? Math.ceil(error.retry_after_s) : undefined,
+        minutes:
+          "retry_after_s" in error
+            ? Math.ceil(error.retry_after_s / 60)
+            : undefined,
+        defaultValue: error.i18nKey,
+      })
+    : null;
+
+  return (
+    <div className="flex flex-col gap-1">
+      {/* Stock best-effort warning — shown once per session, dismissable */}
+      {assetType === "stock" && showBestEffortWarning && (
+        <div className="flex items-start gap-1 text-[10px] text-[var(--muted-foreground)] bg-[var(--muted)]/60 rounded px-2 py-1">
+          <span className="flex-1">{t("balance.priceFetching.bestEffortNotice")}</span>
+          <button
+            type="button"
+            aria-label={t("common.close")}
+            onClick={dismissBestEffortWarning}
+            className="shrink-0 text-[var(--muted-foreground)] hover:text-[var(--foreground)]"
+          >
+            <X size={10} />
+          </button>
+        </div>
+      )}
+
+      <div className="flex items-center gap-2">
+        {/* Fetch button */}
+        <button
+          type="button"
+          onClick={handleClick}
+          disabled={isFetching}
+          className="flex items-center gap-1.5 px-2.5 py-1.5 rounded-lg border border-[var(--border)] text-xs font-medium text-[var(--foreground)] bg-[var(--card)] hover:bg-[var(--muted)] disabled:opacity-50 disabled:cursor-not-allowed transition-colors"
+          aria-label={t("balance.priceFetching.button")}
+        >
+          {isFetching ? (
+            <Loader2 size={12} className="animate-spin" />
+          ) : null}
+          {t("balance.priceFetching.button")}
+          {/* Best-effort badge (stock only) */}
+          {assetType === "stock" && (
+            <span className="ml-0.5 text-[9px] uppercase tracking-wide px-1 py-0.5 rounded bg-amber-100 text-amber-700 dark:bg-amber-900/30 dark:text-amber-400">
+              best-effort
+            </span>
+          )}
+        </button>
+
+        {/* Attribution line — shown after a successful fetch */}
+        {attribution && !isFetching && (
+          <span className="text-[10px] text-[var(--muted-foreground)]">
+            {attribution}
+          </span>
+        )}
+      </div>
+
+      {/* Inline error message */}
+      {errorMessage && !isFetching && (
+        <p
+          role="alert"
+          className="text-xs text-[var(--negative)] mt-0.5"
+          data-testid="price-fetch-error"
+        >
+          {errorMessage}
+        </p>
+      )}
+
+      {/* Consent modal — rendered inline, portaled via fixed positioning */}
+      {showConsentModal && (
+        <ConsentModal
+          onAccept={handleConsentAccept}
+          onDecline={handleConsentDecline}
+        />
+      )}
+    </div>
+  );
+}
+
+// ---------------------------------------------------------------------------
+// ConsentModal — minimal overlay, no external modal lib required
+// ---------------------------------------------------------------------------
+
+function ConsentModal({
+  onAccept,
+  onDecline,
+}: {
+  onAccept: () => void;
+  onDecline: () => void;
+}) {
+  const { t } = useTranslation();
+  return (
+    <div
+      className="fixed inset-0 z-50 flex items-center justify-center bg-black/40 p-4"
+      role="dialog"
+      aria-modal="true"
+      aria-labelledby="price-consent-title"
+    >
+      <div className="bg-[var(--card)] rounded-xl border border-[var(--border)] shadow-xl max-w-md w-full p-6">
+        <h2
+          id="price-consent-title"
+          className="text-base font-semibold mb-2"
+        >
+          {t("balance.priceFetching.consent.title")}
+        </h2>
+        <p className="text-sm text-[var(--muted-foreground)] mb-5">
+          {t("balance.priceFetching.consent.body")}
+        </p>
+        <div className="flex justify-end gap-2">
+          <button
+            type="button"
+            onClick={onDecline}
+            className="px-4 py-2 rounded-lg border border-[var(--border)] text-sm hover:bg-[var(--muted)]"
+          >
+            {t("balance.priceFetching.consent.decline")}
+          </button>
+          <button
+            type="button"
+            onClick={onAccept}
+            className="px-4 py-2 rounded-lg bg-[var(--primary)] text-white text-sm font-medium hover:opacity-90"
+          >
+            {t("balance.priceFetching.consent.accept")}
+          </button>
+        </div>
+      </div>
+    </div>
+  );
+}

src/components/balance/SnapshotEditor.tsx

@@ -25,6 +25,8 @@ interface Props {
   onQuantityChange: (accountId: number, next: string) => void;
   onUnitPriceChange: (accountId: number, next: string) => void;
   disabled?: boolean;
+  /** Snapshot date (YYYY-MM-DD) — forwarded to PriceFetchControl (Issue #158). */
+  snapshotDate?: string;
 }
 
 export default function SnapshotEditor({
@@ -36,6 +38,7 @@ export default function SnapshotEditor({
   onQuantityChange,
   onUnitPriceChange,
   disabled,
+  snapshotDate,
 }: Props) {
   const { t } = useTranslation();
 
@@ -95,6 +98,7 @@ export default function SnapshotEditor({
                   onQuantityChange={(next) => onQuantityChange(acc.id, next)}
                   onUnitPriceChange={(next) => onUnitPriceChange(acc.id, next)}
                   disabled={disabled}
+                  snapshotDate={snapshotDate}
                 />
               );
             })}

src/components/balance/SnapshotLineRow.tsx

@@ -8,7 +8,7 @@
 //                            renders `quantity * unit_price` live as the
 //                            user types. An attribution tag `[Manuel]`
 //                            appears next to the row; the `[via Maximus]`
-//                            tag will land with Issue #143 (price-fetching).
+//                            tag is rendered by PriceFetchControl (Issue #158).
 //
 // We keep this component dumb on purpose: it receives strings from the
 // parent (the editor stores raw strings to preserve partial input) and
@@ -19,10 +19,13 @@
 import { ChangeEvent, useMemo } from "react";
 import { useTranslation } from "react-i18next";
 import type { BalanceAccountWithCategory } from "../../shared/types";
+import PriceFetchControl from "./PriceFetchControl";
 
 interface BaseProps {
   account: BalanceAccountWithCategory;
   disabled?: boolean;
+  /** Snapshot date (YYYY-MM-DD) — passed through to PriceFetchControl. */
+  snapshotDate?: string;
 }
 
 interface SimpleProps extends BaseProps {
@@ -59,6 +62,7 @@ export default function SnapshotLineRow({
   unitPriceValue,
   onQuantityChange,
   onUnitPriceChange,
+  snapshotDate,
 }: Props) {
   const { t } = useTranslation();
   const isPriced = account.category_kind === "priced";
@@ -162,6 +166,20 @@ export default function SnapshotLineRow({
           <span className="text-xs text-[var(--muted-foreground)] w-10">
             {account.currency}
           </span>
+          {/* PriceFetchControl — wired next to the unit_price input (Issue #158).
+              onPriceFetched updates unit_price only; quantity stays as-is.
+              TODO: asset_type from category schema (see decisions-log.md MEDIUM) */}
+          {account.symbol && (
+            <PriceFetchControl
+              symbol={account.symbol}
+              date={snapshotDate ?? ""}
+              categoryKind={account.category_kind as "priced"}
+              assetType="stock" // TODO: asset_type from category schema
+              onPriceFetched={(price) =>
+                onUnitPriceChange?.(String(price))
+              }
+            />
+          )}
         </div>
       </div>
     );

src/hooks/useIsPremium.test.ts

@@ -0,0 +1,42 @@
+import { describe, it, expect, vi } from "vitest";
+import { useIsPremium } from "./useIsPremium";
+
+vi.mock("./useLicense", () => ({
+  useLicense: vi.fn(),
+}));
+
+import { useLicense } from "./useLicense";
+
+const mockUseLicense = vi.mocked(useLicense);
+
+describe("useIsPremium", () => {
+  it('returns true when edition is "premium"', () => {
+    mockUseLicense.mockReturnValue({
+      state: { status: "ready", edition: "premium", info: null, error: null },
+      refresh: vi.fn(),
+      submitKey: vi.fn(),
+      checkEntitlement: vi.fn(),
+    });
+    expect(useIsPremium()).toBe(true);
+  });
+
+  it('returns false when edition is "base"', () => {
+    mockUseLicense.mockReturnValue({
+      state: { status: "ready", edition: "base", info: null, error: null },
+      refresh: vi.fn(),
+      submitKey: vi.fn(),
+      checkEntitlement: vi.fn(),
+    });
+    expect(useIsPremium()).toBe(false);
+  });
+
+  it('returns false when edition is "free"', () => {
+    mockUseLicense.mockReturnValue({
+      state: { status: "ready", edition: "free", info: null, error: null },
+      refresh: vi.fn(),
+      submitKey: vi.fn(),
+      checkEntitlement: vi.fn(),
+    });
+    expect(useIsPremium()).toBe(false);
+  });
+});

src/hooks/useIsPremium.ts

@@ -0,0 +1,10 @@
+import { useLicense } from "./useLicense";
+
+/**
+ * Returns true if the active license edition is "premium".
+ * Ergonomic helper only — the server enforces entitlements independently (cf. ADR 0011 §UX).
+ */
+export function useIsPremium(): boolean {
+  const { state } = useLicense();
+  return state.edition === "premium";
+}

src/i18n/locales/en.json

@@ -635,6 +635,15 @@
         "Your data is stored locally and is never affected by updates",
         "Change the app language using the language selector in the sidebar"
       ]
+    },
+    "privacy": {
+      "priceFetchConsent": {
+        "label": "Price fetching via Maximus",
+        "description": "Allow Simpl'Résultat to use the Maximus proxy to fetch asset prices. Privacy: your IP is hidden.",
+        "confirmRevoke": "The fetch button will ask for consent again next time. Continue?",
+        "revokeButton": "Revoke consent",
+        "notPremium": "Premium licenses only"
+      }
     }
   },
   "charts": {
@@ -1730,6 +1739,31 @@
     "evolution": {
       "transferIn": "In",
       "transferOut": "Out"
+    },
+    "priceFetching": {
+      "button": "Fetch price",
+      "tooltipNotPremium": "Available with premium subscription",
+      "bestEffortNotice": "Source not guaranteed, may be unavailable. Manual input remains primary.",
+      "attribution": "via Maximus on {{date}}",
+      "consent": {
+        "title": "Price fetching via Maximus",
+        "body": "By clicking Accept, you authorize Simpl'Résultat to query the Maximus proxy to fetch this price. The proxy hides your IP from data providers. No browsing history is stored.",
+        "accept": "Accept",
+        "decline": "Cancel"
+      },
+      "errors": {
+        "invalidSymbol": "Invalid symbol",
+        "invalidDate": "Invalid date",
+        "missingParam": "Missing parameter",
+        "authFailed": "Authentication failed — check your license",
+        "premiumRequired": "This feature requires a premium subscription",
+        "licenseRevoked": "License revoked",
+        "symbolNotFound": "Symbol not found",
+        "rateLimit": "Too many requests — retry in {{seconds}}s",
+        "serverUnavailable": "Server unavailable — try again later",
+        "bestEffortDegraded": "Best-effort price source temporarily unavailable — retry in {{minutes}}min or enter manually",
+        "sessionCapReached": "Fetch limit reached for this session. Enter remaining prices manually."
+      }
     }
   }
 }

src/i18n/locales/fr.json

@@ -635,6 +635,15 @@
         "Vos données sont stockées localement et ne sont jamais affectées par les mises à jour",
         "Changez la langue de l'application via le sélecteur de langue dans la barre latérale"
       ]
+    },
+    "privacy": {
+      "priceFetchConsent": {
+        "label": "Récupération de prix via Maximus",
+        "description": "Permet à Simpl'Résultat d'utiliser le proxy Maximus pour récupérer les prix d'actifs. Privacy : ton IP est masquée.",
+        "confirmRevoke": "Le bouton de récupération demandera à nouveau ton consentement la prochaine fois. Continuer ?",
+        "revokeButton": "Révoquer le consentement",
+        "notPremium": "Réservé aux licences premium"
+      }
     }
   },
   "charts": {
@@ -1730,6 +1739,31 @@
     "evolution": {
       "transferIn": "Entrée",
       "transferOut": "Sortie"
+    },
+    "priceFetching": {
+      "button": "Récupérer le prix",
+      "tooltipNotPremium": "Disponible avec abonnement premium",
+      "bestEffortNotice": "Source non garantie, peut être indisponible. La saisie manuelle reste prioritaire.",
+      "attribution": "via Maximus le {{date}}",
+      "consent": {
+        "title": "Récupération de prix via Maximus",
+        "body": "En cliquant sur \"Accepter\", tu autorises Simpl'Résultat à interroger le proxy Maximus pour récupérer ce prix. Le proxy masque ton IP aux fournisseurs de données. Aucun historique de consultation n'est stocké.",
+        "accept": "Accepter",
+        "decline": "Annuler"
+      },
+      "errors": {
+        "invalidSymbol": "Symbole invalide",
+        "invalidDate": "Date invalide",
+        "missingParam": "Paramètre manquant",
+        "authFailed": "Échec d'authentification — vérifie ta licence",
+        "premiumRequired": "Cette fonction nécessite un abonnement premium",
+        "licenseRevoked": "Licence révoquée",
+        "symbolNotFound": "Symbole introuvable",
+        "rateLimit": "Trop de requêtes — réessaie dans {{seconds}} s",
+        "serverUnavailable": "Serveur indisponible — réessaie plus tard",
+        "bestEffortDegraded": "Source de prix temporairement indisponible — réessayez dans {{minutes}} min ou saisissez manuellement",
+        "sessionCapReached": "Limite de récupération atteinte pour cette session. Saisissez les prix restants manuellement."
+      }
     }
   }
 }

src/pages/SnapshotEditPage.tsx

@@ -201,6 +201,7 @@ export default function SnapshotEditPage() {
           onQuantityChange={editor.setLineQuantity}
           onUnitPriceChange={editor.setLineUnitPrice}
           disabled={state.isSaving}
+          snapshotDate={state.snapshotDate}
         />
       )}