Repository navigation
feat(portal): load custom scripts from portal.scripts - #477
Open
sohail2721 wants to merge 25 commits into
Open
sohail2721 wants to merge 25 commits into
sohail2721 wants to merge 25 commits into
Conversation
Each entry is { src }, an https address. The loader inserts them after
the vendor tags, in list order and not async, under the same hold on an
OAuth answer. The key a start runs once by covers the list, so a config
save under portal serve reloads with exactly the new one.
An inserted tag is now found by its src attribute as written: a selector
built from a customer's address misses on a backslash, and the script
would be inserted again on every page view.
Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
A src that does not start with http: or https: names a file under static/. It is checked on disk with the brand's files, written to the identity file as its portal path, and inserted under the base path when the portal is hosted under one. A src that is neither an https address nor a file in static/ gets one report naming both choices, since a path that is no file is often an address without its https://. Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
…alytics A listed script takes a category: necessary, functional, analytics or marketing, and analytics when it names none. Under --no-analytics only necessary and functional scripts reach the portal, for a build, a preview and each config save alike. PortalConfig.withoutVendors() is withoutAnalytics() now that it drops more than the vendors, and the flag's help and the README say what it leaves out. Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
…pimatic
window.apimatic.analytics.subscribe(callback) hands a script every
event reported so far and then each new one, as a frozen
{ name, params, time, version: 1 }, and returns the function that
stops delivery. The feed is the page's, so a subscriber outlives the
second Analytics instance a config save under portal serve makes.
Earlier events arrive just after subscribe() returns, never inside
it, so a script can call the function it got back on the first event.
Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
An editor pointed at the schema now offers scripts, with src as an https address or a file in static/ and the four categories. The address pattern pluginUrl had is one definition both settings use. The schema test holds the schema and the parser to the same verdict on each scripts case, and the schema's categories to the parser's list. Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
The default build now lists an address and a file from static/. The built files have to hold both in a browser script, ship the file where its address points, carry the feed scripts subscribe to, and name neither script in a prerendered page. Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
…nter The script set a property on window, which the whole-tree lint that runs after the tests refuses in a file with no browser environment. The test only checks that the file ships, so it now holds a comment and nothing else. Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
The feed itself sat there. A script could publish events or empty the history, subscribe threw when taken off the object and called on its own, and an object a page had put at that name first made every report throw. Scripts now get a frozen object holding a bound subscribe, put in place whatever was there before, and the feed is held at window.portalEventFeed, where the reporter publishes to it. Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
The conventions leave a class with public methods and private static helpers, and deliver() was a private instance method. Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
insertTags() listed every script in the head again for each tag and listed script it wanted, on every page view. It now reads them once into a set, which still keeps an address listed twice to one element. Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
sohail2721
marked this pull request as ready for review
November 17, 2026 04:39
sohail2721
requested review from
Shield-Jaguar and
saeedjamshaid
as code owners
November 17, 2026 04:39
publish() copied the set before handing an event over, in case a callback subscribed or unsubscribed meanwhile. The set's own iteration already reaches one added in the same pass and skips one removed, and deliver() checks a subscriber is still there, so the copy did nothing. Two tests pin both cases. Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
sohail2721
added a commit
that referenced
this pull request
Nov 17, 2026
…trings in their boxes (#478) Takes fumadocs-openapi from 12.6.0 to 12.6.5. That release fixes points 3 to 6 of apimatic/apimatic-io#2350, which we reported upstream as fuma-nama/fumadocs#3864 and fuma-nama/fumadocs#3865. With it, the playground's sign-in moves to the hand-over Fumadocs added in 12.6.2, which keeps the provider's answer out of page addresses. **12.6.5 is one day old, younger than the seven days `minimumReleaseAge` asks for.** It is merged early by decision: see "Merged before the seven days". ## What a portal gets - **A long field path in the playground stays in its panel** (points 4 and 5). The middle crumbs truncate, and Unset / Remove stay in reach. - **A long unbroken string wraps inside its box** (points 3 and 6): in a property card, a security scheme's card, and the field info popover. - **From 12.6.3, credentials are masked.** API keys and tokens are typed into password inputs, and the cURL sample shows a credential as `********`. - **From 12.6.3, the playground's rows look different.** An optional field outside the request is a muted row that one click adds; a field's name opens its description. - **From 12.6.4, the playground and the cURL sample build some requests correctly:** path parameter values are percent-encoded, form bodies keep `0`, `false` and empty fields, and cookie parameters are sent as the specification says. - **A sign-in's answer stays out of page addresses.** After a playground sign-in the reader lands back on the endpoint page at its own address; the provider's code or token no longer passes through it. The Google tags therefore load there at once, and a page opened through a link of its own ending in `?state=…` loads them too, where it used to wait for the next page. ## What changes here - `package.json`: `fumadocs-openapi` 12.6.5, and `lucide-react` 1.71.0, the lowest version 12.6.5 accepts, so there is still one copy of it. - `pnpm-lock.yaml`: five packages change (the two above, `@scalar/openapi-upgrader` 0.4.8, `@scalar/openapi-types` 0.9.9, and a new `@scalar/helpers` 0.17.1). - `pnpm-workspace.yaml`: `@scalar/json-magic` is held at 0.16.1 under `fumadocs-openapi`. 12.6.5 asks for 0.19, whose floor is Node 22.19, above the CLI's 22.14, so CI's `--engine-strict` install would refuse it. This is the same hold `chokidar` and `undici` already have. - `usage-tabs.tsx`: one comment, which said the cURL sample shows typed credentials. The sign-in hand-over, in its own commit: - `oauth-callback.ts`, `oauth.callback.tsx`: the callback page leaves its address, the provider's answer in it, in the tab's session storage, where the playground reads it since 12.6.2, and sends the reader back to the page that started the flow at that page's own address. Until now it sent them back with the answer still in the query or the `#` part. - `vendor-tags.ts`, `analytics.ts`, `playground.tsx`: the tags no longer wait for an answer to leave the address. `insertTags()` holds back on the callback page alone, and `holdsOAuthAnswer()` and `Analytics.loadTags()` are gone. - `oauth-callback.test.ts`: a new test runs Fumadocs' own handler script beside ours and holds both to the same entry in the session and the same page, so a move of that entry upstream fails the test and not a portal. Apart from that, the template compiles and behaves as before against 12.6.5. ## Merged before the seven days `fumadocs-openapi@12.6.5` turns seven days old on 23 Nov 2026 at 11:58 UTC. #472 waited for that day. This PR does not: the decision is to take the fix now. What that costs until 23 Nov: - **A full re-resolution fails.** `pnpm dedupe` stops with `ERR_PNPM_NO_MATURE_MATCHING_VERSION` for `fumadocs-openapi@12.6.5`. A run that needs one adds `fumadocs-openapi@12.6.5` to `minimumReleaseAgeExclude` for that run only. - **Nothing else changes.** CI installs from the frozen lockfile, which never resolves, and `pnpm install` and `pnpm add` work as before. What speaks for the release: - It was published by Fumadocs' GitHub Actions with npm provenance, as 12.6.0 was, and it runs no install scripts. - The fix itself is one commit that changes class names in five files, fuma-nama/fumadocs@2419e7c. - The whole package was not compared with 12.6.0, and the step also takes in 12.6.1 to 12.6.4, which are three to five days old. - The other four new packages turn seven days old on 17 Nov, by 14:46 UTC. After 23 Nov, `pnpm dedupe --check` should pass without any exception. That is a check only: nothing in the lockfile needs to change. The lockfile here was resolved with a temporary `minimumReleaseAgeExclude` of five exact versions, which is not in this PR. ## A risk to know about Because of the `@scalar/json-magic` hold, the tests in this repository run json-magic 0.16.1, while an `npm install -g` of the CLI gets 0.19.1. The CLI loads this package (Fumadocs reads a specification through its magic proxy), and 0.19 rewrote that proxy. The portal tests workflow installs the packed CLI as npm does, so it covers the 0.19 side, but it runs on a push to `dev`, so only after this merges, and on Node 24. I checked that side by hand before then (below): on Node 24, and on Node 22.14.0, the CLI's floor, which is below the 22.19 that json-magic 0.19 declares. ## Checked - `test/e2e/portal-build.test.ts`: 78 passing, with the template's type-check against 12.6.5 among them. - `test/e2e/portal-serve.test.ts`: 6 passing. - The portal template's unit tests and the portal type tests: 550 passing. - No package in the lockfile is refused on Node 22.14.0 under `--engine-strict`. - I did not run the whole suite locally. In headless Chrome, on portals built from this branch with a neutral spec: | Problem | 12.6.0 | 12.6.5, as built | | --- | --- | --- | | Form under the request panel, three levels deep, 827 px wide | panel 425 px in a 400 px column | 400 px, middle crumbs truncate | | Unset hidden, five levels deep, 1142 px wide | panel 656 px in a 574 px column, Unset cannot be clicked | 574 px, Unset can be clicked | | Long inline code in a parameter's description | 7 px past the card's edge | inside the card | | Long string in the field info popover | 322 px of text in a 262 px box | no overflow | - **A playground sign-in, start to finish**, against a stand-in OAuth provider, through the hand-over: - The authorization code flow, with PKCE, and the implicit flow both sign in, and a request goes out with each one's token. - The reader returns from `/oauth/callback` to the endpoint page at its own address, the tags load there at once, and the entry the callback left in the session is gone once the playground has read it. - The refused case shows the provider's error on the callback page. - The callback page loads no tag and reports nothing, with an answer nobody started as well. A link from it loads the tags on the next page. - A page opened with `?state=CA` loads its tags at once and is reported without the parameter. - **The build a user gets**: the packed CLI installed with npm resolves 12.6.5 with json-magic 0.19.1, undici 8 and chokidar 6. It builds the same portal, and the four measurements above are the same. The tests above ran again after the hand-over commit. The four measurements, the npm-installed build and the Node 22.14.0 checks below ran before it; that commit changes the sign-in's browser code only. ### On Node 22.14.0 The packed CLI, installed by npm running on Node 22.14.0 (the official Windows build), as a customer on the CLI's lowest Node gets it: - **It installs**, with `EBADENGINE` warnings for `@scalar/json-magic@0.19.1`, `chokidar@6.0.0`, `undici@8.12.4` and `undici@8.12.3`. The first and the last are new with this PR: json-magic and the undici it pins. - **fumadocs-openapi 12.6.5 loads json-magic 0.19.1 there**, and its magic proxy follows a reference and a circular one. - **`portal generate` builds three portals:** the layout reproduction, the OAuth one, and a specification with nested, shared and circular `$ref`s across schemas, parameters, a request body and responses. - **The output is the same as this repository's install gives** (Node 24, json-magic 0.16.1). For two of those projects I compared every page's visible text and the data it is rendered from, the Markdown copies, the llms files and the search documents: 16 pages and 16 other files, none differ. - **`portal serve` works:** an operation page renders with its nested fields, the playground and the cURL sample, and saving the specification updates the page within two seconds. Not covered: Node 22.15 to 22.18 one by one, and macOS or Linux on 22.14 with json-magic 0.19. One thing this turned up that is not from this PR: an npm install resolves `zbsearch` 4.0.4 where the lockfile, on `dev` too, has 4.0.2, and the two write the search index differently inside. Its documents are the same. ## Pictures Five levels deep, 1142 px wide: the crumbs truncate and Unset is in reach.  A long inline code in a parameter's description, inside its card:  A long token in a security scheme's description, inside the popover:  ## Not in this PR - **Session replay markers on the playground dialog.** Fumadocs sets none yet, so the template still marks the dialog itself. ## After this merges - **#477 will conflict with it in two places.** That PR passes the listed scripts to `insertTags()` and edits `Analytics.loadTags()`, which this one removes. Whichever merges second resolves them: `insertTags()` keeps its new argument and the callback check, and `loadTags()` stays removed. - **apimatic/apimatic-io#2352 and the docs draft describe the old sign-in.** They say the tags wait on the page a sign-in returns to, and that a page opened with `?state=…` loads no tag. Both lines change with this PR. Part of apimatic/apimatic-io#2350 (points 3 to 6). 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Muhammad Sohail <sohail.shahbaz@apimatic.io> Co-authored-by: Claude Fable 5.2 <noreply@anthropic.com>
dev took fumadocs-openapi 12.6.5 (#478), where a sign-in's answer reaches the playground through the tab's session storage and no page's address but the OAuth callback's holds it. insertTags() there holds the Google tags back on the callback only, and Analytics.loadTags() is gone. Listed scripts follow the same rule here: none on the callback, and all on the next page view. They used to wait wherever the address held an answer, which no page a reader returns to does any more. The test that held them back at such an address now holds them back on the callback, and a second one loads them at once on a page whose own link carries a state parameter. Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
The feed called a callback as a method of the record it keeps for that subscriber, so a callback written without strict mode got the record as `this`. Writing to it could reset the count delivery runs on, which handed the same event over without end, and a callback that expected the window there kept its state in the record instead. A callback is now called on its own, as any function is. Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
The feed sat at window.portalEventFeed, beside the mark of what the page started with. Both showed among the window's own names, and the feed there offered publish() to any script that came across it. The window now holds both under one key, a symbol, so it gains no name but apimatic and the data layer. A script that looks for the feed can still reach it, as it can anything on the page. Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
insertTags() took the head as its record of what it had inserted. A vendor's loader that removes its own element once it has run was inserted again on the next page view, so it ran twice on the first page and once more for every page after. The page now remembers each address it inserted, for a second instance under portal serve too, and no page view reads the head. Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
The start runs while the bundle loads, and it assigned to window.apimatic. Where a host had locked that name the assignment threw, the bundle stopped, and the page never came to life: no search, no theme switch, no listed script and no tag. The portal now starts all the same and shows the error in the console a moment later. Scripts on such a page get no subscribe(). Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
The parser took https:///cdn.example.com/widget.js and wrote the address without the extra slash, while the schema marked it wrong in an editor. httpsAddress() now holds an address to the schema's pattern, for pluginUrl as for a script, and parses it once. Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Script.staticFile() answered null for an address, which its caller had to filter out. It is staticFiles() now and answers a list, empty for an address. Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
A script that names no category counts as analytics, so the flag leaves it out, but the flag's help and the README named only the analytics and marketing scripts. Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
deliveredCount and an Unsubscribe type replace the comments on the feed's count and on what subscribe() returns, and a two-line comment in the schema test is one line. Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Merged
The description of portal.scripts still said they load once the address holds no OAuth answer. Since the merge with dev they load on every page but the OAuth callback. Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
A build made with --no-analytics left out the tags and the analytics and marketing scripts, and still handed every event, a reader's search terms among them, to the necessary and functional scripts it kept. The identity file now says whether the event feed is on, and it is off for such a build. subscribe() stays in place there and is handed nothing, so a kept script that calls it does not throw. The data layer gets its entries as before. The flag's help says what changed. AnalyticsConfig.withoutVendors() is withoutAnalytics() now that it turns off more than the vendors. Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
A consent tool listed in portal.scripts could lose a race with the
built-in Google tags: when it arrived after Google's library, cookies
were set and the page view was sent before it had said "denied".
portal.analytics.googleConsentMode, { "default": "denied" }, makes the
portal queue Google's consent defaults itself, before it sets either
tag up: the four Consent Mode v2 types denied, and a wait of 500 ms for
a consent tool to hand over a returning reader's answer. Both tags load
as before, and set no cookie until something on the page calls
gtag('consent', 'update'). A build made with --no-analytics queues
nothing.
Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
An editor pointed at the schema now offers googleConsentMode, with default required and "denied" its one value. The schema test holds the schema and the parser to the same verdict on each case. Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
The default build now sets googleConsentMode. A browser script has to hold the setting and the defaults it queues, and no prerendered page may hold them. Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
|
This branch has not been deployed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.



PR 2 of apimatic/apimatic-io#2348:
portal.scriptsandwindow.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-analyticsthat hands no event to the scripts it keeps.Ready for review. What is still to do before it merges is under "Before merging": the docs draft, the portal tests on this branch, and the decisions to record in the issues.
What a customer can now write
srcis anhttpsaddress or a file undersrc/static/. A file is checked on disk like a logo.categoryisnecessary,functional,analyticsormarketing, andanalyticswhen left out.--no-analyticsonportal generateandportal serveleaves out theanalyticsandmarketingscripts, and those with no category, along with the two Google tags. The scripts it keeps are handed no event:subscribe()is there and stays silent.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.googleConsentModemakes 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 callsgtag('consent', 'update', …). Without the setting nothing changes.What is on the branch
One commit per step of the plan, then the fixes from two reviews, the merge with
dev, and the two follow-ups to the second review.19cb032ascriptsentries with anhttpsaddress: parsed, written toportal.identity.json, inserted by the loader withasync = false. The key a start runs once by covers the list, so a config save underportal servereloads with the new one. An inserted tag is found by itssrcattribute, since a selector built from a customer's address misses on a backslash (replaced in78505ad0).2580c4easrc/static/assrc: checked on disk with the brand's files, written as its portal path, inserted under the base path.bf320b46category, and--no-analyticsdropping the two categories.PortalConfig.withoutVendors()becomeswithoutAnalytics(). The flag's help and the README say what it leaves out.7849475bEventFeedandwindow.apimatic.analytics, put in place at the start, before any tag or script is inserted, on every portal. What scripts are given there changed in5f220732.cea1bc0cscriptsinapimatic.schema.json, with onehttpsAddressdefinition thatpluginUrlnow shares.6782e26ca0c6d999window, which the whole-tree lint that runs after the tests refused, and CI failed on it.5f220732{ subscribe }atwindow.apimatic.analytics, bound and put in place whatever was there; the feed is held atwindow.portalEventFeed(moved inddbad82a). From the review of 2026-11-16 below.88fe45dc,8d117512insertTags()reads<head>once per call (not at all since78505ad0).6ed31b30publish()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.310f38abdev, which took fumadocs-openapi 12.6.5 in #478. A sign-in's answer now reaches the playground through the tab's session storage, anddevholds 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.d9058be4this, 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.ddbad82awindow.portalEventFeedis gone, and so iswindow.portalAnalyticsStarted, which #473 set. A script that looks for the symbol can still reach the feed, as it can anything on the page.78505ad0insertTags()no longer reads<head>.97946a28window.apimaticread-only no longer stops the bundle. The portal starts, and the error shows in the console a moment later.bc7ec368httpsAddress()refuses an address with no host before its path (https:///…), as the schema's pattern does, and parses it once.pluginUrlgoes through the same function.e50ac0acScript.staticFiles()answers a list, empty for an address, in place ofstaticFile()and itsnull.5f1d49d907ee1f45deliveredCountand anUnsubscribetype replace two comments in the feed that restated the code, and a two-line comment in the schema test is one line.3df7c3ddscriptssays they stay off the OAuth callback page. It still described the hold that the merge withdevremoved.17ddf35f--no-analyticshands no event to the scripts it keeps.portal.identity.jsongainsanalytics.eventFeed, which is"off"for such a build.subscribe()stays in place and silent, and the data layer gets its entries as before.AnalyticsConfig.withoutVendors()becomeswithoutAnalytics(), and the flag's help says what it does. Finding 7 of the review of 2026-11-17.1547e424portal.analytics.googleConsentMode: the portal queues Google's consent defaults ahead of both vendors' setups, and a--no-analyticsbuild queues none. Finding 2 of the same review.440f0b28apimatic.schema.json, with the schema test holding it to the parser's verdict.94c58970Decisions 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 last four, which answer the review of 2026-11-17 and are written up here only. The issues themselves are not edited yet.
attributes. An entry is{ src, category }. A file instatic/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.categoryis not written to the identity file. Nothing in the browser reads it in this release.src, not three. What is neither anhttpsaddress nor a file instatic/gets one report naming both choices.subscribe()returns, not inside it, soconst stop = subscribe(…)can callstop()on the first event.toJSON()does not writescripts, as it writes neitheranalyticsnorseo.--no-analyticsin the build test.portal-project-service.test.tsproves the identity file, as for feat(portal): load Google Tag Manager and GA4 from portal.analytics #473.leave out the tags set in 'portal.analytics' and each script in 'portal.scripts' whose category is 'analytics', 'marketing' or not set, and hand no event to the scripts that stay."The Google Tag Manager and Google Analytics tags" became "the tags",5f1d49d9added the scripts with no category, and17ddf35fthe events.--no-analyticsbuild 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. The data layer still gets its entries: no vendor reads them there, and a preview's console can still show what would be reported.necessaryscripts 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.googleConsentModeis 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 giveswindow.apimatic.consent.update, stays a later phase under a key of its own.--no-analyticsbuild queues nothing.Known limits
loadevent also does not fire in that time, so GTM's "Window Loaded" trigger waits with it. Underportal serveloadhad already fired. A script that fails outright (a host that does not resolve) holds nothing.--no-analytics.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_gacookies 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.googleConsentModeis 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).integrity. The key is refused as unknown.dev(fix(deps): take fumadocs-openapi 12.6.5, which keeps long paths and strings in their boxes #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,codeincluded. fix(deps): take fumadocs-openapi 12.6.5, which keeps long paths and strings in their boxes #478 accepted that window for the Google tags, which read the address and not the storage. For listed scripts it is a decision still to make. 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, asfumadocs-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.apimaticdoes not exist for a script the host injects into<head>itself, which runs before the portal's bundle. If such a script puts an object of its own atwindow.apimatic.analytics, the portal replaces it at its start, and callbacks queued on the old one are not carried over.window.apimaticread-only gets nosubscribe(). The portal starts and works, and the error shows in the console. A listed script that callswindow.apimatic.analytics.subscribe()fails there. Seen in a browser, for a read-only property and for one with a getter alone.https://:443/…,https://[::1/…andhttps://cdn.exa%mple.com/…. An editor shows no warning for them, andportal generatereports the address.Risk
Medium. Nothing here is released: #473 is on
devonly, and this PR builds on it.What changes for every portal, scripts listed or not:
<head>. This applies to the two Google tags too.window.portalAnalyticsStarted, is held under a symbol on the window with the feed.window.apimatic.analytics, and keeps each reported event in memory for the life of the page.portal.identity.jsongainsanalytics.googleConsentModeandanalytics.eventFeed. A portal that sets no consent mode queues nothing new, and its feed is on.pluginUrlis checked by the same rule from a shared function, and its pattern in the schema moved to a shared definition. ApluginUrlwith no host before its path (https:///…) is now refused; the CLI used to accept it and write it without the extra slash.A portal with no
scriptsloads 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 the default,
window.apimatic.analytics.subscribe(), the event it hands over, andgoogleConsentModewith its one value. Customers will write configs and scripts against them.What stands between this and a mistake:
6782e26c, whose five findings are fixed.6ed31b30. Its fourteen findings are answered under "Before merging".6ed31b30, which found no vulnerability.Where the cover is thin:
codeandstateand 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.subscribe()forwarder (at6ed31b30), 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 readsdata-attributes.--no-analytics. None has had a code or security review.googleConsentModeis 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").dev(310f38ab) changed when listed scripts load around a sign-in. That has unit tests, both end-to-end files and a browser run behind it, but no code or security review.No data or state to migrate. Nothing is stored, and
portal.identity.jsonis rewritten on every run.How to revert
dev, before a release: revert this PR's squash commit withgit revert. It is one commit, nothing depends on it yet, and there is nothing to migrate or clean up. The revert also takes--no-analyticsback to leaving out the two Google tags only, with its earlier help text and README lines, and takesscriptsandgoogleConsentModeout of the schema.googleConsentMode: a CLI without this change refuses both as unknown settings, soportal generateandportal servefail until the customer removes them.apimatic.json, rebuild and redeploy. Foranalyticsandmarketingscripts, building with--no-analyticsdoes the same.scriptsfromapimatic.jsonand rebuild. The portal then loads none, andwindow.apimatic.analyticsstays there unused.Before merging
devholds a--no-analyticsthat drops less than it will.6ed31b30, the last commit before the merge withdev: the whole suite and the lint, on Ubuntu, macOS and Windows with Node 22, 22.14, 24 and 26. On6782e26cthe tests passed (2,526 onubuntu-latest / Node 24) and the lint after them failed on the fixture script, whicha0c6d999fixes. The whole suite was not run locally.310f38ab, the merge withdev: all 16 checks.07ee1f45, after the second review's fixes: all 16 checks.94c58970, the head: all 16 checks.5f220732and the two refactors after it:window.apimatic.analyticswas the feed object itself, sopublish()and the event list were reachable from any script;subscribethrew 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.mdrules out; andinsertTags()read<head>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.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 atwindow.portalEventFeed(3); a page that had madewindow.apimaticread-only stopped the bundle (4); a callback got the feed's record of it asthis(5); the CLI accepted and rewrotehttps:///…, which the schema refuses (6, and the double parse of 11); the flag's help left out scripts with no category (9);staticFile()answerednull(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), bygoogleConsentModein1547e424; and--no-analyticshanded events to the scripts it kept (7), in17ddf35f. 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 ruleapi-markdown.tsxondevuses 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).portal.scriptssection, the new CLI row, and what the checks below measured. It is kept outside the PR, like feat(portal): load Google Tag Manager and GA4 from portal.analytics #473's. It also needs a consent section forgoogleConsentMode, and the flag's new wording.devand 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 on6ed31b30, and the build test on8d117512. After the merge withdev, on310f38ab:tscfor all three,eslint ., everytest/portal-templatefile 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 of07ee1f45:tscfor all three, everytest/portal-templateandtest/types/portalfile with the schema, flag,portal-source-context,portal-project-service,serveandquickstarttests (1,449 passing), and both end-to-end files (79 and 6 passing);eslint .on07ee1f45itself. After the two follow-ups, on the tree of94c58970:tscfor all three, those unit files withprepare-projectandportal-template.test.ts(1,491 passing), and both end-to-end files (80 and 6 passing);eslint .on94c58970itself.17ddf35fand1547e424each passed the type checks and those unit files on their own.tscfor the CLI, the tests and the template (the template's known errors from ungenerated files only).eslinton each step's CLI and test files, andprettieron every changed TypeScript file. Neither reads the schema, andeslintskips the template'slib/.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.eslint ., the whole tree, as CI runs it after the tests: clean on6ed31b30, on07ee1f45and on94c58970.APIMATIC_E2E=1withtest/e2e/portal-build.test.ts: 80 passing on94c58970, 79 before the consent mode's test.APIMATIC_E2E=1withtest/e2e/portal-serve.test.ts: 6 passing.Test plan, in a browser (run on Windows: headless Chrome, and one run in Firefox and in WebKit)
Against
portal serveand againstportal generateoutput served statically, with GTM and GA4 set. Listed addresses pointed at a localhttpshost, so order, delay, failure and silence were exact.<head>after the vendor tags,asyncfalse, 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.\in its query included./js/…, and from/docs/js/…with a path inportal.site.url, on a preview and on a built portal.portal generatefails namingportal.scripts[1].src, and names the spelling on disk when only the case differs. A config save underservethat names one is refused and the page keeps what it had.necessary). Without the flag all six run, on a preview and a built portal. With--no-analytics, on both: only thenecessaryandfunctionalones 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.serve. Adding a script reloads the page with it. Editing the description reloads nothing. Under--no-analytics, adding ananalyticsscript changes nothing and adding anecessaryone reloads with it.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.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 typedcodeandstate, and the starting page put in session storage, not a provider's round trip.stateof the customer's own (?state=CA, and?code=…&state=…in a page's own link; on310f38ab): the tag and every listed script load at once, and the page view is reported without them.MutationObserversaw the playground dialog already carrying every marker.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.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.portal, andwindow.apimatic.analyticshassubscribealone, frozen. A callback written without strict mode that pushes tothis.vendorQueuefilledwindow.vendorQueue.94c58970; every hit was answered in the browser, so none reached Google). WithgoogleConsentModeand 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_gacookies and sent the page view with no consent state.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.--no-analyticsand the event feed (preview and built files). A keptfunctionalscript 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 nowindow.gtagand no Google tag. Without the flag the same script got all three.94c58970). With neither host inscript-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.portal.scriptsbeside GA4 built in withgoogleConsentMode, and wired to Consent Mode as its guide shows; a preview at94c58970). 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_gacookies 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.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 therr-blockmarker alone; the markers for Hotjar, Clarity, FullStory, LogRocket, PostHog and Amplitude were not tried against those tools.94c58970). In both: the listed scripts sit in<head>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;subscribealone, frozen; the theme switch and in-app links work, with no error.🤖 Generated with Claude Code