diff --git a/README.md b/README.md index 0156f38..8ebc48f 100644 --- a/README.md +++ b/README.md @@ -48,7 +48,8 @@ The user-facing policy lives at [pmdevsolutions.github.io/Optia/privacy.html](ht - SEO analysis runs **locally**; page content is not transmitted by browsing or analyzing. - AI requests send only the keyword + relevant page snippets — to the Optia backend (Cloudflare Workers → Anthropic) in hosted mode, or **directly to Anthropic** in Pro bring-your-own-key mode (the key never touches the backend; enforced server-side). - The backend stores licenses and coarse usage counters, never page content or profiles. Billing is handled entirely by **Stripe** — no card data ever touches Optia. -- No analytics, no tracking, no ads, no data sales. Data requests: [open an issue](https://github.com/PMDevSolutions/Optia/issues). +- One anonymous usage count, at most once a day: install ID, month and the number of pages analyzed that month, nothing else. On by default; "Share anonymous usage counts" in Options turns it off. +- No analytics services, no tracking, no ads, no data sales. Data requests: [open an issue](https://github.com/PMDevSolutions/Optia/issues). Chrome Web Store data-safety answers are maintained in [`docs/chrome-web-store-data-disclosure.md`](./docs/chrome-web-store-data-disclosure.md); the full listing source is [`docs/chrome-web-store-listing.md`](./docs/chrome-web-store-listing.md). diff --git a/app/src/lib/usage.test.ts b/app/src/lib/usage.test.ts new file mode 100644 index 0000000..23e9660 --- /dev/null +++ b/app/src/lib/usage.test.ts @@ -0,0 +1,282 @@ +import { describe, it, expect, vi, beforeEach, afterEach } from "vitest"; +import { + ANALYSIS_COUNTS_KEY, + SHARE_USAGE_KEY, + USAGE_REPORT_KEY, + getMonthlyAnalysisCount, + isUsageSharingEnabled, + recordAnalysis, + reportUsageIfDue, + setUsageSharingEnabled, +} from "@/lib/usage"; +import { BACKEND_BASE_URL } from "@/lib/entitlement-keys"; +import { getInstallId } from "@/lib/entitlement"; +import { getStorageItem, setStorageItem } from "@/lib/storage"; + +// Keep the real period helper; only the install id is stubbed. +vi.mock("@/lib/entitlement", async (importOriginal) => { + const original = await importOriginal(); + return { ...original, getInstallId: vi.fn() }; +}); + +const getInstallIdMock = vi.mocked(getInstallId); + +const REPORT_URL = `${BACKEND_BASE_URL}/usage/analysis`; +const HOUR = 3_600_000; + +const OCT_15 = new Date("2026-10-15T09:00:00Z"); + +function at(base: Date, hoursLater: number): Date { + return new Date(base.getTime() + hoursLater * HOUR); +} + +async function recordTimes(times: number, now: Date): Promise { + for (let i = 0; i < times; i++) await recordAnalysis(now); +} + +function stubFetch(impl: () => Promise) { + const fetchMock = vi.fn(impl); + vi.stubGlobal("fetch", fetchMock); + return fetchMock; +} + +const accepted = () => Promise.resolve(new Response(null, { status: 204 })); +const offline = () => Promise.reject(new TypeError("Failed to fetch")); + +function sentBody(fetchMock: ReturnType, call = 0): unknown { + return JSON.parse(fetchMock.mock.calls[call][1]?.body as string); +} + +beforeEach(() => { + getInstallIdMock.mockResolvedValue("install-123"); +}); + +afterEach(() => { + vi.unstubAllGlobals(); +}); + +describe("recordAnalysis", () => { + it("adds exactly one to this month's count per completed analysis", async () => { + await recordAnalysis(OCT_15); + expect(await getMonthlyAnalysisCount(OCT_15)).toBe(1); + + await recordTimes(2, OCT_15); + expect(await getMonthlyAnalysisCount(OCT_15)).toBe(3); + }); + + it("does not lose an increment when analyses finish together", async () => { + await Promise.all([1, 2, 3, 4, 5].map(() => recordAnalysis(OCT_15))); + + expect(await getMonthlyAnalysisCount(OCT_15)).toBe(5); + }); + + it("rolls over at the month boundary and keeps only the previous month", async () => { + await recordTimes(2, new Date("2026-10-31T23:59:59Z")); + await recordAnalysis(new Date("2026-11-01T00:00:01Z")); + + expect(await getMonthlyAnalysisCount(new Date("2026-11-01T00:00:01Z"))).toBe(1); + expect(await getStorageItem(ANALYSIS_COUNTS_KEY)).toEqual({ "2026-10": 2, "2026-11": 1 }); + + await recordAnalysis(new Date("2026-12-02T10:00:00Z")); + expect(await getStorageItem(ANALYSIS_COUNTS_KEY)).toEqual({ "2026-11": 1, "2026-12": 1 }); + }); + + it("counts by UTC month, the backend's accounting period", async () => { + // 2026-12-01T03:00Z is still November 30 in the Americas. + await recordAnalysis(new Date("2026-12-01T03:00:00Z")); + + expect(await getStorageItem(ANALYSIS_COUNTS_KEY)).toEqual({ "2026-12": 1 }); + }); + + it("starts each month at zero", async () => { + await recordTimes(4, OCT_15); + + expect(await getMonthlyAnalysisCount(new Date("2026-11-03T12:00:00Z"))).toBe(0); + }); +}); + +describe("usage sharing setting", () => { + it("is on until the user turns it off", async () => { + expect(await isUsageSharingEnabled()).toBe(true); + + await setUsageSharingEnabled(false); + expect(await isUsageSharingEnabled()).toBe(false); + expect(await getStorageItem(SHARE_USAGE_KEY)).toBe(false); + + await setUsageSharingEnabled(true); + expect(await isUsageSharingEnabled()).toBe(true); + }); +}); + +describe("reportUsageIfDue", () => { + it("sends the install id, the month and the running total, and nothing else", async () => { + const fetchMock = stubFetch(accepted); + await recordTimes(3, OCT_15); + + await reportUsageIfDue(OCT_15); + + expect(fetchMock).toHaveBeenCalledTimes(1); + expect(fetchMock).toHaveBeenCalledWith(REPORT_URL, { + method: "POST", + headers: { "Content-Type": "application/json" }, + body: JSON.stringify({ installId: "install-123", period: "2026-10", count: 3 }), + }); + }); + + it("reports at most once a day", async () => { + const fetchMock = stubFetch(accepted); + await recordTimes(2, OCT_15); + await reportUsageIfDue(OCT_15); + + await recordAnalysis(at(OCT_15, 1)); + await reportUsageIfDue(at(OCT_15, 1)); + await reportUsageIfDue(at(OCT_15, 23.9)); + expect(fetchMock).toHaveBeenCalledTimes(1); + + await reportUsageIfDue(at(OCT_15, 24)); + expect(fetchMock).toHaveBeenCalledTimes(2); + expect(sentBody(fetchMock, 1)).toEqual({ installId: "install-123", period: "2026-10", count: 3 }); + }); + + it("survives being offline: the next day's report sends the running total", async () => { + const fetchMock = stubFetch(offline); + await recordTimes(2, OCT_15); + + await reportUsageIfDue(OCT_15); + expect(fetchMock).toHaveBeenCalledTimes(1); + expect(await getStorageItem(USAGE_REPORT_KEY)).toEqual({ + lastAttemptAt: OCT_15.getTime(), + sent: {}, + }); + + // Still the same day: no retry, even after another analysis. + await recordAnalysis(at(OCT_15, 3)); + await reportUsageIfDue(at(OCT_15, 3)); + expect(fetchMock).toHaveBeenCalledTimes(1); + + fetchMock.mockImplementation(accepted); + await reportUsageIfDue(at(OCT_15, 25)); + expect(fetchMock).toHaveBeenCalledTimes(2); + expect(sentBody(fetchMock, 1)).toEqual({ installId: "install-123", period: "2026-10", count: 3 }); + expect(await getStorageItem(USAGE_REPORT_KEY)).toEqual({ + lastAttemptAt: at(OCT_15, 25).getTime(), + sent: { "2026-10": 3 }, + }); + }); + + it("treats an error status like offline and tries again the next day", async () => { + const fetchMock = stubFetch(() => Promise.resolve(new Response("not found", { status: 404 }))); + await recordAnalysis(OCT_15); + + await reportUsageIfDue(OCT_15); + expect(await getStorageItem(USAGE_REPORT_KEY)).toEqual({ + lastAttemptAt: OCT_15.getTime(), + sent: {}, + }); + + fetchMock.mockImplementation(accepted); + await reportUsageIfDue(at(OCT_15, 24)); + expect(fetchMock).toHaveBeenCalledTimes(2); + expect(sentBody(fetchMock, 1)).toMatchObject({ period: "2026-10", count: 1 }); + }); + + it("never sends while sharing is off, but keeps counting", async () => { + const fetchMock = stubFetch(accepted); + await setUsageSharingEnabled(false); + await recordTimes(2, OCT_15); + + await reportUsageIfDue(OCT_15); + await reportUsageIfDue(at(OCT_15, 48)); + + expect(fetchMock).not.toHaveBeenCalled(); + expect(await getStorageItem(USAGE_REPORT_KEY)).toBeNull(); + expect(await getMonthlyAnalysisCount(OCT_15)).toBe(2); + }); + + it("sends the running total once sharing is turned back on", async () => { + const fetchMock = stubFetch(accepted); + await setUsageSharingEnabled(false); + await recordTimes(2, OCT_15); + await reportUsageIfDue(OCT_15); + + await setUsageSharingEnabled(true); + await reportUsageIfDue(at(OCT_15, 1)); + + expect(fetchMock).toHaveBeenCalledTimes(1); + expect(sentBody(fetchMock)).toMatchObject({ count: 2 }); + }); + + it("sends nothing, and keeps the day open, when there is nothing new to report", async () => { + const fetchMock = stubFetch(accepted); + + await reportUsageIfDue(OCT_15); + expect(fetchMock).not.toHaveBeenCalled(); + expect(await getStorageItem(USAGE_REPORT_KEY)).toBeNull(); + + await recordAnalysis(at(OCT_15, 1)); + await reportUsageIfDue(at(OCT_15, 1)); + expect(fetchMock).toHaveBeenCalledTimes(1); + + // A day later with no new analyses: the backend already has this total. + await reportUsageIfDue(at(OCT_15, 30)); + expect(fetchMock).toHaveBeenCalledTimes(1); + }); + + it("sends the previous month's final total alongside the new month's", async () => { + const fetchMock = stubFetch(accepted); + const oct31Morning = new Date("2026-10-31T08:00:00Z"); + await recordAnalysis(oct31Morning); + await reportUsageIfDue(oct31Morning); + + // More analyses after that day's report, then the month turns. + await recordTimes(2, new Date("2026-10-31T20:00:00Z")); + const nov1 = new Date("2026-11-01T09:00:00Z"); + await recordAnalysis(nov1); + await reportUsageIfDue(nov1); + + expect(fetchMock).toHaveBeenCalledTimes(3); + expect(sentBody(fetchMock, 1)).toEqual({ installId: "install-123", period: "2026-10", count: 3 }); + expect(sentBody(fetchMock, 2)).toEqual({ installId: "install-123", period: "2026-11", count: 1 }); + expect(await getStorageItem(USAGE_REPORT_KEY)).toEqual({ + lastAttemptAt: nov1.getTime(), + sent: { "2026-10": 3, "2026-11": 1 }, + }); + }); + + it("caps the count at the backend's 10,000 limit", async () => { + const fetchMock = stubFetch(accepted); + await setStorageItem(ANALYSIS_COUNTS_KEY, { "2026-10": 12_345 }); + + await reportUsageIfDue(OCT_15); + + expect(sentBody(fetchMock)).toMatchObject({ count: 10_000 }); + }); + + it("shares one report between overlapping calls", async () => { + const fetchMock = stubFetch(accepted); + await recordAnalysis(OCT_15); + + await Promise.all([reportUsageIfDue(OCT_15), reportUsageIfDue(OCT_15)]); + + expect(fetchMock).toHaveBeenCalledTimes(1); + }); + + it("treats a clock that moved backwards as due instead of stalling", async () => { + const fetchMock = stubFetch(accepted); + await setStorageItem(USAGE_REPORT_KEY, { lastAttemptAt: at(OCT_15, 72).getTime(), sent: {} }); + await recordAnalysis(OCT_15); + + await reportUsageIfDue(OCT_15); + + expect(fetchMock).toHaveBeenCalledTimes(1); + }); + + it("never throws, even when the install id cannot be read", async () => { + const fetchMock = stubFetch(accepted); + getInstallIdMock.mockRejectedValue(new Error("storage unavailable")); + await recordAnalysis(OCT_15); + + await expect(reportUsageIfDue(OCT_15)).resolves.toBeUndefined(); + expect(fetchMock).not.toHaveBeenCalled(); + }); +}); diff --git a/app/src/lib/usage.ts b/app/src/lib/usage.ts new file mode 100644 index 0000000..e0111c4 --- /dev/null +++ b/app/src/lib/usage.ts @@ -0,0 +1,131 @@ +import { BACKEND_BASE_URL } from "@/lib/entitlement-keys"; +import { currentAiPeriod, getInstallId } from "@/lib/entitlement"; +import { getStorageItem, setStorageItem } from "@/lib/storage"; + +// Anonymous usage counts (#80; backend half optia-backend#30). Each completed +// page analysis adds one to this install's count for the calendar month, kept +// in local storage. At most once a day, right after an analysis, the running +// totals go to POST /usage/analysis as { installId, period, count } and nothing +// else: no URLs, no page content, no scores. The backend keeps the highest +// count it has seen for a month, so re-sending a total is harmless. Turning +// off "Share anonymous usage counts" in Options keeps the local count (Options +// still shows it) and stops every report. + +export const ANALYSIS_COUNTS_KEY = "usage_analyses"; +export const USAGE_REPORT_KEY = "usage_report"; +export const SHARE_USAGE_KEY = "share_usage_counts"; + +const DAY_MS = 24 * 60 * 60 * 1000; +// The backend rejects counts above this; a real install never gets near it. +const MAX_REPORTED_COUNT = 10_000; + +/** Pages analyzed per month ("YYYY-MM"), for the current and previous month only. */ +type AnalysisCounts = Record; + +interface UsageReportState { + /** When a report was last attempted (ms epoch). A failed attempt counts too. */ + lastAttemptAt: number; + /** The count the backend last accepted, per month. */ + sent: Record; +} + +/** The months a report can cover: the backend accepts the current one and the one before. */ +function reportablePeriods(now: Date): [previous: string, current: string] { + const previousMonth = new Date(Date.UTC(now.getUTCFullYear(), now.getUTCMonth() - 1, 1)); + return [currentAiPeriod(previousMonth), currentAiPeriod(now)]; +} + +/** Drops months older than the previous one; that is the whole month rollover. */ +function keepReportable(byPeriod: Record, now: Date): Record { + const kept: Record = {}; + for (const period of reportablePeriods(now)) { + if (typeof byPeriod[period] === "number") kept[period] = byPeriod[period]; + } + return kept; +} + +// Increments run one at a time, so two analyses finishing together never read +// the same total and lose one. +let recordQueue: Promise = Promise.resolve(); + +/** Adds one completed page analysis to this month's count. */ +export function recordAnalysis(now: Date = new Date()): Promise { + const next = recordQueue.then(async () => { + const stored = (await getStorageItem(ANALYSIS_COUNTS_KEY)) ?? {}; + const counts = keepReportable(stored, now); + const period = currentAiPeriod(now); + counts[period] = (counts[period] ?? 0) + 1; + await setStorageItem(ANALYSIS_COUNTS_KEY, counts); + }); + recordQueue = next.catch(() => undefined); + return next; +} + +/** Pages analyzed on this install in the current calendar month. */ +export async function getMonthlyAnalysisCount(now: Date = new Date()): Promise { + const counts = await getStorageItem(ANALYSIS_COUNTS_KEY); + return counts?.[currentAiPeriod(now)] ?? 0; +} + +/** The "Share anonymous usage counts" setting. Unset means on. */ +export async function isUsageSharingEnabled(): Promise { + return (await getStorageItem(SHARE_USAGE_KEY)) !== false; +} + +export async function setUsageSharingEnabled(enabled: boolean): Promise { + await setStorageItem(SHARE_USAGE_KEY, enabled); +} + +let reportInFlight: Promise | null = null; + +/** + * Sends the month's running total, plus last month's when it grew after that + * month's final report, if sharing is on and no report was attempted in the + * past 24 hours. Never throws: a failed report waits for the next day. + */ +export function reportUsageIfDue(now: Date = new Date()): Promise { + reportInFlight ??= sendDueReport(now) + .catch(() => undefined) + .finally(() => { + reportInFlight = null; + }); + return reportInFlight; +} + +async function sendDueReport(now: Date): Promise { + if (!(await isUsageSharingEnabled())) return; + const state = await getStorageItem(USAGE_REPORT_KEY); + const sinceLastAttempt = now.getTime() - (state?.lastAttemptAt ?? 0); + // A negative gap means the clock moved back; treat that as due rather than stall. + if (sinceLastAttempt >= 0 && sinceLastAttempt < DAY_MS) return; + + const counts = (await getStorageItem(ANALYSIS_COUNTS_KEY)) ?? {}; + const sent = keepReportable(state?.sent ?? {}, now); + const due = reportablePeriods(now) + .map((period) => ({ period, count: Math.min(counts[period] ?? 0, MAX_REPORTED_COUNT) })) + .filter(({ period, count }) => count > (sent[period] ?? 0)); + if (due.length === 0) return; + + // Record the attempt before sending, so a failure (offline, an error status, + // the endpoint not live yet) waits a day instead of retrying on every analysis. + await setStorageItem(USAGE_REPORT_KEY, { lastAttemptAt: now.getTime(), sent }); + const installId = await getInstallId(); + for (const { period, count } of due) { + if (await postAnalysisCount(installId, period, count)) sent[period] = count; + } + await setStorageItem(USAGE_REPORT_KEY, { lastAttemptAt: now.getTime(), sent }); +} + +/** POSTs one month's total; true when the backend accepted it. */ +async function postAnalysisCount(installId: string, period: string, count: number): Promise { + try { + const response = await fetch(`${BACKEND_BASE_URL}/usage/analysis`, { + method: "POST", + headers: { "Content-Type": "application/json" }, + body: JSON.stringify({ installId, period, count }), + }); + return response.ok; + } catch { + return false; + } +} diff --git a/app/src/options/Options.test.tsx b/app/src/options/Options.test.tsx index 4501970..d099df2 100644 --- a/app/src/options/Options.test.tsx +++ b/app/src/options/Options.test.tsx @@ -422,4 +422,86 @@ describe("Options page", () => { await waitFor(() => expect(screen.getByText("Free")).toBeInTheDocument()); expect(screen.getByLabelText(/license key/i)).toBeInTheDocument(); }); + + // --- Usage counts (#80) --- + + const thisMonth = () => new Date().toISOString().slice(0, 7); + + function storedItems(items: Record) { + (chrome.storage.local.get as ReturnType).mockImplementation(() => + Promise.resolve(items), + ); + } + + it("shows this month's analysis count next to the free AI quota line", async () => { + getFreeAiQuotaMock.mockResolvedValue({ period: thisMonth(), remaining: 3, limit: 25 }); + storedItems({ usage_analyses: { [thisMonth()]: 7 } }); + render(); + + expect(await screen.findByText("7 pages analyzed this month.")).toBeInTheDocument(); + expect(screen.getByText(/free ai quota this month: 3 of 25 remaining/i)).toBeInTheDocument(); + }); + + it("shows the count on its own before any AI use, in the singular for one page", async () => { + storedItems({ usage_analyses: { [thisMonth()]: 1 } }); + render(); + + expect(await screen.findByText("1 page analyzed this month.")).toBeInTheDocument(); + expect(screen.queryByText(/free ai quota this month/i)).not.toBeInTheDocument(); + }); + + it("counts only the current month", async () => { + storedItems({ usage_analyses: { "2000-01": 40 } }); + render(); + + expect(await screen.findByText("0 pages analyzed this month.")).toBeInTheDocument(); + }); + + it("shows the count next to the Pro quota meter", async () => { + mockPro(100); + storedItems({ usage_analyses: { [thisMonth()]: 12 } }); + render(); + + expect(await screen.findByText("12 pages analyzed this month.")).toBeInTheDocument(); + expect(screen.getByText(/ai quota this month: 100 of 100 remaining/i)).toBeInTheDocument(); + }); + + it("updates the count when the side panel records an analysis", async () => { + storedItems({ usage_analyses: { [thisMonth()]: 2 } }); + render(); + await screen.findByText("2 pages analyzed this month."); + + storedItems({ usage_analyses: { [thisMonth()]: 3 } }); + const onChanged = vi.mocked(chrome.storage.onChanged.addListener).mock.calls.at(-1)![0]; + onChanged({ usage_analyses: { newValue: { [thisMonth()]: 3 } } }, "local"); + + expect(await screen.findByText("3 pages analyzed this month.")).toBeInTheDocument(); + }); + + it("shares anonymous usage counts by default and turns sharing off immediately", async () => { + const user = userEvent.setup(); + render(); + + const toggle = await screen.findByLabelText(/share anonymous usage counts/i); + expect(toggle).toBeChecked(); + expect(screen.getByText(/at most once a day/i)).toHaveTextContent( + /never urls, page content, keywords or scores/i, + ); + + await user.click(toggle); + + expect(chrome.storage.local.set).toHaveBeenCalledWith({ share_usage_counts: false }); + expect(toggle).not.toBeChecked(); + expect(screen.getByText(/nothing is sent/i)).toBeInTheDocument(); + }); + + it("renders the usage toggle off when sharing was turned off", async () => { + storedItems({ share_usage_counts: false }); + render(); + + await waitFor(() => { + expect(screen.getByLabelText(/share anonymous usage counts/i)).not.toBeChecked(); + }); + expect(screen.getByText(/nothing is sent/i)).toBeInTheDocument(); + }); }); diff --git a/app/src/options/Options.tsx b/app/src/options/Options.tsx index 6bd59d6..c79581d 100644 --- a/app/src/options/Options.tsx +++ b/app/src/options/Options.tsx @@ -8,6 +8,12 @@ import { useAiStatus, useEntitlementStore } from "@/lib/entitlement-store"; import { useStore } from "@/lib/store"; import { listTopModels } from "@/lib/anthropic"; import { fetchProxyModels } from "@/lib/ai-proxy"; +import { + ANALYSIS_COUNTS_KEY, + getMonthlyAnalysisCount, + isUsageSharingEnabled, + setUsageSharingEnabled, +} from "@/lib/usage"; /** Opens an external URL in a new tab (extension page or dev preview). */ function openExternalUrl(url: string) { @@ -18,6 +24,44 @@ function openExternalUrl(url: string) { } } +/** This month's local analysis count, kept current while the side panel runs analyses. */ +function useMonthlyAnalysisCount(): number | null { + const [count, setCount] = useState(null); + + useEffect(() => { + let cancelled = false; + const load = () => { + void getMonthlyAnalysisCount().then((value) => { + if (!cancelled) setCount(value); + }); + }; + const onChanged: Parameters[0] = ( + changes, + area, + ) => { + if (area === "local" && changes[ANALYSIS_COUNTS_KEY]) load(); + }; + load(); + chrome.storage.onChanged.addListener(onChanged); + return () => { + cancelled = true; + chrome.storage.onChanged.removeListener(onChanged); + }; + }, []); + + return count; +} + +function AnalysisCountLine() { + const count = useMonthlyAnalysisCount(); + if (count === null) return null; + return ( +

+ {count.toLocaleString()} {count === 1 ? "page" : "pages"} analyzed this month. +

+ ); +} + function LicenseCard() { const isPro = useEntitlementStore((state) => state.isPro); const expiresAt = useEntitlementStore((state) => state.expiresAt); @@ -84,17 +128,20 @@ function LicenseCard() { <> Your entitlement auto-renews by {new Date(expiresAt).toLocaleDateString()}. )}

