From 3a4e5ad0c7d8be509f25bff7083177886ab45afe Mon Sep 17 00:00:00 2001 From: Muhammad Sohail Date: Wed, 11 Nov 2026 14:09:42 +0500 Subject: [PATCH 01/73] feat(portal): clean the reported page address Step 1.1 of .ai/plans/portal-analytics.md: pageLocation(), holdsOAuthAnswer() and the PortalEvents map with docs_page_view, tested without a DOM. Co-Authored-By: Claude Fable 5.1 --- portal-template/src/lib/analytics.ts | 76 +++++++++++++ test/portal-template/analytics.test.ts | 148 +++++++++++++++++++++++++ 2 files changed, 224 insertions(+) create mode 100644 portal-template/src/lib/analytics.ts create mode 100644 test/portal-template/analytics.test.ts diff --git a/portal-template/src/lib/analytics.ts b/portal-template/src/lib/analytics.ts new file mode 100644 index 00000000..2ea1b142 --- /dev/null +++ b/portal-template/src/lib/analytics.ts @@ -0,0 +1,76 @@ +import { withBasePath } from './base-path'; +import { oauthCallbackPath } from './oauth-callback'; + +/** Names the OAuth standard puts in an answer. While one is in the address, the loader inserts nothing. */ +const OAUTH_ANSWER = [ + 'code', + 'state', + 'access_token', + 'id_token', + 'token_type', + 'expires_in', + 'error', + 'session_state', + 'iss' +]; + +/** Query parameters a reported address keeps: campaign, ad-click and cross-domain tags, which attribution reads from the address. */ +const KEPT_PREFIXES = ['utm_', 'hsa_']; +const KEPT_NAMES = [ + '_gl', + 'gclid', + 'gbraid', + 'wbraid', + 'gad_source', + 'dclid', + 'fbclid', + 'msclkid', + 'ttclid', + 'twclid', + 'li_fat_id', + 'mc_cid', + '_hsenc', + '_hsmi', + 'ref' +]; + +/** + * Each event's keys, besides the `page_location` every report adds. Customers' GTM triggers + * match these names, so renaming or removing one breaks them without an error. + */ +export interface PortalEvents { + docs_page_view: { page_title: string }; +} +export type PortalEventName = keyof PortalEvents; + +export interface PortalEvent { + readonly name: PortalEventName; + readonly params: Readonly>; + readonly time: number; + /** Lets a later shape be told from this one. */ + readonly version: 1; +} + +/** The reset entry, then the event entry with every detail under `docs`. */ +export type DataLayerEntry = + | { docs: null } + | { event: PortalEventName; docs: Readonly> }; + +/** The address as reported: no `#` part, no query but the kept tags, and null on the OAuth callback. */ +export function pageLocation(href: string, keep: readonly string[], base?: string): string | null { + const url = new URL(href); + // A static host may answer `/oauth/callback` at `/oauth/callback/` and keep the query. + if (url.pathname.replace(/\/$/, '') === withBasePath(oauthCallbackPath, base)) return null; + const kept = (name: string) => + KEPT_PREFIXES.some((prefix) => name.startsWith(prefix)) || KEPT_NAMES.includes(name) || keep.includes(name); + url.search = new URLSearchParams([...url.searchParams].filter(([name]) => kept(name))).toString(); + url.hash = ''; + return url.href; +} + +/** True while the query or the `#` part holds a name the OAuth standard puts in an answer. */ +export function holdsOAuthAnswer(href: string): boolean { + const url = new URL(href); + const hash = new URLSearchParams(url.hash.slice(1)); + return OAUTH_ANSWER.some((name) => url.searchParams.has(name) || hash.has(name)); +} diff --git a/test/portal-template/analytics.test.ts b/test/portal-template/analytics.test.ts new file mode 100644 index 00000000..e9c2c5d4 --- /dev/null +++ b/test/portal-template/analytics.test.ts @@ -0,0 +1,148 @@ +import { expect } from 'chai'; +import { holdsOAuthAnswer, pageLocation, PortalEventName, PortalEvents } from '../../portal-template/src/lib/analytics'; + +// The lists are written out here, not imported: the test is the contract, and a name the module drops fails it. +const OAUTH_ANSWER = [ + 'code', + 'state', + 'access_token', + 'id_token', + 'token_type', + 'expires_in', + 'error', + 'session_state', + 'iss' +]; +const KEPT_NAMES = [ + '_gl', + 'gclid', + 'gbraid', + 'wbraid', + 'gad_source', + 'dclid', + 'fbclid', + 'msclkid', + 'ttclid', + 'twclid', + 'li_fat_id', + 'mc_cid', + '_hsenc', + '_hsmi', + 'ref' +]; + +describe('pageLocation', () => { + const page = 'https://docs.test/guides/quickstart'; + + it('drops the query and the # part', () => { + expect(pageLocation(`${page}?tab=python&page=2#install`, [])).to.equal(page); + expect(pageLocation(`${page}#install`, [])).to.equal(page); + }); + + it('keeps campaign tags', () => { + expect(pageLocation(`${page}?utm_source=newsletter&utm_medium=email&session=abc`, [])).to.equal( + `${page}?utm_source=newsletter&utm_medium=email` + ); + }); + + it('keeps HubSpot ad tags', () => { + expect(pageLocation(`${page}?hsa_acc=1&hsa_cam=2&session=abc`, [])).to.equal(`${page}?hsa_acc=1&hsa_cam=2`); + }); + + it('keeps each ad-click and cross-domain tag', () => { + for (const name of KEPT_NAMES) { + expect(pageLocation(`${page}?${name}=x&session=abc`, []), name).to.equal(`${page}?${name}=x`); + } + }); + + it("keeps the customer's own names", () => { + expect(pageLocation(`${page}?campaign_id=7&session=abc`, ['campaign_id'])).to.equal(`${page}?campaign_id=7`); + }); + + it('drops a name that only starts with a kept one', () => { + expect(pageLocation(`${page}?gclidx=1`, [])).to.equal(page); + }); + + it('is null on the OAuth callback', () => { + expect(pageLocation('https://docs.test/oauth/callback?code=abc&state=123', [])).to.be.null; + expect(pageLocation('https://docs.test/oauth/callback#access_token=xyz&state=123', [])).to.be.null; + }); + + it('is null on the OAuth callback under a base path', () => { + expect(pageLocation('https://docs.test/docs/oauth/callback?code=abc&state=123', [], '/docs/')).to.be.null; + }); + + // A static host may answer `/oauth/callback` at `/oauth/callback/` and keep the query. + it('is null on the OAuth callback with a trailing slash', () => { + expect(pageLocation('https://docs.test/oauth/callback/?code=abc&state=123', [])).to.be.null; + expect(pageLocation('https://docs.test/docs/oauth/callback/#access_token=xyz', [], '/docs/')).to.be.null; + }); + + it('is not the callback at the root when the portal is under a base path', () => { + expect(pageLocation('https://docs.test/oauth/callback', [], '/docs/')).to.equal('https://docs.test/oauth/callback'); + }); + + it('leaves the address otherwise unchanged', () => { + expect(pageLocation(page, [])).to.equal(page); + expect(pageLocation('https://docs.test/', [])).to.equal('https://docs.test/'); + expect(pageLocation('https://docs.test/docs/api/pets/Get%20Pets', [], '/docs/')).to.equal( + 'https://docs.test/docs/api/pets/Get%20Pets' + ); + expect(pageLocation('http://localhost:3000/guides/quickstart', [])).to.equal( + 'http://localhost:3000/guides/quickstart' + ); + }); +}); + +describe('holdsOAuthAnswer', () => { + const page = 'https://docs.test/api/pets/listPets'; + + it('is true for each OAuth answer name on its own, in the query', () => { + for (const name of OAUTH_ANSWER) { + expect(holdsOAuthAnswer(`${page}?${name}=x`), name).to.be.true; + } + }); + + it('is true for each OAuth answer name on its own, after the #', () => { + for (const name of OAUTH_ANSWER) { + expect(holdsOAuthAnswer(`${page}#${name}=x`), name).to.be.true; + } + }); + + it('is true with the answer beside other parameters', () => { + expect(holdsOAuthAnswer(`${page}?utm_source=newsletter&code=abc&state=123`)).to.be.true; + expect(holdsOAuthAnswer(`${page}?tab=python#access_token=xyz&state=123`)).to.be.true; + }); + + it("is false for a campaign tag or a name of the customer's own", () => { + expect(holdsOAuthAnswer(`${page}?utm_source=newsletter`)).to.be.false; + expect(holdsOAuthAnswer(`${page}?campaign_id=7`)).to.be.false; + expect(holdsOAuthAnswer(`${page}#campaign_id=7`)).to.be.false; + }); + + it('is false for a clean address', () => { + expect(holdsOAuthAnswer(page)).to.be.false; + expect(holdsOAuthAnswer(`${page}#install`)).to.be.false; + }); +}); + +describe('PortalEvents', () => { + // The compiler holds this table to the interface: a missing event, a missing key or an extra key does not compile. + const events: { [E in PortalEventName]: Record } = { + docs_page_view: { page_title: true } + }; + + it('names every event docs_ plus lowercase snake_case, at most 40 characters', () => { + for (const name of Object.keys(events)) { + expect(name).to.match(/^docs_[a-z0-9_]+$/); + expect(name.length, name).to.be.at.most(40); + } + }); + + // GA4 takes at most 25 parameters per event, and report() adds page_location to each. + it('gives every event at most 24 keys, so 25 with page_location', () => { + for (const [name, keys] of Object.entries(events)) { + expect(Object.keys(keys).length, name).to.be.at.most(24); + } + }); +}); From 5e2b3ad4f202f1104ce340b2e4cc870bb0d1cb8e Mon Sep 17 00:00:00 2001 From: Muhammad Sohail Date: Wed, 11 Nov 2026 15:30:21 +0500 Subject: [PATCH 02/73] refactor(portal): keep the kept query names in a Set The list is only ever asked whether it holds a name (SonarCloud on #473). Co-Authored-By: Claude Fable 5.1 --- portal-template/src/lib/analytics.ts | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/portal-template/src/lib/analytics.ts b/portal-template/src/lib/analytics.ts index 2ea1b142..294074ea 100644 --- a/portal-template/src/lib/analytics.ts +++ b/portal-template/src/lib/analytics.ts @@ -16,7 +16,7 @@ const OAUTH_ANSWER = [ /** Query parameters a reported address keeps: campaign, ad-click and cross-domain tags, which attribution reads from the address. */ const KEPT_PREFIXES = ['utm_', 'hsa_']; -const KEPT_NAMES = [ +const KEPT_NAMES = new Set([ '_gl', 'gclid', 'gbraid', @@ -32,7 +32,7 @@ const KEPT_NAMES = [ '_hsenc', '_hsmi', 'ref' -]; +]); /** * Each event's keys, besides the `page_location` every report adds. Customers' GTM triggers @@ -62,7 +62,7 @@ export function pageLocation(href: string, keep: readonly string[], base?: strin // A static host may answer `/oauth/callback` at `/oauth/callback/` and keep the query. if (url.pathname.replace(/\/$/, '') === withBasePath(oauthCallbackPath, base)) return null; const kept = (name: string) => - KEPT_PREFIXES.some((prefix) => name.startsWith(prefix)) || KEPT_NAMES.includes(name) || keep.includes(name); + KEPT_PREFIXES.some((prefix) => name.startsWith(prefix)) || KEPT_NAMES.has(name) || keep.includes(name); url.search = new URLSearchParams([...url.searchParams].filter(([name]) => kept(name))).toString(); url.hash = ''; return url.href; From 0448f115eb5b1b221266d0c0acbad8557f11da46 Mon Sep 17 00:00:00 2001 From: Muhammad Sohail Date: Wed, 11 Nov 2026 16:31:16 +0500 Subject: [PATCH 03/73] feat(portal): report page views to the data layer and GA4 Step 1.2 of .ai/plans/portal-analytics.md: the GTM and GA4 adapters, analyticsFor() with startAnalytics(), report() and reportPageViews(), and the shared adapter suite. The vendor settings join portal-types.ts. Co-Authored-By: Claude Fable 5.1 --- portal-template/src/lib/analytics.ts | 108 +++++ portal-template/src/lib/portal-types.ts | 18 + test/portal-template/analytics.test.ts | 539 +++++++++++++++++++++++- 3 files changed, 664 insertions(+), 1 deletion(-) diff --git a/portal-template/src/lib/analytics.ts b/portal-template/src/lib/analytics.ts index 294074ea..cd0ae4f7 100644 --- a/portal-template/src/lib/analytics.ts +++ b/portal-template/src/lib/analytics.ts @@ -1,5 +1,6 @@ import { withBasePath } from './base-path'; import { oauthCallbackPath } from './oauth-callback'; +import type { PortalAnalytics } from './portal-types'; /** Names the OAuth standard puts in an answer. While one is in the address, the loader inserts nothing. */ const OAUTH_ANSWER = [ @@ -56,6 +57,58 @@ export type DataLayerEntry = | { docs: null } | { event: PortalEventName; docs: Readonly> }; +type Gtag = (...command: unknown[]) => void; + +declare global { + interface Window { + dataLayer?: unknown[]; + gtag?: Gtag; + } +} + +/** Our code for one vendor. The shared adapter suite runs against each. */ +export interface Adapter { + setup(dataLayer: unknown[]): void; + scripts(): string[]; + /** GTM needs nothing here: it reads the data layer. */ + send(name: PortalEventName, params: Record): void; +} + +type Vendor = 'googleTagManager' | 'googleAnalytics'; +const GOOGLE = 'https://www.googletagmanager.com'; + +/** Keyed by every vendor in the union: a vendor without an adapter does not compile. */ +export const adapters: { [V in Vendor]: (setting: NonNullable) => Adapter } = { + googleTagManager: (setting) => { + const env = setting.environment; + const environment = env ? `>m_auth=${env.auth}>m_preview=${env.preview}>m_cookies_win=x` : ''; + return { + setup: (dataLayer) => dataLayer.push({ 'gtm.start': Date.now(), event: 'gtm.js' }), + scripts: () => [`${GOOGLE}/gtm.js?id=${setting.containerId}${environment}`], + send: () => {} + }; + }, + googleAnalytics: (setting) => { + let gtag: Gtag; + return { + setup: (dataLayer) => { + // gtag.js reads only Arguments objects from the data layer, never an array of the same values. + gtag = window.gtag ??= function () { + dataLayer.push(arguments); + }; + gtag('js', new Date()); + gtag('config', setting.measurementId, { + send_page_view: false, + ...(setting.debugMode ? { debug_mode: true } : {}) + }); + }, + scripts: () => [`${GOOGLE}/gtag/js?id=${setting.measurementId}`], + // GA4 gets its own names: the `docs_` prefix comes off. + send: (name, params) => gtag('event', name.replace(/^docs_/, ''), params) + }; + } +}; + /** The address as reported: no `#` part, no query but the kept tags, and null on the OAuth callback. */ export function pageLocation(href: string, keep: readonly string[], base?: string): string | null { const url = new URL(href); @@ -74,3 +127,58 @@ export function holdsOAuthAnswer(href: string): boolean { const hash = new URLSearchParams(url.hash.slice(1)); return OAUTH_ANSWER.some((name) => url.searchParams.has(name) || hash.has(name)); } + +export function analyticsFor(settings: PortalAnalytics) { + const live: Adapter[] = []; + if (settings.googleTagManager) live.push(adapters.googleTagManager(settings.googleTagManager)); + if (settings.googleAnalytics) live.push(adapters.googleAnalytics(settings.googleAnalytics)); + const events: PortalEvent[] = []; + let set = false; + let lastPageView: string | null = null; + + function startAnalytics(): void { + if (set) return; + set = true; + const dataLayer = (window.dataLayer ??= []); + for (const adapter of live) adapter.setup(dataLayer); + if (!holdsOAuthAnswer(window.location.href)) insert(); + } + + function insert(): void { + for (const adapter of live) for (const src of adapter.scripts()) add(src); + } + + function report(name: E, params: PortalEvents[E]): void { + const page_location = pageLocation(window.location.href, settings.keepQueryParams); + if (page_location === null) return; + const all = { ...params, page_location }; + const dataLayer = (window.dataLayer ??= []); + // GTM keeps every key from earlier pushes and merges objects, so clear ours first: a shared GA4 tag never sends the last event's details. + const reset: DataLayerEntry = { docs: null }; + const entry: DataLayerEntry = { event: name, docs: all }; + dataLayer.push(reset); + dataLayer.push(entry); + for (const adapter of live) adapter.send(name, all); + events.push(Object.freeze({ name, params: Object.freeze(all), time: Date.now(), version: 1 })); + } + + function reportPageViews(router: { subscribe(event: 'onRendered', listener: () => void): () => void }): () => void { + const pageView = () => { + const page = pageLocation(window.location.href, settings.keepQueryParams); + if (page === null || page === lastPageView) return; + lastPageView = page; + report('docs_page_view', { page_title: document.title }); + }; + pageView(); + return router.subscribe('onRendered', pageView); + } + + return { startAnalytics, report, reportPageViews, events }; +} + +function add(src: string): void { + const script = document.createElement('script'); + script.async = true; + script.src = src; + document.head.append(script); +} diff --git a/portal-template/src/lib/portal-types.ts b/portal-template/src/lib/portal-types.ts index 8762b2eb..2c1a18b6 100644 --- a/portal-template/src/lib/portal-types.ts +++ b/portal-template/src/lib/portal-types.ts @@ -22,6 +22,24 @@ export interface PortalFavicon { type: string | null; } +export interface GoogleTagManagerSetting { + containerId: string; + environment: { auth: string; preview: string } | null; +} + +/** `debugMode` is set by the CLI under `portal serve`. */ +export interface GoogleAnalyticsSetting { + measurementId: string; + debugMode: boolean; +} + +/** Public values: they sit in every page's scripts. */ +export interface PortalAnalytics { + googleTagManager: GoogleTagManagerSetting | null; + googleAnalytics: GoogleAnalyticsSetting | null; + keepQueryParams: string[]; +} + export interface Portal { name: string; description: string | null; diff --git a/test/portal-template/analytics.test.ts b/test/portal-template/analytics.test.ts index e9c2c5d4..49dc60fd 100644 --- a/test/portal-template/analytics.test.ts +++ b/test/portal-template/analytics.test.ts @@ -1,5 +1,14 @@ import { expect } from 'chai'; -import { holdsOAuthAnswer, pageLocation, PortalEventName, PortalEvents } from '../../portal-template/src/lib/analytics'; +import { + Adapter, + adapters, + analyticsFor, + holdsOAuthAnswer, + pageLocation, + PortalEventName, + PortalEvents +} from '../../portal-template/src/lib/analytics'; +import type { PortalAnalytics } from '../../portal-template/src/lib/portal-types'; // The lists are written out here, not imported: the test is the contract, and a name the module drops fails it. const OAUTH_ANSWER = [ @@ -146,3 +155,531 @@ describe('PortalEvents', () => { } }); }); + +interface FakeScript { + async: boolean; + src: string; + textContent: string; +} + +interface FakeWindow { + location: { href: string }; + dataLayer?: unknown[]; + gtag?: (...command: unknown[]) => void; +} + +/** A page in the browser: the `window` and `document` the module reads, and the scripts the loader appends. */ +function browser(href: string, title = 'Quickstart | Acme API') { + const scripts: FakeScript[] = []; + const window: FakeWindow = { location: { href } }; + const document = { + title, + createElement: (): FakeScript => ({ async: false, src: '', textContent: '' }), + head: { append: (script: FakeScript) => scripts.push(script) } + }; + Object.assign(globalThis, { window, document }); + return { + window, + scripts, + dataLayer: () => window.dataLayer ?? [], + go: (next: string, nextTitle = title) => { + window.location.href = next; + document.title = nextTitle; + } + }; +} + +/** The router's `onRendered` subscription, fired by the test with `render()`. */ +function fakeRouter() { + let listener: (() => void) | null = null; + return { + subscribe: (_event: 'onRendered', next: () => void) => { + listener = next; + return () => { + listener = null; + }; + }, + render: () => listener?.() + }; +} + +const isArguments = (entry: unknown) => Object.prototype.toString.call(entry) === '[object Arguments]'; +const isPlainObject = (value: unknown): value is Record => + typeof value === 'object' && value !== null && !Array.isArray(value) && !isArguments(value); +const gtagCalls = (entries: unknown[]) => + entries.filter(isArguments).map((entry) => Array.from(entry as ArrayLike)); +const pageViews = (entries: unknown[]) => + entries.filter((entry) => isPlainObject(entry) && entry.event === 'docs_page_view'); +/** What the data layer reads as, once GTM has merged every push: objects recursively, `null` replacing. */ +function mergedLikeGtm(entries: unknown[]): Record { + const merge = (into: Record, from: Record): Record => { + for (const [key, value] of Object.entries(from)) { + const current = into[key]; + into[key] = isPlainObject(value) && isPlainObject(current) ? merge({ ...current }, value) : value; + } + return into; + }; + return entries.filter(isPlainObject).reduce(merge, {}); +} + +const none: PortalAnalytics = { googleTagManager: null, googleAnalytics: null, keepQueryParams: [] }; +const withGtm = (environment: { auth: string; preview: string } | null = null): PortalAnalytics => ({ + ...none, + googleTagManager: { containerId: 'GTM-ABC123', environment } +}); +const withGa4 = (debugMode = false): PortalAnalytics => ({ + ...none, + googleAnalytics: { measurementId: 'G-ABC123', debugMode } +}); +const withBoth: PortalAnalytics = { + ...none, + googleTagManager: withGtm().googleTagManager, + googleAnalytics: withGa4().googleAnalytics +}; +const GTM_SCRIPT = 'https://www.googletagmanager.com/gtm.js?id=GTM-ABC123'; +const GA4_SCRIPT = 'https://www.googletagmanager.com/gtag/js?id=G-ABC123'; + +describe('analyticsFor', () => { + const quickstart = 'https://docs.test/guides/quickstart'; + const quickstartView = { + event: 'docs_page_view', + docs: { page_title: 'Quickstart | Acme API', page_location: quickstart } + }; + const global = globalThis as { window?: unknown; document?: unknown }; + + afterEach(() => { + delete global.window; + delete global.document; + }); + + describe('with neither vendor set', () => { + it('pushes a reset entry and one clean page view entry, and nothing else', () => { + const page = browser(`${quickstart}?utm_source=newsletter&tab=python#install`); + const analytics = analyticsFor(none); + + analytics.startAnalytics(); + analytics.reportPageViews(fakeRouter()); + + expect(page.dataLayer()).to.deep.equal([ + { docs: null }, + { + event: 'docs_page_view', + docs: { page_title: 'Quickstart | Acme API', page_location: `${quickstart}?utm_source=newsletter` } + } + ]); + expect(page.window.gtag).to.be.undefined; + expect(page.scripts).to.be.empty; + }); + + it('writes to a data layer the page already has', () => { + const page = browser(quickstart); + const existing = { 'host-tag': true }; + page.window.dataLayer = [existing]; + const analytics = analyticsFor(none); + + analytics.startAnalytics(); + analytics.reportPageViews(fakeRouter()); + + expect(page.dataLayer()).to.deep.equal([existing, { docs: null }, quickstartView]); + }); + }); + + describe('with Google Tag Manager', () => { + it('pushes the gtm.start entry first, inserts gtm.js, then pushes the page view', () => { + const page = browser(quickstart); + const analytics = analyticsFor(withGtm()); + + analytics.startAnalytics(); + analytics.reportPageViews(fakeRouter()); + + const [start, reset, view, ...rest] = page.dataLayer(); + expect(start).to.have.property('event', 'gtm.js'); + expect(start).to.have.property('gtm.start').that.is.a('number'); + expect(reset).to.deep.equal({ docs: null }); + expect(view).to.deep.equal(quickstartView); + expect(rest).to.be.empty; + expect(page.scripts.map((script) => script.src)).to.deep.equal([GTM_SCRIPT]); + expect(page.scripts[0].async).to.be.true; + expect(page.window.gtag).to.be.undefined; + }); + + it("loads the container's environment when one is set", () => { + const page = browser(quickstart); + + analyticsFor(withGtm({ auth: 'abc123', preview: 'env-3' })).startAnalytics(); + + expect(page.scripts.map((script) => script.src)).to.deep.equal([ + `${GTM_SCRIPT}>m_auth=abc123>m_preview=env-3>m_cookies_win=x` + ]); + }); + }); + + describe('with Google Analytics', () => { + it('pushes js and config with its own page view off, and inserts gtag.js', () => { + const page = browser(quickstart); + + analyticsFor(withGa4()).startAnalytics(); + + const [js, config, ...rest] = gtagCalls(page.dataLayer()); + expect(js[0]).to.equal('js'); + expect(js[1]).to.be.an.instanceOf(Date); + expect(config).to.deep.equal(['config', 'G-ABC123', { send_page_view: false }]); + expect(rest).to.be.empty; + expect(page.scripts.map((script) => script.src)).to.deep.equal([GA4_SCRIPT]); + expect(page.window.gtag).to.be.a('function'); + }); + + it('sends each page view as page_view, without the prefix, after the reset and event entries', () => { + const page = browser(quickstart); + const analytics = analyticsFor(withGa4()); + + analytics.startAnalytics(); + analytics.reportPageViews(fakeRouter()); + + const entries = page.dataLayer(); + expect(entries).to.have.length(5); + expect(entries[2]).to.deep.equal({ docs: null }); + expect(entries[3]).to.deep.equal(quickstartView); + expect(gtagCalls([entries[4]])[0]).to.deep.equal(['event', 'page_view', quickstartView.docs]); + }); + + it('pushes Arguments objects, which gtag.js reads, never arrays of the same values', () => { + const page = browser(quickstart); + const analytics = analyticsFor(withGa4()); + + analytics.startAnalytics(); + analytics.reportPageViews(fakeRouter()); + + expect(page.dataLayer().filter(isArguments)).to.have.length(3); + expect(page.dataLayer().some(Array.isArray)).to.be.false; + }); + + it('marks events as debug traffic in a preview', () => { + const page = browser(quickstart); + + analyticsFor(withGa4(true)).startAnalytics(); + + expect(gtagCalls(page.dataLayer())[1]).to.deep.equal([ + 'config', + 'G-ABC123', + { send_page_view: false, debug_mode: true } + ]); + }); + + it('uses a gtag the page already defines, rather than replacing it', () => { + const page = browser(quickstart); + const calls: unknown[][] = []; + const existing = (...command: unknown[]) => { + calls.push(command); + }; + page.window.gtag = existing; + const analytics = analyticsFor(withGa4()); + + analytics.startAnalytics(); + analytics.reportPageViews(fakeRouter()); + + expect(page.window.gtag).to.equal(existing); + expect(calls.map((command) => command[0])).to.deep.equal(['js', 'config', 'event']); + expect(page.dataLayer().filter(isArguments)).to.be.empty; + }); + }); + + describe('with both vendors', () => { + it('pushes every setup entry once, gtm.start first, before the first event', () => { + const page = browser(quickstart); + const analytics = analyticsFor(withBoth); + + analytics.startAnalytics(); + analytics.reportPageViews(fakeRouter()); + + const entries = page.dataLayer(); + expect(entries).to.have.length(6); + expect(entries[0]).to.have.property('event', 'gtm.js'); + expect(gtagCalls(entries.slice(1, 3)).map((command) => command[0])).to.deep.equal(['js', 'config']); + expect(entries[3]).to.deep.equal({ docs: null }); + expect(entries[4]).to.deep.equal(quickstartView); + expect(gtagCalls([entries[5]])[0]).to.deep.equal(['event', 'page_view', quickstartView.docs]); + expect(page.scripts.map((script) => script.src)).to.deep.equal([GTM_SCRIPT, GA4_SCRIPT]); + }); + + it('starts once: a second start adds no entry and no script', () => { + const page = browser(quickstart); + const analytics = analyticsFor(withBoth); + + analytics.startAnalytics(); + analytics.startAnalytics(); + + expect(page.dataLayer()).to.have.length(3); + expect(page.scripts).to.have.length(2); + }); + }); + + // The wait for the playground to take the answer out of the address is the next step. + describe('while the address holds an OAuth answer', () => { + it('pushes the setup entries and inserts no script', () => { + const page = browser('https://docs.test/api/pets/listPets?code=abc&state=123'); + + analyticsFor(withBoth).startAnalytics(); + + expect(page.dataLayer()).to.have.length(3); + expect(page.scripts).to.be.empty; + }); + + it('still reports, with a clean page_location', () => { + const page = browser('https://docs.test/api/pets/listPets#access_token=xyz&state=123', 'List pets'); + const analytics = analyticsFor(withBoth); + + analytics.startAnalytics(); + analytics.reportPageViews(fakeRouter()); + + expect(pageViews(page.dataLayer())).to.deep.equal([ + { + event: 'docs_page_view', + docs: { page_title: 'List pets', page_location: 'https://docs.test/api/pets/listPets' } + } + ]); + }); + }); + + describe('on the OAuth callback', () => { + for (const href of [ + 'https://docs.test/oauth/callback?code=abc&state=123', + 'https://docs.test/oauth/callback/?code=abc&state=123', + 'https://docs.test/oauth/callback#access_token=xyz&state=123' + ]) { + it(`pushes the setup entries and no page view at ${href}`, () => { + const page = browser(href); + const analytics = analyticsFor(withBoth); + + analytics.startAnalytics(); + analytics.reportPageViews(fakeRouter()); + + expect(page.dataLayer()).to.have.length(3); + expect(pageViews(page.dataLayer())).to.be.empty; + expect(page.scripts).to.be.empty; + expect(analytics.events).to.be.empty; + }); + } + }); + + describe('every adapter', () => { + const suite: { + vendor: keyof typeof adapters; + settings: PortalAnalytics; + adapter: () => Adapter; + pageViewCall: (entries: unknown[]) => void; + }[] = [ + { + vendor: 'googleTagManager', + settings: withGtm(), + adapter: () => adapters.googleTagManager({ containerId: 'GTM-ABC123', environment: null }), + // The data layer entry is the call; GTM sends nothing of its own. + pageViewCall: (entries) => expect(entries.filter(isArguments)).to.be.empty + }, + { + vendor: 'googleAnalytics', + settings: withGa4(), + adapter: () => adapters.googleAnalytics({ measurementId: 'G-ABC123', debugMode: false }), + pageViewCall: (entries) => expect(gtagCalls(entries).at(-1)?.slice(0, 2)).to.deep.equal(['event', 'page_view']) + } + ]; + + it('is covered by this suite', () => { + expect(suite.map((row) => row.vendor)).to.have.members(Object.keys(adapters)); + }); + + for (const { vendor, settings, adapter, pageViewCall } of suite) { + describe(vendor, () => { + it("turns the vendor's own page view off in its setup", () => { + browser(quickstart); + const pushed: unknown[] = []; + + adapter().setup(pushed); + + expect(pushed).to.not.be.empty; + for (const entry of pushed) { + expect(entry).to.not.have.property('event', 'page_view'); + const [command, , options] = isArguments(entry) ? Array.from(entry as ArrayLike) : []; + if (command === 'config') expect(options).to.include({ send_page_view: false }); + } + }); + + it('maps docs_page_view to its page view call', () => { + const page = browser(quickstart); + const analytics = analyticsFor(settings); + + analytics.startAnalytics(); + analytics.reportPageViews(fakeRouter()); + + expect(pageViews(page.dataLayer())).to.have.length(1); + pageViewCall(page.dataLayer()); + }); + + it('receives nothing holding code=, token= or a # part from a report made with an OAuth answer in the address', () => { + const page = browser('https://docs.test/api/pets/listPets?code=x&state=y#access_token=z', 'List pets'); + const analytics = analyticsFor(settings); + + analytics.startAnalytics(); + analytics.report('docs_page_view', { page_title: 'List pets' }); + + const received = JSON.stringify( + page.dataLayer().map((entry) => (isArguments(entry) ? Array.from(entry as ArrayLike) : entry)) + ); + expect(received).to.include('https://docs.test/api/pets/listPets'); + expect(received).to.not.match(/code=|token=|#/); + }); + + it('turns on no session recording or input capture', () => { + const page = browser(quickstart); + const analytics = analyticsFor(settings); + + analytics.startAnalytics(); + analytics.reportPageViews(fakeRouter()); + + const everything = JSON.stringify([ + ...page.dataLayer().map((entry) => (isArguments(entry) ? Array.from(entry as ArrayLike) : entry)), + ...page.scripts.map((script) => script.src) + ]); + expect(everything).to.not.match(/record|capture|replay|heatmap/i); + }); + + it('inserts only https scripts, none inline', () => { + expect(adapter().scripts()).to.not.be.empty; + for (const src of adapter().scripts()) expect(src).to.match(/^https:\/\//); + const page = browser(quickstart); + + analyticsFor(settings).startAnalytics(); + + expect(page.scripts).to.not.be.empty; + for (const script of page.scripts) { + expect(script.src).to.match(/^https:\/\//); + expect(script.textContent).to.equal(''); + } + }); + }); + } + }); + + describe('report', () => { + it('pushes a reset entry right before every event entry, which holds event and docs only', () => { + const page = browser(quickstart); + const analytics = analyticsFor(none); + analytics.startAnalytics(); + + analytics.report('docs_page_view', { page_title: 'A' }); + analytics.report('docs_page_view', { page_title: 'B' }); + + const entries = page.dataLayer(); + expect(entries).to.have.length(4); + for (const index of [1, 3]) { + expect(entries[index - 1]).to.deep.equal({ docs: null }); + expect(Object.keys(entries[index] as object)).to.deep.equal(['event', 'docs']); + } + }); + + it("clears the previous event's details for a tag that reads the merged data layer", () => { + const page = browser(quickstart); + const analytics = analyticsFor(none); + analytics.startAnalytics(); + // PR 3's events differ in their keys; until one lands, an extra key on a page view stands in for that. + const withExtraKey = { page_title: 'A', language: 'python' }; + + analytics.report('docs_page_view', withExtraKey); + analytics.report('docs_page_view', { page_title: 'B' }); + + expect(mergedLikeGtm(page.dataLayer()).docs).to.deep.equal({ page_title: 'B', page_location: quickstart }); + const withoutResets = page.dataLayer().filter((entry) => !(isPlainObject(entry) && entry.docs === null)); + expect(mergedLikeGtm(withoutResets).docs).to.have.property('language', 'python'); + }); + + it('keeps each event, frozen, for replay', () => { + browser(quickstart); + const analytics = analyticsFor(none); + analytics.startAnalytics(); + const before = Date.now(); + + analytics.report('docs_page_view', { page_title: 'A' }); + analytics.report('docs_page_view', { page_title: 'B' }); + + expect(analytics.events).to.have.length(2); + const [first, second] = analytics.events; + expect(first).to.deep.equal({ + name: 'docs_page_view', + params: { page_title: 'A', page_location: quickstart }, + time: first.time, + version: 1 + }); + expect(first.time).to.be.at.least(before); + expect(second.params).to.include({ page_title: 'B' }); + expect(Object.isFrozen(first)).to.be.true; + expect(Object.isFrozen(first.params)).to.be.true; + }); + }); + + describe('reportPageViews', () => { + const components = 'https://docs.test/guides/components'; + + it('sends the first page at once, then one per onRendered, each with its own title', () => { + const page = browser(quickstart); + const router = fakeRouter(); + const analytics = analyticsFor(none); + analytics.startAnalytics(); + + analytics.reportPageViews(router); + page.go(components, 'Components | Acme API'); + router.render(); + + expect(pageViews(page.dataLayer())).to.deep.equal([ + quickstartView, + { event: 'docs_page_view', docs: { page_title: 'Components | Acme API', page_location: components } } + ]); + }); + + it('sends none when only the # part or the query changed', () => { + const page = browser(quickstart); + const router = fakeRouter(); + const analytics = analyticsFor(none); + analytics.startAnalytics(); + + analytics.reportPageViews(router); + page.go(`${quickstart}#install`); + router.render(); + page.go(`${quickstart}?tab=python`); + router.render(); + router.render(); + + expect(pageViews(page.dataLayer())).to.have.length(1); + }); + + it('sends three for A, then B, then A', () => { + const page = browser(quickstart); + const router = fakeRouter(); + const analytics = analyticsFor(none); + analytics.startAnalytics(); + + analytics.reportPageViews(router); + page.go(components); + router.render(); + page.go(quickstart); + router.render(); + + expect( + pageViews(page.dataLayer()).map((view) => (view as { docs: { page_location: string } }).docs.page_location) + ).to.deep.equal([quickstart, components, quickstart]); + }); + + it('stops when the function it returns is called', () => { + const page = browser(quickstart); + const router = fakeRouter(); + const analytics = analyticsFor(none); + analytics.startAnalytics(); + + const stop = analytics.reportPageViews(router); + stop(); + page.go(components); + router.render(); + + expect(pageViews(page.dataLayer())).to.have.length(1); + }); + }); +}); From b9312ebb4e1ec6dfb87e754f7c94405a36b96d44 Mon Sep 17 00:00:00 2001 From: Muhammad Sohail Date: Thu, 12 Nov 2026 09:13:45 +0500 Subject: [PATCH 04/73] feat(portal): hold vendor tags back while the address holds an OAuth answer Step 1.3 of .ai/plans/portal-analytics.md: insertWhenClean() checks every 100 ms for up to 5 seconds, inserts once the answer is gone, and leaves a page never cleaned to the next page change. Every analyticsFor() test now runs on a fake clock. Co-Authored-By: Claude Fable 5.1 --- portal-template/src/lib/analytics.ts | 30 ++++++++- test/portal-template/analytics.test.ts | 92 +++++++++++++++++++++++--- 2 files changed, 111 insertions(+), 11 deletions(-) diff --git a/portal-template/src/lib/analytics.ts b/portal-template/src/lib/analytics.ts index cd0ae4f7..3cacf716 100644 --- a/portal-template/src/lib/analytics.ts +++ b/portal-template/src/lib/analytics.ts @@ -2,6 +2,10 @@ import { withBasePath } from './base-path'; import { oauthCallbackPath } from './oauth-callback'; import type { PortalAnalytics } from './portal-types'; +/** 5 seconds in all: long enough for a slow page chunk to run the playground's effect that removes the answer. */ +const ANSWER_CHECKS = 50; +const ANSWER_CHECK_MS = 100; + /** Names the OAuth standard puts in an answer. While one is in the address, the loader inserts nothing. */ const OAUTH_ANSWER = [ 'code', @@ -134,6 +138,8 @@ export function analyticsFor(settings: PortalAnalytics) { if (settings.googleAnalytics) live.push(adapters.googleAnalytics(settings.googleAnalytics)); const events: PortalEvent[] = []; let set = false; + let inserted = false; + let waiting = false; let lastPageView: string | null = null; function startAnalytics(): void { @@ -141,10 +147,30 @@ export function analyticsFor(settings: PortalAnalytics) { set = true; const dataLayer = (window.dataLayer ??= []); for (const adapter of live) adapter.setup(dataLayer); - if (!holdsOAuthAnswer(window.location.href)) insert(); + insertWhenClean(); + } + + function insertWhenClean(): void { + if (inserted || waiting) return; + if (!holdsOAuthAnswer(window.location.href)) { + insert(); + return; + } + // The playground's effect that removes the answer can run after ours, and vendor tags read the address themselves. + waiting = true; + let checks = 0; + const timer = setInterval(() => { + const answered = holdsOAuthAnswer(window.location.href); + if (answered && ++checks < ANSWER_CHECKS) return; + // After the last check the next page change calls this again, so a page never cleaned loads nothing. + clearInterval(timer); + waiting = false; + if (!answered) insert(); + }, ANSWER_CHECK_MS); } function insert(): void { + inserted = true; for (const adapter of live) for (const src of adapter.scripts()) add(src); } @@ -173,7 +199,7 @@ export function analyticsFor(settings: PortalAnalytics) { return router.subscribe('onRendered', pageView); } - return { startAnalytics, report, reportPageViews, events }; + return { startAnalytics, insertWhenClean, report, reportPageViews, events }; } function add(src: string): void { diff --git a/test/portal-template/analytics.test.ts b/test/portal-template/analytics.test.ts index 49dc60fd..8f0c1530 100644 --- a/test/portal-template/analytics.test.ts +++ b/test/portal-template/analytics.test.ts @@ -1,4 +1,5 @@ import { expect } from 'chai'; +import sinon from 'sinon'; import { Adapter, adapters, @@ -246,8 +247,15 @@ describe('analyticsFor', () => { docs: { page_title: 'Quickstart | Acme API', page_location: quickstart } }; const global = globalThis as { window?: unknown; document?: unknown }; + let clock: sinon.SinonFakeTimers; + + // A start on an address with an OAuth answer leaves a timer, which must never fire for real once the fakes are gone. + beforeEach(() => { + clock = sinon.useFakeTimers(); + }); afterEach(() => { + clock.restore(); delete global.window; delete global.document; }); @@ -414,31 +422,97 @@ describe('analyticsFor', () => { }); }); - // The wait for the playground to take the answer out of the address is the next step. describe('while the address holds an OAuth answer', () => { - it('pushes the setup entries and inserts no script', () => { - const page = browser('https://docs.test/api/pets/listPets?code=abc&state=123'); + const listPets = 'https://docs.test/api/pets/listPets'; + const answered = `${listPets}?code=abc&state=123`; + + it('pushes the setup entries at once and inserts no script while the answer stays', () => { + const page = browser(answered); analyticsFor(withBoth).startAnalytics(); expect(page.dataLayer()).to.have.length(3); + clock.tick(100 * 10); expect(page.scripts).to.be.empty; }); - it('still reports, with a clean page_location', () => { - const page = browser('https://docs.test/api/pets/listPets#access_token=xyz&state=123', 'List pets'); + it('still reports meanwhile, at once, with a clean page_location', () => { + const page = browser(`${listPets}#access_token=xyz&state=123`, 'List pets'); const analytics = analyticsFor(withBoth); analytics.startAnalytics(); analytics.reportPageViews(fakeRouter()); expect(pageViews(page.dataLayer())).to.deep.equal([ - { - event: 'docs_page_view', - docs: { page_title: 'List pets', page_location: 'https://docs.test/api/pets/listPets' } - } + { event: 'docs_page_view', docs: { page_title: 'List pets', page_location: listPets } } ]); }); + + it('inserts at the next check once the playground has taken the answer out of the address', () => { + const page = browser(answered); + analyticsFor(withBoth).startAnalytics(); + + clock.tick(300); + page.go(listPets); + expect(page.scripts).to.be.empty; + clock.tick(100); + + expect(page.scripts.map((script) => script.src)).to.deep.equal([GTM_SCRIPT, GA4_SCRIPT]); + expect(clock.countTimers()).to.equal(0); + }); + + it('inserts at the next check after a page change while it waits', () => { + const page = browser(answered); + analyticsFor(withBoth).startAnalytics(); + + clock.tick(1000); + page.go(quickstart); + clock.tick(100); + + expect(page.scripts).to.have.length(2); + }); + + it('stops checking after 5 seconds, and a later call on a clean address inserts at once', () => { + const page = browser(answered); + const analytics = analyticsFor(withBoth); + analytics.startAnalytics(); + + clock.tick(100 * 50); + expect(page.scripts).to.be.empty; + expect(clock.countTimers()).to.equal(0); + page.go(listPets); + clock.tick(100 * 50); + expect(page.scripts).to.be.empty; + analytics.insertWhenClean(); + + expect(page.scripts).to.have.length(2); + expect(clock.countTimers()).to.equal(0); + }); + + it('starts no second timer for a call while it waits, and inserts once', () => { + const page = browser(answered); + const analytics = analyticsFor(withBoth); + analytics.startAnalytics(); + + analytics.insertWhenClean(); + analytics.insertWhenClean(); + expect(clock.countTimers()).to.equal(1); + page.go(listPets); + clock.tick(100); + + expect(page.scripts).to.have.length(2); + }); + + it('adds nothing on a call after the insert', () => { + const page = browser(listPets); + const analytics = analyticsFor(withBoth); + analytics.startAnalytics(); + + analytics.insertWhenClean(); + + expect(page.scripts).to.have.length(2); + expect(clock.countTimers()).to.equal(0); + }); }); describe('on the OAuth callback', () => { From 225978781946dae1931ea169b540984a2613cdb3 Mon Sep 17 00:00:00 2001 From: Muhammad Sohail Date: Thu, 12 Nov 2026 10:09:10 +0500 Subject: [PATCH 05/73] refactor(portal): drop the replay list until listed scripts can subscribe Nothing reads it before PR 2 adds window.apimatic.analytics.subscribe(), and the plan now builds top-down: nothing is written before the code that calls it. Co-Authored-By: Claude Fable 5.1 --- portal-template/src/lib/analytics.ts | 12 +----------- test/portal-template/analytics.test.ts | 24 ------------------------ 2 files changed, 1 insertion(+), 35 deletions(-) diff --git a/portal-template/src/lib/analytics.ts b/portal-template/src/lib/analytics.ts index 3cacf716..3ecc0b84 100644 --- a/portal-template/src/lib/analytics.ts +++ b/portal-template/src/lib/analytics.ts @@ -48,14 +48,6 @@ export interface PortalEvents { } export type PortalEventName = keyof PortalEvents; -export interface PortalEvent { - readonly name: PortalEventName; - readonly params: Readonly>; - readonly time: number; - /** Lets a later shape be told from this one. */ - readonly version: 1; -} - /** The reset entry, then the event entry with every detail under `docs`. */ export type DataLayerEntry = | { docs: null } @@ -136,7 +128,6 @@ export function analyticsFor(settings: PortalAnalytics) { const live: Adapter[] = []; if (settings.googleTagManager) live.push(adapters.googleTagManager(settings.googleTagManager)); if (settings.googleAnalytics) live.push(adapters.googleAnalytics(settings.googleAnalytics)); - const events: PortalEvent[] = []; let set = false; let inserted = false; let waiting = false; @@ -185,7 +176,6 @@ export function analyticsFor(settings: PortalAnalytics) { dataLayer.push(reset); dataLayer.push(entry); for (const adapter of live) adapter.send(name, all); - events.push(Object.freeze({ name, params: Object.freeze(all), time: Date.now(), version: 1 })); } function reportPageViews(router: { subscribe(event: 'onRendered', listener: () => void): () => void }): () => void { @@ -199,7 +189,7 @@ export function analyticsFor(settings: PortalAnalytics) { return router.subscribe('onRendered', pageView); } - return { startAnalytics, insertWhenClean, report, reportPageViews, events }; + return { startAnalytics, insertWhenClean, report, reportPageViews }; } function add(src: string): void { diff --git a/test/portal-template/analytics.test.ts b/test/portal-template/analytics.test.ts index 8f0c1530..6c1c97c9 100644 --- a/test/portal-template/analytics.test.ts +++ b/test/portal-template/analytics.test.ts @@ -531,7 +531,6 @@ describe('analyticsFor', () => { expect(page.dataLayer()).to.have.length(3); expect(pageViews(page.dataLayer())).to.be.empty; expect(page.scripts).to.be.empty; - expect(analytics.events).to.be.empty; }); } }); @@ -665,29 +664,6 @@ describe('analyticsFor', () => { const withoutResets = page.dataLayer().filter((entry) => !(isPlainObject(entry) && entry.docs === null)); expect(mergedLikeGtm(withoutResets).docs).to.have.property('language', 'python'); }); - - it('keeps each event, frozen, for replay', () => { - browser(quickstart); - const analytics = analyticsFor(none); - analytics.startAnalytics(); - const before = Date.now(); - - analytics.report('docs_page_view', { page_title: 'A' }); - analytics.report('docs_page_view', { page_title: 'B' }); - - expect(analytics.events).to.have.length(2); - const [first, second] = analytics.events; - expect(first).to.deep.equal({ - name: 'docs_page_view', - params: { page_title: 'A', page_location: quickstart }, - time: first.time, - version: 1 - }); - expect(first.time).to.be.at.least(before); - expect(second.params).to.include({ page_title: 'B' }); - expect(Object.isFrozen(first)).to.be.true; - expect(Object.isFrozen(first.params)).to.be.true; - }); }); describe('reportPageViews', () => { From b41a5ce84ab2366abb47f5628c574a32ccc4ddea Mon Sep 17 00:00:00 2001 From: Muhammad Sohail Date: Thu, 12 Nov 2026 10:09:10 +0500 Subject: [PATCH 06/73] feat(portal): start analytics from the portal bundle Step 1.4 of .ai/plans/portal-analytics.md, the browser entry point: the root route subscribes the loader to onRendered and reports page views; portal-analytics.ts builds the one instance from portal.analytics and starts it at module evaluation; the shared type and PortalIdentity carry analytics, written as the default until the parser lands. Co-Authored-By: Claude Fable 5.1 --- portal-template/src/lib/portal-analytics.ts | 8 ++++++++ portal-template/src/lib/portal-types.ts | 1 + portal-template/src/routes/__root.tsx | 14 +++++++++++++- src/types/portal/portal-config.ts | 9 ++++++++- test/types/portal/portal-config.test.ts | 6 ++++-- 5 files changed, 34 insertions(+), 4 deletions(-) create mode 100644 portal-template/src/lib/portal-analytics.ts diff --git a/portal-template/src/lib/portal-analytics.ts b/portal-template/src/lib/portal-analytics.ts new file mode 100644 index 00000000..00b6e852 --- /dev/null +++ b/portal-template/src/lib/portal-analytics.ts @@ -0,0 +1,8 @@ +import { analyticsFor } from './analytics'; +import { portal } from './portal'; + +const analytics = analyticsFor(portal.analytics); +// When the bundle starts, before React: setup entries first, then the loader. Never during prerendering. +if (typeof window !== 'undefined') analytics.startAnalytics(); + +export const { insertWhenClean, reportPageViews } = analytics; diff --git a/portal-template/src/lib/portal-types.ts b/portal-template/src/lib/portal-types.ts index 2c1a18b6..c9281010 100644 --- a/portal-template/src/lib/portal-types.ts +++ b/portal-template/src/lib/portal-types.ts @@ -51,4 +51,5 @@ export interface Portal { links: PortalLink[]; /** Whether each page offers to open itself in an external AI assistant. */ pageActions: boolean; + analytics: PortalAnalytics; } diff --git a/portal-template/src/routes/__root.tsx b/portal-template/src/routes/__root.tsx index ba8d973d..41c921de 100644 --- a/portal-template/src/routes/__root.tsx +++ b/portal-template/src/routes/__root.tsx @@ -1,5 +1,6 @@ -import { createRootRoute, HeadContent, Outlet, Scripts } from '@tanstack/react-router'; +import { createRootRoute, HeadContent, Outlet, Scripts, useRouter } from '@tanstack/react-router'; import { createServerFn } from '@tanstack/react-start'; +import { useEffect } from 'react'; import { staticFunctionMiddleware } from '@tanstack/start-static-server-functions'; import { source } from '@/lib/source.server'; import appCss from '@/styles/app.css?url'; @@ -7,6 +8,7 @@ import { RootProvider } from 'fumadocs-ui/provider/tanstack'; import SearchDialog from '@/components/search'; import { withBasePath } from '@/lib/base-path'; import { portal } from '@/lib/portal'; +import { insertWhenClean, reportPageViews } from '@/lib/portal-analytics'; // The sidebar tree is the same on every page. Loaded here, once, it is written to a single // cache file instead of being repeated in every page's own loader payload. @@ -47,6 +49,16 @@ export const Route = createRootRoute({ }); function RootComponent() { + const router = useRouter(); + useEffect(() => { + // A start that outwaited an OAuth answer runs on the next page change. + const stopInserting = router.subscribe('onRendered', insertWhenClean); + const stopPageViews = reportPageViews(router); + return () => { + stopInserting(); + stopPageViews(); + }; + }, [router]); return ( diff --git a/src/types/portal/portal-config.ts b/src/types/portal/portal-config.ts index 56cf2ce4..0263ab33 100644 --- a/src/types/portal/portal-config.ts +++ b/src/types/portal/portal-config.ts @@ -35,6 +35,12 @@ export interface PortalIdentity { links: PortalLink[]; /** Whether each page offers to open itself in an external AI assistant. */ pageActions: boolean; + /** Public values: they sit in every page's scripts. */ + analytics: { + googleTagManager: { containerId: string; environment: { auth: string; preview: string } | null } | null; + googleAnalytics: { measurementId: string; debugMode: boolean } | null; + keepQueryParams: string[]; + }; } const BLOCK = 'portal'; @@ -125,7 +131,8 @@ export class PortalConfig { favicon: favicon === null ? null : { url: favicon.portalPath(), type: favicon.imageType() }, colorMode: this.brand.mode(), links: this.navigation.headerLinks().map(portalLink), - pageActions: this.ai.offersPageActions() + pageActions: this.ai.offersPageActions(), + analytics: { googleTagManager: null, googleAnalytics: null, keepQueryParams: [] } }; } diff --git a/test/types/portal/portal-config.test.ts b/test/types/portal/portal-config.test.ts index 6f0e692f..859b923c 100644 --- a/test/types/portal/portal-config.test.ts +++ b/test/types/portal/portal-config.test.ts @@ -486,7 +486,8 @@ describe('PortalConfig', () => { { label: 'Status', url: 'https://status.example.com', external: true }, { label: 'Changelog', url: '/changelog', external: false } ], - pageActions: false + pageActions: false, + analytics: { googleTagManager: null, googleAnalytics: null, keepQueryParams: [] } }); }); @@ -499,7 +500,8 @@ describe('PortalConfig', () => { favicon: null, colorMode: 'both', links: [], - pageActions: true + pageActions: true, + analytics: { googleTagManager: null, googleAnalytics: null, keepQueryParams: [] } }); }); From ac5b70499218e4dd4be4d99968c16291a182417a Mon Sep 17 00:00:00 2001 From: Muhammad Sohail Date: Thu, 12 Nov 2026 10:29:37 +0500 Subject: [PATCH 07/73] refactor(portal): make the analytics instance a class with flat methods analyticsFor() and its inner functions become the Analytics class: start(), insertWhenClean(), report() and reportPageView(). The router subscription moves into the root effect, which already holds the router, and the one-use helpers are inlined. Co-Authored-By: Claude Fable 5.1 --- portal-template/src/lib/analytics.ts | 121 +++++++------ portal-template/src/lib/portal-analytics.ts | 8 +- portal-template/src/routes/__root.tsx | 15 +- test/portal-template/analytics.test.ts | 182 ++++++++------------ 4 files changed, 144 insertions(+), 182 deletions(-) diff --git a/portal-template/src/lib/analytics.ts b/portal-template/src/lib/analytics.ts index 3ecc0b84..76b4dd61 100644 --- a/portal-template/src/lib/analytics.ts +++ b/portal-template/src/lib/analytics.ts @@ -110,9 +110,11 @@ export function pageLocation(href: string, keep: readonly string[], base?: strin const url = new URL(href); // A static host may answer `/oauth/callback` at `/oauth/callback/` and keep the query. if (url.pathname.replace(/\/$/, '') === withBasePath(oauthCallbackPath, base)) return null; - const kept = (name: string) => - KEPT_PREFIXES.some((prefix) => name.startsWith(prefix)) || KEPT_NAMES.has(name) || keep.includes(name); - url.search = new URLSearchParams([...url.searchParams].filter(([name]) => kept(name))).toString(); + url.search = new URLSearchParams( + [...url.searchParams].filter( + ([name]) => KEPT_PREFIXES.some((prefix) => name.startsWith(prefix)) || KEPT_NAMES.has(name) || keep.includes(name) + ) + ).toString(); url.hash = ''; return url.href; } @@ -124,77 +126,70 @@ export function holdsOAuthAnswer(href: string): boolean { return OAUTH_ANSWER.some((name) => url.searchParams.has(name) || hash.has(name)); } -export function analyticsFor(settings: PortalAnalytics) { - const live: Adapter[] = []; - if (settings.googleTagManager) live.push(adapters.googleTagManager(settings.googleTagManager)); - if (settings.googleAnalytics) live.push(adapters.googleAnalytics(settings.googleAnalytics)); - let set = false; - let inserted = false; - let waiting = false; - let lastPageView: string | null = null; - - function startAnalytics(): void { - if (set) return; - set = true; +/** The one instance a portal runs: started when the bundle evaluates, reporting from the root effect and the components. */ +export class Analytics { + private readonly live: Adapter[] = []; + private started = false; + private inserted = false; + private waiting = false; + private lastPageView: string | null = null; + + public constructor(private readonly settings: PortalAnalytics) { + if (settings.googleTagManager) this.live.push(adapters.googleTagManager(settings.googleTagManager)); + if (settings.googleAnalytics) this.live.push(adapters.googleAnalytics(settings.googleAnalytics)); + } + + /** Once, when the bundle starts: the data layer, every vendor's setup entries, then the vendor tags. */ + public start(): void { + if (this.started) return; + this.started = true; const dataLayer = (window.dataLayer ??= []); - for (const adapter of live) adapter.setup(dataLayer); - insertWhenClean(); + for (const adapter of this.live) adapter.setup(dataLayer); + this.insertWhenClean(); } - function insertWhenClean(): void { - if (inserted || waiting) return; - if (!holdsOAuthAnswer(window.location.href)) { - insert(); + /** The vendor tags: at once on a clean address, else once the OAuth answer is out of it, within 5 seconds. */ + public insertWhenClean(): void { + if (this.inserted || this.waiting) return; + if (holdsOAuthAnswer(window.location.href)) { + // The playground's effect that removes the answer can run after ours, and vendor tags read the address themselves. + this.waiting = true; + let checks = 0; + const timer = setInterval(() => { + const answered = holdsOAuthAnswer(window.location.href); + if (answered && ++checks < ANSWER_CHECKS) return; + // After the last check the next page change calls this again, so a page never cleaned loads nothing. + clearInterval(timer); + this.waiting = false; + if (!answered) this.insertWhenClean(); + }, ANSWER_CHECK_MS); return; } - // The playground's effect that removes the answer can run after ours, and vendor tags read the address themselves. - waiting = true; - let checks = 0; - const timer = setInterval(() => { - const answered = holdsOAuthAnswer(window.location.href); - if (answered && ++checks < ANSWER_CHECKS) return; - // After the last check the next page change calls this again, so a page never cleaned loads nothing. - clearInterval(timer); - waiting = false; - if (!answered) insert(); - }, ANSWER_CHECK_MS); - } - - function insert(): void { - inserted = true; - for (const adapter of live) for (const src of adapter.scripts()) add(src); + this.inserted = true; + for (const src of this.live.flatMap((adapter) => adapter.scripts())) { + const script = document.createElement('script'); + script.async = true; + script.src = src; + document.head.append(script); + } } - function report(name: E, params: PortalEvents[E]): void { - const page_location = pageLocation(window.location.href, settings.keepQueryParams); + public report(name: E, params: PortalEvents[E]): void { + const page_location = pageLocation(window.location.href, this.settings.keepQueryParams); if (page_location === null) return; - const all = { ...params, page_location }; + const docs = { ...params, page_location }; const dataLayer = (window.dataLayer ??= []); // GTM keeps every key from earlier pushes and merges objects, so clear ours first: a shared GA4 tag never sends the last event's details. - const reset: DataLayerEntry = { docs: null }; - const entry: DataLayerEntry = { event: name, docs: all }; - dataLayer.push(reset); - dataLayer.push(entry); - for (const adapter of live) adapter.send(name, all); + dataLayer.push({ docs: null } satisfies DataLayerEntry); + dataLayer.push({ event: name, docs } satisfies DataLayerEntry); + for (const adapter of this.live) adapter.send(name, docs); } - function reportPageViews(router: { subscribe(event: 'onRendered', listener: () => void): () => void }): () => void { - const pageView = () => { - const page = pageLocation(window.location.href, settings.keepQueryParams); - if (page === null || page === lastPageView) return; - lastPageView = page; - report('docs_page_view', { page_title: document.title }); - }; - pageView(); - return router.subscribe('onRendered', pageView); + /** `docs_page_view` for the current page, unless its cleaned address is the one last reported: a `#` jump sends none. */ + public reportPageView(): void { + const page = pageLocation(window.location.href, this.settings.keepQueryParams); + if (page === null || page === this.lastPageView) return; + this.lastPageView = page; + this.report('docs_page_view', { page_title: document.title }); } - - return { startAnalytics, insertWhenClean, report, reportPageViews }; -} - -function add(src: string): void { - const script = document.createElement('script'); - script.async = true; - script.src = src; - document.head.append(script); } diff --git a/portal-template/src/lib/portal-analytics.ts b/portal-template/src/lib/portal-analytics.ts index 00b6e852..f3e2b126 100644 --- a/portal-template/src/lib/portal-analytics.ts +++ b/portal-template/src/lib/portal-analytics.ts @@ -1,8 +1,6 @@ -import { analyticsFor } from './analytics'; +import { Analytics } from './analytics'; import { portal } from './portal'; -const analytics = analyticsFor(portal.analytics); +export const analytics = new Analytics(portal.analytics); // When the bundle starts, before React: setup entries first, then the loader. Never during prerendering. -if (typeof window !== 'undefined') analytics.startAnalytics(); - -export const { insertWhenClean, reportPageViews } = analytics; +if (typeof window !== 'undefined') analytics.start(); diff --git a/portal-template/src/routes/__root.tsx b/portal-template/src/routes/__root.tsx index 41c921de..bee0574a 100644 --- a/portal-template/src/routes/__root.tsx +++ b/portal-template/src/routes/__root.tsx @@ -8,7 +8,7 @@ import { RootProvider } from 'fumadocs-ui/provider/tanstack'; import SearchDialog from '@/components/search'; import { withBasePath } from '@/lib/base-path'; import { portal } from '@/lib/portal'; -import { insertWhenClean, reportPageViews } from '@/lib/portal-analytics'; +import { analytics } from '@/lib/portal-analytics'; // The sidebar tree is the same on every page. Loaded here, once, it is written to a single // cache file instead of being repeated in every page's own loader payload. @@ -51,13 +51,12 @@ export const Route = createRootRoute({ function RootComponent() { const router = useRouter(); useEffect(() => { - // A start that outwaited an OAuth answer runs on the next page change. - const stopInserting = router.subscribe('onRendered', insertWhenClean); - const stopPageViews = reportPageViews(router); - return () => { - stopInserting(); - stopPageViews(); - }; + analytics.reportPageView(); + // Each page change: a start that outwaited an OAuth answer, then the new page's view. + return router.subscribe('onRendered', () => { + analytics.insertWhenClean(); + analytics.reportPageView(); + }); }, [router]); return ( diff --git a/test/portal-template/analytics.test.ts b/test/portal-template/analytics.test.ts index 6c1c97c9..44698a1c 100644 --- a/test/portal-template/analytics.test.ts +++ b/test/portal-template/analytics.test.ts @@ -3,7 +3,7 @@ import sinon from 'sinon'; import { Adapter, adapters, - analyticsFor, + Analytics, holdsOAuthAnswer, pageLocation, PortalEventName, @@ -190,20 +190,6 @@ function browser(href: string, title = 'Quickstart | Acme API') { }; } -/** The router's `onRendered` subscription, fired by the test with `render()`. */ -function fakeRouter() { - let listener: (() => void) | null = null; - return { - subscribe: (_event: 'onRendered', next: () => void) => { - listener = next; - return () => { - listener = null; - }; - }, - render: () => listener?.() - }; -} - const isArguments = (entry: unknown) => Object.prototype.toString.call(entry) === '[object Arguments]'; const isPlainObject = (value: unknown): value is Record => typeof value === 'object' && value !== null && !Array.isArray(value) && !isArguments(value); @@ -240,7 +226,7 @@ const withBoth: PortalAnalytics = { const GTM_SCRIPT = 'https://www.googletagmanager.com/gtm.js?id=GTM-ABC123'; const GA4_SCRIPT = 'https://www.googletagmanager.com/gtag/js?id=G-ABC123'; -describe('analyticsFor', () => { +describe('Analytics', () => { const quickstart = 'https://docs.test/guides/quickstart'; const quickstartView = { event: 'docs_page_view', @@ -263,10 +249,10 @@ describe('analyticsFor', () => { describe('with neither vendor set', () => { it('pushes a reset entry and one clean page view entry, and nothing else', () => { const page = browser(`${quickstart}?utm_source=newsletter&tab=python#install`); - const analytics = analyticsFor(none); + const analytics = new Analytics(none); - analytics.startAnalytics(); - analytics.reportPageViews(fakeRouter()); + analytics.start(); + analytics.reportPageView(); expect(page.dataLayer()).to.deep.equal([ { docs: null }, @@ -283,10 +269,10 @@ describe('analyticsFor', () => { const page = browser(quickstart); const existing = { 'host-tag': true }; page.window.dataLayer = [existing]; - const analytics = analyticsFor(none); + const analytics = new Analytics(none); - analytics.startAnalytics(); - analytics.reportPageViews(fakeRouter()); + analytics.start(); + analytics.reportPageView(); expect(page.dataLayer()).to.deep.equal([existing, { docs: null }, quickstartView]); }); @@ -295,10 +281,10 @@ describe('analyticsFor', () => { describe('with Google Tag Manager', () => { it('pushes the gtm.start entry first, inserts gtm.js, then pushes the page view', () => { const page = browser(quickstart); - const analytics = analyticsFor(withGtm()); + const analytics = new Analytics(withGtm()); - analytics.startAnalytics(); - analytics.reportPageViews(fakeRouter()); + analytics.start(); + analytics.reportPageView(); const [start, reset, view, ...rest] = page.dataLayer(); expect(start).to.have.property('event', 'gtm.js'); @@ -314,7 +300,7 @@ describe('analyticsFor', () => { it("loads the container's environment when one is set", () => { const page = browser(quickstart); - analyticsFor(withGtm({ auth: 'abc123', preview: 'env-3' })).startAnalytics(); + new Analytics(withGtm({ auth: 'abc123', preview: 'env-3' })).start(); expect(page.scripts.map((script) => script.src)).to.deep.equal([ `${GTM_SCRIPT}>m_auth=abc123>m_preview=env-3>m_cookies_win=x` @@ -326,7 +312,7 @@ describe('analyticsFor', () => { it('pushes js and config with its own page view off, and inserts gtag.js', () => { const page = browser(quickstart); - analyticsFor(withGa4()).startAnalytics(); + new Analytics(withGa4()).start(); const [js, config, ...rest] = gtagCalls(page.dataLayer()); expect(js[0]).to.equal('js'); @@ -339,10 +325,10 @@ describe('analyticsFor', () => { it('sends each page view as page_view, without the prefix, after the reset and event entries', () => { const page = browser(quickstart); - const analytics = analyticsFor(withGa4()); + const analytics = new Analytics(withGa4()); - analytics.startAnalytics(); - analytics.reportPageViews(fakeRouter()); + analytics.start(); + analytics.reportPageView(); const entries = page.dataLayer(); expect(entries).to.have.length(5); @@ -353,10 +339,10 @@ describe('analyticsFor', () => { it('pushes Arguments objects, which gtag.js reads, never arrays of the same values', () => { const page = browser(quickstart); - const analytics = analyticsFor(withGa4()); + const analytics = new Analytics(withGa4()); - analytics.startAnalytics(); - analytics.reportPageViews(fakeRouter()); + analytics.start(); + analytics.reportPageView(); expect(page.dataLayer().filter(isArguments)).to.have.length(3); expect(page.dataLayer().some(Array.isArray)).to.be.false; @@ -365,7 +351,7 @@ describe('analyticsFor', () => { it('marks events as debug traffic in a preview', () => { const page = browser(quickstart); - analyticsFor(withGa4(true)).startAnalytics(); + new Analytics(withGa4(true)).start(); expect(gtagCalls(page.dataLayer())[1]).to.deep.equal([ 'config', @@ -381,10 +367,10 @@ describe('analyticsFor', () => { calls.push(command); }; page.window.gtag = existing; - const analytics = analyticsFor(withGa4()); + const analytics = new Analytics(withGa4()); - analytics.startAnalytics(); - analytics.reportPageViews(fakeRouter()); + analytics.start(); + analytics.reportPageView(); expect(page.window.gtag).to.equal(existing); expect(calls.map((command) => command[0])).to.deep.equal(['js', 'config', 'event']); @@ -395,10 +381,10 @@ describe('analyticsFor', () => { describe('with both vendors', () => { it('pushes every setup entry once, gtm.start first, before the first event', () => { const page = browser(quickstart); - const analytics = analyticsFor(withBoth); + const analytics = new Analytics(withBoth); - analytics.startAnalytics(); - analytics.reportPageViews(fakeRouter()); + analytics.start(); + analytics.reportPageView(); const entries = page.dataLayer(); expect(entries).to.have.length(6); @@ -412,10 +398,10 @@ describe('analyticsFor', () => { it('starts once: a second start adds no entry and no script', () => { const page = browser(quickstart); - const analytics = analyticsFor(withBoth); + const analytics = new Analytics(withBoth); - analytics.startAnalytics(); - analytics.startAnalytics(); + analytics.start(); + analytics.start(); expect(page.dataLayer()).to.have.length(3); expect(page.scripts).to.have.length(2); @@ -429,7 +415,7 @@ describe('analyticsFor', () => { it('pushes the setup entries at once and inserts no script while the answer stays', () => { const page = browser(answered); - analyticsFor(withBoth).startAnalytics(); + new Analytics(withBoth).start(); expect(page.dataLayer()).to.have.length(3); clock.tick(100 * 10); @@ -438,10 +424,10 @@ describe('analyticsFor', () => { it('still reports meanwhile, at once, with a clean page_location', () => { const page = browser(`${listPets}#access_token=xyz&state=123`, 'List pets'); - const analytics = analyticsFor(withBoth); + const analytics = new Analytics(withBoth); - analytics.startAnalytics(); - analytics.reportPageViews(fakeRouter()); + analytics.start(); + analytics.reportPageView(); expect(pageViews(page.dataLayer())).to.deep.equal([ { event: 'docs_page_view', docs: { page_title: 'List pets', page_location: listPets } } @@ -450,7 +436,7 @@ describe('analyticsFor', () => { it('inserts at the next check once the playground has taken the answer out of the address', () => { const page = browser(answered); - analyticsFor(withBoth).startAnalytics(); + new Analytics(withBoth).start(); clock.tick(300); page.go(listPets); @@ -463,7 +449,7 @@ describe('analyticsFor', () => { it('inserts at the next check after a page change while it waits', () => { const page = browser(answered); - analyticsFor(withBoth).startAnalytics(); + new Analytics(withBoth).start(); clock.tick(1000); page.go(quickstart); @@ -474,8 +460,8 @@ describe('analyticsFor', () => { it('stops checking after 5 seconds, and a later call on a clean address inserts at once', () => { const page = browser(answered); - const analytics = analyticsFor(withBoth); - analytics.startAnalytics(); + const analytics = new Analytics(withBoth); + analytics.start(); clock.tick(100 * 50); expect(page.scripts).to.be.empty; @@ -491,8 +477,8 @@ describe('analyticsFor', () => { it('starts no second timer for a call while it waits, and inserts once', () => { const page = browser(answered); - const analytics = analyticsFor(withBoth); - analytics.startAnalytics(); + const analytics = new Analytics(withBoth); + analytics.start(); analytics.insertWhenClean(); analytics.insertWhenClean(); @@ -505,8 +491,8 @@ describe('analyticsFor', () => { it('adds nothing on a call after the insert', () => { const page = browser(listPets); - const analytics = analyticsFor(withBoth); - analytics.startAnalytics(); + const analytics = new Analytics(withBoth); + analytics.start(); analytics.insertWhenClean(); @@ -523,10 +509,10 @@ describe('analyticsFor', () => { ]) { it(`pushes the setup entries and no page view at ${href}`, () => { const page = browser(href); - const analytics = analyticsFor(withBoth); + const analytics = new Analytics(withBoth); - analytics.startAnalytics(); - analytics.reportPageViews(fakeRouter()); + analytics.start(); + analytics.reportPageView(); expect(page.dataLayer()).to.have.length(3); expect(pageViews(page.dataLayer())).to.be.empty; @@ -579,10 +565,10 @@ describe('analyticsFor', () => { it('maps docs_page_view to its page view call', () => { const page = browser(quickstart); - const analytics = analyticsFor(settings); + const analytics = new Analytics(settings); - analytics.startAnalytics(); - analytics.reportPageViews(fakeRouter()); + analytics.start(); + analytics.reportPageView(); expect(pageViews(page.dataLayer())).to.have.length(1); pageViewCall(page.dataLayer()); @@ -590,9 +576,9 @@ describe('analyticsFor', () => { it('receives nothing holding code=, token= or a # part from a report made with an OAuth answer in the address', () => { const page = browser('https://docs.test/api/pets/listPets?code=x&state=y#access_token=z', 'List pets'); - const analytics = analyticsFor(settings); + const analytics = new Analytics(settings); - analytics.startAnalytics(); + analytics.start(); analytics.report('docs_page_view', { page_title: 'List pets' }); const received = JSON.stringify( @@ -604,10 +590,10 @@ describe('analyticsFor', () => { it('turns on no session recording or input capture', () => { const page = browser(quickstart); - const analytics = analyticsFor(settings); + const analytics = new Analytics(settings); - analytics.startAnalytics(); - analytics.reportPageViews(fakeRouter()); + analytics.start(); + analytics.reportPageView(); const everything = JSON.stringify([ ...page.dataLayer().map((entry) => (isArguments(entry) ? Array.from(entry as ArrayLike) : entry)), @@ -621,7 +607,7 @@ describe('analyticsFor', () => { for (const src of adapter().scripts()) expect(src).to.match(/^https:\/\//); const page = browser(quickstart); - analyticsFor(settings).startAnalytics(); + new Analytics(settings).start(); expect(page.scripts).to.not.be.empty; for (const script of page.scripts) { @@ -636,8 +622,8 @@ describe('analyticsFor', () => { describe('report', () => { it('pushes a reset entry right before every event entry, which holds event and docs only', () => { const page = browser(quickstart); - const analytics = analyticsFor(none); - analytics.startAnalytics(); + const analytics = new Analytics(none); + analytics.start(); analytics.report('docs_page_view', { page_title: 'A' }); analytics.report('docs_page_view', { page_title: 'B' }); @@ -652,8 +638,8 @@ describe('analyticsFor', () => { it("clears the previous event's details for a tag that reads the merged data layer", () => { const page = browser(quickstart); - const analytics = analyticsFor(none); - analytics.startAnalytics(); + const analytics = new Analytics(none); + analytics.start(); // PR 3's events differ in their keys; until one lands, an extra key on a page view stands in for that. const withExtraKey = { page_title: 'A', language: 'python' }; @@ -666,18 +652,18 @@ describe('analyticsFor', () => { }); }); - describe('reportPageViews', () => { + // The root effect calls this once on mount and once per page change the router renders. + describe('reportPageView', () => { const components = 'https://docs.test/guides/components'; - it('sends the first page at once, then one per onRendered, each with its own title', () => { + it('sends the current page, each with its own title', () => { const page = browser(quickstart); - const router = fakeRouter(); - const analytics = analyticsFor(none); - analytics.startAnalytics(); + const analytics = new Analytics(none); + analytics.start(); - analytics.reportPageViews(router); + analytics.reportPageView(); page.go(components, 'Components | Acme API'); - router.render(); + analytics.reportPageView(); expect(pageViews(page.dataLayer())).to.deep.equal([ quickstartView, @@ -685,51 +671,35 @@ describe('analyticsFor', () => { ]); }); - it('sends none when only the # part or the query changed', () => { + it('sends none when only the # part or the query changed, or nothing changed', () => { const page = browser(quickstart); - const router = fakeRouter(); - const analytics = analyticsFor(none); - analytics.startAnalytics(); + const analytics = new Analytics(none); + analytics.start(); - analytics.reportPageViews(router); + analytics.reportPageView(); page.go(`${quickstart}#install`); - router.render(); + analytics.reportPageView(); page.go(`${quickstart}?tab=python`); - router.render(); - router.render(); + analytics.reportPageView(); + analytics.reportPageView(); expect(pageViews(page.dataLayer())).to.have.length(1); }); it('sends three for A, then B, then A', () => { const page = browser(quickstart); - const router = fakeRouter(); - const analytics = analyticsFor(none); - analytics.startAnalytics(); + const analytics = new Analytics(none); + analytics.start(); - analytics.reportPageViews(router); + analytics.reportPageView(); page.go(components); - router.render(); + analytics.reportPageView(); page.go(quickstart); - router.render(); + analytics.reportPageView(); expect( pageViews(page.dataLayer()).map((view) => (view as { docs: { page_location: string } }).docs.page_location) ).to.deep.equal([quickstart, components, quickstart]); }); - - it('stops when the function it returns is called', () => { - const page = browser(quickstart); - const router = fakeRouter(); - const analytics = analyticsFor(none); - analytics.startAnalytics(); - - const stop = analytics.reportPageViews(router); - stop(); - page.go(components); - router.render(); - - expect(pageViews(page.dataLayer())).to.have.length(1); - }); }); }); From 7541922716707f4167a4585c7d9c6f7257181f18 Mon Sep 17 00:00:00 2001 From: Muhammad Sohail Date: Thu, 12 Nov 2026 11:02:53 +0500 Subject: [PATCH 08/73] refactor(portal): load vendor tags as soon as the bundle starts Removes the wait while the address holds an OAuth answer (step 1.3, 1c616d56): holdsOAuthAnswer(), the nine-name list, the timing constants and insertWhenClean(). start() appends the vendor tags directly and the root reports page views only. fuma-nama/fumadocs#3809 is the PR's merge prerequisite instead; until it ships, a Google tag can read the answer after a playground sign-in. Co-Authored-By: Claude Fable 5.1 --- portal-template/src/lib/analytics.ts | 47 -------- portal-template/src/routes/__root.tsx | 6 +- test/portal-template/analytics.test.ts | 145 ++----------------------- 3 files changed, 9 insertions(+), 189 deletions(-) diff --git a/portal-template/src/lib/analytics.ts b/portal-template/src/lib/analytics.ts index 76b4dd61..924955bc 100644 --- a/portal-template/src/lib/analytics.ts +++ b/portal-template/src/lib/analytics.ts @@ -2,23 +2,6 @@ import { withBasePath } from './base-path'; import { oauthCallbackPath } from './oauth-callback'; import type { PortalAnalytics } from './portal-types'; -/** 5 seconds in all: long enough for a slow page chunk to run the playground's effect that removes the answer. */ -const ANSWER_CHECKS = 50; -const ANSWER_CHECK_MS = 100; - -/** Names the OAuth standard puts in an answer. While one is in the address, the loader inserts nothing. */ -const OAUTH_ANSWER = [ - 'code', - 'state', - 'access_token', - 'id_token', - 'token_type', - 'expires_in', - 'error', - 'session_state', - 'iss' -]; - /** Query parameters a reported address keeps: campaign, ad-click and cross-domain tags, which attribution reads from the address. */ const KEPT_PREFIXES = ['utm_', 'hsa_']; const KEPT_NAMES = new Set([ @@ -119,19 +102,10 @@ export function pageLocation(href: string, keep: readonly string[], base?: strin return url.href; } -/** True while the query or the `#` part holds a name the OAuth standard puts in an answer. */ -export function holdsOAuthAnswer(href: string): boolean { - const url = new URL(href); - const hash = new URLSearchParams(url.hash.slice(1)); - return OAUTH_ANSWER.some((name) => url.searchParams.has(name) || hash.has(name)); -} - /** The one instance a portal runs: started when the bundle evaluates, reporting from the root effect and the components. */ export class Analytics { private readonly live: Adapter[] = []; private started = false; - private inserted = false; - private waiting = false; private lastPageView: string | null = null; public constructor(private readonly settings: PortalAnalytics) { @@ -145,27 +119,6 @@ export class Analytics { this.started = true; const dataLayer = (window.dataLayer ??= []); for (const adapter of this.live) adapter.setup(dataLayer); - this.insertWhenClean(); - } - - /** The vendor tags: at once on a clean address, else once the OAuth answer is out of it, within 5 seconds. */ - public insertWhenClean(): void { - if (this.inserted || this.waiting) return; - if (holdsOAuthAnswer(window.location.href)) { - // The playground's effect that removes the answer can run after ours, and vendor tags read the address themselves. - this.waiting = true; - let checks = 0; - const timer = setInterval(() => { - const answered = holdsOAuthAnswer(window.location.href); - if (answered && ++checks < ANSWER_CHECKS) return; - // After the last check the next page change calls this again, so a page never cleaned loads nothing. - clearInterval(timer); - this.waiting = false; - if (!answered) this.insertWhenClean(); - }, ANSWER_CHECK_MS); - return; - } - this.inserted = true; for (const src of this.live.flatMap((adapter) => adapter.scripts())) { const script = document.createElement('script'); script.async = true; diff --git a/portal-template/src/routes/__root.tsx b/portal-template/src/routes/__root.tsx index bee0574a..1455548e 100644 --- a/portal-template/src/routes/__root.tsx +++ b/portal-template/src/routes/__root.tsx @@ -52,11 +52,7 @@ function RootComponent() { const router = useRouter(); useEffect(() => { analytics.reportPageView(); - // Each page change: a start that outwaited an OAuth answer, then the new page's view. - return router.subscribe('onRendered', () => { - analytics.insertWhenClean(); - analytics.reportPageView(); - }); + return router.subscribe('onRendered', () => analytics.reportPageView()); }, [router]); return ( diff --git a/test/portal-template/analytics.test.ts b/test/portal-template/analytics.test.ts index 44698a1c..422c1de4 100644 --- a/test/portal-template/analytics.test.ts +++ b/test/portal-template/analytics.test.ts @@ -1,28 +1,15 @@ import { expect } from 'chai'; -import sinon from 'sinon'; import { Adapter, adapters, Analytics, - holdsOAuthAnswer, pageLocation, PortalEventName, PortalEvents } from '../../portal-template/src/lib/analytics'; import type { PortalAnalytics } from '../../portal-template/src/lib/portal-types'; -// The lists are written out here, not imported: the test is the contract, and a name the module drops fails it. -const OAUTH_ANSWER = [ - 'code', - 'state', - 'access_token', - 'id_token', - 'token_type', - 'expires_in', - 'error', - 'session_state', - 'iss' -]; +// The list is written out here, not imported: the test is the contract, and a name the module drops fails it. const KEPT_NAMES = [ '_gl', 'gclid', @@ -104,38 +91,6 @@ describe('pageLocation', () => { }); }); -describe('holdsOAuthAnswer', () => { - const page = 'https://docs.test/api/pets/listPets'; - - it('is true for each OAuth answer name on its own, in the query', () => { - for (const name of OAUTH_ANSWER) { - expect(holdsOAuthAnswer(`${page}?${name}=x`), name).to.be.true; - } - }); - - it('is true for each OAuth answer name on its own, after the #', () => { - for (const name of OAUTH_ANSWER) { - expect(holdsOAuthAnswer(`${page}#${name}=x`), name).to.be.true; - } - }); - - it('is true with the answer beside other parameters', () => { - expect(holdsOAuthAnswer(`${page}?utm_source=newsletter&code=abc&state=123`)).to.be.true; - expect(holdsOAuthAnswer(`${page}?tab=python#access_token=xyz&state=123`)).to.be.true; - }); - - it("is false for a campaign tag or a name of the customer's own", () => { - expect(holdsOAuthAnswer(`${page}?utm_source=newsletter`)).to.be.false; - expect(holdsOAuthAnswer(`${page}?campaign_id=7`)).to.be.false; - expect(holdsOAuthAnswer(`${page}#campaign_id=7`)).to.be.false; - }); - - it('is false for a clean address', () => { - expect(holdsOAuthAnswer(page)).to.be.false; - expect(holdsOAuthAnswer(`${page}#install`)).to.be.false; - }); -}); - describe('PortalEvents', () => { // The compiler holds this table to the interface: a missing event, a missing key or an extra key does not compile. const events: { [E in PortalEventName]: Record } = { @@ -233,15 +188,8 @@ describe('Analytics', () => { docs: { page_title: 'Quickstart | Acme API', page_location: quickstart } }; const global = globalThis as { window?: unknown; document?: unknown }; - let clock: sinon.SinonFakeTimers; - - // A start on an address with an OAuth answer leaves a timer, which must never fire for real once the fakes are gone. - beforeEach(() => { - clock = sinon.useFakeTimers(); - }); afterEach(() => { - clock.restore(); delete global.window; delete global.document; }); @@ -408,97 +356,21 @@ describe('Analytics', () => { }); }); - describe('while the address holds an OAuth answer', () => { - const listPets = 'https://docs.test/api/pets/listPets'; - const answered = `${listPets}?code=abc&state=123`; - - it('pushes the setup entries at once and inserts no script while the answer stays', () => { - const page = browser(answered); - - new Analytics(withBoth).start(); - - expect(page.dataLayer()).to.have.length(3); - clock.tick(100 * 10); - expect(page.scripts).to.be.empty; - }); - - it('still reports meanwhile, at once, with a clean page_location', () => { - const page = browser(`${listPets}#access_token=xyz&state=123`, 'List pets'); + describe('after a playground sign-in', () => { + it('reports with the OAuth answer stripped from page_location', () => { + const page = browser('https://docs.test/api/pets/listPets#access_token=xyz&state=123', 'List pets'); const analytics = new Analytics(withBoth); analytics.start(); analytics.reportPageView(); expect(pageViews(page.dataLayer())).to.deep.equal([ - { event: 'docs_page_view', docs: { page_title: 'List pets', page_location: listPets } } + { + event: 'docs_page_view', + docs: { page_title: 'List pets', page_location: 'https://docs.test/api/pets/listPets' } + } ]); }); - - it('inserts at the next check once the playground has taken the answer out of the address', () => { - const page = browser(answered); - new Analytics(withBoth).start(); - - clock.tick(300); - page.go(listPets); - expect(page.scripts).to.be.empty; - clock.tick(100); - - expect(page.scripts.map((script) => script.src)).to.deep.equal([GTM_SCRIPT, GA4_SCRIPT]); - expect(clock.countTimers()).to.equal(0); - }); - - it('inserts at the next check after a page change while it waits', () => { - const page = browser(answered); - new Analytics(withBoth).start(); - - clock.tick(1000); - page.go(quickstart); - clock.tick(100); - - expect(page.scripts).to.have.length(2); - }); - - it('stops checking after 5 seconds, and a later call on a clean address inserts at once', () => { - const page = browser(answered); - const analytics = new Analytics(withBoth); - analytics.start(); - - clock.tick(100 * 50); - expect(page.scripts).to.be.empty; - expect(clock.countTimers()).to.equal(0); - page.go(listPets); - clock.tick(100 * 50); - expect(page.scripts).to.be.empty; - analytics.insertWhenClean(); - - expect(page.scripts).to.have.length(2); - expect(clock.countTimers()).to.equal(0); - }); - - it('starts no second timer for a call while it waits, and inserts once', () => { - const page = browser(answered); - const analytics = new Analytics(withBoth); - analytics.start(); - - analytics.insertWhenClean(); - analytics.insertWhenClean(); - expect(clock.countTimers()).to.equal(1); - page.go(listPets); - clock.tick(100); - - expect(page.scripts).to.have.length(2); - }); - - it('adds nothing on a call after the insert', () => { - const page = browser(listPets); - const analytics = new Analytics(withBoth); - analytics.start(); - - analytics.insertWhenClean(); - - expect(page.scripts).to.have.length(2); - expect(clock.countTimers()).to.equal(0); - }); }); describe('on the OAuth callback', () => { @@ -516,7 +388,6 @@ describe('Analytics', () => { expect(page.dataLayer()).to.have.length(3); expect(pageViews(page.dataLayer())).to.be.empty; - expect(page.scripts).to.be.empty; }); } }); From b744687f29271d19585a78a4dee733db889d34bb Mon Sep 17 00:00:00 2001 From: Muhammad Sohail Date: Thu, 12 Nov 2026 11:21:20 +0500 Subject: [PATCH 09/73] feat(portal): add the site verification meta and keep the playground out of replays The root route's head() writes Google's site verification meta when the identity file holds a value. The identity file gains `seo`, written as null until the config parser reads it. The API page wraps the playground in one element carrying the opt-out markers of the session replay tools a GTM tag may load (PostHog, FullStory, rrweb, Amplitude, Hotjar, Clarity, LogRocket), so a replay records the rest of the page and leaves the playground's inputs blank. The playground client is lazy-loaded from Fumadocs' public export, as Fumadocs itself loads it. Co-Authored-By: Claude Fable 5.1 --- portal-template/src/components/api-page.tsx | 20 ++++++++++++++++++++ portal-template/src/lib/portal-types.ts | 6 ++++++ portal-template/src/routes/__root.tsx | 5 ++++- src/types/portal/portal-config.ts | 7 ++++++- test/types/portal/portal-config.test.ts | 6 ++++-- 5 files changed, 40 insertions(+), 4 deletions(-) diff --git a/portal-template/src/components/api-page.tsx b/portal-template/src/components/api-page.tsx index 219e2851..4fbb96a7 100644 --- a/portal-template/src/components/api-page.tsx +++ b/portal-template/src/components/api-page.tsx @@ -1,3 +1,4 @@ +import { lazy, Suspense } from 'react'; import { createOpenAPIPage } from 'fumadocs-openapi/ui'; import { withBasePath } from '@/lib/base-path'; import { mediaAdapters } from '@/lib/media-adapters'; @@ -6,6 +7,9 @@ import { ApiMarkdown } from './api-markdown'; import { renderExampleLayout } from './example-layout'; import { codeUsages, renderUsageTabs } from './usage-tabs'; +// Its own chunk, as Fumadocs loads it: the playground's forms are not in every page's bundle. +const PlaygroundClient = lazy(() => import('fumadocs-openapi/ui/playground/client')); + export const OpenAPIPage = createOpenAPIPage({ codeUsages, generateTypeScriptDefinitions: false, @@ -13,6 +17,22 @@ export const OpenAPIPage = createOpenAPIPage({ components: { Markdown: ApiMarkdown }, mediaAdapters, oauthRedirectUrl: withBasePath(oauthCallbackPath), + playground: { + // Session replay tools a GTM tag loads record the page's text and input; each marker keeps its tool out of the playground. + render: () => ( +
+ + + +
+ ) + }, // Portals under paths of one host keep their playground's saved values apart; at the root the keys stay Fumadocs' own. storageKeyPrefix: `fumadocs-openapi-${withBasePath('/').slice(1)}` }); diff --git a/portal-template/src/lib/portal-types.ts b/portal-template/src/lib/portal-types.ts index c9281010..a198fc3a 100644 --- a/portal-template/src/lib/portal-types.ts +++ b/portal-template/src/lib/portal-types.ts @@ -40,6 +40,11 @@ export interface PortalAnalytics { keepQueryParams: string[]; } +export interface PortalSeo { + /** The content value of Google's site verification meta tag, for Search Console. */ + googleSiteVerification: string | null; +} + export interface Portal { name: string; description: string | null; @@ -52,4 +57,5 @@ export interface Portal { /** Whether each page offers to open itself in an external AI assistant. */ pageActions: boolean; analytics: PortalAnalytics; + seo: PortalSeo; } diff --git a/portal-template/src/routes/__root.tsx b/portal-template/src/routes/__root.tsx index 1455548e..48852112 100644 --- a/portal-template/src/routes/__root.tsx +++ b/portal-template/src/routes/__root.tsx @@ -41,7 +41,10 @@ export const Route = createRootRoute({ { charSet: 'utf-8' }, { name: 'viewport', content: 'width=device-width, initial-scale=1' }, { title: portal.name }, - ...(portal.description ? [{ name: 'description', content: portal.description }] : []) + ...(portal.description ? [{ name: 'description', content: portal.description }] : []), + ...(portal.seo.googleSiteVerification + ? [{ name: 'google-site-verification', content: portal.seo.googleSiteVerification }] + : []) ], links: [{ rel: 'stylesheet', href: appCss }, ...iconLinks] }), diff --git a/src/types/portal/portal-config.ts b/src/types/portal/portal-config.ts index 0263ab33..a0829318 100644 --- a/src/types/portal/portal-config.ts +++ b/src/types/portal/portal-config.ts @@ -41,6 +41,10 @@ export interface PortalIdentity { googleAnalytics: { measurementId: string; debugMode: boolean } | null; keepQueryParams: string[]; }; + seo: { + /** The content value of Google's site verification meta tag, for Search Console. */ + googleSiteVerification: string | null; + }; } const BLOCK = 'portal'; @@ -132,7 +136,8 @@ export class PortalConfig { colorMode: this.brand.mode(), links: this.navigation.headerLinks().map(portalLink), pageActions: this.ai.offersPageActions(), - analytics: { googleTagManager: null, googleAnalytics: null, keepQueryParams: [] } + analytics: { googleTagManager: null, googleAnalytics: null, keepQueryParams: [] }, + seo: { googleSiteVerification: null } }; } diff --git a/test/types/portal/portal-config.test.ts b/test/types/portal/portal-config.test.ts index 859b923c..b2f2416b 100644 --- a/test/types/portal/portal-config.test.ts +++ b/test/types/portal/portal-config.test.ts @@ -487,7 +487,8 @@ describe('PortalConfig', () => { { label: 'Changelog', url: '/changelog', external: false } ], pageActions: false, - analytics: { googleTagManager: null, googleAnalytics: null, keepQueryParams: [] } + analytics: { googleTagManager: null, googleAnalytics: null, keepQueryParams: [] }, + seo: { googleSiteVerification: null } }); }); @@ -501,7 +502,8 @@ describe('PortalConfig', () => { colorMode: 'both', links: [], pageActions: true, - analytics: { googleTagManager: null, googleAnalytics: null, keepQueryParams: [] } + analytics: { googleTagManager: null, googleAnalytics: null, keepQueryParams: [] }, + seo: { googleSiteVerification: null } }); }); From 5c0a854700e2410e5f0d9617eecf1070f6b4d9de Mon Sep 17 00:00:00 2001 From: Muhammad Sohail Date: Thu, 12 Nov 2026 11:42:00 +0500 Subject: [PATCH 10/73] feat(portal): read portal.analytics and portal.seo from apimatic.json `AnalyticsConfig` parses `googleTagManager` (with its optional `environment`), `googleAnalytics` and `keepQueryParams`, with every rule and message from the table in apimatic/apimatic-io#2348; an OAuth answer's names are refused in the kept list. `SeoConfig` parses `googleSiteVerification`. Both reach the identity file through `identity()` and are serialised only when set, so quickstart's block gains nothing. `portal generate` warns, before the build, when Google Analytics is set: the portal sends its own page views, so the stream's history-change page views must be turned off or every page change counts twice. GA4's `debugMode` is written as false until the delivery reaches `identity()` in the next step. Co-Authored-By: Claude Fable 5.1 --- src/actions/portal/generate.ts | 8 +- src/prompts/portal/generate.ts | 10 ++ src/types/portal/config/analytics-config.ts | 163 +++++++++++++++++++ src/types/portal/config/seo-config.ts | 47 ++++++ src/types/portal/portal-config.ts | 37 +++-- test/actions/portal/generate.test.ts | 22 +++ test/prompts/portal/generate.test.ts | 19 +++ test/types/portal/portal-config.test.ts | 167 ++++++++++++++++++++ 8 files changed, 458 insertions(+), 15 deletions(-) create mode 100644 src/types/portal/config/analytics-config.ts create mode 100644 src/types/portal/config/seo-config.ts diff --git a/src/actions/portal/generate.ts b/src/actions/portal/generate.ts index 2a1f42b3..a4027e88 100644 --- a/src/actions/portal/generate.ts +++ b/src/actions/portal/generate.ts @@ -43,8 +43,12 @@ export class GenerateAction { const portalContext = new PortalContext(portalDirectory); return await new PreparePortalProjectAction(this.configDir, this.commandMetadata, this.authKey).execute(project, { confirm: () => this.confirmOverwrite(portalContext, portalDirectory, force), - onPrepared: (portalProject, source) => - this.build(portalProject, source.config.siteAddress(), portalContext, portalDirectory, zipPortal) + onPrepared: (portalProject, source) => { + if (source.config.usesGoogleAnalytics()) { + this.prompts.googleAnalyticsCountsPageChanges(); + } + return this.build(portalProject, source.config.siteAddress(), portalContext, portalDirectory, zipPortal); + } }); }; diff --git a/src/prompts/portal/generate.ts b/src/prompts/portal/generate.ts index cd8903f9..0c9fc8bd 100644 --- a/src/prompts/portal/generate.ts +++ b/src/prompts/portal/generate.ts @@ -55,6 +55,16 @@ export class PortalGeneratePrompts { log.error(message); } + /** The portal reports its own page views, so a GA4 stream that also counts history changes counts each page twice. */ + public googleAnalyticsCountsPageChanges() { + log.warn( + `Google Analytics is set, so the portal sends its own page views. In GA4, turn off the stream's ` + + `"Page changes based on browser history events" (Admin → Data streams → your stream → Enhanced ` + + `measurement → Page views → advanced settings), or every page change counts twice. ` + + `See the analytics page on ${f.link('docs.apimatic.io/v4')}.` + ); + } + /** * A portal build runs for tens of seconds with no output of its own, so the spinner * carries an elapsed timer rather than a static message. diff --git a/src/types/portal/config/analytics-config.ts b/src/types/portal/config/analytics-config.ts new file mode 100644 index 00000000..0dbfb511 --- /dev/null +++ b/src/types/portal/config/analytics-config.ts @@ -0,0 +1,163 @@ +import { err, ok, Result } from 'neverthrow'; +import { isJsonObject } from '../../../utils/json-utils.js'; +import { allOf, namespace, optional, Parsed, unknownKeys } from './fields.js'; + +export interface GoogleTagManagerSetting { + containerId: string; + /** From the environment's own snippet, so a staging build can still be checked in GTM. */ + environment: { auth: string; preview: string } | null; +} + +/** Public values: they sit in every page's scripts. */ +export interface PortalAnalytics { + googleTagManager: GoogleTagManagerSetting | null; + /** `debugMode` is set by the CLI under `portal serve`. */ + googleAnalytics: { measurementId: string; debugMode: boolean } | null; + keepQueryParams: string[]; +} + +export interface AnalyticsBlock { + googleTagManager?: { containerId: string; environment?: { auth: string; preview: string } }; + googleAnalytics?: { measurementId: string }; + keepQueryParams?: string[]; +} + +const KNOWN = ['googleTagManager', 'googleAnalytics', 'keepQueryParams']; + +/** Names the OAuth standard puts in an answer: never kept, whatever the customer lists. */ +const OAUTH_ANSWER = new Set([ + 'code', + 'state', + 'access_token', + 'id_token', + 'token_type', + 'expires_in', + 'error', + 'session_state', + 'iss' +]); + +export class AnalyticsConfig { + private constructor( + private readonly googleTagManager: GoogleTagManagerSetting | null, + private readonly measurementId: string | null, + private readonly keepQueryParams: string[] + ) {} + + public static readonly defaults = new AnalyticsConfig(null, null, []); + + public static parse(value: unknown, path: string): Parsed { + return namespace(value, path).andThen((data) => + allOf( + unknownKeys(data, KNOWN, path), + Result.combineWithAllErrors([ + optional(data.googleTagManager, (vendor) => googleTagManager(vendor, `${path}.googleTagManager`)), + optional(data.googleAnalytics, (vendor) => googleAnalytics(vendor, `${path}.googleAnalytics`)), + keptQueryParams(data.keepQueryParams, `${path}.keepQueryParams`) + ]) + ).map(([gtm, measurementId, keep]) => new AnalyticsConfig(gtm, measurementId, keep)) + ); + } + + /** `portal generate` warns when this is true: the customer has a GA4 stream setting to turn off. */ + public usesGoogleAnalytics(): boolean { + return this.measurementId !== null; + } + + public identity(): PortalAnalytics { + return { + googleTagManager: this.googleTagManager, + googleAnalytics: this.measurementId === null ? null : { measurementId: this.measurementId, debugMode: false }, + keepQueryParams: this.keepQueryParams + }; + } + + /** Null with nothing set, so the block quickstart writes has no `analytics`. */ + public toJSON(): AnalyticsBlock | null { + const gtm = this.googleTagManager; + const block: AnalyticsBlock = { + ...(gtm === null + ? {} + : { + googleTagManager: { + containerId: gtm.containerId, + ...(gtm.environment === null ? {} : { environment: gtm.environment }) + } + }), + ...(this.measurementId === null ? {} : { googleAnalytics: { measurementId: this.measurementId } }), + ...(this.keepQueryParams.length === 0 ? {} : { keepQueryParams: this.keepQueryParams }) + }; + return Object.keys(block).length === 0 ? null : block; + } +} + +function googleTagManager(value: unknown, path: string): Parsed { + if (!isJsonObject(value)) { + return err([`'${path}' must be a JSON object with 'containerId'.`]); + } + return allOf( + unknownKeys(value, ['containerId', 'environment'], path), + Result.combineWithAllErrors([ + required(value.containerId, `${path}.containerId`, /^\s*GTM-[A-Z0-9]+\s*$/, "must look like 'GTM-ABC123'"), + optional(value.environment, (given) => environment(given, `${path}.environment`)) + ]) + ).map(([containerId, environment]) => ({ containerId: containerId.trim(), environment })); +} + +function environment(value: unknown, path: string): Parsed<{ auth: string; preview: string }> { + if (!isJsonObject(value)) { + return err([`'${path}' must be a JSON object with 'auth' and 'preview'.`]); + } + return allOf( + unknownKeys(value, ['auth', 'preview'], path), + Result.combineWithAllErrors([ + required( + value.auth, + `${path}.auth`, + /^[A-Za-z0-9_-]+$/, + "must be the gtm_auth value from the environment's snippet, with no spaces" + ), + required(value.preview, `${path}.preview`, /^env-\d+$/, "must look like 'env-3'") + ]) + ).map(([auth, preview]) => ({ auth, preview })); +} + +function googleAnalytics(value: unknown, path: string): Parsed { + if (!isJsonObject(value)) { + return err([`'${path}' must be a JSON object with 'measurementId'.`]); + } + return allOf( + unknownKeys(value, ['measurementId'], path), + Result.combineWithAllErrors([ + required(value.measurementId, `${path}.measurementId`, /^\s*G-[A-Z0-9]+\s*$/, "must look like 'G-ABC123'") + ]) + ).map(([measurementId]) => measurementId.trim()); +} + +/** A value pasted from the vendor's console: present, and shaped as the vendor writes it. */ +function required(given: unknown, path: string, shape: RegExp, otherwise: string): Parsed { + if (given === undefined) { + return err([`'${path}' is required.`]); + } + return typeof given === 'string' && shape.test(given) ? ok(given) : err([`'${path}' ${otherwise}.`]); +} + +/** Names a reported address keeps; an OAuth answer's names are refused, whatever the customer lists. */ +function keptQueryParams(value: unknown, path: string): Parsed { + if (value === undefined) { + return ok([]); + } + if (!Array.isArray(value)) { + return err([`'${path}' must be a list of query parameter names.`]); + } + return Result.combineWithAllErrors( + value.map((name, index): Parsed => { + if (typeof name !== 'string' || !/^[A-Za-z0-9_.-]+$/.test(name)) { + return err([`'${path}[${index}]' must be a query parameter name, for example 'campaign_id'.`]); + } + return OAUTH_ANSWER.has(name) + ? err([`'${path}[${index}]' must not be '${name}': the portal never reports an OAuth answer.`]) + : ok(name); + }) + ).mapErr((errors) => errors.flat()); +} diff --git a/src/types/portal/config/seo-config.ts b/src/types/portal/config/seo-config.ts new file mode 100644 index 00000000..8896ccd7 --- /dev/null +++ b/src/types/portal/config/seo-config.ts @@ -0,0 +1,47 @@ +import { err, ok, Result } from 'neverthrow'; +import { allOf, namespace, optional, Parsed, unknownKeys } from './fields.js'; + +export interface PortalSeo { + /** The content value of Google's site verification meta tag, for Search Console. */ + googleSiteVerification: string | null; +} + +export interface SeoBlock { + googleSiteVerification: string; +} + +const KNOWN = ['googleSiteVerification']; + +export class SeoConfig { + private constructor(private readonly googleSiteVerification: string | null) {} + + public static readonly defaults = new SeoConfig(null); + + public static parse(value: unknown, path: string): Parsed { + return namespace(value, path).andThen((data) => + allOf( + unknownKeys(data, KNOWN, path), + Result.combineWithAllErrors([ + optional( + data.googleSiteVerification, + (given): Parsed => + typeof given === 'string' && /^[A-Za-z0-9_-]+$/.test(given) + ? ok(given) + : err([ + `'${path}.googleSiteVerification' must be the content value of Google's verification meta tag, with no spaces.` + ]) + ) + ]) + ).map(([googleSiteVerification]) => new SeoConfig(googleSiteVerification)) + ); + } + + public identity(): PortalSeo { + return { googleSiteVerification: this.googleSiteVerification }; + } + + /** Null with nothing set, so the block quickstart writes has no `seo`. */ + public toJSON(): SeoBlock | null { + return this.googleSiteVerification === null ? null : { googleSiteVerification: this.googleSiteVerification }; + } +} diff --git a/src/types/portal/portal-config.ts b/src/types/portal/portal-config.ts index a0829318..87960ae0 100644 --- a/src/types/portal/portal-config.ts +++ b/src/types/portal/portal-config.ts @@ -2,10 +2,12 @@ import { err, ok, Result } from 'neverthrow'; import { isJsonObject } from '../../utils/json-utils.js'; import { UrlPath } from '../file/urlPath.js'; import { AiConfig } from './config/ai-config.js'; +import { AnalyticsBlock, AnalyticsConfig, PortalAnalytics } from './config/analytics-config.js'; import { BrandConfig, ColorMode } from './config/brand-config.js'; import { allOf, optional, Parsed, unknownKeys } from './config/fields.js'; import { Link } from './config/link.js'; import { NavigationConfig } from './config/navigation-config.js'; +import { PortalSeo, SeoBlock, SeoConfig } from './config/seo-config.js'; import { SiteAddress } from './config/site-address.js'; import { SiteConfig, SuggestedSite } from './config/site-config.js'; import { StaticAsset } from './config/static-asset.js'; @@ -35,21 +37,13 @@ export interface PortalIdentity { links: PortalLink[]; /** Whether each page offers to open itself in an external AI assistant. */ pageActions: boolean; - /** Public values: they sit in every page's scripts. */ - analytics: { - googleTagManager: { containerId: string; environment: { auth: string; preview: string } | null } | null; - googleAnalytics: { measurementId: string; debugMode: boolean } | null; - keepQueryParams: string[]; - }; - seo: { - /** The content value of Google's site verification meta tag, for Search Console. */ - googleSiteVerification: string | null; - }; + analytics: PortalAnalytics; + seo: PortalSeo; } const BLOCK = 'portal'; -const NAMESPACES = ['site', 'brand', 'navigation', 'ai']; +const NAMESPACES = ['site', 'brand', 'navigation', 'ai', 'analytics', 'seo']; /** The one setting outside the namespaces, named as the portal artifacts endpoint reads it. */ const PLUGIN_URL = 'pluginUrl'; @@ -60,6 +54,8 @@ export class PortalConfig { private readonly brand: BrandConfig, private readonly navigation: NavigationConfig, private readonly ai: AiConfig, + private readonly analytics: AnalyticsConfig, + private readonly seo: SeoConfig, private readonly pluginAddress: UrlPath | null ) {} @@ -70,6 +66,8 @@ export class PortalConfig { BrandConfig.defaults, NavigationConfig.defaults, AiConfig.defaults, + AnalyticsConfig.defaults, + SeoConfig.defaults, null ); } @@ -96,6 +94,8 @@ export class PortalConfig { BrandConfig.parse(block.brand, `${BLOCK}.brand`), NavigationConfig.parse(block.navigation, `${BLOCK}.navigation`), AiConfig.parse(block.ai, `${BLOCK}.ai`), + AnalyticsConfig.parse(block.analytics, `${BLOCK}.analytics`), + SeoConfig.parse(block.seo, `${BLOCK}.seo`), optional(block.pluginUrl, (value) => secureAddress(value, `${BLOCK}.${PLUGIN_URL}`)) ]) ).map((settings) => new PortalConfig(...settings)); @@ -123,6 +123,11 @@ export class PortalConfig { return this.brand.files(); } + /** `portal generate` warns when this is true: the customer has a GA4 stream setting to turn off. */ + public usesGoogleAnalytics(): boolean { + return this.analytics.usesGoogleAnalytics(); + } + public identity(): PortalIdentity { const address = this.site.siteAddress(); const logo = this.brand.logoImages(); @@ -136,18 +141,22 @@ export class PortalConfig { colorMode: this.brand.mode(), links: this.navigation.headerLinks().map(portalLink), pageActions: this.ai.offersPageActions(), - analytics: { googleTagManager: null, googleAnalytics: null, keepQueryParams: [] }, - seo: { googleSiteVerification: null } + analytics: this.analytics.identity(), + seo: this.seo.identity() }; } /** Every namespace included, defaults and all, which is what quickstart writes. */ public toJSON(): PortalBlock { + const analytics = this.analytics.toJSON(); + const seo = this.seo.toJSON(); return { site: this.site.toJSON(), brand: this.brand.toJSON(), navigation: this.navigation.toJSON(), ai: this.ai.toJSON(), + ...(analytics === null ? {} : { analytics }), + ...(seo === null ? {} : { seo }), ...(this.pluginAddress === null ? {} : { pluginUrl: this.pluginAddress.toString() }) }; } @@ -176,5 +185,7 @@ export interface PortalBlock { brand: ReturnType; navigation: ReturnType; ai: ReturnType; + analytics?: AnalyticsBlock; + seo?: SeoBlock; pluginUrl?: string; } diff --git a/test/actions/portal/generate.test.ts b/test/actions/portal/generate.test.ts index c5f30bf2..a10d501f 100644 --- a/test/actions/portal/generate.test.ts +++ b/test/actions/portal/generate.test.ts @@ -317,6 +317,28 @@ describe('GenerateAction', () => { expect(shared.prompts.filesShadowedByStatic.firstCall.args[0].map(String)).to.deep.equal(['robots.txt']); }); + it('warns that Google Analytics counts page changes, before the build, when it is set', async () => { + const project = new DirectoryPath(root).join('analytics'); + fs.cpSync(FIXTURE.toString(), project.toString(), { recursive: true }); + const configFile = path.join(project.toString(), 'src', 'apimatic.json'); + const edited = JSON.parse(fs.readFileSync(configFile, 'utf8')); + edited.portal.analytics = { googleAnalytics: { measurementId: 'G-ABC123' } }; + fs.writeFileSync(configFile, JSON.stringify(edited)); + + const result = await execute(project); + + expect(result.isSuccess()).to.be.true; + expect(prompts.googleAnalyticsCountsPageChanges.calledOnce).to.be.true; + expect(prompts.googleAnalyticsCountsPageChanges.calledBefore(build)).to.be.true; + }); + + it('does not warn about Google Analytics when it is not set', async () => { + const result = await execute(); + + expect(result.isSuccess()).to.be.true; + expect(prompts.googleAnalyticsCountsPageChanges.called).to.be.false; + }); + it('reports the specs the SDKs do not cover and the operations two specs declare, none in the fixture', async () => { const result = await execute(); diff --git a/test/prompts/portal/generate.test.ts b/test/prompts/portal/generate.test.ts index 93a216c1..80f34e37 100644 --- a/test/prompts/portal/generate.test.ts +++ b/test/prompts/portal/generate.test.ts @@ -1,4 +1,5 @@ import { stripVTControlCharacters } from 'node:util'; +import { log } from '@clack/prompts'; import { expect } from 'chai'; import sinon from 'sinon'; import { PortalGeneratePrompts } from '../../../src/prompts/portal/generate.js'; @@ -6,6 +7,24 @@ import { DirectoryPath } from '../../../src/types/file/directoryPath.js'; import { SiteAddress } from '../../../src/types/portal/config/site-address.js'; describe('PortalGeneratePrompts', () => { + describe('the GA4 warning', () => { + it('says what to turn off, where, and why', () => { + const warn = sinon.stub(log, 'warn'); + try { + new PortalGeneratePrompts().googleAnalyticsCountsPageChanges(); + } finally { + warn.restore(); + } + + expect(stripVTControlCharacters(String(warn.firstCall.args[0]))).to.equal( + "Google Analytics is set, so the portal sends its own page views. In GA4, turn off the stream's " + + '"Page changes based on browser history events" (Admin → Data streams → your stream → Enhanced ' + + 'measurement → Page views → advanced settings), or every page change counts twice. ' + + 'See the analytics page on docs.apimatic.io/v4.' + ); + }); + }); + describe('the next steps', () => { const portal = new DirectoryPath('portal'); diff --git a/test/types/portal/portal-config.test.ts b/test/types/portal/portal-config.test.ts index b2f2416b..077dc780 100644 --- a/test/types/portal/portal-config.test.ts +++ b/test/types/portal/portal-config.test.ts @@ -395,6 +395,173 @@ describe('PortalConfig', () => { }); }); + describe('analytics', () => { + const gtm = 'portal.analytics.googleTagManager'; + const ga = 'portal.analytics.googleAnalytics'; + const keep = 'portal.analytics.keepQueryParams'; + + it('tells the browser to load nothing when the block sets nothing', () => { + expect(config({}).identity().analytics).to.deep.equal({ + googleTagManager: null, + googleAnalytics: null, + keepQueryParams: [] + }); + expect(JSON.parse(JSON.stringify(config({})))).to.not.have.property('analytics'); + }); + + it('keeps both vendors with their IDs trimmed, the environment and the kept names', () => { + const analytics = { + googleTagManager: { containerId: ' GTM-ABC123 ', environment: { auth: 'a1_b-2', preview: 'env-3' } }, + googleAnalytics: { measurementId: ' G-ABC123 ' }, + keepQueryParams: ['campaign_id', 'ref.1'] + }; + + expect(config({ analytics }).identity().analytics).to.deep.equal({ + googleTagManager: { containerId: 'GTM-ABC123', environment: { auth: 'a1_b-2', preview: 'env-3' } }, + googleAnalytics: { measurementId: 'G-ABC123', debugMode: false }, + keepQueryParams: ['campaign_id', 'ref.1'] + }); + }); + + it('refuses a block, a vendor or an environment that is not an object, as a bare ID is the likely slip', () => { + expect(errorsOf({ analytics: 'GTM-ABC123' })).to.deep.equal(["'portal.analytics' must be a JSON object."]); + expect(errorsOf({ analytics: { googleTagManager: 'GTM-ABC123' } })).to.deep.equal([ + `'${gtm}' must be a JSON object with 'containerId'.` + ]); + expect(errorsOf({ analytics: { googleAnalytics: 'G-ABC123' } })).to.deep.equal([ + `'${ga}' must be a JSON object with 'measurementId'.` + ]); + expect( + errorsOf({ analytics: { googleTagManager: { containerId: 'GTM-ABC123', environment: 'env-3' } } }) + ).to.deep.equal([`'${gtm}.environment' must be a JSON object with 'auth' and 'preview'.`]); + }); + + it('requires each ID and holds it to the vendor’s shape', () => { + expect(errorsOf({ analytics: { googleTagManager: {}, googleAnalytics: {} } })).to.deep.equal([ + `'${gtm}.containerId' is required.`, + `'${ga}.measurementId' is required.` + ]); + expect( + errorsOf({ + analytics: { googleTagManager: { containerId: 'gtm-abc123' }, googleAnalytics: { measurementId: 'UA-1' } } + }) + ).to.deep.equal([ + `'${gtm}.containerId' must look like 'GTM-ABC123'.`, + `'${ga}.measurementId' must look like 'G-ABC123'.` + ]); + }); + + it('requires both environment values and holds each to the snippet’s shape', () => { + const withEnvironment = (environment: unknown) => + errorsOf({ analytics: { googleTagManager: { containerId: 'GTM-ABC123', environment } } }); + + expect(withEnvironment({})).to.deep.equal([ + `'${gtm}.environment.auth' is required.`, + `'${gtm}.environment.preview' is required.` + ]); + expect(withEnvironment({ auth: 'a b', preview: 'env3' })).to.deep.equal([ + `'${gtm}.environment.auth' must be the gtm_auth value from the environment's snippet, with no spaces.`, + `'${gtm}.environment.preview' must look like 'env-3'.` + ]); + }); + + it('names an unknown key beside a vendor or an environment like any other', () => { + expect( + errorsOf({ + analytics: { + posthog: {}, + googleTagManager: { + containerId: 'GTM-ABC123', + serverUrl: 'x', + environment: { auth: 'a', preview: 'env-1', url: 'x' } + }, + googleAnalytics: { measurementId: 'G-ABC123', debug: true } + } + }) + ).to.deep.equal([ + "'portal.analytics.posthog' is not a 'portal' setting.", + `'${gtm}.serverUrl' is not a 'portal' setting.`, + `'${gtm}.environment.url' is not a 'portal' setting.`, + `'${ga}.debug' is not a 'portal' setting.` + ]); + }); + + it('keeps only query parameter names, and never an OAuth answer’s', () => { + expect(errorsOf({ analytics: { keepQueryParams: 'campaign_id' } })).to.deep.equal([ + `'${keep}' must be a list of query parameter names.` + ]); + expect(errorsOf({ analytics: { keepQueryParams: ['a b', 'code', 1] } })).to.deep.equal([ + `'${keep}[0]' must be a query parameter name, for example 'campaign_id'.`, + `'${keep}[1]' must not be 'code': the portal never reports an OAuth answer.`, + `'${keep}[2]' must be a query parameter name, for example 'campaign_id'.` + ]); + }); + + it('reports every fault at once, unknown keys first', () => { + expect( + errorsOf({ + analytics: { + posthog: {}, + googleTagManager: { containerId: 'x' }, + googleAnalytics: 'G-1', + keepQueryParams: ['code'] + } + }) + ).to.deep.equal([ + "'portal.analytics.posthog' is not a 'portal' setting.", + `'${gtm}.containerId' must look like 'GTM-ABC123'.`, + `'${ga}' must be a JSON object with 'measurementId'.`, + `'${keep}[0]' must not be 'code': the portal never reports an OAuth answer.` + ]); + }); + + it('uses Google Analytics only with a measurement ID', () => { + expect(config({}).usesGoogleAnalytics()).to.be.false; + expect(config({ analytics: { googleTagManager: { containerId: 'GTM-ABC123' } } }).usesGoogleAnalytics()).to.be + .false; + expect(config({ analytics: { googleAnalytics: { measurementId: 'G-ABC123' } } }).usesGoogleAnalytics()).to.be + .true; + }); + + it('serialises what it was given, and nothing when given nothing', () => { + const analytics = { + googleTagManager: { containerId: 'GTM-ABC123', environment: { auth: 'a', preview: 'env-1' } }, + googleAnalytics: { measurementId: 'G-ABC123' }, + keepQueryParams: ['campaign_id'] + }; + const written = (block: unknown) => JSON.parse(JSON.stringify(config(block))); + + expect(written({ analytics }).analytics).to.deep.equal(analytics); + expect(written({ analytics: { googleTagManager: { containerId: 'GTM-1' } } }).analytics).to.deep.equal({ + googleTagManager: { containerId: 'GTM-1' } + }); + expect(written({ analytics: {} })).to.not.have.property('analytics'); + }); + }); + + describe('seo', () => { + it('carries the verification value to the browser, or null without one', () => { + expect(config({ seo: { googleSiteVerification: 'abc_123-XYZ' } }).identity().seo).to.deep.equal({ + googleSiteVerification: 'abc_123-XYZ' + }); + expect(config({}).identity().seo).to.deep.equal({ googleSiteVerification: null }); + }); + + it('refuses a block that is not an object, and a value with anything but a token’s characters', () => { + expect(errorsOf({ seo: 'abc' })).to.deep.equal(["'portal.seo' must be a JSON object."]); + expect(errorsOf({ seo: { googleSiteVerification: 'abc 123' } })).to.deep.equal([ + "'portal.seo.googleSiteVerification' must be the content value of Google's verification meta tag, with no spaces." + ]); + }); + + it('is serialised only when set', () => { + const written = (block: unknown) => JSON.parse(JSON.stringify(config(block))); + + expect(written({ seo: { googleSiteVerification: 'abc' } }).seo).to.deep.equal({ googleSiteVerification: 'abc' }); + expect(written({ seo: {} })).to.not.have.property('seo'); + }); + }); + describe('pluginUrl', () => { const REFUSED = "'portal.pluginUrl' must be an address starting with 'https://', with no spaces, for example " + From 7ea287df98409f3857ed2bd7b551820e2adba99c Mon Sep 17 00:00:00 2001 From: Muhammad Sohail Date: Thu, 12 Nov 2026 11:57:23 +0500 Subject: [PATCH 11/73] refactor(portal): leave vendor value formats to the vendors A container ID, a measurement ID, an environment's auth and preview values, the verification token and a kept query parameter name are any non-empty string: a wrong value fails at the vendor, not in the CLI, so the parser checks presence and type only and holds no pattern. The kept-name list no longer refuses an OAuth answer's names either. Decided 2026-11-12; it replaces the locked rule and the format rows of the table in apimatic/apimatic-io#2348, and is to be recorded in #2347. Co-Authored-By: Claude Fable 5.1 --- src/types/portal/config/analytics-config.ts | 59 +++++---------------- src/types/portal/config/seo-config.ts | 14 ++--- test/types/portal/portal-config.test.ts | 50 ++++++++--------- 3 files changed, 41 insertions(+), 82 deletions(-) diff --git a/src/types/portal/config/analytics-config.ts b/src/types/portal/config/analytics-config.ts index 0dbfb511..29d19326 100644 --- a/src/types/portal/config/analytics-config.ts +++ b/src/types/portal/config/analytics-config.ts @@ -1,6 +1,6 @@ import { err, ok, Result } from 'neverthrow'; import { isJsonObject } from '../../../utils/json-utils.js'; -import { allOf, namespace, optional, Parsed, unknownKeys } from './fields.js'; +import { allOf, namespace, nonEmptyString, optional, Parsed, unknownKeys } from './fields.js'; export interface GoogleTagManagerSetting { containerId: string; @@ -24,19 +24,6 @@ export interface AnalyticsBlock { const KNOWN = ['googleTagManager', 'googleAnalytics', 'keepQueryParams']; -/** Names the OAuth standard puts in an answer: never kept, whatever the customer lists. */ -const OAUTH_ANSWER = new Set([ - 'code', - 'state', - 'access_token', - 'id_token', - 'token_type', - 'expires_in', - 'error', - 'session_state', - 'iss' -]); - export class AnalyticsConfig { private constructor( private readonly googleTagManager: GoogleTagManagerSetting | null, @@ -98,10 +85,10 @@ function googleTagManager(value: unknown, path: string): Parsed environment(given, `${path}.environment`)) ]) - ).map(([containerId, environment]) => ({ containerId: containerId.trim(), environment })); + ).map(([containerId, environment]) => ({ containerId, environment })); } function environment(value: unknown, path: string): Parsed<{ auth: string; preview: string }> { @@ -110,15 +97,7 @@ function environment(value: unknown, path: string): Parsed<{ auth: string; previ } return allOf( unknownKeys(value, ['auth', 'preview'], path), - Result.combineWithAllErrors([ - required( - value.auth, - `${path}.auth`, - /^[A-Za-z0-9_-]+$/, - "must be the gtm_auth value from the environment's snippet, with no spaces" - ), - required(value.preview, `${path}.preview`, /^env-\d+$/, "must look like 'env-3'") - ]) + Result.combineWithAllErrors([required(value.auth, `${path}.auth`), required(value.preview, `${path}.preview`)]) ).map(([auth, preview]) => ({ auth, preview })); } @@ -128,21 +107,16 @@ function googleAnalytics(value: unknown, path: string): Parsed { } return allOf( unknownKeys(value, ['measurementId'], path), - Result.combineWithAllErrors([ - required(value.measurementId, `${path}.measurementId`, /^\s*G-[A-Z0-9]+\s*$/, "must look like 'G-ABC123'") - ]) - ).map(([measurementId]) => measurementId.trim()); + Result.combineWithAllErrors([required(value.measurementId, `${path}.measurementId`)]) + ).map(([measurementId]) => measurementId); } -/** A value pasted from the vendor's console: present, and shaped as the vendor writes it. */ -function required(given: unknown, path: string, shape: RegExp, otherwise: string): Parsed { - if (given === undefined) { - return err([`'${path}' is required.`]); - } - return typeof given === 'string' && shape.test(given) ? ok(given) : err([`'${path}' ${otherwise}.`]); +/** Present and a non-empty string; its format is the vendor's to check, since a wrong value fails there, not here. */ +function required(given: unknown, path: string): Parsed { + return given === undefined ? err([`'${path}' is required.`]) : nonEmptyString(given, path); } -/** Names a reported address keeps; an OAuth answer's names are refused, whatever the customer lists. */ +/** Names a reported address keeps, beyond the campaign names it always keeps. */ function keptQueryParams(value: unknown, path: string): Parsed { if (value === undefined) { return ok([]); @@ -150,14 +124,7 @@ function keptQueryParams(value: unknown, path: string): Parsed { if (!Array.isArray(value)) { return err([`'${path}' must be a list of query parameter names.`]); } - return Result.combineWithAllErrors( - value.map((name, index): Parsed => { - if (typeof name !== 'string' || !/^[A-Za-z0-9_.-]+$/.test(name)) { - return err([`'${path}[${index}]' must be a query parameter name, for example 'campaign_id'.`]); - } - return OAUTH_ANSWER.has(name) - ? err([`'${path}[${index}]' must not be '${name}': the portal never reports an OAuth answer.`]) - : ok(name); - }) - ).mapErr((errors) => errors.flat()); + return Result.combineWithAllErrors(value.map((name, index) => nonEmptyString(name, `${path}[${index}]`))).mapErr( + (errors) => errors.flat() + ); } diff --git a/src/types/portal/config/seo-config.ts b/src/types/portal/config/seo-config.ts index 8896ccd7..7f5c3db5 100644 --- a/src/types/portal/config/seo-config.ts +++ b/src/types/portal/config/seo-config.ts @@ -1,5 +1,5 @@ -import { err, ok, Result } from 'neverthrow'; -import { allOf, namespace, optional, Parsed, unknownKeys } from './fields.js'; +import { Result } from 'neverthrow'; +import { allOf, namespace, nonEmptyString, optional, Parsed, unknownKeys } from './fields.js'; export interface PortalSeo { /** The content value of Google's site verification meta tag, for Search Console. */ @@ -22,15 +22,7 @@ export class SeoConfig { allOf( unknownKeys(data, KNOWN, path), Result.combineWithAllErrors([ - optional( - data.googleSiteVerification, - (given): Parsed => - typeof given === 'string' && /^[A-Za-z0-9_-]+$/.test(given) - ? ok(given) - : err([ - `'${path}.googleSiteVerification' must be the content value of Google's verification meta tag, with no spaces.` - ]) - ) + optional(data.googleSiteVerification, (given) => nonEmptyString(given, `${path}.googleSiteVerification`)) ]) ).map(([googleSiteVerification]) => new SeoConfig(googleSiteVerification)) ); diff --git a/test/types/portal/portal-config.test.ts b/test/types/portal/portal-config.test.ts index 077dc780..381e6c28 100644 --- a/test/types/portal/portal-config.test.ts +++ b/test/types/portal/portal-config.test.ts @@ -409,17 +409,17 @@ describe('PortalConfig', () => { expect(JSON.parse(JSON.stringify(config({})))).to.not.have.property('analytics'); }); - it('keeps both vendors with their IDs trimmed, the environment and the kept names', () => { + it('keeps both vendors with their IDs trimmed, the environment and every kept name, an OAuth answer’s included', () => { const analytics = { googleTagManager: { containerId: ' GTM-ABC123 ', environment: { auth: 'a1_b-2', preview: 'env-3' } }, googleAnalytics: { measurementId: ' G-ABC123 ' }, - keepQueryParams: ['campaign_id', 'ref.1'] + keepQueryParams: ['campaign_id', ' code '] }; expect(config({ analytics }).identity().analytics).to.deep.equal({ googleTagManager: { containerId: 'GTM-ABC123', environment: { auth: 'a1_b-2', preview: 'env-3' } }, googleAnalytics: { measurementId: 'G-ABC123', debugMode: false }, - keepQueryParams: ['campaign_id', 'ref.1'] + keepQueryParams: ['campaign_id', 'code'] }); }); @@ -436,22 +436,23 @@ describe('PortalConfig', () => { ).to.deep.equal([`'${gtm}.environment' must be a JSON object with 'auth' and 'preview'.`]); }); - it('requires each ID and holds it to the vendor’s shape', () => { + it('requires each ID as a non-empty string, and leaves its format to the vendor', () => { expect(errorsOf({ analytics: { googleTagManager: {}, googleAnalytics: {} } })).to.deep.equal([ `'${gtm}.containerId' is required.`, `'${ga}.measurementId' is required.` ]); expect( - errorsOf({ - analytics: { googleTagManager: { containerId: 'gtm-abc123' }, googleAnalytics: { measurementId: 'UA-1' } } - }) + errorsOf({ analytics: { googleTagManager: { containerId: ' ' }, googleAnalytics: { measurementId: 1 } } }) ).to.deep.equal([ - `'${gtm}.containerId' must look like 'GTM-ABC123'.`, - `'${ga}.measurementId' must look like 'G-ABC123'.` + `'${gtm}.containerId' must be a non-empty string.`, + `'${ga}.measurementId' must be a non-empty string.` ]); + expect( + config({ analytics: { googleTagManager: { containerId: 'gtm-abc123' } } }).identity().analytics.googleTagManager + ).to.deep.equal({ containerId: 'gtm-abc123', environment: null }); }); - it('requires both environment values and holds each to the snippet’s shape', () => { + it('requires both environment values as non-empty strings', () => { const withEnvironment = (environment: unknown) => errorsOf({ analytics: { googleTagManager: { containerId: 'GTM-ABC123', environment } } }); @@ -459,9 +460,9 @@ describe('PortalConfig', () => { `'${gtm}.environment.auth' is required.`, `'${gtm}.environment.preview' is required.` ]); - expect(withEnvironment({ auth: 'a b', preview: 'env3' })).to.deep.equal([ - `'${gtm}.environment.auth' must be the gtm_auth value from the environment's snippet, with no spaces.`, - `'${gtm}.environment.preview' must look like 'env-3'.` + expect(withEnvironment({ auth: '', preview: 3 })).to.deep.equal([ + `'${gtm}.environment.auth' must be a non-empty string.`, + `'${gtm}.environment.preview' must be a non-empty string.` ]); }); @@ -486,14 +487,13 @@ describe('PortalConfig', () => { ]); }); - it('keeps only query parameter names, and never an OAuth answer’s', () => { + it('takes a list of kept names, each a non-empty string', () => { expect(errorsOf({ analytics: { keepQueryParams: 'campaign_id' } })).to.deep.equal([ `'${keep}' must be a list of query parameter names.` ]); - expect(errorsOf({ analytics: { keepQueryParams: ['a b', 'code', 1] } })).to.deep.equal([ - `'${keep}[0]' must be a query parameter name, for example 'campaign_id'.`, - `'${keep}[1]' must not be 'code': the portal never reports an OAuth answer.`, - `'${keep}[2]' must be a query parameter name, for example 'campaign_id'.` + expect(errorsOf({ analytics: { keepQueryParams: ['', 1] } })).to.deep.equal([ + `'${keep}[0]' must be a non-empty string.`, + `'${keep}[1]' must be a non-empty string.` ]); }); @@ -502,16 +502,16 @@ describe('PortalConfig', () => { errorsOf({ analytics: { posthog: {}, - googleTagManager: { containerId: 'x' }, + googleTagManager: { containerId: '' }, googleAnalytics: 'G-1', - keepQueryParams: ['code'] + keepQueryParams: [1] } }) ).to.deep.equal([ "'portal.analytics.posthog' is not a 'portal' setting.", - `'${gtm}.containerId' must look like 'GTM-ABC123'.`, + `'${gtm}.containerId' must be a non-empty string.`, `'${ga}' must be a JSON object with 'measurementId'.`, - `'${keep}[0]' must not be 'code': the portal never reports an OAuth answer.` + `'${keep}[0]' must be a non-empty string.` ]); }); @@ -547,10 +547,10 @@ describe('PortalConfig', () => { expect(config({}).identity().seo).to.deep.equal({ googleSiteVerification: null }); }); - it('refuses a block that is not an object, and a value with anything but a token’s characters', () => { + it('refuses a block that is not an object, and a blank value', () => { expect(errorsOf({ seo: 'abc' })).to.deep.equal(["'portal.seo' must be a JSON object."]); - expect(errorsOf({ seo: { googleSiteVerification: 'abc 123' } })).to.deep.equal([ - "'portal.seo.googleSiteVerification' must be the content value of Google's verification meta tag, with no spaces." + expect(errorsOf({ seo: { googleSiteVerification: ' ' } })).to.deep.equal([ + "'portal.seo.googleSiteVerification' must be a non-empty string." ]); }); From fe93025efddc8d8ff6b879b9a8ed873aadced879 Mon Sep 17 00:00:00 2001 From: Muhammad Sohail Date: Thu, 12 Nov 2026 12:23:01 +0500 Subject: [PATCH 12/73] feat(portal): add --no-analytics and leave the vendors out of the identity file `portal generate` and `portal serve` take `--no-analytics`, for a staging build that must not count. The flag reaches `identity()` as one boolean, passed through the prepare action and the project service and never stored: with it off, both vendors are written as null and the browser loads no tag, while the kept query names still go through. `portal serve` hands the same value to the rewrite when the block changes. `portal serve` is a hosted portal in every way: GA4's debug mode and the preview/build distinction are gone, so the sketched delivery class is not built. Decided 2026-11-12, to be recorded in apimatic/apimatic-io#2347. Co-Authored-By: Claude Fable 5.1 --- portal-template/src/lib/analytics.ts | 5 +- portal-template/src/lib/portal-types.ts | 2 - src/actions/portal/generate.ts | 6 +- src/actions/portal/prepare-project.ts | 8 +- src/actions/portal/serve.ts | 26 ++-- src/actions/quickstart.ts | 1 + src/commands/portal/generate.ts | 9 +- src/commands/portal/serve.ts | 9 +- src/infrastructure/portal-project-service.ts | 30 +++-- src/types/portal/config/analytics-config.ts | 9 +- src/types/portal/portal-config.ts | 4 +- test/actions/portal/generate.test.ts | 14 ++- test/actions/portal/prepare-project.test.ts | 10 +- test/actions/portal/serve.test.ts | 25 +++- test/commands/portal/generate-flags.test.ts | 15 +++ test/commands/portal/serve-flags.test.ts | 15 +++ test/e2e/portal-build.test.ts | 2 +- test/e2e/portal-serve.test.ts | 2 +- .../portal-project-service.test.ts | 115 +++++++++++------- test/portal-template/analytics.test.ts | 31 ++--- test/types/portal-source-context.test.ts | 8 +- test/types/portal/portal-config.test.ts | 64 ++++++---- 22 files changed, 270 insertions(+), 140 deletions(-) create mode 100644 test/commands/portal/generate-flags.test.ts create mode 100644 test/commands/portal/serve-flags.test.ts diff --git a/portal-template/src/lib/analytics.ts b/portal-template/src/lib/analytics.ts index 924955bc..a22fa6ab 100644 --- a/portal-template/src/lib/analytics.ts +++ b/portal-template/src/lib/analytics.ts @@ -76,10 +76,7 @@ export const adapters: { [V in Vendor]: (setting: NonNullable [`${GOOGLE}/gtag/js?id=${setting.measurementId}`], // GA4 gets its own names: the `docs_` prefix comes off. diff --git a/portal-template/src/lib/portal-types.ts b/portal-template/src/lib/portal-types.ts index a198fc3a..006c0044 100644 --- a/portal-template/src/lib/portal-types.ts +++ b/portal-template/src/lib/portal-types.ts @@ -27,10 +27,8 @@ export interface GoogleTagManagerSetting { environment: { auth: string; preview: string } | null; } -/** `debugMode` is set by the CLI under `portal serve`. */ export interface GoogleAnalyticsSetting { measurementId: string; - debugMode: boolean; } /** Public values: they sit in every page's scripts. */ diff --git a/src/actions/portal/generate.ts b/src/actions/portal/generate.ts index a4027e88..1daf9ced 100644 --- a/src/actions/portal/generate.ts +++ b/src/actions/portal/generate.ts @@ -26,7 +26,8 @@ export class GenerateAction { project: ProjectContext, portalDirectory: DirectoryPath, force: boolean, - zipPortal: boolean + zipPortal: boolean, + enableAnalytics: boolean ): Promise => { if (project.isSourceDirectory(portalDirectory)) { this.prompts.directoryCannotBeSame(portalDirectory); @@ -41,7 +42,8 @@ export class GenerateAction { } const portalContext = new PortalContext(portalDirectory); - return await new PreparePortalProjectAction(this.configDir, this.commandMetadata, this.authKey).execute(project, { + const prepare = new PreparePortalProjectAction(this.configDir, this.commandMetadata, this.authKey); + return await prepare.execute(project, enableAnalytics, { confirm: () => this.confirmOverwrite(portalContext, portalDirectory, force), onPrepared: (portalProject, source) => { if (source.config.usesGoogleAnalytics()) { diff --git a/src/actions/portal/prepare-project.ts b/src/actions/portal/prepare-project.ts index 1aea7782..ad753674 100644 --- a/src/actions/portal/prepare-project.ts +++ b/src/actions/portal/prepare-project.ts @@ -36,6 +36,7 @@ export class PreparePortalProjectAction { /** Takes the caller's next step rather than returning, because its temporary directories must outlive this call. */ public readonly execute = async ( project: ProjectContext, + enableAnalytics: boolean, { confirm = async () => true, onPrepared }: PreparationSteps ): Promise => { const sourceDirectory = project.sourceDirectory(); @@ -110,7 +111,12 @@ export class PreparePortalProjectAction { } return await withDirPath(async (tempDirectory) => { - const portalProject = await this.projectService.prepare(tempDirectory, source.value, artifacts.value); + const portalProject = await this.projectService.prepare( + tempDirectory, + source.value, + artifacts.value, + enableAnalytics + ); if (portalProject.isErr()) { this.prompts.runtimeUnsupported(portalProject.error); return ActionResult.failed(); diff --git a/src/actions/portal/serve.ts b/src/actions/portal/serve.ts index 1c190afe..97a256c3 100644 --- a/src/actions/portal/serve.ts +++ b/src/actions/portal/serve.ts @@ -45,9 +45,11 @@ export class PortalServeAction { project: ProjectContext, port: number, openInBrowser: boolean, + enableAnalytics: boolean, onServing?: () => void ): Promise => { - return await new PreparePortalProjectAction(this.configDir, this.commandMetadata, this.authKey).execute(project, { + const prepare = new PreparePortalProjectAction(this.configDir, this.commandMetadata, this.authKey); + return await prepare.execute(project, enableAnalytics, { onPrepared: async (portalProject, source, artifacts) => { const servePort = await this.networkService.getServerPort([port, 3000, 3001, 3002]); if (servePort !== port) { @@ -73,13 +75,20 @@ export class PortalServeAction { // adds and removes, and which the root nav.json makes tabs of or places in Home. let generatedPages = source.generatedPages; const contentWatch = this.watchContent(project, source, () => generatedPages, portalProject.projectDirectory); - const configWatch = this.watchConfig(project, source, artifacts, portalProject.projectDirectory, (settings) => { - const sectionsChanged = !settings.generatedPages.makesSameSectionsAs(generatedPages); - generatedPages = settings.generatedPages; - if (sectionsChanged) { - contentWatch?.recheck(); + const configWatch = this.watchConfig( + project, + source, + artifacts, + portalProject.projectDirectory, + enableAnalytics, + (settings) => { + const sectionsChanged = !settings.generatedPages.makesSameSectionsAs(generatedPages); + generatedPages = settings.generatedPages; + if (sectionsChanged) { + contentWatch?.recheck(); + } } - }); + ); const specWatch = this.watchSpecs(project, source); const closeWatches = async () => { await specWatch?.close(); @@ -122,6 +131,7 @@ export class PortalServeAction { source: PortalSource, artifacts: PortalArtifacts, portalProjectDirectory: DirectoryPath, + enableAnalytics: boolean, onApplied: (settings: PortalSettings) => void ): FileWatch | undefined { const sourceDirectory = project.sourceDirectory(); @@ -149,7 +159,7 @@ export class PortalServeAction { this.prompts.staticDirectoryNotServed(sourceDirectory); } - const applied = await this.projectService.applyConfig(portalProjectDirectory, settings); + const applied = await this.projectService.applyConfig(portalProjectDirectory, settings, enableAnalytics); if (applied.isErr()) { this.prompts.notApplied('config', applied.error, sourceDirectory); return; diff --git a/src/actions/quickstart.ts b/src/actions/quickstart.ts index 1c620ffe..47c72536 100644 --- a/src/actions/quickstart.ts +++ b/src/actions/quickstart.ts @@ -244,6 +244,7 @@ export class QuickstartAction { project, DEFAULT_PORTAL_PORT, true, + true, () => this.prompts.nextSteps(configFile) ); diff --git a/src/commands/portal/generate.ts b/src/commands/portal/generate.ts index a4f1223c..d94b8ef5 100644 --- a/src/commands/portal/generate.ts +++ b/src/commands/portal/generate.ts @@ -28,6 +28,11 @@ The portal is built on your machine and written as static files for any static h default: false, description: 'write the generated portal as a .zip archive.' }), + 'no-analytics': Flags.boolean({ + default: false, + description: + 'leave out Google Tag Manager, Google Analytics and every analytics or marketing script, for staging.' + }), ...FlagsProvider.input, ...FlagsProvider.destination('portal', 'portal'), ...FlagsProvider.force, @@ -36,7 +41,7 @@ The portal is built on your machine and written as static files for any static h async run(): Promise { const { - flags: { input, destination, force, zip: zipPortal, 'auth-key': authKey } + flags: { input, destination, force, zip: zipPortal, 'no-analytics': noAnalytics, 'auth-key': authKey } } = await this.parse(PortalGenerate); const project = ProjectContext.at(input); @@ -47,7 +52,7 @@ The portal is built on your machine and written as static files for any static h intro('Generate Portal'); const action = new GenerateAction(this.getConfigDir(), commandMetadata, authKey); - const result = await action.execute(project, project.portalDirectory(destination), force, zipPortal); + const result = await action.execute(project, project.portalDirectory(destination), force, zipPortal, !noAnalytics); outro(result); } diff --git a/src/commands/portal/serve.ts b/src/commands/portal/serve.ts index ba4d41c1..67995ca0 100644 --- a/src/commands/portal/serve.ts +++ b/src/commands/portal/serve.ts @@ -36,13 +36,18 @@ Nothing is written to disk; run 'apimatic portal generate' to produce the static description: 'open the portal in the default browser.', default: false }), + 'no-analytics': Flags.boolean({ + default: false, + description: + 'leave out Google Tag Manager, Google Analytics and every analytics or marketing script, for staging.' + }), ...FlagsProvider.input, ...FlagsProvider.authKey }; public async run() { const { - flags: { input, port, open, 'auth-key': authKey } + flags: { input, port, open, 'no-analytics': noAnalytics, 'auth-key': authKey } } = await this.parse(PortalServe); const commandMetadata: CommandMetadata = { @@ -52,7 +57,7 @@ Nothing is written to disk; run 'apimatic portal generate' to produce the static intro('Portal Serve'); const action = new PortalServeAction(this.getConfigDir(), commandMetadata, authKey); - const result = await action.execute(ProjectContext.at(input), port, open); + const result = await action.execute(ProjectContext.at(input), port, open, !noAnalytics); outro(result); } diff --git a/src/infrastructure/portal-project-service.ts b/src/infrastructure/portal-project-service.ts index 87334ad8..b08c7bc5 100644 --- a/src/infrastructure/portal-project-service.ts +++ b/src/infrastructure/portal-project-service.ts @@ -107,7 +107,8 @@ export class PortalProjectService { public async prepare( projectDirectory: DirectoryPath, source: PortalSource, - artifacts: PortalArtifacts + artifacts: PortalArtifacts, + enableAnalytics: boolean ): Promise> { const template = this.templateDirectory(); if (template === undefined) { @@ -131,6 +132,7 @@ export class PortalProjectService { await this.writeCodeSamples(projectDirectory, source, artifacts.codeSampleCatalogs), await this.writeDownloads(projectDirectory, artifacts) ); + await this.writeAppearance(projectDirectory, source.config, enableAnalytics); const pages = await this.pagesService.write(projectDirectory.join(GENERATED_DIRECTORY_NAME), source.generatedPages); if (pages.isErr()) { @@ -297,8 +299,6 @@ export class PortalProjectService { new FilePath(projectDirectory, new FileName('portal.config.json')), JSON.stringify(configuration, null, 2) ); - - await this.writeAppearance(projectDirectory, source.config); } /** @@ -308,11 +308,12 @@ export class PortalProjectService { */ public async applyConfig( projectDirectory: DirectoryPath, - settings: PortalSettings + settings: PortalSettings, + enableAnalytics: boolean ): Promise> { let written = false; try { - for (const [file, contents] of this.appearanceFiles(projectDirectory, settings.config)) { + for (const [file, contents] of this.appearanceFiles(projectDirectory, settings.config, enableAnalytics)) { if (await this.fileService.replaceContentsIfChanged(file, contents)) { written = true; } @@ -372,8 +373,12 @@ export class PortalProjectService { .filter((file) => !isSkippedWithin(file, directory)); } - private async writeAppearance(projectDirectory: DirectoryPath, config: PortalConfig): Promise { - for (const [file, contents] of this.appearanceFiles(projectDirectory, config)) { + private async writeAppearance( + projectDirectory: DirectoryPath, + config: PortalConfig, + enableAnalytics: boolean + ): Promise { + for (const [file, contents] of this.appearanceFiles(projectDirectory, config, enableAnalytics)) { await this.fileService.writeContents(file, contents); } } @@ -382,9 +387,16 @@ export class PortalProjectService { * The browser imports `portal.identity.json` whole, since a retained JSON module is not * tree-shaken per property, which is why it holds nothing that addresses this machine. */ - private appearanceFiles(projectDirectory: DirectoryPath, config: PortalConfig): [FilePath, string][] { + private appearanceFiles( + projectDirectory: DirectoryPath, + config: PortalConfig, + enableAnalytics: boolean + ): [FilePath, string][] { return [ - [new FilePath(projectDirectory, new FileName(IDENTITY_FILE_NAME)), JSON.stringify(config.identity(), null, 2)], + [ + new FilePath(projectDirectory, new FileName(IDENTITY_FILE_NAME)), + JSON.stringify(config.identity(enableAnalytics), null, 2) + ], [ new FilePath(projectDirectory.join('src').join('styles'), new FileName(STYLESHEET_FILE_NAME)), PortalStylesheet.of(config).toString() diff --git a/src/types/portal/config/analytics-config.ts b/src/types/portal/config/analytics-config.ts index 29d19326..191774da 100644 --- a/src/types/portal/config/analytics-config.ts +++ b/src/types/portal/config/analytics-config.ts @@ -11,8 +11,7 @@ export interface GoogleTagManagerSetting { /** Public values: they sit in every page's scripts. */ export interface PortalAnalytics { googleTagManager: GoogleTagManagerSetting | null; - /** `debugMode` is set by the CLI under `portal serve`. */ - googleAnalytics: { measurementId: string; debugMode: boolean } | null; + googleAnalytics: { measurementId: string } | null; keepQueryParams: string[]; } @@ -51,10 +50,10 @@ export class AnalyticsConfig { return this.measurementId !== null; } - public identity(): PortalAnalytics { + public identity(enableAnalytics: boolean): PortalAnalytics { return { - googleTagManager: this.googleTagManager, - googleAnalytics: this.measurementId === null ? null : { measurementId: this.measurementId, debugMode: false }, + googleTagManager: enableAnalytics ? this.googleTagManager : null, + googleAnalytics: enableAnalytics && this.measurementId !== null ? { measurementId: this.measurementId } : null, keepQueryParams: this.keepQueryParams }; } diff --git a/src/types/portal/portal-config.ts b/src/types/portal/portal-config.ts index 87960ae0..0137d016 100644 --- a/src/types/portal/portal-config.ts +++ b/src/types/portal/portal-config.ts @@ -128,7 +128,7 @@ export class PortalConfig { return this.analytics.usesGoogleAnalytics(); } - public identity(): PortalIdentity { + public identity(enableAnalytics: boolean): PortalIdentity { const address = this.site.siteAddress(); const logo = this.brand.logoImages(); const favicon = this.brand.faviconImage(); @@ -141,7 +141,7 @@ export class PortalConfig { colorMode: this.brand.mode(), links: this.navigation.headerLinks().map(portalLink), pageActions: this.ai.offersPageActions(), - analytics: this.analytics.identity(), + analytics: this.analytics.identity(enableAnalytics), seo: this.seo.identity() }; } diff --git a/test/actions/portal/generate.test.ts b/test/actions/portal/generate.test.ts index a10d501f..4a89de38 100644 --- a/test/actions/portal/generate.test.ts +++ b/test/actions/portal/generate.test.ts @@ -38,12 +38,13 @@ describe('GenerateAction', () => { let authorize: sinon.SinonStub; let build: sinon.SinonStub; - const execute = (projectDirectory = FIXTURE, force = false, zip = false) => + const execute = (projectDirectory = FIXTURE, force = false, zip = false, enableAnalytics = true) => new GenerateAction(new DirectoryPath(root), COMMAND_METADATA, 'auth-key').execute( ProjectContext.in(projectDirectory), portalDirectory, force, - zip + zip, + enableAnalytics ); const inPortal = (relative: string) => fs.existsSync(path.join(portalDirectory.toString(), relative)); @@ -119,7 +120,7 @@ describe('GenerateAction', () => { it('fails when the source and destination are the same directory', async () => { const action = new GenerateAction(new DirectoryPath(root), COMMAND_METADATA); - const result = await action.execute(ProjectContext.in(FIXTURE), FIXTURE.join('src'), false, false); + const result = await action.execute(ProjectContext.in(FIXTURE), FIXTURE.join('src'), false, false, true); expect(result.isFailed()).to.be.true; expect(prompts.directoryCannotBeSame.calledOnce).to.be.true; @@ -317,6 +318,13 @@ describe('GenerateAction', () => { expect(shared.prompts.filesShadowedByStatic.firstCall.args[0].map(String)).to.deep.equal(['robots.txt']); }); + it('hands --no-analytics to the project it prepares', async () => { + const result = await execute(FIXTURE, false, false, false); + + expect(result.isSuccess()).to.be.true; + expect(shared.prepare.firstCall.args[3]).to.be.false; + }); + it('warns that Google Analytics counts page changes, before the build, when it is set', async () => { const project = new DirectoryPath(root).join('analytics'); fs.cpSync(FIXTURE.toString(), project.toString(), { recursive: true }); diff --git a/test/actions/portal/prepare-project.test.ts b/test/actions/portal/prepare-project.test.ts index cbb8aa5b..bd47a800 100644 --- a/test/actions/portal/prepare-project.test.ts +++ b/test/actions/portal/prepare-project.test.ts @@ -31,6 +31,7 @@ describe('PreparePortalProjectAction', () => { const result = await new PreparePortalProjectAction(new DirectoryPath(os.tmpdir()), COMMAND_METADATA).execute( ProjectContext.in(share), + true, { onPrepared } ); @@ -45,9 +46,10 @@ describe('PreparePortalProjectAction', () => { let shared: PreparePortalProjectStubs; let onPrepared: sinon.SinonStub; - const execute = () => + const execute = (enableAnalytics = true) => new PreparePortalProjectAction(new DirectoryPath(os.tmpdir()), COMMAND_METADATA).execute( ProjectContext.in(FIXTURE), + enableAnalytics, { onPrepared } ); @@ -71,6 +73,12 @@ describe('PreparePortalProjectAction', () => { expect(uploaded.filter((entry) => entry.startsWith('static/'))).to.be.empty; }); + it('hands --no-analytics to the project it prepares', async () => { + await execute(false); + + expect(shared.prepare.firstCall.args[3]).to.be.false; + }); + it('reports a source it could not zip, without asking for the artifacts', async () => { const problem: FileProblem = { kind: 'zipFailed', reason: 'EBUSY: resource busy or locked' }; sinon.stub(TempContext.prototype, 'zip').resolves(err(problem)); diff --git a/test/actions/portal/serve.test.ts b/test/actions/portal/serve.test.ts index 60f2ba9f..b3e2417e 100644 --- a/test/actions/portal/serve.test.ts +++ b/test/actions/portal/serve.test.ts @@ -45,11 +45,12 @@ describe('PortalServeAction', () => { /** Stands in for the preview process dying, with what it printed on the way out. */ let exit: (output: string) => void; - const execute = (projectDirectory = FIXTURE, openInBrowser = false) => + const execute = (projectDirectory = FIXTURE, openInBrowser = false, enableAnalytics = true) => new PortalServeAction(new DirectoryPath(root), COMMAND_METADATA, 'auth-key').execute( ProjectContext.in(projectDirectory), PORT, - openInBrowser + openInBrowser, + enableAnalytics ); /** Stands in for the watch on `directory`, answered by `watching`; any other tree's watch is left alone. */ @@ -608,8 +609,8 @@ describe('PortalServeAction', () => { fs.writeFileSync(path.join(source.toString(), 'apimatic.json'), JSON.stringify(config)); /** Runs the preview until `body` is done with it, then stops it as CTRL+C would. */ - const whileServing = async (body: () => Promise) => { - const running = execute(new DirectoryPath(root)); + const whileServing = async (body: () => Promise, enableAnalytics = true) => { + const running = execute(new DirectoryPath(root), false, enableAnalytics); const { onChange } = await watched; save = async (config: object) => { writeConfig(config); @@ -630,10 +631,10 @@ describe('PortalServeAction', () => { // `prepare` is stubbed above; this one writes the files an edit can change, as a real one // would, so the test can see what an edit changes. (PortalProjectService.prototype.prepare as sinon.SinonStub).callsFake( - async (directory: DirectoryPath, portal: PortalSource) => { + async (directory: DirectoryPath, portal: PortalSource, _artifacts: unknown, enableAnalytics: boolean) => { projectDirectory = directory; fs.mkdirSync(path.join(directory.toString(), 'src/styles'), { recursive: true }); - (await new PortalProjectService().applyConfig(directory, portal))._unsafeUnwrap(); + (await new PortalProjectService().applyConfig(directory, portal, enableAnalytics))._unsafeUnwrap(); return ok({ projectDirectory: directory, viteBinary: new FilePath(directory, new FileName('vite.js')), @@ -890,6 +891,18 @@ describe('PortalServeAction', () => { }); }); + it('keeps --no-analytics for the rewrite when the block changes', async () => { + const applyConfig = sinon.spy(PortalProjectService.prototype, 'applyConfig'); + + await whileServing(async () => { + const config = originalConfig(); + config.portal.site.name = 'Renamed API'; + await save(config); + }, false); + + expect(applyConfig.lastCall.args[2]).to.be.false; + }); + it('reports a change it could not write to the preview', async () => { await whileServing(async () => { sinon.stub(PortalProjectService.prototype, 'applyConfig').resolves(err('EACCES: permission denied')); diff --git a/test/commands/portal/generate-flags.test.ts b/test/commands/portal/generate-flags.test.ts new file mode 100644 index 00000000..67dc7aee --- /dev/null +++ b/test/commands/portal/generate-flags.test.ts @@ -0,0 +1,15 @@ +import { expect } from 'chai'; +import PortalGenerate from '../../../src/commands/portal/generate.js'; +import { flagParser } from '../flag-parser.js'; + +const { parse } = flagParser(PortalGenerate); + +describe('portal generate flags', () => { + it('accepts --no-analytics, off unless passed', async () => { + const given = (await parse(['--no-analytics'])) as never as { flags: Record }; + const omitted = (await parse([])) as never as { flags: Record }; + + expect(given.flags['no-analytics']).to.be.true; + expect(omitted.flags['no-analytics']).to.be.false; + }); +}); diff --git a/test/commands/portal/serve-flags.test.ts b/test/commands/portal/serve-flags.test.ts new file mode 100644 index 00000000..e0df05a8 --- /dev/null +++ b/test/commands/portal/serve-flags.test.ts @@ -0,0 +1,15 @@ +import { expect } from 'chai'; +import PortalServe from '../../../src/commands/portal/serve.js'; +import { flagParser } from '../flag-parser.js'; + +const { parse } = flagParser(PortalServe); + +describe('portal serve flags', () => { + it('accepts --no-analytics, off unless passed', async () => { + const given = (await parse(['--no-analytics'])) as never as { flags: Record }; + const omitted = (await parse([])) as never as { flags: Record }; + + expect(given.flags['no-analytics']).to.be.true; + expect(omitted.flags['no-analytics']).to.be.false; + }); +}); diff --git a/test/e2e/portal-build.test.ts b/test/e2e/portal-build.test.ts index 3bf144d2..d220e741 100644 --- a/test/e2e/portal-build.test.ts +++ b/test/e2e/portal-build.test.ts @@ -75,7 +75,7 @@ async function buildFixture(name: string, delivered: Delivered = {}): Promise { describe('prepare', () => { it('installs every dependency the template imports, resolved to a real package', async () => { - (await service.prepare(project, sourceFor(), NO_ARTIFACTS))._unsafeUnwrap(); + (await service.prepare(project, sourceFor(), NO_ARTIFACTS, true))._unsafeUnwrap(); const modules = path.join(project.toString(), 'node_modules'); const installed = fs @@ -136,7 +136,7 @@ describe('PortalProjectService', () => { // Vite refuses an 8.3 short name outright, and compares the real path against its allow list. it('links each dependency, and names the Vite binary, by its real path', async () => { - const prepared = (await service.prepare(project, sourceFor(), NO_ARTIFACTS))._unsafeUnwrap(); + const prepared = (await service.prepare(project, sourceFor(), NO_ARTIFACTS, true))._unsafeUnwrap(); for (const name of LINKED_DEPENDENCIES) { const link = path.join(project.toString(), 'node_modules', name); @@ -148,7 +148,7 @@ describe('PortalProjectService', () => { // Linked, their `url()`s would resolve from the CLI's install, which may be on another drive. it('copies the font packages into the project instead of linking them', async () => { - (await service.prepare(project, sourceFor(), NO_ARTIFACTS))._unsafeUnwrap(); + (await service.prepare(project, sourceFor(), NO_ARTIFACTS, true))._unsafeUnwrap(); for (const name of COPIED_DEPENDENCIES) { const directory = path.join(project.toString(), 'node_modules', name); @@ -158,14 +158,14 @@ describe('PortalProjectService', () => { }); it('copies the template rather than moving it', async () => { - (await service.prepare(project, sourceFor(), NO_ARTIFACTS))._unsafeUnwrap(); + (await service.prepare(project, sourceFor(), NO_ARTIFACTS, true))._unsafeUnwrap(); expect(fs.existsSync(path.join(process.cwd(), 'portal-template', 'vite.config.ts'))).to.be.true; expect(fs.existsSync(path.join(project.toString(), 'vite.config.ts'))).to.be.true; }); it('writes the specs and the directories into the build-only config', async () => { - (await service.prepare(project, sourceFor(), NO_ARTIFACTS))._unsafeUnwrap(); + (await service.prepare(project, sourceFor(), NO_ARTIFACTS, true))._unsafeUnwrap(); const config = readConfig(); expect(Object.keys(config).sort()).to.deep.equal([ @@ -187,20 +187,25 @@ describe('PortalProjectService', () => { it('builds the portal under the path of its address', async () => { const config = configFor({ site: { name: 'My API', url: 'https://example.com/Docs/v2.1/' } }); - (await service.prepare(project, sourceFor({ config }), NO_ARTIFACTS))._unsafeUnwrap(); + (await service.prepare(project, sourceFor({ config }), NO_ARTIFACTS, true))._unsafeUnwrap(); expect(readConfig().base).to.equal('/Docs/v2.1/'); }); it('builds the portal at the root when it has no address', async () => { - (await service.prepare(project, sourceFor(), NO_ARTIFACTS))._unsafeUnwrap(); + (await service.prepare(project, sourceFor(), NO_ARTIFACTS, true))._unsafeUnwrap(); expect(readConfig().base).to.equal('/'); }); it('writes the generated pages into the project, and names their directory in the build-only config', async () => { ( - await service.prepare(project, sourceFor({ generatedPages: pagesFor({ typescript: {} }, true) }), NO_ARTIFACTS) + await service.prepare( + project, + sourceFor({ generatedPages: pagesFor({ typescript: {} }, true) }), + NO_ARTIFACTS, + true + ) )._unsafeUnwrap(); expect(generatedFiles()).to.deep.equal([ @@ -221,9 +226,9 @@ describe('PortalProjectService', () => { brand: { logo: 'static/images/logo.png' } }); - (await service.prepare(project, sourceFor({ config }), NO_ARTIFACTS))._unsafeUnwrap(); + (await service.prepare(project, sourceFor({ config }), NO_ARTIFACTS, true))._unsafeUnwrap(); - expect(readIdentity()).to.deep.equal(config.identity()); + expect(readIdentity()).to.deep.equal(config.identity(true)); expect(readIdentity().logo).to.deep.equal({ light: '/images/logo.png', dark: '/images/logo.png' }); expect(readIdentity().siteUrl).to.equal('https://docs.example.com'); }); @@ -234,7 +239,7 @@ describe('PortalProjectService', () => { const contentDirectory = new DirectoryPath(root).join('content'); fs.mkdirSync(contentDirectory.toString(), { recursive: true }); - (await service.prepare(project, sourceFor({ contentDirectory }), NO_ARTIFACTS))._unsafeUnwrap(); + (await service.prepare(project, sourceFor({ contentDirectory }), NO_ARTIFACTS, true))._unsafeUnwrap(); for (const file of ['portal.identity.json', 'src/lib/source.ts', 'src/styles/app.css']) { const contents = fs.readFileSync(path.join(project.toString(), file), 'utf8'); @@ -250,7 +255,7 @@ describe('PortalProjectService', () => { brand: { colors: { primary: '#1d4ed8' } } }); - (await service.prepare(project, sourceFor({ config }), NO_ARTIFACTS))._unsafeUnwrap(); + (await service.prepare(project, sourceFor({ config }), NO_ARTIFACTS, true))._unsafeUnwrap(); const styles = path.join(project.toString(), 'src/styles'); expect(fs.readFileSync(path.join(styles, 'theme.css'), 'utf8')).to.equal(PortalStylesheet.of(config).toString()); @@ -258,7 +263,7 @@ describe('PortalProjectService', () => { }); it('leaves no identity placeholder in the module the browser receives', async () => { - (await service.prepare(project, sourceFor(), NO_ARTIFACTS))._unsafeUnwrap(); + (await service.prepare(project, sourceFor(), NO_ARTIFACTS, true))._unsafeUnwrap(); const module = fs.readFileSync(path.join(project.toString(), 'src/lib/portal.ts'), 'utf8'); expect(module).to.not.contain('__APIMATIC_'); @@ -272,7 +277,7 @@ describe('PortalProjectService', () => { fs.symlinkSync(real, path.join(root, 'linked'), 'junction'); const staticDirectory = new DirectoryPath(root).join('linked', 'static'); - (await service.prepare(project, sourceFor({ staticDirectory }), NO_ARTIFACTS))._unsafeUnwrap(); + (await service.prepare(project, sourceFor({ staticDirectory }), NO_ARTIFACTS, true))._unsafeUnwrap(); expect(readConfig().staticDir).to.equal( path.join(fs.realpathSync.native(real), 'static').split(path.sep).join('/') @@ -280,13 +285,13 @@ describe('PortalProjectService', () => { }); it('reports no static directory when the project has none', async () => { - (await service.prepare(project, sourceFor(), NO_ARTIFACTS))._unsafeUnwrap(); + (await service.prepare(project, sourceFor(), NO_ARTIFACTS, true))._unsafeUnwrap(); expect(readConfig().staticDir).to.be.null; }); it('creates an empty content directory when the project has none, so the build has one to read', async () => { - (await service.prepare(project, sourceFor(), NO_ARTIFACTS))._unsafeUnwrap(); + (await service.prepare(project, sourceFor(), NO_ARTIFACTS, true))._unsafeUnwrap(); const config = readConfig(); expect(fs.existsSync(config.contentDir)).to.be.true; @@ -324,7 +329,7 @@ describe('PortalProjectService', () => { const writtenSamples = () => JSON.parse(fs.readFileSync(readConfig().codeSamples, 'utf8')); it('writes the samples beside the configuration, keyed by path and method, and names them in it', async () => { - (await service.prepare(project, sourceFor(), withCatalogs))._unsafeUnwrap(); + (await service.prepare(project, sourceFor(), withCatalogs, true))._unsafeUnwrap(); const config = readConfig(); expect(config.codeSamples).to.equal(path.join(project.toString(), 'code-samples.json').split(path.sep).join('/')); @@ -333,7 +338,7 @@ describe('PortalProjectService', () => { // The samples hold one per method and path, which would be another API's call on all but one of the pages. it('leaves out the samples of an operation more than one spec declares', async () => { - (await service.prepare(project, sharingSource(), withCatalogs))._unsafeUnwrap(); + (await service.prepare(project, sharingSource(), withCatalogs, true))._unsafeUnwrap(); expect(writtenSamples()).to.deep.equal({ paths: {}, specs: {} }); }); @@ -354,7 +359,7 @@ describe('PortalProjectService', () => { undefined ); - (await service.prepare(project, sharingSource(), filed))._unsafeUnwrap(); + (await service.prepare(project, sharingSource(), filed, true))._unsafeUnwrap(); expect(writtenSamples()).to.deep.equal({ paths: {}, @@ -368,12 +373,12 @@ describe('PortalProjectService', () => { it('points each spec at its own file, samples or not', async () => { const source = sourceFor(); - (await service.prepare(project, source, withCatalogs))._unsafeUnwrap(); + (await service.prepare(project, source, withCatalogs, true))._unsafeUnwrap(); expect(readConfig().specs.calculator).to.equal(source.specs[0].file.toString().split(path.sep).join('/')); }); it('names no samples when there are none', async () => { - (await service.prepare(project, sourceFor(), NO_ARTIFACTS))._unsafeUnwrap(); + (await service.prepare(project, sourceFor(), NO_ARTIFACTS, true))._unsafeUnwrap(); expect(readConfig().codeSamples).to.be.null; expect(fs.existsSync(path.join(project.toString(), 'code-samples.json'))).to.be.false; @@ -400,7 +405,7 @@ describe('PortalProjectService', () => { downloaded('c.zip', 'PK plugin') ); - (await service.prepare(project, sourceFor(), artifacts))._unsafeUnwrap(); + (await service.prepare(project, sourceFor(), artifacts, true))._unsafeUnwrap(); expect(fs.readFileSync(downloadsFile('sdk', 'csharp.zip'), 'utf8')).to.equal('PK csharp'); expect(fs.readFileSync(downloadsFile('sdk', 'python.zip'), 'utf8')).to.equal('PK python'); @@ -416,13 +421,13 @@ describe('PortalProjectService', () => { downloaded('c.zip', 'PK plugin') ); - (await service.prepare(project, sourceFor(), artifacts))._unsafeUnwrap(); + (await service.prepare(project, sourceFor(), artifacts, true))._unsafeUnwrap(); expect(fs.readdirSync(downloadsFile())).to.deep.equal(['plugin.zip']); }); it('names no downloads when the run carried none', async () => { - (await service.prepare(project, sourceFor(), NO_ARTIFACTS))._unsafeUnwrap(); + (await service.prepare(project, sourceFor(), NO_ARTIFACTS, true))._unsafeUnwrap(); expect(readConfig().downloadsDir).to.be.null; expect(fs.existsSync(downloadsFile())).to.be.false; @@ -442,7 +447,7 @@ describe('PortalProjectService', () => { undefined ); - (await service.prepare(project, sourceFor(), artifacts))._unsafeUnwrap(); + (await service.prepare(project, sourceFor(), artifacts, true))._unsafeUnwrap(); expect(includesFile('sdk-docs', 'typescript.md')).to.equal('## Installation\n\nnpm install calc\n'); expect(generatedFiles()).to.not.include('sdk-docs/typescript.md'); @@ -480,7 +485,7 @@ describe('PortalProjectService', () => { }); const prepareCopy = async () => - (await service.prepare(project, sourceFor({ contentDirectory: content }), NO_ARTIFACTS))._unsafeUnwrap(); + (await service.prepare(project, sourceFor({ contentDirectory: content }), NO_ARTIFACTS, true))._unsafeUnwrap(); // The dev server lists the pages once, when it starts, so the copy has to be whole by then. it('is made while the project is prepared, of every file but those the build never reads', async () => { @@ -540,9 +545,31 @@ describe('PortalProjectService', () => { const themeFile = () => path.join(project.toString(), 'src/styles/theme.css'); const identityFile = () => path.join(project.toString(), 'portal.identity.json'); + it('writes neither vendor under --no-analytics, and both once analytics are on again', async () => { + const config = configFor({ + site: { name: 'My API' }, + analytics: { googleTagManager: { containerId: 'GTM-ABC123' }, googleAnalytics: { measurementId: 'G-ABC123' } } + }); + (await service.prepare(project, sourceFor({ config }), NO_ARTIFACTS, false))._unsafeUnwrap(); + + expect(readIdentity().analytics).to.deep.equal({ + googleTagManager: null, + googleAnalytics: null, + keepQueryParams: [] + }); + + expect((await service.applyConfig(project, settingsFor(config), true))._unsafeUnwrap()).to.be.true; + + expect(readIdentity().analytics).to.deep.equal({ + googleTagManager: { containerId: 'GTM-ABC123', environment: null }, + googleAnalytics: { measurementId: 'G-ABC123' }, + keepQueryParams: [] + }); + }); + it('writes nothing, and says so, when the block makes the same site', async () => { const config = configFor({ site: { name: 'My API' }, brand: { colors: { primary: '#1d4ed8' } } }); - (await service.prepare(project, sourceFor({ config }), NO_ARTIFACTS))._unsafeUnwrap(); + (await service.prepare(project, sourceFor({ config }), NO_ARTIFACTS, true))._unsafeUnwrap(); const before = [fs.statSync(themeFile()).mtimeMs, fs.statSync(identityFile()).mtimeMs]; // Written differently, read the same: the comparison is of what the preview shows. @@ -551,31 +578,31 @@ describe('PortalProjectService', () => { brand: { colors: { primary: '#1d4ed8' } }, ai: { pageActions: true } }); - const applied = await service.applyConfig(project, settingsFor(same)); + const applied = await service.applyConfig(project, settingsFor(same), true); expect(applied._unsafeUnwrap()).to.be.false; expect([fs.statSync(themeFile()).mtimeMs, fs.statSync(identityFile()).mtimeMs]).to.deep.equal(before); }); it('rewrites both files for a brand change, to what a fresh build would write', async () => { - (await service.prepare(project, sourceFor(), NO_ARTIFACTS))._unsafeUnwrap(); + (await service.prepare(project, sourceFor(), NO_ARTIFACTS, true))._unsafeUnwrap(); const config = configFor({ site: { name: 'My API' }, brand: { colors: { primary: '#1d4ed8' }, colorMode: 'dark' } }); - expect((await service.applyConfig(project, settingsFor(config)))._unsafeUnwrap()).to.be.true; + expect((await service.applyConfig(project, settingsFor(config), true))._unsafeUnwrap()).to.be.true; expect(fs.readFileSync(themeFile(), 'utf8')).to.equal(PortalStylesheet.of(config).toString()); - expect(readIdentity()).to.deep.equal(config.identity()); + expect(readIdentity()).to.deep.equal(config.identity(true)); }); it('leaves the stylesheet alone when only what the browser is told changes', async () => { - (await service.prepare(project, sourceFor(), NO_ARTIFACTS))._unsafeUnwrap(); + (await service.prepare(project, sourceFor(), NO_ARTIFACTS, true))._unsafeUnwrap(); const before = fs.statSync(themeFile()).mtimeMs; const renamed = configFor({ site: { name: 'Renamed API' } }); - expect((await service.applyConfig(project, settingsFor(renamed)))._unsafeUnwrap()).to.be.true; + expect((await service.applyConfig(project, settingsFor(renamed), true))._unsafeUnwrap()).to.be.true; expect(readIdentity().name).to.equal('Renamed API'); expect(fs.statSync(themeFile()).mtimeMs).to.equal(before); @@ -583,12 +610,12 @@ describe('PortalProjectService', () => { // The dev server is watching both files, and could read one truncated before it is written. it('replaces each file whole rather than writing it in place', async () => { - (await service.prepare(project, sourceFor(), NO_ARTIFACTS))._unsafeUnwrap(); + (await service.prepare(project, sourceFor(), NO_ARTIFACTS, true))._unsafeUnwrap(); const replace = sinon.spy(FileService.prototype, 'replaceContents'); const write = sinon.spy(FileService.prototype, 'writeContents'); const config = configFor({ site: { name: 'Renamed API' }, brand: { colors: { primary: '#1d4ed8' } } }); - expect((await service.applyConfig(project, settingsFor(config)))._unsafeUnwrap()).to.be.true; + expect((await service.applyConfig(project, settingsFor(config), true))._unsafeUnwrap()).to.be.true; expect(replace.args.map(([file]) => file.toString())).to.deep.equal([identityFile(), themeFile()]); expect(write.called).to.be.false; @@ -599,31 +626,37 @@ describe('PortalProjectService', () => { const blocked = new DirectoryPath(root).join('blocked'); fs.writeFileSync(blocked.toString(), ''); - const applied = await service.applyConfig(blocked, settingsFor(configFor({ site: { name: 'My API' } }))); + const applied = await service.applyConfig(blocked, settingsFor(configFor({ site: { name: 'My API' } })), true); expect(applied.isErr()).to.be.true; }); it('writes the page for a language added, and says so', async () => { - (await service.prepare(project, sourceFor(), NO_ARTIFACTS))._unsafeUnwrap(); + (await service.prepare(project, sourceFor(), NO_ARTIFACTS, true))._unsafeUnwrap(); const config = sourceFor().config; - const applied = await service.applyConfig(project, settingsFor(config, pagesFor({ typescript: {}, python: {} }))); + const applied = await service.applyConfig( + project, + settingsFor(config, pagesFor({ typescript: {}, python: {} })), + true + ); expect(applied._unsafeUnwrap()).to.be.true; expect(generatedFiles()).to.include('sdks/python.mdx'); }); it('writes the context plugin folder for a plugin block added, and removes it with the block', async () => { - (await service.prepare(project, sourceFor(), NO_ARTIFACTS))._unsafeUnwrap(); + (await service.prepare(project, sourceFor(), NO_ARTIFACTS, true))._unsafeUnwrap(); const config = sourceFor().config; expect( - (await service.applyConfig(project, settingsFor(config, pagesFor({ typescript: {} }, true))))._unsafeUnwrap() + ( + await service.applyConfig(project, settingsFor(config, pagesFor({ typescript: {} }, true)), true) + )._unsafeUnwrap() ).to.be.true; expect(generatedFiles()).to.include.members(['context-plugin/index.mdx', 'context-plugin/nav.json']); - expect((await service.applyConfig(project, settingsFor(config)))._unsafeUnwrap()).to.be.true; + expect((await service.applyConfig(project, settingsFor(config), true))._unsafeUnwrap()).to.be.true; expect(fs.existsSync(path.join(project.toString(), GENERATED_DIRECTORY_NAME, 'context-plugin'))).to.be.false; }); }); diff --git a/test/portal-template/analytics.test.ts b/test/portal-template/analytics.test.ts index 422c1de4..f0278391 100644 --- a/test/portal-template/analytics.test.ts +++ b/test/portal-template/analytics.test.ts @@ -169,14 +169,11 @@ const withGtm = (environment: { auth: string; preview: string } | null = null): ...none, googleTagManager: { containerId: 'GTM-ABC123', environment } }); -const withGa4 = (debugMode = false): PortalAnalytics => ({ - ...none, - googleAnalytics: { measurementId: 'G-ABC123', debugMode } -}); +const withGa4: PortalAnalytics = { ...none, googleAnalytics: { measurementId: 'G-ABC123' } }; const withBoth: PortalAnalytics = { ...none, googleTagManager: withGtm().googleTagManager, - googleAnalytics: withGa4().googleAnalytics + googleAnalytics: withGa4.googleAnalytics }; const GTM_SCRIPT = 'https://www.googletagmanager.com/gtm.js?id=GTM-ABC123'; const GA4_SCRIPT = 'https://www.googletagmanager.com/gtag/js?id=G-ABC123'; @@ -260,7 +257,7 @@ describe('Analytics', () => { it('pushes js and config with its own page view off, and inserts gtag.js', () => { const page = browser(quickstart); - new Analytics(withGa4()).start(); + new Analytics(withGa4).start(); const [js, config, ...rest] = gtagCalls(page.dataLayer()); expect(js[0]).to.equal('js'); @@ -273,7 +270,7 @@ describe('Analytics', () => { it('sends each page view as page_view, without the prefix, after the reset and event entries', () => { const page = browser(quickstart); - const analytics = new Analytics(withGa4()); + const analytics = new Analytics(withGa4); analytics.start(); analytics.reportPageView(); @@ -287,7 +284,7 @@ describe('Analytics', () => { it('pushes Arguments objects, which gtag.js reads, never arrays of the same values', () => { const page = browser(quickstart); - const analytics = new Analytics(withGa4()); + const analytics = new Analytics(withGa4); analytics.start(); analytics.reportPageView(); @@ -296,18 +293,6 @@ describe('Analytics', () => { expect(page.dataLayer().some(Array.isArray)).to.be.false; }); - it('marks events as debug traffic in a preview', () => { - const page = browser(quickstart); - - new Analytics(withGa4(true)).start(); - - expect(gtagCalls(page.dataLayer())[1]).to.deep.equal([ - 'config', - 'G-ABC123', - { send_page_view: false, debug_mode: true } - ]); - }); - it('uses a gtag the page already defines, rather than replacing it', () => { const page = browser(quickstart); const calls: unknown[][] = []; @@ -315,7 +300,7 @@ describe('Analytics', () => { calls.push(command); }; page.window.gtag = existing; - const analytics = new Analytics(withGa4()); + const analytics = new Analytics(withGa4); analytics.start(); analytics.reportPageView(); @@ -408,8 +393,8 @@ describe('Analytics', () => { }, { vendor: 'googleAnalytics', - settings: withGa4(), - adapter: () => adapters.googleAnalytics({ measurementId: 'G-ABC123', debugMode: false }), + settings: withGa4, + adapter: () => adapters.googleAnalytics({ measurementId: 'G-ABC123' }), pageViewCall: (entries) => expect(gtagCalls(entries).at(-1)?.slice(0, 2)).to.deep.equal(['event', 'page_view']) } ]; diff --git a/test/types/portal-source-context.test.ts b/test/types/portal-source-context.test.ts index 27d6e499..20dbe950 100644 --- a/test/types/portal-source-context.test.ts +++ b/test/types/portal-source-context.test.ts @@ -144,7 +144,7 @@ describe('PortalSourceContext', () => { const { config } = (await resolve())._unsafeUnwrap(); expect(config.siteTitle()).to.equal('Calc'); - expect(config.identity().description).to.equal('Adds.'); + expect(config.identity(true).description).to.equal('Adds.'); }); it('lets the block describe the portal instead, or not at all', async () => { @@ -154,9 +154,9 @@ describe('PortalSourceContext', () => { ); writeConfig({ site: { description: 'Our docs.' } }); - expect((await resolve())._unsafeUnwrap().config.identity().description).to.equal('Our docs.'); + expect((await resolve())._unsafeUnwrap().config.identity(true).description).to.equal('Our docs.'); writeConfig({ site: { description: '' } }); - expect((await resolve())._unsafeUnwrap().config.identity().description).to.be.null; + expect((await resolve())._unsafeUnwrap().config.identity(true).description).to.be.null; }); // No one of several specifications speaks for the whole portal. @@ -2636,7 +2636,7 @@ describe('PortalSourceContext', () => { const empty = (await new PortalSourceContext(source).resolve())._unsafeUnwrap().config; expect(scaffolded.toJSON()).to.deep.equal(empty.toJSON()); - expect(scaffolded.identity()).to.deep.equal(empty.identity()); + expect(scaffolded.identity(true)).to.deep.equal(empty.identity(true)); }); // Every block the wizard writes has to pass the schema it points editors at. diff --git a/test/types/portal/portal-config.test.ts b/test/types/portal/portal-config.test.ts index 381e6c28..2a2615a0 100644 --- a/test/types/portal/portal-config.test.ts +++ b/test/types/portal/portal-config.test.ts @@ -28,7 +28,7 @@ describe('PortalConfig', () => { it('builds a portal from an empty block, with every default', () => { const portal = config({}); - const identity = portal.identity(); + const identity = portal.identity(true); expect(portal.siteTitle()).to.equal('Spec Title'); expect(identity.description).to.equal('What the spec says.'); @@ -120,17 +120,17 @@ describe('PortalConfig', () => { }); it('has no description with several specifications unless the block gives one', () => { - expect(config({ site: { name: 'Calc' } }, null).identity().description).to.be.null; + expect(config({ site: { name: 'Calc' } }, null).identity(true).description).to.be.null; }); it('trims the description', () => { - expect(config({ site: { description: ' Docs ' } }).identity().description).to.equal('Docs'); + expect(config({ site: { description: ' Docs ' } }).identity(true).description).to.equal('Docs'); }); // Blank is how the block turns the specification's description off. it('treats a blank description as none, not as absent', () => { for (const description of ['', ' ', '\n\t']) { - expect(config({ site: { description } }).identity().description, JSON.stringify(description)).to.be.null; + expect(config({ site: { description } }).identity(true).description, JSON.stringify(description)).to.be.null; } }); @@ -139,13 +139,13 @@ describe('PortalConfig', () => { }); it('keeps the path of the address, dropping a trailing slash and keeping a port', () => { - expect(config({ site: { url: 'https://docs.example.com/' } }).identity().siteUrl).to.equal( + expect(config({ site: { url: 'https://docs.example.com/' } }).identity(true).siteUrl).to.equal( 'https://docs.example.com' ); - expect(config({ site: { url: 'https://docs.example.com:8443' } }).identity().siteUrl).to.equal( + expect(config({ site: { url: 'https://docs.example.com:8443' } }).identity(true).siteUrl).to.equal( 'https://docs.example.com:8443' ); - expect(config({ site: { url: 'HTTPS://Example.com/Docs/v2/' } }).identity().siteUrl).to.equal( + expect(config({ site: { url: 'HTTPS://Example.com/Docs/v2/' } }).identity(true).siteUrl).to.equal( 'https://example.com/Docs/v2' ); }); @@ -319,7 +319,7 @@ describe('PortalConfig', () => { { label: 'Auth', url: '/authentication' } ] } - }).identity(); + }).identity(true); expect(links).to.deep.equal([ { label: 'Status', url: 'https://status.example.com', external: true }, @@ -367,7 +367,7 @@ describe('PortalConfig', () => { it('writes a page of the portal as the browser resolves it', () => { const [link] = config({ navigation: { links: [{ label: 'x', url: '/guides/../start here?tab=1#top' }] } - }).identity().links; + }).identity(true).links; expect(link.url).to.equal('/start%20here?tab=1#top'); }); @@ -390,7 +390,7 @@ describe('PortalConfig', () => { // Each page offers to open itself in ChatGPT, Claude, Cursor or Scira. A portal // published under someone else's brand carries that endorsement, so it can be refused. it('offers the page actions unless the block turns them off', () => { - expect(config({ ai: { pageActions: false } }).identity().pageActions).to.be.false; + expect(config({ ai: { pageActions: false } }).identity(true).pageActions).to.be.false; expect(errorsOf({ ai: { pageActions: 'no' } })).to.deep.equal(["'portal.ai.pageActions' must be true or false."]); }); }); @@ -401,7 +401,7 @@ describe('PortalConfig', () => { const keep = 'portal.analytics.keepQueryParams'; it('tells the browser to load nothing when the block sets nothing', () => { - expect(config({}).identity().analytics).to.deep.equal({ + expect(config({}).identity(true).analytics).to.deep.equal({ googleTagManager: null, googleAnalytics: null, keepQueryParams: [] @@ -416,9 +416,9 @@ describe('PortalConfig', () => { keepQueryParams: ['campaign_id', ' code '] }; - expect(config({ analytics }).identity().analytics).to.deep.equal({ + expect(config({ analytics }).identity(true).analytics).to.deep.equal({ googleTagManager: { containerId: 'GTM-ABC123', environment: { auth: 'a1_b-2', preview: 'env-3' } }, - googleAnalytics: { measurementId: 'G-ABC123', debugMode: false }, + googleAnalytics: { measurementId: 'G-ABC123' }, keepQueryParams: ['campaign_id', 'code'] }); }); @@ -448,7 +448,8 @@ describe('PortalConfig', () => { `'${ga}.measurementId' must be a non-empty string.` ]); expect( - config({ analytics: { googleTagManager: { containerId: 'gtm-abc123' } } }).identity().analytics.googleTagManager + config({ analytics: { googleTagManager: { containerId: 'gtm-abc123' } } }).identity(true).analytics + .googleTagManager ).to.deep.equal({ containerId: 'gtm-abc123', environment: null }); }); @@ -515,6 +516,20 @@ describe('PortalConfig', () => { ]); }); + it('tells the browser to load neither vendor under --no-analytics, and still which names to keep', () => { + const analytics = { + googleTagManager: { containerId: 'GTM-ABC123' }, + googleAnalytics: { measurementId: 'G-ABC123' }, + keepQueryParams: ['campaign_id'] + }; + + expect(config({ analytics }).identity(false).analytics).to.deep.equal({ + googleTagManager: null, + googleAnalytics: null, + keepQueryParams: ['campaign_id'] + }); + }); + it('uses Google Analytics only with a measurement ID', () => { expect(config({}).usesGoogleAnalytics()).to.be.false; expect(config({ analytics: { googleTagManager: { containerId: 'GTM-ABC123' } } }).usesGoogleAnalytics()).to.be @@ -541,10 +556,10 @@ describe('PortalConfig', () => { describe('seo', () => { it('carries the verification value to the browser, or null without one', () => { - expect(config({ seo: { googleSiteVerification: 'abc_123-XYZ' } }).identity().seo).to.deep.equal({ + expect(config({ seo: { googleSiteVerification: 'abc_123-XYZ' } }).identity(true).seo).to.deep.equal({ googleSiteVerification: 'abc_123-XYZ' }); - expect(config({}).identity().seo).to.deep.equal({ googleSiteVerification: null }); + expect(config({}).identity(true).seo).to.deep.equal({ googleSiteVerification: null }); }); it('refuses a block that is not an object, and a blank value', () => { @@ -613,7 +628,9 @@ describe('PortalConfig', () => { }); it('is kept out of what the browser is told', () => { - expect(config({ pluginUrl: 'https://plugins.acme.test/calc.zip' }).identity()).to.not.have.property('pluginUrl'); + expect(config({ pluginUrl: 'https://plugins.acme.test/calc.zip' }).identity(true)).to.not.have.property( + 'pluginUrl' + ); }); it('is serialised only when the block gives one', () => { @@ -642,7 +659,7 @@ describe('PortalConfig', () => { ai: { pageActions: false } }); - expect(portal.identity()).to.deep.equal({ + expect(portal.identity(true)).to.deep.equal({ name: 'My API', description: 'Docs', siteUrl: 'https://docs.example.com', @@ -660,7 +677,7 @@ describe('PortalConfig', () => { }); it('reports absent settings as null rather than leaving them out', () => { - expect(PortalConfig.scaffolded({ name: 'My API', description: null }).identity()).to.deep.equal({ + expect(PortalConfig.scaffolded({ name: 'My API', description: null }).identity(true)).to.deep.equal({ name: 'My API', description: null, siteUrl: null, @@ -677,21 +694,22 @@ describe('PortalConfig', () => { // One image serves both modes, so the browser is told the same address twice rather than // having to know that a missing dark variant means the light one. it('names one logo for both modes when the block names one', () => { - expect(config({ brand: { logo: 'static/logo.svg' } }).identity().logo).to.deep.equal({ + expect(config({ brand: { logo: 'static/logo.svg' } }).identity(true).logo).to.deep.equal({ light: '/logo.svg', dark: '/logo.svg' }); }); it('takes the favicon from the light logo when the block names none', () => { - const favicon = config({ brand: { logo: { light: 'static/light.png', dark: 'static/dark.png' } } }).identity() - .favicon; + const favicon = config({ brand: { logo: { light: 'static/light.png', dark: 'static/dark.png' } } }).identity( + true + ).favicon; expect(favicon).to.deep.equal({ url: '/light.png', type: 'image/png' }); }); it('types the favicon by its extension, whatever its case, and leaves an unknown one untyped', () => { - const typeOf = (favicon: string) => config({ brand: { favicon } }).identity().favicon?.type; + const typeOf = (favicon: string) => config({ brand: { favicon } }).identity(true).favicon?.type; expect(typeOf('static/favicon.ICO')).to.equal('image/x-icon'); expect(typeOf('static/icons/app.jpeg')).to.equal('image/jpeg'); From 7b1bcf88f82717f3b99ee99a77d7482753b0cc4f Mon Sep 17 00:00:00 2001 From: Muhammad Sohail Date: Thu, 12 Nov 2026 12:36:59 +0500 Subject: [PATCH 13/73] feat(portal): describe portal.analytics and portal.seo in the schema Editors now offer both blocks. Every ID, environment value, kept name and the verification token is any non-blank string, as the parser reads them, so the schema carries no pattern and refuses nothing the parser accepts; the schema test holds the two to the same verdict on each case, including the formats the parser stopped checking. Co-Authored-By: Claude Fable 5.1 --- apimatic.schema.json | 73 +++++++++++++++++++++++ test/types/apimatic-config/schema.test.ts | 64 +++++++++++++++++++- 2 files changed, 134 insertions(+), 3 deletions(-) diff --git a/apimatic.schema.json b/apimatic.schema.json index f3dae7b9..b09edfe4 100644 --- a/apimatic.schema.json +++ b/apimatic.schema.json @@ -177,6 +177,79 @@ } } }, + "analytics": { + "type": "object", + "description": "Analytics the portal loads. Every page view goes to window.dataLayer as docs_page_view, and to GA4 when a measurement ID is set. The portal counts page changes itself: with googleAnalytics set, turn off the GA4 stream's 'Page changes based on browser history events', or every page change counts twice.", + "additionalProperties": false, + "properties": { + "googleTagManager": { + "type": "object", + "additionalProperties": false, + "required": ["containerId"], + "properties": { + "containerId": { + "allOf": [ + { + "$ref": "#/definitions/nonBlank" + } + ], + "description": "The container's ID, for example 'GTM-ABC123'." + }, + "environment": { + "type": "object", + "description": "A GTM environment, so a staging build loads the container's staging version: the gtm_auth and gtm_preview values from the environment's snippet.", + "additionalProperties": false, + "required": ["auth", "preview"], + "properties": { + "auth": { + "$ref": "#/definitions/nonBlank" + }, + "preview": { + "$ref": "#/definitions/nonBlank" + } + } + } + } + }, + "googleAnalytics": { + "type": "object", + "additionalProperties": false, + "required": ["measurementId"], + "properties": { + "measurementId": { + "allOf": [ + { + "$ref": "#/definitions/nonBlank" + } + ], + "description": "The GA4 web stream's measurement ID, for example 'G-ABC123'. The portal sends its own page views, so turn off the stream's 'Page changes based on browser history events'. Don't also add a GA4 tag to the GTM container: every hit would count twice." + } + } + }, + "keepQueryParams": { + "type": "array", + "description": "Your own link tags to keep in reported page addresses. Campaign (utm_), ad-click and cross-domain tags are kept already; every other query parameter is dropped.", + "items": { + "$ref": "#/definitions/nonBlank" + } + } + } + }, + "seo": { + "type": "object", + "description": "Search engine settings.", + "additionalProperties": false, + "properties": { + "googleSiteVerification": { + "allOf": [ + { + "$ref": "#/definitions/nonBlank" + } + ], + "description": "The content value of Google's site verification meta tag, for Search Console. Not needed for a Domain property verified by DNS." + } + } + }, "pluginUrl": { "type": "string", "description": "Where the context plugin is hosted, starting with 'https://' and with no spaces. The Context Plugin page installs it from here, and the portal carries no copy of its own.", diff --git a/test/types/apimatic-config/schema.test.ts b/test/types/apimatic-config/schema.test.ts index 4626ee62..058f00a0 100644 --- a/test/types/apimatic-config/schema.test.ts +++ b/test/types/apimatic-config/schema.test.ts @@ -99,7 +99,13 @@ describe('apimatic.schema.json', () => { { label: 'Home', url: '/' } ] }, - ai: { pageActions: false } + ai: { pageActions: false }, + analytics: { + googleTagManager: { containerId: 'GTM-ABC123', environment: { auth: 'abc', preview: 'env-3' } }, + googleAnalytics: { measurementId: 'G-ABC123' }, + keepQueryParams: ['campaign_id'] + }, + seo: { googleSiteVerification: 'abc' } } ], ['an address with a port', { site: { url: 'https://docs.example.com:8443' } }], @@ -117,7 +123,36 @@ describe('apimatic.schema.json', () => { ['a link through a parent segment', { navigation: { links: [{ label: 'Start', url: '/guides/../start' }] } }], ['a link with two slashes in its query', { navigation: { links: [{ label: 'Next', url: '/start?next=//x' }] } }], ['a context plugin hosted elsewhere', { pluginUrl: 'https://plugins.acme.test/calc.zip?v=2' }], - ['a plugin address with several query parameters', { pluginUrl: 'https://s3.test/calc.zip?a=1&b=2' }] + ['a plugin address with several query parameters', { pluginUrl: 'https://s3.test/calc.zip?a=1&b=2' }], + ['a GTM container', { analytics: { googleTagManager: { containerId: 'GTM-ABC123' } } }], + [ + 'a GTM container with an environment', + { + analytics: { googleTagManager: { containerId: 'GTM-ABC123', environment: { auth: 'abc', preview: 'env-3' } } } + } + ], + ['a GA4 stream', { analytics: { googleAnalytics: { measurementId: 'G-ABC123' } } }], + [ + 'both vendors, with spaces around the IDs', + { + analytics: { + googleTagManager: { containerId: ' GTM-ABC123 ' }, + googleAnalytics: { measurementId: ' G-ABC123 ' } + } + } + ], + ['a kept query parameter name', { analytics: { keepQueryParams: ['campaign_id'] } }], + ['an empty analytics block', { analytics: {} }], + ['a verification value', { seo: { googleSiteVerification: 'abc_123-XYZ' } }], + // The vendors' formats are theirs to check, so each ID and value is any non-blank string. + ['a lowercase container ID', { analytics: { googleTagManager: { containerId: 'gtm-abc123' } } }], + [ + 'an environment value with a space, and a preview without env-', + { analytics: { googleTagManager: { containerId: 'GTM-1', environment: { auth: 'a b', preview: '3' } } } } + ], + ['a Universal Analytics ID as the measurement ID', { analytics: { googleAnalytics: { measurementId: 'UA-1' } } }], + ['a kept name with a space, and an OAuth answer name', { analytics: { keepQueryParams: ['a b', 'code'] } }], + ['a verification value with a space', { seo: { googleSiteVerification: 'abc 123' } }] ]; const invalid: [string, object][] = [ @@ -219,7 +254,30 @@ describe('apimatic.schema.json', () => { ['a plugin address without a host', { pluginUrl: 'https://' }], ['a plugin address that is not a string', { pluginUrl: 7 }], ['a plugin address with a space', { pluginUrl: 'https://plugins.acme.test/my plugin.zip' }], - ['a plugin address with trailing whitespace', { pluginUrl: 'https://plugins.acme.test/calc.zip ' }] + ['a plugin address with trailing whitespace', { pluginUrl: 'https://plugins.acme.test/calc.zip ' }], + ['analytics that is not an object', { analytics: 'GTM-ABC123' }], + ['an unknown vendor', { analytics: { posthog: {} } }], + ['a bare container ID', { analytics: { googleTagManager: 'GTM-ABC123' } }], + ['a GTM block without its ID', { analytics: { googleTagManager: {} } }], + ['a blank container ID', { analytics: { googleTagManager: { containerId: ' ' } } }], + [ + 'a key beside the container ID', + { analytics: { googleTagManager: { containerId: 'GTM-ABC123', serverUrl: 'x' } } } + ], + [ + 'an environment that is not an object', + { analytics: { googleTagManager: { containerId: 'GTM-ABC123', environment: 'env-3' } } } + ], + [ + 'an environment without its preview', + { analytics: { googleTagManager: { containerId: 'GTM-ABC123', environment: { auth: 'abc' } } } } + ], + ['a GA4 block without its ID', { analytics: { googleAnalytics: {} } }], + ['a measurement ID that is not a string', { analytics: { googleAnalytics: { measurementId: 7 } } }], + ['kept names that are not a list', { analytics: { keepQueryParams: 'campaign_id' } }], + ['a kept name that is not a string', { analytics: { keepQueryParams: [1] } }], + ['seo that is not an object', { seo: 'abc' }], + ['a blank verification value', { seo: { googleSiteVerification: ' ' } }] ]; for (const [label, block] of valid) { From 5851a7842bf3f4bbc1b613ba4efa2ed2be8ef3fe Mon Sep 17 00:00:00 2001 From: Muhammad Sohail Date: Thu, 12 Nov 2026 12:45:45 +0500 Subject: [PATCH 14/73] test(portal): prove analytics and the verification tag in a built portal The default end-to-end build reads a copy of its fixture with both vendors and a verification value set, and checks the output: a browser script holds both IDs while no prerendered page names the tag host, every prerendered page carries the verification meta, and the operation page holds the playground's prerendered header inside the element session replays skip. The fixture the other suites read stays as it is. Co-Authored-By: Claude Fable 5.1 --- test/e2e/portal-build.test.ts | 70 ++++++++++++++++++++++++++++++----- 1 file changed, 60 insertions(+), 10 deletions(-) diff --git a/test/e2e/portal-build.test.ts b/test/e2e/portal-build.test.ts index d220e741..7efd4d2f 100644 --- a/test/e2e/portal-build.test.ts +++ b/test/e2e/portal-build.test.ts @@ -39,6 +39,8 @@ interface BuiltPortal { root: string; project: DirectoryPath; output: DirectoryPath; + /** What the build read: the fixture, or its copy when settings were added to it. */ + source: DirectoryPath; } interface Delivered { @@ -64,11 +66,21 @@ function deliveredInto( ); } -/** Resolves, prepares, builds and saves a fixture as `portal generate` does. */ -async function buildFixture(name: string, delivered: Delivered = {}): Promise { - const fixture = new DirectoryPath(process.cwd()).join('test/resources/portal-inputs').join(name).join('src'); +/** Resolves, prepares, builds and saves a fixture as `portal generate` does, with `settings` added to its `portal` block. */ +async function buildFixture(name: string, delivered: Delivered = {}, settings?: object): Promise { + let fixture = new DirectoryPath(process.cwd()).join('test/resources/portal-inputs').join(name).join('src'); const root = canonical(fs.mkdtempSync(path.join(os.tmpdir(), 'portal-e2e-'))); + if (settings !== undefined) { + // A copy, so the fixture the other suites read stays as it is. + const copy = new DirectoryPath(root).join('src'); + fs.cpSync(fixture.toString(), copy.toString(), { recursive: true }); + const configFile = path.join(copy.toString(), 'apimatic.json'); + const config = JSON.parse(fs.readFileSync(configFile, 'utf8')); + fs.writeFileSync(configFile, JSON.stringify({ ...config, portal: { ...config.portal, ...settings } })); + fixture = copy; + } + const source = (await new PortalSourceContext(fixture).resolve())._unsafeUnwrap(); const project = new DirectoryPath(root).join('build'); @@ -85,7 +97,7 @@ async function buildFixture(name: string, delivered: Delivered = {}): Promise { if (built === undefined) throw new Error(`${name} is not built`); @@ -104,7 +116,7 @@ function portalBuilt(name: string, delivered: Delivered = {}) { }; before(async () => { - built = await buildFixture(name, delivered); + built = await buildFixture(name, delivered, settings); }); after(() => removeBuilt(built)); @@ -112,6 +124,7 @@ function portalBuilt(name: string, delivered: Delivered = {}) { return { output: () => have().output, project: () => have().project, + source: () => have().source, read: (relative: string) => fs.readFileSync(path.join(have().output.toString(), relative), 'utf8'), exists: (relative: string) => fs.existsSync(path.join(have().output.toString(), relative)) }; @@ -179,8 +192,14 @@ const stylesheetOf = (output: DirectoryPath) => { (enabled ? describe : describe.skip)('portal build (end to end)', function () { this.timeout(10 * 60 * 1000); - const fixture = new DirectoryPath(process.cwd()).join('test/resources/portal-inputs/default/src'); - const portal = portalBuilt('default', { codeSampleCatalogs: CODE_SAMPLES }); + const portal = portalBuilt( + 'default', + { codeSampleCatalogs: CODE_SAMPLES }, + { + analytics: { googleTagManager: { containerId: 'GTM-E2ETEST' }, googleAnalytics: { measurementId: 'G-E2ETEST' } }, + seo: { googleSiteVerification: 'e2e-verification' } + } + ); const { read, exists } = portal; /** The prerendered server-function cache entries carrying the sidebar tree. */ @@ -248,6 +267,37 @@ const stylesheetOf = (output: DirectoryPath) => { expect(read('index.html')).to.contain(' + fs + .readdirSync(portal.output().toString(), { recursive: true, withFileTypes: true }) + .filter((entry) => entry.isFile() && entry.name.endsWith('.html')) + .map((entry) => path.relative(portal.output().toString(), path.join(entry.parentPath, entry.name))); + + it('tells the browser both vendor IDs in a script, and names the tag host in no prerendered page', () => { + const scripts = scriptsOf(portal.output()); + expect(scripts.some(({ text }) => text.includes('GTM-E2ETEST') && text.includes('G-E2ETEST'))).to.be.true; + for (const page of pages()) { + expect(read(page), page).to.not.contain('googletagmanager.com'); + } + }); + + it('carries the verification meta on every prerendered page', () => { + expect(pages()).to.have.length.greaterThan(3); + for (const page of pages()) { + expect(read(page), page).to.contain(' { + const parts = read('api/apimatic-calculator/simple-calculator/Calculate/index.html').split( + 'data-portal-playground' + ); + expect(parts, 'one element').to.have.length(2); + // What Fumadocs' playground renders on the server: its header, with the method, the route and the trigger. + expect(parts[1].slice(0, 2000)).to.match(/>GET<[\s\S]*\{operation\}[\s\S]*aria-haspopup="dialog"/); + }); + it('keeps the server-side specification loader out of the browser bundle', () => { const scripts = fs .readdirSync(path.join(portal.output().toString(), 'assets')) @@ -288,13 +338,13 @@ const stylesheetOf = (output: DirectoryPath) => { // published: `portal.server.ts` holds the absolute path of every specification, and the // prepared project's own location has no business in the output either. it('publishes neither the specification paths nor the project directory', () => { - expect(filesNaming(portal.project().toString(), fixture.join('spec').toString())).to.deep.equal([]); + expect(filesNaming(portal.project().toString(), portal.source().join('spec').toString())).to.deep.equal([]); }); // `defineDocs({ dir })` compiles its directory into the client bundle as the collection's // `base`, which is why the project reads a copy of the content by a relative name. it('publishes no absolute path from the build machine at all', () => { - expect(filesNaming(fixture.join('content').toString(), fixture.toString())).to.deep.equal([]); + expect(filesNaming(portal.source().join('content').toString(), portal.source().toString())).to.deep.equal([]); }); it('writes the sidebar tree to one cache file instead of into every page payload', () => { From c860c2782d92219ec12589974c8994df680eb78b Mon Sep 17 00:00:00 2001 From: Muhammad Sohail Date: Thu, 12 Nov 2026 12:51:14 +0500 Subject: [PATCH 15/73] docs(portal): document portal.analytics The README's generated sections carry --no-analytics on both portal commands. The docs page draft for docs.apimatic.io/v4 travels in .ai/plans/portal-analytics-docs.md: the settings, the page view event, the GA4 and GTM setup, previews and staging, Search Console, consent, the CSP domains, container access, session replay and other tag managers, with the CLI reference row. It is the reviewer's to take to the docs repository. Co-Authored-By: Claude Fable 5.1 --- .ai/plans/portal-analytics-docs.md | 189 +++++++++++++++++++++++++++++ README.md | 8 +- 2 files changed, 195 insertions(+), 2 deletions(-) create mode 100644 .ai/plans/portal-analytics-docs.md diff --git a/.ai/plans/portal-analytics-docs.md b/.ai/plans/portal-analytics-docs.md new file mode 100644 index 00000000..c1d55233 --- /dev/null +++ b/.ai/plans/portal-analytics-docs.md @@ -0,0 +1,189 @@ +# Portal analytics: docs draft + +A draft for the analytics page under docs.apimatic.io/v4 and the two rows of the CLI reference, +covering what PR 1 ships (apimatic/apimatic-io#2348, "Docs", and #2349's additions). It is not a +docs PR: the reviewer takes it to the apimatic-docs repository. Lines starting with +`> Reviewer:` are notes for that step, not page text. PR 2 (`portal.scripts`) and PR 3 (the +other seven events) each add to this page in their own docs step. + +--- + +## Analytics + +The portal loads Google Tag Manager and Google Analytics 4 from `portal.analytics` in +`src/apimatic.json`, and reports its own page views to both. Every setting is optional: set +either vendor, both, or neither. + +```json +"portal": { + "analytics": { + "googleTagManager": { "containerId": "GTM-ABC123" }, + "googleAnalytics": { "measurementId": "G-ABC123" }, + "keepQueryParams": ["campaign_id"] + }, + "seo": { "googleSiteVerification": "abc123" } +} +``` + +| Setting | What it is | +|---|---| +| `googleTagManager.containerId` | The container's ID, from the GTM admin page. | +| `googleTagManager.environment` | `{ "auth": "…", "preview": "env-3" }`: the `gtm_auth` and `gtm_preview` values from a GTM environment's snippet (Admin → Environments → Actions → Get Snippet), so a staging build loads the container's staging version. | +| `googleAnalytics.measurementId` | The GA4 web data stream's measurement ID. | +| `keepQueryParams` | Your own link tags to keep in reported page addresses (see below). | +| `seo.googleSiteVerification` | The content value of Google's site verification meta tag, for Search Console (see below). | + +Paste each ID as the console shows it. The CLI checks that an ID is present and not blank, and +nothing else: a wrong ID fails at Google, where the tag does not load, not at build time. + +### Reported page addresses + +A reported `page_location` is the page's address without its `#` part and without its query +string, except for the tags attribution reads: `utm_*` and `hsa_*` parameters, and `_gl`, +`gclid`, `gbraid`, `wbraid`, `gad_source`, `dclid`, `fbclid`, `msclkid`, `ttclid`, `twclid`, +`li_fat_id`, `mc_cid`, `_hsenc`, `_hsmi` and `ref`. Everything else is dropped before any vendor +sees it. `keepQueryParams` adds your own names to that list. + +Never list `code`, `state` or another name an OAuth answer uses. The portal's API playground +signs readers in through OAuth, and a kept answer would be written into every reported address. + +### What the portal sends + +On every page the portal writes to `window.dataLayer`, the queue both Google tags read. Each +report is two entries: `{ docs: null }`, which clears the previous event's details, then the +event with its details under one `docs` key. + +```js +{ docs: null } +{ event: 'docs_page_view', docs: { page_title: 'Quickstart | Acme API', page_location: 'https://docs.acme.com/guides/quickstart' } } +``` + +| Event | Keys under `docs` | When | +|---|---|---| +| `docs_page_view` | `page_title`, `page_location` | The first page renders, and each later page change, once the new page's title is in place. Never twice for the same address, and never on `/oauth/callback`. | + +With `googleAnalytics` set, the portal also sends each event to GA4 directly, under GA4's own +name: `docs_page_view` arrives as `page_view` with the same two parameters. + +> Reviewer: PR 3 adds the other seven events (`docs_markdown_copy`, `docs_plugin_install`, +> `docs_sdk_download`, `docs_code_copy`, `docs_search`, `docs_not_found`, `docs_api_request`) +> and extends this table in its own docs step. + +### Google Analytics 4 + +1. Create a web data stream for the portal's address and paste its measurement ID into + `googleAnalytics.measurementId`. +2. Turn off the stream's own page-change counting: Admin → Data streams → your stream → + Enhanced measurement (the gear) → Page views → Show advanced settings → untick "Page changes + based on browser history events". The portal sends one `page_view` per page change itself; + with the setting on, GA4 sends another, and every page change counts twice. `apimatic portal + generate` prints a reminder whenever `googleAnalytics` is set. +3. Check it: open the portal with Google's Tag Assistant or the Google Analytics Debugger + extension, so DebugView shows your session, then move between pages. DebugView must show one + `page_view` per page change. Two per change means the setting in step 2 is still on; in + reports, double counting shows as views climbing to about twice what readers saw. +4. Redact `code` and `state`: Admin → Data streams → your stream → Redact data → add both as + query parameters. The portal never reports them, but GA4's own collection can read a page's + full address, and this keeps a sign-in answer out of it either way. +5. With `googleAnalytics` set, do not also add a GA4 tag for the same stream inside the GTM + container: every hit would count twice. + +### Google Tag Manager + +The container gets the events as GTM-format data layer pushes, so the usual recipe applies. + +- **The Google tag** (the GA4 configuration) fires on Initialization – All Pages, as Google + recommends, so it is ready before the first `docs_page_view`. Turn off "Send a page view event + when this configuration loads", or the tag counts the first page itself. +- **Data Layer Variables** `docs.page_location` and `docs.page_title`. Every event's details sit + under `docs`, and the portal clears `docs` before each event, so a variable never carries a + value from the previous event. +- **A GA4 Event tag** with the event name `page_view`, the parameters `page_location` and + `page_title` from those variables, and a Custom Event trigger on `docs_page_view`. +- Any other tag that should know about a page change triggers on `docs_page_view` the same way. + +A staging build that must still be checked in GTM sets `environment` to the staging +environment's values, and loads that version of the container. + +### Previews and staging + +`apimatic portal serve` loads the same tags a hosted portal does, and its page views count like +anyone else's. While previewing, run it with `--no-analytics`, or define your own addresses as +internal traffic in GA4 (Admin → Data streams → your stream → Configure tag settings → Define +internal traffic) and filter it from reports. + +`apimatic portal generate --no-analytics` builds a portal that loads neither vendor, for a +staging site that must not count. + +> Reviewer: PR 2 extends `--no-analytics` to the `analytics` and `marketing` scripts in +> `portal.scripts`. + +### Search Console + +Verify the portal's domain as a Domain property, with the DNS TXT record Search Console gives +you; it needs nothing in the portal. For a URL-prefix property verified by the HTML tag method +instead, put the tag's content value in `seo.googleSiteVerification`, and every page carries +``. + +Google's Tag Assistant finds the tags on a portal page. Checks that read only the raw HTML do +not, because the portal loads its tags from its scripts once the page is up, not from a script +tag in the HTML. + +### Consent + +Consent is yours to collect in this release. A consent banner inside the GTM container works as +it does on any site, with Google's Consent Mode deciding what each tag may send. With +`googleAnalytics` set directly, GA4 runs under Consent Mode once your banner sends its update. +A banner of your own, outside GTM, waits for a later portal setting. + +### Content Security Policy + +If the portal's host sets a CSP, allow the domains in +[Google's CSP guide](https://developers.google.com/tag-platform/security/guides/csp): the +tag manager and Google tag script on `https://www.googletagmanager.com`, and GA4's collection on +`https://*.google-analytics.com` and `https://*.analytics.google.com`, plus whatever each tag +inside the container loads. + +### Who can change the container + +Access to the GTM container is access to the site's code: a tag can run any script on every +page, and read what readers type. Give it only to people you would give the repository to. + +### Session replay + +Session replay tools record what readers type. The API playground, where readers paste keys +and tokens, is wrapped in an element carrying the opt-out markers of PostHog (`ph-no-capture`), +FullStory (`fs-exclude`), rrweb (`rr-block`), Amplitude (`amp-block`), Hotjar +(`data-hj-suppress`), Microsoft Clarity (`data-clarity-mask`) and LogRocket (`data-private`), +so a replay shows the page with the playground blank. For any other tool, block the selector +`[data-portal-playground]` in its settings. + +### After a sign-in + +The playground's OAuth sign-in returns the reader to the endpoint page they left. The answer +never reaches the page's address: the playground takes it over through session storage, so the +reported address, the vendors' own page view and anything else that reads the address are +clean. + +> Reviewer: this paragraph holds once fuma-nama/fumadocs#3809 is shipped and picked up, which +> is the PR's merge prerequisite. If the wait of step 1.3 comes back instead, the paragraph +> becomes: the tags start once the playground has removed the answer, up to 5 seconds later, or +> on the next page change. + +### Using another tag manager + +The portal writes GTM-format events to `window.dataLayer` on every portal, whether or not a +Google tag is set. To use another tag manager, load it through your host or, from PR 2, +through `portal.scripts`; turn on its GTM data-layer option, so it reads `docs_page_view` and +the `docs` details; and turn off its own page-change tracking, or page changes count twice. + +--- + +## CLI reference + +In `v4/src/content/apimatic-cli/cli-reference.mdx`, both `apimatic portal generate` and +`apimatic portal serve` gain the row, worded as the flag's description: + +| Flag | Description | +|---|---| +| `--no-analytics` | leave out Google Tag Manager, Google Analytics and every analytics or marketing script, for staging. | diff --git a/README.md b/README.md index a1bf9676..ad9a97cf 100644 --- a/README.md +++ b/README.md @@ -298,7 +298,7 @@ Generate a static API Documentation Portal. ``` USAGE - $ apimatic portal generate [--zip] [-i ] [-d ] [-f] [-k ] + $ apimatic portal generate [--zip] [--no-analytics] [-i ] [-d ] [-f] [-k ] FLAGS -d, --destination= [default: /portal] path where the portal will be generated. @@ -306,6 +306,8 @@ FLAGS -i, --input= [default: ./] path to the parent directory containing the 'src' directory, which includes API specifications and configuration files. -k, --auth-key= override current authentication state with an authentication key. + --no-analytics leave out Google Tag Manager, Google Analytics and every analytics or marketing script, for + staging. --zip write the generated portal as a .zip archive. DESCRIPTION @@ -338,7 +340,7 @@ Preview your API Documentation Portal with live reload. ``` USAGE - $ apimatic portal serve [-p 23513] [-o] [-i ] [-k ] + $ apimatic portal serve [-p 23513] [-o] [--no-analytics] [-i ] [-k ] FLAGS -i, --input= [default: ./] path to the parent directory containing the 'src' directory, which includes API @@ -346,6 +348,8 @@ FLAGS -k, --auth-key= override current authentication state with an authentication key. -o, --open open the portal in the default browser. -p, --port=23513 [default: 23513] port to serve the portal on. + --no-analytics leave out Google Tag Manager, Google Analytics and every analytics or marketing script, for + staging. DESCRIPTION Preview your API Documentation Portal with live reload. From 3f76503871774a6ac46222dacb1bcde05f57fda4 Mon Sep 17 00:00:00 2001 From: Muhammad Sohail Date: Thu, 12 Nov 2026 12:59:49 +0500 Subject: [PATCH 16/73] feat(portal): report Markdown copies, plugin installs and SDK downloads Three more events through the same report(): docs_markdown_copy when the copy succeeds, docs_plugin_install as the install command's copy button is clicked, through an Actions wrapper around Fumadocs' button, and docs_sdk_download with the SDK's language from every download link, the SDK page's own included. Co-Authored-By: Claude Fable 5.1 --- portal-pages/sdk.mdx | 2 +- .../src/components/command-block.tsx | 17 +++++++++++++++-- .../src/components/markdown-copy-button.tsx | 6 +++++- .../src/components/plugin-install.tsx | 5 ++++- portal-template/src/components/sdk-actions.tsx | 18 +++++++++++++++--- portal-template/src/components/sdk-cards.tsx | 10 ++++++---- portal-template/src/lib/analytics.ts | 3 +++ .../portal-pages-service.test.ts | 2 +- test/portal-template/analytics.test.ts | 5 ++++- 9 files changed, 54 insertions(+), 14 deletions(-) diff --git a/portal-pages/sdk.mdx b/portal-pages/sdk.mdx index b6f558c3..5792c0a6 100644 --- a/portal-pages/sdk.mdx +++ b/portal-pages/sdk.mdx @@ -3,6 +3,6 @@ title: "{{name}} SDK" description: "Install and start using the {{name}} SDK." --- - + {{docs}} diff --git a/portal-template/src/components/command-block.tsx b/portal-template/src/components/command-block.tsx index 4d0c8454..7860fc81 100644 --- a/portal-template/src/components/command-block.tsx +++ b/portal-template/src/components/command-block.tsx @@ -7,6 +7,8 @@ interface CommandBlockProps { command: string; /** One line that truncates, for a card; the full command is still what the button copies. */ compact?: boolean; + /** Called as the copy button is clicked. */ + onCopy?: () => void; } // Centred on the one line, where the block's own placement pins the button to the top corner. @@ -15,13 +17,24 @@ function CentredActions({ children }: Readonly<{ children?: ReactNode }>) { } /** One shell command in a copyable block: an MDX page has no highlighter to hand, so it is plain. */ -export function CommandBlock({ command, compact = false }: Readonly) { +export function CommandBlock({ command, compact = false, onCopy }: Readonly) { if (asMarkdown()) { return `\`\`\`bash\n${command}\n\`\`\``; } if (!compact) { return ( - + // Fumadocs calls Actions as a function with its copy button as the children, so a wrapper sees the click. + ( +
+ {children} +
+ )) + } + >
           
             {/* A highlighted block's lines carry this class, which is what the block pads. */}
diff --git a/portal-template/src/components/markdown-copy-button.tsx b/portal-template/src/components/markdown-copy-button.tsx
index ed4ea43e..2064b733 100644
--- a/portal-template/src/components/markdown-copy-button.tsx
+++ b/portal-template/src/components/markdown-copy-button.tsx
@@ -2,6 +2,7 @@ import { useEffect, useState } from 'react';
 import { buttonVariants } from 'fumadocs-ui/components/ui/button';
 import { Check, Copy, X } from 'lucide-react';
 import { copyMarkdown } from '@/lib/copy-markdown';
+import { analytics } from '@/lib/portal-analytics';
 
 type CopyState = 'idle' | 'copying' | 'copied' | 'failed';
 
@@ -24,7 +25,10 @@ export function MarkdownCopyButton({ markdownUrl }: Readonly<{ markdownUrl: stri
   const copy = () => {
     setState('copying');
     copyMarkdown(markdownUrl).then(
-      () => setState('copied'),
+      () => {
+        setState('copied');
+        analytics.report('docs_markdown_copy', {});
+      },
       (error: unknown) => {
         console.error(error);
         setState('failed');
diff --git a/portal-template/src/components/plugin-install.tsx b/portal-template/src/components/plugin-install.tsx
index 9c810b52..2ecc911c 100644
--- a/portal-template/src/components/plugin-install.tsx
+++ b/portal-template/src/components/plugin-install.tsx
@@ -3,11 +3,14 @@ import { asMarkdown } from 'fumadocs-core/server';
 import { CommandBlock } from './command-block';
 import { fullAddress } from '@/lib/base-path';
 import { installCommand } from '@/lib/install-command';
+import { analytics } from '@/lib/portal-analytics';
 import { portal } from '@/lib/portal';
 
 // The address never changes while the page is open, so there is nothing to subscribe to.
 const noSubscribe = () => () => {};
 
+const reportInstall = () => analytics.report('docs_plugin_install', {});
+
 /** The prerender cannot know where the portal is hosted, so the browser swaps in its own address. */
 export function PluginInstall({ path }: Readonly<{ path: string }>) {
   // Ahead of the hook, which only React may call; either branch is taken in every render of one environment.
@@ -19,5 +22,5 @@ export function PluginInstall({ path }: Readonly<{ path: string }>) {
     () => fullAddress('/'),
     () => portal.siteUrl
   );
-  return ;
+  return ;
 }
diff --git a/portal-template/src/components/sdk-actions.tsx b/portal-template/src/components/sdk-actions.tsx
index 4c90cfb1..72728bbe 100644
--- a/portal-template/src/components/sdk-actions.tsx
+++ b/portal-template/src/components/sdk-actions.tsx
@@ -3,8 +3,10 @@ import { asMarkdown } from 'fumadocs-core/server';
 import { buttonVariants } from 'fumadocs-ui/components/ui/button';
 import { Code, Download, Package } from 'lucide-react';
 import { withBasePath } from '@/lib/base-path';
+import { analytics } from '@/lib/portal-analytics';
 
 export interface SdkActionsProps {
+  language: string;
   download: string;
   /** Empty when no source repository is recorded. */
   source: string;
@@ -19,7 +21,7 @@ export const LINK =
 export const QUIET_LINK = `${LINK} text-fd-muted-foreground hover:text-fd-foreground`;
 
 /** Download, View source and View package: each shown only when there is something behind it. */
-export function SdkActions({ download, source, packageUrl, registry }: Readonly) {
+export function SdkActions({ language, download, source, packageUrl, registry }: Readonly) {
   // The page's Markdown twin, which the page actions and llms-full.txt hand to an AI assistant.
   if (asMarkdown()) {
     const links = [
@@ -35,6 +37,7 @@ export function SdkActions({ download, source, packageUrl, registry }: Readonly<
     
@@ -62,10 +65,19 @@ interface LinkProps { children: ReactNode; } +interface DownloadLinkProps extends LinkProps { + language: string; +} + /** A plain link, not a route: the zip is a file the site serves beside its pages. */ -export function DownloadLink({ href, className, children }: Readonly) { +export function DownloadLink({ href, className, language, children }: Readonly) { return ( - + analytics.report('docs_sdk_download', { language })} + > {children} ); diff --git a/portal-template/src/components/sdk-cards.tsx b/portal-template/src/components/sdk-cards.tsx index fda88b91..b7901346 100644 --- a/portal-template/src/components/sdk-cards.tsx +++ b/portal-template/src/components/sdk-cards.tsx @@ -8,7 +8,6 @@ import { LanguageLogo, LogoTile } from './logos'; import { DownloadLink, ExternalLink, LINK, QUIET_LINK, SdkActions, type SdkActionsProps } from './sdk-actions'; interface SdkCardProps extends SdkActionsProps { - language: string; name: string; /** The language's own page. */ page: string; @@ -41,7 +40,10 @@ function LinkContext({ name }: Readonly<{ name: string }>) { export function SdkCard({ language, name, page, install, ...actions }: Readonly) { if (asMarkdown()) { const command = install ? `\`${install}\` · ` : ''; - return [`- [${name}](${withBasePath(page)}): ${command}`, ]; + return [ + `- [${name}](${withBasePath(page)}): ${command}`, + + ]; } const { download, source, packageUrl, registry } = actions; return ( @@ -57,7 +59,7 @@ export function SdkCard({ language, name, page, install, ...actions }: Readonly< {install ? ( ) : ( - + Download SDK @@ -65,7 +67,7 @@ export function SdkCard({ language, name, page, install, ...actions }: Readonly< )}
{install ? ( - + Download SDK diff --git a/portal-template/src/lib/analytics.ts b/portal-template/src/lib/analytics.ts index a22fa6ab..f9deff33 100644 --- a/portal-template/src/lib/analytics.ts +++ b/portal-template/src/lib/analytics.ts @@ -28,6 +28,9 @@ const KEPT_NAMES = new Set([ */ export interface PortalEvents { docs_page_view: { page_title: string }; + docs_markdown_copy: Record; + docs_plugin_install: Record; + docs_sdk_download: { language: string }; } export type PortalEventName = keyof PortalEvents; diff --git a/test/infrastructure/portal-pages-service.test.ts b/test/infrastructure/portal-pages-service.test.ts index 65fb95b6..3f88fdf8 100644 --- a/test/infrastructure/portal-pages-service.test.ts +++ b/test/infrastructure/portal-pages-service.test.ts @@ -90,7 +90,7 @@ describe('PortalPagesService', () => { 'install="npm install @acme/calc" packageUrl="https://www.npmjs.com/package/@acme/calc" registry="npm" />' ); expect(read('sdks/typescript.mdx')).to.contain( - '' ); }); diff --git a/test/portal-template/analytics.test.ts b/test/portal-template/analytics.test.ts index f0278391..a53e1d38 100644 --- a/test/portal-template/analytics.test.ts +++ b/test/portal-template/analytics.test.ts @@ -94,7 +94,10 @@ describe('pageLocation', () => { describe('PortalEvents', () => { // The compiler holds this table to the interface: a missing event, a missing key or an extra key does not compile. const events: { [E in PortalEventName]: Record } = { - docs_page_view: { page_title: true } + docs_page_view: { page_title: true }, + docs_markdown_copy: {}, + docs_plugin_install: {}, + docs_sdk_download: { language: true } }; it('names every event docs_ plus lowercase snake_case, at most 40 characters', () => { From 7611487a5b0ef6bcc9eede1de55d41555010fba6 Mon Sep 17 00:00:00 2001 From: Muhammad Sohail Date: Thu, 12 Nov 2026 13:58:26 +0500 Subject: [PATCH 17/73] feat(portal): report code copies with the block's language Fumadocs' copy button has no callback, so the document hears every click: one inside a code block's figure reports docs_code_copy with the block's caption, or the selected tab's name in a tabbed set. An untitled block reports nothing, and the install command's block, which reports its own copy, is marked and skipped. Co-Authored-By: Claude Fable 5.1 --- .../src/components/command-block.tsx | 2 +- portal-template/src/lib/analytics.ts | 23 ++++ portal-template/src/routes/__root.tsx | 10 +- test/portal-template/analytics.test.ts | 101 +++++++++++++++++- 4 files changed, 133 insertions(+), 3 deletions(-) diff --git a/portal-template/src/components/command-block.tsx b/portal-template/src/components/command-block.tsx index 7860fc81..327d84d3 100644 --- a/portal-template/src/components/command-block.tsx +++ b/portal-template/src/components/command-block.tsx @@ -29,7 +29,7 @@ export function CommandBlock({ command, compact = false, onCopy }: Readonly ( -
+
{children}
)) diff --git a/portal-template/src/lib/analytics.ts b/portal-template/src/lib/analytics.ts index f9deff33..ca0eaf5f 100644 --- a/portal-template/src/lib/analytics.ts +++ b/portal-template/src/lib/analytics.ts @@ -31,6 +31,7 @@ export interface PortalEvents { docs_markdown_copy: Record; docs_plugin_install: Record; docs_sdk_download: { language: string }; + docs_code_copy: { language: string }; } export type PortalEventName = keyof PortalEvents; @@ -102,6 +103,20 @@ export function pageLocation(href: string, keep: readonly string[], base?: strin return url.href; } +/** + * The language of the code block a copy button sits in: a titled block's caption, or the selected tab's name + * when the block is one of a tabbed set. Null for a block with neither, and for a button outside any block. + */ +export function copiedLanguage(button: Element): string | null { + const figure = button.closest('figure'); + if (figure === null) return null; + const tabs = figure.closest('[role="tabpanel"]')?.parentElement; + const name = tabs + ? tabs.querySelector('[role="tab"][aria-selected="true"]')?.textContent + : figure.querySelector('figcaption')?.textContent; + return name?.trim() || null; +} + /** The one instance a portal runs: started when the bundle evaluates, reporting from the root effect and the components. */ export class Analytics { private readonly live: Adapter[] = []; @@ -145,4 +160,12 @@ export class Analytics { this.lastPageView = page; this.report('docs_page_view', { page_title: document.title }); } + /** For a click anywhere on the page: a code block's copy button reports the copy with the block's language. */ + public reportCodeCopy(target: EventTarget | null): void { + const button = target !== null && 'closest' in target ? (target as Element).closest('figure button') : null; + // A block that reports its own copy, such as the install command, is not a code copy as well. + if (button === null || button.closest('[data-copy-reported]') !== null) return; + const language = copiedLanguage(button); + if (language !== null) this.report('docs_code_copy', { language }); + } } diff --git a/portal-template/src/routes/__root.tsx b/portal-template/src/routes/__root.tsx index 48852112..f6b37a9d 100644 --- a/portal-template/src/routes/__root.tsx +++ b/portal-template/src/routes/__root.tsx @@ -29,6 +29,9 @@ const iconLinks = portal.favicon // A portal fixed to one mode keeps to it whatever the visitor's system prefers, and offers no // way out: the layout hides the switch, and the `D` hotkey is turned off here. +// Fumadocs' copy button has no callback of its own, so the document hears every click. +const reportCodeCopy = (event: MouseEvent) => analytics.reportCodeCopy(event.target); + const theme = portal.colorMode === 'both' ? undefined @@ -55,7 +58,12 @@ function RootComponent() { const router = useRouter(); useEffect(() => { analytics.reportPageView(); - return router.subscribe('onRendered', () => analytics.reportPageView()); + const unsubscribe = router.subscribe('onRendered', () => analytics.reportPageView()); + document.addEventListener('click', reportCodeCopy); + return () => { + unsubscribe(); + document.removeEventListener('click', reportCodeCopy); + }; }, [router]); return ( diff --git a/test/portal-template/analytics.test.ts b/test/portal-template/analytics.test.ts index a53e1d38..f1f3d04a 100644 --- a/test/portal-template/analytics.test.ts +++ b/test/portal-template/analytics.test.ts @@ -3,6 +3,7 @@ import { Adapter, adapters, Analytics, + copiedLanguage, pageLocation, PortalEventName, PortalEvents @@ -97,7 +98,8 @@ describe('PortalEvents', () => { docs_page_view: { page_title: true }, docs_markdown_copy: {}, docs_plugin_install: {}, - docs_sdk_download: { language: true } + docs_sdk_download: { language: true }, + docs_code_copy: { language: true } }; it('names every event docs_ plus lowercase snake_case, at most 40 characters', () => { @@ -115,6 +117,72 @@ describe('PortalEvents', () => { }); }); +/** As much of an element as the copy reader walks: the selectors it matches, its text, and its place in the tree. */ +class FakeElement { + public parentElement: FakeElement | null = null; + + public constructor( + private readonly selectors: string[], + public readonly textContent: string | null = null, + private readonly children: FakeElement[] = [] + ) { + for (const child of children) child.parentElement = this; + } + + public closest(selector: string): FakeElement | null { + return this.selectors.includes(selector) ? this : this.parentElement?.closest(selector) ?? null; + } + + public querySelector(selector: string): FakeElement | null { + for (const child of this.children) { + const found = child.selectors.includes(selector) ? child : child.querySelector(selector); + if (found !== null) return found; + } + return null; + } +} + +const element = (fake: FakeElement) => fake as unknown as Parameters[0]; + +/** Fumadocs' code block: a figure with the copy button in its header beside the caption, or in its corner when untitled. */ +function codeBlock(title: string | null) { + const button = new FakeElement(['figure button']); + const caption = title === null ? [] : [new FakeElement(['figcaption'], title)]; + const figure = new FakeElement(['figure'], null, [new FakeElement([], null, [...caption, button])]); + return { figure, button }; +} + +/** A tabbed set of untitled blocks under one root, with `selected` shown: the copy button of the block that is. */ +function tabbedBlocks(names: string[], selected: string): FakeElement { + const tabs = names.map( + (name) => + new FakeElement( + name === selected ? ['[role="tab"]', '[role="tab"][aria-selected="true"]'] : ['[role="tab"]'], + name + ) + ); + const blocks = names.map(() => codeBlock(null)); + const panels = blocks.map(({ figure }) => new FakeElement(['[role="tabpanel"]'], null, [figure])); + new FakeElement([], null, [new FakeElement(['[role="tablist"]'], null, tabs), ...panels]); + return blocks[names.indexOf(selected)].button; +} + +describe('copiedLanguage', () => { + it('reads a titled block’s caption', () => { + expect(copiedLanguage(element(codeBlock('TypeScript').button))).to.equal('TypeScript'); + }); + + it('reads the selected tab’s name for a block in a tabbed set', () => { + expect(copiedLanguage(element(tabbedBlocks(['cURL', 'TypeScript'], 'TypeScript')))).to.equal('TypeScript'); + expect(copiedLanguage(element(tabbedBlocks(['cURL', 'TypeScript'], 'cURL')))).to.equal('cURL'); + }); + + it('is null for a block with neither, and for a button outside any block', () => { + expect(copiedLanguage(element(codeBlock(null).button))).to.be.null; + expect(copiedLanguage(element(new FakeElement(['button'])))).to.be.null; + }); +}); + interface FakeScript { async: boolean; src: string; @@ -561,4 +629,35 @@ describe('Analytics', () => { ).to.deep.equal([quickstart, components, quickstart]); }); }); + describe('reportCodeCopy', () => { + const address = 'https://docs.acme.com/guides/quickstart'; + const codeCopies = (entries: unknown[]) => + entries.filter((entry) => isPlainObject(entry) && entry.event === 'docs_code_copy'); + + it('reports a code block’s copy with its language', () => { + const page = browser(address); + const analytics = new Analytics(none); + + analytics.reportCodeCopy(element(codeBlock('TypeScript').button)); + + expect(codeCopies(page.dataLayer())).to.deep.equal([ + { event: 'docs_code_copy', docs: { language: 'TypeScript', page_location: address } } + ]); + }); + + it('reports nothing for a click outside a block, on an untitled block, or in a block that reports its own copy', () => { + const page = browser(address); + const analytics = new Analytics(none); + const own = codeBlock('Terminal'); + // The install command's wrapper marks its block. + new FakeElement(['[data-copy-reported]'], null, [own.figure]); + + analytics.reportCodeCopy(element(new FakeElement(['button']))); + analytics.reportCodeCopy(element(codeBlock(null).button)); + analytics.reportCodeCopy(element(own.button)); + analytics.reportCodeCopy(null); + + expect(codeCopies(page.dataLayer())).to.be.empty; + }); + }); }); From 18e68aae2aa9ac88395e67c63c216bca122b79ee Mon Sep 17 00:00:00 2001 From: Muhammad Sohail Date: Thu, 12 Nov 2026 14:16:03 +0500 Subject: [PATCH 18/73] feat(portal): report searches with the term, the pick and the count One docs_search when the dialog closes after the reader typed in this open: the term trimmed, the result picked or '' for none, and how many results the list showed. Fumadocs closes the dialog before it hands over the pick, so the report waits a tick for it; a reopen closed without typing reports nothing. Co-Authored-By: Claude Fable 5.1 --- portal-template/src/components/search.tsx | 35 +++++++++++++++++-- portal-template/src/lib/analytics.ts | 7 ++++ test/portal-template/analytics.test.ts | 41 ++++++++++++++++++++++- 3 files changed, 80 insertions(+), 3 deletions(-) diff --git a/portal-template/src/components/search.tsx b/portal-template/src/components/search.tsx index 8180d410..83a5615c 100644 --- a/portal-template/src/components/search.tsx +++ b/portal-template/src/components/search.tsx @@ -8,13 +8,15 @@ import { SearchDialogInput, SearchDialogList, SearchDialogOverlay, + type SearchItemType, type SharedProps } from 'fumadocs-ui/components/dialog/search'; import { useDocsSearch } from 'fumadocs-core/search/client'; import { staticClient } from 'fumadocs-core/search/client/orama-static'; import { useI18n } from 'fumadocs-ui/contexts/i18n'; -import { useMemo } from 'react'; +import { useMemo, useRef } from 'react'; import { withBasePath } from '@/lib/base-path'; +import { analytics } from '@/lib/portal-analytics'; export default function DefaultSearchDialog(props: SharedProps) { const { locale } = useI18n(); @@ -32,8 +34,37 @@ export default function DefaultSearchDialog(props: SharedProps) { [query.data] ); + const typed = useRef(false); + const picked = useRef(''); + + const onSearchChange = (value: string) => { + typed.current = true; + setSearch(value); + }; + const onSelect = (item: SearchItemType) => { + picked.current = 'url' in item ? item.url : ''; + }; + const onOpenChange = (open: boolean) => { + props.onOpenChange(open); + if (open || !typed.current) return; + typed.current = false; + const count = results?.length ?? 0; + // Fumadocs closes the dialog before it hands over the pick, so the report waits a tick for it. + window.setTimeout(() => { + analytics.reportSearch(search, picked.current, count); + picked.current = ''; + }, 0); + }; + return ( - + diff --git a/portal-template/src/lib/analytics.ts b/portal-template/src/lib/analytics.ts index ca0eaf5f..8f4e9821 100644 --- a/portal-template/src/lib/analytics.ts +++ b/portal-template/src/lib/analytics.ts @@ -32,6 +32,7 @@ export interface PortalEvents { docs_plugin_install: Record; docs_sdk_download: { language: string }; docs_code_copy: { language: string }; + docs_search: { search_term: string; result: string; result_count: number }; } export type PortalEventName = keyof PortalEvents; @@ -168,4 +169,10 @@ export class Analytics { const language = copiedLanguage(button); if (language !== null) this.report('docs_code_copy', { language }); } + /** One search, as the dialog closes: what was typed, the result picked or '' for none, and how many were shown. */ + public reportSearch(term: string, picked: string, resultCount: number): void { + const search_term = term.trim(); + if (search_term === '') return; + this.report('docs_search', { search_term, result: picked, result_count: resultCount }); + } } diff --git a/test/portal-template/analytics.test.ts b/test/portal-template/analytics.test.ts index f1f3d04a..b91722f6 100644 --- a/test/portal-template/analytics.test.ts +++ b/test/portal-template/analytics.test.ts @@ -99,7 +99,8 @@ describe('PortalEvents', () => { docs_markdown_copy: {}, docs_plugin_install: {}, docs_sdk_download: { language: true }, - docs_code_copy: { language: true } + docs_code_copy: { language: true }, + docs_search: { search_term: true, result: true, result_count: true } }; it('names every event docs_ plus lowercase snake_case, at most 40 characters', () => { @@ -660,4 +661,42 @@ describe('Analytics', () => { expect(codeCopies(page.dataLayer())).to.be.empty; }); }); + describe('reportSearch', () => { + const address = 'https://docs.acme.com/guides/quickstart'; + const searches = (entries: unknown[]) => + entries.filter((entry) => isPlainObject(entry) && entry.event === 'docs_search'); + + it('reports the term trimmed, the pick and the count shown', () => { + const page = browser(address); + + new Analytics(none).reportSearch(' auth ', '/guides/authentication', 3); + + expect(searches(page.dataLayer())).to.deep.equal([ + { + event: 'docs_search', + docs: { search_term: 'auth', result: '/guides/authentication', result_count: 3, page_location: address } + } + ]); + }); + + it('reports an empty result when the dialog closed without a pick', () => { + const page = browser(address); + + new Analytics(none).reportSearch('auth', '', 0); + + expect(searches(page.dataLayer())).to.deep.equal([ + { event: 'docs_search', docs: { search_term: 'auth', result: '', result_count: 0, page_location: address } } + ]); + }); + + it('reports nothing when nothing was typed', () => { + const page = browser(address); + const analytics = new Analytics(none); + + analytics.reportSearch('', '', 0); + analytics.reportSearch(' ', '/guides/authentication', 1); + + expect(searches(page.dataLayer())).to.be.empty; + }); + }); }); From 64a98f9a43884b40561c58e905d2822327852a31 Mon Sep 17 00:00:00 2001 From: Muhammad Sohail Date: Thu, 12 Nov 2026 14:19:24 +0500 Subject: [PATCH 19/73] feat(portal): report the not-found page with a clean referrer docs_not_found from the not-found page's mount: page_referrer is the portal page the reader left for it after an in-portal link, else the document's referrer without its query and # part on a first load, else empty. The page's own docs_page_view still arrives. Co-Authored-By: Claude Fable 5.1 --- portal-template/src/components/not-found.tsx | 3 ++ portal-template/src/lib/analytics.ts | 12 +++++++ test/portal-template/analytics.test.ts | 33 +++++++++++++++++++- 3 files changed, 47 insertions(+), 1 deletion(-) diff --git a/portal-template/src/components/not-found.tsx b/portal-template/src/components/not-found.tsx index 375aacb7..9b3225f4 100644 --- a/portal-template/src/components/not-found.tsx +++ b/portal-template/src/components/not-found.tsx @@ -1,8 +1,11 @@ +import { useEffect } from 'react'; import { baseOptions } from '@/lib/layout.shared'; +import { analytics } from '@/lib/portal-analytics'; import { HomeLayout } from 'fumadocs-ui/layouts/home'; import { DefaultNotFound } from 'fumadocs-ui/layouts/home/not-found'; export function NotFound() { + useEffect(() => analytics.reportNotFound(document.referrer), []); return ( diff --git a/portal-template/src/lib/analytics.ts b/portal-template/src/lib/analytics.ts index 8f4e9821..af52425a 100644 --- a/portal-template/src/lib/analytics.ts +++ b/portal-template/src/lib/analytics.ts @@ -33,6 +33,7 @@ export interface PortalEvents { docs_sdk_download: { language: string }; docs_code_copy: { language: string }; docs_search: { search_term: string; result: string; result_count: number }; + docs_not_found: { page_referrer: string }; } export type PortalEventName = keyof PortalEvents; @@ -123,6 +124,7 @@ export class Analytics { private readonly live: Adapter[] = []; private started = false; private lastPageView: string | null = null; + private previousPageView: string | null = null; public constructor(private readonly settings: PortalAnalytics) { if (settings.googleTagManager) this.live.push(adapters.googleTagManager(settings.googleTagManager)); @@ -158,6 +160,7 @@ export class Analytics { public reportPageView(): void { const page = pageLocation(window.location.href, this.settings.keepQueryParams); if (page === null || page === this.lastPageView) return; + this.previousPageView = this.lastPageView; this.lastPageView = page; this.report('docs_page_view', { page_title: document.title }); } @@ -175,4 +178,13 @@ export class Analytics { if (search_term === '') return; this.report('docs_search', { search_term, result: picked, result_count: resultCount }); } + /** The not-found page: `page_referrer` is the portal page left for it, else the document's referrer without its query. */ + public reportNotFound(documentReferrer: string): void { + const referrer = documentReferrer === '' ? null : new URL(documentReferrer); + if (referrer !== null) { + referrer.search = ''; + referrer.hash = ''; + } + this.report('docs_not_found', { page_referrer: this.previousPageView ?? referrer?.href ?? '' }); + } } diff --git a/test/portal-template/analytics.test.ts b/test/portal-template/analytics.test.ts index b91722f6..869c4d1d 100644 --- a/test/portal-template/analytics.test.ts +++ b/test/portal-template/analytics.test.ts @@ -100,7 +100,8 @@ describe('PortalEvents', () => { docs_plugin_install: {}, docs_sdk_download: { language: true }, docs_code_copy: { language: true }, - docs_search: { search_term: true, result: true, result_count: true } + docs_search: { search_term: true, result: true, result_count: true }, + docs_not_found: { page_referrer: true } }; it('names every event docs_ plus lowercase snake_case, at most 40 characters', () => { @@ -699,4 +700,34 @@ describe('Analytics', () => { expect(searches(page.dataLayer())).to.be.empty; }); }); + describe('reportNotFound', () => { + const missing = 'https://docs.acme.com/guides/missing'; + const referrers = (entries: unknown[]) => + entries + .filter((entry) => isPlainObject(entry) && entry.event === 'docs_not_found') + .map((entry) => (entry as { docs: { page_referrer: string } }).docs.page_referrer); + + it('names the portal page the reader left for it, whatever the document says', () => { + const page = browser('https://docs.acme.com/guides/quickstart'); + const analytics = new Analytics(none); + analytics.reportPageView(); + page.go(missing); + analytics.reportPageView(); + + analytics.reportNotFound('https://www.google.com/search?q=acme+docs'); + + expect(referrers(page.dataLayer())).to.deep.equal(['https://docs.acme.com/guides/quickstart']); + expect(page.dataLayer().at(-1)).to.have.nested.property('docs.page_location', missing); + }); + + it('names the referrer without its query or # part on a first load, and nothing when the browser sends none', () => { + const page = browser(missing); + const analytics = new Analytics(none); + + analytics.reportNotFound('https://www.google.com/search?q=acme+docs#top'); + analytics.reportNotFound(''); + + expect(referrers(page.dataLayer())).to.deep.equal(['https://www.google.com/search', '']); + }); + }); }); From a3657e0954e5a3ed1bca25b06cc27ddf6840c224 Mon Sep 17 00:00:00 2001 From: Muhammad Sohail Date: Thu, 12 Nov 2026 14:48:06 +0500 Subject: [PATCH 20/73] feat(portal): report playground requests without their contents docs_api_request once per result: the endpoint as the spec writes it, the HTTP status or client_error, and the duration, the response's own or timed from the request's start for one that never arrived. Never the request's address, headers or body. The reporting wraps Fumadocs' result display inside the playground's lazy chunk, so the split from the page bundle holds. Co-Authored-By: Claude Fable 5.1 --- portal-template/src/components/api-page.tsx | 4 +- portal-template/src/components/playground.tsx | 29 ++++++++++ portal-template/src/lib/analytics.ts | 16 ++++++ test/portal-template/analytics.test.ts | 53 ++++++++++++++++++- 4 files changed, 99 insertions(+), 3 deletions(-) create mode 100644 portal-template/src/components/playground.tsx diff --git a/portal-template/src/components/api-page.tsx b/portal-template/src/components/api-page.tsx index 4fbb96a7..c9294ceb 100644 --- a/portal-template/src/components/api-page.tsx +++ b/portal-template/src/components/api-page.tsx @@ -8,7 +8,7 @@ import { renderExampleLayout } from './example-layout'; import { codeUsages, renderUsageTabs } from './usage-tabs'; // Its own chunk, as Fumadocs loads it: the playground's forms are not in every page's bundle. -const PlaygroundClient = lazy(() => import('fumadocs-openapi/ui/playground/client')); +const Playground = lazy(() => import('./playground')); export const OpenAPIPage = createOpenAPIPage({ codeUsages, @@ -28,7 +28,7 @@ export const OpenAPIPage = createOpenAPIPage({ data-portal-playground="" > - +
) diff --git a/portal-template/src/components/playground.tsx b/portal-template/src/components/playground.tsx new file mode 100644 index 00000000..03e2a11c --- /dev/null +++ b/portal-template/src/components/playground.tsx @@ -0,0 +1,29 @@ +import { useEffect } from 'react'; +import { useOperation } from 'fumadocs-openapi/operation'; +import PlaygroundClient, { DefaultResultDisplay, type ResultDisplayProps } from 'fumadocs-openapi/ui/playground/client'; +import { analytics } from '@/lib/portal-analytics'; + +// Fumadocs' request has no callback of its own: the start is noted here, and the request goes on unchanged. +const fetchOptions = { + onRequestInit: (requestInit: RequestInit) => { + analytics.requestStarted(); + return requestInit; + } +}; + +/** Fumadocs' result display, reporting each result once: the effect runs per result object, not per render. */ +function ResultDisplay(props: ResultDisplayProps) { + const { method, path } = useOperation(); + useEffect( + () => analytics.reportApiRequest(`${method.toUpperCase()} ${path}`, props.data), + [method, path, props.data] + ); + return ; +} + +const components = { ResultDisplay }; + +/** The playground with the reporting around it, in the one chunk the API page loads lazily. */ +export default function Playground() { + return ; +} diff --git a/portal-template/src/lib/analytics.ts b/portal-template/src/lib/analytics.ts index af52425a..add71f50 100644 --- a/portal-template/src/lib/analytics.ts +++ b/portal-template/src/lib/analytics.ts @@ -1,3 +1,4 @@ +import type { FetchResult } from 'fumadocs-openapi/playground'; import { withBasePath } from './base-path'; import { oauthCallbackPath } from './oauth-callback'; import type { PortalAnalytics } from './portal-types'; @@ -34,6 +35,7 @@ export interface PortalEvents { docs_code_copy: { language: string }; docs_search: { search_term: string; result: string; result_count: number }; docs_not_found: { page_referrer: string }; + docs_api_request: { endpoint: string; status: string; duration_ms: number }; } export type PortalEventName = keyof PortalEvents; @@ -125,6 +127,7 @@ export class Analytics { private started = false; private lastPageView: string | null = null; private previousPageView: string | null = null; + private requestStartedAt = 0; public constructor(private readonly settings: PortalAnalytics) { if (settings.googleTagManager) this.live.push(adapters.googleTagManager(settings.googleTagManager)); @@ -187,4 +190,17 @@ export class Analytics { } this.report('docs_not_found', { page_referrer: this.previousPageView ?? referrer?.href ?? '' }); } + /** As the playground sends a request: the start of the one duration a request that never arrives can have. */ + public requestStarted(): void { + this.requestStartedAt = Date.now(); + } + + /** The playground's result for `endpoint`, the method and path as the spec writes them: its status and its time, and nothing of the request itself. */ + public reportApiRequest(endpoint: string, result: FetchResult): void { + const [status, duration_ms] = + result.type === 'response' + ? [String(result.status), Math.round(result.duration)] + : ['client_error', Date.now() - this.requestStartedAt]; + this.report('docs_api_request', { endpoint, status, duration_ms }); + } } diff --git a/test/portal-template/analytics.test.ts b/test/portal-template/analytics.test.ts index 869c4d1d..fc552a95 100644 --- a/test/portal-template/analytics.test.ts +++ b/test/portal-template/analytics.test.ts @@ -101,7 +101,8 @@ describe('PortalEvents', () => { docs_sdk_download: { language: true }, docs_code_copy: { language: true }, docs_search: { search_term: true, result: true, result_count: true }, - docs_not_found: { page_referrer: true } + docs_not_found: { page_referrer: true }, + docs_api_request: { endpoint: true, status: true, duration_ms: true } }; it('names every event docs_ plus lowercase snake_case, at most 40 characters', () => { @@ -730,4 +731,54 @@ describe('Analytics', () => { expect(referrers(page.dataLayer())).to.deep.equal(['https://www.google.com/search', '']); }); }); + describe('reportApiRequest', () => { + const address = 'https://docs.acme.com/api/calc/Calculate'; + const endpoint = 'GET /{operation}'; + // The request's own address, which holds filled-in values: never reported. + const url = 'https://api.acme.com/v1/calc/SUM?x=4&api_key=s3cret'; + const requests = (entries: unknown[]) => + entries.filter((entry) => isPlainObject(entry) && entry.event === 'docs_api_request') as { + docs: Record; + }[]; + + it('reports a response by its status and its own duration, rounded', () => { + const page = browser(address); + + new Analytics(none).reportApiRequest(endpoint, { type: 'response', url, status: 200, duration: 123.4 } as never); + + expect(requests(page.dataLayer())).to.deep.equal([ + { event: 'docs_api_request', docs: { endpoint, status: '200', duration_ms: 123, page_location: address } } + ]); + }); + + it('reports a request that never reached the API as a client error, timed from its start', () => { + const page = browser(address); + const analytics = new Analytics(none); + analytics.requestStarted(); + + analytics.reportApiRequest(endpoint, { type: 'client_error', url, message: 'Failed to fetch' } as never); + + const [entry] = requests(page.dataLayer()); + expect(entry.docs).to.include({ endpoint, status: 'client_error', page_location: address }); + expect(entry.docs.duration_ms).to.be.a('number').within(0, 5000); + }); + + it('carries the endpoint, the status and the duration, and nothing of the request', () => { + const page = browser(address); + const result = { + type: 'response', + url, + status: 401, + duration: 8, + headers: { 'x-key': 's3cret' }, + body: 's3cret' + }; + + new Analytics(none).reportApiRequest(endpoint, result as never); + + const [entry] = requests(page.dataLayer()); + expect(Object.keys(entry.docs).sort()).to.deep.equal(['duration_ms', 'endpoint', 'page_location', 'status']); + expect(JSON.stringify(entry)).to.not.contain('s3cret'); + }); + }); }); From cc31714a9bb39509066e119c14bd6ab90402c962 Mon Sep 17 00:00:00 2001 From: Muhammad Sohail Date: Thu, 12 Nov 2026 14:52:35 +0500 Subject: [PATCH 21/73] docs(portal): document the eight portal events The docs draft's table lists every event with its keys and when it fires, the GA4 custom dimensions and metrics to register, and the GTM trigger and variable pattern for the events beyond the page view. Co-Authored-By: Claude Fable 5.1 --- .ai/plans/portal-analytics-docs.md | 42 +++++++++++++++++++++--------- 1 file changed, 30 insertions(+), 12 deletions(-) diff --git a/.ai/plans/portal-analytics-docs.md b/.ai/plans/portal-analytics-docs.md index c1d55233..8d794384 100644 --- a/.ai/plans/portal-analytics-docs.md +++ b/.ai/plans/portal-analytics-docs.md @@ -1,10 +1,10 @@ # Portal analytics: docs draft A draft for the analytics page under docs.apimatic.io/v4 and the two rows of the CLI reference, -covering what PR 1 ships (apimatic/apimatic-io#2348, "Docs", and #2349's additions). It is not a -docs PR: the reviewer takes it to the apimatic-docs repository. Lines starting with -`> Reviewer:` are notes for that step, not page text. PR 2 (`portal.scripts`) and PR 3 (the -other seven events) each add to this page in their own docs step. +covering what PR 1 and PR 3 ship in #473 (apimatic/apimatic-io#2348, "Docs" and the PR 3 event +table, and #2349's additions). It is not a docs PR: the reviewer takes it to the apimatic-docs +repository. Lines starting with `> Reviewer:` are notes for that step, not page text. PR 2 +(`portal.scripts`) adds to this page in its own docs step. --- @@ -58,16 +58,31 @@ event with its details under one `docs` key. { event: 'docs_page_view', docs: { page_title: 'Quickstart | Acme API', page_location: 'https://docs.acme.com/guides/quickstart' } } ``` +Every event carries `page_location`, the address of the page it happened on, cleaned as above. +The table lists the keys each adds. + | Event | Keys under `docs` | When | |---|---|---| -| `docs_page_view` | `page_title`, `page_location` | The first page renders, and each later page change, once the new page's title is in place. Never twice for the same address, and never on `/oauth/callback`. | - -With `googleAnalytics` set, the portal also sends each event to GA4 directly, under GA4's own -name: `docs_page_view` arrives as `page_view` with the same two parameters. - -> Reviewer: PR 3 adds the other seven events (`docs_markdown_copy`, `docs_plugin_install`, -> `docs_sdk_download`, `docs_code_copy`, `docs_search`, `docs_not_found`, `docs_api_request`) -> and extends this table in its own docs step. +| `docs_page_view` | `page_title` | The first page renders, and each later page change, once the new page's title is in place. Never twice for the same address, and never on `/oauth/callback`. | +| `docs_markdown_copy` | none | The page's "Copy Markdown" button, when the copy succeeded. | +| `docs_plugin_install` | none | The Context Plugin page's install command, as its copy button is clicked. | +| `docs_sdk_download` | `language` | A "Download SDK" link, on the SDKs page's cards or an SDK's own page. `language` is the SDK's, as `languages` names it in `apimatic.json`. | +| `docs_code_copy` | `language` | The copy button of a code block on any page, the API reference's examples included. `language` is the block's title, such as `TypeScript` or `Terminal`, or the selected tab's name in a tabbed block. A block with neither reports nothing, and neither does the install command's block, which has its own event. | +| `docs_search` | `search_term`, `result`, `result_count` | The search dialog closes after the reader typed in it: the term, the address of the result picked or empty when none was, and how many results the list showed. Reopening the dialog and closing it without typing again reports nothing. | +| `docs_not_found` | `page_referrer` | The not-found page renders. `page_referrer` is the portal page the reader left for it after a portal link, or on a first load the browser's referrer without its query, or empty when the browser sends none. The page's own `docs_page_view` is sent too. | +| `docs_api_request` | `endpoint`, `status`, `duration_ms` | The API playground shows a result. `endpoint` is the method and path as the specification writes them, such as `GET /users/{id}`; `status` the HTTP status, or `client_error` for a request that never reached the API; `duration_ms` how long it took. It never carries the request's address, headers or body: those hold what the reader typed, keys included. | + +With `googleAnalytics` set, the portal also sends each event to GA4 directly, under its name +without the `docs_` prefix: `docs_page_view` arrives as `page_view` and `docs_search` as +`search`, which are GA4's own events with these same parameters, and the rest as custom +events. + +#### Registering the keys in GA4 + +GA4 reports a custom parameter only once it is registered (Admin → Custom definitions). Register +five custom dimensions, `search_term`, `result`, `language`, `endpoint` and `status`, and two +custom metrics, `result_count` and `duration_ms`. Each appears in reports a day or two after. +`page_title`, `page_location` and `page_referrer` are GA4's own parameters and need nothing. ### Google Analytics 4 @@ -101,6 +116,9 @@ The container gets the events as GTM-format data layer pushes, so the usual reci - **A GA4 Event tag** with the event name `page_view`, the parameters `page_location` and `page_title` from those variables, and a Custom Event trigger on `docs_page_view`. - Any other tag that should know about a page change triggers on `docs_page_view` the same way. +- **The other events** follow the same pattern: a Custom Event trigger on the event's name, and + a Data Layer Variable `docs.` for each key the table above lists, so a GA4 Event tag for + `docs_search` reads `docs.search_term`, `docs.result` and `docs.result_count`. A staging build that must still be checked in GTM sets `environment` to the staging environment's values, and loads that version of the container. From b1622813622481ebb0be549a3e53310773316629 Mon Sep 17 00:00:00 2001 From: Muhammad Sohail Date: Thu, 12 Nov 2026 16:01:08 +0500 Subject: [PATCH 22/73] fix(portal): report each event once, from the page it belongs to The playground's dialog, which Fumadocs portals outside the marked wrapper, is marked for session replay as it appears, until fuma-nama/fumadocs#3824 lets the markers be passed to it directly; the markers themselves move to one module the wrapper shares. docs_search carries the page it was made on, captured when the dialog opens, since a pick changes the address before the close is reported, and a pick without typing counts as a search. docs_api_request reports a result object once however often the display mounts, which happens on every reopen and twice under StrictMode, and a request that failed before it was sent has no duration. docs_not_found reports once per missing page and again for the next, keyed on the path. The code-copy listener ignores dropdowns and the playground's dialog, and prefers a block's caption over its tab. Vendor values are escaped in the tag addresses, since the parser checks presence only. The two empty events take no keys at report(). The docs draft's consent, CSP, replay, search and GA4 lines are corrected: direct GA4 cannot wait for a banner, search_term is GA4's own parameter, and the redact setting sits under the tag settings. Co-Authored-By: Claude Fable 5.1 --- .ai/plans/portal-analytics-docs.md | 53 ++++---- portal-template/src/components/api-page.tsx | 9 +- portal-template/src/components/not-found.tsx | 5 +- portal-template/src/components/playground.tsx | 16 +++ portal-template/src/components/search.tsx | 12 +- portal-template/src/lib/analytics.ts | 54 +++++--- portal-template/src/lib/replay-markers.ts | 16 +++ portal-template/src/routes/__root.tsx | 4 +- test/e2e/portal-build.test.ts | 4 +- test/portal-template/analytics.test.ts | 128 ++++++++++++++---- 10 files changed, 221 insertions(+), 80 deletions(-) create mode 100644 portal-template/src/lib/replay-markers.ts diff --git a/.ai/plans/portal-analytics-docs.md b/.ai/plans/portal-analytics-docs.md index 8d794384..30e4263e 100644 --- a/.ai/plans/portal-analytics-docs.md +++ b/.ai/plans/portal-analytics-docs.md @@ -63,26 +63,26 @@ The table lists the keys each adds. | Event | Keys under `docs` | When | |---|---|---| -| `docs_page_view` | `page_title` | The first page renders, and each later page change, once the new page's title is in place. Never twice for the same address, and never on `/oauth/callback`. | +| `docs_page_view` | `page_title` | The first page renders, and each later page change, once the new page's title is in place. Never twice in a row for the same address, and never on `/oauth/callback`. | | `docs_markdown_copy` | none | The page's "Copy Markdown" button, when the copy succeeded. | | `docs_plugin_install` | none | The Context Plugin page's install command, as its copy button is clicked. | | `docs_sdk_download` | `language` | A "Download SDK" link, on the SDKs page's cards or an SDK's own page. `language` is the SDK's, as `languages` names it in `apimatic.json`. | -| `docs_code_copy` | `language` | The copy button of a code block on any page, the API reference's examples included. `language` is the block's title, such as `TypeScript` or `Terminal`, or the selected tab's name in a tabbed block. A block with neither reports nothing, and neither does the install command's block, which has its own event. | -| `docs_search` | `search_term`, `result`, `result_count` | The search dialog closes after the reader typed in it: the term, the address of the result picked or empty when none was, and how many results the list showed. Reopening the dialog and closing it without typing again reports nothing. | +| `docs_code_copy` | `language` | The copy button of a code block on any page, the API reference's examples included. `language` is the block's title, such as `TypeScript` or `Terminal`, or for an untitled block in a tabbed set the selected tab's name. A block with neither reports nothing, nor does the install command's block, which has its own event, nor the playground's own blocks. | +| `docs_search` | `search_term`, `result`, `result_count` | The search dialog closes after the reader typed in it: the term, the address of the result picked or empty when none was, and how many results the list showed. `page_location` is the page the search was made on, not the result's. Reopening the dialog and closing it without typing or picking reports nothing. | | `docs_not_found` | `page_referrer` | The not-found page renders. `page_referrer` is the portal page the reader left for it after a portal link, or on a first load the browser's referrer without its query, or empty when the browser sends none. The page's own `docs_page_view` is sent too. | -| `docs_api_request` | `endpoint`, `status`, `duration_ms` | The API playground shows a result. `endpoint` is the method and path as the specification writes them, such as `GET /users/{id}`; `status` the HTTP status, or `client_error` for a request that never reached the API; `duration_ms` how long it took. It never carries the request's address, headers or body: those hold what the reader typed, keys included. | +| `docs_api_request` | `endpoint`, `status`, `duration_ms` | The API playground shows a result. `endpoint` is the method in capitals and the path as the specification writes it, such as `GET /users/{id}`; `status` the HTTP status, or `client_error` for a request that never reached the API; `duration_ms` how long it took. It never carries the request's address, headers or body: those hold what the reader typed, keys included. | With `googleAnalytics` set, the portal also sends each event to GA4 directly, under its name without the `docs_` prefix: `docs_page_view` arrives as `page_view` and `docs_search` as -`search`, which are GA4's own events with these same parameters, and the rest as custom -events. +`search`, which are GA4's own events; `page_title`, `page_location` and `search_term` are their own +parameters, and the rest arrive as custom events and parameters. #### Registering the keys in GA4 GA4 reports a custom parameter only once it is registered (Admin → Custom definitions). Register -five custom dimensions, `search_term`, `result`, `language`, `endpoint` and `status`, and two -custom metrics, `result_count` and `duration_ms`. Each appears in reports a day or two after. -`page_title`, `page_location` and `page_referrer` are GA4's own parameters and need nothing. +four custom dimensions, `result`, `language`, `endpoint` and `status`, and two custom metrics, +`result_count` and `duration_ms`. Each appears in reports a day or two after. `page_title`, +`page_location`, `page_referrer` and `search_term` are GA4's own parameters and need nothing. ### Google Analytics 4 @@ -97,8 +97,8 @@ custom metrics, `result_count` and `duration_ms`. Each appears in reports a day extension, so DebugView shows your session, then move between pages. DebugView must show one `page_view` per page change. Two per change means the setting in step 2 is still on; in reports, double counting shows as views climbing to about twice what readers saw. -4. Redact `code` and `state`: Admin → Data streams → your stream → Redact data → add both as - query parameters. The portal never reports them, but GA4's own collection can read a page's +4. Redact `code` and `state`: Admin → Data streams → your stream → Configure tag settings → + Show all → Redact data → add both as query parameters. The portal never reports them, but GA4's own collection can read a page's full address, and this keeps a sign-in answer out of it either way. 5. With `googleAnalytics` set, do not also add a GA4 tag for the same stream inside the GTM container: every hit would count twice. @@ -150,17 +150,18 @@ tag in the HTML. ### Consent Consent is yours to collect in this release. A consent banner inside the GTM container works as -it does on any site, with Google's Consent Mode deciding what each tag may send. With -`googleAnalytics` set directly, GA4 runs under Consent Mode once your banner sends its update. -A banner of your own, outside GTM, waits for a later portal setting. +it does on any site, with Google's Consent Mode deciding what each tag may send, so load GA4 +through the container when readers must consent first. `googleAnalytics` set directly cannot +wait for a banner: the portal configures GA4 as the page starts, before a banner inside the +container can set a consent default, so its first hits go out as consented. A banner of your +own, outside GTM, waits for a later portal setting. ### Content Security Policy -If the portal's host sets a CSP, allow the domains in -[Google's CSP guide](https://developers.google.com/tag-platform/security/guides/csp): the -tag manager and Google tag script on `https://www.googletagmanager.com`, and GA4's collection on -`https://*.google-analytics.com` and `https://*.analytics.google.com`, plus whatever each tag -inside the container loads. +If the portal's host sets a CSP, copy the `script-src`, `img-src` and `connect-src` lists from +[Google's CSP guide](https://developers.google.com/tag-platform/security/guides/csp), which name +`www.googletagmanager.com`, `*.googletagmanager.com`, `*.google-analytics.com` and +`*.analytics.google.com`, and add whatever each tag inside the container loads. ### Who can change the container @@ -170,11 +171,12 @@ page, and read what readers type. Give it only to people you would give the repo ### Session replay Session replay tools record what readers type. The API playground, where readers paste keys -and tokens, is wrapped in an element carrying the opt-out markers of PostHog (`ph-no-capture`), -FullStory (`fs-exclude`), rrweb (`rr-block`), Amplitude (`amp-block`), Hotjar -(`data-hj-suppress`), Microsoft Clarity (`data-clarity-mask`) and LogRocket (`data-private`), -so a replay shows the page with the playground blank. For any other tool, block the selector -`[data-portal-playground]` in its settings. +and tokens, carries the opt-out markers of PostHog (`ph-no-capture`), FullStory (`fs-exclude`), +rrweb (`rr-block`), Amplitude (`amp-block`), Hotjar (`data-hj-suppress`), Microsoft Clarity +(`data-clarity-mask`) and LogRocket (`data-private`): its header on the page, and the dialog it +opens, which is marked as it appears. A replay shows the page with the playground blank. For +any other tool, block the selector `[data-portal-playground]` in its settings, which both the +header and the dialog carry. ### After a sign-in @@ -205,3 +207,6 @@ In `v4/src/content/apimatic-cli/cli-reference.mdx`, both `apimatic portal genera | Flag | Description | |---|---| | `--no-analytics` | leave out Google Tag Manager, Google Analytics and every analytics or marketing script, for staging. | + +"Every analytics or marketing script" refers to `portal.scripts`, which a later release adds; until +then the flag leaves out the two Google tags. \ No newline at end of file diff --git a/portal-template/src/components/api-page.tsx b/portal-template/src/components/api-page.tsx index c9294ceb..608e9a02 100644 --- a/portal-template/src/components/api-page.tsx +++ b/portal-template/src/components/api-page.tsx @@ -3,6 +3,7 @@ import { createOpenAPIPage } from 'fumadocs-openapi/ui'; import { withBasePath } from '@/lib/base-path'; import { mediaAdapters } from '@/lib/media-adapters'; import { oauthCallbackPath } from '@/lib/oauth-callback'; +import { REPLAY_MARKERS } from '@/lib/replay-markers'; import { ApiMarkdown } from './api-markdown'; import { renderExampleLayout } from './example-layout'; import { codeUsages, renderUsageTabs } from './usage-tabs'; @@ -20,13 +21,7 @@ export const OpenAPIPage = createOpenAPIPage({ playground: { // Session replay tools a GTM tag loads record the page's text and input; each marker keeps its tool out of the playground. render: () => ( -
+
diff --git a/portal-template/src/components/not-found.tsx b/portal-template/src/components/not-found.tsx index 9b3225f4..e0351b1b 100644 --- a/portal-template/src/components/not-found.tsx +++ b/portal-template/src/components/not-found.tsx @@ -1,11 +1,14 @@ import { useEffect } from 'react'; +import { useLocation } from '@tanstack/react-router'; import { baseOptions } from '@/lib/layout.shared'; import { analytics } from '@/lib/portal-analytics'; import { HomeLayout } from 'fumadocs-ui/layouts/home'; import { DefaultNotFound } from 'fumadocs-ui/layouts/home/not-found'; export function NotFound() { - useEffect(() => analytics.reportNotFound(document.referrer), []); + const { pathname } = useLocation(); + // Keyed on the path: the same component shows the next missing page too. + useEffect(() => analytics.reportNotFound(document.referrer), [pathname]); return ( diff --git a/portal-template/src/components/playground.tsx b/portal-template/src/components/playground.tsx index 03e2a11c..134e2db3 100644 --- a/portal-template/src/components/playground.tsx +++ b/portal-template/src/components/playground.tsx @@ -2,6 +2,7 @@ import { useEffect } from 'react'; import { useOperation } from 'fumadocs-openapi/operation'; import PlaygroundClient, { DefaultResultDisplay, type ResultDisplayProps } from 'fumadocs-openapi/ui/playground/client'; import { analytics } from '@/lib/portal-analytics'; +import { markForReplay } from '@/lib/replay-markers'; // Fumadocs' request has no callback of its own: the start is noted here, and the request goes on unchanged. const fetchOptions = { @@ -25,5 +26,20 @@ const components = { ResultDisplay }; /** The playground with the reporting around it, in the one chunk the API page loads lazily. */ export default function Playground() { + // Fumadocs renders the dialog outside the marked wrapper, so each dialog is marked as it appears, + // until fuma-nama/fumadocs#3824 lets the markers be passed to the dialog directly. + useEffect(() => { + const observer = new MutationObserver((mutations) => { + for (const { addedNodes } of mutations) { + for (const node of addedNodes) { + if (!(node instanceof Element)) continue; + const dialog = node.matches('[role="dialog"]') ? node : node.querySelector('[role="dialog"]'); + if (dialog !== null) markForReplay(dialog); + } + } + }); + observer.observe(document.body, { childList: true, subtree: true }); + return () => observer.disconnect(); + }, []); return ; } diff --git a/portal-template/src/components/search.tsx b/portal-template/src/components/search.tsx index 83a5615c..cfbf6969 100644 --- a/portal-template/src/components/search.tsx +++ b/portal-template/src/components/search.tsx @@ -14,7 +14,7 @@ import { import { useDocsSearch } from 'fumadocs-core/search/client'; import { staticClient } from 'fumadocs-core/search/client/orama-static'; import { useI18n } from 'fumadocs-ui/contexts/i18n'; -import { useMemo, useRef } from 'react'; +import { useEffect, useMemo, useRef } from 'react'; import { withBasePath } from '@/lib/base-path'; import { analytics } from '@/lib/portal-analytics'; @@ -36,12 +36,19 @@ export default function DefaultSearchDialog(props: SharedProps) { const typed = useRef(false); const picked = useRef(''); + const openedAt = useRef(''); + + // The page the search is made on: a pick changes the address before the dialog reports its close. + useEffect(() => { + if (props.open) openedAt.current = window.location.href; + }, [props.open]); const onSearchChange = (value: string) => { typed.current = true; setSearch(value); }; const onSelect = (item: SearchItemType) => { + typed.current = true; picked.current = 'url' in item ? item.url : ''; }; const onOpenChange = (open: boolean) => { @@ -49,9 +56,10 @@ export default function DefaultSearchDialog(props: SharedProps) { if (open || !typed.current) return; typed.current = false; const count = results?.length ?? 0; + const page = openedAt.current; // Fumadocs closes the dialog before it hands over the pick, so the report waits a tick for it. window.setTimeout(() => { - analytics.reportSearch(search, picked.current, count); + analytics.reportSearch(search, picked.current, count, page); picked.current = ''; }, 0); }; diff --git a/portal-template/src/lib/analytics.ts b/portal-template/src/lib/analytics.ts index add71f50..a63d34e4 100644 --- a/portal-template/src/lib/analytics.ts +++ b/portal-template/src/lib/analytics.ts @@ -29,8 +29,8 @@ const KEPT_NAMES = new Set([ */ export interface PortalEvents { docs_page_view: { page_title: string }; - docs_markdown_copy: Record; - docs_plugin_install: Record; + docs_markdown_copy: Record; + docs_plugin_install: Record; docs_sdk_download: { language: string }; docs_code_copy: { language: string }; docs_search: { search_term: string; result: string; result_count: number }; @@ -68,10 +68,12 @@ const GOOGLE = 'https://www.googletagmanager.com'; export const adapters: { [V in Vendor]: (setting: NonNullable) => Adapter } = { googleTagManager: (setting) => { const env = setting.environment; - const environment = env ? `>m_auth=${env.auth}>m_preview=${env.preview}>m_cookies_win=x` : ''; + const environment = env + ? `>m_auth=${encodeURIComponent(env.auth)}>m_preview=${encodeURIComponent(env.preview)}>m_cookies_win=x` + : ''; return { setup: (dataLayer) => dataLayer.push({ 'gtm.start': Date.now(), event: 'gtm.js' }), - scripts: () => [`${GOOGLE}/gtm.js?id=${setting.containerId}${environment}`], + scripts: () => [`${GOOGLE}/gtm.js?id=${encodeURIComponent(setting.containerId)}${environment}`], send: () => {} }; }, @@ -86,7 +88,7 @@ export const adapters: { [V in Vendor]: (setting: NonNullable [`${GOOGLE}/gtag/js?id=${setting.measurementId}`], + scripts: () => [`${GOOGLE}/gtag/js?id=${encodeURIComponent(setting.measurementId)}`], // GA4 gets its own names: the `docs_` prefix comes off. send: (name, params) => gtag('event', name.replace(/^docs_/, ''), params) }; @@ -114,11 +116,10 @@ export function pageLocation(href: string, keep: readonly string[], base?: strin export function copiedLanguage(button: Element): string | null { const figure = button.closest('figure'); if (figure === null) return null; + const caption = figure.querySelector('figcaption')?.textContent?.trim(); + if (caption) return caption; const tabs = figure.closest('[role="tabpanel"]')?.parentElement; - const name = tabs - ? tabs.querySelector('[role="tab"][aria-selected="true"]')?.textContent - : figure.querySelector('figcaption')?.textContent; - return name?.trim() || null; + return tabs?.querySelector('[role="tab"][aria-selected="true"]')?.textContent?.trim() || null; } /** The one instance a portal runs: started when the bundle evaluates, reporting from the root effect and the components. */ @@ -127,7 +128,9 @@ export class Analytics { private started = false; private lastPageView: string | null = null; private previousPageView: string | null = null; - private requestStartedAt = 0; + private lastNotFound: string | null = null; + private requestStartedAt: number | null = null; + private lastApiResult: FetchResult | null = null; public constructor(private readonly settings: PortalAnalytics) { if (settings.googleTagManager) this.live.push(adapters.googleTagManager(settings.googleTagManager)); @@ -148,8 +151,9 @@ export class Analytics { } } - public report(name: E, params: PortalEvents[E]): void { - const page_location = pageLocation(window.location.href, this.settings.keepQueryParams); + /** `href` is the page the event belongs to, the current one unless the caller saw the address change first. */ + public report(name: E, params: PortalEvents[E], href = window.location.href): void { + const page_location = pageLocation(href, this.settings.keepQueryParams); if (page_location === null) return; const docs = { ...params, page_location }; const dataLayer = (window.dataLayer ??= []); @@ -170,19 +174,25 @@ export class Analytics { /** For a click anywhere on the page: a code block's copy button reports the copy with the block's language. */ public reportCodeCopy(target: EventTarget | null): void { const button = target !== null && 'closest' in target ? (target as Element).closest('figure button') : null; - // A block that reports its own copy, such as the install command, is not a code copy as well. - if (button === null || button.closest('[data-copy-reported]') !== null) return; + if (button === null) return; + // Not a copy: a dropdown in a block's header, the playground's dialog, or a block that reports its own copy. + if (button.matches('[role="combobox"]') || button.matches('[aria-haspopup]')) return; + if (button.closest('[role="dialog"]') !== null || button.closest('[data-copy-reported]') !== null) return; const language = copiedLanguage(button); if (language !== null) this.report('docs_code_copy', { language }); } - /** One search, as the dialog closes: what was typed, the result picked or '' for none, and how many were shown. */ - public reportSearch(term: string, picked: string, resultCount: number): void { + /** One search, as the dialog closes: what was typed, the pick or '' for none, the count shown, and the page searched from. */ + public reportSearch(term: string, picked: string, resultCount: number, href: string): void { const search_term = term.trim(); if (search_term === '') return; - this.report('docs_search', { search_term, result: picked, result_count: resultCount }); + this.report('docs_search', { search_term, result: picked, result_count: resultCount }, href); } - /** The not-found page: `page_referrer` is the portal page left for it, else the document's referrer without its query. */ + /** The not-found page, once per missing page: `page_referrer` is the portal page left for it, else the document's referrer without its query. */ public reportNotFound(documentReferrer: string): void { + const page = pageLocation(window.location.href, this.settings.keepQueryParams); + // A dev build mounts the page twice; the next missing page is a new report. + if (page === null || page === this.lastNotFound) return; + this.lastNotFound = page; const referrer = documentReferrer === '' ? null : new URL(documentReferrer); if (referrer !== null) { referrer.search = ''; @@ -190,17 +200,21 @@ export class Analytics { } this.report('docs_not_found', { page_referrer: this.previousPageView ?? referrer?.href ?? '' }); } - /** As the playground sends a request: the start of the one duration a request that never arrives can have. */ + /** As the playground sends a request: the start of the one duration a request that never arrives can have; a request failing before this has none. */ public requestStarted(): void { this.requestStartedAt = Date.now(); } /** The playground's result for `endpoint`, the method and path as the spec writes them: its status and its time, and nothing of the request itself. */ public reportApiRequest(endpoint: string, result: FetchResult): void { + // The display mounts again with the same result on each reopen, and twice in a dev build. + if (result === this.lastApiResult) return; + this.lastApiResult = result; const [status, duration_ms] = result.type === 'response' ? [String(result.status), Math.round(result.duration)] - : ['client_error', Date.now() - this.requestStartedAt]; + : ['client_error', this.requestStartedAt === null ? 0 : Date.now() - this.requestStartedAt]; + this.requestStartedAt = null; this.report('docs_api_request', { endpoint, status, duration_ms }); } } diff --git a/portal-template/src/lib/replay-markers.ts b/portal-template/src/lib/replay-markers.ts new file mode 100644 index 00000000..a001a5b1 --- /dev/null +++ b/portal-template/src/lib/replay-markers.ts @@ -0,0 +1,16 @@ +/** The opt-out markers of the session replay tools a GTM tag may load; each keeps its tool out of the element. */ +export const REPLAY_MARKERS = { + className: 'ph-no-capture fs-exclude rr-block amp-block', + 'data-hj-suppress': '', + 'data-clarity-mask': 'True', + 'data-private': '', + 'data-portal-playground': '' +} as const; + +/** The same markers on an element Fumadocs renders outside the wrapper, such as the playground's dialog. */ +export function markForReplay(element: Element): void { + element.classList.add(...REPLAY_MARKERS.className.split(' ')); + for (const [name, value] of Object.entries(REPLAY_MARKERS)) { + if (name !== 'className') element.setAttribute(name, value); + } +} diff --git a/portal-template/src/routes/__root.tsx b/portal-template/src/routes/__root.tsx index f6b37a9d..db69ef9b 100644 --- a/portal-template/src/routes/__root.tsx +++ b/portal-template/src/routes/__root.tsx @@ -27,11 +27,11 @@ const iconLinks = portal.favicon ] : []; -// A portal fixed to one mode keeps to it whatever the visitor's system prefers, and offers no -// way out: the layout hides the switch, and the `D` hotkey is turned off here. // Fumadocs' copy button has no callback of its own, so the document hears every click. const reportCodeCopy = (event: MouseEvent) => analytics.reportCodeCopy(event.target); +// A portal fixed to one mode keeps to it whatever the visitor's system prefers, and offers no +// way out: the layout hides the switch, and the `D` hotkey is turned off here. const theme = portal.colorMode === 'both' ? undefined diff --git a/test/e2e/portal-build.test.ts b/test/e2e/portal-build.test.ts index 7efd4d2f..7172605b 100644 --- a/test/e2e/portal-build.test.ts +++ b/test/e2e/portal-build.test.ts @@ -277,6 +277,8 @@ const stylesheetOf = (output: DirectoryPath) => { it('tells the browser both vendor IDs in a script, and names the tag host in no prerendered page', () => { const scripts = scriptsOf(portal.output()); expect(scripts.some(({ text }) => text.includes('GTM-E2ETEST') && text.includes('G-E2ETEST'))).to.be.true; + // The loader itself, not only the identity file the IDs sit in. + expect(scripts.some(({ text }) => text.includes('gtm.js?id=') && text.includes('/gtag/js?id='))).to.be.true; for (const page of pages()) { expect(read(page), page).to.not.contain('googletagmanager.com'); } @@ -289,7 +291,7 @@ const stylesheetOf = (output: DirectoryPath) => { } }); - it('prerenders the operation page’s playground inside the element session replays skip', () => { + it('prerenders the operation page’s playground header inside the element session replays skip', () => { const parts = read('api/apimatic-calculator/simple-calculator/Calculate/index.html').split( 'data-portal-playground' ); diff --git a/test/portal-template/analytics.test.ts b/test/portal-template/analytics.test.ts index fc552a95..53ae8d16 100644 --- a/test/portal-template/analytics.test.ts +++ b/test/portal-template/analytics.test.ts @@ -93,7 +93,8 @@ describe('pageLocation', () => { }); describe('PortalEvents', () => { - // The compiler holds this table to the interface: a missing event, a missing key or an extra key does not compile. + // The compiler holds this table to the interface: a missing event, a missing key, or an extra key on an event with + // keys does not compile; an event with no keys takes none at report(). const events: { [E in PortalEventName]: Record } = { docs_page_view: { page_title: true }, docs_markdown_copy: {}, @@ -132,6 +133,10 @@ class FakeElement { for (const child of children) child.parentElement = this; } + public matches(selector: string): boolean { + return this.selectors.includes(selector); + } + public closest(selector: string): FakeElement | null { return this.selectors.includes(selector) ? this : this.parentElement?.closest(selector) ?? null; } @@ -180,6 +185,17 @@ describe('copiedLanguage', () => { expect(copiedLanguage(element(tabbedBlocks(['cURL', 'TypeScript'], 'cURL')))).to.equal('cURL'); }); + it('prefers the caption of a titled block inside a tabbed set', () => { + const { figure, button } = codeBlock('Terminal'); + const tab = new FakeElement(['[role="tab"]', '[role="tab"][aria-selected="true"]'], 'macOS'); + new FakeElement([], null, [ + new FakeElement(['[role="tablist"]'], null, [tab]), + new FakeElement(['[role="tabpanel"]'], null, [figure]) + ]); + + expect(copiedLanguage(element(button))).to.equal('Terminal'); + }); + it('is null for a block with neither, and for a button outside any block', () => { expect(copiedLanguage(element(codeBlock(null).button))).to.be.null; expect(copiedLanguage(element(new FakeElement(['button'])))).to.be.null; @@ -316,6 +332,17 @@ describe('Analytics', () => { expect(page.window.gtag).to.be.undefined; }); + it("escapes the container's ID and the environment's values in the tag's address", () => { + const page = browser(quickstart); + const setting = { containerId: 'GTM-A&B', environment: { auth: 'a&b', preview: 'env 3' } }; + + new Analytics({ ...none, googleTagManager: setting }).start(); + + expect(page.scripts.map((script) => script.src)).to.deep.equal([ + 'https://www.googletagmanager.com/gtm.js?id=GTM-A%26B>m_auth=a%26b>m_preview=env%203>m_cookies_win=x' + ]); + }); + it("loads the container's environment when one is set", () => { const page = browser(quickstart); @@ -367,6 +394,16 @@ describe('Analytics', () => { expect(page.dataLayer().some(Array.isArray)).to.be.false; }); + it("escapes the measurement ID in the tag's address", () => { + const page = browser(quickstart); + + new Analytics({ ...none, googleAnalytics: { measurementId: 'G-A#B' } }).start(); + + expect(page.scripts.map((script) => script.src)).to.deep.equal([ + 'https://www.googletagmanager.com/gtag/js?id=G-A%23B' + ]); + }); + it('uses a gtag the page already defines, rather than replacing it', () => { const page = browser(quickstart); const calls: unknown[][] = []; @@ -518,20 +555,6 @@ describe('Analytics', () => { expect(received).to.not.match(/code=|token=|#/); }); - it('turns on no session recording or input capture', () => { - const page = browser(quickstart); - const analytics = new Analytics(settings); - - analytics.start(); - analytics.reportPageView(); - - const everything = JSON.stringify([ - ...page.dataLayer().map((entry) => (isArguments(entry) ? Array.from(entry as ArrayLike) : entry)), - ...page.scripts.map((script) => script.src) - ]); - expect(everything).to.not.match(/record|capture|replay|heatmap/i); - }); - it('inserts only https scripts, none inline', () => { expect(adapter().scripts()).to.not.be.empty; for (const src of adapter().scripts()) expect(src).to.match(/^https:\/\//); @@ -570,10 +593,7 @@ describe('Analytics', () => { const page = browser(quickstart); const analytics = new Analytics(none); analytics.start(); - // PR 3's events differ in their keys; until one lands, an extra key on a page view stands in for that. - const withExtraKey = { page_title: 'A', language: 'python' }; - - analytics.report('docs_page_view', withExtraKey); + analytics.report('docs_code_copy', { language: 'python' }); analytics.report('docs_page_view', { page_title: 'B' }); expect(mergedLikeGtm(page.dataLayer()).docs).to.deep.equal({ page_title: 'B', page_location: quickstart }); @@ -662,6 +682,25 @@ describe('Analytics', () => { expect(codeCopies(page.dataLayer())).to.be.empty; }); + + it('reports nothing for a dropdown in a block’s header, nor for anything in the playground’s dialog', () => { + const page = browser(address); + const analytics = new Analytics(none); + const dropdown = new FakeElement(['figure button', '[role="combobox"]']); + new FakeElement(['figure'], null, [ + new FakeElement([], null, [new FakeElement(['figcaption'], 'Request'), dropdown]) + ]); + const menu = new FakeElement(['figure button', '[aria-haspopup]']); + new FakeElement(['figure'], null, [new FakeElement(['figcaption'], 'JSON'), menu]); + const inDialog = codeBlock('Body'); + new FakeElement(['[role="dialog"]'], null, [inDialog.figure]); + + analytics.reportCodeCopy(element(dropdown)); + analytics.reportCodeCopy(element(menu)); + analytics.reportCodeCopy(element(inDialog.button)); + + expect(codeCopies(page.dataLayer())).to.be.empty; + }); }); describe('reportSearch', () => { const address = 'https://docs.acme.com/guides/quickstart'; @@ -671,7 +710,7 @@ describe('Analytics', () => { it('reports the term trimmed, the pick and the count shown', () => { const page = browser(address); - new Analytics(none).reportSearch(' auth ', '/guides/authentication', 3); + new Analytics(none).reportSearch(' auth ', '/guides/authentication', 3, address); expect(searches(page.dataLayer())).to.deep.equal([ { @@ -684,7 +723,7 @@ describe('Analytics', () => { it('reports an empty result when the dialog closed without a pick', () => { const page = browser(address); - new Analytics(none).reportSearch('auth', '', 0); + new Analytics(none).reportSearch('auth', '', 0, address); expect(searches(page.dataLayer())).to.deep.equal([ { event: 'docs_search', docs: { search_term: 'auth', result: '', result_count: 0, page_location: address } } @@ -695,11 +734,21 @@ describe('Analytics', () => { const page = browser(address); const analytics = new Analytics(none); - analytics.reportSearch('', '', 0); - analytics.reportSearch(' ', '/guides/authentication', 1); + analytics.reportSearch('', '', 0, address); + analytics.reportSearch(' ', '/guides/authentication', 1, address); expect(searches(page.dataLayer())).to.be.empty; }); + + it('reports the page the search was made on, not the one a pick led to', () => { + const page = browser(address); + const analytics = new Analytics(none); + page.go('https://docs.acme.com/guides/authentication'); + + analytics.reportSearch('auth', '/guides/authentication', 3, address); + + expect(searches(page.dataLayer())).to.have.nested.property('[0].docs.page_location', address); + }); }); describe('reportNotFound', () => { const missing = 'https://docs.acme.com/guides/missing'; @@ -726,10 +775,23 @@ describe('Analytics', () => { const analytics = new Analytics(none); analytics.reportNotFound('https://www.google.com/search?q=acme+docs#top'); + page.go('https://docs.acme.com/guides/other-missing'); analytics.reportNotFound(''); expect(referrers(page.dataLayer())).to.deep.equal(['https://www.google.com/search', '']); }); + + it('reports a missing page once, however often its page mounts, and the next missing page again', () => { + const page = browser(missing); + const analytics = new Analytics(none); + + analytics.reportNotFound(''); + analytics.reportNotFound(''); + page.go('https://docs.acme.com/guides/also-missing'); + analytics.reportNotFound(''); + + expect(referrers(page.dataLayer())).to.deep.equal(['', '']); + }); }); describe('reportApiRequest', () => { const address = 'https://docs.acme.com/api/calc/Calculate'; @@ -780,5 +842,25 @@ describe('Analytics', () => { expect(Object.keys(entry.docs).sort()).to.deep.equal(['duration_ms', 'endpoint', 'page_location', 'status']); expect(JSON.stringify(entry)).to.not.contain('s3cret'); }); + + it('reports the same result once, however often the display mounts', () => { + const page = browser(address); + const analytics = new Analytics(none); + const result = { type: 'response', url, status: 200, duration: 5 } as never; + + analytics.reportApiRequest(endpoint, result); + analytics.reportApiRequest(endpoint, result); + analytics.reportApiRequest(endpoint, { type: 'response', url, status: 200, duration: 5 } as never); + + expect(requests(page.dataLayer())).to.have.length(2); + }); + + it('reports a request that failed before it was sent with no duration', () => { + const page = browser(address); + + new Analytics(none).reportApiRequest(endpoint, { type: 'client_error', url, message: 'No adapter' } as never); + + expect(requests(page.dataLayer())[0].docs).to.include({ status: 'client_error', duration_ms: 0 }); + }); }); }); From 0fbf185aa90d3aeec7c6e218bb8ad7ee0a13069c Mon Sep 17 00:00:00 2001 From: Muhammad Sohail Date: Thu, 12 Nov 2026 16:01:08 +0500 Subject: [PATCH 23/73] fix(portal): keep the GA4 warning quiet under --no-analytics The warning that a GA4 stream counts page changes twice fires only when the build loads GA4, so a staging build built with --no-analytics is not told to change a stream it does not report to. AnalyticsConfig holds GA4 as a GoogleAnalyticsSetting, named as the template names it, instead of a bare measurement ID rebuilt in two places. Quickstart names the two booleans it passes to serve, the prompt builds its message before logging it and links with a scheme, and the toJSON() comment says what the code does. Co-Authored-By: Claude Fable 5.1 --- src/actions/portal/generate.ts | 2 +- src/actions/quickstart.ts | 6 ++++-- src/prompts/portal/generate.ts | 10 +++++----- src/types/portal/config/analytics-config.ts | 22 ++++++++++++--------- src/types/portal/portal-config.ts | 2 +- test/actions/portal/generate.test.ts | 14 +++++++++++++ test/actions/portal/serve.test.ts | 1 + test/actions/quickstart.test.ts | 1 + test/prompts/portal/generate.test.ts | 2 +- test/types/apimatic-config/schema.test.ts | 12 +++++++++++ test/types/portal/portal-config.test.ts | 21 ++++++++++++++++++-- 11 files changed, 72 insertions(+), 21 deletions(-) diff --git a/src/actions/portal/generate.ts b/src/actions/portal/generate.ts index 1daf9ced..05bcbc3f 100644 --- a/src/actions/portal/generate.ts +++ b/src/actions/portal/generate.ts @@ -46,7 +46,7 @@ export class GenerateAction { return await prepare.execute(project, enableAnalytics, { confirm: () => this.confirmOverwrite(portalContext, portalDirectory, force), onPrepared: (portalProject, source) => { - if (source.config.usesGoogleAnalytics()) { + if (enableAnalytics && source.config.usesGoogleAnalytics()) { this.prompts.googleAnalyticsCountsPageChanges(); } return this.build(portalProject, source.config.siteAddress(), portalContext, portalDirectory, zipPortal); diff --git a/src/actions/quickstart.ts b/src/actions/quickstart.ts index 47c72536..24cb7b56 100644 --- a/src/actions/quickstart.ts +++ b/src/actions/quickstart.ts @@ -240,11 +240,13 @@ export class QuickstartAction { const structure = await this.fileService.getDirectory(project.sourceDirectory()); this.prompts.printDirectoryStructure(projectDirectory, structure); + const openInBrowser = true; + const enableAnalytics = true; const result = await new PortalServeAction(this.configDir, this.commandMetadata, null).execute( project, DEFAULT_PORTAL_PORT, - true, - true, + openInBrowser, + enableAnalytics, () => this.prompts.nextSteps(configFile) ); diff --git a/src/prompts/portal/generate.ts b/src/prompts/portal/generate.ts index 0c9fc8bd..6e1544a7 100644 --- a/src/prompts/portal/generate.ts +++ b/src/prompts/portal/generate.ts @@ -57,12 +57,12 @@ export class PortalGeneratePrompts { /** The portal reports its own page views, so a GA4 stream that also counts history changes counts each page twice. */ public googleAnalyticsCountsPageChanges() { - log.warn( + const message = `Google Analytics is set, so the portal sends its own page views. In GA4, turn off the stream's ` + - `"Page changes based on browser history events" (Admin → Data streams → your stream → Enhanced ` + - `measurement → Page views → advanced settings), or every page change counts twice. ` + - `See the analytics page on ${f.link('docs.apimatic.io/v4')}.` - ); + `"Page changes based on browser history events" (Admin → Data streams → your stream → Enhanced ` + + `measurement → Page views → advanced settings), or every page change counts twice. ` + + `See the analytics page on ${f.link('https://docs.apimatic.io/v4/')}.`; + log.warn(message); } /** diff --git a/src/types/portal/config/analytics-config.ts b/src/types/portal/config/analytics-config.ts index 191774da..8ad5d479 100644 --- a/src/types/portal/config/analytics-config.ts +++ b/src/types/portal/config/analytics-config.ts @@ -8,16 +8,20 @@ export interface GoogleTagManagerSetting { environment: { auth: string; preview: string } | null; } +export interface GoogleAnalyticsSetting { + measurementId: string; +} + /** Public values: they sit in every page's scripts. */ export interface PortalAnalytics { googleTagManager: GoogleTagManagerSetting | null; - googleAnalytics: { measurementId: string } | null; + googleAnalytics: GoogleAnalyticsSetting | null; keepQueryParams: string[]; } export interface AnalyticsBlock { googleTagManager?: { containerId: string; environment?: { auth: string; preview: string } }; - googleAnalytics?: { measurementId: string }; + googleAnalytics?: GoogleAnalyticsSetting; keepQueryParams?: string[]; } @@ -26,7 +30,7 @@ const KNOWN = ['googleTagManager', 'googleAnalytics', 'keepQueryParams']; export class AnalyticsConfig { private constructor( private readonly googleTagManager: GoogleTagManagerSetting | null, - private readonly measurementId: string | null, + private readonly googleAnalytics: GoogleAnalyticsSetting | null, private readonly keepQueryParams: string[] ) {} @@ -41,19 +45,19 @@ export class AnalyticsConfig { optional(data.googleAnalytics, (vendor) => googleAnalytics(vendor, `${path}.googleAnalytics`)), keptQueryParams(data.keepQueryParams, `${path}.keepQueryParams`) ]) - ).map(([gtm, measurementId, keep]) => new AnalyticsConfig(gtm, measurementId, keep)) + ).map(([gtm, ga, keep]) => new AnalyticsConfig(gtm, ga, keep)) ); } /** `portal generate` warns when this is true: the customer has a GA4 stream setting to turn off. */ public usesGoogleAnalytics(): boolean { - return this.measurementId !== null; + return this.googleAnalytics !== null; } public identity(enableAnalytics: boolean): PortalAnalytics { return { googleTagManager: enableAnalytics ? this.googleTagManager : null, - googleAnalytics: enableAnalytics && this.measurementId !== null ? { measurementId: this.measurementId } : null, + googleAnalytics: enableAnalytics ? this.googleAnalytics : null, keepQueryParams: this.keepQueryParams }; } @@ -70,7 +74,7 @@ export class AnalyticsConfig { ...(gtm.environment === null ? {} : { environment: gtm.environment }) } }), - ...(this.measurementId === null ? {} : { googleAnalytics: { measurementId: this.measurementId } }), + ...(this.googleAnalytics === null ? {} : { googleAnalytics: this.googleAnalytics }), ...(this.keepQueryParams.length === 0 ? {} : { keepQueryParams: this.keepQueryParams }) }; return Object.keys(block).length === 0 ? null : block; @@ -100,14 +104,14 @@ function environment(value: unknown, path: string): Parsed<{ auth: string; previ ).map(([auth, preview]) => ({ auth, preview })); } -function googleAnalytics(value: unknown, path: string): Parsed { +function googleAnalytics(value: unknown, path: string): Parsed { if (!isJsonObject(value)) { return err([`'${path}' must be a JSON object with 'measurementId'.`]); } return allOf( unknownKeys(value, ['measurementId'], path), Result.combineWithAllErrors([required(value.measurementId, `${path}.measurementId`)]) - ).map(([measurementId]) => measurementId); + ).map(([measurementId]) => ({ measurementId })); } /** Present and a non-empty string; its format is the vendor's to check, since a wrong value fails there, not here. */ diff --git a/src/types/portal/portal-config.ts b/src/types/portal/portal-config.ts index 0137d016..18c81553 100644 --- a/src/types/portal/portal-config.ts +++ b/src/types/portal/portal-config.ts @@ -146,7 +146,7 @@ export class PortalConfig { }; } - /** Every namespace included, defaults and all, which is what quickstart writes. */ + /** Every namespace included, defaults and all, which is what quickstart writes; `analytics` and `seo` only when set. */ public toJSON(): PortalBlock { const analytics = this.analytics.toJSON(); const seo = this.seo.toJSON(); diff --git a/test/actions/portal/generate.test.ts b/test/actions/portal/generate.test.ts index 4a89de38..794cc388 100644 --- a/test/actions/portal/generate.test.ts +++ b/test/actions/portal/generate.test.ts @@ -340,6 +340,20 @@ describe('GenerateAction', () => { expect(prompts.googleAnalyticsCountsPageChanges.calledBefore(build)).to.be.true; }); + it('does not warn about Google Analytics under --no-analytics, which loads none', async () => { + const project = new DirectoryPath(root).join('staging'); + fs.cpSync(FIXTURE.toString(), project.toString(), { recursive: true }); + const configFile = path.join(project.toString(), 'src', 'apimatic.json'); + const edited = JSON.parse(fs.readFileSync(configFile, 'utf8')); + edited.portal.analytics = { googleAnalytics: { measurementId: 'G-ABC123' } }; + fs.writeFileSync(configFile, JSON.stringify(edited)); + + const result = await execute(project, false, false, false); + + expect(result.isSuccess()).to.be.true; + expect(prompts.googleAnalyticsCountsPageChanges.called).to.be.false; + }); + it('does not warn about Google Analytics when it is not set', async () => { const result = await execute(); diff --git a/test/actions/portal/serve.test.ts b/test/actions/portal/serve.test.ts index b3e2417e..53515a70 100644 --- a/test/actions/portal/serve.test.ts +++ b/test/actions/portal/serve.test.ts @@ -900,6 +900,7 @@ describe('PortalServeAction', () => { await save(config); }, false); + expect(shared.prepare.firstCall.args[3]).to.be.false; expect(applyConfig.lastCall.args[2]).to.be.false; }); diff --git a/test/actions/quickstart.test.ts b/test/actions/quickstart.test.ts index 66d4cc31..81ea971e 100644 --- a/test/actions/quickstart.test.ts +++ b/test/actions/quickstart.test.ts @@ -127,6 +127,7 @@ describe('QuickstartAction', () => { // prepares a project. expect(artifacts.called, 'the wizard asked for the artifacts').to.be.true; expect(prepare.called, 'the wizard reached the preview').to.be.true; + expect(prepare.firstCall.args[3], 'the preview counts like a hosted portal').to.be.true; }); it('asks for nothing more and stops when no language is chosen', async () => { diff --git a/test/prompts/portal/generate.test.ts b/test/prompts/portal/generate.test.ts index 80f34e37..2aa61854 100644 --- a/test/prompts/portal/generate.test.ts +++ b/test/prompts/portal/generate.test.ts @@ -20,7 +20,7 @@ describe('PortalGeneratePrompts', () => { "Google Analytics is set, so the portal sends its own page views. In GA4, turn off the stream's " + '"Page changes based on browser history events" (Admin → Data streams → your stream → Enhanced ' + 'measurement → Page views → advanced settings), or every page change counts twice. ' + - 'See the analytics page on docs.apimatic.io/v4.' + 'See the analytics page on https://docs.apimatic.io/v4/.' ); }); }); diff --git a/test/types/apimatic-config/schema.test.ts b/test/types/apimatic-config/schema.test.ts index 058f00a0..14718590 100644 --- a/test/types/apimatic-config/schema.test.ts +++ b/test/types/apimatic-config/schema.test.ts @@ -152,6 +152,7 @@ describe('apimatic.schema.json', () => { ], ['a Universal Analytics ID as the measurement ID', { analytics: { googleAnalytics: { measurementId: 'UA-1' } } }], ['a kept name with a space, and an OAuth answer name', { analytics: { keepQueryParams: ['a b', 'code'] } }], + ['an empty list of kept names', { analytics: { keepQueryParams: [] } }], ['a verification value with a space', { seo: { googleSiteVerification: 'abc 123' } }] ]; @@ -277,6 +278,17 @@ describe('apimatic.schema.json', () => { ['kept names that are not a list', { analytics: { keepQueryParams: 'campaign_id' } }], ['a kept name that is not a string', { analytics: { keepQueryParams: [1] } }], ['seo that is not an object', { seo: 'abc' }], + ['analytics that is null', { analytics: null }], + [ + 'an environment without its auth', + { analytics: { googleTagManager: { containerId: 'GTM-ABC123', environment: { preview: 'env-3' } } } } + ], + [ + 'a GA4 block with a key beside the ID', + { analytics: { googleAnalytics: { measurementId: 'G-ABC123', debug: true } } } + ], + ['a blank kept name', { analytics: { keepQueryParams: [' '] } }], + ['an unknown seo key', { seo: { foo: 1 } }], ['a blank verification value', { seo: { googleSiteVerification: ' ' } }] ]; diff --git a/test/types/portal/portal-config.test.ts b/test/types/portal/portal-config.test.ts index 2a2615a0..6b379ac6 100644 --- a/test/types/portal/portal-config.test.ts +++ b/test/types/portal/portal-config.test.ts @@ -492,9 +492,10 @@ describe('PortalConfig', () => { expect(errorsOf({ analytics: { keepQueryParams: 'campaign_id' } })).to.deep.equal([ `'${keep}' must be a list of query parameter names.` ]); - expect(errorsOf({ analytics: { keepQueryParams: ['', 1] } })).to.deep.equal([ + expect(errorsOf({ analytics: { keepQueryParams: ['', ' ', 1] } })).to.deep.equal([ `'${keep}[0]' must be a non-empty string.`, - `'${keep}[1]' must be a non-empty string.` + `'${keep}[1]' must be a non-empty string.`, + `'${keep}[2]' must be a non-empty string.` ]); }); @@ -530,6 +531,20 @@ describe('PortalConfig', () => { }); }); + it('refuses a null block, and an environment without its auth value', () => { + expect(errorsOf({ analytics: null })).to.deep.equal(["'portal.analytics' must be a JSON object."]); + expect( + errorsOf({ analytics: { googleTagManager: { containerId: 'GTM-ABC123', environment: { preview: 'env-3' } } } }) + ).to.deep.equal([`'${gtm}.environment.auth' is required.`]); + }); + + it('keeps an empty list of names as none', () => { + expect(config({ analytics: { keepQueryParams: [] } }).identity(true).analytics.keepQueryParams).to.deep.equal([]); + expect(JSON.parse(JSON.stringify(config({ analytics: { keepQueryParams: [] } })))).to.not.have.property( + 'analytics' + ); + }); + it('uses Google Analytics only with a measurement ID', () => { expect(config({}).usesGoogleAnalytics()).to.be.false; expect(config({ analytics: { googleTagManager: { containerId: 'GTM-ABC123' } } }).usesGoogleAnalytics()).to.be @@ -564,6 +579,8 @@ describe('PortalConfig', () => { it('refuses a block that is not an object, and a blank value', () => { expect(errorsOf({ seo: 'abc' })).to.deep.equal(["'portal.seo' must be a JSON object."]); + expect(errorsOf({ seo: null })).to.deep.equal(["'portal.seo' must be a JSON object."]); + expect(errorsOf({ seo: { foo: 1 } })).to.deep.equal(["'portal.seo.foo' is not a 'portal' setting."]); expect(errorsOf({ seo: { googleSiteVerification: ' ' } })).to.deep.equal([ "'portal.seo.googleSiteVerification' must be a non-empty string." ]); From b8a13e65ecf7eb755e9ec42868e939355c37ce74 Mon Sep 17 00:00:00 2001 From: Muhammad Sohail Date: Thu, 12 Nov 2026 16:01:08 +0500 Subject: [PATCH 24/73] docs(portal): add the analytics build plan The step-by-step plan the analytics PR was built from, with each step's commit, the branch table, the questions each step raised and their answers, and the review of 2026-11-12. Co-Authored-By: Claude Fable 5.1 --- .ai/plans/portal-analytics.md | 578 ++++++++++++++++++++++++++++++++++ 1 file changed, 578 insertions(+) create mode 100644 .ai/plans/portal-analytics.md diff --git a/.ai/plans/portal-analytics.md b/.ai/plans/portal-analytics.md new file mode 100644 index 00000000..15baba74 --- /dev/null +++ b/.ai/plans/portal-analytics.md @@ -0,0 +1,578 @@ +# Portal analytics, built in reviewable steps + +Status: planned 2026-11-11 from the locked plan. Steps 1.1 to 1.3 are on PR #473 (draft, stacked +on #472). On 2026-11-12 the remaining steps were reordered top-down, from each entry point +inward, after the first three produced a module nothing called yet; steps 1.6 and 1.7 were swapped +the same day, so the parser lands before the flag it reads. On 2026-11-12 PR 3, the other +seven events, was moved ahead of PR 2 and into PR #473, so GA4 and GTM can be tested with every +event before anything merges. Every decision is final; a +change from here is a new row in the Decisions table of apimatic/apimatic-io#2347. + +What the feature does, and why each decision was made, is written down in the issues, which +are the source of truth. This file says only in what order it is built and how each step is +reviewed. Where this file and an issue disagree, the issue wins and this file is corrected. + +| Source | Holds | Read it when | +|---|---|---| +| apimatic/apimatic-io#2347 | the plan: the eight events, the loader, the Decisions table (locked), the risks | starting, and whenever a "why" comes up | +| apimatic/apimatic-io#2348 | the build checklist for the three PRs, "Schema, validation and reports" (every rule and every message, verbatim), "Done when" | every step | +| apimatic/apimatic-io#2349 | PR 1 in detail, top-down, with code sketches for every file | every PR 1 step; PR 2 and PR 3 build on its `analyticsFor()` | +| Plan doc https://claude.ai/artifact/A6rr4cGkbEL3bRCnPGqWzy | the same plan as a document, with the diagram | only to settle a reading of the issues | +| Explainer https://claude.ai/artifact/RVbt9jerbNzTFyzGh4eE8t | the plain-language version | never needed for the build | + +Read an issue with `gh issue view --repo apimatic/apimatic-io` (they live in +apimatic-io, not in this repository). Shipped beside this plan: PR #472 in this repository +(fumadocs-openapi 12.6, PKCE, the `no-referrer` meta on `/oauth/callback`), and +fuma-nama/fumadocs#3809 and #3810. + +## 1. How a step works + +- Each step delivers one behaviour that runs, with the tests that prove it, and is small enough + to review in one sitting. A step creates only the code its behaviour needs: a class appears + the first time a step has something to hold, a method the first time a step calls it, a + message the first time it is said. +- Top-down, from a caller that exists. A step starts at an entry point that is already in the + tree (a command, a route, an effect, a component, the module the bundle evaluates) and adds + inward only what that caller needs. Nothing is written before the code that calls it, and a + pure helper is split out in the step whose caller needs it, with its tests, not before. Steps + 1.1 to 1.3 were built the other way round, before this rule; from 1.4 on every step follows it. +- Before writing, the agent says in a few lines what the step adds, which files it touches, and + asks the questions section 5 lists for it. Then it waits for a go. +- A step starts from the working tree as the reviewer left it. The agent never runs + `git commit` or `git push` on its own (`.ai/instructions.md`); the reviewer reads the diff, + tailors or refactors the code, and the next step builds on that. +- A step ends with these checks, run by the agent and reported with their output: + + ```bash + pnpm build # tsc on src + pnpm exec tsc -p test/tsconfig.json # the tests and the template modules they import + pnpm lint + pnpm prettier # or pnpm format, then show what it changed + pnpm exec tsx node_modules/mocha/bin/_mocha "test/" --timeout 99999 + pnpm test # the whole suite, at the end of each PR; sooner when a step touches shared code + ``` + +- The agent's report after a step: the files touched, the tests added by name, the output of + the checks, anything it could not verify, anything it found along the way but did not change, + and every place it departed from #2348 or #2349, with the reason. Nothing else. +- Three words from the reviewer drive the loop. `LGTM`: the step is accepted as it stands. + `commit`: the agent commits the step with the header its section names (Conventional Commits; + commitlint and lint-staged run on commit). `next`: the agent starts the next step with its + questions. Anything else is a change request on the current step. +- A step never widens. A problem found outside it goes in the report's "found" list; the + reviewer decides whether it becomes a step. +- A "check first" item (section 5) is answered with evidence from `node_modules` on the branch + before any code that depends on it is written, and the answer goes in the report. +- The manual checks (GTM Preview, GA4 DebugView, a playground sign-in) are the reviewer's, on a + test portal. The agent says which ones a step makes possible and leaves them to the reviewer. + +## 2. Rules for the code + +The conventions in `.ai/instructions.md` and `.ai/skills/` apply unchanged. These are the ones +this feature leans on most, plus its own. + +- **Functional core, imperative shell.** `pageLocation()`, the search and referrer helpers + (PR 3) are plain functions, tested without a DOM. The loader, `report()` and the React + effect are the shell. +- **The sketches in #2349 are the design, not the code.** Every name in them stands unless the + reviewer renames it. The agent may tighten a sketch to the repository's rules (no private + instance methods, no middlemen, `Promise` with early returns) and says where it did. +- **Messages verbatim.** Every parser report comes from the table in #2348, "Parser rules and + reports", word for word; the test asserts the whole sentence. The GA4 warning is the text in + #2348, "The GA4 warning". Since 2026-11-12 the parser checks presence and type only: a + vendor's ID, an environment value, the verification token and a kept name are any non-empty + string, with no pattern and no refused name, since a wrong value fails at the vendor, not in + the CLI; the schema (1.8) carries no patterns either. This replaces the locked "OAuth names + refused in `keepQueryParams`" and is the reviewer's to record in #2347's Decisions table. +- **Names are a contract.** An event name or key, once shipped, never changes. Names are + `docs_` plus lowercase snake_case, checked by a test. The three settled names are + `window.apimatic`, `window.apimatic.consent.update` (a later phase) and + `portal.seo.googleSiteVerification`. +- **`head()` lists no script**, in any PR. Everything loads through the loader, after the + bundle. (The wait for an address free of the nine OAuth answer names was removed on + 2026-11-12; see step 1.3.) +- **`analytics.ts` never imports `portal.ts`**, which loads the generated identity file; only + `portal-analytics.ts` does. Unit tests import `analytics.ts` with a fake `window`. +- **Every event sets all of its keys**, the compiler enforces it through `PortalEvents`, and + `report()` pushes `{ docs: null }` before `{ event, docs }`. The GA4 adapter and `subscribe` + keep flat params. +- **`docs_api_request` never carries** the request URL, body or headers. +- **Comments only for a why**, one line. The sketches carry some comments; keep only the ones + that explain a non-obvious decision (the `Arguments` object, the merge in GTM, the Suspense + order). +- **A helper only when a second caller or its own tests need it.** Logic used once stays inline + where it runs, written to read on its own. Nothing is written ahead of its caller: a function, + field or type with no use yet waits for the step that uses it. A stateful unit is a class with + flat public methods, not a closure over inner functions. + +## 3. Branches + +Start from `origin/dev` once PR #472 is merged; if it is still open, cut PR 1's branch from +`chore/fumadocs-openapi-12-6` and rebase onto `dev` after the merge, since the template work +depends on fumadocs-openapi 12.6. Confirm the base with `git log --oneline -1`. + +| PR | Branch | Cut from | Title (the squash commit) | +|---|---|---|---| +| 1 and 3 | `sohail/portal-analytics`, PR #473 | `chore/fumadocs-openapi-12-6` (#472 still open), rebased onto `dev` after the merge | `feat(portal): load Google Tag Manager and GA4 from portal.analytics and report the portal events` | +| 2 | `sohail/portal-scripts` | `sohail/portal-analytics`, once #473 merges | `feat(portal): load custom scripts from portal.scripts` | + +PR 3 was folded into #473 on 2026-11-12 (its steps follow PR 1's there, and the gate below applies +to both). PR 2 is independent of it and opens against `dev` once #473 is merged, with a PR body +that links #2348 and the issue's section it implements. Push only when the reviewer +says so. + +## 4. The steps + +| Step | A developer can | Size | +|---|---|---| +| 1.1 | clean an address and tell an OAuth answer from a campaign tag (done, `d703e0bd`, `bef3d350`) | small | +| 1.2 | start the vendors, report an event, and see one clean `docs_page_view` per page in the data layer (done, `62265fa3`) | medium | +| 1.3 | sign in through the playground and have the tags wait for a clean address (built as `1c616d56`, removed 2026-11-12; fuma-nama/fumadocs#3809 is the PR's merge prerequisite instead) | small | +| 1.4 | run a built portal against a hand-written identity file and see page views in GTM Preview | medium | +| 1.5 | see the verification meta on every page and the playground blank in a session replay (done, `7012bed8`) | small | +| 1.6 | write `portal.analytics` and `portal.seo` in `apimatic.json`, have them reach the browser, and be warned about GA4's own page views (done, `1538d831`) | medium | +| 1.7 | build or serve with `--no-analytics` and have the flag reach the identity file (done, `af636656`) | small | +| 1.8 | get editor help for the new settings, with the schema agreeing with the parser (done, `f654d592`) | small | +| 1.9 | prove it end to end on a built portal (done, `b698f389`) | small | +| 1.10 | read the README and the docs page draft (done, `c498fada`) | small | +| 2.1 | list a script in `portal.scripts` and have the CLI check it | medium | +| 2.2 | see listed scripts load in order, after the bundle, never beside an OAuth answer | small | +| 2.3 | subscribe to our events from a listed script | small | +| 2.4 | get editor help, the e2e proof and the docs draft for scripts | small | +| 3.1 | see `docs_markdown_copy`, `docs_plugin_install` and `docs_sdk_download` (done, `28817f70`) | small | +| 3.2 | see `docs_code_copy` with the block's language (done, `735533c8`) | small | +| 3.3 | see `docs_search` with the term, the pick and the count (done, `e81f86ae`) | small | +| 3.4 | see `docs_not_found` with a clean referrer (done, `1b19aef2`) | small | +| 3.5 | see `docs_api_request` with endpoint, status and duration, and nothing private (done, `5fae2090`) | medium | +| 3.6 | read the docs for all eight events (done, `cd8de5ea`) | small | + +### PR 1: the setting, the loader and page views + +Steps 1.1 to 1.3 are done and were built bottom-up. From 1.4 on, the order is top-down: first +the browser entry point, which gives the module its caller; then the CLI, from the command flag +inward to the parser; then the schema, the proof and the docs. + +#### Step 1.1: the pure functions (done) + +Delivers, in `portal-template/src/lib/analytics.ts` (new): the constants (`OAUTH_ANSWER`, +`KEPT_PREFIXES`, `KEPT_NAMES`), `pageLocation(href, keep, base?)`, `holdsOAuthAnswer(href)`, +the `PortalEvents` map with `docs_page_view` only, `PortalEventName`, `PortalEvent`, +`DataLayerEntry`. Nothing touches `window` yet. + +Tests, `test/portal-template/analytics.test.ts` (new): the `pageLocation()` cases (query and +`#` dropped; `utm_*`, `hsa_*`, each kept name and `keepQueryParams` kept; `gclidx` not; the +callback at the root, under `/docs/` and with a trailing slash gives `null`; otherwise the +address unchanged), the `holdsOAuthAnswer()` cases (each of the nine names alone, in the query +and after the `#`; `utm_source` and `campaign_id` false), and the event-name test +(`^docs_[a-z0-9_]+$`, at most 40 characters, at most 25 keys). + +Commit: `feat(portal): clean the reported page address`. + +#### Step 1.2: adapters, start, report and page views (done) + +Delivers: the `Adapter` interface and the `adapters` registry keyed by every vendor (GTM: +`gtm.start` entry, `gtm.js?id=…` with the `environment` suffix, `send` a no-op; GA4: +`window.gtag ??=` pushing `Arguments`, `js`, `config` with `send_page_view: false` and +`debug_mode` in a preview, `gtag/js?id=…`, `send` with the `docs_` prefix dropped); +`analyticsFor(settings)` with `startAnalytics()` (once; `window.dataLayer ??= []`; each +adapter's `setup()`; then `insert()` straight away when the address is clean, nothing when it +is not), `report()` (the cleaned `page_location`, nothing when it is `null`, the reset push, the +`{ event, docs }` push, each adapter's `send()`, the frozen event appended to `events`), and +`reportPageViews(router)` (the first page view at once, one per `onRendered`, none for the same +cleaned address, the unsubscribe). The 5-second wait is step 1.3. + +Tests: neither vendor; GTM only, with and without `environment`; GA4 only, including the +`[object Arguments]` check and `debugMode`; both, with every setup entry before the first event; +an existing `window.gtag` kept; a second start adds nothing; the shared adapter suite over the +registry (its setup turns off the vendor's page view; nothing it receives for a report made at +`…?code=x&state=y#access_token=z` holds `code=`, `token=` or `#`; no recording or input capture; +`send('docs_page_view')` maps to the vendor's page view; every script `https`, none inline); +the reset push (right before every event entry; the entry holds `event` and `docs` only; with a +helper that merges entries the way GTM does, a key from the previous event is gone after the +next); the replay list; `reportPageViews()` (first at once, one per `onRendered`, none for a `#` +or query change, A-B-A sends three, the returned function stops it); the callback sends no page +view but the setup entries are pushed. Fake `window` and `document` on `globalThis` as +`base-path.test.ts` does; a fresh instance per case. + +Commit: `feat(portal): report page views to the data layer and GA4`. + +#### Step 1.3: the loader waits out an OAuth answer (built, then removed) + +Built as `1c616d56` and removed on 2026-11-12: the wait made the loader hard to read for a +problem Fumadocs is fixing at the root. The PR now carries fuma-nama/fumadocs#3809 as a merge +prerequisite under "Before merging"; if Fumadocs does not ship it in time, the wait comes back +from that commit. This replaces the locked option A and is the reviewer's to record in #2347's +Decisions table. + +Delivers: `insertWhenClean()` as sketched: while the address holds an answer, a check every +100 ms for up to 50 checks, inserting once it is gone, the timer cleared after the last check, +and a later call on a clean address inserting; a call while it waits starts no second timer. +`startAnalytics()` calls it instead of `insert()`. + +Tests, with `sinon.useFakeTimers()` as `test/infrastructure/generation-status-poller.test.ts` +uses it: the setup entries at once; no script while the answer stays; a report meanwhile pushed +at once with a clean `page_location`; the insert at the next check once the answer is gone; the +timer cleared after 5 seconds and a later call inserting; no second timer. + +Commit: `feat(portal): hold vendor tags back while the address holds an OAuth answer`. + +#### Step 1.4: the bundle starts analytics and reports page views + +The browser entry point, which gives steps 1.1 to 1.3 their caller. It is the riskiest step, +because it is the browser timing, so it is checked in a browser before the CLI side is built. + +Delivers, from the entry point inward: + +- `portal-template/src/routes/__root.tsx`: the effect in `RootComponent` (subscribe + `insertWhenClean` to `onRendered`, then `reportPageViews(router)`, both undone on cleanup). + `head()` still lists no script. +- `portal-template/src/lib/portal-analytics.ts` (new): the one instance from + `portal.analytics`, `startAnalytics()` at module evaluation when `window` exists, exporting + `insertWhenClean`, `report` and `reportPageViews`. +- `portal-template/src/lib/portal-types.ts`: `analytics: PortalAnalytics` on `Portal`. +- `src/types/portal/portal-config.ts`: `analytics` on `PortalIdentity`, and `identity()` + filling it with the default (`null`, `null`, `[]`), so `Equal` in + `test/portal-template.test.ts` still holds. The parser is step 1.6. + +Tests: the existing suite stays green (`test/portal-template.test.ts`, the route tests); the +two `identity()` deep-equal cases gain `analytics`. The new behaviour is browser timing, which +the repository has no runner for, so the step's proof is manual: the reviewer edits +`portal.identity.json` in a prepared project (the file `appearanceFiles()` in +`src/infrastructure/portal-project-service.ts` writes) to hold a GTM container and a GA4 +stream, builds, and runs the manual list in #2349 ("Manual, on a test portal"): first-load +order, one `docs_page_view` per page change, the `#` link sending none, the OAuth wait with +both flows, DebugView with the stream setting on and off. The agent's report says how to +produce that build. + +Commit: `feat(portal): start analytics from the portal bundle`. + +#### Step 1.5: the verification meta and the playground out of replays (done) + +Delivers, from the two pages inward: + +- `portal-template/src/routes/__root.tsx`: `head()` gains the `google-site-verification` meta + when `seo.googleSiteVerification` is set. +- `portal-template/src/components/api-page.tsx`: the playground wrapped in the do-not-record + element, after the "check first" answers in section 5. +- `seo: PortalSeo` on `Portal` and on `PortalIdentity`, with `identity()` filling the default + (`null`). + +Tests: the existing suite; the two `identity()` cases gain `seo`. Manual: the meta in a built +page's ``; the playground blank in a Hotjar or Clarity replay loaded through a GTM tag. + +Commit: `feat(portal): add the site verification meta and keep the playground out of replays`. + +#### Step 1.6: the settings reach the browser, and the GA4 warning (done) + +Built before the flag (the two were swapped on 2026-11-12): until the parser exists, +`identity()` writes constants, so a flag passed to it would be a parameter nothing reads, +which the lint rule rejects and section 2 forbids. + +Delivers, from `apimatic.json` inward: + +- `src/types/portal/portal-config.ts`: `'analytics'` and `'seo'` in `NAMESPACES`, the two + fields after `ai`, the defaults in `scaffolded()`, the parsers in `fromBlock()`, `identity()` + filled from the config, `usesGoogleAnalytics()`, `toJSON()` writing both only when set, + `PortalBlock` gaining both as optional. +- `src/types/portal/config/analytics-config.ts` (new): `AnalyticsConfig` built like `AiConfig`, + with `defaults`, `parse()`, `usesGoogleAnalytics()`, `identity()`, `toJSON()`; every rule and + message from #2348's table, less the format rules (section 2). Both vendors are written whatever the command, until step 1.7 adds the flag. +- `src/types/portal/config/seo-config.ts` (new): `SeoConfig` the same way. +- `src/actions/portal/generate.ts`: once the project is prepared, before the build, when + `usesGoogleAnalytics()`, `this.prompts.googleAnalyticsCountsPageChanges()`; + `src/prompts/portal/generate.ts` prints the warning from #2348 with `log.warn`, in the style + of `src/prompts/portal/source.ts`'s config warnings. + +Tests: `test/types/portal/portal-config.test.ts`, `describe('analytics')` and +`describe('seo')` after `ai`, every case #2349 lists (absent, accepted with trimmed IDs, +`environment`, `keepQueryParams`, each message verbatim, several faults at once with unknown +keys first, `usesGoogleAnalytics()`, `toJSON()` round trip, `scaffolded()` writing neither); +`test/actions/portal/generate.test.ts` prints the warning only with `googleAnalytics` set, and +before the build; `test/prompts/portal/generate.test.ts` holds the warning's text. + +Commit: `feat(portal): read portal.analytics and portal.seo from apimatic.json`. + +#### Step 1.7: `--no-analytics` reaches the identity file (done) + +The CLI entry point. The flag exists and flows to the one place that reads it. `portal serve` +is a hosted portal in every way: the same tags, GA4 in its normal mode (decided 2026-11-12, +replacing the lock's debug-mode preview; the reviewer's to record in #2347). + +Delivers, from the commands inward, after the "check first" answer in section 5: + +- `src/commands/portal/generate.ts` and `src/commands/portal/serve.ts`: the `no-analytics` + boolean flag, description "leave out Google Tag Manager, Google Analytics and every analytics + or marketing script, for staging."; each passes `enableAnalytics: !flags['no-analytics']` to + its action; quickstart's preview passes `true`. +- `PreparePortalProjectAction`, `PortalProjectService.prepare()`, `applyConfig()` and + `appearanceFiles()` take `enableAnalytics: boolean` as a parameter, never a field; + `PortalConfig.identity(enableAnalytics)` hands it to `AnalyticsConfig.identity()`, which + leaves both vendors out when it is false; `src/actions/portal/serve.ts` hands the same value + to the rewrite when the block changes. The sketch's `PortalDelivery` class is not built: with + no preview mode it would wrap this one boolean. + +Tests: both commands accept the flag (`test/commands/flag-parser.ts` is the helper the command +tests use); `identity(false)` leaves both vendors out and keeps `keepQueryParams`; +`test/actions/portal/prepare-project.test.ts` and the stubs follow the new signature; the +generate, prepare and serve actions hand `--no-analytics` on, the serve action to the rewrite +too; the identity file written under `--no-analytics` has both vendors `null`. + +Commit: `feat(portal): add --no-analytics and leave the vendors out of the identity file`. + +#### Step 1.8: the schema (done) + +Delivers: `analytics` and `seo` in `apimatic.schema.json` from #2348's "Schema additions", +between `ai` and `pluginUrl`, less every `pattern` and the OAuth-name `not`, since the parser +checks presence and type only (section 2): each ID and value is `nonBlank`. The "every setting +at once" case gains both; the analytics and seo cases from #2348's "Cases for +`schema.test.ts`" go in `valid` and `invalid`, with the ones #2348 refused on format alone +moved to `valid`, so the parser and the schema agree on each. + +Tests: `test/types/apimatic-config/schema.test.ts`. + +Commit: `feat(portal): describe portal.analytics and portal.seo in the schema`. + +#### Step 1.9: the end-to-end proof (done) + +Delivers: in `test/e2e/portal-build.test.ts`, the default build reads a copy of its fixture +whose `portal` block gains `analytics` with `GTM-E2ETEST` and `G-E2ETEST` and `seo` with a +verification value (the fixture itself stays as it is: four other suites read it, and the +generate action's "does not warn" case needs it without GA4); the cases check a browser script +holds both IDs, no prerendered page names `googletagmanager.com`, every prerendered page +carries the meta tag, and the operation page holds the playground's prerendered header inside the +do-not-record element. The +`--no-analytics` identity file is proved by the project service test; a second Vite build for +the same two nulls is not worth a minute of the CI-only run. + +Commit: `test(portal): prove analytics and the verification tag in a built portal`. + +#### Step 1.10: README and the docs draft (done) + +Delivers: `pnpm readme` after `pnpm build` (colour on, `COLUMNS` unset) for the two flags; a +draft of the docs page, written to `.ai/plans/portal-analytics-docs.md`, covering every PR 1 +bullet in #2348's "Docs" list and #2349's additions, for the apimatic-docs repository +(`v4/src/content/apimatic-cli/cli-reference.mdx` gets the flag's row, same words as the +description). The draft is not a docs PR; the reviewer takes it there. + +Commit: `docs(portal): document portal.analytics` (the README part; the draft travels with it). + +**PR 1 gate** (since 2026-11-12 the #473 gate, applied once step 3.6 is done, with PR 3's manual +check, each event once in GTM Preview with all of its keys, on the list)**:** `pnpm test` green; the manual list in #2349 all checked by the reviewer; the +"Done when" lines in #2348 for loading, counting, nothing private and verification hold; the +fuma-nama/fumadocs#3809 item under "Before merging" in the PR body addressed (Fumadocs ships +the `sessionStorage` hand-over and the branch picks it up, else the wait of step 1.3 comes back +from `1c616d56`). Then the reviewer says to push and open the PR. + +### PR 2: `portal.scripts` and the subscribe helper + +#### Step 2.1: the setting + +Delivers: `src/types/portal/config/portal-script.ts` (new), one entry parsed as +`NavigationConfig.parseLinks()` parses links: `namespace()`, `unknownKeys()` against `src`, +`category`, `attributes`; `src` through `httpsAddress()` when it starts with `http:` or +`https:`, else `StaticAsset.parse()` with a scripts example; `category` through `oneOf()` with +`analytics` as the fallback; `attributes` keys matching `^data-[a-z0-9-]+$` with string values; +every error collected. `httpsAddress(value, path, example)` moved into `fields.ts` from +`portal-config.ts`'s `secureAddress()`, with `pluginUrl` on it. `PortalConfig`: `scripts` among +the known keys, parsed in `fromBlock()`, `staticFiles()` returning the listed static files +beside the brand files, `identity(enableAnalytics)` keeping the `necessary` and `functional` entries always and the rest only when the flag +allows, `toJSON()` writing `scripts` only when set with `category` and `attributes` only when +given. No class for it: the category rule is a function beside the parser. `scripts: PortalScript[]` on `PortalIdentity` and on +the template's `Portal` (`ScriptCategory`, `PortalScript` in `portal-types.ts`). + +Tests: `portal-config.test.ts` `describe('scripts')` with every message from #2348's table, +several entries' errors at once, the `analytics` fallback, the round trip, `identity()` under +`--no-analytics`, the `pluginUrl` cases still passing; `portal-source-context.test.ts` reports +a missing listed file as `portal.scripts[0]` like a missing logo; the category rule for +each category under both flags. + +Commit: `feat(portal): read portal.scripts from apimatic.json`. + +#### Step 2.2: the loader inserts listed scripts + +Delivers: `analyticsFor(settings, scripts)`; `insert()` adds each listed script after the +vendor tags, in order, `async = false`, static files through `withBasePath()`, each attribute +set on the element; a failed one doesn't stop the rest; vendor tags and listed scripts don't +wait for each other. + +Tests: order, `async`, base path, attributes; nothing listed while an answer stays; a failure +doesn't stop the next. + +Commit: `feat(portal): load listed scripts through the loader`. + +#### Step 2.3: `window.apimatic.analytics.subscribe()` + +Delivers: set up by `startAnalytics()` before any script is inserted; replays the events so far, +then each new one; returns an unsubscribe; each callback in `try`/`catch` with the error +rethrown through `setTimeout`; one `window.apimatic` object. + +Tests: a subscriber added after two reports gets both then each new one; the event is frozen; +a throwing subscriber doesn't stop the next and its error is rethrown later; the returned +function stops delivery. + +Commit: `feat(portal): let listed scripts subscribe to portal events`. + +#### Step 2.4: schema, e2e and the docs draft + +Delivers: `scripts` and the `httpsAddress` definition in the schema, `pluginUrl` moved onto it, +the scripts cases in `schema.test.ts` and `scripts` in "every setting at once"; the e2e fixture +gains `scripts`, `scriptsOf()` holds each address and attribute, no prerendered page names +them, a `--no-analytics` build keeps only `necessary` and `functional`; the `portal.scripts` +section appended to `.ai/plans/portal-analytics-docs.md` from #2348's PR 2 "Docs" list. + +Commit: `feat(portal): describe portal.scripts in the schema and prove it in a build`. + +**PR 2 gate:** `pnpm test` green; the PR 2 manual list in #2348 (Segment's debugger shows one +`page` per change, a never-answering host blocks nothing, a `functional` widget runs under +`serve`, an `analytics` script doesn't under `--no-analytics`); the "Scripts" line of "Done +when". + +### PR 3: the other portal events + +Before step 3.1, the agent rechecks the component references in #2348's event table against +the versions on the branch (fumadocs-ui 16.18.4, fumadocs-openapi 12.6.0) and checks each name +after the `docs_` prefix against GA4's recommended event names, and reports both. Each step +adds its entries to `PortalEvents` and reports through `portal-analytics.ts`'s `report()`. +Every event's keys are the ones in #2348's table; `report()` adds `page_location`. + +#### Step 3.1: the three click reporters (done) + +Delivers: `docs_markdown_copy` from `markdown-copy-button.tsx` when the copy succeeds; +`docs_plugin_install` from `plugin-install.tsx` through an `Actions` wrapper's +`onClickCapture`; `docs_sdk_download` with `language` from `sdk-actions.tsx`'s `DownloadLink`, +with `language="{{language}}"` added to `portal-pages/sdk.mdx`. + +Tests: each event's keys. The reporters firing once per action is on the manual list: the +template's component tests render to static markup through Vite and cannot click. + +Commit: `feat(portal): report Markdown copies, plugin installs and SDK downloads`. + +#### Step 3.2: `docs_code_copy` (done) + +Delivers: one document click listener for Fumadocs' copy button in a code block's `
`; +`language` from the `
` (`lib/code-titles.ts`) or the active tab's name; a plain +function that reads the language from the clicked element. + +Tests: the language from a titled block and from a tabbed one; a click elsewhere reports +nothing. + +Commit: `feat(portal): report code copies with the block's language`. + +#### Step 3.3: `docs_search` (done) + +Delivers: in `search.tsx`, one report per search when the dialog closes after the reader typed +something; the report waits a tick to see whether a result was picked; `result` the picked +address or empty, `result_count` the results shown; a plain function from the dialog's state to +the keys. + +Tests: one report with the pick; one with an empty `result` when the dialog closes without one; +none when nothing was typed. + +Commit: `feat(portal): report searches with the term, the pick and the count`. + +#### Step 3.4: `docs_not_found` (done) + +Delivers: in `not-found.tsx`, `page_referrer` as the previous portal page after an in-portal +link, or `document.referrer` without its query on a first load; a plain function for the +referrer rule. The page's `docs_page_view` still fires. + +Tests: the referrer from the previous portal page, and from another site without its query. + +Commit: `feat(portal): report the not-found page with a clean referrer`. + +#### Step 3.5: `docs_api_request` (done) + +Delivers: in `api-page.tsx`, `playground.fetchOptions.onRequestInit` recording the start time +and returning `requestInit` unchanged; a `ResultDisplay` wrapping Fumadocs' default and +reporting once per result with `endpoint` (method and path as the spec writes them), `status` +(the HTTP status or `client_error`) and `duration_ms`; never `data.url`, the body or the +headers; a plain function from a result to the keys. + +Tests: the keys from a `response` result and from a `client_error` result, never carrying the +request URL; the duration from the recorded start. + +Commit: `feat(portal): report playground requests without their contents`. + +#### Step 3.6: the docs draft (done) + +Delivers: the events section of `.ai/plans/portal-analytics-docs.md`: all eight events, keys, +when each fires; the five custom dimensions and two custom metrics to register in GA4. + +Commit: `docs(portal): document the eight portal events`. + +**PR 3 gate:** `pnpm test` green; each event once in GTM Preview with all of its keys, checked +by the reviewer; `docs_api_request` never carrying the request URL; the "Events" line of "Done +when". + +**Review of 2026-11-12** (three reviewers, fixed on the branch, uncommitted until the reviewer +says): the playground's dialog is marked for session replay as it opens, since Fumadocs portals it +outside the marked wrapper; `docs_search` carries the page searched from, captured when the +dialog opens, and a pick counts as a search; `docs_api_request` reports a result once however +often the display mounts, and a request failing before it was sent has no duration; the +code-copy listener ignores dropdowns and the playground's dialog, and prefers a block's caption +over its tab; `docs_not_found` reports once per missing page and again for the next, keyed on +the path; vendor values are escaped in the tag addresses; the GA4 warning stays quiet under +`--no-analytics`; the empty events take no keys at `report()`; the docs draft's consent, CSP, +replay, search and GA4 lines are corrected. `portal serve` runs under React's StrictMode, which is +why the once-per-result and once-per-page rules exist. The dialog marking is a workaround for fuma-nama/fumadocs#3824 (filed 2026-11-12), which asks for a prop that reaches the dialog; a follow-up to remove the observer once it ships, not a merge prerequisite. Rebased onto the base tip `d1e22066` on 2026-11-12, cleanly, with the fixes stashed and restored: the base holds fumadocs-openapi 12.6.0, having stepped back from 12.6.1 for the seven-day release-age rule. fuma-nama/fumadocs#3809 shipped in 12.6.2 on 2026-11-12 (12.6.1 answers #3810 only), which clears the rule on 2026-11-19, so the prerequisite stands until the base takes 12.6.2. + +## 5. Questions each step will raise + +Answered already, so the agent does not ask them: + +- Names: every name in #2349's sketches stands but one: the sketch's `PortalDelivery` is not + built. Since 2026-11-12 there is no preview mode, so what it carried is one boolean, + `enableAnalytics`, passed as a plain parameter. The config classes are `AnalyticsConfig` and + `SeoConfig` under `src/types/portal/config/`. +- `identity()` takes `enableAnalytics: boolean`; there is no second method for previews, and no + preview mode: `portal serve` loads the same tags a hosted portal does, GA4 in its normal mode. +- `--no-analytics` is a plain boolean flag with the description in step 1.7; there is no + `--with-analytics`. +- The parser's messages and the warning's text are the ones in #2348, less the format rules + dropped on 2026-11-12 (section 2); the schema has no patterns. +- `window.gtag` is defined only when GA4 is set. GTM gets no `send()`. +- The wait (100 ms × 50) was removed on 2026-11-12; if it comes back, it is not configurable. +- Unit tests fake `window` and `document` on `globalThis`; no browser runner is added. + +To check first, with evidence from `node_modules` on the branch, before the step's code: + +- **1.2 (answered 2026-11-11):** `@tanstack/router-core` 1.171.28 exposes `subscribe`; + `@tanstack/react-router` 1.170.33 queues `onRendered` at `Transitioner.js:45` and fires it + from the layout effect at `Matches.js:37`, after the commit in which `HeadContent` renders + the new title from the same matches store. +- **1.5:** which component fumadocs-openapi 12.6 renders for the playground ("Try in + Playground") and what `playground.render` receives; that the extra element leaves the layout + unchanged; whether the code samples beside the playground show what readers type (if so, + they are marked too); that `playground` client options still apply beside a custom renderer, + since 3.5 adds `fetchOptions` and `ResultDisplay`. +- **1.7:** how `PortalProjectService.prepare()` and the serve rewrite reach `identity()` today, + so the flag is passed once and not stored in two places. +- **1.9 (answered 2026-11-12):** the prerender resolves the lazy playground client, so the + operation page's HTML holds its header (method, route, the dialog trigger) inside the + do-not-record element; the forms arrive with the chunk in the browser. +- **3.1:** the current `Actions` prop of fumadocs-ui's `CodeBlock`, and the `DownloadLink` + props in `sdk-actions.tsx`. +- **3.2:** the copy button's position in fumadocs-ui 16.18.4's code block markup. +- **3.3:** whether fumadocs-ui 16.18.4's search dialog still calls `onOpenChange(false)` before + `onSelect`, and whether a result count is reachable from `search.tsx`. +- **3.5:** whether `useOperationContext().route` is available inside `ResultDisplay`, and where + the method comes from; which result shapes the display receives. + +For anything else unclear, the agent asks with options and their trade-offs, then waits. + +## 6. Out of scope + +APIMatic's own dashboard (a separate product decision), the ready-made GTM container (good to +have, after the release), Segment and PostHog adapters, script hardening (integrity checks, +build-time reachability), the consent setting (`window.apimatic.consent.update`), and the +docs PR itself in apimatic-docs. + +## 7. Starting a chat + +Paste this as the first message of a new Claude Code session in this repository: + +> Read `.ai/plans/portal-analytics.md` and the three issues it names (`gh issue view 2347`, +> `2348`, `2349` in `apimatic/apimatic-io`). Follow section 1 exactly: one step at a time, +> propose the step with its section 5 questions, wait for my go, build it, run the checks, and +> report. Do not commit or push unless I say `commit` or tell you to push. Start by confirming +> the base branch in section 3, then propose step 1.1. From 2dc7c4783b1520ff64c0366e0251612aa5ee8e1a Mon Sep 17 00:00:00 2001 From: Muhammad Sohail Date: Fri, 13 Nov 2026 10:04:59 +0500 Subject: [PATCH 25/73] fix(portal): report the first page view once the page's head is in place In `portal serve` the root effect runs while the router is still pending, before the page's own head has applied, so the first docs_page_view carried the site name as its title; the address dedupe then dropped the onRendered report that had the right one. A prerendered page mounts with the router idle and the right title, and raises no onRendered for its first page, so the direct report stays for that case: the effect now reports directly only when the router is idle at mount, and leaves the first page to onRendered otherwise. Seen with headless Chrome against both a served and a built portal, each sending one first page view with the page's title after the change. The plan records the end-to-end run. Co-Authored-By: Claude Fable 5.1 --- .ai/plans/portal-analytics.md | 10 ++++++++++ portal-template/src/routes/__root.tsx | 4 +++- 2 files changed, 13 insertions(+), 1 deletion(-) diff --git a/.ai/plans/portal-analytics.md b/.ai/plans/portal-analytics.md index 15baba74..707763cf 100644 --- a/.ai/plans/portal-analytics.md +++ b/.ai/plans/portal-analytics.md @@ -516,6 +516,16 @@ the path; vendor values are escaped in the tag addresses; the GA4 warning stays replay, search and GA4 lines are corrected. `portal serve` runs under React's StrictMode, which is why the once-per-result and once-per-page rules exist. The dialog marking is a workaround for fuma-nama/fumadocs#3824 (filed 2026-11-12), which asks for a prop that reaches the dialog; a follow-up to remove the observer once it ships, not a merge prerequisite. Rebased onto the base tip `d1e22066` on 2026-11-12, cleanly, with the fixes stashed and restored: the base holds fumadocs-openapi 12.6.0, having stepped back from 12.6.1 for the seven-day release-age rule. fuma-nama/fumadocs#3809 shipped in 12.6.2 on 2026-11-12 (12.6.1 answers #3810 only), which clears the rule on 2026-11-19, so the prerequisite stands until the base takes 12.6.2. +**End-to-end run of 2026-11-13** (headless Chrome driven over the DevTools protocol against `portal serve` and a +`portal generate` build, with a real GA4 property): seven of the eight events reached GA4 once each with their +keys; `docs_plugin_install` needs a project with a `plugin` block. The playground's header and its dialog both +carry the replay markers in the browser. One bug found and fixed in `__root.tsx`, uncommitted: in `portal serve` +the root effect runs while the router is still pending, before the page's head applies, so the first +`docs_page_view` carried the site name as its title and the address dedupe then dropped the `onRendered` report +that had the right one; a prerendered page mounts idle with the right title and raises no `onRendered` for its +first page. The effect now reports directly only when the router is idle at mount. GA4's own history-change +page view was seen on every page change with the stream setting still on, as the warning says. + ## 5. Questions each step will raise Answered already, so the agent does not ask them: diff --git a/portal-template/src/routes/__root.tsx b/portal-template/src/routes/__root.tsx index db69ef9b..7aa0eefe 100644 --- a/portal-template/src/routes/__root.tsx +++ b/portal-template/src/routes/__root.tsx @@ -57,7 +57,9 @@ export const Route = createRootRoute({ function RootComponent() { const router = useRouter(); useEffect(() => { - analytics.reportPageView(); + // A prerendered page mounts with the router idle and raises no `onRendered` for its first page, so it + // is reported here; `portal serve` mounts pending, before the page's head applies, and `onRendered` follows. + if (router.state.status === 'idle') analytics.reportPageView(); const unsubscribe = router.subscribe('onRendered', () => analytics.reportPageView()); document.addEventListener('click', reportCodeCopy); return () => { From be8cc928ed13fce6b528d9dd8c1e3d8cf021ba54 Mon Sep 17 00:00:00 2001 From: Muhammad Sohail Date: Fri, 13 Nov 2026 11:29:09 +0500 Subject: [PATCH 26/73] refactor(portal): apply --no-analytics in the actions, not the service The flag travelled through four PortalProjectService methods that never read it, on its way to AnalyticsConfig.identity(): a presentation decision carried by infrastructure, against the "No middlemen" rule. PortalConfig.withoutVendors() now makes the same portal with neither vendor tag, and the prepare and serve actions hand the service that config under the flag, the serve action on each rewrite too. The service and identity() are back to their old signatures, and what follows the build, the GA4 warning included, still sees the source as read. Found by the code review of 2026-11-13; the plan records the shape. Co-Authored-By: Claude Fable 5.1 --- .ai/plans/portal-analytics.md | 26 ++--- src/actions/portal/prepare-project.ts | 6 +- src/actions/portal/serve.ts | 5 +- src/infrastructure/portal-project-service.ts | 29 ++---- src/types/portal/config/analytics-config.ts | 11 ++- src/types/portal/portal-config.ts | 17 +++- test/actions/portal/generate.test.ts | 11 +-- test/actions/portal/prepare-project.test.ts | 29 ++++-- test/actions/portal/serve.test.ts | 14 +-- test/actions/quickstart.test.ts | 4 +- test/e2e/portal-build.test.ts | 2 +- test/e2e/portal-serve.test.ts | 2 +- .../portal-project-service.test.ts | 99 +++++++++---------- test/types/portal-source-context.test.ts | 8 +- test/types/portal/portal-config.test.ts | 60 ++++++----- 15 files changed, 167 insertions(+), 156 deletions(-) diff --git a/.ai/plans/portal-analytics.md b/.ai/plans/portal-analytics.md index 707763cf..9b7211fc 100644 --- a/.ai/plans/portal-analytics.md +++ b/.ai/plans/portal-analytics.md @@ -304,18 +304,20 @@ Delivers, from the commands inward, after the "check first" answer in section 5: boolean flag, description "leave out Google Tag Manager, Google Analytics and every analytics or marketing script, for staging."; each passes `enableAnalytics: !flags['no-analytics']` to its action; quickstart's preview passes `true`. -- `PreparePortalProjectAction`, `PortalProjectService.prepare()`, `applyConfig()` and - `appearanceFiles()` take `enableAnalytics: boolean` as a parameter, never a field; - `PortalConfig.identity(enableAnalytics)` hands it to `AnalyticsConfig.identity()`, which - leaves both vendors out when it is false; `src/actions/portal/serve.ts` hands the same value - to the rewrite when the block changes. The sketch's `PortalDelivery` class is not built: with - no preview mode it would wrap this one boolean. +- `PreparePortalProjectAction` takes `enableAnalytics: boolean` as a parameter, never a field, + and hands `PortalProjectService.prepare()` the source as read, or with + `config.withoutVendors()` when the flag is false; `src/actions/portal/serve.ts` does the same + for `applyConfig()` on each rewrite. The service, `PortalConfig.identity()` and + `AnalyticsConfig.identity()` never see the flag (the review of 2026-11-13 moved it up from + them). The sketch's `PortalDelivery` class is not built: with no preview mode it would wrap + this one boolean. Tests: both commands accept the flag (`test/commands/flag-parser.ts` is the helper the command -tests use); `identity(false)` leaves both vendors out and keeps `keepQueryParams`; -`test/actions/portal/prepare-project.test.ts` and the stubs follow the new signature; the -generate, prepare and serve actions hand `--no-analytics` on, the serve action to the rewrite -too; the identity file written under `--no-analytics` has both vendors `null`. +tests use); `withoutVendors()` leaves both vendors out and keeps `keepQueryParams` and the rest +of the identity; the generate, prepare and serve actions hand the service a config without +vendors under `--no-analytics`, the serve action on each rewrite too, while what follows them +still sees the source as read; the identity file written from such a config has both vendors +`null`. Commit: `feat(portal): add --no-analytics and leave the vendors out of the identity file`. @@ -375,8 +377,8 @@ Delivers: `src/types/portal/config/portal-script.ts` (new), one entry parsed as every error collected. `httpsAddress(value, path, example)` moved into `fields.ts` from `portal-config.ts`'s `secureAddress()`, with `pluginUrl` on it. `PortalConfig`: `scripts` among the known keys, parsed in `fromBlock()`, `staticFiles()` returning the listed static files -beside the brand files, `identity(enableAnalytics)` keeping the `necessary` and `functional` entries always and the rest only when the flag -allows, `toJSON()` writing `scripts` only when set with `category` and `attributes` only when +beside the brand files, `withoutVendors()` keeping the `necessary` and `functional` entries and dropping the rest, so +`identity()` writes what the build loads, `toJSON()` writing `scripts` only when set with `category` and `attributes` only when given. No class for it: the category rule is a function beside the parser. `scripts: PortalScript[]` on `PortalIdentity` and on the template's `Portal` (`ScriptCategory`, `PortalScript` in `portal-types.ts`). diff --git a/src/actions/portal/prepare-project.ts b/src/actions/portal/prepare-project.ts index ad753674..a3315d77 100644 --- a/src/actions/portal/prepare-project.ts +++ b/src/actions/portal/prepare-project.ts @@ -111,11 +111,11 @@ export class PreparePortalProjectAction { } return await withDirPath(async (tempDirectory) => { + // Under --no-analytics the build names neither vendor tag; what follows still sees the source as read. const portalProject = await this.projectService.prepare( tempDirectory, - source.value, - artifacts.value, - enableAnalytics + enableAnalytics ? source.value : { ...source.value, config: source.value.config.withoutVendors() }, + artifacts.value ); if (portalProject.isErr()) { this.prompts.runtimeUnsupported(portalProject.error); diff --git a/src/actions/portal/serve.ts b/src/actions/portal/serve.ts index 97a256c3..cfe861b2 100644 --- a/src/actions/portal/serve.ts +++ b/src/actions/portal/serve.ts @@ -159,7 +159,10 @@ export class PortalServeAction { this.prompts.staticDirectoryNotServed(sourceDirectory); } - const applied = await this.projectService.applyConfig(portalProjectDirectory, settings, enableAnalytics); + const applied = await this.projectService.applyConfig( + portalProjectDirectory, + enableAnalytics ? settings : { ...settings, config: config.withoutVendors() } + ); if (applied.isErr()) { this.prompts.notApplied('config', applied.error, sourceDirectory); return; diff --git a/src/infrastructure/portal-project-service.ts b/src/infrastructure/portal-project-service.ts index b08c7bc5..6d8fdf1a 100644 --- a/src/infrastructure/portal-project-service.ts +++ b/src/infrastructure/portal-project-service.ts @@ -107,8 +107,7 @@ export class PortalProjectService { public async prepare( projectDirectory: DirectoryPath, source: PortalSource, - artifacts: PortalArtifacts, - enableAnalytics: boolean + artifacts: PortalArtifacts ): Promise> { const template = this.templateDirectory(); if (template === undefined) { @@ -132,7 +131,7 @@ export class PortalProjectService { await this.writeCodeSamples(projectDirectory, source, artifacts.codeSampleCatalogs), await this.writeDownloads(projectDirectory, artifacts) ); - await this.writeAppearance(projectDirectory, source.config, enableAnalytics); + await this.writeAppearance(projectDirectory, source.config); const pages = await this.pagesService.write(projectDirectory.join(GENERATED_DIRECTORY_NAME), source.generatedPages); if (pages.isErr()) { @@ -308,12 +307,11 @@ export class PortalProjectService { */ public async applyConfig( projectDirectory: DirectoryPath, - settings: PortalSettings, - enableAnalytics: boolean + settings: PortalSettings ): Promise> { let written = false; try { - for (const [file, contents] of this.appearanceFiles(projectDirectory, settings.config, enableAnalytics)) { + for (const [file, contents] of this.appearanceFiles(projectDirectory, settings.config)) { if (await this.fileService.replaceContentsIfChanged(file, contents)) { written = true; } @@ -373,12 +371,8 @@ export class PortalProjectService { .filter((file) => !isSkippedWithin(file, directory)); } - private async writeAppearance( - projectDirectory: DirectoryPath, - config: PortalConfig, - enableAnalytics: boolean - ): Promise { - for (const [file, contents] of this.appearanceFiles(projectDirectory, config, enableAnalytics)) { + private async writeAppearance(projectDirectory: DirectoryPath, config: PortalConfig): Promise { + for (const [file, contents] of this.appearanceFiles(projectDirectory, config)) { await this.fileService.writeContents(file, contents); } } @@ -387,16 +381,9 @@ export class PortalProjectService { * The browser imports `portal.identity.json` whole, since a retained JSON module is not * tree-shaken per property, which is why it holds nothing that addresses this machine. */ - private appearanceFiles( - projectDirectory: DirectoryPath, - config: PortalConfig, - enableAnalytics: boolean - ): [FilePath, string][] { + private appearanceFiles(projectDirectory: DirectoryPath, config: PortalConfig): [FilePath, string][] { return [ - [ - new FilePath(projectDirectory, new FileName(IDENTITY_FILE_NAME)), - JSON.stringify(config.identity(enableAnalytics), null, 2) - ], + [new FilePath(projectDirectory, new FileName(IDENTITY_FILE_NAME)), JSON.stringify(config.identity(), null, 2)], [ new FilePath(projectDirectory.join('src').join('styles'), new FileName(STYLESHEET_FILE_NAME)), PortalStylesheet.of(config).toString() diff --git a/src/types/portal/config/analytics-config.ts b/src/types/portal/config/analytics-config.ts index 8ad5d479..0161a52b 100644 --- a/src/types/portal/config/analytics-config.ts +++ b/src/types/portal/config/analytics-config.ts @@ -54,14 +54,19 @@ export class AnalyticsConfig { return this.googleAnalytics !== null; } - public identity(enableAnalytics: boolean): PortalAnalytics { + public identity(): PortalAnalytics { return { - googleTagManager: enableAnalytics ? this.googleTagManager : null, - googleAnalytics: enableAnalytics ? this.googleAnalytics : null, + googleTagManager: this.googleTagManager, + googleAnalytics: this.googleAnalytics, keepQueryParams: this.keepQueryParams }; } + /** For a staging build: neither vendor tag loads, while a reported address still keeps the same names. */ + public withoutVendors(): AnalyticsConfig { + return new AnalyticsConfig(null, null, this.keepQueryParams); + } + /** Null with nothing set, so the block quickstart writes has no `analytics`. */ public toJSON(): AnalyticsBlock | null { const gtm = this.googleTagManager; diff --git a/src/types/portal/portal-config.ts b/src/types/portal/portal-config.ts index 18c81553..a0b6a39f 100644 --- a/src/types/portal/portal-config.ts +++ b/src/types/portal/portal-config.ts @@ -128,7 +128,7 @@ export class PortalConfig { return this.analytics.usesGoogleAnalytics(); } - public identity(enableAnalytics: boolean): PortalIdentity { + public identity(): PortalIdentity { const address = this.site.siteAddress(); const logo = this.brand.logoImages(); const favicon = this.brand.faviconImage(); @@ -141,11 +141,24 @@ export class PortalConfig { colorMode: this.brand.mode(), links: this.navigation.headerLinks().map(portalLink), pageActions: this.ai.offersPageActions(), - analytics: this.analytics.identity(enableAnalytics), + analytics: this.analytics.identity(), seo: this.seo.identity() }; } + /** The same portal with neither vendor tag, for a staging build under `--no-analytics`. */ + public withoutVendors(): PortalConfig { + return new PortalConfig( + this.site, + this.brand, + this.navigation, + this.ai, + this.analytics.withoutVendors(), + this.seo, + this.pluginAddress + ); + } + /** Every namespace included, defaults and all, which is what quickstart writes; `analytics` and `seo` only when set. */ public toJSON(): PortalBlock { const analytics = this.analytics.toJSON(); diff --git a/test/actions/portal/generate.test.ts b/test/actions/portal/generate.test.ts index 794cc388..e3383842 100644 --- a/test/actions/portal/generate.test.ts +++ b/test/actions/portal/generate.test.ts @@ -318,13 +318,6 @@ describe('GenerateAction', () => { expect(shared.prompts.filesShadowedByStatic.firstCall.args[0].map(String)).to.deep.equal(['robots.txt']); }); - it('hands --no-analytics to the project it prepares', async () => { - const result = await execute(FIXTURE, false, false, false); - - expect(result.isSuccess()).to.be.true; - expect(shared.prepare.firstCall.args[3]).to.be.false; - }); - it('warns that Google Analytics counts page changes, before the build, when it is set', async () => { const project = new DirectoryPath(root).join('analytics'); fs.cpSync(FIXTURE.toString(), project.toString(), { recursive: true }); @@ -338,9 +331,10 @@ describe('GenerateAction', () => { expect(result.isSuccess()).to.be.true; expect(prompts.googleAnalyticsCountsPageChanges.calledOnce).to.be.true; expect(prompts.googleAnalyticsCountsPageChanges.calledBefore(build)).to.be.true; + expect(shared.prepare.firstCall.args[1].config.usesGoogleAnalytics()).to.be.true; }); - it('does not warn about Google Analytics under --no-analytics, which loads none', async () => { + it('does not warn about Google Analytics under --no-analytics, which prepares the project without it', async () => { const project = new DirectoryPath(root).join('staging'); fs.cpSync(FIXTURE.toString(), project.toString(), { recursive: true }); const configFile = path.join(project.toString(), 'src', 'apimatic.json'); @@ -352,6 +346,7 @@ describe('GenerateAction', () => { expect(result.isSuccess()).to.be.true; expect(prompts.googleAnalyticsCountsPageChanges.called).to.be.false; + expect(shared.prepare.firstCall.args[1].config.usesGoogleAnalytics()).to.be.false; }); it('does not warn about Google Analytics when it is not set', async () => { diff --git a/test/actions/portal/prepare-project.test.ts b/test/actions/portal/prepare-project.test.ts index bd47a800..37deb1d6 100644 --- a/test/actions/portal/prepare-project.test.ts +++ b/test/actions/portal/prepare-project.test.ts @@ -1,4 +1,6 @@ +import fs from 'fs'; import os from 'os'; +import path from 'path'; import AdmZip from 'adm-zip'; import sinon from 'sinon'; import { expect } from 'chai'; @@ -46,9 +48,9 @@ describe('PreparePortalProjectAction', () => { let shared: PreparePortalProjectStubs; let onPrepared: sinon.SinonStub; - const execute = (enableAnalytics = true) => + const execute = (enableAnalytics = true, project = FIXTURE) => new PreparePortalProjectAction(new DirectoryPath(os.tmpdir()), COMMAND_METADATA).execute( - ProjectContext.in(FIXTURE), + ProjectContext.in(project), enableAnalytics, { onPrepared } ); @@ -73,10 +75,25 @@ describe('PreparePortalProjectAction', () => { expect(uploaded.filter((entry) => entry.startsWith('static/'))).to.be.empty; }); - it('hands --no-analytics to the project it prepares', async () => { - await execute(false); - - expect(shared.prepare.firstCall.args[3]).to.be.false; + it('prepares the project with neither vendor tag under --no-analytics, and hands on the source as read', async () => { + const root = fs.mkdtempSync(path.join(os.tmpdir(), 'portal-prepare-')); + try { + fs.cpSync(FIXTURE.toString(), root, { recursive: true }); + const configFile = path.join(root, 'src', 'apimatic.json'); + const edited = JSON.parse(fs.readFileSync(configFile, 'utf8')); + edited.portal.analytics = { googleTagManager: { containerId: 'GTM-ABC123' } }; + fs.writeFileSync(configFile, JSON.stringify(edited)); + + await execute(false, new DirectoryPath(root)); + + expect(shared.prepare.firstCall.args[1].config.identity().analytics.googleTagManager).to.be.null; + expect(onPrepared.firstCall.args[1].config.identity().analytics.googleTagManager).to.deep.equal({ + containerId: 'GTM-ABC123', + environment: null + }); + } finally { + fs.rmSync(root, { recursive: true, force: true }); + } }); it('reports a source it could not zip, without asking for the artifacts', async () => { diff --git a/test/actions/portal/serve.test.ts b/test/actions/portal/serve.test.ts index 53515a70..6d7f0197 100644 --- a/test/actions/portal/serve.test.ts +++ b/test/actions/portal/serve.test.ts @@ -631,10 +631,10 @@ describe('PortalServeAction', () => { // `prepare` is stubbed above; this one writes the files an edit can change, as a real one // would, so the test can see what an edit changes. (PortalProjectService.prototype.prepare as sinon.SinonStub).callsFake( - async (directory: DirectoryPath, portal: PortalSource, _artifacts: unknown, enableAnalytics: boolean) => { + async (directory: DirectoryPath, portal: PortalSource) => { projectDirectory = directory; fs.mkdirSync(path.join(directory.toString(), 'src/styles'), { recursive: true }); - (await new PortalProjectService().applyConfig(directory, portal, enableAnalytics))._unsafeUnwrap(); + (await new PortalProjectService().applyConfig(directory, portal))._unsafeUnwrap(); return ok({ projectDirectory: directory, viteBinary: new FilePath(directory, new FileName('vite.js')), @@ -891,17 +891,19 @@ describe('PortalServeAction', () => { }); }); - it('keeps --no-analytics for the rewrite when the block changes', async () => { + it('leaves the vendor tags out of the project and of each rewrite under --no-analytics', async () => { const applyConfig = sinon.spy(PortalProjectService.prototype, 'applyConfig'); + const config = originalConfig(); + config.portal.analytics = { googleTagManager: { containerId: 'GTM-ABC123' } }; + writeConfig(config); await whileServing(async () => { - const config = originalConfig(); config.portal.site.name = 'Renamed API'; await save(config); }, false); - expect(shared.prepare.firstCall.args[3]).to.be.false; - expect(applyConfig.lastCall.args[2]).to.be.false; + expect(shared.prepare.firstCall.args[1].config.identity().analytics.googleTagManager).to.be.null; + expect(applyConfig.lastCall.args[1].config.identity().analytics.googleTagManager).to.be.null; }); it('reports a change it could not write to the preview', async () => { diff --git a/test/actions/quickstart.test.ts b/test/actions/quickstart.test.ts index 81ea971e..0b571f1d 100644 --- a/test/actions/quickstart.test.ts +++ b/test/actions/quickstart.test.ts @@ -22,6 +22,7 @@ import { FileDownloadService } from '../../src/infrastructure/services/file-down import { ServiceError } from '../../src/infrastructure/service-error'; import { UrlPath } from '../../src/types/file/urlPath'; import { ProjectContext } from '../../src/types/project-context'; +import { PortalConfig } from '../../src/types/portal/portal-config'; import { completeArtifacts } from './portal/prepare-project-stubs'; const COMMAND_METADATA: CommandMetadata = { commandName: 'portal quickstart', shell: 'test' }; @@ -107,6 +108,7 @@ describe('QuickstartAction', () => { .stub(PortalArtifactsService.prototype, 'generate') .resolves(ok(completeArtifacts([Language.TYPESCRIPT, Language.PYTHON]))); const prepare = sinon.stub(PortalProjectService.prototype, 'prepare').resolves(err('stopped here')); + const withoutVendors = sinon.spy(PortalConfig.prototype, 'withoutVendors'); await execute(); @@ -127,7 +129,7 @@ describe('QuickstartAction', () => { // prepares a project. expect(artifacts.called, 'the wizard asked for the artifacts').to.be.true; expect(prepare.called, 'the wizard reached the preview').to.be.true; - expect(prepare.firstCall.args[3], 'the preview counts like a hosted portal').to.be.true; + expect(withoutVendors.called, 'the preview counts like a hosted portal').to.be.false; }); it('asks for nothing more and stops when no language is chosen', async () => { diff --git a/test/e2e/portal-build.test.ts b/test/e2e/portal-build.test.ts index 7172605b..03edae95 100644 --- a/test/e2e/portal-build.test.ts +++ b/test/e2e/portal-build.test.ts @@ -87,7 +87,7 @@ async function buildFixture(name: string, delivered: Delivered = {}, settings?: fs.mkdirSync(project.toString(), { recursive: true }); const artifacts = deliveredInto(path.join(root, 'delivered'), delivered); expect(source.generatedPages.missingFrom(artifacts), 'the artifacts back every page').to.be.null; - const prepared = (await new PortalProjectService().prepare(project, source, artifacts, true))._unsafeUnwrap(); + const prepared = (await new PortalProjectService().prepare(project, source, artifacts))._unsafeUnwrap(); const build = await new PortalBuildService().build(prepared); if (build.isErr()) { diff --git a/test/e2e/portal-serve.test.ts b/test/e2e/portal-serve.test.ts index 7119a90e..b11324e7 100644 --- a/test/e2e/portal-serve.test.ts +++ b/test/e2e/portal-serve.test.ts @@ -44,7 +44,7 @@ const enabled = process.env.APIMATIC_E2E === '1'; const project = new DirectoryPath(root).join('build'); fs.mkdirSync(project.toString(), { recursive: true }); - const prepared = (await new PortalProjectService().prepare(project, resolved, artifacts, true))._unsafeUnwrap(); + const prepared = (await new PortalProjectService().prepare(project, resolved, artifacts))._unsafeUnwrap(); const started = await new PortalDevServerService().start(prepared, await getPort()); if (started.isErr()) { diff --git a/test/infrastructure/portal-project-service.test.ts b/test/infrastructure/portal-project-service.test.ts index 379e6c83..9c3a74d4 100644 --- a/test/infrastructure/portal-project-service.test.ts +++ b/test/infrastructure/portal-project-service.test.ts @@ -115,7 +115,7 @@ describe('PortalProjectService', () => { describe('prepare', () => { it('installs every dependency the template imports, resolved to a real package', async () => { - (await service.prepare(project, sourceFor(), NO_ARTIFACTS, true))._unsafeUnwrap(); + (await service.prepare(project, sourceFor(), NO_ARTIFACTS))._unsafeUnwrap(); const modules = path.join(project.toString(), 'node_modules'); const installed = fs @@ -136,7 +136,7 @@ describe('PortalProjectService', () => { // Vite refuses an 8.3 short name outright, and compares the real path against its allow list. it('links each dependency, and names the Vite binary, by its real path', async () => { - const prepared = (await service.prepare(project, sourceFor(), NO_ARTIFACTS, true))._unsafeUnwrap(); + const prepared = (await service.prepare(project, sourceFor(), NO_ARTIFACTS))._unsafeUnwrap(); for (const name of LINKED_DEPENDENCIES) { const link = path.join(project.toString(), 'node_modules', name); @@ -148,7 +148,7 @@ describe('PortalProjectService', () => { // Linked, their `url()`s would resolve from the CLI's install, which may be on another drive. it('copies the font packages into the project instead of linking them', async () => { - (await service.prepare(project, sourceFor(), NO_ARTIFACTS, true))._unsafeUnwrap(); + (await service.prepare(project, sourceFor(), NO_ARTIFACTS))._unsafeUnwrap(); for (const name of COPIED_DEPENDENCIES) { const directory = path.join(project.toString(), 'node_modules', name); @@ -158,14 +158,14 @@ describe('PortalProjectService', () => { }); it('copies the template rather than moving it', async () => { - (await service.prepare(project, sourceFor(), NO_ARTIFACTS, true))._unsafeUnwrap(); + (await service.prepare(project, sourceFor(), NO_ARTIFACTS))._unsafeUnwrap(); expect(fs.existsSync(path.join(process.cwd(), 'portal-template', 'vite.config.ts'))).to.be.true; expect(fs.existsSync(path.join(project.toString(), 'vite.config.ts'))).to.be.true; }); it('writes the specs and the directories into the build-only config', async () => { - (await service.prepare(project, sourceFor(), NO_ARTIFACTS, true))._unsafeUnwrap(); + (await service.prepare(project, sourceFor(), NO_ARTIFACTS))._unsafeUnwrap(); const config = readConfig(); expect(Object.keys(config).sort()).to.deep.equal([ @@ -187,25 +187,20 @@ describe('PortalProjectService', () => { it('builds the portal under the path of its address', async () => { const config = configFor({ site: { name: 'My API', url: 'https://example.com/Docs/v2.1/' } }); - (await service.prepare(project, sourceFor({ config }), NO_ARTIFACTS, true))._unsafeUnwrap(); + (await service.prepare(project, sourceFor({ config }), NO_ARTIFACTS))._unsafeUnwrap(); expect(readConfig().base).to.equal('/Docs/v2.1/'); }); it('builds the portal at the root when it has no address', async () => { - (await service.prepare(project, sourceFor(), NO_ARTIFACTS, true))._unsafeUnwrap(); + (await service.prepare(project, sourceFor(), NO_ARTIFACTS))._unsafeUnwrap(); expect(readConfig().base).to.equal('/'); }); it('writes the generated pages into the project, and names their directory in the build-only config', async () => { ( - await service.prepare( - project, - sourceFor({ generatedPages: pagesFor({ typescript: {} }, true) }), - NO_ARTIFACTS, - true - ) + await service.prepare(project, sourceFor({ generatedPages: pagesFor({ typescript: {} }, true) }), NO_ARTIFACTS) )._unsafeUnwrap(); expect(generatedFiles()).to.deep.equal([ @@ -226,9 +221,9 @@ describe('PortalProjectService', () => { brand: { logo: 'static/images/logo.png' } }); - (await service.prepare(project, sourceFor({ config }), NO_ARTIFACTS, true))._unsafeUnwrap(); + (await service.prepare(project, sourceFor({ config }), NO_ARTIFACTS))._unsafeUnwrap(); - expect(readIdentity()).to.deep.equal(config.identity(true)); + expect(readIdentity()).to.deep.equal(config.identity()); expect(readIdentity().logo).to.deep.equal({ light: '/images/logo.png', dark: '/images/logo.png' }); expect(readIdentity().siteUrl).to.equal('https://docs.example.com'); }); @@ -239,7 +234,7 @@ describe('PortalProjectService', () => { const contentDirectory = new DirectoryPath(root).join('content'); fs.mkdirSync(contentDirectory.toString(), { recursive: true }); - (await service.prepare(project, sourceFor({ contentDirectory }), NO_ARTIFACTS, true))._unsafeUnwrap(); + (await service.prepare(project, sourceFor({ contentDirectory }), NO_ARTIFACTS))._unsafeUnwrap(); for (const file of ['portal.identity.json', 'src/lib/source.ts', 'src/styles/app.css']) { const contents = fs.readFileSync(path.join(project.toString(), file), 'utf8'); @@ -255,7 +250,7 @@ describe('PortalProjectService', () => { brand: { colors: { primary: '#1d4ed8' } } }); - (await service.prepare(project, sourceFor({ config }), NO_ARTIFACTS, true))._unsafeUnwrap(); + (await service.prepare(project, sourceFor({ config }), NO_ARTIFACTS))._unsafeUnwrap(); const styles = path.join(project.toString(), 'src/styles'); expect(fs.readFileSync(path.join(styles, 'theme.css'), 'utf8')).to.equal(PortalStylesheet.of(config).toString()); @@ -263,7 +258,7 @@ describe('PortalProjectService', () => { }); it('leaves no identity placeholder in the module the browser receives', async () => { - (await service.prepare(project, sourceFor(), NO_ARTIFACTS, true))._unsafeUnwrap(); + (await service.prepare(project, sourceFor(), NO_ARTIFACTS))._unsafeUnwrap(); const module = fs.readFileSync(path.join(project.toString(), 'src/lib/portal.ts'), 'utf8'); expect(module).to.not.contain('__APIMATIC_'); @@ -277,7 +272,7 @@ describe('PortalProjectService', () => { fs.symlinkSync(real, path.join(root, 'linked'), 'junction'); const staticDirectory = new DirectoryPath(root).join('linked', 'static'); - (await service.prepare(project, sourceFor({ staticDirectory }), NO_ARTIFACTS, true))._unsafeUnwrap(); + (await service.prepare(project, sourceFor({ staticDirectory }), NO_ARTIFACTS))._unsafeUnwrap(); expect(readConfig().staticDir).to.equal( path.join(fs.realpathSync.native(real), 'static').split(path.sep).join('/') @@ -285,13 +280,13 @@ describe('PortalProjectService', () => { }); it('reports no static directory when the project has none', async () => { - (await service.prepare(project, sourceFor(), NO_ARTIFACTS, true))._unsafeUnwrap(); + (await service.prepare(project, sourceFor(), NO_ARTIFACTS))._unsafeUnwrap(); expect(readConfig().staticDir).to.be.null; }); it('creates an empty content directory when the project has none, so the build has one to read', async () => { - (await service.prepare(project, sourceFor(), NO_ARTIFACTS, true))._unsafeUnwrap(); + (await service.prepare(project, sourceFor(), NO_ARTIFACTS))._unsafeUnwrap(); const config = readConfig(); expect(fs.existsSync(config.contentDir)).to.be.true; @@ -329,7 +324,7 @@ describe('PortalProjectService', () => { const writtenSamples = () => JSON.parse(fs.readFileSync(readConfig().codeSamples, 'utf8')); it('writes the samples beside the configuration, keyed by path and method, and names them in it', async () => { - (await service.prepare(project, sourceFor(), withCatalogs, true))._unsafeUnwrap(); + (await service.prepare(project, sourceFor(), withCatalogs))._unsafeUnwrap(); const config = readConfig(); expect(config.codeSamples).to.equal(path.join(project.toString(), 'code-samples.json').split(path.sep).join('/')); @@ -338,7 +333,7 @@ describe('PortalProjectService', () => { // The samples hold one per method and path, which would be another API's call on all but one of the pages. it('leaves out the samples of an operation more than one spec declares', async () => { - (await service.prepare(project, sharingSource(), withCatalogs, true))._unsafeUnwrap(); + (await service.prepare(project, sharingSource(), withCatalogs))._unsafeUnwrap(); expect(writtenSamples()).to.deep.equal({ paths: {}, specs: {} }); }); @@ -359,7 +354,7 @@ describe('PortalProjectService', () => { undefined ); - (await service.prepare(project, sharingSource(), filed, true))._unsafeUnwrap(); + (await service.prepare(project, sharingSource(), filed))._unsafeUnwrap(); expect(writtenSamples()).to.deep.equal({ paths: {}, @@ -373,12 +368,12 @@ describe('PortalProjectService', () => { it('points each spec at its own file, samples or not', async () => { const source = sourceFor(); - (await service.prepare(project, source, withCatalogs, true))._unsafeUnwrap(); + (await service.prepare(project, source, withCatalogs))._unsafeUnwrap(); expect(readConfig().specs.calculator).to.equal(source.specs[0].file.toString().split(path.sep).join('/')); }); it('names no samples when there are none', async () => { - (await service.prepare(project, sourceFor(), NO_ARTIFACTS, true))._unsafeUnwrap(); + (await service.prepare(project, sourceFor(), NO_ARTIFACTS))._unsafeUnwrap(); expect(readConfig().codeSamples).to.be.null; expect(fs.existsSync(path.join(project.toString(), 'code-samples.json'))).to.be.false; @@ -405,7 +400,7 @@ describe('PortalProjectService', () => { downloaded('c.zip', 'PK plugin') ); - (await service.prepare(project, sourceFor(), artifacts, true))._unsafeUnwrap(); + (await service.prepare(project, sourceFor(), artifacts))._unsafeUnwrap(); expect(fs.readFileSync(downloadsFile('sdk', 'csharp.zip'), 'utf8')).to.equal('PK csharp'); expect(fs.readFileSync(downloadsFile('sdk', 'python.zip'), 'utf8')).to.equal('PK python'); @@ -421,13 +416,13 @@ describe('PortalProjectService', () => { downloaded('c.zip', 'PK plugin') ); - (await service.prepare(project, sourceFor(), artifacts, true))._unsafeUnwrap(); + (await service.prepare(project, sourceFor(), artifacts))._unsafeUnwrap(); expect(fs.readdirSync(downloadsFile())).to.deep.equal(['plugin.zip']); }); it('names no downloads when the run carried none', async () => { - (await service.prepare(project, sourceFor(), NO_ARTIFACTS, true))._unsafeUnwrap(); + (await service.prepare(project, sourceFor(), NO_ARTIFACTS))._unsafeUnwrap(); expect(readConfig().downloadsDir).to.be.null; expect(fs.existsSync(downloadsFile())).to.be.false; @@ -447,7 +442,7 @@ describe('PortalProjectService', () => { undefined ); - (await service.prepare(project, sourceFor(), artifacts, true))._unsafeUnwrap(); + (await service.prepare(project, sourceFor(), artifacts))._unsafeUnwrap(); expect(includesFile('sdk-docs', 'typescript.md')).to.equal('## Installation\n\nnpm install calc\n'); expect(generatedFiles()).to.not.include('sdk-docs/typescript.md'); @@ -485,7 +480,7 @@ describe('PortalProjectService', () => { }); const prepareCopy = async () => - (await service.prepare(project, sourceFor({ contentDirectory: content }), NO_ARTIFACTS, true))._unsafeUnwrap(); + (await service.prepare(project, sourceFor({ contentDirectory: content }), NO_ARTIFACTS))._unsafeUnwrap(); // The dev server lists the pages once, when it starts, so the copy has to be whole by then. it('is made while the project is prepared, of every file but those the build never reads', async () => { @@ -545,12 +540,12 @@ describe('PortalProjectService', () => { const themeFile = () => path.join(project.toString(), 'src/styles/theme.css'); const identityFile = () => path.join(project.toString(), 'portal.identity.json'); - it('writes neither vendor under --no-analytics, and both once analytics are on again', async () => { + it('writes the vendors the config holds, and none from a config without them', async () => { const config = configFor({ site: { name: 'My API' }, analytics: { googleTagManager: { containerId: 'GTM-ABC123' }, googleAnalytics: { measurementId: 'G-ABC123' } } }); - (await service.prepare(project, sourceFor({ config }), NO_ARTIFACTS, false))._unsafeUnwrap(); + (await service.prepare(project, sourceFor({ config: config.withoutVendors() }), NO_ARTIFACTS))._unsafeUnwrap(); expect(readIdentity().analytics).to.deep.equal({ googleTagManager: null, @@ -558,7 +553,7 @@ describe('PortalProjectService', () => { keepQueryParams: [] }); - expect((await service.applyConfig(project, settingsFor(config), true))._unsafeUnwrap()).to.be.true; + expect((await service.applyConfig(project, settingsFor(config)))._unsafeUnwrap()).to.be.true; expect(readIdentity().analytics).to.deep.equal({ googleTagManager: { containerId: 'GTM-ABC123', environment: null }, @@ -569,7 +564,7 @@ describe('PortalProjectService', () => { it('writes nothing, and says so, when the block makes the same site', async () => { const config = configFor({ site: { name: 'My API' }, brand: { colors: { primary: '#1d4ed8' } } }); - (await service.prepare(project, sourceFor({ config }), NO_ARTIFACTS, true))._unsafeUnwrap(); + (await service.prepare(project, sourceFor({ config }), NO_ARTIFACTS))._unsafeUnwrap(); const before = [fs.statSync(themeFile()).mtimeMs, fs.statSync(identityFile()).mtimeMs]; // Written differently, read the same: the comparison is of what the preview shows. @@ -578,31 +573,31 @@ describe('PortalProjectService', () => { brand: { colors: { primary: '#1d4ed8' } }, ai: { pageActions: true } }); - const applied = await service.applyConfig(project, settingsFor(same), true); + const applied = await service.applyConfig(project, settingsFor(same)); expect(applied._unsafeUnwrap()).to.be.false; expect([fs.statSync(themeFile()).mtimeMs, fs.statSync(identityFile()).mtimeMs]).to.deep.equal(before); }); it('rewrites both files for a brand change, to what a fresh build would write', async () => { - (await service.prepare(project, sourceFor(), NO_ARTIFACTS, true))._unsafeUnwrap(); + (await service.prepare(project, sourceFor(), NO_ARTIFACTS))._unsafeUnwrap(); const config = configFor({ site: { name: 'My API' }, brand: { colors: { primary: '#1d4ed8' }, colorMode: 'dark' } }); - expect((await service.applyConfig(project, settingsFor(config), true))._unsafeUnwrap()).to.be.true; + expect((await service.applyConfig(project, settingsFor(config)))._unsafeUnwrap()).to.be.true; expect(fs.readFileSync(themeFile(), 'utf8')).to.equal(PortalStylesheet.of(config).toString()); - expect(readIdentity()).to.deep.equal(config.identity(true)); + expect(readIdentity()).to.deep.equal(config.identity()); }); it('leaves the stylesheet alone when only what the browser is told changes', async () => { - (await service.prepare(project, sourceFor(), NO_ARTIFACTS, true))._unsafeUnwrap(); + (await service.prepare(project, sourceFor(), NO_ARTIFACTS))._unsafeUnwrap(); const before = fs.statSync(themeFile()).mtimeMs; const renamed = configFor({ site: { name: 'Renamed API' } }); - expect((await service.applyConfig(project, settingsFor(renamed), true))._unsafeUnwrap()).to.be.true; + expect((await service.applyConfig(project, settingsFor(renamed)))._unsafeUnwrap()).to.be.true; expect(readIdentity().name).to.equal('Renamed API'); expect(fs.statSync(themeFile()).mtimeMs).to.equal(before); @@ -610,12 +605,12 @@ describe('PortalProjectService', () => { // The dev server is watching both files, and could read one truncated before it is written. it('replaces each file whole rather than writing it in place', async () => { - (await service.prepare(project, sourceFor(), NO_ARTIFACTS, true))._unsafeUnwrap(); + (await service.prepare(project, sourceFor(), NO_ARTIFACTS))._unsafeUnwrap(); const replace = sinon.spy(FileService.prototype, 'replaceContents'); const write = sinon.spy(FileService.prototype, 'writeContents'); const config = configFor({ site: { name: 'Renamed API' }, brand: { colors: { primary: '#1d4ed8' } } }); - expect((await service.applyConfig(project, settingsFor(config), true))._unsafeUnwrap()).to.be.true; + expect((await service.applyConfig(project, settingsFor(config)))._unsafeUnwrap()).to.be.true; expect(replace.args.map(([file]) => file.toString())).to.deep.equal([identityFile(), themeFile()]); expect(write.called).to.be.false; @@ -626,37 +621,31 @@ describe('PortalProjectService', () => { const blocked = new DirectoryPath(root).join('blocked'); fs.writeFileSync(blocked.toString(), ''); - const applied = await service.applyConfig(blocked, settingsFor(configFor({ site: { name: 'My API' } })), true); + const applied = await service.applyConfig(blocked, settingsFor(configFor({ site: { name: 'My API' } }))); expect(applied.isErr()).to.be.true; }); it('writes the page for a language added, and says so', async () => { - (await service.prepare(project, sourceFor(), NO_ARTIFACTS, true))._unsafeUnwrap(); + (await service.prepare(project, sourceFor(), NO_ARTIFACTS))._unsafeUnwrap(); const config = sourceFor().config; - const applied = await service.applyConfig( - project, - settingsFor(config, pagesFor({ typescript: {}, python: {} })), - true - ); + const applied = await service.applyConfig(project, settingsFor(config, pagesFor({ typescript: {}, python: {} }))); expect(applied._unsafeUnwrap()).to.be.true; expect(generatedFiles()).to.include('sdks/python.mdx'); }); it('writes the context plugin folder for a plugin block added, and removes it with the block', async () => { - (await service.prepare(project, sourceFor(), NO_ARTIFACTS, true))._unsafeUnwrap(); + (await service.prepare(project, sourceFor(), NO_ARTIFACTS))._unsafeUnwrap(); const config = sourceFor().config; expect( - ( - await service.applyConfig(project, settingsFor(config, pagesFor({ typescript: {} }, true)), true) - )._unsafeUnwrap() + (await service.applyConfig(project, settingsFor(config, pagesFor({ typescript: {} }, true))))._unsafeUnwrap() ).to.be.true; expect(generatedFiles()).to.include.members(['context-plugin/index.mdx', 'context-plugin/nav.json']); - expect((await service.applyConfig(project, settingsFor(config), true))._unsafeUnwrap()).to.be.true; + expect((await service.applyConfig(project, settingsFor(config)))._unsafeUnwrap()).to.be.true; expect(fs.existsSync(path.join(project.toString(), GENERATED_DIRECTORY_NAME, 'context-plugin'))).to.be.false; }); }); diff --git a/test/types/portal-source-context.test.ts b/test/types/portal-source-context.test.ts index 20dbe950..27d6e499 100644 --- a/test/types/portal-source-context.test.ts +++ b/test/types/portal-source-context.test.ts @@ -144,7 +144,7 @@ describe('PortalSourceContext', () => { const { config } = (await resolve())._unsafeUnwrap(); expect(config.siteTitle()).to.equal('Calc'); - expect(config.identity(true).description).to.equal('Adds.'); + expect(config.identity().description).to.equal('Adds.'); }); it('lets the block describe the portal instead, or not at all', async () => { @@ -154,9 +154,9 @@ describe('PortalSourceContext', () => { ); writeConfig({ site: { description: 'Our docs.' } }); - expect((await resolve())._unsafeUnwrap().config.identity(true).description).to.equal('Our docs.'); + expect((await resolve())._unsafeUnwrap().config.identity().description).to.equal('Our docs.'); writeConfig({ site: { description: '' } }); - expect((await resolve())._unsafeUnwrap().config.identity(true).description).to.be.null; + expect((await resolve())._unsafeUnwrap().config.identity().description).to.be.null; }); // No one of several specifications speaks for the whole portal. @@ -2636,7 +2636,7 @@ describe('PortalSourceContext', () => { const empty = (await new PortalSourceContext(source).resolve())._unsafeUnwrap().config; expect(scaffolded.toJSON()).to.deep.equal(empty.toJSON()); - expect(scaffolded.identity(true)).to.deep.equal(empty.identity(true)); + expect(scaffolded.identity()).to.deep.equal(empty.identity()); }); // Every block the wizard writes has to pass the schema it points editors at. diff --git a/test/types/portal/portal-config.test.ts b/test/types/portal/portal-config.test.ts index 6b379ac6..253adf1c 100644 --- a/test/types/portal/portal-config.test.ts +++ b/test/types/portal/portal-config.test.ts @@ -28,7 +28,7 @@ describe('PortalConfig', () => { it('builds a portal from an empty block, with every default', () => { const portal = config({}); - const identity = portal.identity(true); + const identity = portal.identity(); expect(portal.siteTitle()).to.equal('Spec Title'); expect(identity.description).to.equal('What the spec says.'); @@ -120,17 +120,17 @@ describe('PortalConfig', () => { }); it('has no description with several specifications unless the block gives one', () => { - expect(config({ site: { name: 'Calc' } }, null).identity(true).description).to.be.null; + expect(config({ site: { name: 'Calc' } }, null).identity().description).to.be.null; }); it('trims the description', () => { - expect(config({ site: { description: ' Docs ' } }).identity(true).description).to.equal('Docs'); + expect(config({ site: { description: ' Docs ' } }).identity().description).to.equal('Docs'); }); // Blank is how the block turns the specification's description off. it('treats a blank description as none, not as absent', () => { for (const description of ['', ' ', '\n\t']) { - expect(config({ site: { description } }).identity(true).description, JSON.stringify(description)).to.be.null; + expect(config({ site: { description } }).identity().description, JSON.stringify(description)).to.be.null; } }); @@ -139,13 +139,13 @@ describe('PortalConfig', () => { }); it('keeps the path of the address, dropping a trailing slash and keeping a port', () => { - expect(config({ site: { url: 'https://docs.example.com/' } }).identity(true).siteUrl).to.equal( + expect(config({ site: { url: 'https://docs.example.com/' } }).identity().siteUrl).to.equal( 'https://docs.example.com' ); - expect(config({ site: { url: 'https://docs.example.com:8443' } }).identity(true).siteUrl).to.equal( + expect(config({ site: { url: 'https://docs.example.com:8443' } }).identity().siteUrl).to.equal( 'https://docs.example.com:8443' ); - expect(config({ site: { url: 'HTTPS://Example.com/Docs/v2/' } }).identity(true).siteUrl).to.equal( + expect(config({ site: { url: 'HTTPS://Example.com/Docs/v2/' } }).identity().siteUrl).to.equal( 'https://example.com/Docs/v2' ); }); @@ -319,7 +319,7 @@ describe('PortalConfig', () => { { label: 'Auth', url: '/authentication' } ] } - }).identity(true); + }).identity(); expect(links).to.deep.equal([ { label: 'Status', url: 'https://status.example.com', external: true }, @@ -367,7 +367,7 @@ describe('PortalConfig', () => { it('writes a page of the portal as the browser resolves it', () => { const [link] = config({ navigation: { links: [{ label: 'x', url: '/guides/../start here?tab=1#top' }] } - }).identity(true).links; + }).identity().links; expect(link.url).to.equal('/start%20here?tab=1#top'); }); @@ -390,7 +390,7 @@ describe('PortalConfig', () => { // Each page offers to open itself in ChatGPT, Claude, Cursor or Scira. A portal // published under someone else's brand carries that endorsement, so it can be refused. it('offers the page actions unless the block turns them off', () => { - expect(config({ ai: { pageActions: false } }).identity(true).pageActions).to.be.false; + expect(config({ ai: { pageActions: false } }).identity().pageActions).to.be.false; expect(errorsOf({ ai: { pageActions: 'no' } })).to.deep.equal(["'portal.ai.pageActions' must be true or false."]); }); }); @@ -401,7 +401,7 @@ describe('PortalConfig', () => { const keep = 'portal.analytics.keepQueryParams'; it('tells the browser to load nothing when the block sets nothing', () => { - expect(config({}).identity(true).analytics).to.deep.equal({ + expect(config({}).identity().analytics).to.deep.equal({ googleTagManager: null, googleAnalytics: null, keepQueryParams: [] @@ -416,7 +416,7 @@ describe('PortalConfig', () => { keepQueryParams: ['campaign_id', ' code '] }; - expect(config({ analytics }).identity(true).analytics).to.deep.equal({ + expect(config({ analytics }).identity().analytics).to.deep.equal({ googleTagManager: { containerId: 'GTM-ABC123', environment: { auth: 'a1_b-2', preview: 'env-3' } }, googleAnalytics: { measurementId: 'G-ABC123' }, keepQueryParams: ['campaign_id', 'code'] @@ -448,8 +448,7 @@ describe('PortalConfig', () => { `'${ga}.measurementId' must be a non-empty string.` ]); expect( - config({ analytics: { googleTagManager: { containerId: 'gtm-abc123' } } }).identity(true).analytics - .googleTagManager + config({ analytics: { googleTagManager: { containerId: 'gtm-abc123' } } }).identity().analytics.googleTagManager ).to.deep.equal({ containerId: 'gtm-abc123', environment: null }); }); @@ -517,17 +516,17 @@ describe('PortalConfig', () => { ]); }); - it('tells the browser to load neither vendor under --no-analytics, and still which names to keep', () => { + it('tells the browser to load neither vendor without them, and still which names to keep', () => { const analytics = { googleTagManager: { containerId: 'GTM-ABC123' }, googleAnalytics: { measurementId: 'G-ABC123' }, keepQueryParams: ['campaign_id'] }; + const portal = config({ analytics }); - expect(config({ analytics }).identity(false).analytics).to.deep.equal({ - googleTagManager: null, - googleAnalytics: null, - keepQueryParams: ['campaign_id'] + expect(portal.withoutVendors().identity()).to.deep.equal({ + ...portal.identity(), + analytics: { googleTagManager: null, googleAnalytics: null, keepQueryParams: ['campaign_id'] } }); }); @@ -539,7 +538,7 @@ describe('PortalConfig', () => { }); it('keeps an empty list of names as none', () => { - expect(config({ analytics: { keepQueryParams: [] } }).identity(true).analytics.keepQueryParams).to.deep.equal([]); + expect(config({ analytics: { keepQueryParams: [] } }).identity().analytics.keepQueryParams).to.deep.equal([]); expect(JSON.parse(JSON.stringify(config({ analytics: { keepQueryParams: [] } })))).to.not.have.property( 'analytics' ); @@ -571,10 +570,10 @@ describe('PortalConfig', () => { describe('seo', () => { it('carries the verification value to the browser, or null without one', () => { - expect(config({ seo: { googleSiteVerification: 'abc_123-XYZ' } }).identity(true).seo).to.deep.equal({ + expect(config({ seo: { googleSiteVerification: 'abc_123-XYZ' } }).identity().seo).to.deep.equal({ googleSiteVerification: 'abc_123-XYZ' }); - expect(config({}).identity(true).seo).to.deep.equal({ googleSiteVerification: null }); + expect(config({}).identity().seo).to.deep.equal({ googleSiteVerification: null }); }); it('refuses a block that is not an object, and a blank value', () => { @@ -645,9 +644,7 @@ describe('PortalConfig', () => { }); it('is kept out of what the browser is told', () => { - expect(config({ pluginUrl: 'https://plugins.acme.test/calc.zip' }).identity(true)).to.not.have.property( - 'pluginUrl' - ); + expect(config({ pluginUrl: 'https://plugins.acme.test/calc.zip' }).identity()).to.not.have.property('pluginUrl'); }); it('is serialised only when the block gives one', () => { @@ -676,7 +673,7 @@ describe('PortalConfig', () => { ai: { pageActions: false } }); - expect(portal.identity(true)).to.deep.equal({ + expect(portal.identity()).to.deep.equal({ name: 'My API', description: 'Docs', siteUrl: 'https://docs.example.com', @@ -694,7 +691,7 @@ describe('PortalConfig', () => { }); it('reports absent settings as null rather than leaving them out', () => { - expect(PortalConfig.scaffolded({ name: 'My API', description: null }).identity(true)).to.deep.equal({ + expect(PortalConfig.scaffolded({ name: 'My API', description: null }).identity()).to.deep.equal({ name: 'My API', description: null, siteUrl: null, @@ -711,22 +708,21 @@ describe('PortalConfig', () => { // One image serves both modes, so the browser is told the same address twice rather than // having to know that a missing dark variant means the light one. it('names one logo for both modes when the block names one', () => { - expect(config({ brand: { logo: 'static/logo.svg' } }).identity(true).logo).to.deep.equal({ + expect(config({ brand: { logo: 'static/logo.svg' } }).identity().logo).to.deep.equal({ light: '/logo.svg', dark: '/logo.svg' }); }); it('takes the favicon from the light logo when the block names none', () => { - const favicon = config({ brand: { logo: { light: 'static/light.png', dark: 'static/dark.png' } } }).identity( - true - ).favicon; + const favicon = config({ brand: { logo: { light: 'static/light.png', dark: 'static/dark.png' } } }).identity() + .favicon; expect(favicon).to.deep.equal({ url: '/light.png', type: 'image/png' }); }); it('types the favicon by its extension, whatever its case, and leaves an unknown one untyped', () => { - const typeOf = (favicon: string) => config({ brand: { favicon } }).identity(true).favicon?.type; + const typeOf = (favicon: string) => config({ brand: { favicon } }).identity().favicon?.type; expect(typeOf('static/favicon.ICO')).to.equal('image/x-icon'); expect(typeOf('static/icons/app.jpeg')).to.equal('image/jpeg'); From 90dc0e9347b93c696940757369f9f7076acf9e8d Mon Sep 17 00:00:00 2001 From: Muhammad Sohail Date: Fri, 13 Nov 2026 11:29:09 +0500 Subject: [PATCH 27/73] refactor(portal): share the required-field check between the parsers analytics-config.ts had its own required() and lightDark in fields.ts inlined the same check, so the next required field would have copied one of them again. required(value, path, parse) now sits in fields.ts beside optional(), and both use it. Co-Authored-By: Claude Fable 5.1 --- src/types/portal/config/analytics-config.ts | 17 ++++++++--------- src/types/portal/config/fields.ts | 16 +++++++++++++--- 2 files changed, 21 insertions(+), 12 deletions(-) diff --git a/src/types/portal/config/analytics-config.ts b/src/types/portal/config/analytics-config.ts index 0161a52b..54d944c6 100644 --- a/src/types/portal/config/analytics-config.ts +++ b/src/types/portal/config/analytics-config.ts @@ -1,6 +1,6 @@ import { err, ok, Result } from 'neverthrow'; import { isJsonObject } from '../../../utils/json-utils.js'; -import { allOf, namespace, nonEmptyString, optional, Parsed, unknownKeys } from './fields.js'; +import { allOf, namespace, nonEmptyString, optional, Parsed, required, unknownKeys } from './fields.js'; export interface GoogleTagManagerSetting { containerId: string; @@ -86,6 +86,7 @@ export class AnalyticsConfig { } } +// Each ID is required and nothing more: its format is the vendor's to check, since a wrong value fails there, not here. function googleTagManager(value: unknown, path: string): Parsed { if (!isJsonObject(value)) { return err([`'${path}' must be a JSON object with 'containerId'.`]); @@ -93,7 +94,7 @@ function googleTagManager(value: unknown, path: string): Parsed environment(given, `${path}.environment`)) ]) ).map(([containerId, environment]) => ({ containerId, environment })); @@ -105,7 +106,10 @@ function environment(value: unknown, path: string): Parsed<{ auth: string; previ } return allOf( unknownKeys(value, ['auth', 'preview'], path), - Result.combineWithAllErrors([required(value.auth, `${path}.auth`), required(value.preview, `${path}.preview`)]) + Result.combineWithAllErrors([ + required(value.auth, `${path}.auth`, nonEmptyString), + required(value.preview, `${path}.preview`, nonEmptyString) + ]) ).map(([auth, preview]) => ({ auth, preview })); } @@ -115,15 +119,10 @@ function googleAnalytics(value: unknown, path: string): Parsed ({ measurementId })); } -/** Present and a non-empty string; its format is the vendor's to check, since a wrong value fails there, not here. */ -function required(given: unknown, path: string): Parsed { - return given === undefined ? err([`'${path}' is required.`]) : nonEmptyString(given, path); -} - /** Names a reported address keeps, beyond the campaign names it always keeps. */ function keptQueryParams(value: unknown, path: string): Parsed { if (value === undefined) { diff --git a/src/types/portal/config/fields.ts b/src/types/portal/config/fields.ts index 4755f3d4..ef581704 100644 --- a/src/types/portal/config/fields.ts +++ b/src/types/portal/config/fields.ts @@ -52,11 +52,12 @@ export function lightDark( if (!isJsonObject(value)) { return err([`'${path}' must be a string, or an object with 'light' and 'dark'.`]); } - const mode = (name: 'light' | 'dark'): Parsed => - value[name] === undefined ? err([`'${path}.${name}' is required.`]) : parse(value[name], `${path}.${name}`); return allOf( unknownKeys(value, ['light', 'dark'], path), - Result.combineWithAllErrors([mode('light'), mode('dark')]) + Result.combineWithAllErrors([ + required(value.light, `${path}.light`, parse), + required(value.dark, `${path}.dark`, parse) + ]) ).map(([light, dark]) => ({ light, dark, single: false })); } @@ -64,6 +65,15 @@ export function optional(value: unknown, parse: (present: unknown) => Parsed< return value === undefined ? ok(null) : parse(value); } +/** Present, then parsed: a field left out is named as missing rather than as the wrong type. */ +export function required( + value: unknown, + path: string, + parse: (present: unknown, path: string) => Parsed +): Parsed { + return value === undefined ? err([`'${path}' is required.`]) : parse(value, path); +} + export function optionalBoolean(value: unknown, path: string, fallback: boolean): Parsed { if (value === undefined) { return ok(fallback); From f39de85ac5db05b0a6735673c3eeafb5cc80c592 Mon Sep 17 00:00:00 2001 From: Muhammad Sohail Date: Fri, 13 Nov 2026 11:29:09 +0500 Subject: [PATCH 28/73] fix(portal): report a search once its close has rendered and its results are in Fumadocs closes the dialog before it hands over the pick, so the close handler's bookkeeping ran a step early: a pick left the typed flag set for the next open, which then reported a phantom search on Escape; a pick without typing reported nothing; and the count read at close could belong to an earlier term whose results were still showing. A close is now seen from the open prop going false, which the hotkey changes too, and the report is made from an effect once the results are shown, with no timeout. Seen in headless Chrome: a pick reports once, a reopen and Escape report nothing, and a term closed before its results arrive is reported with its own count. Co-Authored-By: Claude Fable 5.1 --- portal-template/src/components/search.tsx | 31 ++++++++++++----------- 1 file changed, 16 insertions(+), 15 deletions(-) diff --git a/portal-template/src/components/search.tsx b/portal-template/src/components/search.tsx index cfbf6969..09a72a7b 100644 --- a/portal-template/src/components/search.tsx +++ b/portal-template/src/components/search.tsx @@ -37,32 +37,34 @@ export default function DefaultSearchDialog(props: SharedProps) { const typed = useRef(false); const picked = useRef(''); const openedAt = useRef(''); + const wasOpen = useRef(false); // The page the search is made on: a pick changes the address before the dialog reports its close. useEffect(() => { - if (props.open) openedAt.current = window.location.href; + if (!props.open) return; + wasOpen.current = true; + openedAt.current = window.location.href; }, [props.open]); + // A close is seen from the prop, which the hotkey changes too. Fumadocs hands over the pick before the close + // renders, and the last keystrokes' results may still be loading, so the report waits for the results shown. + useEffect(() => { + if (props.open || !wasOpen.current || query.isLoading) return; + wasOpen.current = false; + if (typed.current || picked.current !== '') { + analytics.reportSearch(search, picked.current, results?.length ?? 0, openedAt.current); + } + typed.current = false; + picked.current = ''; + }, [props.open, query.isLoading, search, results]); + const onSearchChange = (value: string) => { typed.current = true; setSearch(value); }; const onSelect = (item: SearchItemType) => { - typed.current = true; picked.current = 'url' in item ? item.url : ''; }; - const onOpenChange = (open: boolean) => { - props.onOpenChange(open); - if (open || !typed.current) return; - typed.current = false; - const count = results?.length ?? 0; - const page = openedAt.current; - // Fumadocs closes the dialog before it hands over the pick, so the report waits a tick for it. - window.setTimeout(() => { - analytics.reportSearch(search, picked.current, count, page); - picked.current = ''; - }, 0); - }; return ( From af91f019ad3a665c77eb444f8351f1b49af7a809 Mon Sep 17 00:00:00 2001 From: Muhammad Sohail Date: Fri, 13 Nov 2026 11:29:11 +0500 Subject: [PATCH 29/73] refactor(portal): load whatever the adapter registry builds The registry is keyed by every vendor so a missing adapter fails to compile, but the constructor wired the two vendors by hand, so a third could be added to the union and the registry and still never load. Each builder now takes the settings and answers null with its vendor unset, and the constructor loads what the registry builds. Co-Authored-By: Claude Fable 5.1 --- portal-template/src/lib/analytics.ts | 20 +++++++++++++------- test/portal-template/analytics.test.ts | 11 +++++++---- 2 files changed, 20 insertions(+), 11 deletions(-) diff --git a/portal-template/src/lib/analytics.ts b/portal-template/src/lib/analytics.ts index a63d34e4..201dd7d7 100644 --- a/portal-template/src/lib/analytics.ts +++ b/portal-template/src/lib/analytics.ts @@ -64,9 +64,13 @@ export interface Adapter { type Vendor = 'googleTagManager' | 'googleAnalytics'; const GOOGLE = 'https://www.googletagmanager.com'; -/** Keyed by every vendor in the union: a vendor without an adapter does not compile. */ -export const adapters: { [V in Vendor]: (setting: NonNullable) => Adapter } = { - googleTagManager: (setting) => { +/** + * Keyed by every vendor in the union, each building its adapter from the settings, or null with its vendor + * unset: a vendor without an adapter does not compile, and an instance loads whatever the registry builds. + */ +export const adapters: { [V in Vendor]: (settings: PortalAnalytics) => Adapter | null } = { + googleTagManager: ({ googleTagManager: setting }) => { + if (setting === null) return null; const env = setting.environment; const environment = env ? `>m_auth=${encodeURIComponent(env.auth)}>m_preview=${encodeURIComponent(env.preview)}>m_cookies_win=x` @@ -77,7 +81,8 @@ export const adapters: { [V in Vendor]: (setting: NonNullable {} }; }, - googleAnalytics: (setting) => { + googleAnalytics: ({ googleAnalytics: setting }) => { + if (setting === null) return null; let gtag: Gtag; return { setup: (dataLayer) => { @@ -124,7 +129,7 @@ export function copiedLanguage(button: Element): string | null { /** The one instance a portal runs: started when the bundle evaluates, reporting from the root effect and the components. */ export class Analytics { - private readonly live: Adapter[] = []; + private readonly live: Adapter[]; private started = false; private lastPageView: string | null = null; private previousPageView: string | null = null; @@ -133,8 +138,9 @@ export class Analytics { private lastApiResult: FetchResult | null = null; public constructor(private readonly settings: PortalAnalytics) { - if (settings.googleTagManager) this.live.push(adapters.googleTagManager(settings.googleTagManager)); - if (settings.googleAnalytics) this.live.push(adapters.googleAnalytics(settings.googleAnalytics)); + this.live = Object.values(adapters) + .map((build) => build(settings)) + .filter((adapter) => adapter !== null); } /** Once, when the bundle starts: the data layer, every vendor's setup entries, then the vendor tags. */ diff --git a/test/portal-template/analytics.test.ts b/test/portal-template/analytics.test.ts index 53ae8d16..07fad7cf 100644 --- a/test/portal-template/analytics.test.ts +++ b/test/portal-template/analytics.test.ts @@ -492,20 +492,17 @@ describe('Analytics', () => { const suite: { vendor: keyof typeof adapters; settings: PortalAnalytics; - adapter: () => Adapter; pageViewCall: (entries: unknown[]) => void; }[] = [ { vendor: 'googleTagManager', settings: withGtm(), - adapter: () => adapters.googleTagManager({ containerId: 'GTM-ABC123', environment: null }), // The data layer entry is the call; GTM sends nothing of its own. pageViewCall: (entries) => expect(entries.filter(isArguments)).to.be.empty }, { vendor: 'googleAnalytics', settings: withGa4, - adapter: () => adapters.googleAnalytics({ measurementId: 'G-ABC123' }), pageViewCall: (entries) => expect(gtagCalls(entries).at(-1)?.slice(0, 2)).to.deep.equal(['event', 'page_view']) } ]; @@ -514,8 +511,14 @@ describe('Analytics', () => { expect(suite.map((row) => row.vendor)).to.have.members(Object.keys(adapters)); }); - for (const { vendor, settings, adapter, pageViewCall } of suite) { + for (const { vendor, settings, pageViewCall } of suite) { describe(vendor, () => { + const adapter = (): Adapter => adapters[vendor](settings) ?? expect.fail(`${vendor} builds no adapter`); + + it('builds no adapter from settings without its vendor', () => { + expect(adapters[vendor](none)).to.be.null; + }); + it("turns the vendor's own page view off in its setup", () => { browser(quickstart); const pushed: unknown[] = []; From 99a4abe357bfc7af4cba505c5f3484ec196bfe9d Mon Sep 17 00:00:00 2001 From: Muhammad Sohail Date: Fri, 13 Nov 2026 11:29:12 +0500 Subject: [PATCH 30/73] fix(portal): name the page left whichever not-found report lands first page_referrer took the page before the last one reported, which is right only when the missing page's own view has been reported already; in a served portal the not-found effect lands first. The page left is now the last one reported other than the missing page, in either order. Co-Authored-By: Claude Fable 5.1 --- portal-template/src/lib/analytics.ts | 5 ++++- test/portal-template/analytics.test.ts | 12 ++++++++++++ 2 files changed, 16 insertions(+), 1 deletion(-) diff --git a/portal-template/src/lib/analytics.ts b/portal-template/src/lib/analytics.ts index 201dd7d7..560c147d 100644 --- a/portal-template/src/lib/analytics.ts +++ b/portal-template/src/lib/analytics.ts @@ -204,7 +204,10 @@ export class Analytics { referrer.search = ''; referrer.hash = ''; } - this.report('docs_not_found', { page_referrer: this.previousPageView ?? referrer?.href ?? '' }); + // The missing page's own view may be reported before this or after it: the page left is the last + // one reported besides it. + const left = this.lastPageView === page ? this.previousPageView : this.lastPageView; + this.report('docs_not_found', { page_referrer: left ?? referrer?.href ?? '' }); } /** As the playground sends a request: the start of the one duration a request that never arrives can have; a request failing before this has none. */ public requestStarted(): void { diff --git a/test/portal-template/analytics.test.ts b/test/portal-template/analytics.test.ts index 07fad7cf..836d16b4 100644 --- a/test/portal-template/analytics.test.ts +++ b/test/portal-template/analytics.test.ts @@ -773,6 +773,18 @@ describe('Analytics', () => { expect(page.dataLayer().at(-1)).to.have.nested.property('docs.page_location', missing); }); + it('names the page left when the missing page’s own view is yet to be reported', () => { + const page = browser('https://docs.acme.com/guides/quickstart'); + const analytics = new Analytics(none); + analytics.reportPageView(); + page.go(missing); + + analytics.reportNotFound('https://www.google.com/search?q=acme+docs'); + analytics.reportPageView(); + + expect(referrers(page.dataLayer())).to.deep.equal(['https://docs.acme.com/guides/quickstart']); + }); + it('names the referrer without its query or # part on a first load, and nothing when the browser sends none', () => { const page = browser(missing); const analytics = new Analytics(none); From 9518de463be997c76c6e4594a837c566c9557c75 Mon Sep 17 00:00:00 2001 From: Muhammad Sohail Date: Fri, 13 Nov 2026 11:29:13 +0500 Subject: [PATCH 31/73] fix(portal): mark only the dialog holding the request form for replays The playground's observer marked every dialog that opened while an API page was mounted, the search dialog included, which kept search typing out of session replays and put the playground marker on it. The request form tells the playground's dialog from the rest. Co-Authored-By: Claude Fable 5.1 --- portal-template/src/components/playground.tsx | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/portal-template/src/components/playground.tsx b/portal-template/src/components/playground.tsx index 134e2db3..3d5f2874 100644 --- a/portal-template/src/components/playground.tsx +++ b/portal-template/src/components/playground.tsx @@ -26,15 +26,15 @@ const components = { ResultDisplay }; /** The playground with the reporting around it, in the one chunk the API page loads lazily. */ export default function Playground() { - // Fumadocs renders the dialog outside the marked wrapper, so each dialog is marked as it appears, - // until fuma-nama/fumadocs#3824 lets the markers be passed to the dialog directly. + // Fumadocs renders the dialog outside the marked wrapper, so it is marked as it appears, told from the search + // dialog by the request form in it, until fuma-nama/fumadocs#3824 lets the markers be passed to the dialog directly. useEffect(() => { const observer = new MutationObserver((mutations) => { for (const { addedNodes } of mutations) { for (const node of addedNodes) { if (!(node instanceof Element)) continue; const dialog = node.matches('[role="dialog"]') ? node : node.querySelector('[role="dialog"]'); - if (dialog !== null) markForReplay(dialog); + if (dialog !== null && dialog.querySelector('form') !== null) markForReplay(dialog); } } }); From 54c8c60f418fb3d1516d043f35cc9cfb5da6fada Mon Sep 17 00:00:00 2001 From: Muhammad Sohail Date: Fri, 13 Nov 2026 11:29:15 +0500 Subject: [PATCH 32/73] fix(portal): forget a request's start when the playground leaves the page A request still in flight when the reader leaves the operation page reports nothing, and its start stayed to time the next client error, which Fumadocs raises before onRequestInit for a body it has no media adapter for. The playground now clears the start as it unmounts. Co-Authored-By: Claude Fable 5.1 --- portal-template/src/components/playground.tsx | 2 ++ portal-template/src/lib/analytics.ts | 5 +++++ test/portal-template/analytics.test.ts | 11 +++++++++++ 3 files changed, 18 insertions(+) diff --git a/portal-template/src/components/playground.tsx b/portal-template/src/components/playground.tsx index 3d5f2874..1eaf54e0 100644 --- a/portal-template/src/components/playground.tsx +++ b/portal-template/src/components/playground.tsx @@ -41,5 +41,7 @@ export default function Playground() { observer.observe(document.body, { childList: true, subtree: true }); return () => observer.disconnect(); }, []); + // A request still in flight when the page is left reports nothing, so its start must not time a later one. + useEffect(() => () => analytics.requestAbandoned(), []); return ; } diff --git a/portal-template/src/lib/analytics.ts b/portal-template/src/lib/analytics.ts index 560c147d..e35c18df 100644 --- a/portal-template/src/lib/analytics.ts +++ b/portal-template/src/lib/analytics.ts @@ -214,6 +214,11 @@ export class Analytics { this.requestStartedAt = Date.now(); } + /** As the playground leaves the page: a request still in flight reports nothing, so its start times nothing later. */ + public requestAbandoned(): void { + this.requestStartedAt = null; + } + /** The playground's result for `endpoint`, the method and path as the spec writes them: its status and its time, and nothing of the request itself. */ public reportApiRequest(endpoint: string, result: FetchResult): void { // The display mounts again with the same result on each reopen, and twice in a dev build. diff --git a/test/portal-template/analytics.test.ts b/test/portal-template/analytics.test.ts index 836d16b4..04a15e2e 100644 --- a/test/portal-template/analytics.test.ts +++ b/test/portal-template/analytics.test.ts @@ -877,5 +877,16 @@ describe('Analytics', () => { expect(requests(page.dataLayer())[0].docs).to.include({ status: 'client_error', duration_ms: 0 }); }); + + it('times a client error from no start once the playground left the page with a request in flight', () => { + const page = browser(address); + const analytics = new Analytics(none); + analytics.requestStarted(); + analytics.requestAbandoned(); + + analytics.reportApiRequest(endpoint, { type: 'client_error', url, message: 'No adapter' } as never); + + expect(requests(page.dataLayer())[0].docs).to.include({ status: 'client_error', duration_ms: 0 }); + }); }); }); From eee78f68967636194ae93b18ef96cf0a12817398 Mon Sep 17 00:00:00 2001 From: Muhammad Sohail Date: Fri, 13 Nov 2026 11:29:15 +0500 Subject: [PATCH 33/73] docs(portal): record the review of 2026-11-13 Co-Authored-By: Claude Fable 5.1 --- .ai/plans/portal-analytics.md | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/.ai/plans/portal-analytics.md b/.ai/plans/portal-analytics.md index 9b7211fc..4286721f 100644 --- a/.ai/plans/portal-analytics.md +++ b/.ai/plans/portal-analytics.md @@ -528,6 +528,23 @@ that had the right one; a prerendered page mounts idle with the right title and first page. The effect now reports directly only when the router is idle at mount. GA4's own history-change page view was seen on every page change with the stream setting still on, as the warning says. +**Review of 2026-11-13** (`/code-review` over the whole PR, each finding checked against the code, Fumadocs' +source and the served portal): eight findings stood and are fixed, uncommitted. The search dialog's typed and +picked bookkeeping leaked across opens, since Fumadocs closes the dialog before it hands over the pick, and the +count could belong to an earlier term while the last keystrokes' results were loading; the report is now made +from an effect once the close has rendered and the results are shown, which also drops the one-tick timeout. +The playground's observer marked every dialog, the search dialog included on an operation page, so it now +marks only a dialog holding the request form. `enableAnalytics` was forwarded unread through four +`PortalProjectService` methods and into `identity()`, against the "No middlemen" rule; the service and +`identity()` are back to their old signatures, and the two actions hand the service `config.withoutVendors()` +under `--no-analytics`. The `Analytics` constructor hand-wired the two vendors beside a registry meant to guard +them, so the registry's builders now take the settings and the constructor loads whatever they build. Smaller: +the not-found referrer no longer depends on `onRendered` running before the not-found effect; a request still +in flight when the playground leaves the page no longer times a later client error; `required()` moved to +`fields.ts` and serves `lightDark` too. Set aside: a `language-` class the review assumed on code blocks, which +this build renders nowhere; the OAuth-callback tag load, which fuma-nama/fumadocs#3809 covers; the +`sessionStorage` read, which came with #472. + ## 5. Questions each step will raise Answered already, so the agent does not ask them: From d974f46486fc5fc45d204ac24175e09ceafcf95a Mon Sep 17 00:00:00 2001 From: Muhammad Sohail Date: Fri, 13 Nov 2026 11:38:03 +0500 Subject: [PATCH 34/73] fix(portal): hold the vendor tags back at any address holding an OAuth answer The bundle starts on /oauth/callback too, whose address always holds the provider's answer, and on the page a sign-in returns to while the playground has yet to remove it. The portal's own events were already clean there, but gtm.js, gtag.js and the container's tags read the address for themselves. The setup entries are still pushed at start, and the tags are inserted only at a clean address: at start, or on the first page view after, each tag once, so a reader who leaves the callback through the header gets them on the next page. Co-Authored-By: Claude Fable 5.1 --- .ai/plans/portal-analytics-docs.md | 18 ++++++++------- portal-template/src/lib/analytics.ts | 32 +++++++++++++++++++------- test/portal-template/analytics.test.ts | 27 ++++++++++++++++++++-- 3 files changed, 59 insertions(+), 18 deletions(-) diff --git a/.ai/plans/portal-analytics-docs.md b/.ai/plans/portal-analytics-docs.md index 30e4263e..cdd24943 100644 --- a/.ai/plans/portal-analytics-docs.md +++ b/.ai/plans/portal-analytics-docs.md @@ -181,14 +181,16 @@ header and the dialog carry. ### After a sign-in The playground's OAuth sign-in returns the reader to the endpoint page they left. The answer -never reaches the page's address: the playground takes it over through session storage, so the -reported address, the vendors' own page view and anything else that reads the address are -clean. - -> Reviewer: this paragraph holds once fuma-nama/fumadocs#3809 is shipped and picked up, which -> is the PR's merge prerequisite. If the wait of step 1.3 comes back instead, the paragraph -> becomes: the tags start once the playground has removed the answer, up to 5 seconds later, or -> on the next page change. +never reaches a page the vendor tags load on: the callback page loads none, and the page the +reader returns to has a clean address, since the callback hands the answer over through session +storage, so the reported address, the vendors' own page view and anything else that reads the +address are clean. + +> Reviewer: the callback page has loaded no tag since 2026-11-13. The rest of this paragraph +> holds once the branch takes fumadocs-openapi 12.6.2 (from 2026-11-19) with the callback change +> the PR's "Before merging" item names; until then the return page's address holds the answer +> until the playground removes it, the tags load on the next page change, and that page view is +> the first reported. ### Using another tag manager diff --git a/portal-template/src/lib/analytics.ts b/portal-template/src/lib/analytics.ts index e35c18df..58657bb4 100644 --- a/portal-template/src/lib/analytics.ts +++ b/portal-template/src/lib/analytics.ts @@ -127,6 +127,21 @@ export function copiedLanguage(button: Element): string | null { return tabs?.querySelector('[role="tab"][aria-selected="true"]')?.textContent?.trim() || null; } +/** + * Appends each vendor tag once, and none while the address holds an OAuth answer, which GTM's tags and gtag.js + * read for themselves; a tag already in the page is left, so a page view after the callback adds only the rest. + */ +function insertTags(live: Adapter[], keep: readonly string[]): void { + if (pageLocation(window.location.href, keep) === null) return; + for (const src of live.flatMap((adapter) => adapter.scripts())) { + if (document.head.querySelector(`script[src="${src}"]`) !== null) continue; + const script = document.createElement('script'); + script.async = true; + script.src = src; + document.head.append(script); + } +} + /** The one instance a portal runs: started when the bundle evaluates, reporting from the root effect and the components. */ export class Analytics { private readonly live: Adapter[]; @@ -143,18 +158,16 @@ export class Analytics { .filter((adapter) => adapter !== null); } - /** Once, when the bundle starts: the data layer, every vendor's setup entries, then the vendor tags. */ + /** + * Once, when the bundle starts: the data layer, every vendor's setup entries, then the vendor tags unless the + * address holds an OAuth answer, in which case the next page view inserts them. + */ public start(): void { if (this.started) return; this.started = true; const dataLayer = (window.dataLayer ??= []); for (const adapter of this.live) adapter.setup(dataLayer); - for (const src of this.live.flatMap((adapter) => adapter.scripts())) { - const script = document.createElement('script'); - script.async = true; - script.src = src; - document.head.append(script); - } + insertTags(this.live, this.settings.keepQueryParams); } /** `href` is the page the event belongs to, the current one unless the caller saw the address change first. */ @@ -172,7 +185,10 @@ export class Analytics { /** `docs_page_view` for the current page, unless its cleaned address is the one last reported: a `#` jump sends none. */ public reportPageView(): void { const page = pageLocation(window.location.href, this.settings.keepQueryParams); - if (page === null || page === this.lastPageView) return; + if (page === null) return; + // The tags held back on the OAuth callback start here, on the first page after it. + insertTags(this.live, this.settings.keepQueryParams); + if (page === this.lastPageView) return; this.previousPageView = this.lastPageView; this.lastPageView = page; this.report('docs_page_view', { page_title: document.title }); diff --git a/test/portal-template/analytics.test.ts b/test/portal-template/analytics.test.ts index 04a15e2e..7bc96ae8 100644 --- a/test/portal-template/analytics.test.ts +++ b/test/portal-template/analytics.test.ts @@ -221,7 +221,10 @@ function browser(href: string, title = 'Quickstart | Acme API') { const document = { title, createElement: (): FakeScript => ({ async: false, src: '', textContent: '' }), - head: { append: (script: FakeScript) => scripts.push(script) } + head: { + append: (script: FakeScript) => scripts.push(script), + querySelector: (selector: string) => scripts.find((script) => selector === `script[src="${script.src}"]`) ?? null + } }; Object.assign(globalThis, { window, document }); return { @@ -475,7 +478,7 @@ describe('Analytics', () => { 'https://docs.test/oauth/callback/?code=abc&state=123', 'https://docs.test/oauth/callback#access_token=xyz&state=123' ]) { - it(`pushes the setup entries and no page view at ${href}`, () => { + it(`holds the tags and the page view back at ${href}, and inserts the tags on the next page`, () => { const page = browser(href); const analytics = new Analytics(withBoth); @@ -484,6 +487,26 @@ describe('Analytics', () => { expect(page.dataLayer()).to.have.length(3); expect(pageViews(page.dataLayer())).to.be.empty; + expect(page.scripts).to.be.empty; + + page.go(quickstart); + analytics.reportPageView(); + analytics.reportPageView(); + + expect(page.scripts.map((script) => script.src)).to.deep.equal([GTM_SCRIPT, GA4_SCRIPT]); + expect(pageViews(page.dataLayer())).to.have.length(1); + }); + + it(`sends nothing for any event reported at ${href}`, () => { + const page = browser(href); + const analytics = new Analytics(withBoth); + analytics.start(); + + analytics.report('docs_code_copy', { language: 'cURL' }); + analytics.report('docs_markdown_copy', {}); + + expect(page.dataLayer()).to.have.length(3); + expect(gtagCalls(page.dataLayer()).map((command) => command[0])).to.deep.equal(['js', 'config']); }); } }); From a2cfc95dfeabdd15f8e3a407acc3b2f47fe9ad7b Mon Sep 17 00:00:00 2001 From: Muhammad Sohail Date: Fri, 13 Nov 2026 11:38:04 +0500 Subject: [PATCH 35/73] fix(portal): start the analytics once per page load, not once per module A config save under portal serve rewrites portal.identity.json, and Vite evaluates the analytics module again without reloading the page, so a second instance pushed the setup entries and appended both tags again: seen in the browser as two gtm.js scripts and two gtm.start entries in one document, which fires every All Pages trigger twice. The guard is now the window's, which outlives the module. Co-Authored-By: Claude Fable 5.1 --- portal-template/src/lib/analytics.ts | 12 +++++++----- test/portal-template/analytics.test.ts | 3 ++- 2 files changed, 9 insertions(+), 6 deletions(-) diff --git a/portal-template/src/lib/analytics.ts b/portal-template/src/lib/analytics.ts index 58657bb4..6c1d05d4 100644 --- a/portal-template/src/lib/analytics.ts +++ b/portal-template/src/lib/analytics.ts @@ -50,6 +50,8 @@ declare global { interface Window { dataLayer?: unknown[]; gtag?: Gtag; + /** Set by the first start in a page load: a module Vite evaluates again under `portal serve` makes a second instance. */ + portalAnalyticsStarted?: true; } } @@ -145,7 +147,6 @@ function insertTags(live: Adapter[], keep: readonly string[]): void { /** The one instance a portal runs: started when the bundle evaluates, reporting from the root effect and the components. */ export class Analytics { private readonly live: Adapter[]; - private started = false; private lastPageView: string | null = null; private previousPageView: string | null = null; private lastNotFound: string | null = null; @@ -159,12 +160,13 @@ export class Analytics { } /** - * Once, when the bundle starts: the data layer, every vendor's setup entries, then the vendor tags unless the - * address holds an OAuth answer, in which case the next page view inserts them. + * Once per page load, when the bundle starts: the data layer, every vendor's setup entries, then the vendor + * tags unless the address holds an OAuth answer, in which case the next page view inserts them. The guard is + * the window's, not the instance's: a config save under `portal serve` makes Vite evaluate the module again. */ public start(): void { - if (this.started) return; - this.started = true; + if (window.portalAnalyticsStarted) return; + window.portalAnalyticsStarted = true; const dataLayer = (window.dataLayer ??= []); for (const adapter of this.live) adapter.setup(dataLayer); insertTags(this.live, this.settings.keepQueryParams); diff --git a/test/portal-template/analytics.test.ts b/test/portal-template/analytics.test.ts index 7bc96ae8..6bada6dc 100644 --- a/test/portal-template/analytics.test.ts +++ b/test/portal-template/analytics.test.ts @@ -443,12 +443,13 @@ describe('Analytics', () => { expect(page.scripts.map((script) => script.src)).to.deep.equal([GTM_SCRIPT, GA4_SCRIPT]); }); - it('starts once: a second start adds no entry and no script', () => { + it('starts once per page, for a second start and for a second instance alike', () => { const page = browser(quickstart); const analytics = new Analytics(withBoth); analytics.start(); analytics.start(); + new Analytics(withBoth).start(); expect(page.dataLayer()).to.have.length(3); expect(page.scripts).to.have.length(2); From 45945e62364c1f8d4c0d6da9aa769ea341acd7c9 Mon Sep 17 00:00:00 2001 From: Muhammad Sohail Date: Fri, 13 Nov 2026 11:38:06 +0500 Subject: [PATCH 36/73] fix(portal): report a missing page again when the reader comes back to it lastNotFound was set and never cleared, so the guard that absorbs a dev build's double mount also swallowed a real second visit: A, M, A, M sent four page views and one docs_not_found. A page view of any other page now clears it. Co-Authored-By: Claude Fable 5.1 --- portal-template/src/lib/analytics.ts | 2 ++ test/portal-template/analytics.test.ts | 21 +++++++++++++++++++++ 2 files changed, 23 insertions(+) diff --git a/portal-template/src/lib/analytics.ts b/portal-template/src/lib/analytics.ts index 6c1d05d4..b00abfe4 100644 --- a/portal-template/src/lib/analytics.ts +++ b/portal-template/src/lib/analytics.ts @@ -193,6 +193,8 @@ export class Analytics { if (page === this.lastPageView) return; this.previousPageView = this.lastPageView; this.lastPageView = page; + // Another page now: the missing page's next render is a new visit, while its own mounts stay one. + if (this.lastNotFound !== page) this.lastNotFound = null; this.report('docs_page_view', { page_title: document.title }); } /** For a click anywhere on the page: a code block's copy button reports the copy with the block's language. */ diff --git a/test/portal-template/analytics.test.ts b/test/portal-template/analytics.test.ts index 6bada6dc..61370a07 100644 --- a/test/portal-template/analytics.test.ts +++ b/test/portal-template/analytics.test.ts @@ -831,6 +831,27 @@ describe('Analytics', () => { expect(referrers(page.dataLayer())).to.deep.equal(['', '']); }); + + it('reports a missing page again when the reader comes back to it from another page', () => { + const page = browser('https://docs.acme.com/guides/quickstart'); + const analytics = new Analytics(none); + analytics.reportPageView(); + page.go(missing); + analytics.reportNotFound(''); + analytics.reportPageView(); + analytics.reportNotFound(''); + page.go('https://docs.acme.com/guides/quickstart'); + analytics.reportPageView(); + page.go(missing); + analytics.reportPageView(); + analytics.reportNotFound(''); + + expect(referrers(page.dataLayer())).to.deep.equal([ + 'https://docs.acme.com/guides/quickstart', + 'https://docs.acme.com/guides/quickstart' + ]); + expect(pageViews(page.dataLayer())).to.have.length(4); + }); }); describe('reportApiRequest', () => { const address = 'https://docs.acme.com/api/calc/Calculate'; From 246accb71843d165b0dd92a52405b13e716c5df1 Mon Sep 17 00:00:00 2001 From: Muhammad Sohail Date: Fri, 13 Nov 2026 11:38:06 +0500 Subject: [PATCH 37/73] fix(portal): keep the cURL sample out of session replays too The sample beside the playground follows what the reader types into it, the Authorization header and the body included, and it sits outside the marked wrapper and the dialog, so a replay tool would record the typed credential as ordinary page text. It carries the same markers now. Co-Authored-By: Claude Fable 5.1 --- .ai/plans/portal-analytics-docs.md | 9 +++++---- portal-template/src/components/usage-tabs.tsx | 10 ++++++++-- 2 files changed, 13 insertions(+), 6 deletions(-) diff --git a/.ai/plans/portal-analytics-docs.md b/.ai/plans/portal-analytics-docs.md index cdd24943..14f6125d 100644 --- a/.ai/plans/portal-analytics-docs.md +++ b/.ai/plans/portal-analytics-docs.md @@ -173,10 +173,11 @@ page, and read what readers type. Give it only to people you would give the repo Session replay tools record what readers type. The API playground, where readers paste keys and tokens, carries the opt-out markers of PostHog (`ph-no-capture`), FullStory (`fs-exclude`), rrweb (`rr-block`), Amplitude (`amp-block`), Hotjar (`data-hj-suppress`), Microsoft Clarity -(`data-clarity-mask`) and LogRocket (`data-private`): its header on the page, and the dialog it -opens, which is marked as it appears. A replay shows the page with the playground blank. For -any other tool, block the selector `[data-portal-playground]` in its settings, which both the -header and the dialog carry. +(`data-clarity-mask`) and LogRocket (`data-private`): its header on the page, the dialog it +opens, which is marked as it appears, and the cURL sample beside it, which follows what the +reader types into the playground. A replay shows the page with the playground and that sample +blank. For any other tool, block the selector `[data-portal-playground]` in its settings, which +all three carry. ### After a sign-in diff --git a/portal-template/src/components/usage-tabs.tsx b/portal-template/src/components/usage-tabs.tsx index a5e59fcf..776ed526 100644 --- a/portal-template/src/components/usage-tabs.tsx +++ b/portal-template/src/components/usage-tabs.tsx @@ -5,6 +5,7 @@ import { useCodeUsage } from 'fumadocs-openapi/operation'; import { createCodeUsageGeneratorRegistry } from 'fumadocs-openapi/requests/generators'; import { curl } from 'fumadocs-openapi/requests/generators/curl'; import { CodeSample } from '@/lib/code-samples'; +import { REPLAY_MARKERS } from '@/lib/replay-markers'; import { useExampleSelection } from './example-layout'; interface UsageTab { @@ -64,9 +65,14 @@ function SampleCode({ sample }: Readonly<{ sample: CodeSample }>) { return ; } -// Follows the playground's edits to the selected example, on the selected server. +// Follows the playground's edits to the selected example, on the selected server, the typed credentials among +// them: marked as the playground is, so a session replay shows this sample blank too. function CurlCode() { const { CodeBlock } = useComponents(); const code = useCodeUsage(CURL_USAGE_ID); - return code === undefined ? null : ; + return code === undefined ? null : ( +
+ +
+ ); } From 8c4be3fe8a36f64e063c1d37b159a11608ed736a Mon Sep 17 00:00:00 2001 From: Muhammad Sohail Date: Fri, 13 Nov 2026 11:38:08 +0500 Subject: [PATCH 38/73] test(portal): hold every adapter to naming no recording or capture The suite was meant to stop a later adapter that turns session recording or input capture on, and had no check for it. Neither a setup entry nor a script of an adapter may so much as name them; one that has to, to turn them off, says in the suite how it does. Co-Authored-By: Claude Fable 5.1 --- test/portal-template/analytics.test.ts | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/test/portal-template/analytics.test.ts b/test/portal-template/analytics.test.ts index 61370a07..0f669902 100644 --- a/test/portal-template/analytics.test.ts +++ b/test/portal-template/analytics.test.ts @@ -543,6 +543,18 @@ describe('Analytics', () => { expect(adapters[vendor](none)).to.be.null; }); + it('turns no session recording or input capture on, nor so much as names them', () => { + browser(quickstart); + const pushed: unknown[] = []; + adapter().setup(pushed); + + // A later adapter that has to name them, to turn them off, says here how it does. + const named = /record|capture|replay/i; + const entries = pushed.map((entry) => (isArguments(entry) ? Array.from(entry as ArrayLike) : entry)); + expect(JSON.stringify(entries)).to.not.match(named); + for (const src of adapter().scripts()) expect(src).to.not.match(named); + }); + it("turns the vendor's own page view off in its setup", () => { browser(quickstart); const pushed: unknown[] = []; From 7252e776a2b6816aa1a9217b36e732700dbbf581 Mon Sep 17 00:00:00 2001 From: Muhammad Sohail Date: Fri, 13 Nov 2026 11:38:08 +0500 Subject: [PATCH 39/73] docs(portal): record the reviewer's findings of 2026-11-13 Co-Authored-By: Claude Fable 5.1 --- .ai/plans/portal-analytics.md | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/.ai/plans/portal-analytics.md b/.ai/plans/portal-analytics.md index 4286721f..876ec3c4 100644 --- a/.ai/plans/portal-analytics.md +++ b/.ai/plans/portal-analytics.md @@ -545,6 +545,22 @@ in flight when the playground leaves the page no longer times a later client err this build renders nowhere; the OAuth-callback tag load, which fuma-nama/fumadocs#3809 covers; the `sessionStorage` read, which came with #472. +**The reviewer's findings of 2026-11-13** (seven, on PR #473), taken the same day: the vendor tags load +neither on `/oauth/callback` nor at any address holding an OAuth answer; `start()` pushes the setup entries +and inserts the tags only at a clean address, `reportPageView()` inserts them otherwise on the first page +after, each tag once, and the start guard is the window's, since a config save under `portal serve` made Vite +evaluate the module again and start a second time (seen in the browser: two `gtm.js` scripts and two +`gtm.start` entries in one document). The cURL sample beside the playground follows the typed credentials, so +it carries the replay markers too. The search dialog's close is seen from its open prop, which the hotkey +changes as well. `lastNotFound` clears on the next page, so a repeat visit to a missing page reports again. The +adapter suite checks that no setup entry or script so much as names recording or capture, and `report()`'s own +callback guard has a direct test. Still open, and now the one merge prerequisite: taking fumadocs-openapi +12.6.2 does not keep the answer out of the address on its own, since our own callback copies the provider's +query and `#` part onto the starting page; 12.6.2's `getReturnedFlow()` reads `sessionStorage` under +`fumadocs-openapi-oauth-returned` and falls back to the address, while 12.6.0 reads the address only, so the +callback change (store `location.href` under that key, return the bare page, follow in +`oauth-callback.test.ts` and the comment at `oauth-callback.ts:13`) lands with the bump, from 2026-11-19. + ## 5. Questions each step will raise Answered already, so the agent does not ask them: From 42cae7a8a6a2a7192c928d8f194eb566392bf007 Mon Sep 17 00:00:00 2001 From: Muhammad Sohail Date: Fri, 13 Nov 2026 11:54:33 +0500 Subject: [PATCH 40/73] refactor(portal): decide the build's vendor tags in one place settingsForBuild() turns the settings and --no-analytics into what the build writes, so the prepare and serve actions no longer repeat the ternary. The prepare action hands the same source to the caller's next step, which lets generate's Google Analytics notice read the config alone. Co-Authored-By: Claude Opus 5.5 --- .ai/plans/portal-analytics.md | 12 +++++++----- src/actions/portal/generate.ts | 2 +- src/actions/portal/prepare-project.ts | 12 ++++-------- src/actions/portal/serve.ts | 4 ++-- src/types/portal/portal-source.ts | 5 +++++ test/actions/portal/prepare-project.test.ts | 7 ++----- 6 files changed, 21 insertions(+), 21 deletions(-) diff --git a/.ai/plans/portal-analytics.md b/.ai/plans/portal-analytics.md index 876ec3c4..d4a6528a 100644 --- a/.ai/plans/portal-analytics.md +++ b/.ai/plans/portal-analytics.md @@ -305,9 +305,11 @@ Delivers, from the commands inward, after the "check first" answer in section 5: or marketing script, for staging."; each passes `enableAnalytics: !flags['no-analytics']` to its action; quickstart's preview passes `true`. - `PreparePortalProjectAction` takes `enableAnalytics: boolean` as a parameter, never a field, - and hands `PortalProjectService.prepare()` the source as read, or with - `config.withoutVendors()` when the flag is false; `src/actions/portal/serve.ts` does the same - for `applyConfig()` on each rewrite. The service, `PortalConfig.identity()` and + and hands `PortalProjectService.prepare()` and the caller's next step + `settingsForBuild(source, enableAnalytics)` from `src/types/portal/portal-source.ts`: the source + as read, or with `config.withoutVendors()` when the flag is false. `src/actions/portal/serve.ts` + does the same for `applyConfig()` on each rewrite, and `generate`'s Google Analytics notice + reads the config alone. The service, `PortalConfig.identity()` and `AnalyticsConfig.identity()` never see the flag (the review of 2026-11-13 moved it up from them). The sketch's `PortalDelivery` class is not built: with no preview mode it would wrap this one boolean. @@ -315,8 +317,8 @@ Delivers, from the commands inward, after the "check first" answer in section 5: Tests: both commands accept the flag (`test/commands/flag-parser.ts` is the helper the command tests use); `withoutVendors()` leaves both vendors out and keeps `keepQueryParams` and the rest of the identity; the generate, prepare and serve actions hand the service a config without -vendors under `--no-analytics`, the serve action on each rewrite too, while what follows them -still sees the source as read; the identity file written from such a config has both vendors +vendors under `--no-analytics`, the serve action on each rewrite too, and the prepare action +hands the same config to the caller's next step; the identity file written from such a config has both vendors `null`. Commit: `feat(portal): add --no-analytics and leave the vendors out of the identity file`. diff --git a/src/actions/portal/generate.ts b/src/actions/portal/generate.ts index 05bcbc3f..1daf9ced 100644 --- a/src/actions/portal/generate.ts +++ b/src/actions/portal/generate.ts @@ -46,7 +46,7 @@ export class GenerateAction { return await prepare.execute(project, enableAnalytics, { confirm: () => this.confirmOverwrite(portalContext, portalDirectory, force), onPrepared: (portalProject, source) => { - if (enableAnalytics && source.config.usesGoogleAnalytics()) { + if (source.config.usesGoogleAnalytics()) { this.prompts.googleAnalyticsCountsPageChanges(); } return this.build(portalProject, source.config.siteAddress(), portalContext, portalDirectory, zipPortal); diff --git a/src/actions/portal/prepare-project.ts b/src/actions/portal/prepare-project.ts index a3315d77..844f90e2 100644 --- a/src/actions/portal/prepare-project.ts +++ b/src/actions/portal/prepare-project.ts @@ -6,7 +6,7 @@ import { PreparePortalProjectPrompts } from '../../prompts/portal/prepare-projec import { CommandMetadata } from '../../types/common/command-metadata.js'; import { DirectoryPath } from '../../types/file/directoryPath.js'; import { PortalArtifacts } from '../../types/portal/portal-artifacts.js'; -import { PortalSource } from '../../types/portal/portal-source.js'; +import { PortalSource, settingsForBuild } from '../../types/portal/portal-source.js'; import { ProjectContext } from '../../types/project-context.js'; import { ActionResult } from '../action-result.js'; @@ -111,18 +111,14 @@ export class PreparePortalProjectAction { } return await withDirPath(async (tempDirectory) => { - // Under --no-analytics the build names neither vendor tag; what follows still sees the source as read. - const portalProject = await this.projectService.prepare( - tempDirectory, - enableAnalytics ? source.value : { ...source.value, config: source.value.config.withoutVendors() }, - artifacts.value - ); + const sourceForBuild = settingsForBuild(source.value, enableAnalytics); + const portalProject = await this.projectService.prepare(tempDirectory, sourceForBuild, artifacts.value); if (portalProject.isErr()) { this.prompts.runtimeUnsupported(portalProject.error); return ActionResult.failed(); } - return await onPrepared(portalProject.value, source.value, artifacts.value); + return await onPrepared(portalProject.value, sourceForBuild, artifacts.value); }); }); }; diff --git a/src/actions/portal/serve.ts b/src/actions/portal/serve.ts index cfe861b2..8ab0dc4f 100644 --- a/src/actions/portal/serve.ts +++ b/src/actions/portal/serve.ts @@ -9,7 +9,7 @@ import { ProjectContext } from '../../types/project-context.js'; import { isSkippedByGlob } from '../../types/portal/content-tree.js'; import { GeneratedPages } from '../../types/portal/generated-pages.js'; import { PortalArtifacts } from '../../types/portal/portal-artifacts.js'; -import { PortalSettings, PortalSource, WatchedSource } from '../../types/portal/portal-source.js'; +import { PortalSettings, PortalSource, settingsForBuild, WatchedSource } from '../../types/portal/portal-source.js'; import { PreviewConfig } from '../../types/portal/preview-config.js'; import { PreviewContent } from '../../types/portal/preview-content.js'; import { PreviewSpecs } from '../../types/portal/preview-specs.js'; @@ -161,7 +161,7 @@ export class PortalServeAction { const applied = await this.projectService.applyConfig( portalProjectDirectory, - enableAnalytics ? settings : { ...settings, config: config.withoutVendors() } + settingsForBuild(settings, enableAnalytics) ); if (applied.isErr()) { this.prompts.notApplied('config', applied.error, sourceDirectory); diff --git a/src/types/portal/portal-source.ts b/src/types/portal/portal-source.ts index bf5c8ccf..6468540d 100644 --- a/src/types/portal/portal-source.ts +++ b/src/types/portal/portal-source.ts @@ -47,6 +47,11 @@ export interface PortalSource extends PortalSettings { contentNotices: ContentNotices; } +/** The settings a portal is built from: under `--no-analytics`, neither vendor tag. */ +export function settingsForBuild(settings: T, enableAnalytics: boolean): T { + return enableAnalytics ? settings : { ...settings, config: settings.config.withoutVendors() }; +} + /** Why a source directory could not be written; each variant maps to its own message. */ export type PortalScaffoldProblem = | { kind: 'configUnreadable' } diff --git a/test/actions/portal/prepare-project.test.ts b/test/actions/portal/prepare-project.test.ts index 37deb1d6..f8bed4c0 100644 --- a/test/actions/portal/prepare-project.test.ts +++ b/test/actions/portal/prepare-project.test.ts @@ -75,7 +75,7 @@ describe('PreparePortalProjectAction', () => { expect(uploaded.filter((entry) => entry.startsWith('static/'))).to.be.empty; }); - it('prepares the project with neither vendor tag under --no-analytics, and hands on the source as read', async () => { + it('prepares the project, and hands on the source, with neither vendor tag under --no-analytics', async () => { const root = fs.mkdtempSync(path.join(os.tmpdir(), 'portal-prepare-')); try { fs.cpSync(FIXTURE.toString(), root, { recursive: true }); @@ -87,10 +87,7 @@ describe('PreparePortalProjectAction', () => { await execute(false, new DirectoryPath(root)); expect(shared.prepare.firstCall.args[1].config.identity().analytics.googleTagManager).to.be.null; - expect(onPrepared.firstCall.args[1].config.identity().analytics.googleTagManager).to.deep.equal({ - containerId: 'GTM-ABC123', - environment: null - }); + expect(onPrepared.firstCall.args[1].config.identity().analytics.googleTagManager).to.be.null; } finally { fs.rmSync(root, { recursive: true, force: true }); } From c810cb8c5489b068b2645250bbed63cc4642d02f Mon Sep 17 00:00:00 2001 From: Muhammad Sohail Date: Fri, 13 Nov 2026 12:00:13 +0500 Subject: [PATCH 41/73] refactor(portal): write the appearance files from writeConfiguration again fe93025e moved the call up into prepare() so it could take the --no-analytics flag; be8cc928 took the flag back out of the service but left the call where it was. Moving it back leaves the project service as it is on dev. The files are written in the same order as before. Co-Authored-By: Claude Opus 5.5 --- src/infrastructure/portal-project-service.ts | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/src/infrastructure/portal-project-service.ts b/src/infrastructure/portal-project-service.ts index 6d8fdf1a..87334ad8 100644 --- a/src/infrastructure/portal-project-service.ts +++ b/src/infrastructure/portal-project-service.ts @@ -131,7 +131,6 @@ export class PortalProjectService { await this.writeCodeSamples(projectDirectory, source, artifacts.codeSampleCatalogs), await this.writeDownloads(projectDirectory, artifacts) ); - await this.writeAppearance(projectDirectory, source.config); const pages = await this.pagesService.write(projectDirectory.join(GENERATED_DIRECTORY_NAME), source.generatedPages); if (pages.isErr()) { @@ -298,6 +297,8 @@ export class PortalProjectService { new FilePath(projectDirectory, new FileName('portal.config.json')), JSON.stringify(configuration, null, 2) ); + + await this.writeAppearance(projectDirectory, source.config); } /** From beaecde85df03d27c3725c92fbb1a21786d9a046 Mon Sep 17 00:00:00 2001 From: Muhammad Sohail Date: Fri, 13 Nov 2026 14:01:59 +0500 Subject: [PATCH 42/73] refactor(portal): report code copies and searches from their components analytics.ts read Fumadocs' code-block markup, and held half of the rule for when a search counts while search.tsx held the other half. The click is now read by copiedLanguage() in lib/code-copy.ts, and the root's listener reports it through report(); search.tsx decides alone whether a search counts and reports it the same way. reportNotFound() reads document.referrer itself, as reportPageView() reads the title. The code-copy tests move with the function. Co-Authored-By: Claude Opus 5.5 --- portal-template/src/components/not-found.tsx | 2 +- portal-template/src/components/search.tsx | 6 +- portal-template/src/lib/analytics.ts | 34 +-- portal-template/src/lib/code-copy.ts | 16 ++ portal-template/src/routes/__root.tsx | 6 +- test/portal-template/analytics.test.ts | 238 ++++--------------- test/portal-template/code-copy.test.ts | 107 +++++++++ 7 files changed, 176 insertions(+), 233 deletions(-) create mode 100644 portal-template/src/lib/code-copy.ts create mode 100644 test/portal-template/code-copy.test.ts diff --git a/portal-template/src/components/not-found.tsx b/portal-template/src/components/not-found.tsx index e0351b1b..54b409b3 100644 --- a/portal-template/src/components/not-found.tsx +++ b/portal-template/src/components/not-found.tsx @@ -8,7 +8,7 @@ import { DefaultNotFound } from 'fumadocs-ui/layouts/home/not-found'; export function NotFound() { const { pathname } = useLocation(); // Keyed on the path: the same component shows the next missing page too. - useEffect(() => analytics.reportNotFound(document.referrer), [pathname]); + useEffect(() => analytics.reportNotFound(), [pathname]); return ( diff --git a/portal-template/src/components/search.tsx b/portal-template/src/components/search.tsx index 09a72a7b..7d1a5811 100644 --- a/portal-template/src/components/search.tsx +++ b/portal-template/src/components/search.tsx @@ -51,8 +51,10 @@ export default function DefaultSearchDialog(props: SharedProps) { useEffect(() => { if (props.open || !wasOpen.current || query.isLoading) return; wasOpen.current = false; - if (typed.current || picked.current !== '') { - analytics.reportSearch(search, picked.current, results?.length ?? 0, openedAt.current); + const search_term = search.trim(); + if ((typed.current || picked.current !== '') && search_term !== '') { + const result_count = results?.length ?? 0; + analytics.report('docs_search', { search_term, result: picked.current, result_count }, openedAt.current); } typed.current = false; picked.current = ''; diff --git a/portal-template/src/lib/analytics.ts b/portal-template/src/lib/analytics.ts index b00abfe4..051a0630 100644 --- a/portal-template/src/lib/analytics.ts +++ b/portal-template/src/lib/analytics.ts @@ -116,19 +116,6 @@ export function pageLocation(href: string, keep: readonly string[], base?: strin return url.href; } -/** - * The language of the code block a copy button sits in: a titled block's caption, or the selected tab's name - * when the block is one of a tabbed set. Null for a block with neither, and for a button outside any block. - */ -export function copiedLanguage(button: Element): string | null { - const figure = button.closest('figure'); - if (figure === null) return null; - const caption = figure.querySelector('figcaption')?.textContent?.trim(); - if (caption) return caption; - const tabs = figure.closest('[role="tabpanel"]')?.parentElement; - return tabs?.querySelector('[role="tab"][aria-selected="true"]')?.textContent?.trim() || null; -} - /** * Appends each vendor tag once, and none while the address holds an OAuth answer, which GTM's tags and gtag.js * read for themselves; a tag already in the page is left, so a page view after the callback adds only the rest. @@ -197,29 +184,14 @@ export class Analytics { if (this.lastNotFound !== page) this.lastNotFound = null; this.report('docs_page_view', { page_title: document.title }); } - /** For a click anywhere on the page: a code block's copy button reports the copy with the block's language. */ - public reportCodeCopy(target: EventTarget | null): void { - const button = target !== null && 'closest' in target ? (target as Element).closest('figure button') : null; - if (button === null) return; - // Not a copy: a dropdown in a block's header, the playground's dialog, or a block that reports its own copy. - if (button.matches('[role="combobox"]') || button.matches('[aria-haspopup]')) return; - if (button.closest('[role="dialog"]') !== null || button.closest('[data-copy-reported]') !== null) return; - const language = copiedLanguage(button); - if (language !== null) this.report('docs_code_copy', { language }); - } - /** One search, as the dialog closes: what was typed, the pick or '' for none, the count shown, and the page searched from. */ - public reportSearch(term: string, picked: string, resultCount: number, href: string): void { - const search_term = term.trim(); - if (search_term === '') return; - this.report('docs_search', { search_term, result: picked, result_count: resultCount }, href); - } + /** The not-found page, once per missing page: `page_referrer` is the portal page left for it, else the document's referrer without its query. */ - public reportNotFound(documentReferrer: string): void { + public reportNotFound(): void { const page = pageLocation(window.location.href, this.settings.keepQueryParams); // A dev build mounts the page twice; the next missing page is a new report. if (page === null || page === this.lastNotFound) return; this.lastNotFound = page; - const referrer = documentReferrer === '' ? null : new URL(documentReferrer); + const referrer = document.referrer === '' ? null : new URL(document.referrer); if (referrer !== null) { referrer.search = ''; referrer.hash = ''; diff --git a/portal-template/src/lib/code-copy.ts b/portal-template/src/lib/code-copy.ts new file mode 100644 index 00000000..3a7d9f4c --- /dev/null +++ b/portal-template/src/lib/code-copy.ts @@ -0,0 +1,16 @@ +/** + * The language of the code block whose copy button a click hit: a titled block's caption, or the selected tab's + * name when the block is one of a tabbed set. Null for a block with neither, and for any other click. + */ +export function copiedLanguage(target: EventTarget | null): string | null { + const button = target !== null && 'closest' in target ? (target as Element).closest('figure button') : null; + if (button === null) return null; + // Not a copy: a dropdown in a block's header, the playground's dialog, or a block that reports its own copy. + if (button.matches('[role="combobox"]') || button.matches('[aria-haspopup]')) return null; + if (button.closest('[role="dialog"]') !== null || button.closest('[data-copy-reported]') !== null) return null; + const figure = button.closest('figure'); + const caption = figure?.querySelector('figcaption')?.textContent?.trim(); + if (caption) return caption; + const tabs = figure?.closest('[role="tabpanel"]')?.parentElement; + return tabs?.querySelector('[role="tab"][aria-selected="true"]')?.textContent?.trim() || null; +} diff --git a/portal-template/src/routes/__root.tsx b/portal-template/src/routes/__root.tsx index 7aa0eefe..7c1c4820 100644 --- a/portal-template/src/routes/__root.tsx +++ b/portal-template/src/routes/__root.tsx @@ -7,6 +7,7 @@ import appCss from '@/styles/app.css?url'; import { RootProvider } from 'fumadocs-ui/provider/tanstack'; import SearchDialog from '@/components/search'; import { withBasePath } from '@/lib/base-path'; +import { copiedLanguage } from '@/lib/code-copy'; import { portal } from '@/lib/portal'; import { analytics } from '@/lib/portal-analytics'; @@ -28,7 +29,10 @@ const iconLinks = portal.favicon : []; // Fumadocs' copy button has no callback of its own, so the document hears every click. -const reportCodeCopy = (event: MouseEvent) => analytics.reportCodeCopy(event.target); +const reportCodeCopy = (event: MouseEvent) => { + const language = copiedLanguage(event.target); + if (language !== null) analytics.report('docs_code_copy', { language }); +}; // A portal fixed to one mode keeps to it whatever the visitor's system prefers, and offers no // way out: the layout hides the switch, and the `D` hotkey is turned off here. diff --git a/test/portal-template/analytics.test.ts b/test/portal-template/analytics.test.ts index 0f669902..7262472e 100644 --- a/test/portal-template/analytics.test.ts +++ b/test/portal-template/analytics.test.ts @@ -3,7 +3,6 @@ import { Adapter, adapters, Analytics, - copiedLanguage, pageLocation, PortalEventName, PortalEvents @@ -121,87 +120,6 @@ describe('PortalEvents', () => { }); }); -/** As much of an element as the copy reader walks: the selectors it matches, its text, and its place in the tree. */ -class FakeElement { - public parentElement: FakeElement | null = null; - - public constructor( - private readonly selectors: string[], - public readonly textContent: string | null = null, - private readonly children: FakeElement[] = [] - ) { - for (const child of children) child.parentElement = this; - } - - public matches(selector: string): boolean { - return this.selectors.includes(selector); - } - - public closest(selector: string): FakeElement | null { - return this.selectors.includes(selector) ? this : this.parentElement?.closest(selector) ?? null; - } - - public querySelector(selector: string): FakeElement | null { - for (const child of this.children) { - const found = child.selectors.includes(selector) ? child : child.querySelector(selector); - if (found !== null) return found; - } - return null; - } -} - -const element = (fake: FakeElement) => fake as unknown as Parameters[0]; - -/** Fumadocs' code block: a figure with the copy button in its header beside the caption, or in its corner when untitled. */ -function codeBlock(title: string | null) { - const button = new FakeElement(['figure button']); - const caption = title === null ? [] : [new FakeElement(['figcaption'], title)]; - const figure = new FakeElement(['figure'], null, [new FakeElement([], null, [...caption, button])]); - return { figure, button }; -} - -/** A tabbed set of untitled blocks under one root, with `selected` shown: the copy button of the block that is. */ -function tabbedBlocks(names: string[], selected: string): FakeElement { - const tabs = names.map( - (name) => - new FakeElement( - name === selected ? ['[role="tab"]', '[role="tab"][aria-selected="true"]'] : ['[role="tab"]'], - name - ) - ); - const blocks = names.map(() => codeBlock(null)); - const panels = blocks.map(({ figure }) => new FakeElement(['[role="tabpanel"]'], null, [figure])); - new FakeElement([], null, [new FakeElement(['[role="tablist"]'], null, tabs), ...panels]); - return blocks[names.indexOf(selected)].button; -} - -describe('copiedLanguage', () => { - it('reads a titled block’s caption', () => { - expect(copiedLanguage(element(codeBlock('TypeScript').button))).to.equal('TypeScript'); - }); - - it('reads the selected tab’s name for a block in a tabbed set', () => { - expect(copiedLanguage(element(tabbedBlocks(['cURL', 'TypeScript'], 'TypeScript')))).to.equal('TypeScript'); - expect(copiedLanguage(element(tabbedBlocks(['cURL', 'TypeScript'], 'cURL')))).to.equal('cURL'); - }); - - it('prefers the caption of a titled block inside a tabbed set', () => { - const { figure, button } = codeBlock('Terminal'); - const tab = new FakeElement(['[role="tab"]', '[role="tab"][aria-selected="true"]'], 'macOS'); - new FakeElement([], null, [ - new FakeElement(['[role="tablist"]'], null, [tab]), - new FakeElement(['[role="tabpanel"]'], null, [figure]) - ]); - - expect(copiedLanguage(element(button))).to.equal('Terminal'); - }); - - it('is null for a block with neither, and for a button outside any block', () => { - expect(copiedLanguage(element(codeBlock(null).button))).to.be.null; - expect(copiedLanguage(element(new FakeElement(['button'])))).to.be.null; - }); -}); - interface FakeScript { async: boolean; src: string; @@ -215,11 +133,12 @@ interface FakeWindow { } /** A page in the browser: the `window` and `document` the module reads, and the scripts the loader appends. */ -function browser(href: string, title = 'Quickstart | Acme API') { +function browser(href: string, title = 'Quickstart | Acme API', referrer = '') { const scripts: FakeScript[] = []; const window: FakeWindow = { location: { href } }; const document = { title, + referrer, createElement: (): FakeScript => ({ async: false, src: '', textContent: '' }), head: { append: (script: FakeScript) => scripts.push(script), @@ -639,6 +558,20 @@ describe('Analytics', () => { const withoutResets = page.dataLayer().filter((entry) => !(isPlainObject(entry) && entry.docs === null)); expect(mergedLikeGtm(withoutResets).docs).to.have.property('language', 'python'); }); + + it('reports the page the caller names, not the one the address has moved on to', () => { + const page = browser(quickstart); + const analytics = new Analytics(none); + page.go('https://docs.test/guides/authentication'); + + analytics.report( + 'docs_search', + { search_term: 'auth', result: '/guides/authentication', result_count: 3 }, + quickstart + ); + + expect(page.dataLayer().at(-1)).to.have.nested.property('docs.page_location', quickstart); + }); }); // The root effect calls this once on mount and once per page change the router renders. @@ -691,104 +624,6 @@ describe('Analytics', () => { ).to.deep.equal([quickstart, components, quickstart]); }); }); - describe('reportCodeCopy', () => { - const address = 'https://docs.acme.com/guides/quickstart'; - const codeCopies = (entries: unknown[]) => - entries.filter((entry) => isPlainObject(entry) && entry.event === 'docs_code_copy'); - - it('reports a code block’s copy with its language', () => { - const page = browser(address); - const analytics = new Analytics(none); - - analytics.reportCodeCopy(element(codeBlock('TypeScript').button)); - - expect(codeCopies(page.dataLayer())).to.deep.equal([ - { event: 'docs_code_copy', docs: { language: 'TypeScript', page_location: address } } - ]); - }); - - it('reports nothing for a click outside a block, on an untitled block, or in a block that reports its own copy', () => { - const page = browser(address); - const analytics = new Analytics(none); - const own = codeBlock('Terminal'); - // The install command's wrapper marks its block. - new FakeElement(['[data-copy-reported]'], null, [own.figure]); - - analytics.reportCodeCopy(element(new FakeElement(['button']))); - analytics.reportCodeCopy(element(codeBlock(null).button)); - analytics.reportCodeCopy(element(own.button)); - analytics.reportCodeCopy(null); - - expect(codeCopies(page.dataLayer())).to.be.empty; - }); - - it('reports nothing for a dropdown in a block’s header, nor for anything in the playground’s dialog', () => { - const page = browser(address); - const analytics = new Analytics(none); - const dropdown = new FakeElement(['figure button', '[role="combobox"]']); - new FakeElement(['figure'], null, [ - new FakeElement([], null, [new FakeElement(['figcaption'], 'Request'), dropdown]) - ]); - const menu = new FakeElement(['figure button', '[aria-haspopup]']); - new FakeElement(['figure'], null, [new FakeElement(['figcaption'], 'JSON'), menu]); - const inDialog = codeBlock('Body'); - new FakeElement(['[role="dialog"]'], null, [inDialog.figure]); - - analytics.reportCodeCopy(element(dropdown)); - analytics.reportCodeCopy(element(menu)); - analytics.reportCodeCopy(element(inDialog.button)); - - expect(codeCopies(page.dataLayer())).to.be.empty; - }); - }); - describe('reportSearch', () => { - const address = 'https://docs.acme.com/guides/quickstart'; - const searches = (entries: unknown[]) => - entries.filter((entry) => isPlainObject(entry) && entry.event === 'docs_search'); - - it('reports the term trimmed, the pick and the count shown', () => { - const page = browser(address); - - new Analytics(none).reportSearch(' auth ', '/guides/authentication', 3, address); - - expect(searches(page.dataLayer())).to.deep.equal([ - { - event: 'docs_search', - docs: { search_term: 'auth', result: '/guides/authentication', result_count: 3, page_location: address } - } - ]); - }); - - it('reports an empty result when the dialog closed without a pick', () => { - const page = browser(address); - - new Analytics(none).reportSearch('auth', '', 0, address); - - expect(searches(page.dataLayer())).to.deep.equal([ - { event: 'docs_search', docs: { search_term: 'auth', result: '', result_count: 0, page_location: address } } - ]); - }); - - it('reports nothing when nothing was typed', () => { - const page = browser(address); - const analytics = new Analytics(none); - - analytics.reportSearch('', '', 0, address); - analytics.reportSearch(' ', '/guides/authentication', 1, address); - - expect(searches(page.dataLayer())).to.be.empty; - }); - - it('reports the page the search was made on, not the one a pick led to', () => { - const page = browser(address); - const analytics = new Analytics(none); - page.go('https://docs.acme.com/guides/authentication'); - - analytics.reportSearch('auth', '/guides/authentication', 3, address); - - expect(searches(page.dataLayer())).to.have.nested.property('[0].docs.page_location', address); - }); - }); describe('reportNotFound', () => { const missing = 'https://docs.acme.com/guides/missing'; const referrers = (entries: unknown[]) => @@ -797,49 +632,56 @@ describe('Analytics', () => { .map((entry) => (entry as { docs: { page_referrer: string } }).docs.page_referrer); it('names the portal page the reader left for it, whatever the document says', () => { - const page = browser('https://docs.acme.com/guides/quickstart'); + const page = browser( + 'https://docs.acme.com/guides/quickstart', + 'Quickstart', + 'https://www.google.com/search?q=acme+docs' + ); const analytics = new Analytics(none); analytics.reportPageView(); page.go(missing); analytics.reportPageView(); - analytics.reportNotFound('https://www.google.com/search?q=acme+docs'); + analytics.reportNotFound(); expect(referrers(page.dataLayer())).to.deep.equal(['https://docs.acme.com/guides/quickstart']); expect(page.dataLayer().at(-1)).to.have.nested.property('docs.page_location', missing); }); it('names the page left when the missing page’s own view is yet to be reported', () => { - const page = browser('https://docs.acme.com/guides/quickstart'); + const page = browser( + 'https://docs.acme.com/guides/quickstart', + 'Quickstart', + 'https://www.google.com/search?q=acme+docs' + ); const analytics = new Analytics(none); analytics.reportPageView(); page.go(missing); - analytics.reportNotFound('https://www.google.com/search?q=acme+docs'); + analytics.reportNotFound(); analytics.reportPageView(); expect(referrers(page.dataLayer())).to.deep.equal(['https://docs.acme.com/guides/quickstart']); }); it('names the referrer without its query or # part on a first load, and nothing when the browser sends none', () => { - const page = browser(missing); - const analytics = new Analytics(none); - - analytics.reportNotFound('https://www.google.com/search?q=acme+docs#top'); - page.go('https://docs.acme.com/guides/other-missing'); - analytics.reportNotFound(''); + const fromSearch = browser(missing, 'Not found', 'https://www.google.com/search?q=acme+docs#top'); + new Analytics(none).reportNotFound(); + const typedIn = browser(missing, 'Not found'); + new Analytics(none).reportNotFound(); - expect(referrers(page.dataLayer())).to.deep.equal(['https://www.google.com/search', '']); + expect(referrers(fromSearch.dataLayer())).to.deep.equal(['https://www.google.com/search']); + expect(referrers(typedIn.dataLayer())).to.deep.equal(['']); }); it('reports a missing page once, however often its page mounts, and the next missing page again', () => { const page = browser(missing); const analytics = new Analytics(none); - analytics.reportNotFound(''); - analytics.reportNotFound(''); + analytics.reportNotFound(); + analytics.reportNotFound(); page.go('https://docs.acme.com/guides/also-missing'); - analytics.reportNotFound(''); + analytics.reportNotFound(); expect(referrers(page.dataLayer())).to.deep.equal(['', '']); }); @@ -849,14 +691,14 @@ describe('Analytics', () => { const analytics = new Analytics(none); analytics.reportPageView(); page.go(missing); - analytics.reportNotFound(''); + analytics.reportNotFound(); analytics.reportPageView(); - analytics.reportNotFound(''); + analytics.reportNotFound(); page.go('https://docs.acme.com/guides/quickstart'); analytics.reportPageView(); page.go(missing); analytics.reportPageView(); - analytics.reportNotFound(''); + analytics.reportNotFound(); expect(referrers(page.dataLayer())).to.deep.equal([ 'https://docs.acme.com/guides/quickstart', diff --git a/test/portal-template/code-copy.test.ts b/test/portal-template/code-copy.test.ts new file mode 100644 index 00000000..27e579f9 --- /dev/null +++ b/test/portal-template/code-copy.test.ts @@ -0,0 +1,107 @@ +import { expect } from 'chai'; +import { copiedLanguage } from '../../portal-template/src/lib/code-copy'; + +/** As much of an element as the copy reader walks: the selectors it matches, its text, and its place in the tree. */ +class FakeElement { + public parentElement: FakeElement | null = null; + + public constructor( + private readonly selectors: string[], + public readonly textContent: string | null = null, + private readonly children: FakeElement[] = [] + ) { + for (const child of children) child.parentElement = this; + } + + public matches(selector: string): boolean { + return this.selectors.includes(selector); + } + + public closest(selector: string): FakeElement | null { + return this.selectors.includes(selector) ? this : this.parentElement?.closest(selector) ?? null; + } + + public querySelector(selector: string): FakeElement | null { + for (const child of this.children) { + const found = child.selectors.includes(selector) ? child : child.querySelector(selector); + if (found !== null) return found; + } + return null; + } +} + +const element = (fake: FakeElement) => fake as unknown as Parameters[0]; + +/** Fumadocs' code block: a figure with the copy button in its header beside the caption, or in its corner when untitled. */ +function codeBlock(title: string | null) { + const button = new FakeElement(['figure button']); + const caption = title === null ? [] : [new FakeElement(['figcaption'], title)]; + const figure = new FakeElement(['figure'], null, [new FakeElement([], null, [...caption, button])]); + return { figure, button }; +} + +/** A tabbed set of untitled blocks under one root, with `selected` shown: the copy button of the block that is. */ +function tabbedBlocks(names: string[], selected: string): FakeElement { + const tabs = names.map( + (name) => + new FakeElement( + name === selected ? ['[role="tab"]', '[role="tab"][aria-selected="true"]'] : ['[role="tab"]'], + name + ) + ); + const blocks = names.map(() => codeBlock(null)); + const panels = blocks.map(({ figure }) => new FakeElement(['[role="tabpanel"]'], null, [figure])); + new FakeElement([], null, [new FakeElement(['[role="tablist"]'], null, tabs), ...panels]); + return blocks[names.indexOf(selected)].button; +} + +describe('copiedLanguage', () => { + it('reads a titled block’s caption', () => { + expect(copiedLanguage(element(codeBlock('TypeScript').button))).to.equal('TypeScript'); + }); + + it('reads the selected tab’s name for a block in a tabbed set', () => { + expect(copiedLanguage(element(tabbedBlocks(['cURL', 'TypeScript'], 'TypeScript')))).to.equal('TypeScript'); + expect(copiedLanguage(element(tabbedBlocks(['cURL', 'TypeScript'], 'cURL')))).to.equal('cURL'); + }); + + it('prefers the caption of a titled block inside a tabbed set', () => { + const { figure, button } = codeBlock('Terminal'); + const tab = new FakeElement(['[role="tab"]', '[role="tab"][aria-selected="true"]'], 'macOS'); + new FakeElement([], null, [ + new FakeElement(['[role="tablist"]'], null, [tab]), + new FakeElement(['[role="tabpanel"]'], null, [figure]) + ]); + + expect(copiedLanguage(element(button))).to.equal('Terminal'); + }); + + it('is null for a block with neither, for a click outside any block, and for a click with no target', () => { + expect(copiedLanguage(element(codeBlock(null).button))).to.be.null; + expect(copiedLanguage(element(new FakeElement(['button'])))).to.be.null; + expect(copiedLanguage(null)).to.be.null; + }); + + it('is null in a block that reports its own copy', () => { + const own = codeBlock('Terminal'); + // The install command's wrapper marks its block. + new FakeElement(['[data-copy-reported]'], null, [own.figure]); + + expect(copiedLanguage(element(own.button))).to.be.null; + }); + + it('is null for a dropdown in a block’s header, and for anything in the playground’s dialog', () => { + const dropdown = new FakeElement(['figure button', '[role="combobox"]']); + new FakeElement(['figure'], null, [ + new FakeElement([], null, [new FakeElement(['figcaption'], 'Request'), dropdown]) + ]); + const menu = new FakeElement(['figure button', '[aria-haspopup]']); + new FakeElement(['figure'], null, [new FakeElement(['figcaption'], 'JSON'), menu]); + const inDialog = codeBlock('Body'); + new FakeElement(['[role="dialog"]'], null, [inDialog.figure]); + + expect(copiedLanguage(element(dropdown))).to.be.null; + expect(copiedLanguage(element(menu))).to.be.null; + expect(copiedLanguage(element(inDialog.button))).to.be.null; + }); +}); From 2c78cc1aa8dd893bd6c791a1590a8610e43e064d Mon Sep 17 00:00:00 2001 From: Muhammad Sohail Date: Fri, 13 Nov 2026 14:02:20 +0500 Subject: [PATCH 43/73] refactor(portal): move the vendor adapters and the tag loader to vendor-tags.ts analytics.ts held the vendor integration beside the event rules. The adapters, the registry and insertTags() now live in lib/vendor-tags.ts, and analytics.ts keeps the events, the reported address and the instance. An adapter has one script, not a list of one. The registry is keyed by the vendors PortalAnalytics names, so a vendor added there without an adapter no longer compiles. isOAuthCallbackPath() in lib/oauth-callback.ts is the one check of the callback's path, for pageLocation() and the loader, which took the kept query names only to ask it. DataLayerEntry is no longer exported, since nothing imports it. Co-Authored-By: Claude Opus 5.5 --- portal-template/src/lib/analytics.ts | 84 +++-------------------- portal-template/src/lib/oauth-callback.ts | 7 ++ portal-template/src/lib/vendor-tags.ts | 73 ++++++++++++++++++++ test/portal-template/analytics.test.ts | 19 ++--- 4 files changed, 94 insertions(+), 89 deletions(-) create mode 100644 portal-template/src/lib/vendor-tags.ts diff --git a/portal-template/src/lib/analytics.ts b/portal-template/src/lib/analytics.ts index 051a0630..5264a903 100644 --- a/portal-template/src/lib/analytics.ts +++ b/portal-template/src/lib/analytics.ts @@ -1,7 +1,7 @@ import type { FetchResult } from 'fumadocs-openapi/playground'; -import { withBasePath } from './base-path'; -import { oauthCallbackPath } from './oauth-callback'; +import { isOAuthCallbackPath } from './oauth-callback'; import type { PortalAnalytics } from './portal-types'; +import { type Adapter, adapters, insertTags } from './vendor-tags'; /** Query parameters a reported address keeps: campaign, ad-click and cross-domain tags, which attribution reads from the address. */ const KEPT_PREFIXES = ['utm_', 'hsa_']; @@ -40,73 +40,20 @@ export interface PortalEvents { export type PortalEventName = keyof PortalEvents; /** The reset entry, then the event entry with every detail under `docs`. */ -export type DataLayerEntry = - | { docs: null } - | { event: PortalEventName; docs: Readonly> }; - -type Gtag = (...command: unknown[]) => void; +type DataLayerEntry = { docs: null } | { event: PortalEventName; docs: Readonly> }; declare global { interface Window { dataLayer?: unknown[]; - gtag?: Gtag; /** Set by the first start in a page load: a module Vite evaluates again under `portal serve` makes a second instance. */ portalAnalyticsStarted?: true; } } -/** Our code for one vendor. The shared adapter suite runs against each. */ -export interface Adapter { - setup(dataLayer: unknown[]): void; - scripts(): string[]; - /** GTM needs nothing here: it reads the data layer. */ - send(name: PortalEventName, params: Record): void; -} - -type Vendor = 'googleTagManager' | 'googleAnalytics'; -const GOOGLE = 'https://www.googletagmanager.com'; - -/** - * Keyed by every vendor in the union, each building its adapter from the settings, or null with its vendor - * unset: a vendor without an adapter does not compile, and an instance loads whatever the registry builds. - */ -export const adapters: { [V in Vendor]: (settings: PortalAnalytics) => Adapter | null } = { - googleTagManager: ({ googleTagManager: setting }) => { - if (setting === null) return null; - const env = setting.environment; - const environment = env - ? `>m_auth=${encodeURIComponent(env.auth)}>m_preview=${encodeURIComponent(env.preview)}>m_cookies_win=x` - : ''; - return { - setup: (dataLayer) => dataLayer.push({ 'gtm.start': Date.now(), event: 'gtm.js' }), - scripts: () => [`${GOOGLE}/gtm.js?id=${encodeURIComponent(setting.containerId)}${environment}`], - send: () => {} - }; - }, - googleAnalytics: ({ googleAnalytics: setting }) => { - if (setting === null) return null; - let gtag: Gtag; - return { - setup: (dataLayer) => { - // gtag.js reads only Arguments objects from the data layer, never an array of the same values. - gtag = window.gtag ??= function () { - dataLayer.push(arguments); - }; - gtag('js', new Date()); - gtag('config', setting.measurementId, { send_page_view: false }); - }, - scripts: () => [`${GOOGLE}/gtag/js?id=${encodeURIComponent(setting.measurementId)}`], - // GA4 gets its own names: the `docs_` prefix comes off. - send: (name, params) => gtag('event', name.replace(/^docs_/, ''), params) - }; - } -}; - /** The address as reported: no `#` part, no query but the kept tags, and null on the OAuth callback. */ export function pageLocation(href: string, keep: readonly string[], base?: string): string | null { const url = new URL(href); - // A static host may answer `/oauth/callback` at `/oauth/callback/` and keep the query. - if (url.pathname.replace(/\/$/, '') === withBasePath(oauthCallbackPath, base)) return null; + if (isOAuthCallbackPath(url.pathname, base)) return null; url.search = new URLSearchParams( [...url.searchParams].filter( ([name]) => KEPT_PREFIXES.some((prefix) => name.startsWith(prefix)) || KEPT_NAMES.has(name) || keep.includes(name) @@ -116,21 +63,6 @@ export function pageLocation(href: string, keep: readonly string[], base?: strin return url.href; } -/** - * Appends each vendor tag once, and none while the address holds an OAuth answer, which GTM's tags and gtag.js - * read for themselves; a tag already in the page is left, so a page view after the callback adds only the rest. - */ -function insertTags(live: Adapter[], keep: readonly string[]): void { - if (pageLocation(window.location.href, keep) === null) return; - for (const src of live.flatMap((adapter) => adapter.scripts())) { - if (document.head.querySelector(`script[src="${src}"]`) !== null) continue; - const script = document.createElement('script'); - script.async = true; - script.src = src; - document.head.append(script); - } -} - /** The one instance a portal runs: started when the bundle evaluates, reporting from the root effect and the components. */ export class Analytics { private readonly live: Adapter[]; @@ -148,15 +80,15 @@ export class Analytics { /** * Once per page load, when the bundle starts: the data layer, every vendor's setup entries, then the vendor - * tags unless the address holds an OAuth answer, in which case the next page view inserts them. The guard is - * the window's, not the instance's: a config save under `portal serve` makes Vite evaluate the module again. + * tags unless this is the OAuth callback, in which case the next page view inserts them. The guard is the + * window's, not the instance's: a config save under `portal serve` makes Vite evaluate the module again. */ public start(): void { if (window.portalAnalyticsStarted) return; window.portalAnalyticsStarted = true; const dataLayer = (window.dataLayer ??= []); for (const adapter of this.live) adapter.setup(dataLayer); - insertTags(this.live, this.settings.keepQueryParams); + insertTags(this.live); } /** `href` is the page the event belongs to, the current one unless the caller saw the address change first. */ @@ -176,7 +108,7 @@ export class Analytics { const page = pageLocation(window.location.href, this.settings.keepQueryParams); if (page === null) return; // The tags held back on the OAuth callback start here, on the first page after it. - insertTags(this.live, this.settings.keepQueryParams); + insertTags(this.live); if (page === this.lastPageView) return; this.previousPageView = this.lastPageView; this.lastPageView = page; diff --git a/portal-template/src/lib/oauth-callback.ts b/portal-template/src/lib/oauth-callback.ts index cf8cf74d..87b79ee9 100644 --- a/portal-template/src/lib/oauth-callback.ts +++ b/portal-template/src/lib/oauth-callback.ts @@ -1,3 +1,5 @@ +import { withBasePath } from './base-path'; + /** * The one redirect URI a portal owner registers with their OAuth provider, instead of the * address of every endpoint page that can start an authorization. The CLI keeps the user's @@ -5,6 +7,11 @@ */ export const oauthCallbackPath = '/oauth/callback'; +/** Whether a path is the callback's under `base`, Vite's own unless one is given; a static host may add a slash. */ +export function isOAuthCallbackPath(pathname: string, base?: string): boolean { + return pathname.replace(/\/$/, '') === withBasePath(oauthCallbackPath, base); +} + /** Where the playground notes the path of the page that started the flow before it leaves: this tab's session storage. */ const STARTING_PAGE_KEY = 'fumadocs-openapi-oauth'; diff --git a/portal-template/src/lib/vendor-tags.ts b/portal-template/src/lib/vendor-tags.ts new file mode 100644 index 00000000..47ba6210 --- /dev/null +++ b/portal-template/src/lib/vendor-tags.ts @@ -0,0 +1,73 @@ +import type { PortalEventName } from './analytics'; +import { isOAuthCallbackPath } from './oauth-callback'; +import type { PortalAnalytics } from './portal-types'; + +type Gtag = (...command: unknown[]) => void; + +declare global { + interface Window { + gtag?: Gtag; + } +} + +/** Our code for one vendor. The shared adapter suite runs against each. */ +export interface Adapter { + setup(dataLayer: unknown[]): void; + script: string; + /** GTM needs nothing here: it reads the data layer. */ + send(name: PortalEventName, params: Record): void; +} + +type Vendor = Exclude; +const GOOGLE = 'https://www.googletagmanager.com'; + +/** + * Keyed by every vendor `PortalAnalytics` names, each building its adapter from the settings, or null with its vendor + * unset: a vendor without an adapter does not compile, and an instance loads whatever the registry builds. + */ +export const adapters: { [V in Vendor]: (settings: PortalAnalytics) => Adapter | null } = { + googleTagManager: ({ googleTagManager: setting }) => { + if (setting === null) return null; + const env = setting.environment; + const environment = env + ? `>m_auth=${encodeURIComponent(env.auth)}>m_preview=${encodeURIComponent(env.preview)}>m_cookies_win=x` + : ''; + return { + setup: (dataLayer) => dataLayer.push({ 'gtm.start': Date.now(), event: 'gtm.js' }), + script: `${GOOGLE}/gtm.js?id=${encodeURIComponent(setting.containerId)}${environment}`, + send: () => {} + }; + }, + googleAnalytics: ({ googleAnalytics: setting }) => { + if (setting === null) return null; + let gtag: Gtag; + return { + setup: (dataLayer) => { + // gtag.js reads only Arguments objects from the data layer, never an array of the same values. + gtag = window.gtag ??= function () { + dataLayer.push(arguments); + }; + gtag('js', new Date()); + gtag('config', setting.measurementId, { send_page_view: false }); + }, + script: `${GOOGLE}/gtag/js?id=${encodeURIComponent(setting.measurementId)}`, + // GA4 gets its own names: the `docs_` prefix comes off. + send: (name, params) => gtag('event', name.replace(/^docs_/, ''), params) + }; + } +}; + +/** + * Appends each vendor tag once, and none on the OAuth callback, whose address GTM's tags and gtag.js read for + * themselves; a tag already in the page is left, so a page view after the callback adds only the rest. + */ +export function insertTags(live: Adapter[]): void { + if (isOAuthCallbackPath(window.location.pathname)) return; + for (const { script: src } of live) { + if (document.head.querySelector(`script[src="${src}"]`) !== null) continue; + const script = document.createElement('script'); + script.async = true; + script.src = src; + document.head.append(script); + } +} diff --git a/test/portal-template/analytics.test.ts b/test/portal-template/analytics.test.ts index 7262472e..71f208ea 100644 --- a/test/portal-template/analytics.test.ts +++ b/test/portal-template/analytics.test.ts @@ -1,13 +1,7 @@ import { expect } from 'chai'; -import { - Adapter, - adapters, - Analytics, - pageLocation, - PortalEventName, - PortalEvents -} from '../../portal-template/src/lib/analytics'; +import { Analytics, pageLocation, PortalEventName, PortalEvents } from '../../portal-template/src/lib/analytics'; import type { PortalAnalytics } from '../../portal-template/src/lib/portal-types'; +import { Adapter, adapters } from '../../portal-template/src/lib/vendor-tags'; // The list is written out here, not imported: the test is the contract, and a name the module drops fails it. const KEPT_NAMES = [ @@ -127,7 +121,7 @@ interface FakeScript { } interface FakeWindow { - location: { href: string }; + location: URL; dataLayer?: unknown[]; gtag?: (...command: unknown[]) => void; } @@ -135,7 +129,7 @@ interface FakeWindow { /** A page in the browser: the `window` and `document` the module reads, and the scripts the loader appends. */ function browser(href: string, title = 'Quickstart | Acme API', referrer = '') { const scripts: FakeScript[] = []; - const window: FakeWindow = { location: { href } }; + const window: FakeWindow = { location: new URL(href) }; const document = { title, referrer, @@ -471,7 +465,7 @@ describe('Analytics', () => { const named = /record|capture|replay/i; const entries = pushed.map((entry) => (isArguments(entry) ? Array.from(entry as ArrayLike) : entry)); expect(JSON.stringify(entries)).to.not.match(named); - for (const src of adapter().scripts()) expect(src).to.not.match(named); + expect(adapter().script).to.not.match(named); }); it("turns the vendor's own page view off in its setup", () => { @@ -514,8 +508,7 @@ describe('Analytics', () => { }); it('inserts only https scripts, none inline', () => { - expect(adapter().scripts()).to.not.be.empty; - for (const src of adapter().scripts()) expect(src).to.match(/^https:\/\//); + expect(adapter().script).to.match(/^https:\/\//); const page = browser(quickstart); new Analytics(settings).start(); From 9f32c1bb27f043cb33c900623f9680d95d0eef8a Mon Sep 17 00:00:00 2001 From: Muhammad Sohail Date: Fri, 13 Nov 2026 14:02:46 +0500 Subject: [PATCH 44/73] fix(portal): send to GA4 through the page's gtag from any instance The GA4 adapter kept gtag in a variable its setup() filled. A config save under portal serve evaluates the module again, and the second instance's start() returns early, so its adapter never ran setup() and threw "gtag is not a function" on the first report: seen in isolation, not in the browser. send() now calls window.gtag, which the first start defines for the page. Co-Authored-By: Claude Opus 5.5 --- portal-template/src/lib/vendor-tags.ts | 10 +++++----- test/portal-template/analytics.test.ts | 11 +++++++++++ 2 files changed, 16 insertions(+), 5 deletions(-) diff --git a/portal-template/src/lib/vendor-tags.ts b/portal-template/src/lib/vendor-tags.ts index 47ba6210..f5f9692f 100644 --- a/portal-template/src/lib/vendor-tags.ts +++ b/portal-template/src/lib/vendor-tags.ts @@ -40,19 +40,19 @@ export const adapters: { [V in Vendor]: (settings: PortalAnalytics) => Adapter | }, googleAnalytics: ({ googleAnalytics: setting }) => { if (setting === null) return null; - let gtag: Gtag; return { setup: (dataLayer) => { // gtag.js reads only Arguments objects from the data layer, never an array of the same values. - gtag = window.gtag ??= function () { + const gtag = (window.gtag ??= function () { dataLayer.push(arguments); - }; + }); gtag('js', new Date()); gtag('config', setting.measurementId, { send_page_view: false }); }, script: `${GOOGLE}/gtag/js?id=${encodeURIComponent(setting.measurementId)}`, - // GA4 gets its own names: the `docs_` prefix comes off. - send: (name, params) => gtag('event', name.replace(/^docs_/, ''), params) + // The page's gtag, which an instance a config save under `portal serve` makes never sets up; GA4 gets its own + // names, without the `docs_` prefix. + send: (name, params) => window.gtag?.('event', name.replace(/^docs_/, ''), params) }; } }; diff --git a/test/portal-template/analytics.test.ts b/test/portal-template/analytics.test.ts index 71f208ea..56332140 100644 --- a/test/portal-template/analytics.test.ts +++ b/test/portal-template/analytics.test.ts @@ -336,6 +336,17 @@ describe('Analytics', () => { expect(calls.map((command) => command[0])).to.deep.equal(['js', 'config', 'event']); expect(page.dataLayer().filter(isArguments)).to.be.empty; }); + + it("sends through the page's gtag from a second instance, as a config save under portal serve makes", () => { + const page = browser(quickstart); + new Analytics(withGa4).start(); + const second = new Analytics(withGa4); + second.start(); + + second.report('docs_markdown_copy', {}); + + expect(gtagCalls(page.dataLayer()).map((command) => command[0])).to.deep.equal(['js', 'config', 'event']); + }); }); describe('with both vendors', () => { From 382e850987c192ad7fd928464f8be4a42309445a Mon Sep 17 00:00:00 2001 From: Muhammad Sohail Date: Fri, 13 Nov 2026 14:02:46 +0500 Subject: [PATCH 45/73] docs(portal): record the second review of analytics.ts The build plan records what the review moved and why, names the code PR 2 builds on as it now stands, and notes that the loader holds the tags back on /oauth/callback only, not on the starting page the callback returns to with the answer attached. The merge prerequisite's reference to the callback comment follows it to oauth-callback.ts:20. Co-Authored-By: Claude Opus 5.5 --- .ai/plans/portal-analytics.md | 25 ++++++++++++++++++++----- 1 file changed, 20 insertions(+), 5 deletions(-) diff --git a/.ai/plans/portal-analytics.md b/.ai/plans/portal-analytics.md index d4a6528a..925aa17d 100644 --- a/.ai/plans/portal-analytics.md +++ b/.ai/plans/portal-analytics.md @@ -16,7 +16,7 @@ reviewed. Where this file and an issue disagree, the issue wins and this file is |---|---|---| | apimatic/apimatic-io#2347 | the plan: the eight events, the loader, the Decisions table (locked), the risks | starting, and whenever a "why" comes up | | apimatic/apimatic-io#2348 | the build checklist for the three PRs, "Schema, validation and reports" (every rule and every message, verbatim), "Done when" | every step | -| apimatic/apimatic-io#2349 | PR 1 in detail, top-down, with code sketches for every file | every PR 1 step; PR 2 and PR 3 build on its `analyticsFor()` | +| apimatic/apimatic-io#2349 | PR 1 in detail, top-down, with code sketches for every file | every PR 1 step; PR 2 builds on its loader, in the code `Analytics` (`lib/analytics.ts`) and `insertTags()` (`lib/vendor-tags.ts`) | | Plan doc https://claude.ai/artifact/A6rr4cGkbEL3bRCnPGqWzy | the same plan as a document, with the diagram | only to settle a reading of the issues | | Explainer https://claude.ai/artifact/RVbt9jerbNzTFyzGh4eE8t | the plain-language version | never needed for the build | @@ -394,8 +394,9 @@ Commit: `feat(portal): read portal.scripts from apimatic.json`. #### Step 2.2: the loader inserts listed scripts -Delivers: `analyticsFor(settings, scripts)`; `insert()` adds each listed script after the -vendor tags, in order, `async = false`, static files through `withBasePath()`, each attribute +Delivers: `Analytics` takes the listed scripts beside the settings (`new Analytics(portal.analytics, +portal.scripts)` in `lib/portal-analytics.ts`); `insertTags()` in `lib/vendor-tags.ts` adds each +listed script after the vendor tags, in order, `async = false`, static files through `withBasePath()`, each attribute set on the element; a failed one doesn't stop the rest; vendor tags and listed scripts don't wait for each other. @@ -406,7 +407,7 @@ Commit: `feat(portal): load listed scripts through the loader`. #### Step 2.3: `window.apimatic.analytics.subscribe()` -Delivers: set up by `startAnalytics()` before any script is inserted; replays the events so far, +Delivers: set up by `Analytics.start()` before any script is inserted; replays the events so far, then each new one; returns an unsubscribe; each callback in `try`/`catch` with the error rethrown through `setTimeout`; one `window.apimatic` object. @@ -561,7 +562,21 @@ callback guard has a direct test. Still open, and now the one merge prerequisite query and `#` part onto the starting page; 12.6.2's `getReturnedFlow()` reads `sessionStorage` under `fumadocs-openapi-oauth-returned` and falls back to the address, while 12.6.0 reads the address only, so the callback change (store `location.href` under that key, return the bare page, follow in -`oauth-callback.test.ts` and the comment at `oauth-callback.ts:13`) lands with the bump, from 2026-11-19. +`oauth-callback.test.ts` and the comment at `oauth-callback.ts:20`) lands with the bump, from 2026-11-19. + +**Second review of 2026-11-13** (`lib/analytics.ts`, for encapsulation it does not need and infrastructure +mixed in), taken the same day. The class keeps what every event shares: `start()`, `report()`, the page-view +and not-found history, and the playground's request timing. Reading Fumadocs' code-block markup moved to +`copiedLanguage()` in `lib/code-copy.ts`, which the root's click listener reports through `report()`; +`search.tsx` alone decides whether a search counts, and reports through `report()`; `reportNotFound()` reads +`document.referrer` itself, as `reportPageView()` reads the title. The vendor adapters and the tag loader moved +to `lib/vendor-tags.ts`: an adapter has one `script`; the registry is keyed by the vendors `PortalAnalytics` +names, so a vendor added there without an adapter does not compile; GA4's `send()` calls the page's `gtag`, +since an instance a config save makes never runs its setup (in isolation it threw `gtag is not a function`; a +config save in the browser did not show it). `isOAuthCallbackPath()` in `lib/oauth-callback.ts` is the one +check of the callback's path, for `pageLocation()` and the loader. Found on the way: the loader holds the tags +back on `/oauth/callback` only, not on the starting page the callback returns to with the answer attached, so +until the merge prerequisite above lands the tags load there with the answer in the address. ## 5. Questions each step will raise From 2a4f79cd77eb5cf4b2f00f1a19154408cc5baac3 Mon Sep 17 00:00:00 2001 From: Muhammad Sohail Date: Fri, 13 Nov 2026 15:33:36 +0500 Subject: [PATCH 46/73] test(portal): expect the cURL sample marked beside the playground header Since the cURL sample carries the replay markers too, the operation page has two elements with data-portal-playground: the playground's header and the sample. The test still expected one, so every CI job failed. Co-Authored-By: Claude Opus 5.5 --- test/e2e/portal-build.test.ts | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-) diff --git a/test/e2e/portal-build.test.ts b/test/e2e/portal-build.test.ts index 03edae95..6f5da2a4 100644 --- a/test/e2e/portal-build.test.ts +++ b/test/e2e/portal-build.test.ts @@ -291,13 +291,15 @@ const stylesheetOf = (output: DirectoryPath) => { } }); - it('prerenders the operation page’s playground header inside the element session replays skip', () => { - const parts = read('api/apimatic-calculator/simple-calculator/Calculate/index.html').split( - 'data-portal-playground' - ); - expect(parts, 'one element').to.have.length(2); + it('prerenders the playground header and the cURL sample beside it inside the elements session replays skip', () => { + const marked = read('api/apimatic-calculator/simple-calculator/Calculate/index.html') + .split('data-portal-playground') + .slice(1); + expect(marked, 'the header and the sample').to.have.length(2); // What Fumadocs' playground renders on the server: its header, with the method, the route and the trigger. - expect(parts[1].slice(0, 2000)).to.match(/>GET<[\s\S]*\{operation\}[\s\S]*aria-haspopup="dialog"/); + expect(marked[0].slice(0, 2000)).to.match(/>GET<[\s\S]*\{operation\}[\s\S]*aria-haspopup="dialog"/); + // The sample follows what the reader types into the playground, the credentials among it. + expect(marked[1]).to.match(/>curl<[\s\S]*> -X<[\s\S]*> GET { From 09a22ba3b02372ce0bde71b96e70e21d1639934a Mon Sep 17 00:00:00 2001 From: Muhammad Sohail Date: Fri, 13 Nov 2026 17:34:43 +0500 Subject: [PATCH 47/73] refactor(portal): define --no-analytics once, saying what it leaves out The flag moves to FlagsProvider, and its help names the two Google tags it drops rather than every analytics or marketing script, which a later release adds; 'for staging' goes, since the docs advise it for previews. Co-Authored-By: Claude Opus 5.5 --- README.md | 6 ++---- src/commands/portal/generate.ts | 6 +----- src/commands/portal/serve.ts | 6 +----- src/types/flags-provider.ts | 7 +++++++ 4 files changed, 11 insertions(+), 14 deletions(-) diff --git a/README.md b/README.md index ad9a97cf..8ee8c6b4 100644 --- a/README.md +++ b/README.md @@ -306,8 +306,7 @@ FLAGS -i, --input= [default: ./] path to the parent directory containing the 'src' directory, which includes API specifications and configuration files. -k, --auth-key= override current authentication state with an authentication key. - --no-analytics leave out Google Tag Manager, Google Analytics and every analytics or marketing script, for - staging. + --no-analytics leave out the Google Tag Manager and Google Analytics tags set in 'portal.analytics'. --zip write the generated portal as a .zip archive. DESCRIPTION @@ -348,8 +347,7 @@ FLAGS -k, --auth-key= override current authentication state with an authentication key. -o, --open open the portal in the default browser. -p, --port=23513 [default: 23513] port to serve the portal on. - --no-analytics leave out Google Tag Manager, Google Analytics and every analytics or marketing script, for - staging. + --no-analytics leave out the Google Tag Manager and Google Analytics tags set in 'portal.analytics'. DESCRIPTION Preview your API Documentation Portal with live reload. diff --git a/src/commands/portal/generate.ts b/src/commands/portal/generate.ts index d94b8ef5..627e78af 100644 --- a/src/commands/portal/generate.ts +++ b/src/commands/portal/generate.ts @@ -28,11 +28,7 @@ The portal is built on your machine and written as static files for any static h default: false, description: 'write the generated portal as a .zip archive.' }), - 'no-analytics': Flags.boolean({ - default: false, - description: - 'leave out Google Tag Manager, Google Analytics and every analytics or marketing script, for staging.' - }), + ...FlagsProvider.noAnalytics, ...FlagsProvider.input, ...FlagsProvider.destination('portal', 'portal'), ...FlagsProvider.force, diff --git a/src/commands/portal/serve.ts b/src/commands/portal/serve.ts index 67995ca0..34a94724 100644 --- a/src/commands/portal/serve.ts +++ b/src/commands/portal/serve.ts @@ -36,11 +36,7 @@ Nothing is written to disk; run 'apimatic portal generate' to produce the static description: 'open the portal in the default browser.', default: false }), - 'no-analytics': Flags.boolean({ - default: false, - description: - 'leave out Google Tag Manager, Google Analytics and every analytics or marketing script, for staging.' - }), + ...FlagsProvider.noAnalytics, ...FlagsProvider.input, ...FlagsProvider.authKey }; diff --git a/src/types/flags-provider.ts b/src/types/flags-provider.ts index 44f7a516..899b955c 100644 --- a/src/types/flags-provider.ts +++ b/src/types/flags-provider.ts @@ -33,6 +33,13 @@ export class FlagsProvider { }; } + public static readonly noAnalytics = { + 'no-analytics': Flags.boolean({ + default: false, + description: "leave out the Google Tag Manager and Google Analytics tags set in 'portal.analytics'." + }) + }; + // Auth key group public static authKey = { 'auth-key': Flags.string({ From 18b9a3bfa171f98a13f77263c3debdb3b5f65a5e Mon Sep 17 00:00:00 2001 From: Muhammad Sohail Date: Fri, 13 Nov 2026 17:34:43 +0500 Subject: [PATCH 48/73] refactor(portal): apply --no-analytics where the settings are read PortalSourceContext.resolve() and resolveSettings() take the run's PortalBuildOptions and drop the vendors in the one place both read the config, so the prepare action and serve's config watch no longer apply it apart. The actions take it as an options object instead of a third positional boolean. Co-Authored-By: Claude Opus 5.5 --- src/actions/portal/generate.ts | 5 ++-- src/actions/portal/prepare-project.ts | 11 ++++---- src/actions/portal/serve.ts | 17 +++++------- src/actions/quickstart.ts | 6 ++--- src/commands/portal/generate.ts | 4 ++- src/commands/portal/serve.ts | 2 +- src/types/portal-source-context.ts | 19 ++++++++----- src/types/portal/portal-source.ts | 7 ++--- test/actions/portal/generate.test.ts | 28 +++++++++----------- test/actions/portal/prepare-project-stubs.ts | 16 +++++++++++ test/actions/portal/prepare-project.test.ts | 23 +++++++++------- test/actions/portal/serve.test.ts | 8 +++--- test/types/portal-source-context.test.ts | 24 +++++++++++++++++ 13 files changed, 107 insertions(+), 63 deletions(-) diff --git a/src/actions/portal/generate.ts b/src/actions/portal/generate.ts index 1daf9ced..21dbe214 100644 --- a/src/actions/portal/generate.ts +++ b/src/actions/portal/generate.ts @@ -5,6 +5,7 @@ import { CommandMetadata } from '../../types/common/command-metadata.js'; import { DirectoryPath } from '../../types/file/directoryPath.js'; import { PortalContext } from '../../types/portal-context.js'; import { SiteAddress } from '../../types/portal/config/site-address.js'; +import { PortalBuildOptions } from '../../types/portal/portal-source.js'; import { ProjectContext } from '../../types/project-context.js'; import { ActionResult } from '../action-result.js'; import { PreparePortalProjectAction } from './prepare-project.js'; @@ -27,7 +28,7 @@ export class GenerateAction { portalDirectory: DirectoryPath, force: boolean, zipPortal: boolean, - enableAnalytics: boolean + build: PortalBuildOptions ): Promise => { if (project.isSourceDirectory(portalDirectory)) { this.prompts.directoryCannotBeSame(portalDirectory); @@ -43,7 +44,7 @@ export class GenerateAction { const portalContext = new PortalContext(portalDirectory); const prepare = new PreparePortalProjectAction(this.configDir, this.commandMetadata, this.authKey); - return await prepare.execute(project, enableAnalytics, { + return await prepare.execute(project, build, { confirm: () => this.confirmOverwrite(portalContext, portalDirectory, force), onPrepared: (portalProject, source) => { if (source.config.usesGoogleAnalytics()) { diff --git a/src/actions/portal/prepare-project.ts b/src/actions/portal/prepare-project.ts index 844f90e2..15c6e988 100644 --- a/src/actions/portal/prepare-project.ts +++ b/src/actions/portal/prepare-project.ts @@ -6,7 +6,7 @@ import { PreparePortalProjectPrompts } from '../../prompts/portal/prepare-projec import { CommandMetadata } from '../../types/common/command-metadata.js'; import { DirectoryPath } from '../../types/file/directoryPath.js'; import { PortalArtifacts } from '../../types/portal/portal-artifacts.js'; -import { PortalSource, settingsForBuild } from '../../types/portal/portal-source.js'; +import { PortalBuildOptions, PortalSource } from '../../types/portal/portal-source.js'; import { ProjectContext } from '../../types/project-context.js'; import { ActionResult } from '../action-result.js'; @@ -36,7 +36,7 @@ export class PreparePortalProjectAction { /** Takes the caller's next step rather than returning, because its temporary directories must outlive this call. */ public readonly execute = async ( project: ProjectContext, - enableAnalytics: boolean, + build: PortalBuildOptions, { confirm = async () => true, onPrepared }: PreparationSteps ): Promise => { const sourceDirectory = project.sourceDirectory(); @@ -64,7 +64,7 @@ export class PreparePortalProjectAction { } // Ahead of the server run, which can take minutes: a mistake or a question should not wait on it. - const source = await project.portalSource().resolve(); + const source = await project.portalSource().resolve(build); if (source.isErr()) { this.prompts.sourceProblem(source.error, sourceDirectory); return ActionResult.failed(); @@ -111,14 +111,13 @@ export class PreparePortalProjectAction { } return await withDirPath(async (tempDirectory) => { - const sourceForBuild = settingsForBuild(source.value, enableAnalytics); - const portalProject = await this.projectService.prepare(tempDirectory, sourceForBuild, artifacts.value); + const portalProject = await this.projectService.prepare(tempDirectory, source.value, artifacts.value); if (portalProject.isErr()) { this.prompts.runtimeUnsupported(portalProject.error); return ActionResult.failed(); } - return await onPrepared(portalProject.value, sourceForBuild, artifacts.value); + return await onPrepared(portalProject.value, source.value, artifacts.value); }); }); }; diff --git a/src/actions/portal/serve.ts b/src/actions/portal/serve.ts index 8ab0dc4f..8c644e9a 100644 --- a/src/actions/portal/serve.ts +++ b/src/actions/portal/serve.ts @@ -9,7 +9,7 @@ import { ProjectContext } from '../../types/project-context.js'; import { isSkippedByGlob } from '../../types/portal/content-tree.js'; import { GeneratedPages } from '../../types/portal/generated-pages.js'; import { PortalArtifacts } from '../../types/portal/portal-artifacts.js'; -import { PortalSettings, PortalSource, settingsForBuild, WatchedSource } from '../../types/portal/portal-source.js'; +import { PortalBuildOptions, PortalSettings, PortalSource, WatchedSource } from '../../types/portal/portal-source.js'; import { PreviewConfig } from '../../types/portal/preview-config.js'; import { PreviewContent } from '../../types/portal/preview-content.js'; import { PreviewSpecs } from '../../types/portal/preview-specs.js'; @@ -45,11 +45,11 @@ export class PortalServeAction { project: ProjectContext, port: number, openInBrowser: boolean, - enableAnalytics: boolean, + build: PortalBuildOptions, onServing?: () => void ): Promise => { const prepare = new PreparePortalProjectAction(this.configDir, this.commandMetadata, this.authKey); - return await prepare.execute(project, enableAnalytics, { + return await prepare.execute(project, build, { onPrepared: async (portalProject, source, artifacts) => { const servePort = await this.networkService.getServerPort([port, 3000, 3001, 3002]); if (servePort !== port) { @@ -80,7 +80,7 @@ export class PortalServeAction { source, artifacts, portalProject.projectDirectory, - enableAnalytics, + build, (settings) => { const sectionsChanged = !settings.generatedPages.makesSameSectionsAs(generatedPages); generatedPages = settings.generatedPages; @@ -131,7 +131,7 @@ export class PortalServeAction { source: PortalSource, artifacts: PortalArtifacts, portalProjectDirectory: DirectoryPath, - enableAnalytics: boolean, + build: PortalBuildOptions, onApplied: (settings: PortalSettings) => void ): FileWatch | undefined { const sourceDirectory = project.sourceDirectory(); @@ -139,7 +139,7 @@ export class PortalServeAction { const preview = new PreviewConfig(source.config, source.staticDirectory !== null); const applyEdit = async () => { - const reloaded = await sourceContext.resolveSettings(source.suggestedSite); + const reloaded = await sourceContext.resolveSettings(source.suggestedSite, build); if (reloaded.isErr()) { preview.refuse(); this.prompts.configRejected(reloaded.error, sourceDirectory); @@ -159,10 +159,7 @@ export class PortalServeAction { this.prompts.staticDirectoryNotServed(sourceDirectory); } - const applied = await this.projectService.applyConfig( - portalProjectDirectory, - settingsForBuild(settings, enableAnalytics) - ); + const applied = await this.projectService.applyConfig(portalProjectDirectory, settings); if (applied.isErr()) { this.prompts.notApplied('config', applied.error, sourceDirectory); return; diff --git a/src/actions/quickstart.ts b/src/actions/quickstart.ts index 24cb7b56..7b7b2069 100644 --- a/src/actions/quickstart.ts +++ b/src/actions/quickstart.ts @@ -240,13 +240,11 @@ export class QuickstartAction { const structure = await this.fileService.getDirectory(project.sourceDirectory()); this.prompts.printDirectoryStructure(projectDirectory, structure); - const openInBrowser = true; - const enableAnalytics = true; const result = await new PortalServeAction(this.configDir, this.commandMetadata, null).execute( project, DEFAULT_PORTAL_PORT, - openInBrowser, - enableAnalytics, + true, + { analytics: true }, () => this.prompts.nextSteps(configFile) ); diff --git a/src/commands/portal/generate.ts b/src/commands/portal/generate.ts index 627e78af..87ba963e 100644 --- a/src/commands/portal/generate.ts +++ b/src/commands/portal/generate.ts @@ -48,7 +48,9 @@ The portal is built on your machine and written as static files for any static h intro('Generate Portal'); const action = new GenerateAction(this.getConfigDir(), commandMetadata, authKey); - const result = await action.execute(project, project.portalDirectory(destination), force, zipPortal, !noAnalytics); + const result = await action.execute(project, project.portalDirectory(destination), force, zipPortal, { + analytics: !noAnalytics + }); outro(result); } diff --git a/src/commands/portal/serve.ts b/src/commands/portal/serve.ts index 34a94724..e13b4bf7 100644 --- a/src/commands/portal/serve.ts +++ b/src/commands/portal/serve.ts @@ -53,7 +53,7 @@ Nothing is written to disk; run 'apimatic portal generate' to produce the static intro('Portal Serve'); const action = new PortalServeAction(this.getConfigDir(), commandMetadata, authKey); - const result = await action.execute(ProjectContext.at(input), port, open, !noAnalytics); + const result = await action.execute(ProjectContext.at(input), port, open, { analytics: !noAnalytics }); outro(result); } diff --git a/src/types/portal-source-context.ts b/src/types/portal-source-context.ts index f81e4e27..38a913de 100644 --- a/src/types/portal-source-context.ts +++ b/src/types/portal-source-context.ts @@ -30,6 +30,7 @@ import { MissingFile, MissingImage, MissingStaticFile, + PortalBuildOptions, PortalScaffoldProblem, PortalSettings, PortalSource, @@ -135,7 +136,9 @@ export class PortalSourceContext { } /** Reads and validates the whole source directory, or reports the first problem found. */ - public async resolve(): Promise> { + public async resolve( + build: PortalBuildOptions = { analytics: true } + ): Promise> { const document = await this.readConfigDocument(); if (document.isErr()) { return err(document.error); @@ -149,7 +152,7 @@ export class PortalSourceContext { } const { specs, suggestedSite, unmergedSpecs, leftOutSpecs } = discovered.value; - const settings = await this.settingsFrom(document.value, suggestedSite); + const settings = await this.settingsFrom(document.value, suggestedSite, build); if (settings.isErr()) { return err(settings.error); } @@ -279,17 +282,21 @@ export class PortalSourceContext { * is accepted exactly when a build would accept it. `suggested` is what `resolve` found in the * specifications, which are not read again; changing them needs a restart anyway. */ - public async resolveSettings(suggested: SuggestedSite | null): Promise> { + public async resolveSettings( + suggested: SuggestedSite | null, + build: PortalBuildOptions = { analytics: true } + ): Promise> { const document = await this.readConfigDocument(); if (document.isErr()) { return err(document.error); } - return this.settingsFrom(document.value, suggested); + return this.settingsFrom(document.value, suggested, build); } private async settingsFrom( document: ApimaticConfigDocument, - suggested: SuggestedSite | null + suggested: SuggestedSite | null, + build: PortalBuildOptions ): Promise> { const settings = PortalSourceContext.parseSettings(document, suggested); if (settings.isErr()) { @@ -301,7 +308,7 @@ export class PortalSourceContext { if (missingFiles.length > 0) { return err({ kind: 'missingStaticFiles', files: missingFiles }); } - return ok(settings.value); + return ok(build.analytics ? settings.value : { ...settings.value, config: settings.value.config.withoutVendors() }); } private async readConfigDocument(): Promise> { diff --git a/src/types/portal/portal-source.ts b/src/types/portal/portal-source.ts index 6468540d..c5adac07 100644 --- a/src/types/portal/portal-source.ts +++ b/src/types/portal/portal-source.ts @@ -47,9 +47,10 @@ export interface PortalSource extends PortalSettings { contentNotices: ContentNotices; } -/** The settings a portal is built from: under `--no-analytics`, neither vendor tag. */ -export function settingsForBuild(settings: T, enableAnalytics: boolean): T { - return enableAnalytics ? settings : { ...settings, config: settings.config.withoutVendors() }; +/** What a run's flags change in the portal it builds from the source. */ +export interface PortalBuildOptions { + /** False under `--no-analytics`: the portal loads neither vendor tag. */ + analytics: boolean; } /** Why a source directory could not be written; each variant maps to its own message. */ diff --git a/test/actions/portal/generate.test.ts b/test/actions/portal/generate.test.ts index e3383842..1232b09f 100644 --- a/test/actions/portal/generate.test.ts +++ b/test/actions/portal/generate.test.ts @@ -15,7 +15,7 @@ import { ServiceError } from '../../../src/infrastructure/service-error'; import { DirectoryPath } from '../../../src/types/file/directoryPath'; import { CommandMetadata } from '../../../src/types/common/command-metadata'; import { ProjectContext } from '../../../src/types/project-context'; -import { completeArtifacts, stubPreparePortalProject } from './prepare-project-stubs'; +import { completeArtifacts, fixtureWithAnalytics, stubPreparePortalProject } from './prepare-project-stubs'; const COMMAND_METADATA: CommandMetadata = { commandName: 'portal generate', shell: 'test' }; const FIXTURE = new DirectoryPath(process.cwd()).join('test/resources/portal-inputs/default'); @@ -38,13 +38,13 @@ describe('GenerateAction', () => { let authorize: sinon.SinonStub; let build: sinon.SinonStub; - const execute = (projectDirectory = FIXTURE, force = false, zip = false, enableAnalytics = true) => + const execute = (projectDirectory = FIXTURE, force = false, zip = false, analytics = true) => new GenerateAction(new DirectoryPath(root), COMMAND_METADATA, 'auth-key').execute( ProjectContext.in(projectDirectory), portalDirectory, force, zip, - enableAnalytics + { analytics } ); const inPortal = (relative: string) => fs.existsSync(path.join(portalDirectory.toString(), relative)); @@ -120,7 +120,9 @@ describe('GenerateAction', () => { it('fails when the source and destination are the same directory', async () => { const action = new GenerateAction(new DirectoryPath(root), COMMAND_METADATA); - const result = await action.execute(ProjectContext.in(FIXTURE), FIXTURE.join('src'), false, false, true); + const result = await action.execute(ProjectContext.in(FIXTURE), FIXTURE.join('src'), false, false, { + analytics: true + }); expect(result.isFailed()).to.be.true; expect(prompts.directoryCannotBeSame.calledOnce).to.be.true; @@ -319,12 +321,9 @@ describe('GenerateAction', () => { }); it('warns that Google Analytics counts page changes, before the build, when it is set', async () => { - const project = new DirectoryPath(root).join('analytics'); - fs.cpSync(FIXTURE.toString(), project.toString(), { recursive: true }); - const configFile = path.join(project.toString(), 'src', 'apimatic.json'); - const edited = JSON.parse(fs.readFileSync(configFile, 'utf8')); - edited.portal.analytics = { googleAnalytics: { measurementId: 'G-ABC123' } }; - fs.writeFileSync(configFile, JSON.stringify(edited)); + const project = fixtureWithAnalytics(FIXTURE, new DirectoryPath(root).join('analytics'), { + googleAnalytics: { measurementId: 'G-ABC123' } + }); const result = await execute(project); @@ -335,12 +334,9 @@ describe('GenerateAction', () => { }); it('does not warn about Google Analytics under --no-analytics, which prepares the project without it', async () => { - const project = new DirectoryPath(root).join('staging'); - fs.cpSync(FIXTURE.toString(), project.toString(), { recursive: true }); - const configFile = path.join(project.toString(), 'src', 'apimatic.json'); - const edited = JSON.parse(fs.readFileSync(configFile, 'utf8')); - edited.portal.analytics = { googleAnalytics: { measurementId: 'G-ABC123' } }; - fs.writeFileSync(configFile, JSON.stringify(edited)); + const project = fixtureWithAnalytics(FIXTURE, new DirectoryPath(root).join('staging'), { + googleAnalytics: { measurementId: 'G-ABC123' } + }); const result = await execute(project, false, false, false); diff --git a/test/actions/portal/prepare-project-stubs.ts b/test/actions/portal/prepare-project-stubs.ts index 5357b97e..28f6909f 100644 --- a/test/actions/portal/prepare-project-stubs.ts +++ b/test/actions/portal/prepare-project-stubs.ts @@ -1,3 +1,5 @@ +import fs from 'fs'; +import path from 'path'; import { ok } from 'neverthrow'; import sinon from 'sinon'; import { PortalProjectService } from '../../../src/infrastructure/portal-project-service'; @@ -34,6 +36,20 @@ export function completeArtifacts( ); } +/** A copy of `fixture` at `directory`, its `portal.analytics` set to `analytics`. */ +export function fixtureWithAnalytics( + fixture: DirectoryPath, + directory: DirectoryPath, + analytics: object +): DirectoryPath { + fs.cpSync(fixture.toString(), directory.toString(), { recursive: true }); + const configFile = path.join(directory.toString(), 'src', 'apimatic.json'); + const config = JSON.parse(fs.readFileSync(configFile, 'utf8')); + config.portal.analytics = analytics; + fs.writeFileSync(configFile, JSON.stringify(config)); + return directory; +} + /** * What `PreparePortalProjectAction` reaches for, stubbed the same way for both commands that run * it. A test that cares about one of these overrides it afterwards; the defaults are the happy path. diff --git a/test/actions/portal/prepare-project.test.ts b/test/actions/portal/prepare-project.test.ts index f8bed4c0..212afab7 100644 --- a/test/actions/portal/prepare-project.test.ts +++ b/test/actions/portal/prepare-project.test.ts @@ -14,7 +14,12 @@ import { FilePath } from '../../../src/types/file/filePath'; import { CommandMetadata } from '../../../src/types/common/command-metadata'; import { ProjectContext } from '../../../src/types/project-context'; import { TempContext } from '../../../src/types/temp-context'; -import { completeArtifacts, PreparePortalProjectStubs, stubPreparePortalProject } from './prepare-project-stubs'; +import { + completeArtifacts, + fixtureWithAnalytics, + PreparePortalProjectStubs, + stubPreparePortalProject +} from './prepare-project-stubs'; const COMMAND_METADATA: CommandMetadata = { commandName: 'portal generate', shell: 'test' }; @@ -33,7 +38,7 @@ describe('PreparePortalProjectAction', () => { const result = await new PreparePortalProjectAction(new DirectoryPath(os.tmpdir()), COMMAND_METADATA).execute( ProjectContext.in(share), - true, + { analytics: true }, { onPrepared } ); @@ -48,10 +53,10 @@ describe('PreparePortalProjectAction', () => { let shared: PreparePortalProjectStubs; let onPrepared: sinon.SinonStub; - const execute = (enableAnalytics = true, project = FIXTURE) => + const execute = (analytics = true, project = FIXTURE) => new PreparePortalProjectAction(new DirectoryPath(os.tmpdir()), COMMAND_METADATA).execute( ProjectContext.in(project), - enableAnalytics, + { analytics }, { onPrepared } ); @@ -78,13 +83,11 @@ describe('PreparePortalProjectAction', () => { it('prepares the project, and hands on the source, with neither vendor tag under --no-analytics', async () => { const root = fs.mkdtempSync(path.join(os.tmpdir(), 'portal-prepare-')); try { - fs.cpSync(FIXTURE.toString(), root, { recursive: true }); - const configFile = path.join(root, 'src', 'apimatic.json'); - const edited = JSON.parse(fs.readFileSync(configFile, 'utf8')); - edited.portal.analytics = { googleTagManager: { containerId: 'GTM-ABC123' } }; - fs.writeFileSync(configFile, JSON.stringify(edited)); + const project = fixtureWithAnalytics(FIXTURE, new DirectoryPath(root), { + googleTagManager: { containerId: 'GTM-ABC123' } + }); - await execute(false, new DirectoryPath(root)); + await execute(false, project); expect(shared.prepare.firstCall.args[1].config.identity().analytics.googleTagManager).to.be.null; expect(onPrepared.firstCall.args[1].config.identity().analytics.googleTagManager).to.be.null; diff --git a/test/actions/portal/serve.test.ts b/test/actions/portal/serve.test.ts index 6d7f0197..1d381ae3 100644 --- a/test/actions/portal/serve.test.ts +++ b/test/actions/portal/serve.test.ts @@ -45,12 +45,12 @@ describe('PortalServeAction', () => { /** Stands in for the preview process dying, with what it printed on the way out. */ let exit: (output: string) => void; - const execute = (projectDirectory = FIXTURE, openInBrowser = false, enableAnalytics = true) => + const execute = (projectDirectory = FIXTURE, openInBrowser = false, analytics = true) => new PortalServeAction(new DirectoryPath(root), COMMAND_METADATA, 'auth-key').execute( ProjectContext.in(projectDirectory), PORT, openInBrowser, - enableAnalytics + { analytics } ); /** Stands in for the watch on `directory`, answered by `watching`; any other tree's watch is left alone. */ @@ -609,8 +609,8 @@ describe('PortalServeAction', () => { fs.writeFileSync(path.join(source.toString(), 'apimatic.json'), JSON.stringify(config)); /** Runs the preview until `body` is done with it, then stops it as CTRL+C would. */ - const whileServing = async (body: () => Promise, enableAnalytics = true) => { - const running = execute(new DirectoryPath(root), false, enableAnalytics); + const whileServing = async (body: () => Promise, analytics = true) => { + const running = execute(new DirectoryPath(root), false, analytics); const { onChange } = await watched; save = async (config: object) => { writeConfig(config); diff --git a/test/types/portal-source-context.test.ts b/test/types/portal-source-context.test.ts index 27d6e499..120d4e9b 100644 --- a/test/types/portal-source-context.test.ts +++ b/test/types/portal-source-context.test.ts @@ -376,6 +376,30 @@ describe('PortalSourceContext', () => { ]); }); + it('leaves out the vendor tags under --no-analytics, as resolve does, and keeps the query names to keep', async () => { + writeConfig({ + site: { name: 'Calc' }, + analytics: { googleTagManager: { containerId: 'GTM-ABC123' }, keepQueryParams: ['campaign_id'] } + }); + const off = { analytics: false }; + + const resolved = (await new PortalSourceContext(new DirectoryPath(root)).resolve(off))._unsafeUnwrap(); + const reloaded = (await context().resolveSettings(null, off))._unsafeUnwrap(); + const kept = (await context().resolveSettings(null))._unsafeUnwrap(); + + for (const { config } of [resolved, reloaded]) { + expect(config.identity().analytics).to.deep.equal({ + googleTagManager: null, + googleAnalytics: null, + keepQueryParams: ['campaign_id'] + }); + } + expect(kept.config.identity().analytics.googleTagManager).to.deep.equal({ + containerId: 'GTM-ABC123', + environment: null + }); + }); + it('reports a file removed while the preview runs', async () => { expect((await context().resolveSettings(null))._unsafeUnwrapErr()).to.deep.equal({ kind: 'missingConfig' }); }); From 9635ebbf360cddb309b62bd2dcf1f25dac52f1c4 Mon Sep 17 00:00:00 2001 From: Muhammad Sohail Date: Fri, 13 Nov 2026 17:34:44 +0500 Subject: [PATCH 49/73] fix(portal): warn about GA4's page changes on portal serve too The warning moves to the prepare step both commands share, so serve, which loads GA4 as well, prints it. The schema gives the advice once, on the measurement ID. Co-Authored-By: Claude Opus 5.5 --- apimatic.schema.json | 2 +- src/actions/portal/generate.ts | 8 +--- src/actions/portal/prepare-project.ts | 3 ++ src/prompts/portal/generate.ts | 10 ----- src/prompts/portal/prepare-project.ts | 10 +++++ src/types/portal/config/analytics-config.ts | 2 +- src/types/portal/portal-config.ts | 2 +- test/actions/portal/generate.test.ts | 34 +---------------- test/actions/portal/prepare-project.test.ts | 42 ++++++++++++++++----- test/prompts/portal/generate.test.ts | 19 ---------- test/prompts/portal/prepare-project.test.ts | 13 +++++++ 11 files changed, 65 insertions(+), 80 deletions(-) diff --git a/apimatic.schema.json b/apimatic.schema.json index b09edfe4..f0982f69 100644 --- a/apimatic.schema.json +++ b/apimatic.schema.json @@ -179,7 +179,7 @@ }, "analytics": { "type": "object", - "description": "Analytics the portal loads. Every page view goes to window.dataLayer as docs_page_view, and to GA4 when a measurement ID is set. The portal counts page changes itself: with googleAnalytics set, turn off the GA4 stream's 'Page changes based on browser history events', or every page change counts twice.", + "description": "Analytics the portal loads. Every page view goes to window.dataLayer as docs_page_view, and to GA4 when a measurement ID is set.", "additionalProperties": false, "properties": { "googleTagManager": { diff --git a/src/actions/portal/generate.ts b/src/actions/portal/generate.ts index 21dbe214..ac126945 100644 --- a/src/actions/portal/generate.ts +++ b/src/actions/portal/generate.ts @@ -46,12 +46,8 @@ export class GenerateAction { const prepare = new PreparePortalProjectAction(this.configDir, this.commandMetadata, this.authKey); return await prepare.execute(project, build, { confirm: () => this.confirmOverwrite(portalContext, portalDirectory, force), - onPrepared: (portalProject, source) => { - if (source.config.usesGoogleAnalytics()) { - this.prompts.googleAnalyticsCountsPageChanges(); - } - return this.build(portalProject, source.config.siteAddress(), portalContext, portalDirectory, zipPortal); - } + onPrepared: (portalProject, source) => + this.build(portalProject, source.config.siteAddress(), portalContext, portalDirectory, zipPortal) }); }; diff --git a/src/actions/portal/prepare-project.ts b/src/actions/portal/prepare-project.ts index 15c6e988..415d5bc9 100644 --- a/src/actions/portal/prepare-project.ts +++ b/src/actions/portal/prepare-project.ts @@ -73,6 +73,9 @@ export class PreparePortalProjectAction { this.prompts.contentNotices(source.value.contentNotices, sourceDirectory); this.prompts.unmergedSpecs(source.value.unmergedSpecs, sourceDirectory); this.prompts.leftOutSpecs(source.value.leftOutSpecs, sourceDirectory); + if (source.value.config.usesGoogleAnalytics()) { + this.prompts.googleAnalyticsCountsPageChanges(); + } if (!(await confirm())) { return ActionResult.cancelled(); diff --git a/src/prompts/portal/generate.ts b/src/prompts/portal/generate.ts index 6e1544a7..cd8903f9 100644 --- a/src/prompts/portal/generate.ts +++ b/src/prompts/portal/generate.ts @@ -55,16 +55,6 @@ export class PortalGeneratePrompts { log.error(message); } - /** The portal reports its own page views, so a GA4 stream that also counts history changes counts each page twice. */ - public googleAnalyticsCountsPageChanges() { - const message = - `Google Analytics is set, so the portal sends its own page views. In GA4, turn off the stream's ` + - `"Page changes based on browser history events" (Admin → Data streams → your stream → Enhanced ` + - `measurement → Page views → advanced settings), or every page change counts twice. ` + - `See the analytics page on ${f.link('https://docs.apimatic.io/v4/')}.`; - log.warn(message); - } - /** * A portal build runs for tens of seconds with no output of its own, so the spinner * carries an elapsed timer rather than a static message. diff --git a/src/prompts/portal/prepare-project.ts b/src/prompts/portal/prepare-project.ts index cf50a4be..24ce0f2e 100644 --- a/src/prompts/portal/prepare-project.ts +++ b/src/prompts/portal/prepare-project.ts @@ -41,6 +41,16 @@ export class PreparePortalProjectPrompts { reportAuthorizationFailure(failure); } + /** The portal reports its own page views, so a GA4 stream that also counts history changes counts each page twice. */ + public googleAnalyticsCountsPageChanges() { + const message = + `Google Analytics is set, so the portal sends its own page views. In GA4, turn off the stream's ` + + `"Page changes based on browser history events" (Admin → Data streams → your stream → Enhanced ` + + `measurement → Page views → advanced settings), or every page change counts twice. ` + + `See the analytics page on ${f.link('https://docs.apimatic.io/v4/')}.`; + log.warn(message); + } + public sourceNotZipped(problem: FileProblem, sourceDirectory: DirectoryPath) { log.error(notZippedForUpload(sourceDirectory, problem.reason)); } diff --git a/src/types/portal/config/analytics-config.ts b/src/types/portal/config/analytics-config.ts index 54d944c6..dbc89660 100644 --- a/src/types/portal/config/analytics-config.ts +++ b/src/types/portal/config/analytics-config.ts @@ -49,7 +49,7 @@ export class AnalyticsConfig { ); } - /** `portal generate` warns when this is true: the customer has a GA4 stream setting to turn off. */ + /** `portal generate` and `portal serve` warn when this is true: the customer has a GA4 stream setting to turn off. */ public usesGoogleAnalytics(): boolean { return this.googleAnalytics !== null; } diff --git a/src/types/portal/portal-config.ts b/src/types/portal/portal-config.ts index a0b6a39f..5a39ecc2 100644 --- a/src/types/portal/portal-config.ts +++ b/src/types/portal/portal-config.ts @@ -123,7 +123,7 @@ export class PortalConfig { return this.brand.files(); } - /** `portal generate` warns when this is true: the customer has a GA4 stream setting to turn off. */ + /** `portal generate` and `portal serve` warn when this is true: the customer has a GA4 stream setting to turn off. */ public usesGoogleAnalytics(): boolean { return this.analytics.usesGoogleAnalytics(); } diff --git a/test/actions/portal/generate.test.ts b/test/actions/portal/generate.test.ts index 1232b09f..72f610d5 100644 --- a/test/actions/portal/generate.test.ts +++ b/test/actions/portal/generate.test.ts @@ -15,7 +15,7 @@ import { ServiceError } from '../../../src/infrastructure/service-error'; import { DirectoryPath } from '../../../src/types/file/directoryPath'; import { CommandMetadata } from '../../../src/types/common/command-metadata'; import { ProjectContext } from '../../../src/types/project-context'; -import { completeArtifacts, fixtureWithAnalytics, stubPreparePortalProject } from './prepare-project-stubs'; +import { completeArtifacts, stubPreparePortalProject } from './prepare-project-stubs'; const COMMAND_METADATA: CommandMetadata = { commandName: 'portal generate', shell: 'test' }; const FIXTURE = new DirectoryPath(process.cwd()).join('test/resources/portal-inputs/default'); @@ -320,38 +320,6 @@ describe('GenerateAction', () => { expect(shared.prompts.filesShadowedByStatic.firstCall.args[0].map(String)).to.deep.equal(['robots.txt']); }); - it('warns that Google Analytics counts page changes, before the build, when it is set', async () => { - const project = fixtureWithAnalytics(FIXTURE, new DirectoryPath(root).join('analytics'), { - googleAnalytics: { measurementId: 'G-ABC123' } - }); - - const result = await execute(project); - - expect(result.isSuccess()).to.be.true; - expect(prompts.googleAnalyticsCountsPageChanges.calledOnce).to.be.true; - expect(prompts.googleAnalyticsCountsPageChanges.calledBefore(build)).to.be.true; - expect(shared.prepare.firstCall.args[1].config.usesGoogleAnalytics()).to.be.true; - }); - - it('does not warn about Google Analytics under --no-analytics, which prepares the project without it', async () => { - const project = fixtureWithAnalytics(FIXTURE, new DirectoryPath(root).join('staging'), { - googleAnalytics: { measurementId: 'G-ABC123' } - }); - - const result = await execute(project, false, false, false); - - expect(result.isSuccess()).to.be.true; - expect(prompts.googleAnalyticsCountsPageChanges.called).to.be.false; - expect(shared.prepare.firstCall.args[1].config.usesGoogleAnalytics()).to.be.false; - }); - - it('does not warn about Google Analytics when it is not set', async () => { - const result = await execute(); - - expect(result.isSuccess()).to.be.true; - expect(prompts.googleAnalyticsCountsPageChanges.called).to.be.false; - }); - it('reports the specs the SDKs do not cover and the operations two specs declare, none in the fixture', async () => { const result = await execute(); diff --git a/test/actions/portal/prepare-project.test.ts b/test/actions/portal/prepare-project.test.ts index 212afab7..cb60ea15 100644 --- a/test/actions/portal/prepare-project.test.ts +++ b/test/actions/portal/prepare-project.test.ts @@ -80,20 +80,44 @@ describe('PreparePortalProjectAction', () => { expect(uploaded.filter((entry) => entry.startsWith('static/'))).to.be.empty; }); - it('prepares the project, and hands on the source, with neither vendor tag under --no-analytics', async () => { - const root = fs.mkdtempSync(path.join(os.tmpdir(), 'portal-prepare-')); - try { - const project = fixtureWithAnalytics(FIXTURE, new DirectoryPath(root), { - googleTagManager: { containerId: 'GTM-ABC123' } + describe('with both vendors set', () => { + let root: string; + const project = () => + fixtureWithAnalytics(FIXTURE, new DirectoryPath(root), { + googleTagManager: { containerId: 'GTM-ABC123' }, + googleAnalytics: { measurementId: 'G-ABC123' } }); - await execute(false, project); + beforeEach(() => { + root = fs.mkdtempSync(path.join(os.tmpdir(), 'portal-prepare-')); + }); + + afterEach(() => { + fs.rmSync(root, { recursive: true, force: true }); + }); + + it('warns that Google Analytics counts page changes, before the artifacts are asked for', async () => { + await execute(true, project()); + + expect(shared.prompts.googleAnalyticsCountsPageChanges.calledOnce).to.be.true; + expect(shared.prompts.googleAnalyticsCountsPageChanges.calledBefore(shared.artifacts)).to.be.true; + expect(onPrepared.firstCall.args[1].config.usesGoogleAnalytics()).to.be.true; + }); + + it('prepares the project, and hands on the source, with neither vendor tag and no warning under --no-analytics', async () => { + await execute(false, project()); expect(shared.prepare.firstCall.args[1].config.identity().analytics.googleTagManager).to.be.null; expect(onPrepared.firstCall.args[1].config.identity().analytics.googleTagManager).to.be.null; - } finally { - fs.rmSync(root, { recursive: true, force: true }); - } + expect(onPrepared.firstCall.args[1].config.usesGoogleAnalytics()).to.be.false; + expect(shared.prompts.googleAnalyticsCountsPageChanges.called).to.be.false; + }); + }); + + it('does not warn about Google Analytics when it is not set', async () => { + await execute(); + + expect(shared.prompts.googleAnalyticsCountsPageChanges.called).to.be.false; }); it('reports a source it could not zip, without asking for the artifacts', async () => { diff --git a/test/prompts/portal/generate.test.ts b/test/prompts/portal/generate.test.ts index 2aa61854..93a216c1 100644 --- a/test/prompts/portal/generate.test.ts +++ b/test/prompts/portal/generate.test.ts @@ -1,5 +1,4 @@ import { stripVTControlCharacters } from 'node:util'; -import { log } from '@clack/prompts'; import { expect } from 'chai'; import sinon from 'sinon'; import { PortalGeneratePrompts } from '../../../src/prompts/portal/generate.js'; @@ -7,24 +6,6 @@ import { DirectoryPath } from '../../../src/types/file/directoryPath.js'; import { SiteAddress } from '../../../src/types/portal/config/site-address.js'; describe('PortalGeneratePrompts', () => { - describe('the GA4 warning', () => { - it('says what to turn off, where, and why', () => { - const warn = sinon.stub(log, 'warn'); - try { - new PortalGeneratePrompts().googleAnalyticsCountsPageChanges(); - } finally { - warn.restore(); - } - - expect(stripVTControlCharacters(String(warn.firstCall.args[0]))).to.equal( - "Google Analytics is set, so the portal sends its own page views. In GA4, turn off the stream's " + - '"Page changes based on browser history events" (Admin → Data streams → your stream → Enhanced ' + - 'measurement → Page views → advanced settings), or every page change counts twice. ' + - 'See the analytics page on https://docs.apimatic.io/v4/.' - ); - }); - }); - describe('the next steps', () => { const portal = new DirectoryPath('portal'); diff --git a/test/prompts/portal/prepare-project.test.ts b/test/prompts/portal/prepare-project.test.ts index 419d40e9..7dacc65f 100644 --- a/test/prompts/portal/prepare-project.test.ts +++ b/test/prompts/portal/prepare-project.test.ts @@ -12,6 +12,19 @@ describe('PreparePortalProjectPrompts', () => { sinon.restore(); }); + it('says what to turn off in GA4, where, and why', () => { + const warn = sinon.stub(log, 'warn'); + + new PreparePortalProjectPrompts().googleAnalyticsCountsPageChanges(); + + expect(stripVTControlCharacters(String(warn.firstCall.args[0]))).to.equal( + "Google Analytics is set, so the portal sends its own page views. In GA4, turn off the stream's " + + '"Page changes based on browser history events" (Admin → Data streams → your stream → Enhanced ' + + 'measurement → Page views → advanced settings), or every page change counts twice. ' + + 'See the analytics page on https://docs.apimatic.io/v4/.' + ); + }); + // A run delivers everything or nothing, so a gap is the server's to fix. it('names what the artifacts left out, and says to try again', () => { const error = sinon.stub(log, 'error'); From 3f458d582bfcf88c1c4b6e0c17c65f3ab80633ae Mon Sep 17 00:00:00 2001 From: Muhammad Sohail Date: Fri, 13 Nov 2026 17:34:44 +0500 Subject: [PATCH 50/73] refactor(portal): leave analytics and seo out of the block quickstart writes toJSON() only ever wrote the scaffold's defaults, so its analytics and seo branches ran in tests alone. The GTM environment gets one named type on each side. Co-Authored-By: Claude Opus 5.5 --- portal-template/src/lib/portal-types.ts | 7 ++++- src/types/portal/config/analytics-config.ts | 35 +++++---------------- src/types/portal/config/seo-config.ts | 9 ------ src/types/portal/portal-config.ts | 12 ++----- test/types/portal/portal-config.test.ts | 26 --------------- 5 files changed, 17 insertions(+), 72 deletions(-) diff --git a/portal-template/src/lib/portal-types.ts b/portal-template/src/lib/portal-types.ts index 006c0044..cbc8cc0e 100644 --- a/portal-template/src/lib/portal-types.ts +++ b/portal-template/src/lib/portal-types.ts @@ -22,9 +22,14 @@ export interface PortalFavicon { type: string | null; } +export interface GoogleTagManagerEnvironment { + auth: string; + preview: string; +} + export interface GoogleTagManagerSetting { containerId: string; - environment: { auth: string; preview: string } | null; + environment: GoogleTagManagerEnvironment | null; } export interface GoogleAnalyticsSetting { diff --git a/src/types/portal/config/analytics-config.ts b/src/types/portal/config/analytics-config.ts index dbc89660..76ec59d2 100644 --- a/src/types/portal/config/analytics-config.ts +++ b/src/types/portal/config/analytics-config.ts @@ -2,10 +2,15 @@ import { err, ok, Result } from 'neverthrow'; import { isJsonObject } from '../../../utils/json-utils.js'; import { allOf, namespace, nonEmptyString, optional, Parsed, required, unknownKeys } from './fields.js'; +/** From a GTM environment's own snippet, so a staging build can still be checked in GTM. */ +export interface GoogleTagManagerEnvironment { + auth: string; + preview: string; +} + export interface GoogleTagManagerSetting { containerId: string; - /** From the environment's own snippet, so a staging build can still be checked in GTM. */ - environment: { auth: string; preview: string } | null; + environment: GoogleTagManagerEnvironment | null; } export interface GoogleAnalyticsSetting { @@ -19,12 +24,6 @@ export interface PortalAnalytics { keepQueryParams: string[]; } -export interface AnalyticsBlock { - googleTagManager?: { containerId: string; environment?: { auth: string; preview: string } }; - googleAnalytics?: GoogleAnalyticsSetting; - keepQueryParams?: string[]; -} - const KNOWN = ['googleTagManager', 'googleAnalytics', 'keepQueryParams']; export class AnalyticsConfig { @@ -66,24 +65,6 @@ export class AnalyticsConfig { public withoutVendors(): AnalyticsConfig { return new AnalyticsConfig(null, null, this.keepQueryParams); } - - /** Null with nothing set, so the block quickstart writes has no `analytics`. */ - public toJSON(): AnalyticsBlock | null { - const gtm = this.googleTagManager; - const block: AnalyticsBlock = { - ...(gtm === null - ? {} - : { - googleTagManager: { - containerId: gtm.containerId, - ...(gtm.environment === null ? {} : { environment: gtm.environment }) - } - }), - ...(this.googleAnalytics === null ? {} : { googleAnalytics: this.googleAnalytics }), - ...(this.keepQueryParams.length === 0 ? {} : { keepQueryParams: this.keepQueryParams }) - }; - return Object.keys(block).length === 0 ? null : block; - } } // Each ID is required and nothing more: its format is the vendor's to check, since a wrong value fails there, not here. @@ -100,7 +81,7 @@ function googleTagManager(value: unknown, path: string): Parsed ({ containerId, environment })); } -function environment(value: unknown, path: string): Parsed<{ auth: string; preview: string }> { +function environment(value: unknown, path: string): Parsed { if (!isJsonObject(value)) { return err([`'${path}' must be a JSON object with 'auth' and 'preview'.`]); } diff --git a/src/types/portal/config/seo-config.ts b/src/types/portal/config/seo-config.ts index 7f5c3db5..e775fdd5 100644 --- a/src/types/portal/config/seo-config.ts +++ b/src/types/portal/config/seo-config.ts @@ -6,10 +6,6 @@ export interface PortalSeo { googleSiteVerification: string | null; } -export interface SeoBlock { - googleSiteVerification: string; -} - const KNOWN = ['googleSiteVerification']; export class SeoConfig { @@ -31,9 +27,4 @@ export class SeoConfig { public identity(): PortalSeo { return { googleSiteVerification: this.googleSiteVerification }; } - - /** Null with nothing set, so the block quickstart writes has no `seo`. */ - public toJSON(): SeoBlock | null { - return this.googleSiteVerification === null ? null : { googleSiteVerification: this.googleSiteVerification }; - } } diff --git a/src/types/portal/portal-config.ts b/src/types/portal/portal-config.ts index 5a39ecc2..acc02030 100644 --- a/src/types/portal/portal-config.ts +++ b/src/types/portal/portal-config.ts @@ -2,12 +2,12 @@ import { err, ok, Result } from 'neverthrow'; import { isJsonObject } from '../../utils/json-utils.js'; import { UrlPath } from '../file/urlPath.js'; import { AiConfig } from './config/ai-config.js'; -import { AnalyticsBlock, AnalyticsConfig, PortalAnalytics } from './config/analytics-config.js'; +import { AnalyticsConfig, PortalAnalytics } from './config/analytics-config.js'; import { BrandConfig, ColorMode } from './config/brand-config.js'; import { allOf, optional, Parsed, unknownKeys } from './config/fields.js'; import { Link } from './config/link.js'; import { NavigationConfig } from './config/navigation-config.js'; -import { PortalSeo, SeoBlock, SeoConfig } from './config/seo-config.js'; +import { PortalSeo, SeoConfig } from './config/seo-config.js'; import { SiteAddress } from './config/site-address.js'; import { SiteConfig, SuggestedSite } from './config/site-config.js'; import { StaticAsset } from './config/static-asset.js'; @@ -159,17 +159,13 @@ export class PortalConfig { ); } - /** Every namespace included, defaults and all, which is what quickstart writes; `analytics` and `seo` only when set. */ + /** Every namespace included, defaults and all, which is what quickstart writes; `analytics` and `seo` start unset. */ public toJSON(): PortalBlock { - const analytics = this.analytics.toJSON(); - const seo = this.seo.toJSON(); return { site: this.site.toJSON(), brand: this.brand.toJSON(), navigation: this.navigation.toJSON(), ai: this.ai.toJSON(), - ...(analytics === null ? {} : { analytics }), - ...(seo === null ? {} : { seo }), ...(this.pluginAddress === null ? {} : { pluginUrl: this.pluginAddress.toString() }) }; } @@ -198,7 +194,5 @@ export interface PortalBlock { brand: ReturnType; navigation: ReturnType; ai: ReturnType; - analytics?: AnalyticsBlock; - seo?: SeoBlock; pluginUrl?: string; } diff --git a/test/types/portal/portal-config.test.ts b/test/types/portal/portal-config.test.ts index 253adf1c..d90e1cbc 100644 --- a/test/types/portal/portal-config.test.ts +++ b/test/types/portal/portal-config.test.ts @@ -406,7 +406,6 @@ describe('PortalConfig', () => { googleAnalytics: null, keepQueryParams: [] }); - expect(JSON.parse(JSON.stringify(config({})))).to.not.have.property('analytics'); }); it('keeps both vendors with their IDs trimmed, the environment and every kept name, an OAuth answer’s included', () => { @@ -539,9 +538,6 @@ describe('PortalConfig', () => { it('keeps an empty list of names as none', () => { expect(config({ analytics: { keepQueryParams: [] } }).identity().analytics.keepQueryParams).to.deep.equal([]); - expect(JSON.parse(JSON.stringify(config({ analytics: { keepQueryParams: [] } })))).to.not.have.property( - 'analytics' - ); }); it('uses Google Analytics only with a measurement ID', () => { @@ -551,21 +547,6 @@ describe('PortalConfig', () => { expect(config({ analytics: { googleAnalytics: { measurementId: 'G-ABC123' } } }).usesGoogleAnalytics()).to.be .true; }); - - it('serialises what it was given, and nothing when given nothing', () => { - const analytics = { - googleTagManager: { containerId: 'GTM-ABC123', environment: { auth: 'a', preview: 'env-1' } }, - googleAnalytics: { measurementId: 'G-ABC123' }, - keepQueryParams: ['campaign_id'] - }; - const written = (block: unknown) => JSON.parse(JSON.stringify(config(block))); - - expect(written({ analytics }).analytics).to.deep.equal(analytics); - expect(written({ analytics: { googleTagManager: { containerId: 'GTM-1' } } }).analytics).to.deep.equal({ - googleTagManager: { containerId: 'GTM-1' } - }); - expect(written({ analytics: {} })).to.not.have.property('analytics'); - }); }); describe('seo', () => { @@ -584,13 +565,6 @@ describe('PortalConfig', () => { "'portal.seo.googleSiteVerification' must be a non-empty string." ]); }); - - it('is serialised only when set', () => { - const written = (block: unknown) => JSON.parse(JSON.stringify(config(block))); - - expect(written({ seo: { googleSiteVerification: 'abc' } }).seo).to.deep.equal({ googleSiteVerification: 'abc' }); - expect(written({ seo: {} })).to.not.have.property('seo'); - }); }); describe('pluginUrl', () => { From 353918b53751f0bab8dc160ba2f087f6e051575c Mon Sep 17 00:00:00 2001 From: Muhammad Sohail Date: Fri, 13 Nov 2026 17:34:44 +0500 Subject: [PATCH 51/73] test(portal): run the portal commands to see --no-analytics reach the settings Both commands run up to their read of the source, so a flipped flag fails a test, where the parse-only tests stayed green. Co-Authored-By: Claude Opus 5.5 --- test/commands/portal/build-options.ts | 35 +++++++++++++++++++++ test/commands/portal/generate-flags.test.ts | 13 +++----- test/commands/portal/serve-flags.test.ts | 13 +++----- 3 files changed, 43 insertions(+), 18 deletions(-) create mode 100644 test/commands/portal/build-options.ts diff --git a/test/commands/portal/build-options.ts b/test/commands/portal/build-options.ts new file mode 100644 index 00000000..ab7d09d4 --- /dev/null +++ b/test/commands/portal/build-options.ts @@ -0,0 +1,35 @@ +import os from 'os'; +import sinon from 'sinon'; +import { Config } from '@oclif/core'; +import { err, ok } from 'neverthrow'; +import { PortalAuthorizationService } from '../../../src/infrastructure/services/portal-authorization-service.js'; +import { PortalSourceContext } from '../../../src/types/portal-source-context.js'; +import { stubPreparePortalProject } from '../../actions/portal/prepare-project-stubs.js'; + +const FIXTURE = 'test/resources/portal-inputs/default'; + +/** Just enough of oclif's config for a command to parse its flags and name its config directory. */ +const config = { + configDir: os.tmpdir(), + shell: 'test', + runHook: async () => ({ successes: [], failures: [] }) +} as unknown as Config; + +/** Runs a portal command up to its read of the source, and gives what its flags asked that read for. */ +export async function buildOptionsOf( + command: new (argv: string[], config: Config) => { run(): Promise }, + argv: string[] +): Promise { + stubPreparePortalProject(); + sinon.stub(PortalAuthorizationService.prototype, 'authorize').resolves(ok(undefined)); + const resolve = sinon.stub(PortalSourceContext.prototype, 'resolve').resolves(err({ kind: 'missingConfig' })); + sinon.stub(process.stdout, 'write').returns(true); + const exitCode = process.exitCode; + try { + await new command([...argv, '--input', FIXTURE], config).run(); + } finally { + process.exitCode = exitCode; + sinon.restore(); + } + return resolve.firstCall.args[0]; +} diff --git a/test/commands/portal/generate-flags.test.ts b/test/commands/portal/generate-flags.test.ts index 67dc7aee..b5917aad 100644 --- a/test/commands/portal/generate-flags.test.ts +++ b/test/commands/portal/generate-flags.test.ts @@ -1,15 +1,10 @@ import { expect } from 'chai'; import PortalGenerate from '../../../src/commands/portal/generate.js'; -import { flagParser } from '../flag-parser.js'; - -const { parse } = flagParser(PortalGenerate); +import { buildOptionsOf } from './build-options.js'; describe('portal generate flags', () => { - it('accepts --no-analytics, off unless passed', async () => { - const given = (await parse(['--no-analytics'])) as never as { flags: Record }; - const omitted = (await parse([])) as never as { flags: Record }; - - expect(given.flags['no-analytics']).to.be.true; - expect(omitted.flags['no-analytics']).to.be.false; + it('reads the source without the vendor tags under --no-analytics, and with them otherwise', async () => { + expect(await buildOptionsOf(PortalGenerate, ['--no-analytics'])).to.deep.equal({ analytics: false }); + expect(await buildOptionsOf(PortalGenerate, [])).to.deep.equal({ analytics: true }); }); }); diff --git a/test/commands/portal/serve-flags.test.ts b/test/commands/portal/serve-flags.test.ts index e0df05a8..f3607c00 100644 --- a/test/commands/portal/serve-flags.test.ts +++ b/test/commands/portal/serve-flags.test.ts @@ -1,15 +1,10 @@ import { expect } from 'chai'; import PortalServe from '../../../src/commands/portal/serve.js'; -import { flagParser } from '../flag-parser.js'; - -const { parse } = flagParser(PortalServe); +import { buildOptionsOf } from './build-options.js'; describe('portal serve flags', () => { - it('accepts --no-analytics, off unless passed', async () => { - const given = (await parse(['--no-analytics'])) as never as { flags: Record }; - const omitted = (await parse([])) as never as { flags: Record }; - - expect(given.flags['no-analytics']).to.be.true; - expect(omitted.flags['no-analytics']).to.be.false; + it('reads the source without the vendor tags under --no-analytics, and with them otherwise', async () => { + expect(await buildOptionsOf(PortalServe, ['--no-analytics'])).to.deep.equal({ analytics: false }); + expect(await buildOptionsOf(PortalServe, [])).to.deep.equal({ analytics: true }); }); }); From 1c5a5ffaca419344d5d053d07566b15e27ed2219 Mon Sep 17 00:00:00 2001 From: Muhammad Sohail Date: Fri, 13 Nov 2026 17:34:44 +0500 Subject: [PATCH 52/73] refactor(portal): drop the import cycle, GTM's no-op send and the null page location An adapter's send takes the event name as a string and is optional, so vendor-tags.ts no longer imports analytics.ts and GTM has none. pageLocation() always cleans an address; the callers skip the OAuth callback. Co-Authored-By: Claude Opus 5.5 --- portal-template/src/lib/analytics.ts | 18 +++++++------- portal-template/src/lib/vendor-tags.ts | 8 +++---- test/portal-template/analytics.test.ts | 21 +---------------- test/portal-template/oauth-callback.test.ts | 26 ++++++++++++++++++++- 4 files changed, 37 insertions(+), 36 deletions(-) diff --git a/portal-template/src/lib/analytics.ts b/portal-template/src/lib/analytics.ts index 5264a903..de5310af 100644 --- a/portal-template/src/lib/analytics.ts +++ b/portal-template/src/lib/analytics.ts @@ -50,10 +50,9 @@ declare global { } } -/** The address as reported: no `#` part, no query but the kept tags, and null on the OAuth callback. */ -export function pageLocation(href: string, keep: readonly string[], base?: string): string | null { +/** The address as reported: no `#` part, and no query but the kept tags. */ +export function pageLocation(href: string, keep: readonly string[]): string { const url = new URL(href); - if (isOAuthCallbackPath(url.pathname, base)) return null; url.search = new URLSearchParams( [...url.searchParams].filter( ([name]) => KEPT_PREFIXES.some((prefix) => name.startsWith(prefix)) || KEPT_NAMES.has(name) || keep.includes(name) @@ -93,22 +92,21 @@ export class Analytics { /** `href` is the page the event belongs to, the current one unless the caller saw the address change first. */ public report(name: E, params: PortalEvents[E], href = window.location.href): void { - const page_location = pageLocation(href, this.settings.keepQueryParams); - if (page_location === null) return; - const docs = { ...params, page_location }; + if (isOAuthCallbackPath(new URL(href).pathname)) return; + const docs = { ...params, page_location: pageLocation(href, this.settings.keepQueryParams) }; const dataLayer = (window.dataLayer ??= []); // GTM keeps every key from earlier pushes and merges objects, so clear ours first: a shared GA4 tag never sends the last event's details. dataLayer.push({ docs: null } satisfies DataLayerEntry); dataLayer.push({ event: name, docs } satisfies DataLayerEntry); - for (const adapter of this.live) adapter.send(name, docs); + for (const adapter of this.live) adapter.send?.(name, docs); } /** `docs_page_view` for the current page, unless its cleaned address is the one last reported: a `#` jump sends none. */ public reportPageView(): void { - const page = pageLocation(window.location.href, this.settings.keepQueryParams); - if (page === null) return; + if (isOAuthCallbackPath(window.location.pathname)) return; // The tags held back on the OAuth callback start here, on the first page after it. insertTags(this.live); + const page = pageLocation(window.location.href, this.settings.keepQueryParams); if (page === this.lastPageView) return; this.previousPageView = this.lastPageView; this.lastPageView = page; @@ -121,7 +119,7 @@ export class Analytics { public reportNotFound(): void { const page = pageLocation(window.location.href, this.settings.keepQueryParams); // A dev build mounts the page twice; the next missing page is a new report. - if (page === null || page === this.lastNotFound) return; + if (page === this.lastNotFound) return; this.lastNotFound = page; const referrer = document.referrer === '' ? null : new URL(document.referrer); if (referrer !== null) { diff --git a/portal-template/src/lib/vendor-tags.ts b/portal-template/src/lib/vendor-tags.ts index f5f9692f..184dd2d8 100644 --- a/portal-template/src/lib/vendor-tags.ts +++ b/portal-template/src/lib/vendor-tags.ts @@ -1,4 +1,3 @@ -import type { PortalEventName } from './analytics'; import { isOAuthCallbackPath } from './oauth-callback'; import type { PortalAnalytics } from './portal-types'; @@ -14,8 +13,8 @@ declare global { export interface Adapter { setup(dataLayer: unknown[]): void; script: string; - /** GTM needs nothing here: it reads the data layer. */ - send(name: PortalEventName, params: Record): void; + /** For a vendor that does not read the data layer itself, as GTM does. */ + send?(name: string, params: Record): void; } type Vendor = Exclude; @@ -34,8 +33,7 @@ export const adapters: { [V in Vendor]: (settings: PortalAnalytics) => Adapter | : ''; return { setup: (dataLayer) => dataLayer.push({ 'gtm.start': Date.now(), event: 'gtm.js' }), - script: `${GOOGLE}/gtm.js?id=${encodeURIComponent(setting.containerId)}${environment}`, - send: () => {} + script: `${GOOGLE}/gtm.js?id=${encodeURIComponent(setting.containerId)}${environment}` }; }, googleAnalytics: ({ googleAnalytics: setting }) => { diff --git a/test/portal-template/analytics.test.ts b/test/portal-template/analytics.test.ts index 56332140..ed332442 100644 --- a/test/portal-template/analytics.test.ts +++ b/test/portal-template/analytics.test.ts @@ -54,29 +54,10 @@ describe('pageLocation', () => { expect(pageLocation(`${page}?gclidx=1`, [])).to.equal(page); }); - it('is null on the OAuth callback', () => { - expect(pageLocation('https://docs.test/oauth/callback?code=abc&state=123', [])).to.be.null; - expect(pageLocation('https://docs.test/oauth/callback#access_token=xyz&state=123', [])).to.be.null; - }); - - it('is null on the OAuth callback under a base path', () => { - expect(pageLocation('https://docs.test/docs/oauth/callback?code=abc&state=123', [], '/docs/')).to.be.null; - }); - - // A static host may answer `/oauth/callback` at `/oauth/callback/` and keep the query. - it('is null on the OAuth callback with a trailing slash', () => { - expect(pageLocation('https://docs.test/oauth/callback/?code=abc&state=123', [])).to.be.null; - expect(pageLocation('https://docs.test/docs/oauth/callback/#access_token=xyz', [], '/docs/')).to.be.null; - }); - - it('is not the callback at the root when the portal is under a base path', () => { - expect(pageLocation('https://docs.test/oauth/callback', [], '/docs/')).to.equal('https://docs.test/oauth/callback'); - }); - it('leaves the address otherwise unchanged', () => { expect(pageLocation(page, [])).to.equal(page); expect(pageLocation('https://docs.test/', [])).to.equal('https://docs.test/'); - expect(pageLocation('https://docs.test/docs/api/pets/Get%20Pets', [], '/docs/')).to.equal( + expect(pageLocation('https://docs.test/docs/api/pets/Get%20Pets', [])).to.equal( 'https://docs.test/docs/api/pets/Get%20Pets' ); expect(pageLocation('http://localhost:3000/guides/quickstart', [])).to.equal( diff --git a/test/portal-template/oauth-callback.test.ts b/test/portal-template/oauth-callback.test.ts index a370e8dc..b7565445 100644 --- a/test/portal-template/oauth-callback.test.ts +++ b/test/portal-template/oauth-callback.test.ts @@ -1,7 +1,12 @@ import { expect } from 'chai'; import type { SecuritySchemeObject } from 'fumadocs-openapi'; import { requestOAuthToken } from 'fumadocs-openapi/playground'; -import { oauthCallback, oauthCallbackPath, takeStartingPage } from '../../portal-template/src/lib/oauth-callback'; +import { + isOAuthCallbackPath, + oauthCallback, + oauthCallbackPath, + takeStartingPage +} from '../../portal-template/src/lib/oauth-callback'; import { OAUTH_CALLBACK_ADDRESS } from '../../src/types/portal/content-tree'; // The CLI refuses a page of the user's at the address the template serves the callback at. @@ -16,6 +21,25 @@ describe('oauthCallbackPath', () => { * callback takes the note from the same place. The playground's flow is run here, in a stand-in * tab, so a move of the note, as 12.5.7 made from a cookie, fails this test and not a portal. */ +describe('isOAuthCallbackPath', () => { + it('is the callback at the root, and under a base path', () => { + expect(isOAuthCallbackPath('/oauth/callback')).to.be.true; + expect(isOAuthCallbackPath('/docs/oauth/callback', '/docs/')).to.be.true; + }); + + // A static host may answer `/oauth/callback` at `/oauth/callback/`. + it('is the callback with a trailing slash', () => { + expect(isOAuthCallbackPath('/oauth/callback/')).to.be.true; + expect(isOAuthCallbackPath('/docs/oauth/callback/', '/docs/')).to.be.true; + }); + + it('is not the callback at the root when the portal is under a base path, nor any other page', () => { + expect(isOAuthCallbackPath('/oauth/callback', '/docs/')).to.be.false; + expect(isOAuthCallbackPath('/guides/quickstart')).to.be.false; + expect(isOAuthCallbackPath('/oauth/callback/more')).to.be.false; + }); +}); + describe('takeStartingPage', () => { const origin = 'https://docs.test'; const pathname = '/api/pets/pets/listPets'; From f9b415af3e19c7db84529ca83a1272f464fadb07 Mon Sep 17 00:00:00 2001 From: Muhammad Sohail Date: Fri, 13 Nov 2026 17:34:45 +0500 Subject: [PATCH 53/73] fix(portal): give GA4's own events the reported address Each page view sets GA4's page_location to the cleaned address, so its scroll and click events no longer send the browser's full address. Co-Authored-By: Claude Opus 5.5 --- portal-template/src/lib/vendor-tags.ts | 6 ++++- test/portal-template/analytics.test.ts | 32 +++++++++++++++++++++----- 2 files changed, 31 insertions(+), 7 deletions(-) diff --git a/portal-template/src/lib/vendor-tags.ts b/portal-template/src/lib/vendor-tags.ts index 184dd2d8..87330de5 100644 --- a/portal-template/src/lib/vendor-tags.ts +++ b/portal-template/src/lib/vendor-tags.ts @@ -50,7 +50,11 @@ export const adapters: { [V in Vendor]: (settings: PortalAnalytics) => Adapter | script: `${GOOGLE}/gtag/js?id=${encodeURIComponent(setting.measurementId)}`, // The page's gtag, which an instance a config save under `portal serve` makes never sets up; GA4 gets its own // names, without the `docs_` prefix. - send: (name, params) => window.gtag?.('event', name.replace(/^docs_/, ''), params) + send: (name, params) => { + // GA4's own events, such as a scroll, read this instead of the address, which may hold more. + if (name === 'docs_page_view') window.gtag?.('set', { page_location: params.page_location }); + window.gtag?.('event', name.replace(/^docs_/, ''), params); + } }; } }; diff --git a/test/portal-template/analytics.test.ts b/test/portal-template/analytics.test.ts index ed332442..17951eda 100644 --- a/test/portal-template/analytics.test.ts +++ b/test/portal-template/analytics.test.ts @@ -274,10 +274,29 @@ describe('Analytics', () => { analytics.reportPageView(); const entries = page.dataLayer(); - expect(entries).to.have.length(5); + expect(entries).to.have.length(6); expect(entries[2]).to.deep.equal({ docs: null }); expect(entries[3]).to.deep.equal(quickstartView); - expect(gtagCalls([entries[4]])[0]).to.deep.equal(['event', 'page_view', quickstartView.docs]); + expect(gtagCalls(entries.slice(4))).to.deep.equal([ + ['set', { page_location: quickstart }], + ['event', 'page_view', quickstartView.docs] + ]); + }); + + it("gives GA4's own events the reported address of each page, never the one in the address bar", () => { + const page = browser('https://docs.test/api/pets/listPets?code=x&state=y#access_token=z', 'List pets'); + const analytics = new Analytics(withGa4); + + analytics.start(); + analytics.reportPageView(); + page.go(`${quickstart}?utm_source=mail&tab=python#install`); + analytics.reportPageView(); + analytics.report('docs_markdown_copy', {}); + + expect(gtagCalls(page.dataLayer()).filter((command) => command[0] === 'set')).to.deep.equal([ + ['set', { page_location: 'https://docs.test/api/pets/listPets' }], + ['set', { page_location: `${quickstart}?utm_source=mail` }] + ]); }); it('pushes Arguments objects, which gtag.js reads, never arrays of the same values', () => { @@ -287,7 +306,7 @@ describe('Analytics', () => { analytics.start(); analytics.reportPageView(); - expect(page.dataLayer().filter(isArguments)).to.have.length(3); + expect(page.dataLayer().filter(isArguments)).to.have.length(4); expect(page.dataLayer().some(Array.isArray)).to.be.false; }); @@ -314,7 +333,7 @@ describe('Analytics', () => { analytics.reportPageView(); expect(page.window.gtag).to.equal(existing); - expect(calls.map((command) => command[0])).to.deep.equal(['js', 'config', 'event']); + expect(calls.map((command) => command[0])).to.deep.equal(['js', 'config', 'set', 'event']); expect(page.dataLayer().filter(isArguments)).to.be.empty; }); @@ -339,12 +358,13 @@ describe('Analytics', () => { analytics.reportPageView(); const entries = page.dataLayer(); - expect(entries).to.have.length(6); + expect(entries).to.have.length(7); expect(entries[0]).to.have.property('event', 'gtm.js'); expect(gtagCalls(entries.slice(1, 3)).map((command) => command[0])).to.deep.equal(['js', 'config']); expect(entries[3]).to.deep.equal({ docs: null }); expect(entries[4]).to.deep.equal(quickstartView); - expect(gtagCalls([entries[5]])[0]).to.deep.equal(['event', 'page_view', quickstartView.docs]); + expect(gtagCalls(entries.slice(5)).map((command) => command[0])).to.deep.equal(['set', 'event']); + expect(gtagCalls([entries[6]])[0]).to.deep.equal(['event', 'page_view', quickstartView.docs]); expect(page.scripts.map((script) => script.src)).to.deep.equal([GTM_SCRIPT, GA4_SCRIPT]); }); From 15460ba0a036f5ebde8600d5644920087dae1232 Mon Sep 17 00:00:00 2001 From: Muhammad Sohail Date: Fri, 13 Nov 2026 17:34:45 +0500 Subject: [PATCH 54/73] fix(portal): reload the preview when a config save changes the vendors A config save under portal serve evaluates the analytics module again; with other settings than the page started with, the page reloads, so it holds exactly the new tags and a new vendor's setup runs. Co-Authored-By: Claude Opus 5.5 --- portal-template/src/lib/analytics.ts | 14 ++++++++++---- test/portal-template/analytics.test.ts | 18 ++++++++++++++++-- 2 files changed, 26 insertions(+), 6 deletions(-) diff --git a/portal-template/src/lib/analytics.ts b/portal-template/src/lib/analytics.ts index de5310af..27d7847b 100644 --- a/portal-template/src/lib/analytics.ts +++ b/portal-template/src/lib/analytics.ts @@ -45,8 +45,8 @@ type DataLayerEntry = { docs: null } | { event: PortalEventName; docs: Readonly< declare global { interface Window { dataLayer?: unknown[]; - /** Set by the first start in a page load: a module Vite evaluates again under `portal serve` makes a second instance. */ - portalAnalyticsStarted?: true; + /** The settings the page load started with: a config save under `portal serve` evaluates the module again. */ + portalAnalyticsStarted?: string; } } @@ -83,8 +83,14 @@ export class Analytics { * window's, not the instance's: a config save under `portal serve` makes Vite evaluate the module again. */ public start(): void { - if (window.portalAnalyticsStarted) return; - window.portalAnalyticsStarted = true; + const settings = JSON.stringify(this.settings); + if (window.portalAnalyticsStarted === settings) return; + // Other vendors after a config save: only a fresh page holds exactly their tags and setup. + if (window.portalAnalyticsStarted !== undefined) { + window.location.reload(); + return; + } + window.portalAnalyticsStarted = settings; const dataLayer = (window.dataLayer ??= []); for (const adapter of this.live) adapter.setup(dataLayer); insertTags(this.live); diff --git a/test/portal-template/analytics.test.ts b/test/portal-template/analytics.test.ts index 17951eda..f12f3a4d 100644 --- a/test/portal-template/analytics.test.ts +++ b/test/portal-template/analytics.test.ts @@ -102,7 +102,7 @@ interface FakeScript { } interface FakeWindow { - location: URL; + location: URL & { reload: () => void }; dataLayer?: unknown[]; gtag?: (...command: unknown[]) => void; } @@ -110,7 +110,8 @@ interface FakeWindow { /** A page in the browser: the `window` and `document` the module reads, and the scripts the loader appends. */ function browser(href: string, title = 'Quickstart | Acme API', referrer = '') { const scripts: FakeScript[] = []; - const window: FakeWindow = { location: new URL(href) }; + let reloads = 0; + const window: FakeWindow = { location: Object.assign(new URL(href), { reload: () => (reloads += 1) }) }; const document = { title, referrer, @@ -125,6 +126,7 @@ function browser(href: string, title = 'Quickstart | Acme API', referrer = '') { window, scripts, dataLayer: () => window.dataLayer ?? [], + reloads: () => reloads, go: (next: string, nextTitle = title) => { window.location.href = next; document.title = nextTitle; @@ -378,6 +380,18 @@ describe('Analytics', () => { expect(page.dataLayer()).to.have.length(3); expect(page.scripts).to.have.length(2); + expect(page.reloads()).to.equal(0); + }); + + it('reloads the page for a start with other vendors, as a config save under portal serve makes', () => { + const page = browser(quickstart); + new Analytics(withGtm()).start(); + + new Analytics(withBoth).start(); + + expect(page.reloads()).to.equal(1); + expect(page.dataLayer()).to.have.length(1); + expect(page.scripts.map((script) => script.src)).to.deep.equal([GTM_SCRIPT]); }); }); From c15f0d305f5bb848d595916420106ea0ab185cb0 Mon Sep 17 00:00:00 2001 From: Muhammad Sohail Date: Fri, 13 Nov 2026 17:34:45 +0500 Subject: [PATCH 55/73] refactor(portal): time playground requests in the playground The send time lives in a ref the playground owns and reaches the result display by context, and a plain apiRequest() shapes the event, tested with typed results. Analytics loses the playground's state and methods. Co-Authored-By: Claude Opus 5.5 --- portal-template/src/components/playground.tsx | 48 +++++++---- portal-template/src/lib/analytics.ts | 25 ------ portal-template/src/lib/api-request.ts | 15 ++++ test/portal-template/analytics.test.ts | 81 ------------------- test/portal-template/api-request.test.ts | 46 +++++++++++ 5 files changed, 93 insertions(+), 122 deletions(-) create mode 100644 portal-template/src/lib/api-request.ts create mode 100644 test/portal-template/api-request.test.ts diff --git a/portal-template/src/components/playground.tsx b/portal-template/src/components/playground.tsx index 1eaf54e0..b18dcf37 100644 --- a/portal-template/src/components/playground.tsx +++ b/portal-template/src/components/playground.tsx @@ -1,24 +1,27 @@ -import { useEffect } from 'react'; +import { createContext, use, useEffect, useMemo, useRef, type RefObject } from 'react'; import { useOperation } from 'fumadocs-openapi/operation'; +import type { FetchResult } from 'fumadocs-openapi/playground'; import PlaygroundClient, { DefaultResultDisplay, type ResultDisplayProps } from 'fumadocs-openapi/ui/playground/client'; +import { apiRequest } from '@/lib/api-request'; import { analytics } from '@/lib/portal-analytics'; import { markForReplay } from '@/lib/replay-markers'; -// Fumadocs' request has no callback of its own: the start is noted here, and the request goes on unchanged. -const fetchOptions = { - onRequestInit: (requestInit: RequestInit) => { - analytics.requestStarted(); - return requestInit; - } -}; +/** When this playground last sent a request, for a result that has no duration of its own. */ +const SentAt = createContext>({ current: null }); + +// The display mounts again with the same result on each reopen, and twice in a dev build. +const reported = new WeakSet(); -/** Fumadocs' result display, reporting each result once: the effect runs per result object, not per render. */ function ResultDisplay(props: ResultDisplayProps) { const { method, path } = useOperation(); - useEffect( - () => analytics.reportApiRequest(`${method.toUpperCase()} ${path}`, props.data), - [method, path, props.data] - ); + const sentAt = use(SentAt); + useEffect(() => { + if (reported.has(props.data)) return; + reported.add(props.data); + const endpoint = `${method.toUpperCase()} ${path}`; + analytics.report('docs_api_request', apiRequest(endpoint, props.data, sentAt.current, Date.now())); + sentAt.current = null; + }, [method, path, props.data, sentAt]); return ; } @@ -26,6 +29,17 @@ const components = { ResultDisplay }; /** The playground with the reporting around it, in the one chunk the API page loads lazily. */ export default function Playground() { + const sentAt = useRef(null); + // Fumadocs' request has no callback of its own: the time is noted here, and the request goes on unchanged. + const fetchOptions = useMemo( + () => ({ + onRequestInit: (requestInit: RequestInit) => { + sentAt.current = Date.now(); + return requestInit; + } + }), + [] + ); // Fumadocs renders the dialog outside the marked wrapper, so it is marked as it appears, told from the search // dialog by the request form in it, until fuma-nama/fumadocs#3824 lets the markers be passed to the dialog directly. useEffect(() => { @@ -41,7 +55,9 @@ export default function Playground() { observer.observe(document.body, { childList: true, subtree: true }); return () => observer.disconnect(); }, []); - // A request still in flight when the page is left reports nothing, so its start must not time a later one. - useEffect(() => () => analytics.requestAbandoned(), []); - return ; + return ( + + + + ); } diff --git a/portal-template/src/lib/analytics.ts b/portal-template/src/lib/analytics.ts index 27d7847b..979a4f1b 100644 --- a/portal-template/src/lib/analytics.ts +++ b/portal-template/src/lib/analytics.ts @@ -1,4 +1,3 @@ -import type { FetchResult } from 'fumadocs-openapi/playground'; import { isOAuthCallbackPath } from './oauth-callback'; import type { PortalAnalytics } from './portal-types'; import { type Adapter, adapters, insertTags } from './vendor-tags'; @@ -68,8 +67,6 @@ export class Analytics { private lastPageView: string | null = null; private previousPageView: string | null = null; private lastNotFound: string | null = null; - private requestStartedAt: number | null = null; - private lastApiResult: FetchResult | null = null; public constructor(private readonly settings: PortalAnalytics) { this.live = Object.values(adapters) @@ -137,26 +134,4 @@ export class Analytics { const left = this.lastPageView === page ? this.previousPageView : this.lastPageView; this.report('docs_not_found', { page_referrer: left ?? referrer?.href ?? '' }); } - /** As the playground sends a request: the start of the one duration a request that never arrives can have; a request failing before this has none. */ - public requestStarted(): void { - this.requestStartedAt = Date.now(); - } - - /** As the playground leaves the page: a request still in flight reports nothing, so its start times nothing later. */ - public requestAbandoned(): void { - this.requestStartedAt = null; - } - - /** The playground's result for `endpoint`, the method and path as the spec writes them: its status and its time, and nothing of the request itself. */ - public reportApiRequest(endpoint: string, result: FetchResult): void { - // The display mounts again with the same result on each reopen, and twice in a dev build. - if (result === this.lastApiResult) return; - this.lastApiResult = result; - const [status, duration_ms] = - result.type === 'response' - ? [String(result.status), Math.round(result.duration)] - : ['client_error', this.requestStartedAt === null ? 0 : Date.now() - this.requestStartedAt]; - this.requestStartedAt = null; - this.report('docs_api_request', { endpoint, status, duration_ms }); - } } diff --git a/portal-template/src/lib/api-request.ts b/portal-template/src/lib/api-request.ts new file mode 100644 index 00000000..19db41dc --- /dev/null +++ b/portal-template/src/lib/api-request.ts @@ -0,0 +1,15 @@ +import type { FetchResult } from 'fumadocs-openapi/playground'; +import type { PortalEvents } from './analytics'; + +/** A playground result as `docs_api_request` reports it; a request that never reached the API is timed from `sentAt`. */ +export function apiRequest( + endpoint: string, + result: FetchResult, + sentAt: number | null, + now: number +): PortalEvents['docs_api_request'] { + if (result.type === 'response') { + return { endpoint, status: String(result.status), duration_ms: Math.round(result.duration) }; + } + return { endpoint, status: 'client_error', duration_ms: sentAt === null ? 0 : now - sentAt }; +} diff --git a/test/portal-template/analytics.test.ts b/test/portal-template/analytics.test.ts index f12f3a4d..4d923cba 100644 --- a/test/portal-template/analytics.test.ts +++ b/test/portal-template/analytics.test.ts @@ -726,85 +726,4 @@ describe('Analytics', () => { expect(pageViews(page.dataLayer())).to.have.length(4); }); }); - describe('reportApiRequest', () => { - const address = 'https://docs.acme.com/api/calc/Calculate'; - const endpoint = 'GET /{operation}'; - // The request's own address, which holds filled-in values: never reported. - const url = 'https://api.acme.com/v1/calc/SUM?x=4&api_key=s3cret'; - const requests = (entries: unknown[]) => - entries.filter((entry) => isPlainObject(entry) && entry.event === 'docs_api_request') as { - docs: Record; - }[]; - - it('reports a response by its status and its own duration, rounded', () => { - const page = browser(address); - - new Analytics(none).reportApiRequest(endpoint, { type: 'response', url, status: 200, duration: 123.4 } as never); - - expect(requests(page.dataLayer())).to.deep.equal([ - { event: 'docs_api_request', docs: { endpoint, status: '200', duration_ms: 123, page_location: address } } - ]); - }); - - it('reports a request that never reached the API as a client error, timed from its start', () => { - const page = browser(address); - const analytics = new Analytics(none); - analytics.requestStarted(); - - analytics.reportApiRequest(endpoint, { type: 'client_error', url, message: 'Failed to fetch' } as never); - - const [entry] = requests(page.dataLayer()); - expect(entry.docs).to.include({ endpoint, status: 'client_error', page_location: address }); - expect(entry.docs.duration_ms).to.be.a('number').within(0, 5000); - }); - - it('carries the endpoint, the status and the duration, and nothing of the request', () => { - const page = browser(address); - const result = { - type: 'response', - url, - status: 401, - duration: 8, - headers: { 'x-key': 's3cret' }, - body: 's3cret' - }; - - new Analytics(none).reportApiRequest(endpoint, result as never); - - const [entry] = requests(page.dataLayer()); - expect(Object.keys(entry.docs).sort()).to.deep.equal(['duration_ms', 'endpoint', 'page_location', 'status']); - expect(JSON.stringify(entry)).to.not.contain('s3cret'); - }); - - it('reports the same result once, however often the display mounts', () => { - const page = browser(address); - const analytics = new Analytics(none); - const result = { type: 'response', url, status: 200, duration: 5 } as never; - - analytics.reportApiRequest(endpoint, result); - analytics.reportApiRequest(endpoint, result); - analytics.reportApiRequest(endpoint, { type: 'response', url, status: 200, duration: 5 } as never); - - expect(requests(page.dataLayer())).to.have.length(2); - }); - - it('reports a request that failed before it was sent with no duration', () => { - const page = browser(address); - - new Analytics(none).reportApiRequest(endpoint, { type: 'client_error', url, message: 'No adapter' } as never); - - expect(requests(page.dataLayer())[0].docs).to.include({ status: 'client_error', duration_ms: 0 }); - }); - - it('times a client error from no start once the playground left the page with a request in flight', () => { - const page = browser(address); - const analytics = new Analytics(none); - analytics.requestStarted(); - analytics.requestAbandoned(); - - analytics.reportApiRequest(endpoint, { type: 'client_error', url, message: 'No adapter' } as never); - - expect(requests(page.dataLayer())[0].docs).to.include({ status: 'client_error', duration_ms: 0 }); - }); - }); }); diff --git a/test/portal-template/api-request.test.ts b/test/portal-template/api-request.test.ts new file mode 100644 index 00000000..a1a8eb1f --- /dev/null +++ b/test/portal-template/api-request.test.ts @@ -0,0 +1,46 @@ +import { expect } from 'chai'; +import type { FetchErrorResult, FetchResponseResult } from 'fumadocs-openapi/playground'; +import { apiRequest } from '../../portal-template/src/lib/api-request'; + +describe('apiRequest', () => { + const endpoint = 'GET /{operation}'; + // The request's own address, which holds filled-in values: never reported. + const url = 'https://api.acme.com/v1/calc/SUM?x=4&api_key=s3cret'; + const response = (status: number, duration: number): FetchResponseResult => ({ + type: 'response', + url, + status, + headers: new globalThis.Headers({ 'x-key': 's3cret' }), + body: new ArrayBuffer(0), + duration, + text: () => 's3cret' + }); + const clientError: FetchErrorResult = { type: 'client_error', url, message: 'Failed to fetch' }; + + it('reports a response by its status and its own duration, rounded', () => { + expect(apiRequest(endpoint, response(200, 123.4), 1000, 9000)).to.deep.equal({ + endpoint, + status: '200', + duration_ms: 123 + }); + }); + + it('times a request that never reached the API from when it was sent', () => { + expect(apiRequest(endpoint, clientError, 1000, 1250)).to.deep.equal({ + endpoint, + status: 'client_error', + duration_ms: 250 + }); + }); + + it('gives no duration to a request that failed before it was sent', () => { + expect(apiRequest(endpoint, clientError, null, 1250)).to.deep.include({ status: 'client_error', duration_ms: 0 }); + }); + + it('carries the endpoint, the status and the duration, and nothing of the request', () => { + const reported = apiRequest(endpoint, response(401, 8), null, 0); + + expect(Object.keys(reported).sort()).to.deep.equal(['duration_ms', 'endpoint', 'status']); + expect(JSON.stringify(reported)).to.not.contain('s3cret'); + }); +}); From fa9358712a5ac65abb19e785e7a3ac125641cb6f Mon Sep 17 00:00:00 2001 From: Muhammad Sohail Date: Fri, 13 Nov 2026 17:34:46 +0500 Subject: [PATCH 56/73] fix(portal): mark the playground dialog from one observer made at startup Mutation observers are told in the order they were made. One made as the bundle starts, before any vendor tag, marks the dialog before a replay tool's observer records it, which one made per mount did not. Co-Authored-By: Claude Opus 5.5 --- portal-template/src/components/playground.tsx | 16 --------------- portal-template/src/lib/portal-analytics.ts | 8 ++++++-- portal-template/src/lib/replay-markers.ts | 20 +++++++++++++++++-- 3 files changed, 24 insertions(+), 20 deletions(-) diff --git a/portal-template/src/components/playground.tsx b/portal-template/src/components/playground.tsx index b18dcf37..9c8918cb 100644 --- a/portal-template/src/components/playground.tsx +++ b/portal-template/src/components/playground.tsx @@ -4,7 +4,6 @@ import type { FetchResult } from 'fumadocs-openapi/playground'; import PlaygroundClient, { DefaultResultDisplay, type ResultDisplayProps } from 'fumadocs-openapi/ui/playground/client'; import { apiRequest } from '@/lib/api-request'; import { analytics } from '@/lib/portal-analytics'; -import { markForReplay } from '@/lib/replay-markers'; /** When this playground last sent a request, for a result that has no duration of its own. */ const SentAt = createContext>({ current: null }); @@ -40,21 +39,6 @@ export default function Playground() { }), [] ); - // Fumadocs renders the dialog outside the marked wrapper, so it is marked as it appears, told from the search - // dialog by the request form in it, until fuma-nama/fumadocs#3824 lets the markers be passed to the dialog directly. - useEffect(() => { - const observer = new MutationObserver((mutations) => { - for (const { addedNodes } of mutations) { - for (const node of addedNodes) { - if (!(node instanceof Element)) continue; - const dialog = node.matches('[role="dialog"]') ? node : node.querySelector('[role="dialog"]'); - if (dialog !== null && dialog.querySelector('form') !== null) markForReplay(dialog); - } - } - }); - observer.observe(document.body, { childList: true, subtree: true }); - return () => observer.disconnect(); - }, []); return ( diff --git a/portal-template/src/lib/portal-analytics.ts b/portal-template/src/lib/portal-analytics.ts index f3e2b126..d23527eb 100644 --- a/portal-template/src/lib/portal-analytics.ts +++ b/portal-template/src/lib/portal-analytics.ts @@ -1,6 +1,10 @@ import { Analytics } from './analytics'; import { portal } from './portal'; +import { markPlaygroundDialogs } from './replay-markers'; export const analytics = new Analytics(portal.analytics); -// When the bundle starts, before React: setup entries first, then the loader. Never during prerendering. -if (typeof window !== 'undefined') analytics.start(); +// When the bundle starts, before React and before any vendor tag. Never during prerendering. +if (typeof window !== 'undefined') { + markPlaygroundDialogs(); + analytics.start(); +} diff --git a/portal-template/src/lib/replay-markers.ts b/portal-template/src/lib/replay-markers.ts index a001a5b1..84524fa1 100644 --- a/portal-template/src/lib/replay-markers.ts +++ b/portal-template/src/lib/replay-markers.ts @@ -7,10 +7,26 @@ export const REPLAY_MARKERS = { 'data-portal-playground': '' } as const; -/** The same markers on an element Fumadocs renders outside the wrapper, such as the playground's dialog. */ -export function markForReplay(element: Element): void { +function markForReplay(element: Element): void { element.classList.add(...REPLAY_MARKERS.className.split(' ')); for (const [name, value] of Object.entries(REPLAY_MARKERS)) { if (name !== 'className') element.setAttribute(name, value); } } + +/** + * Marks the playground's dialog, which Fumadocs renders outside the marked wrapper, as it appears: observers are told + * in the order they were made, so this one, made before any vendor tag, marks it before a replay tool's records it. + */ +export function markPlaygroundDialogs(): void { + new MutationObserver((mutations) => { + for (const { addedNodes } of mutations) { + for (const node of addedNodes) { + if (!(node instanceof Element)) continue; + // Told from the search dialog by its request form, until fuma-nama/fumadocs#3824 takes the markers itself. + const dialog = node.matches('[role="dialog"]') ? node : node.querySelector('[role="dialog"]'); + if (dialog !== null && dialog.querySelector('form') !== null) markForReplay(dialog); + } + } + }).observe(document.body, { childList: true, subtree: true }); +} From 95c8187a2b5a6d545f7d881bbecbede3baf9baf5 Mon Sep 17 00:00:00 2001 From: Muhammad Sohail Date: Fri, 13 Nov 2026 17:34:46 +0500 Subject: [PATCH 57/73] refactor(portal): keep data-portal-playground on the playground wrapper The test hook no longer marks the cURL sample and the dialog, which carry the replay markers alone; the e2e test checks the one element again, with its markers. Co-Authored-By: Claude Opus 5.5 --- portal-template/src/components/api-page.tsx | 2 +- portal-template/src/lib/replay-markers.ts | 3 +-- test/e2e/portal-build.test.ts | 15 +++++++-------- 3 files changed, 9 insertions(+), 11 deletions(-) diff --git a/portal-template/src/components/api-page.tsx b/portal-template/src/components/api-page.tsx index 608e9a02..d828c0d6 100644 --- a/portal-template/src/components/api-page.tsx +++ b/portal-template/src/components/api-page.tsx @@ -21,7 +21,7 @@ export const OpenAPIPage = createOpenAPIPage({ playground: { // Session replay tools a GTM tag loads record the page's text and input; each marker keeps its tool out of the playground. render: () => ( -
+
diff --git a/portal-template/src/lib/replay-markers.ts b/portal-template/src/lib/replay-markers.ts index 84524fa1..49cabc3c 100644 --- a/portal-template/src/lib/replay-markers.ts +++ b/portal-template/src/lib/replay-markers.ts @@ -3,8 +3,7 @@ export const REPLAY_MARKERS = { className: 'ph-no-capture fs-exclude rr-block amp-block', 'data-hj-suppress': '', 'data-clarity-mask': 'True', - 'data-private': '', - 'data-portal-playground': '' + 'data-private': '' } as const; function markForReplay(element: Element): void { diff --git a/test/e2e/portal-build.test.ts b/test/e2e/portal-build.test.ts index 6f5da2a4..b04b52aa 100644 --- a/test/e2e/portal-build.test.ts +++ b/test/e2e/portal-build.test.ts @@ -291,15 +291,14 @@ const stylesheetOf = (output: DirectoryPath) => { } }); - it('prerenders the playground header and the cURL sample beside it inside the elements session replays skip', () => { - const marked = read('api/apimatic-calculator/simple-calculator/Calculate/index.html') - .split('data-portal-playground') - .slice(1); - expect(marked, 'the header and the sample').to.have.length(2); + it('prerenders the operation page’s playground header inside the element session replays skip', () => { + const parts = read('api/apimatic-calculator/simple-calculator/Calculate/index.html').split( + 'data-portal-playground' + ); + expect(parts, 'one element').to.have.length(2); // What Fumadocs' playground renders on the server: its header, with the method, the route and the trigger. - expect(marked[0].slice(0, 2000)).to.match(/>GET<[\s\S]*\{operation\}[\s\S]*aria-haspopup="dialog"/); - // The sample follows what the reader types into the playground, the credentials among it. - expect(marked[1]).to.match(/>curl<[\s\S]*> -X<[\s\S]*> GETGET<[\s\S]*\{operation\}[\s\S]*aria-haspopup="dialog"/); + expect(parts[0].slice(parts[0].lastIndexOf(' { From a7f1c6297c1fbb09a3720ebb02480d9ebfec0f8c Mon Sep 17 00:00:00 2001 From: Muhammad Sohail Date: Fri, 13 Nov 2026 17:34:46 +0500 Subject: [PATCH 58/73] fix(portal): report every code copy from its block's button, by language ID Copies report through each block's Actions slot instead of a document listener: the MDX blocks, which the build names the language of, the API reference's blocks, its Markdown and the playground's, Example Response, and every command block, an SDK card's install command included. language is the ID SDK downloads also send, csharp or shellscript; the IDs and aliases move from shiki-bundle.ts to languages.ts, so a page can read them without loading the highlighter. Co-Authored-By: Claude Opus 5.5 --- .../src/components/api-markdown.tsx | 4 +- portal-template/src/components/api-page.tsx | 3 +- portal-template/src/components/code-copy.tsx | 34 ++++++ .../src/components/command-block.tsx | 22 ++-- .../src/components/example-layout.tsx | 12 +- portal-template/src/components/mdx.tsx | 11 ++ portal-template/src/lib/code-copy.ts | 16 --- portal-template/src/lib/code-titles.ts | 3 +- portal-template/src/lib/languages.ts | 73 ++++++++++++ portal-template/src/lib/rehype-code-titles.ts | 2 +- portal-template/src/lib/shiki-bundle.ts | 44 +------ portal-template/src/lib/source.ts | 4 +- .../src/lib/transformer-language.ts | 16 +++ portal-template/src/routes/__root.tsx | 14 +-- portal-template/vite.config.ts | 4 +- test/portal-template.test.ts | 11 +- test/portal-template/code-copy.test.ts | 107 ------------------ test/portal-template/languages.test.ts | 29 +++++ 18 files changed, 199 insertions(+), 210 deletions(-) create mode 100644 portal-template/src/components/code-copy.tsx delete mode 100644 portal-template/src/lib/code-copy.ts create mode 100644 portal-template/src/lib/languages.ts create mode 100644 portal-template/src/lib/transformer-language.ts delete mode 100644 test/portal-template/code-copy.test.ts create mode 100644 test/portal-template/languages.test.ts diff --git a/portal-template/src/components/api-markdown.tsx b/portal-template/src/components/api-markdown.tsx index 884582c2..e3e26b20 100644 --- a/portal-template/src/components/api-markdown.tsx +++ b/portal-template/src/components/api-markdown.tsx @@ -1,10 +1,10 @@ import { createMarkdownRenderer } from 'fumadocs-core/content/md'; import { remarkGfm } from 'fumadocs-core/mdx-plugins/remark-gfm'; -import { DynamicCodeBlock } from 'fumadocs-ui/components/dynamic-codeblock'; import defaultMdxComponents from 'fumadocs-ui/mdx'; import { Children, type ComponentProps, type ReactElement } from 'react'; import { withBasePath } from '@/lib/base-path'; import { languageOf } from '@/lib/code-titles'; +import { ReportedCodeBlock } from './code-copy'; const { Markdown } = createMarkdownRenderer({ remarkPlugins: [remarkGfm] }); @@ -28,5 +28,5 @@ function CodeBlock({ children }: ComponentProps<'pre'>) { const text = code.props.children; if (typeof text !== 'string') return null; const language = languageOf(code.props.className?.split(' ') ?? []) ?? 'text'; - return ; + return ; } diff --git a/portal-template/src/components/api-page.tsx b/portal-template/src/components/api-page.tsx index d828c0d6..becaa996 100644 --- a/portal-template/src/components/api-page.tsx +++ b/portal-template/src/components/api-page.tsx @@ -5,6 +5,7 @@ import { mediaAdapters } from '@/lib/media-adapters'; import { oauthCallbackPath } from '@/lib/oauth-callback'; import { REPLAY_MARKERS } from '@/lib/replay-markers'; import { ApiMarkdown } from './api-markdown'; +import { ReportedCodeBlock } from './code-copy'; import { renderExampleLayout } from './example-layout'; import { codeUsages, renderUsageTabs } from './usage-tabs'; @@ -15,7 +16,7 @@ export const OpenAPIPage = createOpenAPIPage({ codeUsages, generateTypeScriptDefinitions: false, content: { renderAPIExampleLayout: renderExampleLayout, renderAPIExampleUsageTabs: renderUsageTabs }, - components: { Markdown: ApiMarkdown }, + components: { Markdown: ApiMarkdown, CodeBlock: ReportedCodeBlock }, mediaAdapters, oauthRedirectUrl: withBasePath(oauthCallbackPath), playground: { diff --git a/portal-template/src/components/code-copy.tsx b/portal-template/src/components/code-copy.tsx new file mode 100644 index 00000000..4414d538 --- /dev/null +++ b/portal-template/src/components/code-copy.tsx @@ -0,0 +1,34 @@ +import type { CodeBlockProps as BlockProps } from 'fumadocs-ui/components/codeblock'; +import { DynamicCodeBlock } from 'fumadocs-ui/components/dynamic-codeblock'; +import type { CodeBlockProps } from 'fumadocs-openapi'; +import { languageId } from '@/lib/languages'; +import { analytics } from '@/lib/portal-analytics'; + +type Actions = NonNullable; + +export const reportCodeCopy = (language: string) => + analytics.report('docs_code_copy', { language: languageId(language) }); + +// Fumadocs' own, which any Actions a block is given replaces. +const DefaultActions: Actions = ({ className, children }) => ( +
{children}
+); + +/** A block's Actions slot, which Fumadocs hands the copy button: a click on it calls `onCopy`. */ +export function reportCopies(onCopy: () => void, Actions: Actions = DefaultActions): Actions { + return ({ className, children }) => + Actions({ + className, + children: children && ( + + {children} + + ) + }); +} + +/** Fumadocs' highlighted block, as the API reference renders each, reporting its copies with its language. */ +export function ReportedCodeBlock({ codeblock, ...props }: CodeBlockProps) { + const Actions = reportCopies(() => reportCodeCopy(props.lang), codeblock?.Actions); + return ; +} diff --git a/portal-template/src/components/command-block.tsx b/portal-template/src/components/command-block.tsx index 327d84d3..19b54ddf 100644 --- a/portal-template/src/components/command-block.tsx +++ b/portal-template/src/components/command-block.tsx @@ -2,12 +2,13 @@ import type { ReactNode } from 'react'; import { asMarkdown } from 'fumadocs-core/server'; import { CodeBlock, Pre } from 'fumadocs-ui/components/codeblock'; import { CODE_BLOCK_TITLES } from '@/lib/code-titles'; +import { reportCodeCopy, reportCopies } from './code-copy'; interface CommandBlockProps { command: string; /** One line that truncates, for a card; the full command is still what the button copies. */ compact?: boolean; - /** Called as the copy button is clicked. */ + /** Called as the copy button is clicked; a copy of a shell command otherwise. */ onCopy?: () => void; } @@ -17,24 +18,15 @@ function CentredActions({ children }: Readonly<{ children?: ReactNode }>) { } /** One shell command in a copyable block: an MDX page has no highlighter to hand, so it is plain. */ -export function CommandBlock({ command, compact = false, onCopy }: Readonly) { +const reportShellCopy = () => reportCodeCopy('shellscript'); + +export function CommandBlock({ command, compact = false, onCopy = reportShellCopy }: Readonly) { if (asMarkdown()) { return `\`\`\`bash\n${command}\n\`\`\``; } if (!compact) { return ( - // Fumadocs calls Actions as a function with its copy button as the children, so a wrapper sees the click. - ( -
- {children} -
- )) - } - > +
           
             {/* A highlighted block's lines carry this class, which is what the block pads. */}
@@ -48,7 +40,7 @@ export function CommandBlock({ command, compact = false, onCopy }: Readonly
       
         
diff --git a/portal-template/src/components/example-layout.tsx b/portal-template/src/components/example-layout.tsx
index 8c904800..aa3c0a31 100644
--- a/portal-template/src/components/example-layout.tsx
+++ b/portal-template/src/components/example-layout.tsx
@@ -1,9 +1,10 @@
-import { createContext, useContext, useMemo, useState, type ReactNode } from 'react';
+import { createContext, useContext, useMemo, useState, type MouseEvent, type ReactNode } from 'react';
 import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from '@fumadocs/api-docs/components/select';
 import { useOpenAPI } from 'fumadocs-openapi';
 import { useExampleRequests, useOperation } from 'fumadocs-openapi/operation';
 import { CodeSample } from '@/lib/code-samples';
 import { Parameter, requestExamples, type RequestExample } from '@/lib/request-examples';
+import { reportCodeCopy } from './code-copy';
 
 interface ExampleSelection {
   operation: unknown;
@@ -20,6 +21,11 @@ interface LayoutSlots {
 
 const SelectionContext = createContext(undefined);
 
+// "Example Response" copies through a button of Fumadocs' own in the card's header, which takes no callback.
+const reportResponseCopy = (event: MouseEvent) => {
+  if (event.target instanceof Element && event.target.closest('button[aria-live]') !== null) reportCodeCopy('json');
+};
+
 export function useExampleSelection(): ExampleSelection {
   const selection = useContext(SelectionContext);
   if (selection === undefined) throw new Error('useExampleSelection needs an ExampleLayout above it');
@@ -63,7 +69,9 @@ function ExampleLayout({ selector, usageTabs, responseTabs }: Readonly
         {selector === null ? null : }
         {usageTabs}
-        {responseTabs}
+        
+ {responseTabs} +
); diff --git a/portal-template/src/components/mdx.tsx b/portal-template/src/components/mdx.tsx index 8661f5e6..cbd8b5b8 100644 --- a/portal-template/src/components/mdx.tsx +++ b/portal-template/src/components/mdx.tsx @@ -1,10 +1,13 @@ +import type { HTMLAttributes } from 'react'; import defaultMdxComponents from 'fumadocs-ui/mdx'; import { Accordion, Accordions } from 'fumadocs-ui/components/accordion'; +import { CodeBlock, Pre } from 'fumadocs-ui/components/codeblock'; import { File, Files, Folder } from 'fumadocs-ui/components/files'; import { InlineTOC } from 'fumadocs-ui/components/inline-toc'; import { Step, Steps } from 'fumadocs-ui/components/steps'; import { Tab, Tabs } from 'fumadocs-ui/components/tabs'; import { TypeTable } from 'fumadocs-ui/components/type-table'; +import { reportCodeCopy, reportCopies } from './code-copy'; import { PluginInstall } from './plugin-install'; import { PluginLanguage, PluginLanguages, PluginPlatforms } from './plugin-support'; import { SdkActions } from './sdk-actions'; @@ -12,9 +15,17 @@ import { SdkCard, SdkCards } from './sdk-cards'; type MDXComponents = Record; +type HighlightedPre = HTMLAttributes & { 'data-language'?: string }; + export function getMDXComponents(components?: MDXComponents) { return { ...defaultMdxComponents, + // Fumadocs' own, its copy button reporting the language the build names on the block. + pre: ({ 'data-language': language = 'plaintext', ...props }: HighlightedPre) => ( + reportCodeCopy(language))}> +
{props.children}
+
+ ), // Fumadocs' components beyond its defaults, so an author's page can use them without importing. Accordion, Accordions, diff --git a/portal-template/src/lib/code-copy.ts b/portal-template/src/lib/code-copy.ts deleted file mode 100644 index 3a7d9f4c..00000000 --- a/portal-template/src/lib/code-copy.ts +++ /dev/null @@ -1,16 +0,0 @@ -/** - * The language of the code block whose copy button a click hit: a titled block's caption, or the selected tab's - * name when the block is one of a tabbed set. Null for a block with neither, and for any other click. - */ -export function copiedLanguage(target: EventTarget | null): string | null { - const button = target !== null && 'closest' in target ? (target as Element).closest('figure button') : null; - if (button === null) return null; - // Not a copy: a dropdown in a block's header, the playground's dialog, or a block that reports its own copy. - if (button.matches('[role="combobox"]') || button.matches('[aria-haspopup]')) return null; - if (button.closest('[role="dialog"]') !== null || button.closest('[data-copy-reported]') !== null) return null; - const figure = button.closest('figure'); - const caption = figure?.querySelector('figcaption')?.textContent?.trim(); - if (caption) return caption; - const tabs = figure?.closest('[role="tabpanel"]')?.parentElement; - return tabs?.querySelector('[role="tab"][aria-selected="true"]')?.textContent?.trim() || null; -} diff --git a/portal-template/src/lib/code-titles.ts b/portal-template/src/lib/code-titles.ts index 6d6cdbca..73005bf3 100644 --- a/portal-template/src/lib/code-titles.ts +++ b/portal-template/src/lib/code-titles.ts @@ -1,5 +1,4 @@ -// A type alone, so a page naming a title does not load the highlighter the bundle builds. -import type { BundledLanguage } from './shiki-bundle'; +import type { BundledLanguage } from './languages'; /** What a code block's header calls its language; a shell is named for where the command runs. */ export const CODE_BLOCK_TITLES: Readonly> = { diff --git a/portal-template/src/lib/languages.ts b/portal-template/src/lib/languages.ts new file mode 100644 index 00000000..d66cce47 --- /dev/null +++ b/portal-template/src/lib/languages.ts @@ -0,0 +1,73 @@ +/** The languages the portal highlights, by Shiki's IDs; apart from `shiki-bundle.ts`, so naming one loads no grammar. */ +export const BUNDLED_LANGUAGES = [ + // The seven the CLI generates SDKs for (src/types/sdk/generate.ts). + 'csharp', + 'go', + 'java', + 'php', + 'python', + 'ruby', + 'typescript', + + // Shell commands, and the shapes a response or a specification is shown in. + 'http', + 'json', + 'jsonc', + 'shellscript', + 'shellsession', + 'xml', + 'yaml', + + // What the Markdown pages beside the reference are written in. + 'css', + 'diff', + 'graphql', + 'html', + 'javascript', + 'jsx', + 'markdown', + 'sql', + 'tsx' +] as const; + +export type BundledLanguage = (typeof BUNDLED_LANGUAGES)[number]; + +/** + * Shiki's own bundle resolves `ts` or `yml` through an alias table beside its grammars; a + * hand-built map has none, so an alias reaches Fumadocs as an unknown language and is replaced + * with `text`. Taken from Shiki's `bundledLanguagesInfo`; `test/portal-template.test.ts` holds + * them to it. + */ +export const languageAliases: Readonly> = { + 'c#': 'csharp', + cs: 'csharp', + py: 'python', + rb: 'ruby', + ts: 'typescript', + cts: 'typescript', + mts: 'typescript', + js: 'javascript', + cjs: 'javascript', + mjs: 'javascript', + bash: 'shellscript', + sh: 'shellscript', + shell: 'shellscript', + zsh: 'shellscript', + console: 'shellsession', + yml: 'yaml', + md: 'markdown', + gql: 'graphql' +}; + +/** The grammar a fence's language names, by its own name or an alias; null for one not bundled. */ +export function bundledLanguage(name: string): BundledLanguage | null { + if ((BUNDLED_LANGUAGES as readonly string[]).includes(name)) { + return name as BundledLanguage; + } + return Object.hasOwn(languageAliases, name) ? languageAliases[name] : null; +} + +/** A block's language as the portal reports it: the bundle's ID for a name or alias it knows, else the name as given. */ +export function languageId(name: string): string { + return bundledLanguage(name) ?? name; +} diff --git a/portal-template/src/lib/rehype-code-titles.ts b/portal-template/src/lib/rehype-code-titles.ts index e563fe26..01fd1ec1 100644 --- a/portal-template/src/lib/rehype-code-titles.ts +++ b/portal-template/src/lib/rehype-code-titles.ts @@ -1,6 +1,6 @@ import { parseCodeBlockAttributes } from 'fumadocs-core/mdx-plugins/codeblock-utils'; import { CODE_BLOCK_TITLES, languageOf } from './code-titles'; -import { bundledLanguage } from './shiki-bundle'; +import { bundledLanguage } from './languages'; interface HastNode { type: string; diff --git a/portal-template/src/lib/shiki-bundle.ts b/portal-template/src/lib/shiki-bundle.ts index 2ab73b5c..e5e02869 100644 --- a/portal-template/src/lib/shiki-bundle.ts +++ b/portal-template/src/lib/shiki-bundle.ts @@ -1,5 +1,6 @@ import { createBundledHighlighter } from 'shiki/core'; import { createJavaScriptRegexEngine } from 'shiki/engine/javascript'; +import { languageAliases, type BundledLanguage } from './languages'; // Re-exported untouched: Fumadocs imports it from the `shiki` entry point this file stands // in for, though the bundle itself builds its highlighter on the JavaScript engine. @@ -44,49 +45,12 @@ const languages = { markdown: () => import('shiki/dist/langs/markdown.mjs'), sql: () => import('shiki/dist/langs/sql.mjs'), tsx: () => import('shiki/dist/langs/tsx.mjs') -} satisfies Record; - -/** - * Shiki's own bundle resolves `ts` or `yml` through an alias table beside its grammars; a - * hand-built map has none, so an alias reaches Fumadocs as an unknown language and is replaced - * with `text`. Each shares its grammar's import, as Shiki's `bundledLanguagesAlias` does, so - * the bundler still emits one chunk per language rather than one per spelling. Taken from - * Shiki's `bundledLanguagesInfo`; `test/portal-template.test.ts` holds them to it. - */ -const aliases: Record = { - 'c#': 'csharp', - cs: 'csharp', - py: 'python', - rb: 'ruby', - ts: 'typescript', - cts: 'typescript', - mts: 'typescript', - js: 'javascript', - cjs: 'javascript', - mjs: 'javascript', - bash: 'shellscript', - sh: 'shellscript', - shell: 'shellscript', - zsh: 'shellscript', - console: 'shellsession', - yml: 'yaml', - md: 'markdown', - gql: 'graphql' -}; - -export type BundledLanguage = keyof typeof languages; - -/** The grammar a fence's language names, by its own name or an alias; null for one not bundled. */ -export function bundledLanguage(name: string): BundledLanguage | null { - if (Object.hasOwn(languages, name)) { - return name as BundledLanguage; - } - return Object.hasOwn(aliases, name) ? aliases[name] : null; -} +} satisfies Record; +// Each alias shares its grammar's import, as Shiki's `bundledLanguagesAlias` does: one chunk per language, not per spelling. const bundledLanguages = { ...languages, - ...Object.fromEntries(Object.entries(aliases).map(([alias, id]) => [alias, languages[id]])) + ...Object.fromEntries(Object.entries(languageAliases).map(([alias, id]) => [alias, languages[id]])) } as never; /** The two Fumadocs asks for by default; the rest of Shiki's themes are never requested. */ diff --git a/portal-template/src/lib/source.ts b/portal-template/src/lib/source.ts index f6eae85e..e239a140 100644 --- a/portal-template/src/lib/source.ts +++ b/portal-template/src/lib/source.ts @@ -1,9 +1,9 @@ import { defineDocs } from 'fumadocs-mdx/macro'; import { applyMdxPreset } from 'fumadocs-mdx/config'; -import { rehypeCodeDefaultOptions } from 'fumadocs-core/mdx-plugins'; import rehypeRaw from 'rehype-raw'; import { rehypeCodeTitles, rehypeKeepCodeMeta } from './rehype-code-titles'; import { navigationSchema } from './navigation-schema'; +import { rehypeCodeOptions } from './transformer-language'; // What `rehype-raw` must hand on untouched, being MDX's own nodes rather than HTML. const MDX_NODE_TYPES = ['mdxFlowExpression', 'mdxJsxFlowElement', 'mdxJsxTextElement', 'mdxTextExpression', 'mdxjsEsm']; @@ -35,7 +35,7 @@ export const generated = defineDocs({ // A remote image is never fetched for its size, which would make the build depend on its host. remarkImageOptions: { external: false }, // The SDK pages' design heads a block with its title alone, without Fumadocs' language icon. - rehypeCodeOptions: { ...rehypeCodeDefaultOptions, icon: false }, + rehypeCodeOptions: { ...rehypeCodeOptions, icon: false }, // The SDK docs' HTML fails the build unrendered; not sanitized, as it comes from the owner's own spec. // The titles go in after it, and ahead of `rehypeCode`, the first of the defaults, which reads them. rehypePlugins: (defaults) => [ diff --git a/portal-template/src/lib/transformer-language.ts b/portal-template/src/lib/transformer-language.ts new file mode 100644 index 00000000..be12cf34 --- /dev/null +++ b/portal-template/src/lib/transformer-language.ts @@ -0,0 +1,16 @@ +import { rehypeCodeDefaultOptions } from 'fumadocs-core/mdx-plugins'; +import type { ShikiTransformer } from 'shiki'; + +/** Names each highlighted block's language on its `pre`, which the MDX `pre` hands to the block's copy button. */ +export const transformerLanguage: ShikiTransformer = { + name: 'portal:language', + pre(node) { + node.properties['data-language'] = this.options.lang; + } +}; + +/** Fumadocs' code options for every collection, with each block's language named for its copy button. */ +export const rehypeCodeOptions = { + ...rehypeCodeDefaultOptions, + transformers: [...(rehypeCodeDefaultOptions.transformers ?? []), transformerLanguage] +}; diff --git a/portal-template/src/routes/__root.tsx b/portal-template/src/routes/__root.tsx index 7c1c4820..687bcd48 100644 --- a/portal-template/src/routes/__root.tsx +++ b/portal-template/src/routes/__root.tsx @@ -7,7 +7,6 @@ import appCss from '@/styles/app.css?url'; import { RootProvider } from 'fumadocs-ui/provider/tanstack'; import SearchDialog from '@/components/search'; import { withBasePath } from '@/lib/base-path'; -import { copiedLanguage } from '@/lib/code-copy'; import { portal } from '@/lib/portal'; import { analytics } from '@/lib/portal-analytics'; @@ -28,12 +27,6 @@ const iconLinks = portal.favicon ] : []; -// Fumadocs' copy button has no callback of its own, so the document hears every click. -const reportCodeCopy = (event: MouseEvent) => { - const language = copiedLanguage(event.target); - if (language !== null) analytics.report('docs_code_copy', { language }); -}; - // A portal fixed to one mode keeps to it whatever the visitor's system prefers, and offers no // way out: the layout hides the switch, and the `D` hotkey is turned off here. const theme = @@ -64,12 +57,7 @@ function RootComponent() { // A prerendered page mounts with the router idle and raises no `onRendered` for its first page, so it // is reported here; `portal serve` mounts pending, before the page's head applies, and `onRendered` follows. if (router.state.status === 'idle') analytics.reportPageView(); - const unsubscribe = router.subscribe('onRendered', () => analytics.reportPageView()); - document.addEventListener('click', reportCodeCopy); - return () => { - unsubscribe(); - document.removeEventListener('click', reportCodeCopy); - }; + return router.subscribe('onRendered', () => analytics.reportPageView()); }, [router]); return ( diff --git a/portal-template/vite.config.ts b/portal-template/vite.config.ts index 1151c6ff..9fd1975e 100644 --- a/portal-template/vite.config.ts +++ b/portal-template/vite.config.ts @@ -12,6 +12,7 @@ import { prerenderPages } from './prerender-pages.ts'; import { remarkJsxImages } from './remark-jsx-images.ts'; import { specReload } from './spec-reload.ts'; import { remarkImageReferences } from './src/lib/remark-image-references.ts'; +import { rehypeCodeOptions } from './src/lib/transformer-language.ts'; import { staticFunctionsBase } from './static-functions-base.ts'; import { staticImages } from './static-images.ts'; @@ -37,7 +38,8 @@ export default defineConfig(async ({ command, isPreview }) => { mdxOptions: { remarkImageOptions: { publicDir: publicDir || undefined, external: false }, // A function, so it runs ahead of the preset's own plugins, `remarkImage` among them. - remarkPlugins: (plugins) => [remarkImageReferences, [remarkJsxImages, { publicDir }], ...plugins] + remarkPlugins: (plugins) => [remarkImageReferences, [remarkJsxImages, { publicDir }], ...plugins], + rehypeCodeOptions } } }), diff --git a/test/portal-template.test.ts b/test/portal-template.test.ts index 5c5c4f32..51aba568 100644 --- a/test/portal-template.test.ts +++ b/test/portal-template.test.ts @@ -16,6 +16,7 @@ import { GENERATED_INCLUDES_DIRECTORY_NAME } from '../src/types/portal/page-frag import { PortalIdentity } from '../src/types/portal/portal-config'; import type { BuildPaths } from '../portal-template/portal-config'; import type { CodeSamplesFile as TemplateCodeSamplesFile } from '../portal-template/src/lib/code-samples.server'; +import { languageAliases } from '../portal-template/src/lib/languages'; import type { Portal } from '../portal-template/src/lib/portal-types'; /** True only when the two types are identical, every nested field and union member included. */ @@ -232,12 +233,7 @@ describe('portal template packaging', () => { /** The language ids the bundle imports a grammar for. */ const bundledIds = (): string[] => [...source().matchAll(/shiki\/dist\/langs\/([\w-]+)\.mjs/g)].map((m) => m[1]); - const keys = (): Set => { - const text = source(); - const block = /const aliases[^{]*{([\s\S]*?)\n};/.exec(text); - const aliasKeys = [...(block?.[1] ?? '').matchAll(/^\s*'?([\w#-]+)'?\s*:/gm)].map((m) => m[1]); - return new Set([...bundledIds(), ...aliasKeys]); - }; + const keys = (): Set => new Set([...bundledIds(), ...Object.keys(languageAliases)]); it('names every grammar it imports by a file that exists', async () => { const shiki = path.dirname(createRequire(import.meta.url).resolve('shiki/package.json')); @@ -265,8 +261,7 @@ describe('portal template packaging', () => { }); it('points every alias at a language it actually bundles', () => { - const block = /const aliases[^{]*{([\s\S]*?)\n};/.exec(source()); - const targets = [...(block?.[1] ?? '').matchAll(/:\s*'([\w-]+)'/g)].map((m) => m[1]); + const targets = Object.values(languageAliases); const bundled = new Set(bundledIds()); expect(targets).to.not.be.empty; diff --git a/test/portal-template/code-copy.test.ts b/test/portal-template/code-copy.test.ts deleted file mode 100644 index 27e579f9..00000000 --- a/test/portal-template/code-copy.test.ts +++ /dev/null @@ -1,107 +0,0 @@ -import { expect } from 'chai'; -import { copiedLanguage } from '../../portal-template/src/lib/code-copy'; - -/** As much of an element as the copy reader walks: the selectors it matches, its text, and its place in the tree. */ -class FakeElement { - public parentElement: FakeElement | null = null; - - public constructor( - private readonly selectors: string[], - public readonly textContent: string | null = null, - private readonly children: FakeElement[] = [] - ) { - for (const child of children) child.parentElement = this; - } - - public matches(selector: string): boolean { - return this.selectors.includes(selector); - } - - public closest(selector: string): FakeElement | null { - return this.selectors.includes(selector) ? this : this.parentElement?.closest(selector) ?? null; - } - - public querySelector(selector: string): FakeElement | null { - for (const child of this.children) { - const found = child.selectors.includes(selector) ? child : child.querySelector(selector); - if (found !== null) return found; - } - return null; - } -} - -const element = (fake: FakeElement) => fake as unknown as Parameters[0]; - -/** Fumadocs' code block: a figure with the copy button in its header beside the caption, or in its corner when untitled. */ -function codeBlock(title: string | null) { - const button = new FakeElement(['figure button']); - const caption = title === null ? [] : [new FakeElement(['figcaption'], title)]; - const figure = new FakeElement(['figure'], null, [new FakeElement([], null, [...caption, button])]); - return { figure, button }; -} - -/** A tabbed set of untitled blocks under one root, with `selected` shown: the copy button of the block that is. */ -function tabbedBlocks(names: string[], selected: string): FakeElement { - const tabs = names.map( - (name) => - new FakeElement( - name === selected ? ['[role="tab"]', '[role="tab"][aria-selected="true"]'] : ['[role="tab"]'], - name - ) - ); - const blocks = names.map(() => codeBlock(null)); - const panels = blocks.map(({ figure }) => new FakeElement(['[role="tabpanel"]'], null, [figure])); - new FakeElement([], null, [new FakeElement(['[role="tablist"]'], null, tabs), ...panels]); - return blocks[names.indexOf(selected)].button; -} - -describe('copiedLanguage', () => { - it('reads a titled block’s caption', () => { - expect(copiedLanguage(element(codeBlock('TypeScript').button))).to.equal('TypeScript'); - }); - - it('reads the selected tab’s name for a block in a tabbed set', () => { - expect(copiedLanguage(element(tabbedBlocks(['cURL', 'TypeScript'], 'TypeScript')))).to.equal('TypeScript'); - expect(copiedLanguage(element(tabbedBlocks(['cURL', 'TypeScript'], 'cURL')))).to.equal('cURL'); - }); - - it('prefers the caption of a titled block inside a tabbed set', () => { - const { figure, button } = codeBlock('Terminal'); - const tab = new FakeElement(['[role="tab"]', '[role="tab"][aria-selected="true"]'], 'macOS'); - new FakeElement([], null, [ - new FakeElement(['[role="tablist"]'], null, [tab]), - new FakeElement(['[role="tabpanel"]'], null, [figure]) - ]); - - expect(copiedLanguage(element(button))).to.equal('Terminal'); - }); - - it('is null for a block with neither, for a click outside any block, and for a click with no target', () => { - expect(copiedLanguage(element(codeBlock(null).button))).to.be.null; - expect(copiedLanguage(element(new FakeElement(['button'])))).to.be.null; - expect(copiedLanguage(null)).to.be.null; - }); - - it('is null in a block that reports its own copy', () => { - const own = codeBlock('Terminal'); - // The install command's wrapper marks its block. - new FakeElement(['[data-copy-reported]'], null, [own.figure]); - - expect(copiedLanguage(element(own.button))).to.be.null; - }); - - it('is null for a dropdown in a block’s header, and for anything in the playground’s dialog', () => { - const dropdown = new FakeElement(['figure button', '[role="combobox"]']); - new FakeElement(['figure'], null, [ - new FakeElement([], null, [new FakeElement(['figcaption'], 'Request'), dropdown]) - ]); - const menu = new FakeElement(['figure button', '[aria-haspopup]']); - new FakeElement(['figure'], null, [new FakeElement(['figcaption'], 'JSON'), menu]); - const inDialog = codeBlock('Body'); - new FakeElement(['[role="dialog"]'], null, [inDialog.figure]); - - expect(copiedLanguage(element(dropdown))).to.be.null; - expect(copiedLanguage(element(menu))).to.be.null; - expect(copiedLanguage(element(inDialog.button))).to.be.null; - }); -}); diff --git a/test/portal-template/languages.test.ts b/test/portal-template/languages.test.ts new file mode 100644 index 00000000..a0dea2fe --- /dev/null +++ b/test/portal-template/languages.test.ts @@ -0,0 +1,29 @@ +import { expect } from 'chai'; +import { languageId } from '../../portal-template/src/lib/languages'; +import { Language } from '../../src/types/sdk/generate'; + +describe('languageId', () => { + // A download sends the language's key in `languages`, a copy this: one GA4 dimension holds both. + it('is the key of every language the CLI generates an SDK in', () => { + for (const language of Object.values(Language)) { + expect(languageId(language)).to.equal(language); + } + }); + + it('names a language by its ID, whichever alias the block was written with', () => { + expect(['ts', 'cs', 'c#', 'py', 'bash', 'sh', 'yml'].map(languageId)).to.deep.equal([ + 'typescript', + 'csharp', + 'csharp', + 'python', + 'shellscript', + 'shellscript', + 'yaml' + ]); + }); + + it('keeps a language the bundle does not know as it was written', () => { + expect(languageId('plaintext')).to.equal('plaintext'); + expect(languageId('rust')).to.equal('rust'); + }); +}); From 97d7df2c167f938e632cfd307bd54b328fe66b54 Mon Sep 17 00:00:00 2001 From: Muhammad Sohail Date: Fri, 13 Nov 2026 17:34:46 +0500 Subject: [PATCH 59/73] test(portal): decide a search's report in a function, and test its sequences searchOutcome() takes the dialog's open, loading, typed and picked state; the dialog keeps the refs. Co-Authored-By: Claude Opus 5.5 --- portal-template/src/components/search.tsx | 21 ++++++---- portal-template/src/lib/search-report.ts | 26 +++++++++++++ test/portal-template/search-report.test.ts | 45 ++++++++++++++++++++++ 3 files changed, 84 insertions(+), 8 deletions(-) create mode 100644 portal-template/src/lib/search-report.ts create mode 100644 test/portal-template/search-report.test.ts diff --git a/portal-template/src/components/search.tsx b/portal-template/src/components/search.tsx index 7d1a5811..f092afe3 100644 --- a/portal-template/src/components/search.tsx +++ b/portal-template/src/components/search.tsx @@ -17,6 +17,7 @@ import { useI18n } from 'fumadocs-ui/contexts/i18n'; import { useEffect, useMemo, useRef } from 'react'; import { withBasePath } from '@/lib/base-path'; import { analytics } from '@/lib/portal-analytics'; +import { searchOutcome } from '@/lib/search-report'; export default function DefaultSearchDialog(props: SharedProps) { const { locale } = useI18n(); @@ -46,18 +47,22 @@ export default function DefaultSearchDialog(props: SharedProps) { openedAt.current = window.location.href; }, [props.open]); - // A close is seen from the prop, which the hotkey changes too. Fumadocs hands over the pick before the close - // renders, and the last keystrokes' results may still be loading, so the report waits for the results shown. + // A close is seen from the prop, which the hotkey changes too. useEffect(() => { - if (props.open || !wasOpen.current || query.isLoading) return; + if (!wasOpen.current) return; + const outcome = searchOutcome({ + open: props.open, + loading: query.isLoading, + typed: typed.current, + picked: picked.current, + term: search, + resultCount: results?.length ?? 0 + }); + if (!outcome.ended) return; wasOpen.current = false; - const search_term = search.trim(); - if ((typed.current || picked.current !== '') && search_term !== '') { - const result_count = results?.length ?? 0; - analytics.report('docs_search', { search_term, result: picked.current, result_count }, openedAt.current); - } typed.current = false; picked.current = ''; + if (outcome.report !== null) analytics.report('docs_search', outcome.report, openedAt.current); }, [props.open, query.isLoading, search, results]); const onSearchChange = (value: string) => { diff --git a/portal-template/src/lib/search-report.ts b/portal-template/src/lib/search-report.ts new file mode 100644 index 00000000..0e7d4ae5 --- /dev/null +++ b/portal-template/src/lib/search-report.ts @@ -0,0 +1,26 @@ +import type { PortalEvents } from './analytics'; + +/** The search dialog on a render after it opened. */ +export interface SearchDialogState { + open: boolean; + /** The last keystrokes' results are still on their way. */ + loading: boolean; + typed: boolean; + /** The address of the result picked, or empty. */ + picked: string; + term: string; + resultCount: number; +} + +export type SearchOutcome = { ended: false } | { ended: true; report: PortalEvents['docs_search'] | null }; + +/** A search ends once the dialog has closed with its results in; it reports when the reader typed or picked a term. */ +export function searchOutcome(state: SearchDialogState): SearchOutcome { + if (state.open || state.loading) return { ended: false }; + const search_term = state.term.trim(); + const counted = (state.typed || state.picked !== '') && search_term !== ''; + return { + ended: true, + report: counted ? { search_term, result: state.picked, result_count: state.resultCount } : null + }; +} diff --git a/test/portal-template/search-report.test.ts b/test/portal-template/search-report.test.ts new file mode 100644 index 00000000..c1bcfaec --- /dev/null +++ b/test/portal-template/search-report.test.ts @@ -0,0 +1,45 @@ +import { expect } from 'chai'; +import { searchOutcome, type SearchDialogState } from '../../portal-template/src/lib/search-report'; + +describe('searchOutcome', () => { + const closed: SearchDialogState = { + open: false, + loading: false, + typed: true, + picked: '', + term: 'pets', + resultCount: 3 + }; + + it('waits while the dialog is open, and while the last keystrokes’ results load after it closed', () => { + expect(searchOutcome({ ...closed, open: true })).to.deep.equal({ ended: false }); + expect(searchOutcome({ ...closed, loading: true })).to.deep.equal({ ended: false }); + }); + + it('reports a typed term with the count shown once the results are in', () => { + expect(searchOutcome(closed)).to.deep.equal({ + ended: true, + report: { search_term: 'pets', result: '', result_count: 3 } + }); + }); + + // Fumadocs hands over the pick before the close renders, so a pick made with the hotkey's term counts too. + it('reports the result picked, typed or not', () => { + expect(searchOutcome({ ...closed, typed: false, picked: '/api/pets/listPets' })).to.deep.equal({ + ended: true, + report: { search_term: 'pets', result: '/api/pets/listPets', result_count: 3 } + }); + }); + + it('ends without a report when the reader neither typed nor picked, or left no term', () => { + expect(searchOutcome({ ...closed, typed: false })).to.deep.equal({ ended: true, report: null }); + expect(searchOutcome({ ...closed, term: ' ' })).to.deep.equal({ ended: true, report: null }); + }); + + it('reports the term without the spaces around it', () => { + expect(searchOutcome({ ...closed, term: ' list pets ' })).to.have.nested.property( + 'report.search_term', + 'list pets' + ); + }); +}); From 07092fd79ca38c61cec06072d1f4844002bd9d3e Mon Sep 17 00:00:00 2001 From: Muhammad Sohail Date: Fri, 13 Nov 2026 17:34:47 +0500 Subject: [PATCH 60/73] fix(portal): show the endpoint bar while the playground loads A first client-side visit to an operation page showed nothing in the playground's place until its chunk loaded; Fumadocs shows its endpoint bar there, which it does not export, so the template draws the same. Co-Authored-By: Claude Opus 5.5 --- portal-template/src/components/api-page.tsx | 5 +-- .../src/components/endpoint-bar.tsx | 35 +++++++++++++++++++ 2 files changed, 38 insertions(+), 2 deletions(-) create mode 100644 portal-template/src/components/endpoint-bar.tsx diff --git a/portal-template/src/components/api-page.tsx b/portal-template/src/components/api-page.tsx index becaa996..4ec3c519 100644 --- a/portal-template/src/components/api-page.tsx +++ b/portal-template/src/components/api-page.tsx @@ -6,6 +6,7 @@ import { oauthCallbackPath } from '@/lib/oauth-callback'; import { REPLAY_MARKERS } from '@/lib/replay-markers'; import { ApiMarkdown } from './api-markdown'; import { ReportedCodeBlock } from './code-copy'; +import { EndpointBar } from './endpoint-bar'; import { renderExampleLayout } from './example-layout'; import { codeUsages, renderUsageTabs } from './usage-tabs'; @@ -21,9 +22,9 @@ export const OpenAPIPage = createOpenAPIPage({ oauthRedirectUrl: withBasePath(oauthCallbackPath), playground: { // Session replay tools a GTM tag loads record the page's text and input; each marker keeps its tool out of the playground. - render: () => ( + render: ({ method, path }) => (
- + }>
diff --git a/portal-template/src/components/endpoint-bar.tsx b/portal-template/src/components/endpoint-bar.tsx new file mode 100644 index 00000000..85890ea2 --- /dev/null +++ b/portal-template/src/components/endpoint-bar.tsx @@ -0,0 +1,35 @@ +const METHOD_COLORS: Record = { + PUT: 'text-yellow-600 dark:text-yellow-400', + PATCH: 'text-orange-600 dark:text-orange-400', + POST: 'text-blue-600 dark:text-blue-400', + DELETE: 'text-red-600 dark:text-red-400' +}; + +/** Fumadocs' endpoint bar, which it shows while the playground loads but does not export: the method and the route. */ +export function EndpointBar({ method, route }: Readonly<{ method: string; route: string }>) { + const verb = method.toUpperCase(); + return ( +
+ + {verb} + +
+ {route.split(/(\{[^}]*\}|\/)/).map((part, index) => { + if (index % 2 === 0) return part; + if (part === '/') { + return ( + + / + + ); + } + return ( + + {part} + + ); + })} +
+
+ ); +} From 94e99c2b409d300b1f9768960200696776e99a8a Mon Sep 17 00:00:00 2001 From: Muhammad Sohail Date: Fri, 13 Nov 2026 17:34:47 +0500 Subject: [PATCH 61/73] refactor(portal): cut the analytics comments to one line each Comments that restated the code go; the rest say why in one line. Co-Authored-By: Claude Opus 5.5 --- portal-template/src/components/api-page.tsx | 1 - portal-template/src/components/usage-tabs.tsx | 3 +- portal-template/src/lib/analytics.ts | 29 +++++-------------- portal-template/src/lib/languages.ts | 7 +---- portal-template/src/lib/replay-markers.ts | 5 +--- portal-template/src/lib/vendor-tags.ts | 14 ++------- portal-template/src/routes/__root.tsx | 3 +- 7 files changed, 14 insertions(+), 48 deletions(-) diff --git a/portal-template/src/components/api-page.tsx b/portal-template/src/components/api-page.tsx index 4ec3c519..6b135aab 100644 --- a/portal-template/src/components/api-page.tsx +++ b/portal-template/src/components/api-page.tsx @@ -21,7 +21,6 @@ export const OpenAPIPage = createOpenAPIPage({ mediaAdapters, oauthRedirectUrl: withBasePath(oauthCallbackPath), playground: { - // Session replay tools a GTM tag loads record the page's text and input; each marker keeps its tool out of the playground. render: ({ method, path }) => (
}> diff --git a/portal-template/src/components/usage-tabs.tsx b/portal-template/src/components/usage-tabs.tsx index 776ed526..43cb1d7b 100644 --- a/portal-template/src/components/usage-tabs.tsx +++ b/portal-template/src/components/usage-tabs.tsx @@ -65,8 +65,7 @@ function SampleCode({ sample }: Readonly<{ sample: CodeSample }>) { return ; } -// Follows the playground's edits to the selected example, on the selected server, the typed credentials among -// them: marked as the playground is, so a session replay shows this sample blank too. +// Follows the playground's edits, typed credentials included, so it carries the playground's replay markers. function CurlCode() { const { CodeBlock } = useComponents(); const code = useCodeUsage(CURL_USAGE_ID); diff --git a/portal-template/src/lib/analytics.ts b/portal-template/src/lib/analytics.ts index 979a4f1b..af5f72d9 100644 --- a/portal-template/src/lib/analytics.ts +++ b/portal-template/src/lib/analytics.ts @@ -2,7 +2,7 @@ import { isOAuthCallbackPath } from './oauth-callback'; import type { PortalAnalytics } from './portal-types'; import { type Adapter, adapters, insertTags } from './vendor-tags'; -/** Query parameters a reported address keeps: campaign, ad-click and cross-domain tags, which attribution reads from the address. */ +/** The query parameters attribution reads from an address: campaign, ad-click and cross-domain tags. */ const KEPT_PREFIXES = ['utm_', 'hsa_']; const KEPT_NAMES = new Set([ '_gl', @@ -22,10 +22,7 @@ const KEPT_NAMES = new Set([ 'ref' ]); -/** - * Each event's keys, besides the `page_location` every report adds. Customers' GTM triggers - * match these names, so renaming or removing one breaks them without an error. - */ +/** Customers' GTM triggers match these names, so renaming or removing one breaks them without an error. */ export interface PortalEvents { docs_page_view: { page_title: string }; docs_markdown_copy: Record; @@ -38,13 +35,12 @@ export interface PortalEvents { } export type PortalEventName = keyof PortalEvents; -/** The reset entry, then the event entry with every detail under `docs`. */ type DataLayerEntry = { docs: null } | { event: PortalEventName; docs: Readonly> }; declare global { interface Window { dataLayer?: unknown[]; - /** The settings the page load started with: a config save under `portal serve` evaluates the module again. */ + /** Held by the window: a config save under `portal serve` evaluates this module again. */ portalAnalyticsStarted?: string; } } @@ -61,7 +57,6 @@ export function pageLocation(href: string, keep: readonly string[]): string { return url.href; } -/** The one instance a portal runs: started when the bundle evaluates, reporting from the root effect and the components. */ export class Analytics { private readonly live: Adapter[]; private lastPageView: string | null = null; @@ -74,15 +69,10 @@ export class Analytics { .filter((adapter) => adapter !== null); } - /** - * Once per page load, when the bundle starts: the data layer, every vendor's setup entries, then the vendor - * tags unless this is the OAuth callback, in which case the next page view inserts them. The guard is the - * window's, not the instance's: a config save under `portal serve` makes Vite evaluate the module again. - */ public start(): void { const settings = JSON.stringify(this.settings); if (window.portalAnalyticsStarted === settings) return; - // Other vendors after a config save: only a fresh page holds exactly their tags and setup. + // Other vendors after a config save: only a fresh page holds exactly their tags. if (window.portalAnalyticsStarted !== undefined) { window.location.reload(); return; @@ -93,18 +83,17 @@ export class Analytics { insertTags(this.live); } - /** `href` is the page the event belongs to, the current one unless the caller saw the address change first. */ + /** `href` is the page the event belongs to, when the caller saw the address move on first. */ public report(name: E, params: PortalEvents[E], href = window.location.href): void { if (isOAuthCallbackPath(new URL(href).pathname)) return; const docs = { ...params, page_location: pageLocation(href, this.settings.keepQueryParams) }; const dataLayer = (window.dataLayer ??= []); - // GTM keeps every key from earlier pushes and merges objects, so clear ours first: a shared GA4 tag never sends the last event's details. + // GTM merges every push into what it holds, so a tag would send the last event's details without this. dataLayer.push({ docs: null } satisfies DataLayerEntry); dataLayer.push({ event: name, docs } satisfies DataLayerEntry); for (const adapter of this.live) adapter.send?.(name, docs); } - /** `docs_page_view` for the current page, unless its cleaned address is the one last reported: a `#` jump sends none. */ public reportPageView(): void { if (isOAuthCallbackPath(window.location.pathname)) return; // The tags held back on the OAuth callback start here, on the first page after it. @@ -113,15 +102,12 @@ export class Analytics { if (page === this.lastPageView) return; this.previousPageView = this.lastPageView; this.lastPageView = page; - // Another page now: the missing page's next render is a new visit, while its own mounts stay one. if (this.lastNotFound !== page) this.lastNotFound = null; this.report('docs_page_view', { page_title: document.title }); } - /** The not-found page, once per missing page: `page_referrer` is the portal page left for it, else the document's referrer without its query. */ public reportNotFound(): void { const page = pageLocation(window.location.href, this.settings.keepQueryParams); - // A dev build mounts the page twice; the next missing page is a new report. if (page === this.lastNotFound) return; this.lastNotFound = page; const referrer = document.referrer === '' ? null : new URL(document.referrer); @@ -129,8 +115,7 @@ export class Analytics { referrer.search = ''; referrer.hash = ''; } - // The missing page's own view may be reported before this or after it: the page left is the last - // one reported besides it. + // The missing page's own view may be reported before this or after it. const left = this.lastPageView === page ? this.previousPageView : this.lastPageView; this.report('docs_not_found', { page_referrer: left ?? referrer?.href ?? '' }); } diff --git a/portal-template/src/lib/languages.ts b/portal-template/src/lib/languages.ts index d66cce47..e04b8ba0 100644 --- a/portal-template/src/lib/languages.ts +++ b/portal-template/src/lib/languages.ts @@ -32,12 +32,7 @@ export const BUNDLED_LANGUAGES = [ export type BundledLanguage = (typeof BUNDLED_LANGUAGES)[number]; -/** - * Shiki's own bundle resolves `ts` or `yml` through an alias table beside its grammars; a - * hand-built map has none, so an alias reaches Fumadocs as an unknown language and is replaced - * with `text`. Taken from Shiki's `bundledLanguagesInfo`; `test/portal-template.test.ts` holds - * them to it. - */ +/** Shiki's aliases, which a hand-built bundle lacks; `test/portal-template.test.ts` holds them to Shiki's own. */ export const languageAliases: Readonly> = { 'c#': 'csharp', cs: 'csharp', diff --git a/portal-template/src/lib/replay-markers.ts b/portal-template/src/lib/replay-markers.ts index 49cabc3c..d1ab3542 100644 --- a/portal-template/src/lib/replay-markers.ts +++ b/portal-template/src/lib/replay-markers.ts @@ -13,10 +13,7 @@ function markForReplay(element: Element): void { } } -/** - * Marks the playground's dialog, which Fumadocs renders outside the marked wrapper, as it appears: observers are told - * in the order they were made, so this one, made before any vendor tag, marks it before a replay tool's records it. - */ +/** Observers are told in the order they were made, so this one, made before any tag's, marks the dialog first. */ export function markPlaygroundDialogs(): void { new MutationObserver((mutations) => { for (const { addedNodes } of mutations) { diff --git a/portal-template/src/lib/vendor-tags.ts b/portal-template/src/lib/vendor-tags.ts index 87330de5..96fcee44 100644 --- a/portal-template/src/lib/vendor-tags.ts +++ b/portal-template/src/lib/vendor-tags.ts @@ -9,7 +9,6 @@ declare global { } } -/** Our code for one vendor. The shared adapter suite runs against each. */ export interface Adapter { setup(dataLayer: unknown[]): void; script: string; @@ -20,10 +19,7 @@ export interface Adapter { type Vendor = Exclude; const GOOGLE = 'https://www.googletagmanager.com'; -/** - * Keyed by every vendor `PortalAnalytics` names, each building its adapter from the settings, or null with its vendor - * unset: a vendor without an adapter does not compile, and an instance loads whatever the registry builds. - */ +/** Keyed by every vendor `PortalAnalytics` names, so a vendor without an adapter does not compile. */ export const adapters: { [V in Vendor]: (settings: PortalAnalytics) => Adapter | null } = { googleTagManager: ({ googleTagManager: setting }) => { if (setting === null) return null; @@ -48,21 +44,17 @@ export const adapters: { [V in Vendor]: (settings: PortalAnalytics) => Adapter | gtag('config', setting.measurementId, { send_page_view: false }); }, script: `${GOOGLE}/gtag/js?id=${encodeURIComponent(setting.measurementId)}`, - // The page's gtag, which an instance a config save under `portal serve` makes never sets up; GA4 gets its own - // names, without the `docs_` prefix. send: (name, params) => { // GA4's own events, such as a scroll, read this instead of the address, which may hold more. if (name === 'docs_page_view') window.gtag?.('set', { page_location: params.page_location }); + // The page's gtag, since a second instance under `portal serve` never runs its setup. window.gtag?.('event', name.replace(/^docs_/, ''), params); } }; } }; -/** - * Appends each vendor tag once, and none on the OAuth callback, whose address GTM's tags and gtag.js read for - * themselves; a tag already in the page is left, so a page view after the callback adds only the rest. - */ +/** None on the OAuth callback, whose address the tags read for themselves; each once, so a later page adds the rest. */ export function insertTags(live: Adapter[]): void { if (isOAuthCallbackPath(window.location.pathname)) return; for (const { script: src } of live) { diff --git a/portal-template/src/routes/__root.tsx b/portal-template/src/routes/__root.tsx index 687bcd48..1186941d 100644 --- a/portal-template/src/routes/__root.tsx +++ b/portal-template/src/routes/__root.tsx @@ -54,8 +54,7 @@ export const Route = createRootRoute({ function RootComponent() { const router = useRouter(); useEffect(() => { - // A prerendered page mounts with the router idle and raises no `onRendered` for its first page, so it - // is reported here; `portal serve` mounts pending, before the page's head applies, and `onRendered` follows. + // A prerendered page mounts idle with no `onRendered` to come; `portal serve` mounts pending, and one follows. if (router.state.status === 'idle') analytics.reportPageView(); return router.subscribe('onRendered', () => analytics.reportPageView()); }, [router]); From 96885d4d26c57c3f992c72552614aee251147ea7 Mon Sep 17 00:00:00 2001 From: Muhammad Sohail Date: Fri, 13 Nov 2026 17:35:01 +0500 Subject: [PATCH 62/73] chore(portal): keep the analytics plans out of the pull request The build plan, its review log and the docs draft for apimatic-docs stay on the author's machine, so the squash brings none of them into dev. Co-Authored-By: Claude Opus 5.5 --- .ai/plans/portal-analytics-docs.md | 215 ---------- .ai/plans/portal-analytics.md | 640 ----------------------------- 2 files changed, 855 deletions(-) delete mode 100644 .ai/plans/portal-analytics-docs.md delete mode 100644 .ai/plans/portal-analytics.md diff --git a/.ai/plans/portal-analytics-docs.md b/.ai/plans/portal-analytics-docs.md deleted file mode 100644 index 14f6125d..00000000 --- a/.ai/plans/portal-analytics-docs.md +++ /dev/null @@ -1,215 +0,0 @@ -# Portal analytics: docs draft - -A draft for the analytics page under docs.apimatic.io/v4 and the two rows of the CLI reference, -covering what PR 1 and PR 3 ship in #473 (apimatic/apimatic-io#2348, "Docs" and the PR 3 event -table, and #2349's additions). It is not a docs PR: the reviewer takes it to the apimatic-docs -repository. Lines starting with `> Reviewer:` are notes for that step, not page text. PR 2 -(`portal.scripts`) adds to this page in its own docs step. - ---- - -## Analytics - -The portal loads Google Tag Manager and Google Analytics 4 from `portal.analytics` in -`src/apimatic.json`, and reports its own page views to both. Every setting is optional: set -either vendor, both, or neither. - -```json -"portal": { - "analytics": { - "googleTagManager": { "containerId": "GTM-ABC123" }, - "googleAnalytics": { "measurementId": "G-ABC123" }, - "keepQueryParams": ["campaign_id"] - }, - "seo": { "googleSiteVerification": "abc123" } -} -``` - -| Setting | What it is | -|---|---| -| `googleTagManager.containerId` | The container's ID, from the GTM admin page. | -| `googleTagManager.environment` | `{ "auth": "…", "preview": "env-3" }`: the `gtm_auth` and `gtm_preview` values from a GTM environment's snippet (Admin → Environments → Actions → Get Snippet), so a staging build loads the container's staging version. | -| `googleAnalytics.measurementId` | The GA4 web data stream's measurement ID. | -| `keepQueryParams` | Your own link tags to keep in reported page addresses (see below). | -| `seo.googleSiteVerification` | The content value of Google's site verification meta tag, for Search Console (see below). | - -Paste each ID as the console shows it. The CLI checks that an ID is present and not blank, and -nothing else: a wrong ID fails at Google, where the tag does not load, not at build time. - -### Reported page addresses - -A reported `page_location` is the page's address without its `#` part and without its query -string, except for the tags attribution reads: `utm_*` and `hsa_*` parameters, and `_gl`, -`gclid`, `gbraid`, `wbraid`, `gad_source`, `dclid`, `fbclid`, `msclkid`, `ttclid`, `twclid`, -`li_fat_id`, `mc_cid`, `_hsenc`, `_hsmi` and `ref`. Everything else is dropped before any vendor -sees it. `keepQueryParams` adds your own names to that list. - -Never list `code`, `state` or another name an OAuth answer uses. The portal's API playground -signs readers in through OAuth, and a kept answer would be written into every reported address. - -### What the portal sends - -On every page the portal writes to `window.dataLayer`, the queue both Google tags read. Each -report is two entries: `{ docs: null }`, which clears the previous event's details, then the -event with its details under one `docs` key. - -```js -{ docs: null } -{ event: 'docs_page_view', docs: { page_title: 'Quickstart | Acme API', page_location: 'https://docs.acme.com/guides/quickstart' } } -``` - -Every event carries `page_location`, the address of the page it happened on, cleaned as above. -The table lists the keys each adds. - -| Event | Keys under `docs` | When | -|---|---|---| -| `docs_page_view` | `page_title` | The first page renders, and each later page change, once the new page's title is in place. Never twice in a row for the same address, and never on `/oauth/callback`. | -| `docs_markdown_copy` | none | The page's "Copy Markdown" button, when the copy succeeded. | -| `docs_plugin_install` | none | The Context Plugin page's install command, as its copy button is clicked. | -| `docs_sdk_download` | `language` | A "Download SDK" link, on the SDKs page's cards or an SDK's own page. `language` is the SDK's, as `languages` names it in `apimatic.json`. | -| `docs_code_copy` | `language` | The copy button of a code block on any page, the API reference's examples included. `language` is the block's title, such as `TypeScript` or `Terminal`, or for an untitled block in a tabbed set the selected tab's name. A block with neither reports nothing, nor does the install command's block, which has its own event, nor the playground's own blocks. | -| `docs_search` | `search_term`, `result`, `result_count` | The search dialog closes after the reader typed in it: the term, the address of the result picked or empty when none was, and how many results the list showed. `page_location` is the page the search was made on, not the result's. Reopening the dialog and closing it without typing or picking reports nothing. | -| `docs_not_found` | `page_referrer` | The not-found page renders. `page_referrer` is the portal page the reader left for it after a portal link, or on a first load the browser's referrer without its query, or empty when the browser sends none. The page's own `docs_page_view` is sent too. | -| `docs_api_request` | `endpoint`, `status`, `duration_ms` | The API playground shows a result. `endpoint` is the method in capitals and the path as the specification writes it, such as `GET /users/{id}`; `status` the HTTP status, or `client_error` for a request that never reached the API; `duration_ms` how long it took. It never carries the request's address, headers or body: those hold what the reader typed, keys included. | - -With `googleAnalytics` set, the portal also sends each event to GA4 directly, under its name -without the `docs_` prefix: `docs_page_view` arrives as `page_view` and `docs_search` as -`search`, which are GA4's own events; `page_title`, `page_location` and `search_term` are their own -parameters, and the rest arrive as custom events and parameters. - -#### Registering the keys in GA4 - -GA4 reports a custom parameter only once it is registered (Admin → Custom definitions). Register -four custom dimensions, `result`, `language`, `endpoint` and `status`, and two custom metrics, -`result_count` and `duration_ms`. Each appears in reports a day or two after. `page_title`, -`page_location`, `page_referrer` and `search_term` are GA4's own parameters and need nothing. - -### Google Analytics 4 - -1. Create a web data stream for the portal's address and paste its measurement ID into - `googleAnalytics.measurementId`. -2. Turn off the stream's own page-change counting: Admin → Data streams → your stream → - Enhanced measurement (the gear) → Page views → Show advanced settings → untick "Page changes - based on browser history events". The portal sends one `page_view` per page change itself; - with the setting on, GA4 sends another, and every page change counts twice. `apimatic portal - generate` prints a reminder whenever `googleAnalytics` is set. -3. Check it: open the portal with Google's Tag Assistant or the Google Analytics Debugger - extension, so DebugView shows your session, then move between pages. DebugView must show one - `page_view` per page change. Two per change means the setting in step 2 is still on; in - reports, double counting shows as views climbing to about twice what readers saw. -4. Redact `code` and `state`: Admin → Data streams → your stream → Configure tag settings → - Show all → Redact data → add both as query parameters. The portal never reports them, but GA4's own collection can read a page's - full address, and this keeps a sign-in answer out of it either way. -5. With `googleAnalytics` set, do not also add a GA4 tag for the same stream inside the GTM - container: every hit would count twice. - -### Google Tag Manager - -The container gets the events as GTM-format data layer pushes, so the usual recipe applies. - -- **The Google tag** (the GA4 configuration) fires on Initialization – All Pages, as Google - recommends, so it is ready before the first `docs_page_view`. Turn off "Send a page view event - when this configuration loads", or the tag counts the first page itself. -- **Data Layer Variables** `docs.page_location` and `docs.page_title`. Every event's details sit - under `docs`, and the portal clears `docs` before each event, so a variable never carries a - value from the previous event. -- **A GA4 Event tag** with the event name `page_view`, the parameters `page_location` and - `page_title` from those variables, and a Custom Event trigger on `docs_page_view`. -- Any other tag that should know about a page change triggers on `docs_page_view` the same way. -- **The other events** follow the same pattern: a Custom Event trigger on the event's name, and - a Data Layer Variable `docs.` for each key the table above lists, so a GA4 Event tag for - `docs_search` reads `docs.search_term`, `docs.result` and `docs.result_count`. - -A staging build that must still be checked in GTM sets `environment` to the staging -environment's values, and loads that version of the container. - -### Previews and staging - -`apimatic portal serve` loads the same tags a hosted portal does, and its page views count like -anyone else's. While previewing, run it with `--no-analytics`, or define your own addresses as -internal traffic in GA4 (Admin → Data streams → your stream → Configure tag settings → Define -internal traffic) and filter it from reports. - -`apimatic portal generate --no-analytics` builds a portal that loads neither vendor, for a -staging site that must not count. - -> Reviewer: PR 2 extends `--no-analytics` to the `analytics` and `marketing` scripts in -> `portal.scripts`. - -### Search Console - -Verify the portal's domain as a Domain property, with the DNS TXT record Search Console gives -you; it needs nothing in the portal. For a URL-prefix property verified by the HTML tag method -instead, put the tag's content value in `seo.googleSiteVerification`, and every page carries -``. - -Google's Tag Assistant finds the tags on a portal page. Checks that read only the raw HTML do -not, because the portal loads its tags from its scripts once the page is up, not from a script -tag in the HTML. - -### Consent - -Consent is yours to collect in this release. A consent banner inside the GTM container works as -it does on any site, with Google's Consent Mode deciding what each tag may send, so load GA4 -through the container when readers must consent first. `googleAnalytics` set directly cannot -wait for a banner: the portal configures GA4 as the page starts, before a banner inside the -container can set a consent default, so its first hits go out as consented. A banner of your -own, outside GTM, waits for a later portal setting. - -### Content Security Policy - -If the portal's host sets a CSP, copy the `script-src`, `img-src` and `connect-src` lists from -[Google's CSP guide](https://developers.google.com/tag-platform/security/guides/csp), which name -`www.googletagmanager.com`, `*.googletagmanager.com`, `*.google-analytics.com` and -`*.analytics.google.com`, and add whatever each tag inside the container loads. - -### Who can change the container - -Access to the GTM container is access to the site's code: a tag can run any script on every -page, and read what readers type. Give it only to people you would give the repository to. - -### Session replay - -Session replay tools record what readers type. The API playground, where readers paste keys -and tokens, carries the opt-out markers of PostHog (`ph-no-capture`), FullStory (`fs-exclude`), -rrweb (`rr-block`), Amplitude (`amp-block`), Hotjar (`data-hj-suppress`), Microsoft Clarity -(`data-clarity-mask`) and LogRocket (`data-private`): its header on the page, the dialog it -opens, which is marked as it appears, and the cURL sample beside it, which follows what the -reader types into the playground. A replay shows the page with the playground and that sample -blank. For any other tool, block the selector `[data-portal-playground]` in its settings, which -all three carry. - -### After a sign-in - -The playground's OAuth sign-in returns the reader to the endpoint page they left. The answer -never reaches a page the vendor tags load on: the callback page loads none, and the page the -reader returns to has a clean address, since the callback hands the answer over through session -storage, so the reported address, the vendors' own page view and anything else that reads the -address are clean. - -> Reviewer: the callback page has loaded no tag since 2026-11-13. The rest of this paragraph -> holds once the branch takes fumadocs-openapi 12.6.2 (from 2026-11-19) with the callback change -> the PR's "Before merging" item names; until then the return page's address holds the answer -> until the playground removes it, the tags load on the next page change, and that page view is -> the first reported. - -### Using another tag manager - -The portal writes GTM-format events to `window.dataLayer` on every portal, whether or not a -Google tag is set. To use another tag manager, load it through your host or, from PR 2, -through `portal.scripts`; turn on its GTM data-layer option, so it reads `docs_page_view` and -the `docs` details; and turn off its own page-change tracking, or page changes count twice. - ---- - -## CLI reference - -In `v4/src/content/apimatic-cli/cli-reference.mdx`, both `apimatic portal generate` and -`apimatic portal serve` gain the row, worded as the flag's description: - -| Flag | Description | -|---|---| -| `--no-analytics` | leave out Google Tag Manager, Google Analytics and every analytics or marketing script, for staging. | - -"Every analytics or marketing script" refers to `portal.scripts`, which a later release adds; until -then the flag leaves out the two Google tags. \ No newline at end of file diff --git a/.ai/plans/portal-analytics.md b/.ai/plans/portal-analytics.md deleted file mode 100644 index 925aa17d..00000000 --- a/.ai/plans/portal-analytics.md +++ /dev/null @@ -1,640 +0,0 @@ -# Portal analytics, built in reviewable steps - -Status: planned 2026-11-11 from the locked plan. Steps 1.1 to 1.3 are on PR #473 (draft, stacked -on #472). On 2026-11-12 the remaining steps were reordered top-down, from each entry point -inward, after the first three produced a module nothing called yet; steps 1.6 and 1.7 were swapped -the same day, so the parser lands before the flag it reads. On 2026-11-12 PR 3, the other -seven events, was moved ahead of PR 2 and into PR #473, so GA4 and GTM can be tested with every -event before anything merges. Every decision is final; a -change from here is a new row in the Decisions table of apimatic/apimatic-io#2347. - -What the feature does, and why each decision was made, is written down in the issues, which -are the source of truth. This file says only in what order it is built and how each step is -reviewed. Where this file and an issue disagree, the issue wins and this file is corrected. - -| Source | Holds | Read it when | -|---|---|---| -| apimatic/apimatic-io#2347 | the plan: the eight events, the loader, the Decisions table (locked), the risks | starting, and whenever a "why" comes up | -| apimatic/apimatic-io#2348 | the build checklist for the three PRs, "Schema, validation and reports" (every rule and every message, verbatim), "Done when" | every step | -| apimatic/apimatic-io#2349 | PR 1 in detail, top-down, with code sketches for every file | every PR 1 step; PR 2 builds on its loader, in the code `Analytics` (`lib/analytics.ts`) and `insertTags()` (`lib/vendor-tags.ts`) | -| Plan doc https://claude.ai/artifact/A6rr4cGkbEL3bRCnPGqWzy | the same plan as a document, with the diagram | only to settle a reading of the issues | -| Explainer https://claude.ai/artifact/RVbt9jerbNzTFyzGh4eE8t | the plain-language version | never needed for the build | - -Read an issue with `gh issue view --repo apimatic/apimatic-io` (they live in -apimatic-io, not in this repository). Shipped beside this plan: PR #472 in this repository -(fumadocs-openapi 12.6, PKCE, the `no-referrer` meta on `/oauth/callback`), and -fuma-nama/fumadocs#3809 and #3810. - -## 1. How a step works - -- Each step delivers one behaviour that runs, with the tests that prove it, and is small enough - to review in one sitting. A step creates only the code its behaviour needs: a class appears - the first time a step has something to hold, a method the first time a step calls it, a - message the first time it is said. -- Top-down, from a caller that exists. A step starts at an entry point that is already in the - tree (a command, a route, an effect, a component, the module the bundle evaluates) and adds - inward only what that caller needs. Nothing is written before the code that calls it, and a - pure helper is split out in the step whose caller needs it, with its tests, not before. Steps - 1.1 to 1.3 were built the other way round, before this rule; from 1.4 on every step follows it. -- Before writing, the agent says in a few lines what the step adds, which files it touches, and - asks the questions section 5 lists for it. Then it waits for a go. -- A step starts from the working tree as the reviewer left it. The agent never runs - `git commit` or `git push` on its own (`.ai/instructions.md`); the reviewer reads the diff, - tailors or refactors the code, and the next step builds on that. -- A step ends with these checks, run by the agent and reported with their output: - - ```bash - pnpm build # tsc on src - pnpm exec tsc -p test/tsconfig.json # the tests and the template modules they import - pnpm lint - pnpm prettier # or pnpm format, then show what it changed - pnpm exec tsx node_modules/mocha/bin/_mocha "test/" --timeout 99999 - pnpm test # the whole suite, at the end of each PR; sooner when a step touches shared code - ``` - -- The agent's report after a step: the files touched, the tests added by name, the output of - the checks, anything it could not verify, anything it found along the way but did not change, - and every place it departed from #2348 or #2349, with the reason. Nothing else. -- Three words from the reviewer drive the loop. `LGTM`: the step is accepted as it stands. - `commit`: the agent commits the step with the header its section names (Conventional Commits; - commitlint and lint-staged run on commit). `next`: the agent starts the next step with its - questions. Anything else is a change request on the current step. -- A step never widens. A problem found outside it goes in the report's "found" list; the - reviewer decides whether it becomes a step. -- A "check first" item (section 5) is answered with evidence from `node_modules` on the branch - before any code that depends on it is written, and the answer goes in the report. -- The manual checks (GTM Preview, GA4 DebugView, a playground sign-in) are the reviewer's, on a - test portal. The agent says which ones a step makes possible and leaves them to the reviewer. - -## 2. Rules for the code - -The conventions in `.ai/instructions.md` and `.ai/skills/` apply unchanged. These are the ones -this feature leans on most, plus its own. - -- **Functional core, imperative shell.** `pageLocation()`, the search and referrer helpers - (PR 3) are plain functions, tested without a DOM. The loader, `report()` and the React - effect are the shell. -- **The sketches in #2349 are the design, not the code.** Every name in them stands unless the - reviewer renames it. The agent may tighten a sketch to the repository's rules (no private - instance methods, no middlemen, `Promise` with early returns) and says where it did. -- **Messages verbatim.** Every parser report comes from the table in #2348, "Parser rules and - reports", word for word; the test asserts the whole sentence. The GA4 warning is the text in - #2348, "The GA4 warning". Since 2026-11-12 the parser checks presence and type only: a - vendor's ID, an environment value, the verification token and a kept name are any non-empty - string, with no pattern and no refused name, since a wrong value fails at the vendor, not in - the CLI; the schema (1.8) carries no patterns either. This replaces the locked "OAuth names - refused in `keepQueryParams`" and is the reviewer's to record in #2347's Decisions table. -- **Names are a contract.** An event name or key, once shipped, never changes. Names are - `docs_` plus lowercase snake_case, checked by a test. The three settled names are - `window.apimatic`, `window.apimatic.consent.update` (a later phase) and - `portal.seo.googleSiteVerification`. -- **`head()` lists no script**, in any PR. Everything loads through the loader, after the - bundle. (The wait for an address free of the nine OAuth answer names was removed on - 2026-11-12; see step 1.3.) -- **`analytics.ts` never imports `portal.ts`**, which loads the generated identity file; only - `portal-analytics.ts` does. Unit tests import `analytics.ts` with a fake `window`. -- **Every event sets all of its keys**, the compiler enforces it through `PortalEvents`, and - `report()` pushes `{ docs: null }` before `{ event, docs }`. The GA4 adapter and `subscribe` - keep flat params. -- **`docs_api_request` never carries** the request URL, body or headers. -- **Comments only for a why**, one line. The sketches carry some comments; keep only the ones - that explain a non-obvious decision (the `Arguments` object, the merge in GTM, the Suspense - order). -- **A helper only when a second caller or its own tests need it.** Logic used once stays inline - where it runs, written to read on its own. Nothing is written ahead of its caller: a function, - field or type with no use yet waits for the step that uses it. A stateful unit is a class with - flat public methods, not a closure over inner functions. - -## 3. Branches - -Start from `origin/dev` once PR #472 is merged; if it is still open, cut PR 1's branch from -`chore/fumadocs-openapi-12-6` and rebase onto `dev` after the merge, since the template work -depends on fumadocs-openapi 12.6. Confirm the base with `git log --oneline -1`. - -| PR | Branch | Cut from | Title (the squash commit) | -|---|---|---|---| -| 1 and 3 | `sohail/portal-analytics`, PR #473 | `chore/fumadocs-openapi-12-6` (#472 still open), rebased onto `dev` after the merge | `feat(portal): load Google Tag Manager and GA4 from portal.analytics and report the portal events` | -| 2 | `sohail/portal-scripts` | `sohail/portal-analytics`, once #473 merges | `feat(portal): load custom scripts from portal.scripts` | - -PR 3 was folded into #473 on 2026-11-12 (its steps follow PR 1's there, and the gate below applies -to both). PR 2 is independent of it and opens against `dev` once #473 is merged, with a PR body -that links #2348 and the issue's section it implements. Push only when the reviewer -says so. - -## 4. The steps - -| Step | A developer can | Size | -|---|---|---| -| 1.1 | clean an address and tell an OAuth answer from a campaign tag (done, `d703e0bd`, `bef3d350`) | small | -| 1.2 | start the vendors, report an event, and see one clean `docs_page_view` per page in the data layer (done, `62265fa3`) | medium | -| 1.3 | sign in through the playground and have the tags wait for a clean address (built as `1c616d56`, removed 2026-11-12; fuma-nama/fumadocs#3809 is the PR's merge prerequisite instead) | small | -| 1.4 | run a built portal against a hand-written identity file and see page views in GTM Preview | medium | -| 1.5 | see the verification meta on every page and the playground blank in a session replay (done, `7012bed8`) | small | -| 1.6 | write `portal.analytics` and `portal.seo` in `apimatic.json`, have them reach the browser, and be warned about GA4's own page views (done, `1538d831`) | medium | -| 1.7 | build or serve with `--no-analytics` and have the flag reach the identity file (done, `af636656`) | small | -| 1.8 | get editor help for the new settings, with the schema agreeing with the parser (done, `f654d592`) | small | -| 1.9 | prove it end to end on a built portal (done, `b698f389`) | small | -| 1.10 | read the README and the docs page draft (done, `c498fada`) | small | -| 2.1 | list a script in `portal.scripts` and have the CLI check it | medium | -| 2.2 | see listed scripts load in order, after the bundle, never beside an OAuth answer | small | -| 2.3 | subscribe to our events from a listed script | small | -| 2.4 | get editor help, the e2e proof and the docs draft for scripts | small | -| 3.1 | see `docs_markdown_copy`, `docs_plugin_install` and `docs_sdk_download` (done, `28817f70`) | small | -| 3.2 | see `docs_code_copy` with the block's language (done, `735533c8`) | small | -| 3.3 | see `docs_search` with the term, the pick and the count (done, `e81f86ae`) | small | -| 3.4 | see `docs_not_found` with a clean referrer (done, `1b19aef2`) | small | -| 3.5 | see `docs_api_request` with endpoint, status and duration, and nothing private (done, `5fae2090`) | medium | -| 3.6 | read the docs for all eight events (done, `cd8de5ea`) | small | - -### PR 1: the setting, the loader and page views - -Steps 1.1 to 1.3 are done and were built bottom-up. From 1.4 on, the order is top-down: first -the browser entry point, which gives the module its caller; then the CLI, from the command flag -inward to the parser; then the schema, the proof and the docs. - -#### Step 1.1: the pure functions (done) - -Delivers, in `portal-template/src/lib/analytics.ts` (new): the constants (`OAUTH_ANSWER`, -`KEPT_PREFIXES`, `KEPT_NAMES`), `pageLocation(href, keep, base?)`, `holdsOAuthAnswer(href)`, -the `PortalEvents` map with `docs_page_view` only, `PortalEventName`, `PortalEvent`, -`DataLayerEntry`. Nothing touches `window` yet. - -Tests, `test/portal-template/analytics.test.ts` (new): the `pageLocation()` cases (query and -`#` dropped; `utm_*`, `hsa_*`, each kept name and `keepQueryParams` kept; `gclidx` not; the -callback at the root, under `/docs/` and with a trailing slash gives `null`; otherwise the -address unchanged), the `holdsOAuthAnswer()` cases (each of the nine names alone, in the query -and after the `#`; `utm_source` and `campaign_id` false), and the event-name test -(`^docs_[a-z0-9_]+$`, at most 40 characters, at most 25 keys). - -Commit: `feat(portal): clean the reported page address`. - -#### Step 1.2: adapters, start, report and page views (done) - -Delivers: the `Adapter` interface and the `adapters` registry keyed by every vendor (GTM: -`gtm.start` entry, `gtm.js?id=…` with the `environment` suffix, `send` a no-op; GA4: -`window.gtag ??=` pushing `Arguments`, `js`, `config` with `send_page_view: false` and -`debug_mode` in a preview, `gtag/js?id=…`, `send` with the `docs_` prefix dropped); -`analyticsFor(settings)` with `startAnalytics()` (once; `window.dataLayer ??= []`; each -adapter's `setup()`; then `insert()` straight away when the address is clean, nothing when it -is not), `report()` (the cleaned `page_location`, nothing when it is `null`, the reset push, the -`{ event, docs }` push, each adapter's `send()`, the frozen event appended to `events`), and -`reportPageViews(router)` (the first page view at once, one per `onRendered`, none for the same -cleaned address, the unsubscribe). The 5-second wait is step 1.3. - -Tests: neither vendor; GTM only, with and without `environment`; GA4 only, including the -`[object Arguments]` check and `debugMode`; both, with every setup entry before the first event; -an existing `window.gtag` kept; a second start adds nothing; the shared adapter suite over the -registry (its setup turns off the vendor's page view; nothing it receives for a report made at -`…?code=x&state=y#access_token=z` holds `code=`, `token=` or `#`; no recording or input capture; -`send('docs_page_view')` maps to the vendor's page view; every script `https`, none inline); -the reset push (right before every event entry; the entry holds `event` and `docs` only; with a -helper that merges entries the way GTM does, a key from the previous event is gone after the -next); the replay list; `reportPageViews()` (first at once, one per `onRendered`, none for a `#` -or query change, A-B-A sends three, the returned function stops it); the callback sends no page -view but the setup entries are pushed. Fake `window` and `document` on `globalThis` as -`base-path.test.ts` does; a fresh instance per case. - -Commit: `feat(portal): report page views to the data layer and GA4`. - -#### Step 1.3: the loader waits out an OAuth answer (built, then removed) - -Built as `1c616d56` and removed on 2026-11-12: the wait made the loader hard to read for a -problem Fumadocs is fixing at the root. The PR now carries fuma-nama/fumadocs#3809 as a merge -prerequisite under "Before merging"; if Fumadocs does not ship it in time, the wait comes back -from that commit. This replaces the locked option A and is the reviewer's to record in #2347's -Decisions table. - -Delivers: `insertWhenClean()` as sketched: while the address holds an answer, a check every -100 ms for up to 50 checks, inserting once it is gone, the timer cleared after the last check, -and a later call on a clean address inserting; a call while it waits starts no second timer. -`startAnalytics()` calls it instead of `insert()`. - -Tests, with `sinon.useFakeTimers()` as `test/infrastructure/generation-status-poller.test.ts` -uses it: the setup entries at once; no script while the answer stays; a report meanwhile pushed -at once with a clean `page_location`; the insert at the next check once the answer is gone; the -timer cleared after 5 seconds and a later call inserting; no second timer. - -Commit: `feat(portal): hold vendor tags back while the address holds an OAuth answer`. - -#### Step 1.4: the bundle starts analytics and reports page views - -The browser entry point, which gives steps 1.1 to 1.3 their caller. It is the riskiest step, -because it is the browser timing, so it is checked in a browser before the CLI side is built. - -Delivers, from the entry point inward: - -- `portal-template/src/routes/__root.tsx`: the effect in `RootComponent` (subscribe - `insertWhenClean` to `onRendered`, then `reportPageViews(router)`, both undone on cleanup). - `head()` still lists no script. -- `portal-template/src/lib/portal-analytics.ts` (new): the one instance from - `portal.analytics`, `startAnalytics()` at module evaluation when `window` exists, exporting - `insertWhenClean`, `report` and `reportPageViews`. -- `portal-template/src/lib/portal-types.ts`: `analytics: PortalAnalytics` on `Portal`. -- `src/types/portal/portal-config.ts`: `analytics` on `PortalIdentity`, and `identity()` - filling it with the default (`null`, `null`, `[]`), so `Equal` in - `test/portal-template.test.ts` still holds. The parser is step 1.6. - -Tests: the existing suite stays green (`test/portal-template.test.ts`, the route tests); the -two `identity()` deep-equal cases gain `analytics`. The new behaviour is browser timing, which -the repository has no runner for, so the step's proof is manual: the reviewer edits -`portal.identity.json` in a prepared project (the file `appearanceFiles()` in -`src/infrastructure/portal-project-service.ts` writes) to hold a GTM container and a GA4 -stream, builds, and runs the manual list in #2349 ("Manual, on a test portal"): first-load -order, one `docs_page_view` per page change, the `#` link sending none, the OAuth wait with -both flows, DebugView with the stream setting on and off. The agent's report says how to -produce that build. - -Commit: `feat(portal): start analytics from the portal bundle`. - -#### Step 1.5: the verification meta and the playground out of replays (done) - -Delivers, from the two pages inward: - -- `portal-template/src/routes/__root.tsx`: `head()` gains the `google-site-verification` meta - when `seo.googleSiteVerification` is set. -- `portal-template/src/components/api-page.tsx`: the playground wrapped in the do-not-record - element, after the "check first" answers in section 5. -- `seo: PortalSeo` on `Portal` and on `PortalIdentity`, with `identity()` filling the default - (`null`). - -Tests: the existing suite; the two `identity()` cases gain `seo`. Manual: the meta in a built -page's ``; the playground blank in a Hotjar or Clarity replay loaded through a GTM tag. - -Commit: `feat(portal): add the site verification meta and keep the playground out of replays`. - -#### Step 1.6: the settings reach the browser, and the GA4 warning (done) - -Built before the flag (the two were swapped on 2026-11-12): until the parser exists, -`identity()` writes constants, so a flag passed to it would be a parameter nothing reads, -which the lint rule rejects and section 2 forbids. - -Delivers, from `apimatic.json` inward: - -- `src/types/portal/portal-config.ts`: `'analytics'` and `'seo'` in `NAMESPACES`, the two - fields after `ai`, the defaults in `scaffolded()`, the parsers in `fromBlock()`, `identity()` - filled from the config, `usesGoogleAnalytics()`, `toJSON()` writing both only when set, - `PortalBlock` gaining both as optional. -- `src/types/portal/config/analytics-config.ts` (new): `AnalyticsConfig` built like `AiConfig`, - with `defaults`, `parse()`, `usesGoogleAnalytics()`, `identity()`, `toJSON()`; every rule and - message from #2348's table, less the format rules (section 2). Both vendors are written whatever the command, until step 1.7 adds the flag. -- `src/types/portal/config/seo-config.ts` (new): `SeoConfig` the same way. -- `src/actions/portal/generate.ts`: once the project is prepared, before the build, when - `usesGoogleAnalytics()`, `this.prompts.googleAnalyticsCountsPageChanges()`; - `src/prompts/portal/generate.ts` prints the warning from #2348 with `log.warn`, in the style - of `src/prompts/portal/source.ts`'s config warnings. - -Tests: `test/types/portal/portal-config.test.ts`, `describe('analytics')` and -`describe('seo')` after `ai`, every case #2349 lists (absent, accepted with trimmed IDs, -`environment`, `keepQueryParams`, each message verbatim, several faults at once with unknown -keys first, `usesGoogleAnalytics()`, `toJSON()` round trip, `scaffolded()` writing neither); -`test/actions/portal/generate.test.ts` prints the warning only with `googleAnalytics` set, and -before the build; `test/prompts/portal/generate.test.ts` holds the warning's text. - -Commit: `feat(portal): read portal.analytics and portal.seo from apimatic.json`. - -#### Step 1.7: `--no-analytics` reaches the identity file (done) - -The CLI entry point. The flag exists and flows to the one place that reads it. `portal serve` -is a hosted portal in every way: the same tags, GA4 in its normal mode (decided 2026-11-12, -replacing the lock's debug-mode preview; the reviewer's to record in #2347). - -Delivers, from the commands inward, after the "check first" answer in section 5: - -- `src/commands/portal/generate.ts` and `src/commands/portal/serve.ts`: the `no-analytics` - boolean flag, description "leave out Google Tag Manager, Google Analytics and every analytics - or marketing script, for staging."; each passes `enableAnalytics: !flags['no-analytics']` to - its action; quickstart's preview passes `true`. -- `PreparePortalProjectAction` takes `enableAnalytics: boolean` as a parameter, never a field, - and hands `PortalProjectService.prepare()` and the caller's next step - `settingsForBuild(source, enableAnalytics)` from `src/types/portal/portal-source.ts`: the source - as read, or with `config.withoutVendors()` when the flag is false. `src/actions/portal/serve.ts` - does the same for `applyConfig()` on each rewrite, and `generate`'s Google Analytics notice - reads the config alone. The service, `PortalConfig.identity()` and - `AnalyticsConfig.identity()` never see the flag (the review of 2026-11-13 moved it up from - them). The sketch's `PortalDelivery` class is not built: with no preview mode it would wrap - this one boolean. - -Tests: both commands accept the flag (`test/commands/flag-parser.ts` is the helper the command -tests use); `withoutVendors()` leaves both vendors out and keeps `keepQueryParams` and the rest -of the identity; the generate, prepare and serve actions hand the service a config without -vendors under `--no-analytics`, the serve action on each rewrite too, and the prepare action -hands the same config to the caller's next step; the identity file written from such a config has both vendors -`null`. - -Commit: `feat(portal): add --no-analytics and leave the vendors out of the identity file`. - -#### Step 1.8: the schema (done) - -Delivers: `analytics` and `seo` in `apimatic.schema.json` from #2348's "Schema additions", -between `ai` and `pluginUrl`, less every `pattern` and the OAuth-name `not`, since the parser -checks presence and type only (section 2): each ID and value is `nonBlank`. The "every setting -at once" case gains both; the analytics and seo cases from #2348's "Cases for -`schema.test.ts`" go in `valid` and `invalid`, with the ones #2348 refused on format alone -moved to `valid`, so the parser and the schema agree on each. - -Tests: `test/types/apimatic-config/schema.test.ts`. - -Commit: `feat(portal): describe portal.analytics and portal.seo in the schema`. - -#### Step 1.9: the end-to-end proof (done) - -Delivers: in `test/e2e/portal-build.test.ts`, the default build reads a copy of its fixture -whose `portal` block gains `analytics` with `GTM-E2ETEST` and `G-E2ETEST` and `seo` with a -verification value (the fixture itself stays as it is: four other suites read it, and the -generate action's "does not warn" case needs it without GA4); the cases check a browser script -holds both IDs, no prerendered page names `googletagmanager.com`, every prerendered page -carries the meta tag, and the operation page holds the playground's prerendered header inside the -do-not-record element. The -`--no-analytics` identity file is proved by the project service test; a second Vite build for -the same two nulls is not worth a minute of the CI-only run. - -Commit: `test(portal): prove analytics and the verification tag in a built portal`. - -#### Step 1.10: README and the docs draft (done) - -Delivers: `pnpm readme` after `pnpm build` (colour on, `COLUMNS` unset) for the two flags; a -draft of the docs page, written to `.ai/plans/portal-analytics-docs.md`, covering every PR 1 -bullet in #2348's "Docs" list and #2349's additions, for the apimatic-docs repository -(`v4/src/content/apimatic-cli/cli-reference.mdx` gets the flag's row, same words as the -description). The draft is not a docs PR; the reviewer takes it there. - -Commit: `docs(portal): document portal.analytics` (the README part; the draft travels with it). - -**PR 1 gate** (since 2026-11-12 the #473 gate, applied once step 3.6 is done, with PR 3's manual -check, each event once in GTM Preview with all of its keys, on the list)**:** `pnpm test` green; the manual list in #2349 all checked by the reviewer; the -"Done when" lines in #2348 for loading, counting, nothing private and verification hold; the -fuma-nama/fumadocs#3809 item under "Before merging" in the PR body addressed (Fumadocs ships -the `sessionStorage` hand-over and the branch picks it up, else the wait of step 1.3 comes back -from `1c616d56`). Then the reviewer says to push and open the PR. - -### PR 2: `portal.scripts` and the subscribe helper - -#### Step 2.1: the setting - -Delivers: `src/types/portal/config/portal-script.ts` (new), one entry parsed as -`NavigationConfig.parseLinks()` parses links: `namespace()`, `unknownKeys()` against `src`, -`category`, `attributes`; `src` through `httpsAddress()` when it starts with `http:` or -`https:`, else `StaticAsset.parse()` with a scripts example; `category` through `oneOf()` with -`analytics` as the fallback; `attributes` keys matching `^data-[a-z0-9-]+$` with string values; -every error collected. `httpsAddress(value, path, example)` moved into `fields.ts` from -`portal-config.ts`'s `secureAddress()`, with `pluginUrl` on it. `PortalConfig`: `scripts` among -the known keys, parsed in `fromBlock()`, `staticFiles()` returning the listed static files -beside the brand files, `withoutVendors()` keeping the `necessary` and `functional` entries and dropping the rest, so -`identity()` writes what the build loads, `toJSON()` writing `scripts` only when set with `category` and `attributes` only when -given. No class for it: the category rule is a function beside the parser. `scripts: PortalScript[]` on `PortalIdentity` and on -the template's `Portal` (`ScriptCategory`, `PortalScript` in `portal-types.ts`). - -Tests: `portal-config.test.ts` `describe('scripts')` with every message from #2348's table, -several entries' errors at once, the `analytics` fallback, the round trip, `identity()` under -`--no-analytics`, the `pluginUrl` cases still passing; `portal-source-context.test.ts` reports -a missing listed file as `portal.scripts[0]` like a missing logo; the category rule for -each category under both flags. - -Commit: `feat(portal): read portal.scripts from apimatic.json`. - -#### Step 2.2: the loader inserts listed scripts - -Delivers: `Analytics` takes the listed scripts beside the settings (`new Analytics(portal.analytics, -portal.scripts)` in `lib/portal-analytics.ts`); `insertTags()` in `lib/vendor-tags.ts` adds each -listed script after the vendor tags, in order, `async = false`, static files through `withBasePath()`, each attribute -set on the element; a failed one doesn't stop the rest; vendor tags and listed scripts don't -wait for each other. - -Tests: order, `async`, base path, attributes; nothing listed while an answer stays; a failure -doesn't stop the next. - -Commit: `feat(portal): load listed scripts through the loader`. - -#### Step 2.3: `window.apimatic.analytics.subscribe()` - -Delivers: set up by `Analytics.start()` before any script is inserted; replays the events so far, -then each new one; returns an unsubscribe; each callback in `try`/`catch` with the error -rethrown through `setTimeout`; one `window.apimatic` object. - -Tests: a subscriber added after two reports gets both then each new one; the event is frozen; -a throwing subscriber doesn't stop the next and its error is rethrown later; the returned -function stops delivery. - -Commit: `feat(portal): let listed scripts subscribe to portal events`. - -#### Step 2.4: schema, e2e and the docs draft - -Delivers: `scripts` and the `httpsAddress` definition in the schema, `pluginUrl` moved onto it, -the scripts cases in `schema.test.ts` and `scripts` in "every setting at once"; the e2e fixture -gains `scripts`, `scriptsOf()` holds each address and attribute, no prerendered page names -them, a `--no-analytics` build keeps only `necessary` and `functional`; the `portal.scripts` -section appended to `.ai/plans/portal-analytics-docs.md` from #2348's PR 2 "Docs" list. - -Commit: `feat(portal): describe portal.scripts in the schema and prove it in a build`. - -**PR 2 gate:** `pnpm test` green; the PR 2 manual list in #2348 (Segment's debugger shows one -`page` per change, a never-answering host blocks nothing, a `functional` widget runs under -`serve`, an `analytics` script doesn't under `--no-analytics`); the "Scripts" line of "Done -when". - -### PR 3: the other portal events - -Before step 3.1, the agent rechecks the component references in #2348's event table against -the versions on the branch (fumadocs-ui 16.18.4, fumadocs-openapi 12.6.0) and checks each name -after the `docs_` prefix against GA4's recommended event names, and reports both. Each step -adds its entries to `PortalEvents` and reports through `portal-analytics.ts`'s `report()`. -Every event's keys are the ones in #2348's table; `report()` adds `page_location`. - -#### Step 3.1: the three click reporters (done) - -Delivers: `docs_markdown_copy` from `markdown-copy-button.tsx` when the copy succeeds; -`docs_plugin_install` from `plugin-install.tsx` through an `Actions` wrapper's -`onClickCapture`; `docs_sdk_download` with `language` from `sdk-actions.tsx`'s `DownloadLink`, -with `language="{{language}}"` added to `portal-pages/sdk.mdx`. - -Tests: each event's keys. The reporters firing once per action is on the manual list: the -template's component tests render to static markup through Vite and cannot click. - -Commit: `feat(portal): report Markdown copies, plugin installs and SDK downloads`. - -#### Step 3.2: `docs_code_copy` (done) - -Delivers: one document click listener for Fumadocs' copy button in a code block's `
`; -`language` from the `
` (`lib/code-titles.ts`) or the active tab's name; a plain -function that reads the language from the clicked element. - -Tests: the language from a titled block and from a tabbed one; a click elsewhere reports -nothing. - -Commit: `feat(portal): report code copies with the block's language`. - -#### Step 3.3: `docs_search` (done) - -Delivers: in `search.tsx`, one report per search when the dialog closes after the reader typed -something; the report waits a tick to see whether a result was picked; `result` the picked -address or empty, `result_count` the results shown; a plain function from the dialog's state to -the keys. - -Tests: one report with the pick; one with an empty `result` when the dialog closes without one; -none when nothing was typed. - -Commit: `feat(portal): report searches with the term, the pick and the count`. - -#### Step 3.4: `docs_not_found` (done) - -Delivers: in `not-found.tsx`, `page_referrer` as the previous portal page after an in-portal -link, or `document.referrer` without its query on a first load; a plain function for the -referrer rule. The page's `docs_page_view` still fires. - -Tests: the referrer from the previous portal page, and from another site without its query. - -Commit: `feat(portal): report the not-found page with a clean referrer`. - -#### Step 3.5: `docs_api_request` (done) - -Delivers: in `api-page.tsx`, `playground.fetchOptions.onRequestInit` recording the start time -and returning `requestInit` unchanged; a `ResultDisplay` wrapping Fumadocs' default and -reporting once per result with `endpoint` (method and path as the spec writes them), `status` -(the HTTP status or `client_error`) and `duration_ms`; never `data.url`, the body or the -headers; a plain function from a result to the keys. - -Tests: the keys from a `response` result and from a `client_error` result, never carrying the -request URL; the duration from the recorded start. - -Commit: `feat(portal): report playground requests without their contents`. - -#### Step 3.6: the docs draft (done) - -Delivers: the events section of `.ai/plans/portal-analytics-docs.md`: all eight events, keys, -when each fires; the five custom dimensions and two custom metrics to register in GA4. - -Commit: `docs(portal): document the eight portal events`. - -**PR 3 gate:** `pnpm test` green; each event once in GTM Preview with all of its keys, checked -by the reviewer; `docs_api_request` never carrying the request URL; the "Events" line of "Done -when". - -**Review of 2026-11-12** (three reviewers, fixed on the branch, uncommitted until the reviewer -says): the playground's dialog is marked for session replay as it opens, since Fumadocs portals it -outside the marked wrapper; `docs_search` carries the page searched from, captured when the -dialog opens, and a pick counts as a search; `docs_api_request` reports a result once however -often the display mounts, and a request failing before it was sent has no duration; the -code-copy listener ignores dropdowns and the playground's dialog, and prefers a block's caption -over its tab; `docs_not_found` reports once per missing page and again for the next, keyed on -the path; vendor values are escaped in the tag addresses; the GA4 warning stays quiet under -`--no-analytics`; the empty events take no keys at `report()`; the docs draft's consent, CSP, -replay, search and GA4 lines are corrected. `portal serve` runs under React's StrictMode, which is -why the once-per-result and once-per-page rules exist. The dialog marking is a workaround for fuma-nama/fumadocs#3824 (filed 2026-11-12), which asks for a prop that reaches the dialog; a follow-up to remove the observer once it ships, not a merge prerequisite. Rebased onto the base tip `d1e22066` on 2026-11-12, cleanly, with the fixes stashed and restored: the base holds fumadocs-openapi 12.6.0, having stepped back from 12.6.1 for the seven-day release-age rule. fuma-nama/fumadocs#3809 shipped in 12.6.2 on 2026-11-12 (12.6.1 answers #3810 only), which clears the rule on 2026-11-19, so the prerequisite stands until the base takes 12.6.2. - -**End-to-end run of 2026-11-13** (headless Chrome driven over the DevTools protocol against `portal serve` and a -`portal generate` build, with a real GA4 property): seven of the eight events reached GA4 once each with their -keys; `docs_plugin_install` needs a project with a `plugin` block. The playground's header and its dialog both -carry the replay markers in the browser. One bug found and fixed in `__root.tsx`, uncommitted: in `portal serve` -the root effect runs while the router is still pending, before the page's head applies, so the first -`docs_page_view` carried the site name as its title and the address dedupe then dropped the `onRendered` report -that had the right one; a prerendered page mounts idle with the right title and raises no `onRendered` for its -first page. The effect now reports directly only when the router is idle at mount. GA4's own history-change -page view was seen on every page change with the stream setting still on, as the warning says. - -**Review of 2026-11-13** (`/code-review` over the whole PR, each finding checked against the code, Fumadocs' -source and the served portal): eight findings stood and are fixed, uncommitted. The search dialog's typed and -picked bookkeeping leaked across opens, since Fumadocs closes the dialog before it hands over the pick, and the -count could belong to an earlier term while the last keystrokes' results were loading; the report is now made -from an effect once the close has rendered and the results are shown, which also drops the one-tick timeout. -The playground's observer marked every dialog, the search dialog included on an operation page, so it now -marks only a dialog holding the request form. `enableAnalytics` was forwarded unread through four -`PortalProjectService` methods and into `identity()`, against the "No middlemen" rule; the service and -`identity()` are back to their old signatures, and the two actions hand the service `config.withoutVendors()` -under `--no-analytics`. The `Analytics` constructor hand-wired the two vendors beside a registry meant to guard -them, so the registry's builders now take the settings and the constructor loads whatever they build. Smaller: -the not-found referrer no longer depends on `onRendered` running before the not-found effect; a request still -in flight when the playground leaves the page no longer times a later client error; `required()` moved to -`fields.ts` and serves `lightDark` too. Set aside: a `language-` class the review assumed on code blocks, which -this build renders nowhere; the OAuth-callback tag load, which fuma-nama/fumadocs#3809 covers; the -`sessionStorage` read, which came with #472. - -**The reviewer's findings of 2026-11-13** (seven, on PR #473), taken the same day: the vendor tags load -neither on `/oauth/callback` nor at any address holding an OAuth answer; `start()` pushes the setup entries -and inserts the tags only at a clean address, `reportPageView()` inserts them otherwise on the first page -after, each tag once, and the start guard is the window's, since a config save under `portal serve` made Vite -evaluate the module again and start a second time (seen in the browser: two `gtm.js` scripts and two -`gtm.start` entries in one document). The cURL sample beside the playground follows the typed credentials, so -it carries the replay markers too. The search dialog's close is seen from its open prop, which the hotkey -changes as well. `lastNotFound` clears on the next page, so a repeat visit to a missing page reports again. The -adapter suite checks that no setup entry or script so much as names recording or capture, and `report()`'s own -callback guard has a direct test. Still open, and now the one merge prerequisite: taking fumadocs-openapi -12.6.2 does not keep the answer out of the address on its own, since our own callback copies the provider's -query and `#` part onto the starting page; 12.6.2's `getReturnedFlow()` reads `sessionStorage` under -`fumadocs-openapi-oauth-returned` and falls back to the address, while 12.6.0 reads the address only, so the -callback change (store `location.href` under that key, return the bare page, follow in -`oauth-callback.test.ts` and the comment at `oauth-callback.ts:20`) lands with the bump, from 2026-11-19. - -**Second review of 2026-11-13** (`lib/analytics.ts`, for encapsulation it does not need and infrastructure -mixed in), taken the same day. The class keeps what every event shares: `start()`, `report()`, the page-view -and not-found history, and the playground's request timing. Reading Fumadocs' code-block markup moved to -`copiedLanguage()` in `lib/code-copy.ts`, which the root's click listener reports through `report()`; -`search.tsx` alone decides whether a search counts, and reports through `report()`; `reportNotFound()` reads -`document.referrer` itself, as `reportPageView()` reads the title. The vendor adapters and the tag loader moved -to `lib/vendor-tags.ts`: an adapter has one `script`; the registry is keyed by the vendors `PortalAnalytics` -names, so a vendor added there without an adapter does not compile; GA4's `send()` calls the page's `gtag`, -since an instance a config save makes never runs its setup (in isolation it threw `gtag is not a function`; a -config save in the browser did not show it). `isOAuthCallbackPath()` in `lib/oauth-callback.ts` is the one -check of the callback's path, for `pageLocation()` and the loader. Found on the way: the loader holds the tags -back on `/oauth/callback` only, not on the starting page the callback returns to with the answer attached, so -until the merge prerequisite above lands the tags load there with the answer in the address. - -## 5. Questions each step will raise - -Answered already, so the agent does not ask them: - -- Names: every name in #2349's sketches stands but one: the sketch's `PortalDelivery` is not - built. Since 2026-11-12 there is no preview mode, so what it carried is one boolean, - `enableAnalytics`, passed as a plain parameter. The config classes are `AnalyticsConfig` and - `SeoConfig` under `src/types/portal/config/`. -- `identity()` takes `enableAnalytics: boolean`; there is no second method for previews, and no - preview mode: `portal serve` loads the same tags a hosted portal does, GA4 in its normal mode. -- `--no-analytics` is a plain boolean flag with the description in step 1.7; there is no - `--with-analytics`. -- The parser's messages and the warning's text are the ones in #2348, less the format rules - dropped on 2026-11-12 (section 2); the schema has no patterns. -- `window.gtag` is defined only when GA4 is set. GTM gets no `send()`. -- The wait (100 ms × 50) was removed on 2026-11-12; if it comes back, it is not configurable. -- Unit tests fake `window` and `document` on `globalThis`; no browser runner is added. - -To check first, with evidence from `node_modules` on the branch, before the step's code: - -- **1.2 (answered 2026-11-11):** `@tanstack/router-core` 1.171.28 exposes `subscribe`; - `@tanstack/react-router` 1.170.33 queues `onRendered` at `Transitioner.js:45` and fires it - from the layout effect at `Matches.js:37`, after the commit in which `HeadContent` renders - the new title from the same matches store. -- **1.5:** which component fumadocs-openapi 12.6 renders for the playground ("Try in - Playground") and what `playground.render` receives; that the extra element leaves the layout - unchanged; whether the code samples beside the playground show what readers type (if so, - they are marked too); that `playground` client options still apply beside a custom renderer, - since 3.5 adds `fetchOptions` and `ResultDisplay`. -- **1.7:** how `PortalProjectService.prepare()` and the serve rewrite reach `identity()` today, - so the flag is passed once and not stored in two places. -- **1.9 (answered 2026-11-12):** the prerender resolves the lazy playground client, so the - operation page's HTML holds its header (method, route, the dialog trigger) inside the - do-not-record element; the forms arrive with the chunk in the browser. -- **3.1:** the current `Actions` prop of fumadocs-ui's `CodeBlock`, and the `DownloadLink` - props in `sdk-actions.tsx`. -- **3.2:** the copy button's position in fumadocs-ui 16.18.4's code block markup. -- **3.3:** whether fumadocs-ui 16.18.4's search dialog still calls `onOpenChange(false)` before - `onSelect`, and whether a result count is reachable from `search.tsx`. -- **3.5:** whether `useOperationContext().route` is available inside `ResultDisplay`, and where - the method comes from; which result shapes the display receives. - -For anything else unclear, the agent asks with options and their trade-offs, then waits. - -## 6. Out of scope - -APIMatic's own dashboard (a separate product decision), the ready-made GTM container (good to -have, after the release), Segment and PostHog adapters, script hardening (integrity checks, -build-time reachability), the consent setting (`window.apimatic.consent.update`), and the -docs PR itself in apimatic-docs. - -## 7. Starting a chat - -Paste this as the first message of a new Claude Code session in this repository: - -> Read `.ai/plans/portal-analytics.md` and the three issues it names (`gh issue view 2347`, -> `2348`, `2349` in `apimatic/apimatic-io`). Follow section 1 exactly: one step at a time, -> propose the step with its section 5 questions, wait for my go, build it, run the checks, and -> report. Do not commit or push unless I say `commit` or tell you to push. Start by confirming -> the base branch in section 3, then propose step 1.1. From 1bb6dfbb81f506662cc6820fee4aa10227044c7e Mon Sep 17 00:00:00 2001 From: Muhammad Sohail Date: Sun, 15 Nov 2026 21:33:26 +0500 Subject: [PATCH 63/73] fix(portal): hold the vendor tags back on the page a sign-in returns to fumadocs-openapi 12.6.0 reads a returned sign-in's answer from the address, so the callback sends the reader back with it attached, and gtm.js and gtag.js read the address for themselves. The tags now wait while the address carries the callback's path or a state, which Fumadocs sends with every authorization, and the playground loads them once Fumadocs has taken the answer out, in its effects; an answer nothing takes out waits for the next page. Co-Authored-By: Claude Opus 5.5 --- portal-template/src/components/playground.tsx | 2 ++ portal-template/src/lib/analytics.ts | 8 +++++-- portal-template/src/lib/oauth-callback.ts | 10 ++++++++ portal-template/src/lib/vendor-tags.ts | 6 ++--- test/portal-template/analytics.test.ts | 23 +++++++++++++++++++ test/portal-template/oauth-callback.test.ts | 21 +++++++++++++++++ 6 files changed, 65 insertions(+), 5 deletions(-) diff --git a/portal-template/src/components/playground.tsx b/portal-template/src/components/playground.tsx index 9c8918cb..0908ea9a 100644 --- a/portal-template/src/components/playground.tsx +++ b/portal-template/src/components/playground.tsx @@ -39,6 +39,8 @@ export default function Playground() { }), [] ); + // Fumadocs takes a returned sign-in's answer out of the address in the effects of the playground below this one. + useEffect(() => analytics.loadTags(), []); return ( diff --git a/portal-template/src/lib/analytics.ts b/portal-template/src/lib/analytics.ts index af5f72d9..f473b79f 100644 --- a/portal-template/src/lib/analytics.ts +++ b/portal-template/src/lib/analytics.ts @@ -83,6 +83,11 @@ export class Analytics { insertTags(this.live); } + /** The tags held back while the address held an OAuth answer, once something has taken it out. */ + public loadTags(): void { + insertTags(this.live); + } + /** `href` is the page the event belongs to, when the caller saw the address move on first. */ public report(name: E, params: PortalEvents[E], href = window.location.href): void { if (isOAuthCallbackPath(new URL(href).pathname)) return; @@ -96,8 +101,7 @@ export class Analytics { public reportPageView(): void { if (isOAuthCallbackPath(window.location.pathname)) return; - // The tags held back on the OAuth callback start here, on the first page after it. - insertTags(this.live); + this.loadTags(); const page = pageLocation(window.location.href, this.settings.keepQueryParams); if (page === this.lastPageView) return; this.previousPageView = this.lastPageView; diff --git a/portal-template/src/lib/oauth-callback.ts b/portal-template/src/lib/oauth-callback.ts index 87b79ee9..ad878ec7 100644 --- a/portal-template/src/lib/oauth-callback.ts +++ b/portal-template/src/lib/oauth-callback.ts @@ -12,6 +12,16 @@ export function isOAuthCallbackPath(pathname: string, base?: string): boolean { return pathname.replace(/\/$/, '') === withBasePath(oauthCallbackPath, base); } +/** The callback's address always holds a provider's answer; a page a sign-in returned to does until the playground reads it. */ +export function holdsOAuthAnswer({ pathname, search, hash }: Pick): boolean { + // Fumadocs sends a `state` with every authorization, and the answer carries it back in the query or the `#` part. + return ( + isOAuthCallbackPath(pathname) || + new URLSearchParams(search).has('state') || + new URLSearchParams(hash.slice(1)).has('state') + ); +} + /** Where the playground notes the path of the page that started the flow before it leaves: this tab's session storage. */ const STARTING_PAGE_KEY = 'fumadocs-openapi-oauth'; diff --git a/portal-template/src/lib/vendor-tags.ts b/portal-template/src/lib/vendor-tags.ts index 96fcee44..76f7922e 100644 --- a/portal-template/src/lib/vendor-tags.ts +++ b/portal-template/src/lib/vendor-tags.ts @@ -1,4 +1,4 @@ -import { isOAuthCallbackPath } from './oauth-callback'; +import { holdsOAuthAnswer } from './oauth-callback'; import type { PortalAnalytics } from './portal-types'; type Gtag = (...command: unknown[]) => void; @@ -54,9 +54,9 @@ export const adapters: { [V in Vendor]: (settings: PortalAnalytics) => Adapter | } }; -/** None on the OAuth callback, whose address the tags read for themselves; each once, so a later page adds the rest. */ +/** None while the address holds an OAuth answer, which the tags read for themselves; each once, so a later call adds the rest. */ export function insertTags(live: Adapter[]): void { - if (isOAuthCallbackPath(window.location.pathname)) return; + if (holdsOAuthAnswer(window.location)) return; for (const { script: src } of live) { if (document.head.querySelector(`script[src="${src}"]`) !== null) continue; const script = document.createElement('script'); diff --git a/test/portal-template/analytics.test.ts b/test/portal-template/analytics.test.ts index 4d923cba..f4be38ca 100644 --- a/test/portal-template/analytics.test.ts +++ b/test/portal-template/analytics.test.ts @@ -412,6 +412,29 @@ describe('Analytics', () => { }); }); + describe('on the page a playground sign-in returned to', () => { + const answered = 'https://docs.test/api/pets/listPets?code=abc&state=123'; + + it('holds the tags back while the answer is in the address, and loads them once the playground took it out', () => { + const page = browser(answered, 'List pets'); + const analytics = new Analytics(withBoth); + + analytics.start(); + analytics.reportPageView(); + analytics.loadTags(); + + expect(page.scripts).to.be.empty; + expect(pageViews(page.dataLayer())).to.have.length(1); + + page.go('https://docs.test/api/pets/listPets'); + analytics.loadTags(); + analytics.reportPageView(); + + expect(page.scripts.map((script) => script.src)).to.deep.equal([GTM_SCRIPT, GA4_SCRIPT]); + expect(pageViews(page.dataLayer())).to.have.length(1); + }); + }); + describe('on the OAuth callback', () => { for (const href of [ 'https://docs.test/oauth/callback?code=abc&state=123', diff --git a/test/portal-template/oauth-callback.test.ts b/test/portal-template/oauth-callback.test.ts index b7565445..7d016570 100644 --- a/test/portal-template/oauth-callback.test.ts +++ b/test/portal-template/oauth-callback.test.ts @@ -2,6 +2,7 @@ import { expect } from 'chai'; import type { SecuritySchemeObject } from 'fumadocs-openapi'; import { requestOAuthToken } from 'fumadocs-openapi/playground'; import { + holdsOAuthAnswer, isOAuthCallbackPath, oauthCallback, oauthCallbackPath, @@ -40,6 +41,26 @@ describe('isOAuthCallbackPath', () => { }); }); +describe('holdsOAuthAnswer', () => { + const at = (href: string) => holdsOAuthAnswer(new URL(href)); + + it('holds on the callback, with or without an answer', () => { + expect(at('https://docs.test/oauth/callback')).to.be.true; + expect(at('https://docs.test/oauth/callback?code=abc&state=123')).to.be.true; + }); + + it('holds on a page a sign-in returned to, with a code, a token or an error', () => { + expect(at('https://docs.test/api/pets/listPets?code=abc&state=123')).to.be.true; + expect(at('https://docs.test/api/pets/listPets#access_token=xyz&token_type=Bearer&state=123')).to.be.true; + expect(at('https://docs.test/api/pets/listPets?error=access_denied&state=123')).to.be.true; + }); + + it('does not hold on any other address, a query or a # part of its own included', () => { + expect(at('https://docs.test/api/pets/listPets')).to.be.false; + expect(at('https://docs.test/guides/quickstart?utm_source=mail&code=SAVE10#install')).to.be.false; + }); +}); + describe('takeStartingPage', () => { const origin = 'https://docs.test'; const pathname = '/api/pets/pets/listPets'; From f54b30ef9301df7ca809e7835ff1d404d1469f07 Mon Sep 17 00:00:00 2001 From: Muhammad Sohail Date: Mon, 16 Nov 2026 13:05:10 +0500 Subject: [PATCH 64/73] fix(portal): report a missing page only once the router has settled on it The not-found page keyed its report on the router's location, which already names the page a reader is leaving for while the not-found page is still mounted. Leaving it by Back, the Home link or any other link sent a second docs_not_found, for the page the reader went to, with the missing page as its referrer. The report is now keyed on the path the router has resolved, and nothing is reported in between. Seen in headless Chrome on portal serve and on a built portal, with in-app navigations only: leaving the missing page reports nothing more, and a second visit and a second missing page each report once. Co-Authored-By: Claude Fable 5.2 --- portal-template/src/components/not-found.tsx | 12 +++++++++--- 1 file changed, 9 insertions(+), 3 deletions(-) diff --git a/portal-template/src/components/not-found.tsx b/portal-template/src/components/not-found.tsx index 54b409b3..3eba7d78 100644 --- a/portal-template/src/components/not-found.tsx +++ b/portal-template/src/components/not-found.tsx @@ -1,14 +1,20 @@ import { useEffect } from 'react'; -import { useLocation } from '@tanstack/react-router'; +import { useRouterState } from '@tanstack/react-router'; import { baseOptions } from '@/lib/layout.shared'; import { analytics } from '@/lib/portal-analytics'; import { HomeLayout } from 'fumadocs-ui/layouts/home'; import { DefaultNotFound } from 'fumadocs-ui/layouts/home/not-found'; export function NotFound() { - const { pathname } = useLocation(); + // The path the router has settled on: its location alone already names the page a reader is leaving this one for. + const settled = useRouterState({ + select: ({ location, resolvedLocation }) => + resolvedLocation?.pathname === location.pathname ? location.pathname : null + }); // Keyed on the path: the same component shows the next missing page too. - useEffect(() => analytics.reportNotFound(), [pathname]); + useEffect(() => { + if (settled !== null) analytics.reportNotFound(); + }, [settled]); return ( From eba596e487c3768006f2f30fb66f050a7da0e2b6 Mon Sep 17 00:00:00 2001 From: Muhammad Sohail Date: Mon, 16 Nov 2026 13:05:10 +0500 Subject: [PATCH 65/73] fix(portal): send one value per language, for copies and downloads alike languageId() looked a name up as written, so a fence written TS or TypeScript missed the alias table, and a language the bundle does not know went out in the author's capitals: several values for one language in the one GA4 dimension. It now reads the name in lowercase first. docs_sdk_download goes through the same function, so the two events share one table instead of two sets that happen to match. Co-Authored-By: Claude Fable 5.2 --- portal-template/src/components/sdk-actions.tsx | 3 ++- portal-template/src/lib/languages.ts | 5 +++-- test/portal-template/languages.test.ts | 15 ++++++++++++--- 3 files changed, 17 insertions(+), 6 deletions(-) diff --git a/portal-template/src/components/sdk-actions.tsx b/portal-template/src/components/sdk-actions.tsx index 72728bbe..541e2122 100644 --- a/portal-template/src/components/sdk-actions.tsx +++ b/portal-template/src/components/sdk-actions.tsx @@ -3,6 +3,7 @@ import { asMarkdown } from 'fumadocs-core/server'; import { buttonVariants } from 'fumadocs-ui/components/ui/button'; import { Code, Download, Package } from 'lucide-react'; import { withBasePath } from '@/lib/base-path'; +import { languageId } from '@/lib/languages'; import { analytics } from '@/lib/portal-analytics'; export interface SdkActionsProps { @@ -76,7 +77,7 @@ export function DownloadLink({ href, className, language, children }: Readonly analytics.report('docs_sdk_download', { language })} + onClick={() => analytics.report('docs_sdk_download', { language: languageId(language) })} > {children} diff --git a/portal-template/src/lib/languages.ts b/portal-template/src/lib/languages.ts index e04b8ba0..9c6768a0 100644 --- a/portal-template/src/lib/languages.ts +++ b/portal-template/src/lib/languages.ts @@ -62,7 +62,8 @@ export function bundledLanguage(name: string): BundledLanguage | null { return Object.hasOwn(languageAliases, name) ? languageAliases[name] : null; } -/** A block's language as the portal reports it: the bundle's ID for a name or alias it knows, else the name as given. */ +/** A language as the portal reports it: the bundle's ID for a name or alias, else the name itself, read in lowercase. */ export function languageId(name: string): string { - return bundledLanguage(name) ?? name; + const lowered = name.toLowerCase(); + return bundledLanguage(lowered) ?? lowered; } diff --git a/test/portal-template/languages.test.ts b/test/portal-template/languages.test.ts index a0dea2fe..4825804a 100644 --- a/test/portal-template/languages.test.ts +++ b/test/portal-template/languages.test.ts @@ -3,7 +3,7 @@ import { languageId } from '../../portal-template/src/lib/languages'; import { Language } from '../../src/types/sdk/generate'; describe('languageId', () => { - // A download sends the language's key in `languages`, a copy this: one GA4 dimension holds both. + // A download and a copy both send this, so one GA4 dimension holds one set of values. it('is the key of every language the CLI generates an SDK in', () => { for (const language of Object.values(Language)) { expect(languageId(language)).to.equal(language); @@ -22,8 +22,17 @@ describe('languageId', () => { ]); }); - it('keeps a language the bundle does not know as it was written', () => { + it('reads a name or an alias written in capitals as the same language', () => { + expect(['TypeScript', 'TS', 'C#', 'JSON'].map(languageId)).to.deep.equal([ + 'typescript', + 'typescript', + 'csharp', + 'json' + ]); + }); + + it('sends a language the bundle does not know in lowercase, so one language is one value', () => { expect(languageId('plaintext')).to.equal('plaintext'); - expect(languageId('rust')).to.equal('rust'); + expect(['rust', 'Rust', 'Kotlin'].map(languageId)).to.deep.equal(['rust', 'rust', 'kotlin']); }); }); From 5e8a9f52c21835d647e7d6de9a388809c32d68de Mon Sep 17 00:00:00 2001 From: Muhammad Sohail Date: Mon, 16 Nov 2026 13:05:10 +0500 Subject: [PATCH 66/73] fix(portal): report a search's result as a whole address, and cap its term result was the picked page's path under the base path, while every page_location is a whole address, so the two did not join in a report. searchOutcome() now passes the pick through pageLocation(), which also drops the # part of a heading hit. The term is cut at 100 characters, which is what GA4 keeps of a value, so no other tag gets more of a key or a token pasted into search. Co-Authored-By: Claude Fable 5.2 --- portal-template/src/components/search.tsx | 2 +- portal-template/src/lib/search-report.ts | 16 ++++++++------- test/portal-template/search-report.test.ts | 23 ++++++++++++++++++++-- 3 files changed, 31 insertions(+), 10 deletions(-) diff --git a/portal-template/src/components/search.tsx b/portal-template/src/components/search.tsx index f092afe3..db145048 100644 --- a/portal-template/src/components/search.tsx +++ b/portal-template/src/components/search.tsx @@ -70,7 +70,7 @@ export default function DefaultSearchDialog(props: SharedProps) { setSearch(value); }; const onSelect = (item: SearchItemType) => { - picked.current = 'url' in item ? item.url : ''; + picked.current = 'url' in item ? new URL(item.url, window.location.href).href : ''; }; return ( diff --git a/portal-template/src/lib/search-report.ts b/portal-template/src/lib/search-report.ts index 0e7d4ae5..2b347b3a 100644 --- a/portal-template/src/lib/search-report.ts +++ b/portal-template/src/lib/search-report.ts @@ -1,4 +1,4 @@ -import type { PortalEvents } from './analytics'; +import { pageLocation, type PortalEvents } from './analytics'; /** The search dialog on a render after it opened. */ export interface SearchDialogState { @@ -6,7 +6,7 @@ export interface SearchDialogState { /** The last keystrokes' results are still on their way. */ loading: boolean; typed: boolean; - /** The address of the result picked, or empty. */ + /** The whole address of the result picked, or empty. */ picked: string; term: string; resultCount: number; @@ -14,13 +14,15 @@ export interface SearchDialogState { export type SearchOutcome = { ended: false } | { ended: true; report: PortalEvents['docs_search'] | null }; +/** What GA4 keeps of a parameter's value, so no other tag gets more of what a reader pasted into search. */ +const TERM_LIMIT = 100; + /** A search ends once the dialog has closed with its results in; it reports when the reader typed or picked a term. */ export function searchOutcome(state: SearchDialogState): SearchOutcome { if (state.open || state.loading) return { ended: false }; - const search_term = state.term.trim(); + const search_term = state.term.trim().slice(0, TERM_LIMIT); const counted = (state.typed || state.picked !== '') && search_term !== ''; - return { - ended: true, - report: counted ? { search_term, result: state.picked, result_count: state.resultCount } : null - }; + // In the shape of `page_location`, so a report joins the two: a heading hit loses its `#` part. + const result = state.picked === '' ? '' : pageLocation(state.picked, []); + return { ended: true, report: counted ? { search_term, result, result_count: state.resultCount } : null }; } diff --git a/test/portal-template/search-report.test.ts b/test/portal-template/search-report.test.ts index c1bcfaec..31fa8246 100644 --- a/test/portal-template/search-report.test.ts +++ b/test/portal-template/search-report.test.ts @@ -25,12 +25,24 @@ describe('searchOutcome', () => { // Fumadocs hands over the pick before the close renders, so a pick made with the hotkey's term counts too. it('reports the result picked, typed or not', () => { - expect(searchOutcome({ ...closed, typed: false, picked: '/api/pets/listPets' })).to.deep.equal({ + const picked = 'https://docs.acme.com/api/pets/listPets'; + + expect(searchOutcome({ ...closed, typed: false, picked })).to.deep.equal({ ended: true, - report: { search_term: 'pets', result: '/api/pets/listPets', result_count: 3 } + report: { search_term: 'pets', result: picked, result_count: 3 } }); }); + // Every event's page_location has this shape, so a report can join a search to the page it led to. + it('reports the result as a whole address, without the # part of a heading hit', () => { + const picked = 'https://docs.acme.com/docs/guides/intro#install'; + + expect(searchOutcome({ ...closed, picked })).to.have.nested.property( + 'report.result', + 'https://docs.acme.com/docs/guides/intro' + ); + }); + it('ends without a report when the reader neither typed nor picked, or left no term', () => { expect(searchOutcome({ ...closed, typed: false })).to.deep.equal({ ended: true, report: null }); expect(searchOutcome({ ...closed, term: ' ' })).to.deep.equal({ ended: true, report: null }); @@ -42,4 +54,11 @@ describe('searchOutcome', () => { 'list pets' ); }); + + it('reports at most the 100 characters of a term that GA4 keeps', () => { + expect(searchOutcome({ ...closed, term: 'k'.repeat(300) })).to.have.nested.property( + 'report.search_term', + 'k'.repeat(100) + ); + }); }); From 89f6b79827872b64ac8d59b19b18bf032eabe02f Mon Sep 17 00:00:00 2001 From: Muhammad Sohail Date: Mon, 16 Nov 2026 13:05:12 +0500 Subject: [PATCH 67/73] fix(portal): leave ref out of the query names every portal keeps Every other built-in name is one an ad or mail platform reads from the address itself. Nothing reads ref, sites use it for referral and invite codes of their own, and a customer can add a name through keepQueryParams but cannot take one out, so once shipped it could not have been removed. Co-Authored-By: Claude Fable 5.2 --- portal-template/src/lib/analytics.ts | 5 ++--- test/portal-template/analytics.test.ts | 9 +++++++-- 2 files changed, 9 insertions(+), 5 deletions(-) diff --git a/portal-template/src/lib/analytics.ts b/portal-template/src/lib/analytics.ts index f473b79f..6add6c46 100644 --- a/portal-template/src/lib/analytics.ts +++ b/portal-template/src/lib/analytics.ts @@ -2,7 +2,7 @@ import { isOAuthCallbackPath } from './oauth-callback'; import type { PortalAnalytics } from './portal-types'; import { type Adapter, adapters, insertTags } from './vendor-tags'; -/** The query parameters attribution reads from an address: campaign, ad-click and cross-domain tags. */ +/** The query parameters an ad or mail platform reads from an address itself; a customer adds names, and removes none. */ const KEPT_PREFIXES = ['utm_', 'hsa_']; const KEPT_NAMES = new Set([ '_gl', @@ -18,8 +18,7 @@ const KEPT_NAMES = new Set([ 'li_fat_id', 'mc_cid', '_hsenc', - '_hsmi', - 'ref' + '_hsmi' ]); /** Customers' GTM triggers match these names, so renaming or removing one breaks them without an error. */ diff --git a/test/portal-template/analytics.test.ts b/test/portal-template/analytics.test.ts index f4be38ca..cbea4a5f 100644 --- a/test/portal-template/analytics.test.ts +++ b/test/portal-template/analytics.test.ts @@ -18,8 +18,7 @@ const KEPT_NAMES = [ 'li_fat_id', 'mc_cid', '_hsenc', - '_hsmi', - 'ref' + '_hsmi' ]; describe('pageLocation', () => { @@ -54,6 +53,12 @@ describe('pageLocation', () => { expect(pageLocation(`${page}?gclidx=1`, [])).to.equal(page); }); + // No platform reads it from the address, and a customer can add a name but cannot take one out. + it('drops ref, which sites use for codes of their own, unless the customer keeps it', () => { + expect(pageLocation(`${page}?ref=invite-4821`, [])).to.equal(page); + expect(pageLocation(`${page}?ref=newsletter`, ['ref'])).to.equal(`${page}?ref=newsletter`); + }); + it('leaves the address otherwise unchanged', () => { expect(pageLocation(page, [])).to.equal(page); expect(pageLocation('https://docs.test/', [])).to.equal('https://docs.test/'); From c69d66a54937201b9f1f4d0a390945d078cf21ef Mon Sep 17 00:00:00 2001 From: Muhammad Sohail Date: Mon, 16 Nov 2026 13:05:12 +0500 Subject: [PATCH 68/73] test(portal): pin the shipped event names and keys Customers build GTM triggers and GA4 reports on them. The typed table follows the interface through a rename, so a rename passed CI. The names and keys are now also listed as plain text, and a change has to be made in that list on purpose. Co-Authored-By: Claude Fable 5.2 --- test/portal-template/analytics.test.ts | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/test/portal-template/analytics.test.ts b/test/portal-template/analytics.test.ts index cbea4a5f..8b04e005 100644 --- a/test/portal-template/analytics.test.ts +++ b/test/portal-template/analytics.test.ts @@ -85,6 +85,21 @@ describe('PortalEvents', () => { docs_api_request: { endpoint: true, status: true, duration_ms: true } }; + // Customers build GTM triggers and GA4 reports on these. They are plain text here, apart from the interface, so + // a rename or a new key is a change made in this list on purpose, never the side effect of a refactor. + it('ships exactly these events, each with exactly these keys', () => { + expect(Object.entries(events).map(([name, keys]) => [name, Object.keys(keys)])).to.deep.equal([ + ['docs_page_view', ['page_title']], + ['docs_markdown_copy', []], + ['docs_plugin_install', []], + ['docs_sdk_download', ['language']], + ['docs_code_copy', ['language']], + ['docs_search', ['search_term', 'result', 'result_count']], + ['docs_not_found', ['page_referrer']], + ['docs_api_request', ['endpoint', 'status', 'duration_ms']] + ]); + }); + it('names every event docs_ plus lowercase snake_case, at most 40 characters', () => { for (const name of Object.keys(events)) { expect(name).to.match(/^docs_[a-z0-9_]+$/); From 1c93ac275c9cc91e805c9cebb761eb4ac03887ca Mon Sep 17 00:00:00 2001 From: Muhammad Sohail Date: Mon, 16 Nov 2026 13:05:12 +0500 Subject: [PATCH 69/73] refactor(portal): make every caller choose the build's options resolve() and resolveSettings() defaulted to loading the vendor tags, so a new caller that forgot the argument got them without noticing. Co-Authored-By: Claude Fable 5.2 --- src/types/portal-source-context.ts | 6 ++--- test/e2e/portal-build.test.ts | 2 +- test/e2e/portal-serve.test.ts | 2 +- test/types/portal-source-context.test.ts | 34 +++++++++++++----------- 4 files changed, 23 insertions(+), 21 deletions(-) diff --git a/src/types/portal-source-context.ts b/src/types/portal-source-context.ts index 38a913de..8dd06d31 100644 --- a/src/types/portal-source-context.ts +++ b/src/types/portal-source-context.ts @@ -136,9 +136,7 @@ export class PortalSourceContext { } /** Reads and validates the whole source directory, or reports the first problem found. */ - public async resolve( - build: PortalBuildOptions = { analytics: true } - ): Promise> { + public async resolve(build: PortalBuildOptions): Promise> { const document = await this.readConfigDocument(); if (document.isErr()) { return err(document.error); @@ -284,7 +282,7 @@ export class PortalSourceContext { */ public async resolveSettings( suggested: SuggestedSite | null, - build: PortalBuildOptions = { analytics: true } + build: PortalBuildOptions ): Promise> { const document = await this.readConfigDocument(); if (document.isErr()) { diff --git a/test/e2e/portal-build.test.ts b/test/e2e/portal-build.test.ts index b04b52aa..d283033a 100644 --- a/test/e2e/portal-build.test.ts +++ b/test/e2e/portal-build.test.ts @@ -81,7 +81,7 @@ async function buildFixture(name: string, delivered: Delivered = {}, settings?: fixture = copy; } - const source = (await new PortalSourceContext(fixture).resolve())._unsafeUnwrap(); + const source = (await new PortalSourceContext(fixture).resolve({ analytics: true }))._unsafeUnwrap(); const project = new DirectoryPath(root).join('build'); fs.mkdirSync(project.toString(), { recursive: true }); diff --git a/test/e2e/portal-serve.test.ts b/test/e2e/portal-serve.test.ts index b11324e7..d9f8ee15 100644 --- a/test/e2e/portal-serve.test.ts +++ b/test/e2e/portal-serve.test.ts @@ -30,7 +30,7 @@ const enabled = process.env.APIMATIC_E2E === '1'; const root = canonical(fs.mkdtempSync(path.join(os.tmpdir(), 'portal-serve-e2e-'))); roots.push(root); - const resolved = (await new PortalSourceContext(source).resolve())._unsafeUnwrap(); + const resolved = (await new PortalSourceContext(source).resolve({ analytics: true }))._unsafeUnwrap(); const delivered = path.join(root, 'delivered'); fs.mkdirSync(delivered, { recursive: true }); fs.writeFileSync(path.join(delivered, 'typescript.zip'), 'PK typescript'); diff --git a/test/types/portal-source-context.test.ts b/test/types/portal-source-context.test.ts index 120d4e9b..cc3c6f4b 100644 --- a/test/types/portal-source-context.test.ts +++ b/test/types/portal-source-context.test.ts @@ -49,7 +49,7 @@ describe('PortalSourceContext', () => { const REQUIRED_LANGUAGES = /^'languages' must name at least one SDK language/; - const resolve = () => new PortalSourceContext(new DirectoryPath(root)).resolve(); + const resolve = () => new PortalSourceContext(new DirectoryPath(root)).resolve({ analytics: true }); /** The ignored navigation files as the warning names them, relative to the source directory. */ const ignored = (source: PortalSource): string[] => @@ -349,7 +349,7 @@ describe('PortalSourceContext', () => { writeConfig({ brand: { colors: { primary: '#1d4ed8' } } }); const resolved = (await resolve())._unsafeUnwrap(); - const reloaded = (await context().resolveSettings(resolved.suggestedSite))._unsafeUnwrap(); + const reloaded = (await context().resolveSettings(resolved.suggestedSite, { analytics: true }))._unsafeUnwrap(); expect(reloaded.config.toJSON()).to.deep.equal(resolved.config.toJSON()); expect(reloaded.config.siteTitle()).to.equal(resolved.config.siteTitle()); @@ -359,7 +359,7 @@ describe('PortalSourceContext', () => { it('holds the file to the rules resolve holds it to', async () => { writeConfig({}); - const errors = (await context().resolveSettings(null))._unsafeUnwrapErr(); + const errors = (await context().resolveSettings(null, { analytics: true }))._unsafeUnwrapErr(); expect(errors).to.deep.equal({ kind: 'invalidConfig', @@ -371,7 +371,7 @@ describe('PortalSourceContext', () => { it('reports a file the block names that is not on disk', async () => { writeConfig({ site: { name: 'Calc' }, brand: { favicon: 'static/favicon.ico' } }); - expect(missingFiles(await context().resolveSettings(null))).to.deep.equal([ + expect(missingFiles(await context().resolveSettings(null, { analytics: true }))).to.deep.equal([ ['portal.brand.favicon', 'static/favicon.ico', null] ]); }); @@ -385,7 +385,7 @@ describe('PortalSourceContext', () => { const resolved = (await new PortalSourceContext(new DirectoryPath(root)).resolve(off))._unsafeUnwrap(); const reloaded = (await context().resolveSettings(null, off))._unsafeUnwrap(); - const kept = (await context().resolveSettings(null))._unsafeUnwrap(); + const kept = (await context().resolveSettings(null, { analytics: true }))._unsafeUnwrap(); for (const { config } of [resolved, reloaded]) { expect(config.identity().analytics).to.deep.equal({ @@ -401,7 +401,9 @@ describe('PortalSourceContext', () => { }); it('reports a file removed while the preview runs', async () => { - expect((await context().resolveSettings(null))._unsafeUnwrapErr()).to.deep.equal({ kind: 'missingConfig' }); + expect((await context().resolveSettings(null, { analytics: true }))._unsafeUnwrapErr()).to.deep.equal({ + kind: 'missingConfig' + }); }); }); @@ -1555,7 +1557,9 @@ describe('PortalSourceContext', () => { // Named, because nothing suggests a site when the specifications are not read again. writeFile({ portal: { site: { name: 'Calc' } }, languages: { csharp: {} }, plugin: {} }); - const reloaded = (await new PortalSourceContext(new DirectoryPath(root)).resolveSettings(null))._unsafeUnwrap(); + const reloaded = ( + await new PortalSourceContext(new DirectoryPath(root)).resolveSettings(null, { analytics: true }) + )._unsafeUnwrap(); expect(generated(reloaded)).to.deep.equal(['sdks/index.mdx', 'sdks/csharp.mdx', 'context-plugin/index.mdx']); }); @@ -2625,11 +2629,11 @@ describe('PortalSourceContext', () => { it('writes a source directory it accepts itself, once a language is named', async () => { await scaffold(writeSpec({ title: 'Petstore', version: '1' })); - const unnamed = (await new PortalSourceContext(source).resolve())._unsafeUnwrapErr(); + const unnamed = (await new PortalSourceContext(source).resolve({ analytics: true }))._unsafeUnwrapErr(); expect(unnamed.kind === 'invalidConfig' ? unnamed.errors : []).to.have.lengthOf(1); addLanguages(); - const resolved = (await new PortalSourceContext(source).resolve())._unsafeUnwrap(); + const resolved = (await new PortalSourceContext(source).resolve({ analytics: true }))._unsafeUnwrap(); expect(resolved.config.siteTitle()).to.equal('Petstore'); expect(resolved.specs.map((spec) => spec.slug)).to.deep.equal(['petstore']); expect(resolved.contentDirectory).to.not.be.null; @@ -2654,10 +2658,10 @@ describe('PortalSourceContext', () => { it('writes a block that resolves to the portal an empty block makes', async () => { await scaffold(writeSpec({ title: 'Petstore', version: '1', description: 'All the pets.' })); addLanguages(); - const scaffolded = (await new PortalSourceContext(source).resolve())._unsafeUnwrap().config; + const scaffolded = (await new PortalSourceContext(source).resolve({ analytics: true }))._unsafeUnwrap().config; write('project/src/apimatic.json', JSON.stringify({ portal: {}, languages: LANGUAGES })); - const empty = (await new PortalSourceContext(source).resolve())._unsafeUnwrap().config; + const empty = (await new PortalSourceContext(source).resolve({ analytics: true }))._unsafeUnwrap().config; expect(scaffolded.toJSON()).to.deep.equal(empty.toJSON()); expect(scaffolded.identity()).to.deep.equal(empty.identity()); @@ -2695,7 +2699,7 @@ describe('PortalSourceContext', () => { addLanguages(); const contentFiles = fs.readdirSync(path.join(source.toString(), 'content')).sort(); - const scaffolded = (await new PortalSourceContext(source).resolve())._unsafeUnwrap(); + const scaffolded = (await new PortalSourceContext(source).resolve({ analytics: true }))._unsafeUnwrap(); expect(contentFiles).to.deep.equal(['index.md', 'nav.json']); expect(scaffolded.contentNotices.ignoredNavigationFiles).to.deep.equal([]); @@ -2812,7 +2816,7 @@ describe('PortalSourceContext', () => { await adopt(); - const resolved = (await new PortalSourceContext(source).resolve())._unsafeUnwrap(); + const resolved = (await new PortalSourceContext(source).resolve({ analytics: true }))._unsafeUnwrap(); expect(resolved.config.siteTitle()).to.equal('Petstore'); // The one that was there, and no copy of it beside itself. expect(fs.readdirSync(path.join(source.toString(), 'spec'))).to.deep.equal(['petstore.json']); @@ -2925,7 +2929,7 @@ describe('PortalSourceContext', () => { await adopt(); expect(portalBlock().site.name).to.equal(name); - const resolved = (await new PortalSourceContext(source).resolve())._unsafeUnwrap(); + const resolved = (await new PortalSourceContext(source).resolve({ analytics: true }))._unsafeUnwrap(); expect(resolved.config.siteTitle()).to.equal(name); }); }); @@ -2944,7 +2948,7 @@ describe('PortalSourceContext', () => { await adopt(); expect(portalBlock().site.name).to.equal('Alpha'); - expect((await new PortalSourceContext(source).resolve()).isOk()).to.be.true; + expect((await new PortalSourceContext(source).resolve({ analytics: true })).isOk()).to.be.true; }); }); }); From ec787d13d7ad3b01b18690aa886943b8f19aa0d9 Mon Sep 17 00:00:00 2001 From: Muhammad Sohail Date: Mon, 16 Nov 2026 13:05:12 +0500 Subject: [PATCH 70/73] test(portal): hold a built page to the cURL sample's markers and the response copy button The check that the cURL sample sits inside an element session replays skip went out with 95c8187a, though the sample follows what the reader types. It is back. A second check expects Fumadocs' copy button on "Example Response" to be the button[aria-live] the report listens for, so a Fumadocs update that changes either fails the build test instead of silently dropping the markers or the event. Co-Authored-By: Claude Fable 5.2 --- test/e2e/portal-build.test.ts | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/test/e2e/portal-build.test.ts b/test/e2e/portal-build.test.ts index d283033a..84489d29 100644 --- a/test/e2e/portal-build.test.ts +++ b/test/e2e/portal-build.test.ts @@ -301,6 +301,20 @@ const stylesheetOf = (output: DirectoryPath) => { expect(parts[0].slice(parts[0].lastIndexOf(' { + // The marked element's one child, past React's own comment, is the sample's block, with the command in it. + expect(read('api/apimatic-calculator/simple-calculator/Calculate/index.html')).to.match( + /data-private="">(?:)*)[\s\S])*>curl<[\s\S]*?> -X<[\s\S]*?> GET { + // Fumadocs' own button, in the card's header: after the title, before the header closes. + expect(read('api/apimatic-calculator/simple-calculator/Calculate/index.html')).to.match( + />Example Response<\/span>(?:(?!<\/div>)[\s\S])*]*\baria-live=/ + ); + }); + it('keeps the server-side specification loader out of the browser bundle', () => { const scripts = fs .readdirSync(path.join(portal.output().toString(), 'assets')) From 2c025b43ec4440305c6686cfbeeff85d44f4074d Mon Sep 17 00:00:00 2001 From: Muhammad Sohail Date: Mon, 16 Nov 2026 13:05:12 +0500 Subject: [PATCH 71/73] docs(portal): say in the schema that a GTM environment is for staging only Its two values are public in the built portal, and with them anyone can load that environment's version of the container. Co-Authored-By: Claude Fable 5.2 --- apimatic.schema.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/apimatic.schema.json b/apimatic.schema.json index f0982f69..78ea007d 100644 --- a/apimatic.schema.json +++ b/apimatic.schema.json @@ -197,7 +197,7 @@ }, "environment": { "type": "object", - "description": "A GTM environment, so a staging build loads the container's staging version: the gtm_auth and gtm_preview values from the environment's snippet.", + "description": "A GTM environment, for a staging build only, which loads the container's staging version: the gtm_auth and gtm_preview values from the environment's snippet. Both are public in the built portal, so a production portal sets none.", "additionalProperties": false, "required": ["auth", "preview"], "properties": { From 2ffa3b654f5ad196cff034f7abfaab6b16b9d004 Mon Sep 17 00:00:00 2001 From: Muhammad Sohail Date: Mon, 16 Nov 2026 14:40:49 +0500 Subject: [PATCH 72/73] fix(portal): name a language outside the bundle by its ID, whichever short name a block uses A language the bundle does not ship went out by the name the author gave it, so kt and kotlin were two values in the one GA4 dimension. A small report-only map beside the bundle's aliases names the common short names by Shiki's ID, and a test holds each entry to the ID and alias Shiki lists. A block in no language reported plaintext from a page and text from a description; both are plaintext now. Co-Authored-By: Claude Fable 5.2 --- portal-template/src/lib/languages.ts | 34 ++++++++++++++++++++++++-- test/portal-template/languages.test.ts | 30 ++++++++++++++++++++++- 2 files changed, 61 insertions(+), 3 deletions(-) diff --git a/portal-template/src/lib/languages.ts b/portal-template/src/lib/languages.ts index 9c6768a0..0d1865c4 100644 --- a/portal-template/src/lib/languages.ts +++ b/portal-template/src/lib/languages.ts @@ -62,8 +62,38 @@ export function bundledLanguage(name: string): BundledLanguage | null { return Object.hasOwn(languageAliases, name) ? languageAliases[name] : null; } -/** A language as the portal reports it: the bundle's ID for a name or alias, else the name itself, read in lowercase. */ +/** Short names of languages outside the bundle, by Shiki's ID: for reports only, so one language is one value. */ +export const reportedAliases: Readonly> = { + kt: 'kotlin', + kts: 'kotlin', + rs: 'rust', + 'c++': 'cpp', + objc: 'objective-c', + 'f#': 'fsharp', + fs: 'fsharp', + hs: 'haskell', + clj: 'clojure', + erl: 'erlang', + jl: 'julia', + ps: 'powershell', + ps1: 'powershell', + pwsh: 'powershell', + batch: 'bat', + cmd: 'bat', + dockerfile: 'docker', + makefile: 'make', + tf: 'terraform', + tfvars: 'terraform', + protobuf: 'proto', + properties: 'ini', + // Shiki's other names for a block in no language, which a page's own blocks report as `plaintext`. + text: 'plaintext', + txt: 'plaintext', + plain: 'plaintext' +}; + +/** A language as the portal reports it: its ID for any name it goes by, bundled or not, else the name in lowercase. */ export function languageId(name: string): string { const lowered = name.toLowerCase(); - return bundledLanguage(lowered) ?? lowered; + return bundledLanguage(lowered) ?? (Object.hasOwn(reportedAliases, lowered) ? reportedAliases[lowered] : lowered); } diff --git a/test/portal-template/languages.test.ts b/test/portal-template/languages.test.ts index 4825804a..d726f8c8 100644 --- a/test/portal-template/languages.test.ts +++ b/test/portal-template/languages.test.ts @@ -1,5 +1,5 @@ import { expect } from 'chai'; -import { languageId } from '../../portal-template/src/lib/languages'; +import { bundledLanguage, languageId, reportedAliases } from '../../portal-template/src/lib/languages'; import { Language } from '../../src/types/sdk/generate'; describe('languageId', () => { @@ -35,4 +35,32 @@ describe('languageId', () => { expect(languageId('plaintext')).to.equal('plaintext'); expect(['rust', 'Rust', 'Kotlin'].map(languageId)).to.deep.equal(['rust', 'rust', 'kotlin']); }); + + it('names a language outside the bundle by its ID too, whichever short name the block was written with', () => { + expect(['kt', 'KT', 'rs', 'c++', 'ps1', 'dockerfile'].map(languageId)).to.deep.equal([ + 'kotlin', + 'kotlin', + 'rust', + 'cpp', + 'powershell', + 'docker' + ]); + }); + + // A page's own block in no language reports `plaintext`; a description's reports `text`. + it('reports a block in no language as plaintext, by any of the names Shiki has for it', () => { + expect(['text', 'txt', 'plain', 'plaintext'].map(languageId)).to.deep.equal(Array(4).fill('plaintext')); + }); + + it('gives each short name outside the bundle the ID Shiki gives it, and shadows no bundled name', async () => { + const { bundledLanguagesInfo } = (await import('shiki/bundle/full')) as { + bundledLanguagesInfo: { id: string; aliases?: string[] }[]; + }; + + for (const [alias, id] of Object.entries(reportedAliases)) { + expect(bundledLanguage(alias), alias).to.be.null; + if (id === 'plaintext') continue; + expect(bundledLanguagesInfo.find((entry) => entry.id === id)?.aliases, `${alias} for ${id}`).to.include(alias); + } + }); }); From 02200bbceef51b61d91d16cc9d16365ac3c16e70 Mon Sep 17 00:00:00 2001 From: Muhammad Sohail Date: Mon, 16 Nov 2026 14:40:49 +0500 Subject: [PATCH 73/73] test(portal): pin an API request's status as text, digits or client_error docs_api_request sends status as the HTTP status in digits or as client_error, in one field customers register as one GA4 dimension. The choice is now written on the event's type and held by a test, so a change to either form is made on purpose. Co-Authored-By: Claude Fable 5.2 --- portal-template/src/lib/analytics.ts | 3 ++- test/portal-template/api-request.test.ts | 8 ++++++++ 2 files changed, 10 insertions(+), 1 deletion(-) diff --git a/portal-template/src/lib/analytics.ts b/portal-template/src/lib/analytics.ts index 6add6c46..10e59cff 100644 --- a/portal-template/src/lib/analytics.ts +++ b/portal-template/src/lib/analytics.ts @@ -2,7 +2,7 @@ import { isOAuthCallbackPath } from './oauth-callback'; import type { PortalAnalytics } from './portal-types'; import { type Adapter, adapters, insertTags } from './vendor-tags'; -/** The query parameters an ad or mail platform reads from an address itself; a customer adds names, and removes none. */ +/** The query parameters an ad or mail platform reads from an address itself; a customer adds names and removes none. */ const KEPT_PREFIXES = ['utm_', 'hsa_']; const KEPT_NAMES = new Set([ '_gl', @@ -30,6 +30,7 @@ export interface PortalEvents { docs_code_copy: { language: string }; docs_search: { search_term: string; result: string; result_count: number }; docs_not_found: { page_referrer: string }; + /** `status` is always text: the HTTP status in digits, or `client_error` for a request that never reached the API. */ docs_api_request: { endpoint: string; status: string; duration_ms: number }; } export type PortalEventName = keyof PortalEvents; diff --git a/test/portal-template/api-request.test.ts b/test/portal-template/api-request.test.ts index a1a8eb1f..d8b33d37 100644 --- a/test/portal-template/api-request.test.ts +++ b/test/portal-template/api-request.test.ts @@ -25,6 +25,14 @@ describe('apiRequest', () => { }); }); + // One GA4 dimension holds both forms, so a report filters on `status = 500` and on `status = client_error` alike. + it('reports the status as text either way: the HTTP status in digits, or client_error', () => { + for (const status of [200, 204, 404, 500]) { + expect(apiRequest(endpoint, response(status, 1), null, 0).status).to.equal(String(status)); + } + expect(apiRequest(endpoint, clientError, null, 0).status).to.equal('client_error'); + }); + it('times a request that never reached the API from when it was sent', () => { expect(apiRequest(endpoint, clientError, 1000, 1250)).to.deep.equal({ endpoint,