From 01a90fa582a78c1d1a2ec0dcc5cafb2856eef0cb Mon Sep 17 00:00:00 2001 From: Muhammad Sohail <62895181+sohail2721@users.noreply.github.com> Date: Thu, 19 Nov 2026 10:13:06 +0500 Subject: [PATCH 1/3] feat(portal): load custom scripts from portal.scripts (#477) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit PR 2 of apimatic/apimatic-io#2348: `portal.scripts` and `window.apimatic.analytics.subscribe()`. PR 1 and PR 3 merged as #473. The plan this was built from, step by step, is apimatic/apimatic-io#2351; where the code departs from apimatic/apimatic-io#2347, #2348 and #2349 it says where and why. Since the review of 2026-11-17 it also carries `portal.analytics.googleConsentMode`, with which a consent tool can govern the built-in Google tags, and a `--no-analytics` that hands no event to the scripts it keeps. On 2026-11-18 it renamed three event keys that #473 had put out on the `beta` tag, and made a script's `category` required. The same day it answered a re-review of the fixes, whose ten new findings are under "Before merging". Ready for review. What is still to do before it merges is under "Before merging": the portal tests on this branch, the decisions to record in the issues, and releasing it together with #473. ## What a customer can now write ```json "portal": { "analytics": { "googleAnalytics": { "measurementId": "G-ABC123" }, "googleConsentMode": { "default": "denied" } }, "scripts": [ { "src": "static/js/consent.js", "category": "necessary" }, { "src": "https://cdn.example.com/chat.js", "category": "functional" }, { "src": "https://cdn.example.com/analytics.js" } ] } ``` - `src` is an `https` address or a file under `src/static/`. A file is checked on disk like a logo. - `category` is `necessary`, `functional`, `analytics` or `marketing`, the groups consent tools ask readers about. It is required: the CLI assumes none. The schema's description says what belongs in each. - The portal inserts each script after its own bundle and after the vendor tags, in list order, once per page, and never on the OAuth callback page. - `--no-analytics` on `portal generate` and `portal serve` leaves out the `analytics` and `marketing` scripts along with the two Google tags. The scripts it keeps are handed no event: `subscribe()` is there and stays silent. The consent default of `googleConsentMode` stays in such a build. - A script gets the portal's events from `window.apimatic.analytics.subscribe(callback)`: every event so far, then each new one, as a frozen `{ name, params, time, version: 1 }`. It returns the function that stops delivery. - `googleConsentMode` makes the portal queue Google's Consent Mode defaults ("denied", with a wait of 500 ms) before it sets either Google tag up. Both tags load as before and set no cookie until a consent tool calls `gtag('consent', 'update', …)`. Without the setting nothing changes. - Three event keys have new names. `docs_code_copy` carries `code_language` and `docs_sdk_download` carries `sdk_language`, where 2.3.0-beta.1 sends `language`. `docs_search` carries `picked_result`, where it sends `result`. ## What is on the branch One commit per step of the plan, then the fixes from two reviews, the merge with `dev`, the two follow-ups to the second review, five changes of 2026-11-18, seven commits that answer the re-review of that day, three that answer a review comment and SonarCloud after it, and four that answer the last of the review on 2026-11-19. | Commit | What it adds | |---|---| | `19cb032a` | `scripts` entries with an `https` address: parsed, written to `portal.identity.json`, inserted by the loader with `async = false`. The key a start runs once by covers the list, so a config save under `portal serve` reloads with the new one. An inserted tag is found by its `src` attribute, since a selector built from a customer's address misses on a backslash (replaced in `78505ad0`). | | `2580c4ea` | A file from `src/static/` as `src`: checked on disk with the brand's files, written as its portal path, inserted under the base path. | | `bf320b46` | `category`, and `--no-analytics` dropping the two categories. `PortalConfig.withoutVendors()` becomes `withoutAnalytics()`. The flag's help and the README say what it leaves out. | | `7849475b` | `EventFeed` and `window.apimatic.analytics`, put in place at the start, before any tag or script is inserted, on every portal. What scripts are given there changed in `5f220732`. | | `cea1bc0c` | `scripts` in `apimatic.schema.json`, with one `httpsAddress` definition that `pluginUrl` now shares. | | `6782e26c` | The build test lists an address and a static file and checks the built files. | | `a0c6d999` | The fixture script that test ships holds a comment only. Its first version set a property on `window`, which the whole-tree lint that runs after the tests refused, and CI failed on it. | | `5f220732` | Scripts get a frozen `{ subscribe }` at `window.apimatic.analytics`, bound and put in place whatever was there; the feed is held at `window.portalEventFeed` (moved in `ddbad82a`). From the review of 2026-11-16 below. | | `88fe45dc`, `8d117512` | Two refactors from the same review: the feed's delivery is a static helper, and `insertTags()` reads `` once per call (not at all since `78505ad0`). | | `6ed31b30` | `publish()` loops over the subscribers without copying them first, which SonarCloud flagged on this PR as needless. Two tests pin what the copy was guarding: a subscriber added, and one removed, while an event is being handed over. | | `310f38ab` | The merge with `dev`, which took fumadocs-openapi 12.6.5 in #478. A sign-in's answer now reaches the playground through the tab's session storage, and `dev` holds the Google tags back on the OAuth callback only. Listed scripts follow that rule: none on the callback, all on the next page. They used to wait wherever the address held an answer. | | `d9058be4` | A subscriber's callback is called on its own. It was called on the feed's record of that subscriber, so a callback written without strict mode got the record as `this`, and one that reset the record's count was handed the same event without end. From the review of 2026-11-17 below, as are the seven commits after it. | | `ddbad82a` | The feed and the mark of what the page started with are held by the window under one symbol. `window.portalEventFeed` is gone, and so is `window.portalAnalyticsStarted`, which #473 set. A script that looks for the symbol can still reach the feed, as it can anything on the page. | | `78505ad0` | The page remembers each address it inserted, so a script that removes its own element once it has run is not inserted again on the next page view. `insertTags()` no longer reads ``. | | `97946a28` | A page that made `window.apimatic` read-only no longer stops the bundle. The portal starts, and the error shows in the console a moment later. Since `f7518097` that error is left to a page that froze the object too. | | `bc7ec368` | `httpsAddress()` refuses an address with no host before its path (`https:///…`), as the schema's pattern does, and parses it once. `pluginUrl` goes through the same function. | | `e50ac0ac` | `Script.staticFiles()` answers a list, empty for an address, in place of `staticFile()` and its `null`. | | `5f1d49d9` | The flag's help and the README say that a script with no category is left out too. `367cf0be` takes that out again: no entry is without one. | | `07ee1f45` | `deliveredCount` and an `Unsubscribe` type replace two comments in the feed that restated the code, and a two-line comment in the schema test is one line. | | `3df7c3dd` | The schema's description of `scripts` says they stay off the OAuth callback page. It still described the hold that the merge with `dev` removed. | | `17ddf35f` | A build made with `--no-analytics` hands no event to the scripts it keeps. `portal.identity.json` gains `analytics.eventFeed`, which is `"off"` for such a build (`analytics.events` since `6792fa8d`). `subscribe()` stays in place and silent, and the data layer gets its entries as before (it gets none since `b9450b72`). `AnalyticsConfig.withoutVendors()` becomes `withoutAnalytics()`, and the flag's help says what it does. Finding 7 of the review of 2026-11-17. | | `1547e424` | `portal.analytics.googleConsentMode`: the portal queues Google's consent defaults ahead of both vendors' setups, and a `--no-analytics` build queues none (it queues them since `a895b2cd`). Finding 2 of the same review. | | `440f0b28` | The setting in `apimatic.schema.json`, with the schema test holding it to the parser's verdict. | | `94c58970` | The build test sets it and checks that a built script holds the defaults and no prerendered page does. | | `be9556c2` | `language` on `docs_code_copy` and `docs_sdk_download` becomes `code_language` and `sdk_language`. gtag takes `language` on an event for the reader's own language, so GA4's language field read `python` for a code copy. A test keeps the name out of every event. From a review of the docs PR. | | `5ad3cfe8` | `result` on `docs_search` becomes `picked_result`. Next to `result_count` a reviewer read it as the list of results, sent empty. | | `367cf0be` | `category` is required on every entry, by the parser and the schema. No entry counts as `analytics` any more. The flag's help and the README lose "or not set". `oneOf()` loses its fallback, and `brand.colorMode` gets its default through `optional()`. | | `95780b18` | The state a window shares is `WindowAnalytics`, held under `WINDOW_ANALYTICS`, with a comment saying it means the `Window` object, which a reload replaces. "Page" in this code now means a route only. From a review comment on this PR, as is the next. | | `37db2b44` | `start()` keeps that state on the instance and is the one place that reads the global. An instance whose start asked for a reload used to find the state anyway, and its next page view inserted the new script into the window being left. It now adds no tag and hands over no event. | | `9a6e19b4` | `window.gtag` counts as a gtag only when it is a function. A browser answers that name with an element whose id is `gtag`, such as a guide's heading, and on a fresh load of such a page the portal called the heading and its whole script stopped. Portals with Google Analytics had this from #473. New finding 1 of the re-review, as are the six commits after it by their numbers. | | `7b491436` | The build test for the consent setting reads the setting's value, and a second build, without the setting, has to fail the same check. It used to look for two texts that every build holds. New finding 4. | | `a895b2cd` | A `--no-analytics` build keeps the consent default. A script such a build keeps may load a Google tag of its own. New finding 3. | | `eb200e91` | The schema's description of `googleConsentMode` says "Google's own tags", says that other vendors' tags in a container need their own consent checks, and no longer says "set here". New finding 5. | | `a3a04d3e` | The addresses the window remembers start with the `src` of every script `` holds when the portal starts, so a script the host injects itself gets no second copy. New finding 7, a regression of `78505ad0`. | | `f7518097` | `analytics` is defined on the object a host keeps at `window.apimatic`, when that object takes a property. A copy is made only for one that does not. New finding 6. | | `ae99bcc1` | A backslash is refused anywhere before an https address's path, by the schema's pattern and the CLI's alike, and the report asks for "an address starting with 'https://' and a host". New finding 8. | | `37dcd1b3` | `gtagFor()` sets `window.gtag` before it returns it, not inside the return expression, which SonarCloud flagged (S1121) after `9a6e19b4`. | | `b9450b72` | A `--no-analytics` build writes no event to `window.dataLayer` either: `report()` returns at once. The consent default, queued in `start()`, is the one thing such a build puts there. From a review comment on this PR. | | `6792fa8d` | The identity's switch is `analytics.events`, no longer `analytics.eventFeed`, since it turns off the data layer's events too. It is still refused as a setting in `apimatic.json`. | | `15aaf820` | The schema's description of `scripts` names the token an OAuth 2.0 sign-in leaves in session storage among what a listed script can read. Tracked in apimatic/apimatic-io#2355; wording from the review. | | `144c6b73` | The schema's description of `googleConsentMode` says it does not affect which scripts in `portal.scripts` are loaded, or when, in place of "holds back no script". Wording from the review. | | `482418b2` | The schema's description of a script's `category` says what belongs in each of the four, with examples, and that a script doing more than one thing takes the last that applies. From the review. | | `665c8ef9` | `windowGtag()`, `scriptsInHead()` and `putOn()` are inlined where they were called, by the rule `3fc4fdd3` adds to `.ai/instructions.md`: each one's doc comment, signature and brace outweighed its body. Nothing changes in what the portal does. | ## Decisions on record Each is a departure from the issues, made with the reviewer during the build and written up in apimatic/apimatic-io#2351 (section 4 and section 1, row 22), except the four that answer the review of 2026-11-17 and the last two, of 2026-11-18, which are written up here only. The issues themselves are not edited yet. - **No `attributes`.** An entry is `{ src, category }`. A file in `static/` can add a vendor's tag and set its attributes, and Plausible, the issues' example, now gives out a site-specific address with an inline call. Adding the key later breaks no config. - **`category` is not written to the identity file.** Nothing in the browser reads it in this release. - **Two reports for `src`, not three.** What is neither an `https` address nor a file in `static/` gets one report naming both choices. - **Events from before a subscription arrive just after `subscribe()` returns**, not inside it, so `const stop = subscribe(…)` can call `stop()` on the first event. - **`toJSON()` does not write `scripts`**, as it writes neither `analytics` nor `seo`. - **No second Vite build for `--no-analytics` in the build test.** `portal-project-service.test.ts` proves the identity file, as for #473. - **The flag's help** is `leave out the tags set in 'portal.analytics' and each script in 'portal.scripts' whose category is 'analytics' or 'marketing', and hand no event to the scripts that stay.` "The Google Tag Manager and Google Analytics tags" became "the tags", and `17ddf35f` added the events. `5f1d49d9` had added "or not set", which `367cf0be` took out with the default. - **A `--no-analytics` build hands no event to the scripts it keeps** (`17ddf35f`). This reverses a bullet written here earlier on 2026-11-17, which called the open feed a design choice. `subscribe()` stays in place, so a kept script does not throw on a staging build. - **A `--no-analytics` build writes no event to the data layer either** (`b9450b72`). This reverses what stood in the bullet above until 2026-11-18: "the data layer still gets its entries: no vendor reads them there". Since `a895b2cd` keeps the consent default for a Google tag a kept script loads, a vendor can read them there: a tag manager such a script loads fires on the data layer's events. The cost is that a preview made with the flag no longer shows in the console what would have been reported. - **Consent Mode defaults are queued in the setup, and nothing is held back.** #2347 already says GTM and GA4 are never held back and get Consent Mode defaults in their setup. Holding the tags until `necessary` scripts have run was considered and not built: it needs a queue for events, delays analytics by the slowest script, never starts if one hangs, and still races for a consent tool that sets its default late. - **`googleConsentMode` is Google's alone.** It is `{ "default": "denied" }`, an object so that a later key changes no config, and it holds no listed script. The portal-wide consent setting of #2347, which holds scripts by category and gives `window.apimatic.consent.update`, stays a later phase under a key of its own. - **The wait is fixed at 500 ms, and "denied" covers the four Consent Mode v2 types.** The setting is accepted with no built-in tag, for a Google snippet the customer lists themselves. - **A `--no-analytics` build keeps the consent default** (`a895b2cd`). This reverses what stood here until 2026-11-18, that such a build queues nothing for Google. It keeps `necessary` and `functional` scripts, and an owner may load Google's own snippet from one of those, the route this description gives for no contact with Google before consent. On staging only, that snippet then started with no consent state. The default does nothing where no Google tag loads. - **`category` is required** (`367cf0be`). This reverses the default of `analytics` that #2351 records. A reviewer's point: a customer who never chose a category has no way to see why `--no-analytics` dropped a script. What the default guarded still holds, since only a script someone marked `necessary` or `functional` survives the flag. A missing category is reported as `'portal.scripts[0].category' is required.` No release has `scripts`, so no config breaks. - **The four categories stay, and each is defined** (`482418b2`). The review asked why there are four when two behave alike today, `necessary` with `functional` and `analytics` with `marketing`. They are the groups consent tools ask readers about: Cookiebot's necessary, preferences, statistics and marketing, and OneTrust's strictly necessary, functional, performance and targeting. #2347 records them for that reason, for the later consent setting that holds each script until the reader agrees to its group. That setting needs both splits: a reader may accept statistics and refuse marketing, and a chat widget can wait for consent where a consent tool cannot. Merging two names now would leave every config that used the merged one meaning the wrong thing once they split. `preferences` is what `functional` covers, and a fifth group, such as OneTrust's social media, can be added later without breaking a config. - **Three value-object methods keep their own place** although they fall under the rule of `3fc4fdd3`: `AnalyticsConfig.withoutAnalytics()`, `Script.staticFiles()` and `Script.loadsWithoutAnalytics()`. Each answers from private state, so inlining it would mean exposing that state to its caller. - **Three event keys are renamed after #473 went out on the `beta` tag** (`be9556c2`, `5ad3cfe8`). A container built against 2.3.0-beta.1 that reads `docs.language` or `docs.result` gets nothing from them after this, with no error. The docs were not published with that beta. ## Known limits - **A listed script that never answers.** Measured in headless Chrome with a host that accepts the connection and sends nothing: the page, GTM, GA4 and page views are unaffected, but the listed scripts after it do not run while it is pending. On a built portal the window's `load` event also does not fire in that time, so GTM's "Window Loaded" trigger waits with it. Under `portal serve` `load` had already fired. A script that fails outright (a host that does not resolve) holds nothing. - **No consent gating.** Every listed script loads for every reader, whatever its category, unless the build used `--no-analytics`. - **Without `googleConsentMode`, a listed consent script can still lose to the built-in Google tags.** Measured with Google Analytics and the consent script 1.5 s late: Google set its `_ga` cookies and sent the page view with no consent state. With the setting on, the same run set no cookie and marked the page view denied. A customer whose banner decides what is tracked has to set it, and the docs must say so. - **A consent tool's own default replaces the portal's, wait included.** A stand-in that queued its own "denied" default, with no wait, after the portal's kept the state denied, and a returning reader's first page view then went out as denied. With no second default the wait held and it went out as granted. - **`googleConsentMode` is Google's advanced Consent Mode.** Both tags load before the reader answers and send hits marked denied, with no cookie. A customer who wants no contact with Google before consent lists Google's own snippet from a file of theirs that waits; list order holds (measured). - **No `integrity`.** The key is refused as unknown, so a build fixes a script's address but not what it serves. A script listed by its address runs whatever the address serves at each page load: a change by its vendor, or by anyone who takes the address over, reaches a published portal without a rebuild. A file in `static/` changes only with a rebuild, apart from code it loads from elsewhere. Documented rather than fixed, for now: a [review comment on apimatic/apimatic-docs#887](https://github.com/apimatic/apimatic-docs/pull/887#discussion_r4613672315) asks the scripts warning to say so. An optional `integrity` key can come later without breaking a config. - **Any listed script can read the page**, the API playground included. The replay markers, and keeping scripts off the OAuth callback, limit what a well-behaved vendor script picks up; they do not sandbox a script. - **On the page a sign-in returns to, listed scripts load at once, while the provider's answer still waits in the tab's session storage.** Since the merge with `dev` (#478) the answer is in no page's address but the callback's, where nothing loads. It waits in session storage until a playground reads it, and on a page with no playground it stays for the life of the tab. A listed script that reads session storage can read it there: seen in a browser, a script starting on the returned page read the callback's address, `code` included. #478 accepted that window for the Google tags, which read the address and not the storage. For listed scripts it is tracked in apimatic/apimatic-io#2355: the schema's description of `scripts` names the token (`15aaf820`), and fuma-nama/fumadocs#3874 asks Fumadocs for an option to keep it out of session storage. Whether portals must keep it out of listed scripts' reach altogether is still to decide. Holding them until the playground has taken the answer would not keep a credential from them. Measured with a sign-in through the playground against a stub provider that answers in the implicit flow: a listed script starting on the returned page read the token in the waiting answer; the playground then kept the token in session storage, as `fumadocs-openapi-auth-oauth`, for the life of the tab; and the same script read it there at its next start, on a guide page with no playground. - **`window.apimatic` does not exist for a script the host injects into `` itself**, which runs before the portal's bundle. If such a script puts an object of its own at `window.apimatic.analytics`, the portal replaces it at its start, and callbacks queued on the old one are not carried over. - **A page that made `window.apimatic` read-only and froze its object gets no `subscribe()`.** The portal starts and works, and the error shows in the console. A listed script that calls `window.apimatic.analytics.subscribe()` fails there. Where the object behind the read-only name still takes a property, the portal puts `analytics` on it and nothing is in error (`f7518097`; seen in a browser for a read-only property, not run again for a getter alone). - **A script the host injects is told from a listed one by its `src` as written.** The same file under another spelling of its address, relative where the portal writes it from the root, gets a second copy. - **The schema passes three malformed hosts that the CLI refuses:** `https://:443/…`, `https://[::1/…` and `https://cdn.exa%mple.com/…`. An editor shows no warning for them, and `portal generate` reports the address. ## Risk **Medium.** #473 is out on the `beta` tag only, as 2.3.0-beta.1 (`latest` is 2.2.0, which has none of it). Nothing of this PR is released, and it builds on #473. - **What changes for every portal, scripts listed or not:** - The loader remembers the addresses it has inserted, and reads `` once, at its start, for the scripts already there. This applies to the two Google tags too. It takes `window.gtag` as Google's only when it is a function: a browser answers that name with an element whose id is `gtag`, such as a guide's heading, and `dev`'s GA4 tag calls whatever the name holds, which stops the portal's script on such a page. - The mark of a started page, which #473 kept at `window.portalAnalyticsStarted`, is held under a symbol on the window with the feed. - Every portal gets `window.apimatic.analytics`, and keeps each reported event in memory for the life of the page. - `portal.identity.json` gains `analytics.googleConsentMode` and `analytics.events`. A portal that sets no consent mode queues nothing new, and its events are on. - `pluginUrl` is checked by the same rule from a shared function, and its pattern in the schema moved to a shared definition. A `pluginUrl` with no host before its path (`https:///…`) or with a backslash in its host (`https://host\x.zip`) is now refused; the CLI used to accept both, writing the first without the extra slash and the second with a slash for the backslash. A portal with no `scripts` loads nothing new. - **What changes only for a portal that lists scripts:** those scripts run on every page, the API playground included, with full access to the page. That is the feature, and choosing them is the customer's. - **What cannot be taken back after a release:** the shape of an entry, the four category names and that one is required, `window.apimatic.analytics.subscribe()`, the event it hands over and the keys of each event, and `googleConsentMode` with its one value. Customers will write configs and scripts against them. - **What stands between this and a mistake:** - CI: the whole suite and the lint, on three systems and four Node versions. - Both end-to-end files. - The browser checks under "Test plan, in a browser". - A code review at `6782e26c`, whose five findings are fixed. - A second code review, by a colleague, at `6ed31b30`, and a re-review at `94c58970`. Their fourteen and ten findings are answered under "Before merging". - Two security reviews, the second on `6ed31b30`, which found no vulnerability. - **Where the cover is thin:** - The browser checks were Chrome, with one run each in Firefox and in WebKit on Windows. Safari itself was not run. - The sign-in path was checked by opening the callback by hand, with a typed `code` and `state` and the starting page put in session storage, not with a provider's round trip. One sign-in was then run through the playground itself, against a stub provider that answered in the implicit flow. No real provider has been used. - Real vendors' scripts run: Google's GA4 snippet with a `subscribe()` forwarder (at `6ed31b30`), an open-source consent tool and an open-source session recorder. Not run: a commercial consent tool or replay tool, a chat widget, Segment, or a vendor that reads `data-` attributes. - The thirteen commits after the merge (the second review's fixes and its two follow-ups) have tests and both end-to-end files behind them, and a browser run each: on a preview for the first eight, and on built files too for the consent mode and `--no-analytics`. The re-review at `94c58970` read them; none has had a security review. - The five commits of 2026-11-18 have tests behind them. The first three also have the build end-to-end file, a browser run for the two renames and a run of `portal generate` for the required category. The last two have a browser run on a preview. None has had a code or security review beyond the comment the last two answer, and neither end-to-end file was run locally for the last two. - The seven commits that answer the re-review have tests, both end-to-end files and a browser run on built files behind them, or a run of `portal generate` for the address rule. None has had a code or security review. Two of them change what a host sees: where `analytics` is put on `window.apimatic`, and which scripts in `` count as inserted. - The three commits after them have tests, both end-to-end files and a browser run on a `--no-analytics` build behind them. None has had a code or security review beyond the comment and the SonarCloud issue they answer. - The four commits of 2026-11-19 change three schema descriptions and inline three helpers. They have the schema test, the unit files, both end-to-end files and a browser run on built files behind them, and no other review. - The one real consent tool run against `googleConsentMode` is open source and wired to Consent Mode by hand, as its guide shows. A commercial tool that queues its own default may behave as the stand-in did (see "Known limits"). - The merge with `dev` (`310f38ab`) changed when listed scripts load around a sign-in. That has unit tests, both end-to-end files, a browser run and the re-review at `94c58970` behind it, but no security review. - **No data or state to migrate.** Nothing is stored, and `portal.identity.json` is rewritten on every run. ## How to revert - **On `dev`, before a release:** revert this PR's squash commit with `git revert`. It is one commit, nothing depends on it yet, and there is nothing to migrate or clean up. The revert also takes `--no-analytics` back to leaving out the two Google tags only, with its earlier help text and README lines, and takes `scripts` and `googleConsentMode` out of the schema. - **After a release:** prefer a fix forward. A revert breaks every config that lists scripts or sets `googleConsentMode`: a CLI without this change refuses both as unknown settings, so `portal generate` and `portal serve` fail until the customer removes them. - **A portal already published keeps what it was built with.** It is static files, so reverting the CLI takes no script off a live portal. To stop one, remove its entry from `apimatic.json`, rebuild and redeploy. For `analytics` and `marketing` scripts, building with `--no-analytics` does the same. - **For one customer, without touching the CLI:** remove `scripts` from `apimatic.json` and rebuild. The portal then loads none, and `window.apimatic.analytics` stays there unused. - **There is no feature flag.** ## Before merging - [ ] **Release together with #473.** This PR is what that PR's "Release together with PR 2" item waits for: until it merges, `dev` holds a `--no-analytics` that drops less than it will. - [x] **CI green on `6ed31b30`**, the last commit before the merge with `dev`: the whole suite and the lint, on Ubuntu, macOS and Windows with Node 22, 22.14, 24 and 26. On `6782e26c` the tests passed (2,526 on `ubuntu-latest / Node 24`) and the lint after them failed on the fixture script, which `a0c6d999` fixes. The whole suite was not run locally. - [x] **CI green on `310f38ab`**, the merge with `dev`: all 16 checks. - [x] **CI green on `07ee1f45`**, after the second review's fixes: all 16 checks. - [x] **CI green on `94c58970`**: all 16 checks. - [x] **CI green on `367cf0be`**: all 16 checks. - [x] **CI green on `37db2b44`**: all 16 checks. - [x] **CI green on `ae99bcc1`**: all 16 checks. - [x] **CI green on `6792fa8d`**: all 16 checks. - [x] **CI green on `665c8ef9`**, the head: all 16 checks. - [x] **The re-review at `94c58970`** (a second review, which read the fixes at that commit and raised ten new findings). Each was checked first: the dead page of finding 1 was reproduced on built files, and finding 4 on two builds. Fixed: a heading called "gtag" stopped the portal's script (1, `9a6e19b4`); a staging build dropped the consent default (3, `a895b2cd`); the consent setting's build test could not fail (4, `7b491436`); the schema promised more than Consent Mode does (5, `eb200e91`); a host's own object at `window.apimatic` was swapped for a copy (6, `f7518097`); a script the host injects was loaded twice (7, `a3a04d3e`); a backslash passed for a host (8, `ae99bcc1`); a config save could insert the new script into the window being left (9, `37db2b44`, which a comment on this PR asked for). Not changed: listed scripts can read a sign-in's answer in session storage (2), tracked in apimatic/apimatic-io#2355, since holding them would not keep the token from them (see "Known limits"); and the list of wanted scripts is still built on each page view, and two field comments stay (10). - [x] **The review of 2026-11-16** (a code review of this PR, findings checked by hand). Fixed in `5f220732` and the two refactors after it: `window.apimatic.analytics` was the feed object itself, so `publish()` and the event list were reachable from any script; `subscribe` threw when called detached from that object; an object a page had already put at that name made every report throw; `EventFeed.deliver()` was a private instance method, which `.ai/instructions.md` rules out; and `insertTags()` read `` once per script. Seen in a browser with a page's own stand-in set first. Left as they are, on purpose: an address with a space around it is refused while a static path with one is accepted; the event history is not capped; missing-file checks read a folder once per file. A security review of the diff found no vulnerability. - [x] **The review of 2026-11-17** (a colleague's review at `6ed31b30`, fourteen findings, each checked against the head, the runtime ones reproduced in a browser or in Node first). Fixed in the eight commits after the merge: a script that removes its own element was inserted again on every page view (1, and 10 with it); the feed was reachable at `window.portalEventFeed` (3); a page that had made `window.apimatic` read-only stopped the bundle (4); a callback got the feed's record of it as `this` (5); the CLI accepted and rewrote `https:///…`, which the schema refuses (6, and the double parse of 11); the flag's help left out scripts with no category (9); `staticFile()` answered `null` (12); three comments restated the code (14). Fixed after those, on the reviewer's word: a listed consent script could not hold back the built-in Google tags (2), by `googleConsentMode` in `1547e424`; and `--no-analytics` handed events to the scripts it kept (7), in `17ddf35f`. Left as they are, on purpose: the event history is not capped (8), as after the first review; the browser tells a portal file from an address by its leading `/` (13), which is the rule `api-markdown.tsx` on `dev` uses for images, and tests pin what the CLI writes; `isWebAddress()`, which checks links and the site address, keeps its own rule (the rest of 11). - [x] **The manual list** is closed. Three of its checks were run with real tools on 2026-11-17 and are in the browser list; the others were dropped: each is covered by a run above or by a test, is a docs example, or is optional. - [x] **Review comments.** Rafay's two, both on `analytics.ts`: the name of the state a window shares (answered by `95780b18` and `37db2b44`, resolved), and `--no-analytics` writing every event to the data layer (answered by `b9450b72`, resolved). SonarCloud's one new issue on this PR, S1121 in `vendor-tags.ts`, is answered by `37dcd1b3`. Rafay's last three, on `apimatic.schema.json`: the sign-in token in the description of `scripts` (`15aaf820`, resolved), plain words for what `googleConsentMode` leaves to listed scripts (`144c6b73`, resolved), and defining the four categories and saying why there are four (`482418b2` and "Decisions on record", answered and left open for Rafay). The rule Rafay added to `.ai/instructions.md` in `3fc4fdd3` is applied by `665c8ef9`. - [x] **The docs**, in apimatic/apimatic-docs#887 at `0b13cb5c`, have the `portal.scripts` page with `category` required, the CLI row with the flag's wording, a consent section for `googleConsentMode`, the sign-in section as it works since #478, the three renamed event keys, and what the re-review's fixes change for a reader of them, and what belongs in each category. That PR stays a draft until this is in a full release. - [ ] **apimatic/apimatic-io#2347, #2348 and #2349** record the decisions above. - [ ] **The portal tests** of apimatic/v4-test-automation, which run on a push to `dev` and not on a pull request: dispatch them on this branch. ## Test plan, automated Run on the tree of `6782e26c`; the lint and the analytics and feed tests again on `6ed31b30`, and the build test on `8d117512`. After the merge with `dev`, on `310f38ab`: `tsc` for all three, `eslint .`, every `test/portal-template` file with the config, schema and flag tests (1,130 passing), and both end-to-end files (79 and 6 passing). After the second review's fixes, on the tree of `07ee1f45`: `tsc` for all three, every `test/portal-template` and `test/types/portal` file with the schema, flag, `portal-source-context`, `portal-project-service`, `serve` and `quickstart` tests (1,449 passing), and both end-to-end files (79 and 6 passing); `eslint .` on `07ee1f45` itself. After the two follow-ups, on the tree of `94c58970`: `tsc` for all three, those unit files with `prepare-project` and `portal-template.test.ts` (1,491 passing), and both end-to-end files (80 and 6 passing); `eslint .` on `94c58970` itself. `17ddf35f` and `1547e424` each passed the type checks and those unit files on their own. After the three commits of 2026-11-18, on the tree of `367cf0be`: `tsc` for the CLI and the tests, the unit files those commits touch with the config, schema, source, project, serve and template ones (792 passing), `test/e2e/portal-build.test.ts` (80 passing) and `eslint .`. `tsc` for the template was run after the two renames, which are all that touch it. After `37db2b44`: `tsc` for the template and the tests, the analytics and feed tests (100 passing) and `eslint .`. After the seven commits that answer the re-review, on `ae99bcc1`: `tsc` for all three, the config, schema, source, project, serve and template unit files (804 passing), both end-to-end files (81 and 6 passing) and `eslint .`. After the three commits that follow, on `6792fa8d`: `tsc` for all three, the same unit files (805 passing), both end-to-end files (81 and 6 passing) and `eslint .`. After the four of 2026-11-19, on `665c8ef9`: the same again (805, 81 and 6 passing), with the schema test after each schema commit. - [x] `tsc` for the CLI, the tests and the template (the template's known errors from ungenerated files only). - [x] `eslint` on each step's CLI and test files, and `prettier` on every changed TypeScript file. Neither reads the schema, and `eslint` skips the template's `lib/`. - [x] Unit: `portal-config`, `portal-source-context`, `preview-config`, `portal-project-service`, `schema`, `analytics`, `event-feed`, `portal-template`, and the action and command tests that read the default fixture. Each step added tests to its own files. - [x] `eslint .`, the whole tree, as CI runs it after the tests: clean on `6ed31b30`, on `07ee1f45`, on `94c58970`, on the tree of `367cf0be`, on `ae99bcc1`, on `6792fa8d` and on `665c8ef9`. - [x] `APIMATIC_E2E=1` with `test/e2e/portal-build.test.ts`: 81 passing on `ae99bcc1`, 80 on `94c58970` and on the tree of `367cf0be`, 79 before the consent mode's test. `APIMATIC_E2E=1` with `test/e2e/portal-serve.test.ts`: 6 passing, again on `ae99bcc1`. Both again on `6792fa8d` and `665c8ef9`: 81 and 6. ## Test plan, in a browser (run on Windows: headless Chrome, and one run in Firefox and in WebKit) Against `portal serve` and against `portal generate` output served statically, with GTM and GA4 set. Listed addresses pointed at a local `https` host, so order, delay, failure and silence were exact. - [x] **Order and place.** Scripts sit in `` after the vendor tags, `async` false, and run in list order with the first served 1.5 s late. Seen on a preview and on a built portal. No prerendered page names one. - [x] **Once per page.** After three page changes through the portal's links, each element is there once, ran once and was fetched once, an address with a `\` in its query included. - [x] **A static file.** Loads from `/js/…`, and from `/docs/js/…` with a path in `portal.site.url`, on a preview and on a built portal. - [x] **A missing file.** `portal generate` fails naming `portal.scripts[1].src`, and names the spelling on disk when only the case differs. A config save under `serve` that names one is refused and the page keeps what it had. - [x] **Categories** (run before `367cf0be`, when an entry could still have none). Six probes (one per category, one with none, one static file marked `necessary`). Without the flag all six run, on a preview and a built portal. With `--no-analytics`, on both: only the `necessary` and `functional` ones run, the host is never asked for the others, no Google tag is on the page, the page view is still reported. In the built files, none of 138 holds a dropped address or either ID. - [x] **Config saves under `serve`.** Adding a script reloads the page with it. Editing the description reloads nothing. Under `--no-analytics`, adding an `analytics` script changes nothing and adding a `necessary` one reloads with it. - [x] **Subscribe.** A listed file with four subscribers: a forwarder got the page view from before it loaded, then two page changes, a code copy and a search, the same five events in the same order as the data layer. Each had exactly `name`, `params`, `time`, `version`, both objects frozen. A subscriber that tried to change events changed nothing the next one saw. A one-time subscriber got one event and stopped. A throwing one showed one console error per event and stopped nothing. All of this on a preview; on a built portal under a path, the replay, a page change, the one-time subscriber and the throwing one. - [x] **Through a config save.** A subscriber from before a save that changed nothing got the next page view. - [x] **Around a sign-in** (preview, on `310f38ab`). On `/oauth/callback?code=…&state=…`: no vendor tag, no listed script, no page view. Sent back from the callback to the page that started the sign-in: that page's address is its own, the tag and every listed script load at once, and the page view has the clean address. A listed script starting there could read the answer in session storage; on the API reference page it was gone once the playground had loaded, and on a guide page it stayed. The callback was opened by hand with a typed `code` and `state`, and the starting page put in session storage, not a provider's round trip. - [x] **A `state` of the customer's own** (`?state=CA`, and `?code=…&state=…` in a page's own link; on `310f38ab`): the tag and every listed script load at once, and the page view is reported without them. - [x] **A script that fails** (a host that does not resolve), first in the list: the next ones run, the page works. - [x] **A script that never answers**, first and last in the list: see "Known limits". - [x] **Replay markers.** A listed script with its own `MutationObserver` saw the playground dialog already carrying every marker. - [x] **A script that removes its own element** (preview, on the tree of `07ee1f45`). Before the fix it ran twice on the first page and once more on each page change. After it, once for the whole visit, across three page changes. - [x] **A page that locked `window.apimatic`** (same preview), read-only and with a getter alone. Before the fix the bundle threw and the page never came to life: no theme switch, no listed script, no Google tag. After it the theme switch works, the Google tag and the listed scripts load, and the console shows the error. Run on the tree of `07ee1f45`; since `f7518097` the read-only case gets `subscribe()` and shows no error (below). - [x] **What the window holds** (same preview). No name on the window holds `portal`, and `window.apimatic.analytics` has `subscribe` alone, frozen. A callback written without strict mode that pushes to `this.vendorQueue` filled `window.vendorQueue`. - [x] **Config saves again** (same preview). Saving a description reloads nothing, runs no script again and keeps the subscriber. Adding a script reloads the page with it. - [x] **A consent script against the built-in tags** (on the tree of `94c58970`; every hit was answered in the browser, so none reached Google). With `googleConsentMode` and a consent stand-in 1.5 s late: the data layer leads with the portal's default, no cookie is set, and the page view is marked denied, on a preview and on built files. Without the setting the same run set `_ga` cookies and sent the page view with no consent state. - [x] **A reader who agrees** (preview). After `gtag('consent', 'update', …)` the cookies appear and the next hit is marked granted. A returning reader whose answer came 300 ms after Google's library ran got a first page view marked granted. - [x] **A GTM container** (preview, GTM-KRV5DMCJ) with the setting: the default leads the data layer, no cookie is set, and hits are marked denied. - [x] **A config save that adds the setting** (preview) reloads the page, whose data layer then leads with the default. - [x] **`--no-analytics` and the event feed** (preview and built files). A kept `functional` script that subscribes ran once and was handed nothing across three page views. `subscribe()` gave back a function, called detached too; the data layer held each page view; there was no `window.gtag` and no Google tag. Without the flag the same script got all three. Run before `a895b2cd`: with the consent setting, such a build now queues the default and has a `window.gtag`. Since `b9450b72` the data layer holds no page view either (below). - [x] **`--no-analytics` and the data layer** (built files on `6792fa8d`, `googleConsentMode` set, a `necessary` script standing in for a tag manager that watches the data layer, and Google's own snippet listed as `functional`). After a fresh load, a page change and a search, the data layer holds the consent default, the snippet's own commands and Google's `gtm.dom` and `gtm.load`, and no `docs_` event. The stand-in saw no portal event, a subscriber got none, no cookie was set, and the snippet's page view was marked denied. - [x] **A host with a Content Security Policy** (built files at `94c58970`). With neither host in `script-src`, the listed address and Google's tag are refused, the listed file after them still runs and gets its events, and the theme switch and the in-app links work. With both hosts added, everything loads. - [x] **A real consent tool** (vanilla-cookieconsent 3.1.0, open source, listed in `portal.scripts` beside GA4 built in with `googleConsentMode`, and wired to Consent Mode as its guide shows; a preview at `94c58970`). On a first visit the banner is up, the portal's default leads the data layer, no cookie is set and the page view is marked denied. After "Accept all" the tool sends its update, the `_ga` cookies appear and the next hit is marked granted. On a return visit with the answer stored there is no banner, the update lands ahead of the first page view, and that page view is marked granted. Tag Assistant was not used: the hits themselves were read. - [x] **A real session recorder** (rrweb 2.0.0-alpha.4, listed in `portal.scripts`; the same preview). With the playground open, a number typed into its field is not in the recording, which holds a blocked placeholder for the dialog. A term typed into the search box is in it. This proves the `rr-block` marker alone; the markers for Hotjar, Clarity, FullStory, LogRocket, PostHog and Amplitude were not tried against those tools. - [x] **Firefox and WebKit** (Playwright 1.64.1 on Windows: Firefox 157.0, and WebKit 27.2, the engine Safari uses; built files at `94c58970`). In both: the listed scripts sit in `` in list order and not async; with the first served 1.5 s late, the files after it still ran after it; each ran once across four page views, one that removes its own tag included; a forwarder got every page view, and a late subscriber was handed all four; `subscribe` alone, frozen; the theme switch and in-app links work, with no error. - [x] **The renamed keys** (a preview with both renames, GA4 built in, every hit answered in the browser). A code copy, an SDK download and two searches, one closed and one with a pick, reach the data layer, a subscriber and GA4's own hits as `code_language`, `sdk_language` and `picked_result`. GA4's language field stays `en-us` on each. Before the rename a code copy set it to the code's language. - [x] **A heading called "gtag"** (built files; a preview does not show it, since its heading is not in the page when the script starts). Before `9a6e19b4`, on a fresh load of a guide with that heading: `window.gtag` is the heading, the console shows `a(...) is not a function`, search does not open, the theme switch does nothing, no listed script runs and no hit is sent. After it all of those work and the consent default leads the data layer. - [x] **A staging build that lists Google's own snippet** (built with `--no-analytics` on `ae99bcc1`, the snippet listed as `functional`, `googleConsentMode` set and no built-in tag). The data layer leads with the consent default, no cookie is set, the snippet's page view is marked denied, and a subscriber is handed nothing. - [x] **A script the host injects** (built files on `ae99bcc1`, the tag for a listed file added to one page's `` by hand). It runs once and `` holds one tag for it, on the fresh load and after two page changes. - [x] **A host's own object at `window.apimatic`** (same files, the object set before the portal's script). After the start it is the same object, its class's method works, and `subscribe` is there. A read-only `window.apimatic` holding an ordinary object gets `subscribe` too, with no error. - [x] **An address with a backslash for its host** (`portal generate` on `ae99bcc1`). Refused for a listed script and for `pluginUrl`, with the report that asks for a host; so is `https:///…`. A backslash in the path is accepted. - [x] **After the helpers were inlined** (built files on `665c8ef9`). The four checks above for `ae99bcc1` (a heading called "gtag", a script the host injects, a host's own object and a read-only `window.apimatic`, a staging build with Google's own snippet) and the data layer check for `6792fa8d` give the same results. - [x] **Config saves after `37db2b44`** (preview, on its tree). Saving a description reloads nothing and runs no script again, and the subscriber gets the next page view. Adding a script reloads the page with it, and a counter kept across the reload shows the added script ran once. - [x] **A config with no category** (`portal generate`, on the tree of `367cf0be`). It stops and reports `'portal.scripts[0].category' is required.` for the entry that names none, and the four choices for one that is misspelt. 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Muhammad Sohail Co-authored-by: Claude Fable 5.2 Co-authored-by: Muhammad Rafay Nadeem --- .ai/instructions.md | 2 +- README.md | 6 +- apimatic.schema.json | 54 +- portal-template/src/components/code-copy.tsx | 2 +- .../src/components/sdk-actions.tsx | 2 +- portal-template/src/lib/analytics.ts | 80 ++- portal-template/src/lib/event-feed.ts | 60 ++ portal-template/src/lib/portal-analytics.ts | 2 +- portal-template/src/lib/portal-types.ts | 14 + portal-template/src/lib/search-report.ts | 4 +- portal-template/src/lib/vendor-tags.ts | 63 +- src/types/flags-provider.ts | 3 +- src/types/portal-source-context.ts | 4 +- src/types/portal/config/analytics-config.ts | 48 +- src/types/portal/config/brand-config.ts | 7 +- src/types/portal/config/fields.ts | 19 +- src/types/portal/config/script.ts | 76 +++ src/types/portal/portal-config.ts | 42 +- src/types/portal/portal-source.ts | 2 +- test/actions/portal/serve.test.ts | 33 +- test/actions/quickstart.test.ts | 4 +- test/e2e/portal-build.test.ts | 48 +- .../portal-project-service.test.ts | 54 +- test/portal-template/analytics.test.ts | 635 ++++++++++++++++-- test/portal-template/event-feed.test.ts | 192 ++++++ test/portal-template/search-report.test.ts | 6 +- .../default/src/static/js/widget.js | 1 + test/types/apimatic-config/schema.test.ts | 89 ++- test/types/portal-source-context.test.ts | 73 +- test/types/portal/portal-config.test.ts | 279 +++++++- test/types/portal/preview-config.test.ts | 8 + 31 files changed, 1744 insertions(+), 168 deletions(-) create mode 100644 portal-template/src/lib/event-feed.ts create mode 100644 src/types/portal/config/script.ts create mode 100644 test/portal-template/event-feed.test.ts create mode 100644 test/resources/portal-inputs/default/src/static/js/widget.js diff --git a/.ai/instructions.md b/.ai/instructions.md index 5239d30df..afc70d8bb 100644 --- a/.ai/instructions.md +++ b/.ai/instructions.md @@ -106,7 +106,7 @@ Supporting: **Types** (`src/types/`) for value objects, context objects, and dom - **No private instance methods** — a class has `private readonly` fields and public methods; a helper is a `private static` method or a module-level function. - **No middlemen** — a method does something with each argument (reads it, transforms it, or combines it with the object's own state); no method only forwards to another call, and no layer re-exposes a service one to one. - **Functional core, imperative shell** — a step reads every fact it needs first, decides as a pure function over that data, then does its I/O. `execute` is the script of the run and the only place that speaks; prompts word the data they are handed and decide nothing; a value with several outcomes (`ShareHook`, `SnapshotFetch`, `ActionResult`) offers `match` over named handlers, so a caller that leaves one out fails to compile; contexts answer data and never print. -- **Good code is not more functions** — a step's logic stays together where it reads as one thing; a function is split out only when it is used twice, when it separates a decision from I/O, or when its name says something the reader would otherwise work out. A one-line call does not get a wrapper. +- **Good code is not more functions** — a step's logic stays together where it reads as one thing; a function is split out only when it is used twice, when it separates a decision from I/O, or when its name says something the reader would otherwise work out. Even then, a function or method whose boilerplate (its doc comment, signature and closing brace) has more characters than its body is an unnecessary abstraction, such as a wrapper around a one-line call: inline it. - **One prompts class per action** — wording is repeated per class rather than shared through a prompt module. - **Flag descriptions match the docs** — a flag's `description` (which the generated README carries) and its row in apimatic-docs' CLI Reference (`v4/src/content/apimatic-cli/cli-reference.mdx`) say the same words; change both, or flag the mismatch. - **Telemetry** — After `outro(result)`, commands optionally track failures via `result.match({ success: () => {}, failed: async () => { await new TelemetryService(configDir).trackEvent(new SomeFailedEvent(...), shell) }, cancelled: () => {}, actionRequired: () => {} })`. Event classes extend `DomainEvent` (`src/types/events/`). Only the `failed` handler is populated; the others are no-ops. diff --git a/README.md b/README.md index 8ee8c6b4f..799856540 100644 --- a/README.md +++ b/README.md @@ -306,7 +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 the Google Tag Manager and Google Analytics tags set in 'portal.analytics'. + --no-analytics leave out the tags set in 'portal.analytics' and each script in 'portal.scripts' whose + category is 'analytics' or 'marketing', and hand no event to the scripts that stay. --zip write the generated portal as a .zip archive. DESCRIPTION @@ -347,7 +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 the Google Tag Manager and Google Analytics tags set in 'portal.analytics'. + --no-analytics leave out the tags set in 'portal.analytics' and each script in 'portal.scripts' whose + category is 'analytics' or 'marketing', and hand no event to the scripts that stay. DESCRIPTION Preview your API Documentation Portal with live reload. diff --git a/apimatic.schema.json b/apimatic.schema.json index 78ea007da..954ddbd85 100644 --- a/apimatic.schema.json +++ b/apimatic.schema.json @@ -38,6 +38,11 @@ "description": "A path relative to 'src' inside the 'static' directory, for example 'static/images/logo.png'.", "pattern": "^\\s*(?:\\.[\\\\/])?static(?:[\\\\/](?!\\.{1,2}(?:[\\\\/]|\\s*$))[^\\\\/]*[^\\\\/\\s][^\\\\/]*)+\\s*$" }, + "httpsAddress": { + "type": "string", + "description": "An address starting with 'https://' and a host, with no spaces.", + "pattern": "^[hH][tT][tT][pP][sS]://[^\\s/\\\\?#]+(?:[/?#]\\S*)?$" + }, "color": { "type": "string", "description": "#rgb or #rrggbb, for example '#1d4ed8'.", @@ -226,6 +231,19 @@ } } }, + "googleConsentMode": { + "type": "object", + "description": "Starts Google's own tags in Google's Consent Mode: they load at once, set no cookies and mark every hit as denied until your consent tool calls gtag('consent', 'update'). Other vendors' tags inside a Google Tag Manager container need consent checks of their own there. Set it when a consent banner decides what is tracked. It does not affect which scripts in 'portal.scripts' are loaded, or when.", + "additionalProperties": false, + "required": ["default"], + "properties": { + "default": { + "type": "string", + "enum": ["denied"], + "description": "What the tags take a reader's answer to be until your consent tool gives one." + } + } + }, "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.", @@ -250,10 +268,40 @@ } } }, + "scripts": { + "type": "array", + "description": "Other vendors' scripts and widgets, loaded on every page in the listed order, except the OAuth callback page. They get the portal's events from window.apimatic.analytics.subscribe(). Any listed script can read what readers type into the API playground, and the token an OAuth 2.0 sign-in leaves in the browser's session storage, so list only vendors you trust.", + "items": { + "type": "object", + "additionalProperties": false, + "required": ["src", "category"], + "properties": { + "src": { + "description": "An address starting with 'https://' and a host, with no spaces, or a file in the 'static' directory, for example 'static/analytics.js'.", + "anyOf": [ + { + "$ref": "#/definitions/httpsAddress" + }, + { + "$ref": "#/definitions/staticPath" + } + ] + }, + "category": { + "type": "string", + "description": "What the script is for, in the four groups consent tools ask readers about. 'necessary': the portal needs it to work, or the law requires it, such as your consent tool. 'functional': a feature a reader sees or uses, which may remember their choices, such as a chat widget, a feedback form or a status banner. 'analytics': it measures how readers use the portal, such as an analytics tool, a session recorder or an A/B testing tool. 'marketing': it serves or measures advertising, or follows readers across sites, such as an ad pixel. A script that does more than one takes the last of these that applies, so a feedback widget that also records sessions is 'analytics'. --no-analytics leaves out the 'analytics' and 'marketing' scripts.", + "enum": ["necessary", "functional", "analytics", "marketing"] + } + } + } + }, "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.", - "pattern": "^[hH][tT][tT][pP][sS]://[^\\s/?#]+(?:[/?#]\\S*)?$" + "allOf": [ + { + "$ref": "#/definitions/httpsAddress" + } + ], + "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/portal-template/src/components/code-copy.tsx b/portal-template/src/components/code-copy.tsx index 4414d5388..4c57b2f72 100644 --- a/portal-template/src/components/code-copy.tsx +++ b/portal-template/src/components/code-copy.tsx @@ -7,7 +7,7 @@ import { analytics } from '@/lib/portal-analytics'; type Actions = NonNullable; export const reportCodeCopy = (language: string) => - analytics.report('docs_code_copy', { language: languageId(language) }); + analytics.report('docs_code_copy', { code_language: languageId(language) }); // Fumadocs' own, which any Actions a block is given replaces. const DefaultActions: Actions = ({ className, children }) => ( diff --git a/portal-template/src/components/sdk-actions.tsx b/portal-template/src/components/sdk-actions.tsx index 541e21229..32393a6c1 100644 --- a/portal-template/src/components/sdk-actions.tsx +++ b/portal-template/src/components/sdk-actions.tsx @@ -77,7 +77,7 @@ export function DownloadLink({ href, className, language, children }: Readonly analytics.report('docs_sdk_download', { language: languageId(language) })} + onClick={() => analytics.report('docs_sdk_download', { sdk_language: languageId(language) })} > {children} diff --git a/portal-template/src/lib/analytics.ts b/portal-template/src/lib/analytics.ts index 5d5a9b922..148d65e53 100644 --- a/portal-template/src/lib/analytics.ts +++ b/portal-template/src/lib/analytics.ts @@ -1,6 +1,7 @@ +import { EventFeed } from './event-feed'; import { isOAuthCallbackPath } from './oauth-callback'; -import type { PortalAnalytics } from './portal-types'; -import { type Adapter, adapters, insertTags } from './vendor-tags'; +import type { PortalAnalytics, PortalScript } from './portal-types'; +import { type Adapter, adapters, insertTags, queueConsentDefaults } from './vendor-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_']; @@ -26,9 +27,10 @@ export interface PortalEvents { docs_page_view: { page_title: string }; 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 }; + // Neither is named `language`: gtag takes that name on an event for the reader's own language. + docs_sdk_download: { sdk_language: string }; + docs_code_copy: { code_language: string }; + docs_search: { search_term: string; picked_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 }; @@ -37,11 +39,27 @@ export type PortalEventName = keyof PortalEvents; type DataLayerEntry = { docs: null } | { event: PortalEventName; docs: Readonly> }; +/** A symbol, so the window holds it under no name a script comes across and builds on. */ +const WINDOW_ANALYTICS = Symbol.for('apimatic.portal.analytics'); + +/** + * One per `Window` object (https://developer.mozilla.org/en-US/docs/Web/API/Window), which a reload replaces. + * Every instance in it shares this one: a config save under `portal serve` makes a second. + */ +interface WindowAnalytics { + /** The settings and scripts the window started with. */ + started: string; + feed: EventFeed; + /** The address of every script the head held at the start, and of each tag and script inserted since. */ + inserted: Set; +} + declare global { interface Window { dataLayer?: unknown[]; - /** Held by the window: a config save under `portal serve` evaluates this module again. */ - portalAnalyticsStarted?: string; + [WINDOW_ANALYTICS]?: WindowAnalytics; + /** What customers' scripts are given: `subscribe()` and nothing else. */ + apimatic?: { analytics?: Pick }; } } @@ -59,32 +77,58 @@ export function pageLocation(href: string, keep: readonly string[]): string { export class Analytics { private readonly live: Adapter[]; + /** The window's, once `start()` has made it or joined it: no other method reads the global. */ + private windowAnalytics: WindowAnalytics | undefined; private lastPageView: string | null = null; private previousPageView: string | null = null; private lastNotFound: string | null = null; - public constructor(private readonly settings: PortalAnalytics) { + public constructor(private readonly settings: PortalAnalytics, private readonly scripts: PortalScript[]) { this.live = Object.values(adapters) .map((build) => build(settings)) .filter((adapter) => adapter !== null); } 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. - if (window.portalAnalyticsStarted !== undefined) { - window.location.reload(); + const started = JSON.stringify([this.settings, this.scripts]); + const existing = window[WINDOW_ANALYTICS]; + if (existing !== undefined) { + // Other vendors or scripts after a config save: only a fresh window holds exactly their tags. + if (existing.started === started) this.windowAnalytics = existing; + else window.location.reload(); return; } - window.portalAnalyticsStarted = settings; + const feed = new EventFeed(); + // Each script the head holds already, by its src as written: a host may inject one of the portal's itself. + const head = document.head.querySelectorAll('script[src]'); + const inserted = new Set(Array.from(head, (script) => script.getAttribute('src') ?? '')); + this.windowAnalytics = { started, feed, inserted }; + window[WINDOW_ANALYTICS] = this.windowAnalytics; const dataLayer = (window.dataLayer ??= []); + if (this.settings.googleConsentMode !== null) queueConsentDefaults(dataLayer); for (const adapter of this.live) adapter.setup(dataLayer); - insertTags(this.live); + // Ours whatever the window held there first, and `subscribe` alone, bound so a script may call it on its own. + const analytics = Object.freeze({ subscribe: feed.subscribe.bind(feed) }); + try { + // On the host's own object if it takes one: a copy lacks its class's methods and is not the object it holds. + // A frozen object takes none, nor one that fixed the name. + const host: unknown = window.apimatic; + const property = { value: analytics, writable: true, enumerable: true, configurable: true }; + const taken = Object(host) === host && Reflect.defineProperty(host as object, 'analytics', property); + if (!taken) window.apimatic = { ...window.apimatic, analytics }; + } catch (error) { + // A host may have locked the name. Thrown later, so it shows in the console and the bundle goes on loading. + setTimeout(() => { + throw error; + }); + } + insertTags(this.live, this.scripts, inserted); } /** `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 { + // A `--no-analytics` build reports nothing, even to the data layer: a container a kept script loads reads it. + if (this.settings.events === 'off') return; if (isOAuthCallbackPath(new URL(href).pathname)) return; const docs = { ...params, page_location: pageLocation(href, this.settings.keepQueryParams) }; const dataLayer = (window.dataLayer ??= []); @@ -92,12 +136,14 @@ export class Analytics { dataLayer.push({ docs: null } satisfies DataLayerEntry); dataLayer.push({ event: name, docs } satisfies DataLayerEntry); for (const adapter of this.live) adapter.send?.(name, docs); + this.windowAnalytics?.feed.publish(name, docs); } public reportPageView(): void { if (isOAuthCallbackPath(window.location.pathname)) return; - // The tags a start on the OAuth callback left out, now that the reader has moved on from it. - insertTags(this.live); + const inserted = this.windowAnalytics?.inserted; + // The tags and scripts a start on the OAuth callback left out, now that the reader has moved on from it. + if (inserted !== undefined) insertTags(this.live, this.scripts, inserted); 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/event-feed.ts b/portal-template/src/lib/event-feed.ts new file mode 100644 index 000000000..d168c21d6 --- /dev/null +++ b/portal-template/src/lib/event-feed.ts @@ -0,0 +1,60 @@ +/** One portal event as a subscriber receives it. Customers' scripts read these keys, so `version` moves if one ever changes. */ +export interface PortalEvent { + readonly name: string; + /** The event's details, with `page_location` among them. */ + readonly params: Readonly>; + /** When it was reported, in milliseconds since the epoch. */ + readonly time: number; + readonly version: 1; +} + +type Subscriber = (event: PortalEvent) => void; +type Unsubscribe = () => void; + +interface Subscription { + callback: Subscriber; + deliveredCount: number; +} + +/** A window's events, for the scripts in it: a subscriber gets every one reported so far, then each new one. */ +export class EventFeed { + private readonly events: PortalEvent[] = []; + private readonly subscriptions = new Set(); + + public subscribe(callback: Subscriber): Unsubscribe { + if (typeof callback !== 'function') { + throw new TypeError('window.apimatic.analytics.subscribe() takes a function.'); + } + const subscription: Subscription = { callback, deliveredCount: 0 }; + this.subscriptions.add(subscription); + // Once this has returned, so a callback can call the function it returns, even for an earlier event. + queueMicrotask(() => EventFeed.deliver(this, subscription)); + return () => { + this.subscriptions.delete(subscription); + }; + } + + public publish(name: string, params: Record): void { + // A copy, frozen, so no subscriber changes what the next one gets, or what the data layer was handed. + this.events.push(Object.freeze({ name, params: Object.freeze({ ...params }), time: Date.now(), version: 1 })); + // The set itself: one a callback adds is reached in this same pass, and one it removes is skipped. + for (const subscription of this.subscriptions) EventFeed.deliver(this, subscription); + } + + private static deliver(feed: EventFeed, subscription: Subscription): void { + // Called on its own, so a callback written without strict mode finds the window as `this`, never this record. + const { callback } = subscription; + while (feed.subscriptions.has(subscription) && subscription.deliveredCount < feed.events.length) { + const event = feed.events[subscription.deliveredCount]; + subscription.deliveredCount += 1; + try { + callback(event); + } catch (error) { + // Thrown later, so it shows in the console and stops neither the next event nor the next subscriber. + setTimeout(() => { + throw error; + }); + } + } + } +} diff --git a/portal-template/src/lib/portal-analytics.ts b/portal-template/src/lib/portal-analytics.ts index d23527eb9..83f6aebbe 100644 --- a/portal-template/src/lib/portal-analytics.ts +++ b/portal-template/src/lib/portal-analytics.ts @@ -2,7 +2,7 @@ import { Analytics } from './analytics'; import { portal } from './portal'; import { markPlaygroundDialogs } from './replay-markers'; -export const analytics = new Analytics(portal.analytics); +export const analytics = new Analytics(portal.analytics, portal.scripts); // When the bundle starts, before React and before any vendor tag. Never during prerendering. if (typeof window !== 'undefined') { markPlaygroundDialogs(); diff --git a/portal-template/src/lib/portal-types.ts b/portal-template/src/lib/portal-types.ts index cbc8cc0e1..bb119d739 100644 --- a/portal-template/src/lib/portal-types.ts +++ b/portal-template/src/lib/portal-types.ts @@ -36,11 +36,19 @@ export interface GoogleAnalyticsSetting { measurementId: string; } +export interface GoogleConsentModeSetting { + /** What Google's tags take a reader's answer to be until a consent tool gives one. */ + default: 'denied'; +} + /** Public values: they sit in every page's scripts. */ export interface PortalAnalytics { googleTagManager: GoogleTagManagerSetting | null; googleAnalytics: GoogleAnalyticsSetting | null; + googleConsentMode: GoogleConsentModeSetting | null; keepQueryParams: string[]; + /** Off in a build made with `--no-analytics`, which reports no event: none to the data layer, none to a script. */ + events: 'on' | 'off'; } export interface PortalSeo { @@ -48,6 +56,10 @@ export interface PortalSeo { googleSiteVerification: string | null; } +export interface PortalScript { + src: string; +} + export interface Portal { name: string; description: string | null; @@ -61,4 +73,6 @@ export interface Portal { pageActions: boolean; analytics: PortalAnalytics; seo: PortalSeo; + /** In the order the block lists them, which is the order the browser runs them in. */ + scripts: PortalScript[]; } diff --git a/portal-template/src/lib/search-report.ts b/portal-template/src/lib/search-report.ts index 2b347b3ae..ec4692d77 100644 --- a/portal-template/src/lib/search-report.ts +++ b/portal-template/src/lib/search-report.ts @@ -23,6 +23,6 @@ export function searchOutcome(state: SearchDialogState): SearchOutcome { const search_term = state.term.trim().slice(0, TERM_LIMIT); const counted = (state.typed || state.picked !== '') && search_term !== ''; // 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 }; + const picked_result = state.picked === '' ? '' : pageLocation(state.picked, []); + return { ended: true, report: counted ? { search_term, picked_result, result_count: state.resultCount } : null }; } diff --git a/portal-template/src/lib/vendor-tags.ts b/portal-template/src/lib/vendor-tags.ts index bd0d92128..face79e84 100644 --- a/portal-template/src/lib/vendor-tags.ts +++ b/portal-template/src/lib/vendor-tags.ts @@ -1,5 +1,6 @@ +import { withBasePath } from './base-path'; import { isOAuthCallbackPath } from './oauth-callback'; -import type { PortalAnalytics } from './portal-types'; +import type { PortalAnalytics, PortalScript } from './portal-types'; type Gtag = (...command: unknown[]) => void; @@ -16,9 +17,34 @@ export interface Adapter { send?(name: string, params: Record): void; } -type Vendor = Exclude; +type Vendor = Exclude; const GOOGLE = 'https://www.googletagmanager.com'; +/** The window's own, or one made here: Google reads only Arguments objects from the data layer, never arrays. */ +function gtagFor(dataLayer: unknown[]): Gtag { + // Only a function: a browser answers `window.gtag` with an element whose id is `gtag`, such as a guide's heading. + const gtag = + typeof window.gtag === 'function' + ? window.gtag + : function () { + dataLayer.push(arguments); + }; + window.gtag = gtag; + return gtag; +} + +/** Ahead of every vendor's setup: Google reads a reader's answer from what is queued before its first event. */ +export function queueConsentDefaults(dataLayer: unknown[]): void { + gtagFor(dataLayer)('consent', 'default', { + ad_storage: 'denied', + ad_user_data: 'denied', + ad_personalization: 'denied', + analytics_storage: 'denied', + // Time for a consent tool to hand over a returning reader's answer, before the first hit goes out as denied. + wait_for_update: 500 + }); +} + /** 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 }) => { @@ -36,19 +62,17 @@ export const adapters: { [V in Vendor]: (settings: PortalAnalytics) => Adapter | if (setting === null) return null; return { setup: (dataLayer) => { - // gtag.js reads only Arguments objects from the data layer, never an array of the same values. - const gtag = (window.gtag ??= function () { - dataLayer.push(arguments); - }); + const gtag = gtagFor(dataLayer); gtag('js', new Date()); gtag('config', setting.measurementId, { send_page_view: false }); }, script: `${GOOGLE}/gtag/js?id=${encodeURIComponent(setting.measurementId)}`, send: (name, params) => { + // The window's gtag, since a second instance under `portal serve` never runs its setup; never an element. + if (typeof window.gtag !== 'function') return; // 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); + if (name === 'docs_page_view') window.gtag('set', { page_location: params.page_location }); + window.gtag('event', name.replace(/^docs_/, ''), params); } }; } @@ -57,15 +81,24 @@ export const adapters: { [V in Vendor]: (settings: PortalAnalytics) => Adapter | /** * None on the OAuth callback, whose address holds the provider's answer; each once, so a later call adds the rest. * The page a sign-in returns to loads them at once, although the answer waits in the tab's session storage until - * a playground reads it: tags read the address, not the storage, so that window is accepted. On a page that mounts - * no playground the answer stays until one mounts in the tab or the tab closes, as with Fumadocs' own handler. + * a playground reads it: tags read the address, not the storage, so that window is accepted. A listed script could + * read it there, as it could anything else on the page. On a page that mounts no playground the answer stays until + * one mounts in the tab or the tab closes, as with Fumadocs' own handler. */ -export function insertTags(live: Adapter[]): void { +export function insertTags(live: Adapter[], scripts: PortalScript[], inserted: Set): void { if (isOAuthCallbackPath(window.location.pathname)) return; - for (const { script: src } of live) { - if (document.head.querySelector(`script[src="${src}"]`) !== null) continue; + // A listed script is not async, so the browser runs them in the order listed, whichever arrives first. + const wanted = [ + ...live.map(({ script: src }) => ({ src, async: true })), + // A file of the portal's own is named from its root, which a host may serve under a path. + ...scripts.map(({ src }) => ({ src: src.startsWith('/') ? withBasePath(src) : src, async: false })) + ]; + for (const { src, async } of wanted) { + // Remembered, not looked up in the head: a vendor's loader may take its own element out once it has run. + if (inserted.has(src)) continue; + inserted.add(src); const script = document.createElement('script'); - script.async = true; + script.async = async; script.src = src; document.head.append(script); } diff --git a/src/types/flags-provider.ts b/src/types/flags-provider.ts index 899b955c0..1b8472e7c 100644 --- a/src/types/flags-provider.ts +++ b/src/types/flags-provider.ts @@ -36,7 +36,8 @@ 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'." + description: + "leave out the tags set in 'portal.analytics' and each script in 'portal.scripts' whose category is 'analytics' or 'marketing', and hand no event to the scripts that stay." }) }; diff --git a/src/types/portal-source-context.ts b/src/types/portal-source-context.ts index 8dd06d313..a57c9b007 100644 --- a/src/types/portal-source-context.ts +++ b/src/types/portal-source-context.ts @@ -306,7 +306,9 @@ export class PortalSourceContext { if (missingFiles.length > 0) { return err({ kind: 'missingStaticFiles', files: missingFiles }); } - return ok(build.analytics ? settings.value : { ...settings.value, config: settings.value.config.withoutVendors() }); + return ok( + build.analytics ? settings.value : { ...settings.value, config: settings.value.config.withoutAnalytics() } + ); } private async readConfigDocument(): Promise> { diff --git a/src/types/portal/config/analytics-config.ts b/src/types/portal/config/analytics-config.ts index 76ec59d2b..341d27f83 100644 --- a/src/types/portal/config/analytics-config.ts +++ b/src/types/portal/config/analytics-config.ts @@ -17,23 +17,33 @@ export interface GoogleAnalyticsSetting { measurementId: string; } +export interface GoogleConsentModeSetting { + /** What Google's tags take a reader's answer to be until a consent tool gives one. */ + default: 'denied'; +} + /** Public values: they sit in every page's scripts. */ export interface PortalAnalytics { googleTagManager: GoogleTagManagerSetting | null; googleAnalytics: GoogleAnalyticsSetting | null; + googleConsentMode: GoogleConsentModeSetting | null; keepQueryParams: string[]; + /** Off in a build made with `--no-analytics`, which reports no event: none to the data layer, none to a script. */ + events: 'on' | 'off'; } -const KNOWN = ['googleTagManager', 'googleAnalytics', 'keepQueryParams']; +const KNOWN = ['googleTagManager', 'googleAnalytics', 'googleConsentMode', 'keepQueryParams']; export class AnalyticsConfig { private constructor( private readonly googleTagManager: GoogleTagManagerSetting | null, private readonly googleAnalytics: GoogleAnalyticsSetting | null, - private readonly keepQueryParams: string[] + private readonly googleConsentMode: GoogleConsentModeSetting | null, + private readonly keepQueryParams: string[], + private readonly events: 'on' | 'off' ) {} - public static readonly defaults = new AnalyticsConfig(null, null, []); + public static readonly defaults = new AnalyticsConfig(null, null, null, [], 'on'); public static parse(value: unknown, path: string): Parsed { return namespace(value, path).andThen((data) => @@ -42,9 +52,10 @@ export class AnalyticsConfig { Result.combineWithAllErrors([ optional(data.googleTagManager, (vendor) => googleTagManager(vendor, `${path}.googleTagManager`)), optional(data.googleAnalytics, (vendor) => googleAnalytics(vendor, `${path}.googleAnalytics`)), + optional(data.googleConsentMode, (mode) => googleConsentMode(mode, `${path}.googleConsentMode`)), keptQueryParams(data.keepQueryParams, `${path}.keepQueryParams`) ]) - ).map(([gtm, ga, keep]) => new AnalyticsConfig(gtm, ga, keep)) + ).map(([gtm, ga, consent, keep]) => new AnalyticsConfig(gtm, ga, consent, keep, 'on')) ); } @@ -57,13 +68,19 @@ export class AnalyticsConfig { return { googleTagManager: this.googleTagManager, googleAnalytics: this.googleAnalytics, - keepQueryParams: this.keepQueryParams + googleConsentMode: this.googleConsentMode, + keepQueryParams: this.keepQueryParams, + events: this.events }; } - /** 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); + /** + * For a staging build: no tag, and no event in the data layer or for a script; an address keeps the same names. + * The consent default stays, since a script the build keeps may load a Google tag of its own, which has to start + * as denied there too. + */ + public withoutAnalytics(): AnalyticsConfig { + return new AnalyticsConfig(null, null, this.googleConsentMode, this.keepQueryParams, 'off'); } } @@ -104,6 +121,21 @@ function googleAnalytics(value: unknown, path: string): Parsed ({ measurementId })); } +// An object with one key, so a key added later (a wait, regions) changes no config written today. +function googleConsentMode(value: unknown, path: string): Parsed { + if (!isJsonObject(value)) { + return err([`'${path}' must be a JSON object with 'default'.`]); + } + return allOf( + unknownKeys(value, ['default'], path), + Result.combineWithAllErrors([required(value.default, `${path}.default`, denied)]) + ).map(([given]) => ({ default: given })); +} + +function denied(value: unknown, path: string): Parsed<'denied'> { + return value === 'denied' ? ok('denied') : err([`'${path}' must be 'denied'.`]); +} + /** 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/brand-config.ts b/src/types/portal/config/brand-config.ts index 0cf5cb9d2..04225c901 100644 --- a/src/types/portal/config/brand-config.ts +++ b/src/types/portal/config/brand-config.ts @@ -91,9 +91,12 @@ export class BrandConfig { optional(data.logo, (logo) => Logo.parse(logo, `${path}.logo`)), optional(data.favicon, (favicon) => StaticAsset.parse(favicon, `${path}.favicon`)), BrandColors.parse(data.colors, `${path}.colors`), - oneOf(data.colorMode, `${path}.colorMode`, COLOR_MODES, BrandConfig.defaults.colorMode) + optional(data.colorMode, (colorMode) => oneOf(colorMode, `${path}.colorMode`, COLOR_MODES)) ]) - ).map(([logo, favicon, colors, colorMode]) => new BrandConfig(logo, favicon, colors, colorMode)) + ).map( + ([logo, favicon, colors, colorMode]) => + new BrandConfig(logo, favicon, colors, colorMode ?? BrandConfig.defaults.colorMode) + ) ); } diff --git a/src/types/portal/config/fields.ts b/src/types/portal/config/fields.ts index ef581704a..9e24487c9 100644 --- a/src/types/portal/config/fields.ts +++ b/src/types/portal/config/fields.ts @@ -81,10 +81,7 @@ export function optionalBoolean(value: unknown, path: string, fallback: boolean) return typeof value === 'boolean' ? ok(value) : err([`'${path}' must be true or false.`]); } -export function oneOf(value: unknown, path: string, allowed: readonly T[], fallback: T): Parsed { - if (value === undefined) { - return ok(fallback); - } +export function oneOf(value: unknown, path: string, allowed: readonly T[]): Parsed { if (typeof value === 'string' && (allowed as readonly string[]).includes(value)) { return ok(value as T); } @@ -104,3 +101,17 @@ export function nonEmptyString(value: unknown, path: string): Parsed { ? ok(value.trim()) : err([`'${path}' must be a non-empty string.`]); } + +// The same addresses as `httpsAddress` in the schema, so an editor and a build give one verdict on a missing host. +// No backslash in the host: an address parser reads one as a slash, and takes what follows it for the host. +const HTTPS_ADDRESS = /^https:\/\/[^\s/\\?#]+(?:[/?#]\S*)?$/i; + +// https, since what it names is fetched and run; parsed, so it holds no space or quote wherever it is written out. +export function httpsAddress(value: unknown, path: string, example: string): Parsed { + const url = typeof value === 'string' && HTTPS_ADDRESS.test(value) ? URL.parse(value) : null; + return url === null + ? err([ + `'${path}' must be an address starting with 'https://' and a host, with no spaces, for example '${example}'.` + ]) + : ok(new UrlPath(url.href)); +} diff --git a/src/types/portal/config/script.ts b/src/types/portal/config/script.ts new file mode 100644 index 000000000..05226835d --- /dev/null +++ b/src/types/portal/config/script.ts @@ -0,0 +1,76 @@ +import { err, ok, Result } from 'neverthrow'; +import { isJsonObject } from '../../../utils/json-utils.js'; +import { UrlPath } from '../../file/urlPath.js'; +import { allOf, httpsAddress, oneOf, Parsed, required, unknownKeys } from './fields.js'; +import { StaticAsset } from './static-asset.js'; + +const KNOWN = ['src', 'category']; + +export const SCRIPT_CATEGORIES = ['necessary', 'functional', 'analytics', 'marketing'] as const; + +const ADDRESS_EXAMPLE = 'https://cdn.example.com/widget.js'; + +const FILE_EXAMPLE = 'static/analytics.js'; + +export interface PortalScript { + /** An https address, or the portal-relative path of a file in the static directory. */ + src: string; +} + +/** A script of the customer's own, which the portal loads on every page. */ +export class Script { + private constructor( + private readonly source: UrlPath | StaticAsset, + private readonly category: (typeof SCRIPT_CATEGORIES)[number] + ) {} + + public static parseList(value: unknown, path: string): Parsed { + if (value === undefined) { + return ok([]); + } + if (!Array.isArray(value)) { + return err([`'${path}' must be a list of scripts.`]); + } + return Result.combineWithAllErrors(value.map((script, index) => Script.parse(script, `${path}[${index}]`))).mapErr( + (errors) => errors.flat() + ); + } + + /** The file it names in the static directory; none for an address. */ + public staticFiles(): StaticAsset[] { + return this.source instanceof StaticAsset ? [this.source] : []; + } + + /** Whether a portal built with `--no-analytics` still loads it. */ + public loadsWithoutAnalytics(): boolean { + return this.category === 'necessary' || this.category === 'functional'; + } + + public identity(): PortalScript { + return { src: this.source instanceof StaticAsset ? this.source.portalPath() : this.source.toString() }; + } + + private static parse(value: unknown, path: string): Parsed