- {aiStatus.mode === "byok" ? ( -

- AI: using your Anthropic key — not metered. -

- ) : ( - quotaLimit > 0 && ( +
+ {aiStatus.mode === "byok" ? (

- AI quota this month: {aiQuotaRemaining} of {quotaLimit} remaining. + AI: using your Anthropic key — not metered.

- ) - )} + ) : ( + quotaLimit > 0 && ( +

+ AI quota this month: {aiQuotaRemaining} of {quotaLimit} remaining. +

+ ) + )} + +
{billingPortalError && (

{billingPortalError} @@ -126,11 +173,14 @@ function LicenseCard() { Enter your Optia Pro license key to unlock AI without an Anthropic key and advanced analysis.

- {freeAiRemaining !== null && freeAiLimit !== null && ( -

- Free AI quota this month: {freeAiRemaining} of {freeAiLimit} remaining. -

- )} +
+ {freeAiRemaining !== null && freeAiLimit !== null && ( +

+ Free AI quota this month: {freeAiRemaining} of {freeAiLimit} remaining. +

+ )} + +
diff --git a/app/src/sidepanel/App.test.tsx b/app/src/sidepanel/App.test.tsx new file mode 100644 index 0000000..9ee6225 --- /dev/null +++ b/app/src/sidepanel/App.test.tsx @@ -0,0 +1,117 @@ +import { render, screen, waitFor } from "@testing-library/react"; +import userEvent from "@testing-library/user-event"; +import { describe, it, expect, vi, beforeEach } from "vitest"; +import App from "./App"; +import { useStore } from "@/lib/store"; +import { fetchAndAnalyzePage } from "@/lib/fetch-page"; +import { recordAnalysis, reportUsageIfDue } from "@/lib/usage"; +import type { PageSEOData } from "@/types/seo"; + +// The harness path (no chrome.tabs in jsdom) fetches the page by URL; stub the +// fetch and the usage layer so this suite only sees how App drives them. +vi.mock("@/lib/fetch-page", () => ({ fetchAndAnalyzePage: vi.fn() })); +vi.mock("@/lib/usage", () => ({ + recordAnalysis: vi.fn(), + reportUsageIfDue: vi.fn(), +})); +vi.mock("canvas-confetti", () => ({ default: vi.fn() })); + +const fetchAndAnalyzePageMock = vi.mocked(fetchAndAnalyzePage); +const recordAnalysisMock = vi.mocked(recordAnalysis); +const reportUsageIfDueMock = vi.mocked(reportUsageIfDue); + +const pageData: PageSEOData = { + url: "https://example.com/", + title: "Example Domain", + metaDescription: "An example page", + metaKeywords: "", + canonical: "https://example.com/", + h1: ["Example Domain"], + h2: [], + h3: [], + h4: [], + h5: [], + h6: [], + images: [], + ogTags: {}, + twitterTags: {}, + wordCount: 120, + internalLinks: 1, + externalLinks: 1, + lang: "en", + paragraphs: ["This domain is for use in examples."], + resources: { js: [], css: [] }, + schemaMarkup: { types: [], count: 0 }, + ogImage: "", + imageFileSizes: [], + fetchWarnings: [], +}; + +async function analyze(user: ReturnType) { + await user.click(screen.getByRole("button", { name: /optimize my seo/i })); +} + +beforeEach(async () => { + // Past onboarding, on the setup screen with a URL and keyword filled in. + await chrome.storage.local.set({ onboarding_dismissed: true }); + useStore.setState({ + view: "setup", + analysis: null, + activeCategory: null, + error: null, + settings: { + keyword: "example", + secondaryKeywords: "", + pageType: "homepage", + language: "en", + advancedMode: false, + targetUrl: "https://example.com/", + }, + }); + fetchAndAnalyzePageMock.mockResolvedValue(pageData); + recordAnalysisMock.mockResolvedValue(undefined); + reportUsageIfDueMock.mockResolvedValue(undefined); +}); + +describe("App analysis usage counting", () => { + it("counts each completed analysis exactly once, then checks for a due report", async () => { + const user = userEvent.setup(); + render(); + + await analyze(user); + await screen.findByRole("button", { name: /new analysis/i }); + + expect(recordAnalysisMock).toHaveBeenCalledTimes(1); + await waitFor(() => expect(reportUsageIfDueMock).toHaveBeenCalledTimes(1)); + + await user.click(screen.getByRole("button", { name: /new analysis/i })); + await analyze(user); + await screen.findByRole("button", { name: /new analysis/i }); + + expect(recordAnalysisMock).toHaveBeenCalledTimes(2); + await waitFor(() => expect(reportUsageIfDueMock).toHaveBeenCalledTimes(2)); + }); + + it("does not count an analysis that failed", async () => { + const user = userEvent.setup(); + fetchAndAnalyzePageMock.mockRejectedValue(new Error("Could not fetch the page")); + render(); + + await analyze(user); + + expect(await screen.findByText(/could not fetch the page/i)).toBeInTheDocument(); + expect(recordAnalysisMock).not.toHaveBeenCalled(); + expect(reportUsageIfDueMock).not.toHaveBeenCalled(); + }); + + it("still shows the results when the local count cannot be saved", async () => { + const user = userEvent.setup(); + recordAnalysisMock.mockRejectedValue(new Error("storage unavailable")); + render(); + + await analyze(user); + + expect(await screen.findByRole("button", { name: /new analysis/i })).toBeInTheDocument(); + expect(reportUsageIfDueMock).not.toHaveBeenCalled(); + }); +}); diff --git a/app/src/sidepanel/App.tsx b/app/src/sidepanel/App.tsx index 74c740b..c93531c 100644 --- a/app/src/sidepanel/App.tsx +++ b/app/src/sidepanel/App.tsx @@ -7,6 +7,7 @@ import { fetchAndAnalyzePage } from "@/lib/fetch-page"; import { detectLanguage } from "@/lib/languages"; import { generateRecommendation, generateAllH2Suggestions } from "@/lib/ai"; import { aiStatusNow } from "@/lib/entitlement-store"; +import { recordAnalysis, reportUsageIfDue } from "@/lib/usage"; import { saveKeywordForUrl, getKeywordForUrl, @@ -381,6 +382,14 @@ export default function App() { setAnalysis(analysis); + // Count the completed analysis, then send the once-a-day anonymous usage + // report if one is due (#80). Fire-and-forget: it never delays results. + void recordAnalysis() + .then(() => reportUsageIfDue()) + .catch(() => { + // Usage counting is non-critical + }); + // Auto-generate AI recommendations in the background (non-blocking) only // for unmetered/high-cap paths. Free users generate on demand per // recommendation so a single analysis doesn't drain their monthly allowance. diff --git a/docs/architecture.md b/docs/architecture.md index f8a9ac3..66af59b 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -19,6 +19,7 @@ Optia is **open-core**. The split is by trust, not by convenience: | Licensing | The **client** half: entitlement verification, caching, refresh, the paywall/account UI, checkout *initiation* | The **authority** half: license minting, Ed25519 **signing** (private key), seat activation, revocation | | Billing | Opens Checkout/portal URLs the backend returns | Stripe integration: Checkout session creation (price allowlist), Billing Portal, webhook ingestion — webhooks are the source of truth for license state | | AI | The routing facade (`app/src/lib/ai.ts`) and the BYO-key direct path | The hosted AI proxy `/ai/generate`: server-funded Anthropic key, per-subject metering (D1), rate limiting (KV), per-check prompts | +| Usage counts | Counts page analyses per month locally and reports the running total at most once a day (`app/src/lib/usage.ts`) | `POST /usage/analysis`: keeps the highest count per install and month (D1) | | Secrets | **None.** Public verification keys only | Anthropic API key, Stripe secret + webhook secret, the entitlement signing JWK | The extension's full gating logic is public on purpose. Hiding it would add @@ -38,6 +39,7 @@ flowchart LR LIC["/license
activate · refresh · deactivate
Ed25519 entitlement signing"] BILL["/billing
checkout · portal · webhook"] AIP["/ai/generate
metered proxy"] + USG["/usage/analysis
monthly analysis counts"] D1[("D1
licenses · usage")] KV[("KV
rate limits")] end @@ -52,10 +54,12 @@ flowchart LR EXT -- "BYO key (Pro): direct,
never transits the backend" --> ANTH EXT --> LIC EXT -- "start checkout / portal" --> BILL + EXT -- "at most daily: install id,
month, count" --> USG BILL <--> STRIPE STRIPE -- "webhooks (license truth)" --> BILL LIC --- D1 AIP --- D1 + USG --- D1 AIP --- KV STRIPE -- "redirects after pay/cancel" --> PAGES ``` @@ -63,6 +67,12 @@ flowchart LR Notes the diagram can't carry: - **SEO analysis is fully local.** Scoring never sends the page anywhere. +- **The only usage signal is a count.** At most once a day, right after an + analysis, the side panel sends `{ installId, period, count }` (the month's + running total of pages analyzed) to `POST /usage/analysis`. The backend keeps + the highest count per install and month, so a re-sent total changes nothing. + "Share anonymous usage counts" in Options stops the reports; the local count + continues. Nothing enforces a limit on analyses (#80, optia-backend#30). - **BYO-key requests never touch the backend** — the proxy deliberately ignores any `Authorization` header, so user keys cannot transit our infrastructure even by accident. diff --git a/docs/chrome-web-store-data-disclosure.md b/docs/chrome-web-store-data-disclosure.md index cf24983..537577a 100644 --- a/docs/chrome-web-store-data-disclosure.md +++ b/docs/chrome-web-store-data-disclosure.md @@ -12,14 +12,14 @@ For each category the dashboard asks about, declare: | Dashboard category | Collected? | Detail | |---|---|---| -| Personally identifiable information | **No** | No name, address, email, or ID is collected by the extension. (Stripe collects billing details during Pro checkout on Stripe-hosted pages — outside the extension.) | +| Personally identifiable information | **No** | No name, address, email, or identification number is collected by the extension; the random install ID is not linked to identity. (Stripe collects billing details during Pro checkout on Stripe-hosted pages — outside the extension.) | | Health information | No | — | | Financial and payment information | **No** | Payment is handled entirely by Stripe's hosted checkout/portal; the extension never sees card data. | | Authentication information | **Yes** | A Pro license key and a signed entitlement token are sent to our backend to activate/refresh the license. A user's optional Anthropic API key is stored locally only and sent only to Anthropic — never to us. | | Personal communications | No | — | | Location | No | No location data; standard IP handling by our CDN/backend is not used for geolocation features. | | Web history | **No** | The extension does not record browsing history. It reads a page's content only when the user runs an analysis on that page. | -| User activity | **No** | No analytics, telemetry, clickstream, or usage tracking. The only counters are anonymous quota counts (install ID / license) needed to meter the AI allowance. | +| User activity | **Yes** | One anonymous usage count: the number of pages the user analyzed this month, sent at most once a day after an analysis with the random install ID and the month, and nothing else (no URLs, page content, keywords or scores). On by default; the user turns it off in Options ("Share anonymous usage counts"). No clickstream, keystroke, mouse or scroll data, and no analytics SDK. The AI allowance is also metered by anonymous counts (install ID / license). | | Website content | **Yes** | When the user requests an AI recommendation, the target keyword and the relevant page snippets (title/heading/alt-text context) are sent to our AI service — or directly to Anthropic in bring-your-own-key mode — solely to generate the suggestion. | ## Certifications (check all three) @@ -30,13 +30,13 @@ For each category the dashboard asks about, declare: ## Limited Use -Optia's use of website content complies with the Limited Use policy: data sent to the AI service is used only to provide the user-requested feature (generating the SEO suggestion), is not used for advertising, and is not sold. +Optia's use of website content complies with the Limited Use policy: data sent to the AI service is used only to provide the user-requested feature (generating the SEO suggestion), is not used for advertising, and is not sold. The anonymous usage count is used only to see how much the extension is used and to set the free tier's limits; it is not used for advertising and is not sold. ## Remote code Declare **No remote code**. All executable code ships in the package. Network calls fetch data (JSON) only: -- `https://api.optia-api.com` — AI proxy, license activation/refresh, billing portal session (production) +- `https://api.optia-api.com` — AI proxy, license activation/refresh, billing portal session, and the once-a-day anonymous usage count (production) - `https://api.anthropic.com` — direct AI calls in Pro bring-your-own-key mode only - `https://checkout.stripe.com` / billing portal — opened as pages, not fetched into the extension diff --git a/docs/chrome-web-store-listing.md b/docs/chrome-web-store-listing.md index f2af59b..bfa0329 100644 --- a/docs/chrome-web-store-listing.md +++ b/docs/chrome-web-store-listing.md @@ -62,7 +62,7 @@ Note: Optia Pro is purchased from us and billed securely through Stripe — not **PRIVACY FIRST** -All SEO analysis happens locally in your browser. When you request an AI recommendation, only the relevant page snippets (like the current title and your keyword) are sent to our AI service to generate the suggestion — nothing else, and never in the background. No accounts required for the free tier. No tracking, no ads, no analytics, and your data is never sold. Pro users who bring their own Anthropic key talk to Anthropic directly; the key never leaves the browser. +All SEO analysis happens locally in your browser. When you request an AI recommendation, only the relevant page snippets (like the current title and your keyword) are sent to our AI service to generate the suggestion — nothing else, and never in the background. At most once a day, Optia also sends one anonymous number: how many pages you analyzed this month, with a random install ID. No URLs, page content or scores, and you can turn it off in Options. No accounts required for the free tier. No tracking, no ads, no analytics services, and your data is never sold. Pro users who bring their own Anthropic key talk to Anthropic directly; the key never leaves the browser. Full privacy policy: https://pmdevsolutions.github.io/Optia/privacy.html diff --git a/docs/privacy-policy.md b/docs/privacy-policy.md index 4a34b49..c6e3614 100644 --- a/docs/privacy-policy.md +++ b/docs/privacy-policy.md @@ -1,7 +1,7 @@ # Optia Privacy Policy **Effective date:** 2026-08-20 -**Last updated:** 2026-08-20 +**Last updated:** 2026-10-24 > Published at **https://pmdevsolutions.github.io/Optia/privacy.html** (rendered from `site/privacy.html` — keep the two in sync; the HTML version is the user-facing one). Grounded in the extension's actual data flows (see `docs/free-vs-pro-gating.md` and the backend design records). **A qualified lawyer's review is still recommended** — tracked in `docs/launch-checklist.md` Phase 0. @@ -11,14 +11,15 @@ Optia ("we", "our") is a Chrome extension that analyzes web pages for SEO issues - SEO analysis runs **locally in your browser**. Pages you visit are not sent anywhere just by browsing. - When you explicitly request an AI recommendation, the relevant page snippets are sent to our AI service (or directly to Anthropic if you use your own API key) to generate the suggestion. -- We require **no account** for the free tier, and we use **no analytics, no ads, and no trackers**. We never sell your data. +- At most once a day, Optia sends us one **anonymous usage count**: a random install ID, the month, and how many pages you analyzed that month. No URLs, page content, keywords or scores. You can turn it off in Optia's options. +- We require **no account** for the free tier, and we use **no analytics services, no ads, and no trackers**. We never sell your data. - Your own Anthropic API key (Pro option) is stored only in your browser and **never sent to our servers** — this is enforced server-side: our backend does not accept caller API keys. ## Data we handle, and where it goes ### 1. Page content you analyze (stays local by default) -When you run an analysis, Optia's content script reads the current page's SEO-relevant elements (title, meta tags, headings, image alt attributes, link structure, body text) **inside your browser** and computes the score locally. This data is not transmitted. +When you run an analysis, Optia's content script reads the current page's SEO-relevant elements (title, meta tags, headings, image alt attributes, link structure, body text) **inside your browser** and computes the score locally. This data is not transmitted. Running an analysis adds one to the monthly count described in section 4; nothing about the page itself goes with it. ### 2. AI recommendation requests (sent only when you click) @@ -27,19 +28,23 @@ When you request an AI suggestion, Optia sends the minimum needed to generate it - **Hosted mode (default, free and Pro):** sent to our backend (`api.optia-api.com`, Cloudflare Workers), which forwards it to Anthropic's Claude API to generate the suggestion. Our backend meters usage counts; it does not build profiles from request content. Anthropic processes the snippets as our AI provider ([Anthropic's privacy policy](https://www.anthropic.com/legal/privacy)). - **Bring-your-own-key mode (Pro):** sent directly from your browser to Anthropic using your key. Our servers are not involved at all. -### 3. Install identifier (free-tier metering) +### 3. Install identifier -Free-tier AI requests include a random install ID generated by your extension. It exists solely to meter the free monthly allowance, is not linked to your identity, and resets if you reinstall. +Your extension generates a random install ID. It is sent with hosted AI requests, where it meters the monthly allowance; with Pro checkout and license activation, where it ties a license seat to this browser; and with the usage count in section 4. It is not linked to your identity and resets if you reinstall. -### 4. License and billing data (Pro only) +### 4. Anonymous usage count (on unless you turn it off) + +Optia counts the pages you analyze each month, on your device. At most once a day, after you run an analysis, it sends that count to our backend (`api.optia-api.com`). The report contains only three things: your install ID, the month (for example `2026-11`), and how many pages you have analyzed that month. It never contains URLs, page content, keywords or scores. This applies on every plan. We use the counts to see how much Optia is used, so the free tier's limits are set from real numbers. To stop the reports, turn off **Share anonymous usage counts** in Optia's options. Optia keeps counting on your device, so the options page can still show you the number, but sends nothing. + +### 5. License and billing data (Pro only) If you purchase Optia Pro, checkout and payment are handled by **Stripe** — we never see your card details ([Stripe's privacy policy](https://stripe.com/privacy)). Our backend stores what's needed to operate your license: your license key, subscription status, and billing-portal linkage. Activating Pro stores a signed entitlement token in your browser, refreshed periodically. -### 5. Your Anthropic API key (Pro, optional) +### 6. Your Anthropic API key (Pro, optional) Stored only in Chrome's local extension storage on your device. Used exclusively for direct browser→Anthropic requests. Never transmitted to our backend, logged by us, or synced. -### 6. Settings and history (local) +### 7. Settings and history (local) Your keyword history, per-site options, language preference, and toggles are stored in Chrome's local extension storage on your device. Nothing is synced to us. @@ -53,7 +58,7 @@ Your keyword history, per-site options, language preference, and toggles are sto ## Data retention - Local data (settings, keys, entitlement tokens): retained until you clear it or uninstall the extension. -- Backend metering counters (install ID / license usage): retained per monthly quota period for billing/abuse-prevention purposes. +- Backend usage counters (AI requests per install ID or license, and pages analyzed per install ID): kept as one total per month, for billing, abuse prevention and setting the free tier's limits. - Backend request logs: operational logs are short-lived and used for reliability and abuse prevention, not profiling. ## Your rights diff --git a/site/index.html b/site/index.html index 447e7bd..62f3f8c 100644 --- a/site/index.html +++ b/site/index.html @@ -93,7 +93,7 @@

Optia Pro$50/yr = 2 months free

Privacy first

-

All SEO analysis runs locally in your browser. When you request an AI suggestion, only the relevant page snippets are sent to generate it — nothing else, never in the background. No analytics, no tracking, no ads, and your data is never sold. Pro users who bring their own Anthropic key talk to Anthropic directly; the key never touches our servers.

+

All SEO analysis runs locally in your browser. When you request an AI suggestion, only the relevant page snippets are sent to generate it — nothing else, never in the background. At most once a day, Optia also sends one anonymous number: how many pages you analyzed this month, with a random install ID. No URLs, page content or scores, and you can turn it off in Options. No analytics services, no tracking, no ads, and your data is never sold. Pro users who bring their own Anthropic key talk to Anthropic directly; the key never touches our servers.

Read the full privacy policy →

diff --git a/site/privacy.html b/site/privacy.html index c562497..e0b73aa 100644 --- a/site/privacy.html +++ b/site/privacy.html @@ -27,7 +27,7 @@
← Optia home

Optia Privacy Policy

-

Effective date: August 20, 2026 · Last updated: August 20, 2026

+

Effective date: August 20, 2026 · Last updated: October 24, 2026

Optia ("we", "our") is a Chrome extension operated by Paul Mulligan Development Solutions (PMDS) that analyzes web pages for SEO issues and generates AI-powered recommendations. This policy explains what data Optia handles, where it goes, and the choices you have.

@@ -35,14 +35,15 @@

The short version

  • SEO analysis runs locally in your browser. Pages you visit are not sent anywhere just by browsing.
  • When you explicitly request an AI recommendation, the relevant page snippets are sent to our AI service (or directly to Anthropic if you use your own API key) to generate the suggestion.
    • -
  • We require no account for the free tier, and we use no analytics, no ads, and no trackers. We never sell your data.
    • +
  • At most once a day, Optia sends us one anonymous usage count: a random install ID, the month, and how many pages you analyzed that month. No URLs, page content, keywords or scores. You can turn it off in Optia's options.
    • +
  • We require no account for the free tier, and we use no analytics services, no ads, and no trackers. We never sell your data.
  • Your own Anthropic API key (Pro option) is stored only in your browser and never sent to our servers — enforced server-side: our backend does not accept caller API keys.

Data we handle, and where it goes

1. Page content you analyze (stays local by default)

-

When you run an analysis, Optia's content script reads the current page's SEO-relevant elements (title, meta tags, headings, image alt attributes, link structure, body text) inside your browser and computes the score locally. This data is not transmitted.

+

When you run an analysis, Optia's content script reads the current page's SEO-relevant elements (title, meta tags, headings, image alt attributes, link structure, body text) inside your browser and computes the score locally. This data is not transmitted. Running an analysis adds one to the monthly count described in section 4; nothing about the page itself goes with it.

2. AI recommendation requests (sent only when you click)

When you request an AI suggestion, Optia sends the minimum needed to generate it — your target keyword and the relevant page snippet (e.g., the current title, a heading, or an image reference), plus any page-type or secondary-keyword context you configured:

@@ -51,16 +52,19 @@

2. AI recommendation requests (sent only when you click)

  • Bring-your-own-key mode (Pro): sent directly from your browser to Anthropic using your key. Our servers are not involved at all.
    • -

    3. Install identifier (free-tier metering)

    -

    Free-tier AI requests include a random install ID generated by your extension. It exists solely to meter the free monthly allowance, is not linked to your identity, and resets if you reinstall.

    +

    3. Install identifier

    +

    Your extension generates a random install ID. It is sent with hosted AI requests, where it meters the monthly allowance; with Pro checkout and license activation, where it ties a license seat to this browser; and with the usage count in section 4. It is not linked to your identity and resets if you reinstall.

    -

    4. License and billing data (Pro only)

    +

    4. Anonymous usage count (on unless you turn it off)

    +

    Optia counts the pages you analyze each month, on your device. At most once a day, after you run an analysis, it sends that count to our backend (api.optia-api.com). The report contains only three things: your install ID, the month (for example 2026-11), and how many pages you have analyzed that month. It never contains URLs, page content, keywords or scores. This applies on every plan. We use the counts to see how much Optia is used, so the free tier's limits are set from real numbers. To stop the reports, turn off Share anonymous usage counts in Optia's options. Optia keeps counting on your device, so the options page can still show you the number, but sends nothing.

    + +

    5. License and billing data (Pro only)

    If you purchase Optia Pro, checkout and payment are handled by Stripe — we never see your card details (Stripe's privacy policy). Our backend stores what's needed to operate your license: your license key, subscription status, and billing-portal linkage. Activating Pro stores a signed entitlement token in your browser, refreshed periodically. Pro is billed by us through Stripe, not through the Chrome Web Store.

    -

    5. Your Anthropic API key (Pro, optional)

    +

    6. Your Anthropic API key (Pro, optional)

    Stored only in Chrome's local extension storage on your device. Used exclusively for direct browser-to-Anthropic requests. Never transmitted to our backend, logged by us, or synced.

    -

    6. Settings and history (local)

    +

    7. Settings and history (local)

    Your keyword history, per-site options, language preference, and toggles are stored in Chrome's local extension storage on your device. Nothing is synced to us.

    What we don't do

    @@ -74,7 +78,7 @@

    What we don't do

    Data retention

    • Local data (settings, keys, entitlement tokens): retained until you clear it or uninstall the extension.
      • -
    • Backend metering counters (install ID / license usage): retained per monthly quota period for billing and abuse prevention.
      • +
    • Backend usage counters (AI requests per install ID or license, and pages analyzed per install ID): kept as one total per month, for billing, abuse prevention and setting the free tier's limits.
    • Backend request logs: operational logs are short-lived and used for reliability and abuse prevention, not profiling.