From f7fe7dff961795bc662f6066caaa04f48d69dbc4 Mon Sep 17 00:00:00 2001 From: Muhammad Sohail <62895181+sohail2721@users.noreply.github.com> Date: Thu, 12 Nov 2026 16:24:14 +0500 Subject: [PATCH 1/5] feat(portal): fumadocs-openapi 12.6 with PKCE for playground sign-ins (#472) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## What changes for portal owners `fumadocs-openapi` 12.1.1 → 12.6.0, with `fumadocs-core` and `fumadocs-ui` 16.17.1 → 16.18.0 (12.6 requires 16.17.11 or later; the two must match). - **Playground OAuth sign-ins use PKCE** (12.5.0): the authorization request carries a `code_challenge`, the token request a `code_verifier`, so an authorization code that leaks on its way back is useless on its own. - **The token stays in the tab** (12.5.0): the playground keeps auth values in `sessionStorage` instead of `localStorage`; only the client ID is remembered across visits. - **The callback page sends no referrer**: `/oauth/callback` carries ``, the policy Fumadocs' own `createOAuthHandler()` sets since 12.5.7. Without it the endpoint page's `document.referrer` held the callback address with the provider's code for the whole visit, and any analytics tag sent it as the page referrer. - **The playground opens from a "Try in Playground" button** and the example request and response are cards with selects (12.5.0); code blocks in operation descriptions are highlighted (12.5.5). ## What changed in the template - `oauth-callback.ts`, `oauth.callback.tsx`: 12.5.7 moved the page the playground returns to from a cookie to `sessionStorage['fumadocs-openapi-oauth']` (a fix for redirects other subdomains could control), so the callback takes it from there with `takeStartingPage()`, which reads the note and forgets it in one place. The outcomes, the same-origin check and the error page are unchanged; the "no authorization was started" page says "in this tab", since the note is per tab now. - `openapi-section.server.ts`: `DistributiveOmit` is no longer exported; spelled out locally. Fumadocs now writes one page for an operation that lists the same tag twice, so the refusal for that case is gone (the case-and-spacing one stays, and names a repeated tag once). - `.ai/instructions.md`: the documented `--ignore-minimum-release-age` flag does not exist in pnpm 11; `--config.minimumReleaseAge=0` is what works. Not needed for this PR any more: every version here is past the 7-day `minimumReleaseAge`, and the lockfile resolves without a flag. - `pnpm-workspace.yaml`: 12.5.6 moved fumadocs-openapi to chokidar 6 (engines `>= 22.22`) and undici 8 (`>= 22.19`), which fails the `--engine-strict` install on the CLI's Node 22.14 floor. The CLI never loads either: chokidar serves `generateFiles()` in watch mode and undici the server proxy, and the portal uses `staticSource()` and no proxy. So they are overridden to chokidar 5, which 12.5.0 shipped with, and to undici 7.30.1, the patched release that `@scalar/json-magic` 0.16 pins as well (its own `>undici` override is gone, since that older pin no longer exists). The alternative is raising the floor to Node 22.22, a breaking change; not taken here. **These overrides reach CI alone:** `npm install -g @apimatic/cli` ignores `pnpm-workspace.yaml`, prints an `EBADENGINE` warning for chokidar 6 and undici 8 on Node 22.14, and installs all the same; neither loads. - `package.json`: `lucide-react` 1.69.0 and `shiki` 4.6.0, the versions fumadocs 16.18 resolves to, and `pnpm dedupe`, so each has one copy (as does `@base-ui/react`), in the lockfile and in a fresh `npm install` tree alike. The petstore test build's home page loads 435 KB gzipped on a first visit (its HTML and every stylesheet and script it links), against 438 KB with the copies and 441 KB on dev. - `.github/workflows/portal_tests.yml`: a `tests_ref` input for `workflow_dispatch`, so a branch of `apimatic/v4-test-automation` can be run against a CLI branch before either lands. A push to dev still runs the suite's main. ## Tests - `oauth-callback.test.ts` runs the playground's own `requestOAuthToken` from `fumadocs-openapi/playground` in a stand-in tab, takes the note it wrote with `takeStartingPage()`, and hands it to `oauthCallback`: a move of the key upstream fails here, not in a portal. The refusal test adds a page path that does not read as an address. - `openapi-section.test.ts`: the duplicate-tag case now expects one page; `['pets', 'pets', 'Pets']` reads "lists the tags 'pets' and 'Pets'". - `navigation.test.ts`: a `null` `nav.json` no longer reaches the transformer, Fumadocs' loader reads a metadata file's data itself. - `request-examples.test.ts`: `OperationParameters.items` now requires `name`. - `portal-build.test.ts` (e2e): the callback page's referrer meta is asserted; the stylesheet budget is 128 KB (Fumadocs' new components took it from 93 KB to 119 KB, a `node_modules` scan would still blow past it); the description's code block is read as text, since it is highlighted now. Verified with `pnpm test` (type check, unit suite, lint) and `APIMATIC_E2E=1` on the e2e suite, and with a live sign-in: a portal built from a calculator spec with an `authorizationCode` scheme, driven in headless Chrome against a local fake provider. The authorize request carried `code_challenge_method=S256`, the token request `code_verifier` and the client secret in a Basic auth header, the callback sent the browser back through the session-storage note, the endpoint page's referrer was empty and a GA4 hit after the sign-in had `dr=null`. A `--frozen-lockfile --engine-strict` install passes on Node 22.14. **Portal automation tests:** the suite in `apimatic/v4-test-automation` drove the old inline playground; its update is apimatic/v4-test-automation#26 (WasifIsrar's 12.5 rework, #13, carried onto main with baselines from this build). Run on this branch with that suite: https://github.com/apimatic/apimatic-cli/actions/runs/43196475277. The two merge together; whichever lands first leaves dev's run red until the other does. Supersedes #441. ## Not in this PR - 12.6.1 (2026-11-11): `finishOAuthFlow()` rejecting with a provider's error, and `createOAuthHandler({ inline: true })`, a prerenderable redirect route. The template runs neither: its callback page shows the provider's error itself and never forwards it, and keeps its own page, which also explains a visit without a flow. It still reads Fumadocs' internal storage key, which the test above pins. Can come with a later bump once it is seven days old. - `openapiPlugin()` of `fumadocs-openapi/server` is deprecated in 12.6 in favour of `createOpenAPI().loaderPlugin()`. It still works; a follow-up. - The provider's answer is still forwarded in the endpoint page's address for the moment before the playground removes it (about 300 ms locally). That is Fumadocs' hand-off and the subject of fuma-nama/fumadocs#3809, closed without a change; the maintainer considers the sessionStorage verifier enough for the code flow, and the implicit flow's bearer token, which the same hand-off forwards, is raised there. 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Muhammad Sohail Co-authored-by: Claude Fable 5.1 --- .ai/instructions.md | 2 +- .github/workflows/portal_tests.yml | 10 + package.json | 10 +- pnpm-lock.yaml | 723 +++++++++--------- pnpm-workspace.yaml | 9 +- .../src/components/authorization-failure.tsx | 2 +- portal-template/src/lib/oauth-callback.ts | 32 +- .../src/lib/openapi-section.server.ts | 20 +- portal-template/src/routes/oauth.callback.tsx | 26 +- test/e2e/portal-build.test.ts | 13 +- .../authorization-failure.test.ts | 4 +- test/portal-template/navigation.test.ts | 5 +- test/portal-template/oauth-callback.test.ts | 117 ++- test/portal-template/openapi-section.test.ts | 26 +- test/portal-template/request-examples.test.ts | 5 +- 15 files changed, 562 insertions(+), 442 deletions(-) diff --git a/.ai/instructions.md b/.ai/instructions.md index 25dfe9734..5239d30df 100644 --- a/.ai/instructions.md +++ b/.ai/instructions.md @@ -38,7 +38,7 @@ pnpm apimatic -i # -i: for commands `pnpm-workspace.yaml` sets `minimumReleaseAge: 10080` (7 days) as a supply-chain defense. Brand-new package versions are blocked from install until they've been on the registry for at least a week. `@apimatic/*` is exempt via `minimumReleaseAgeExclude`. -If you hit `ERR_PNPM_PACKAGE_RECENTLY_PUBLISHED` adding a fresh release, either wait it out or run a one-off install with `pnpm install --ignore-minimum-release-age` (CI uses `--frozen-lockfile`, which bypasses the check entirely, so this only blocks manual `pnpm add` / `pnpm update`). +If you hit `ERR_PNPM_PACKAGE_RECENTLY_PUBLISHED` adding a fresh release, either wait it out or run a one-off install with `pnpm install --config.minimumReleaseAge=0` (pnpm 11 has no `--ignore-minimum-release-age` flag; CI uses `--frozen-lockfile`, which bypasses the check entirely, so this only blocks manual `pnpm add` / `pnpm update`). ## TypeScript toolchain — two compilers, on purpose diff --git a/.github/workflows/portal_tests.yml b/.github/workflows/portal_tests.yml index b3b9bd85c..7792d5e26 100644 --- a/.github/workflows/portal_tests.yml +++ b/.github/workflows/portal_tests.yml @@ -4,7 +4,16 @@ on: push: branches: [dev] + # A branch of the test suite can be named when a CLI change moves what the + # suite checks, so the two can be run together before either lands. A push + # to dev always runs the suite's main. workflow_dispatch: + inputs: + tests_ref: + description: Branch, tag or SHA of apimatic/v4-test-automation to run + required: false + default: main + type: string concurrency: group: ${{ github.workflow }}-${{ github.ref }} @@ -82,6 +91,7 @@ jobs: uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0 with: repository: apimatic/v4-test-automation + ref: ${{ inputs.tests_ref || 'main' }} path: tests - name: install test dependencies diff --git a/package.json b/package.json index 142c9083f..f139b7868 100644 --- a/package.json +++ b/package.json @@ -77,13 +77,13 @@ "fast-levenshtein": "^3.0.0", "form-data": "^4.0.2", "fs-extra": "^11.3.0", - "fumadocs-core": "16.17.1", + "fumadocs-core": "16.18.0", "fumadocs-mdx": "15.4.7", - "fumadocs-openapi": "12.1.1", - "fumadocs-ui": "16.17.1", + "fumadocs-openapi": "12.6.0", + "fumadocs-ui": "16.18.0", "get-port": "^7.1.0", "is-in-ci": "^2.0.0", - "lucide-react": "1.54.0", + "lucide-react": "1.69.0", "mustache": "^4.2.0", "neverthrow": "^8.2.0", "open": "^8.4.0", @@ -95,7 +95,7 @@ "remark": "15.0.1", "remark-mdx": "3.1.1", "semver": "^7.8.0", - "shiki": "4.5.0", + "shiki": "4.6.0", "striptags": "^3.2.0", "tailwindcss": "4.3.3", "tmp-promise": "^3.0.3", diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index ca50f53ac..3cdaea16a 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -16,7 +16,8 @@ overrides: '@oclif/core': 4.11.0 oclif: 4.17.34 browserslist: 4.24.4 - '@scalar/json-magic>undici': 7.29.1 + fumadocs-openapi>chokidar: ^5.0.0 + fumadocs-openapi>undici: 7.30.1 '@types/node': 22.14.1 importers: @@ -40,7 +41,7 @@ importers: version: 5.3.0 '@fumadocs/api-docs': specifier: 0.2.8 - version: 0.2.8(@types/react@19.3.0)(fumadocs-core@16.17.1(@mdx-js/mdx@3.1.1)(@tanstack/react-router@1.170.33(react-dom@19.2.8(react@19.2.8))(react@19.2.8))(@types/estree-jsx@1.0.5)(@types/hast@3.0.5)(@types/mdast@4.0.4)(@types/react@19.3.0)(lucide-react@1.54.0(@types/react@19.3.0)(react@19.2.8))(react-dom@19.2.8(react@19.2.8))(react@19.2.8)(zod@4.6.5))(fumadocs-ui@16.17.1(@types/mdx@2.0.14)(@types/react-dom@19.3.0(@types/react@19.3.0))(@types/react@19.3.0)(fumadocs-core@16.17.1(@mdx-js/mdx@3.1.1)(@tanstack/react-router@1.170.33(react-dom@19.2.8(react@19.2.8))(react@19.2.8))(@types/estree-jsx@1.0.5)(@types/hast@3.0.5)(@types/mdast@4.0.4)(@types/react@19.3.0)(lucide-react@1.54.0(@types/react@19.3.0)(react@19.2.8))(react-dom@19.2.8(react@19.2.8))(react@19.2.8)(zod@4.6.5))(react-dom@19.2.8(react@19.2.8))(react@19.2.8)(tailwindcss@4.3.3))(react-dom@19.2.8(react@19.2.8))(react@19.2.8) + version: 0.2.8(@types/react@19.3.0)(fumadocs-core@16.18.0(@mdx-js/mdx@3.1.1)(@tanstack/react-router@1.170.33(react-dom@19.2.8(react@19.2.8))(react@19.2.8))(@types/estree-jsx@1.0.5)(@types/hast@3.0.5)(@types/mdast@4.0.4)(@types/react@19.3.0)(lucide-react@1.69.0(@types/react@19.3.0)(react@19.2.8))(react-dom@19.2.8(react@19.2.8))(react@19.2.8)(zod@4.6.5))(fumadocs-ui@16.18.0(@types/mdx@2.0.14)(@types/react-dom@19.3.0(@types/react@19.3.0))(@types/react@19.3.0)(fumadocs-core@16.18.0(@mdx-js/mdx@3.1.1)(@tanstack/react-router@1.170.33(react-dom@19.2.8(react@19.2.8))(react@19.2.8))(@types/estree-jsx@1.0.5)(@types/hast@3.0.5)(@types/mdast@4.0.4)(@types/react@19.3.0)(lucide-react@1.69.0(@types/react@19.3.0)(react@19.2.8))(react-dom@19.2.8(react@19.2.8))(react@19.2.8)(zod@4.6.5))(react-dom@19.2.8(react@19.2.8))(react@19.2.8)(tailwindcss@4.3.3))(react-dom@19.2.8(react@19.2.8))(react@19.2.8) '@oclif/core': specifier: 4.11.0 version: 4.11.0 @@ -93,17 +94,17 @@ importers: specifier: ^11.3.0 version: 11.3.5 fumadocs-core: - specifier: 16.17.1 - version: 16.17.1(@mdx-js/mdx@3.1.1)(@tanstack/react-router@1.170.33(react-dom@19.2.8(react@19.2.8))(react@19.2.8))(@types/estree-jsx@1.0.5)(@types/hast@3.0.5)(@types/mdast@4.0.4)(@types/react@19.3.0)(lucide-react@1.54.0(@types/react@19.3.0)(react@19.2.8))(react-dom@19.2.8(react@19.2.8))(react@19.2.8)(zod@4.6.5) + specifier: 16.18.0 + version: 16.18.0(@mdx-js/mdx@3.1.1)(@tanstack/react-router@1.170.33(react-dom@19.2.8(react@19.2.8))(react@19.2.8))(@types/estree-jsx@1.0.5)(@types/hast@3.0.5)(@types/mdast@4.0.4)(@types/react@19.3.0)(lucide-react@1.69.0(@types/react@19.3.0)(react@19.2.8))(react-dom@19.2.8(react@19.2.8))(react@19.2.8)(zod@4.6.5) fumadocs-mdx: specifier: 15.4.7 - version: 15.4.7(@types/mdast@4.0.4)(@types/mdx@2.0.14)(@types/react@19.3.0)(fumadocs-core@16.17.1(@mdx-js/mdx@3.1.1)(@tanstack/react-router@1.170.33(react-dom@19.2.8(react@19.2.8))(react@19.2.8))(@types/estree-jsx@1.0.5)(@types/hast@3.0.5)(@types/mdast@4.0.4)(@types/react@19.3.0)(lucide-react@1.54.0(@types/react@19.3.0)(react@19.2.8))(react-dom@19.2.8(react@19.2.8))(react@19.2.8)(zod@4.6.5))(react@19.2.8)(rolldown@1.2.8)(vite@8.2.2(@types/node@22.14.1)(esbuild@0.28.2)(jiti@2.7.0)(tsx@4.21.0)(yaml@2.9.1)) + version: 15.4.7(@types/mdast@4.0.4)(@types/mdx@2.0.14)(@types/react@19.3.0)(fumadocs-core@16.18.0(@mdx-js/mdx@3.1.1)(@tanstack/react-router@1.170.33(react-dom@19.2.8(react@19.2.8))(react@19.2.8))(@types/estree-jsx@1.0.5)(@types/hast@3.0.5)(@types/mdast@4.0.4)(@types/react@19.3.0)(lucide-react@1.69.0(@types/react@19.3.0)(react@19.2.8))(react-dom@19.2.8(react@19.2.8))(react@19.2.8)(zod@4.6.5))(react@19.2.8)(rolldown@1.2.8)(vite@8.2.2(@types/node@22.14.1)(esbuild@0.28.2)(jiti@2.7.0)(tsx@4.21.0)(yaml@2.9.1)) fumadocs-openapi: - specifier: 12.1.1 - version: 12.1.1(@types/react@19.3.0)(fumadocs-core@16.17.1(@mdx-js/mdx@3.1.1)(@tanstack/react-router@1.170.33(react-dom@19.2.8(react@19.2.8))(react@19.2.8))(@types/estree-jsx@1.0.5)(@types/hast@3.0.5)(@types/mdast@4.0.4)(@types/react@19.3.0)(lucide-react@1.54.0(@types/react@19.3.0)(react@19.2.8))(react-dom@19.2.8(react@19.2.8))(react@19.2.8)(zod@4.6.5))(fumadocs-ui@16.17.1(@types/mdx@2.0.14)(@types/react-dom@19.3.0(@types/react@19.3.0))(@types/react@19.3.0)(fumadocs-core@16.17.1(@mdx-js/mdx@3.1.1)(@tanstack/react-router@1.170.33(react-dom@19.2.8(react@19.2.8))(react@19.2.8))(@types/estree-jsx@1.0.5)(@types/hast@3.0.5)(@types/mdast@4.0.4)(@types/react@19.3.0)(lucide-react@1.54.0(@types/react@19.3.0)(react@19.2.8))(react-dom@19.2.8(react@19.2.8))(react@19.2.8)(zod@4.6.5))(react-dom@19.2.8(react@19.2.8))(react@19.2.8)(tailwindcss@4.3.3))(react-dom@19.2.8(react@19.2.8))(react@19.2.8) + specifier: 12.6.0 + version: 12.6.0(@types/react@19.3.0)(fumadocs-core@16.18.0(@mdx-js/mdx@3.1.1)(@tanstack/react-router@1.170.33(react-dom@19.2.8(react@19.2.8))(react@19.2.8))(@types/estree-jsx@1.0.5)(@types/hast@3.0.5)(@types/mdast@4.0.4)(@types/react@19.3.0)(lucide-react@1.69.0(@types/react@19.3.0)(react@19.2.8))(react-dom@19.2.8(react@19.2.8))(react@19.2.8)(zod@4.6.5))(fumadocs-ui@16.18.0(@types/mdx@2.0.14)(@types/react-dom@19.3.0(@types/react@19.3.0))(@types/react@19.3.0)(fumadocs-core@16.18.0(@mdx-js/mdx@3.1.1)(@tanstack/react-router@1.170.33(react-dom@19.2.8(react@19.2.8))(react@19.2.8))(@types/estree-jsx@1.0.5)(@types/hast@3.0.5)(@types/mdast@4.0.4)(@types/react@19.3.0)(lucide-react@1.69.0(@types/react@19.3.0)(react@19.2.8))(react-dom@19.2.8(react@19.2.8))(react@19.2.8)(zod@4.6.5))(react-dom@19.2.8(react@19.2.8))(react@19.2.8)(tailwindcss@4.3.3))(react-dom@19.2.8(react@19.2.8))(react@19.2.8) fumadocs-ui: - specifier: 16.17.1 - version: 16.17.1(@types/mdx@2.0.14)(@types/react-dom@19.3.0(@types/react@19.3.0))(@types/react@19.3.0)(fumadocs-core@16.17.1(@mdx-js/mdx@3.1.1)(@tanstack/react-router@1.170.33(react-dom@19.2.8(react@19.2.8))(react@19.2.8))(@types/estree-jsx@1.0.5)(@types/hast@3.0.5)(@types/mdast@4.0.4)(@types/react@19.3.0)(lucide-react@1.54.0(@types/react@19.3.0)(react@19.2.8))(react-dom@19.2.8(react@19.2.8))(react@19.2.8)(zod@4.6.5))(react-dom@19.2.8(react@19.2.8))(react@19.2.8)(tailwindcss@4.3.3) + specifier: 16.18.0 + version: 16.18.0(@types/mdx@2.0.14)(@types/react-dom@19.3.0(@types/react@19.3.0))(@types/react@19.3.0)(fumadocs-core@16.18.0(@mdx-js/mdx@3.1.1)(@tanstack/react-router@1.170.33(react-dom@19.2.8(react@19.2.8))(react@19.2.8))(@types/estree-jsx@1.0.5)(@types/hast@3.0.5)(@types/mdast@4.0.4)(@types/react@19.3.0)(lucide-react@1.69.0(@types/react@19.3.0)(react@19.2.8))(react-dom@19.2.8(react@19.2.8))(react@19.2.8)(zod@4.6.5))(react-dom@19.2.8(react@19.2.8))(react@19.2.8)(tailwindcss@4.3.3) get-port: specifier: ^7.1.0 version: 7.2.0 @@ -111,8 +112,8 @@ importers: specifier: ^2.0.0 version: 2.0.0 lucide-react: - specifier: 1.54.0 - version: 1.54.0(@types/react@19.3.0)(react@19.2.8) + specifier: 1.69.0 + version: 1.69.0(@types/react@19.3.0)(react@19.2.8) mustache: specifier: ^4.2.0 version: 4.2.0 @@ -147,8 +148,8 @@ importers: specifier: ^7.7.0 version: 7.8.0 shiki: - specifier: 4.5.0 - version: 4.5.0 + specifier: 4.6.0 + version: 4.6.0 striptags: specifier: ^3.2.0 version: 3.2.0 @@ -606,8 +607,8 @@ packages: resolution: {integrity: sha512-LwdZHpScM4Qz8Xw2iKSzS+cfglZzJGvofQICy7W7v4caru4EaAmyUuO6BGrbyQ2mYV11W0U8j5mBhd14dd3B0A==} engines: {node: '>=6.9.0'} - '@base-ui/react@1.8.0': - resolution: {integrity: sha512-P0/1sxo6SBVZOklKMIedvTWqw2s2IQzi9x5bIVsXu980cuSOD4NeuRSs+/L7LZQfDkZP/uRZyGPyfFl/B1oH+Q==} + '@base-ui/react@1.9.0': + resolution: {integrity: sha512-S8CSYosASBKtpL8SWUfS78rFElfLijiCgA7oHOK22jCJ95FULsYyKwBNFOgudt0RA+/7yNc7F81bOvQnRgbBiQ==} engines: {node: '>=14.0.0'} peerDependencies: '@date-fns/tz': ^1.2.0 @@ -623,8 +624,8 @@ packages: date-fns: optional: true - '@base-ui/utils@0.4.0': - resolution: {integrity: sha512-bO9fz25kKtPf+aZVyfQrC0PDmJdmVni31W2hCS5/Owb+inwdIL3XU26pCPRPlt4LSxZrBgLwubXQXQlKaFEZzw==} + '@base-ui/utils@0.5.0': + resolution: {integrity: sha512-dYGGcEttjkYiMoa5nHm8vLaJ2UcuTWxo3BFAwOYXeRg/q7UVVvA6cacEIXEs3FgBfK1CGtW1ptElqs7wsx+t9A==} peerDependencies: '@types/react': ^17 || ^18 || ^19 react: ^17 || ^18 || ^19 @@ -1120,8 +1121,8 @@ packages: json-schema-typed: optional: true - '@fumadocs/json-schema@0.2.0': - resolution: {integrity: sha512-I3sB2wwJr1Up5JSmaAThmQ2CSP4j2pM01igpbsuKDG3kHYuoHDXiKGEoFWmYK3a81VjQ98AOYx60SEs6xEXr7A==} + '@fumadocs/json-schema@0.3.5': + resolution: {integrity: sha512-BhFhYtVufkLY0cZfWuMFJm0Rq7oBaIDMzONrsHovhY6on7GiPiuTSuJv4ZlOgmyBaPL3HW+s1wkevjhvRUUlFg==} peerDependencies: json-schema-typed: '*' react: ^19.2.0 @@ -1131,8 +1132,8 @@ packages: react: optional: true - '@fumadocs/tailwind@0.1.3': - resolution: {integrity: sha512-gDgLbTnY5b+nogCg2y/pP7GsaQS4Zt/0vftJAu07Wy7Wsb3/lwd9GwoGqccCnPElTFwMG+pPwrmHXBPexEfE8A==} + '@fumadocs/tailwind@0.1.5': + resolution: {integrity: sha512-ohzmuLTfNNRvP6B/Xx31lWJ58xu40NcmI+6mc/jivYeOoofnmdxBKu5gCErTgOE/mUqyVv4GvYeqd9FhoLHphg==} peerDependencies: tailwindcss: ^4.0.0 peerDependenciesMeta: @@ -1160,8 +1161,8 @@ packages: '@types/react': optional: true - '@fumari/stf@1.1.1': - resolution: {integrity: sha512-W0ISkQFwwX438CYlBxAe3OdCdPRSlHWVNizB1q4ICzrQKR9AYhGZuvKYo+HukSpgaMCUt++cM7VEa4VtSA8rhg==} + '@fumari/stf@1.1.2': + resolution: {integrity: sha512-8PuvETmnMRJjof6BJLFNJBKq9at6Ar1oJWRkedSJ0K/GJ73QPHVSZqTkgXh3hb6uXkQhbbWkv+5WD0Fh50YUGA==} peerDependencies: '@types/react': '*' react: ^19.2.0 @@ -1505,11 +1506,11 @@ packages: '@radix-ui/number@1.1.3': resolution: {integrity: sha512-Road2bidD0uu/1BGDOWNdPI06g0lIRy6IF9GZcIrDK2KGItfor8IQwQa+yM2ERgHM1MmHxaxpTzk0/Jp42lNfA==} - '@radix-ui/primitive@1.1.7': - resolution: {integrity: sha512-rqWnm76nYT8HoNNqEjpgJ7Pw/DrBj5iBTrmEPo6HTX5+VJyBNOqTdv4g89G63HuR5g0AaENoAcH7Is5fF2kZ8Q==} + '@radix-ui/primitive@1.2.0': + resolution: {integrity: sha512-KABY+VMIRPJL+Vyzv/335FEhXXD/xDv8BMb1kl48/aXJZMH0LtHCTx5ga5RnxaEP3nZHtmTLf1P9vanmFX46bw==} - '@radix-ui/react-accordion@1.2.20': - resolution: {integrity: sha512-jDhG9FvAEnlhnjrsINbNXcUa4G+L1KqSkJSunkbKEzFRcAb52jvM0PjPxPRvhe1HNc5F5yc0yzzWeeqlH4yBIg==} + '@radix-ui/react-accordion@1.3.1': + resolution: {integrity: sha512-lCZ6sbGS/7WO0j84yx4srIgOf0MRJ/sZ13RonADXxvKBym8xrxNCq5f6DibGcr38sIlwPk8/52uYdXeOPsbEDw==} peerDependencies: '@types/react': '*' '@types/react-dom': '*' @@ -1521,8 +1522,8 @@ packages: '@types/react-dom': optional: true - '@radix-ui/react-arrow@1.1.15': - resolution: {integrity: sha512-v4zggRcjadnI+ClKDuijlQEW4tw3NoaeHc/PwpKnLoLLKNUG4InLegkstooLcRIUWCs+8L22dGURCVuFfOKfnA==} + '@radix-ui/react-arrow@1.1.17': + resolution: {integrity: sha512-67jjcVvxjXCCStnTW3Z+M7jmaFMuMR7M2JgpDzH4w7JSRrikmzhjfYgP/09ECb8n7whnsgh1ifJ+Ie96qEj+pQ==} peerDependencies: '@types/react': '*' '@types/react-dom': '*' @@ -1534,8 +1535,8 @@ packages: '@types/react-dom': optional: true - '@radix-ui/react-collapsible@1.1.20': - resolution: {integrity: sha512-mcGesGplBnzN2sbvJETzpCNfSMyPnb29q1GRLU+Ib7bJrpIG2ywmRoh2V5VbA2uNvKikKUlVbAPks7JDjz4A8Q==} + '@radix-ui/react-collapsible@1.2.1': + resolution: {integrity: sha512-fSzLb/qy1wuZSxQBcxpW0hNXYHDMWiIXDGyJGdA4+FSLknOWZsNRrTCUavxb4PI8b8lvHo/CysO6NVi5zLpo5g==} peerDependencies: '@types/react': '*' '@types/react-dom': '*' @@ -1547,8 +1548,8 @@ packages: '@types/react-dom': optional: true - '@radix-ui/react-collection@1.1.15': - resolution: {integrity: sha512-9W+B9NPF0NaaPh/1NJd3+KqsnlLqU9H7T2rvww+fp+T/evVXdNAyYcnfRQZFOjkR1ajQp3yORlqnI8soawLvNA==} + '@radix-ui/react-collection@1.2.0': + resolution: {integrity: sha512-+yiQzqcc7Sy7/5s0jrMCjpPRFB3538VNrXPWdTLZhE/SCfgEws4aI6lHWN/vvcnyhHndROWBzqmqB4QBrITZ9Q==} peerDependencies: '@types/react': '*' '@types/react-dom': '*' @@ -1569,8 +1570,8 @@ packages: '@types/react': optional: true - '@radix-ui/react-context@1.2.2': - resolution: {integrity: sha512-RHCUGwKHDr0hDGg4X7ma4JG4/+12qxw8rkh5QKdDldlCvtja6nUx1Ef/8HVrJze81lEsgLQlqjzjGNHantgnQA==} + '@radix-ui/react-context@1.3.0': + resolution: {integrity: sha512-v5AYEocMISkbJ+1fTXzZpiFv7NRr3D2WiYbLIKf+FkmJ8VkP6d503eV2n34MFussHXY1pcoq3yfJiQH77dc4Mg==} peerDependencies: '@types/react': '*' react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc @@ -1578,8 +1579,8 @@ packages: '@types/react': optional: true - '@radix-ui/react-dialog@1.1.23': - resolution: {integrity: sha512-Ksw4WeROkO4rC9k/onilX/Ao2Cr1ku1unMNH+XSCcP4jSXYu7HDsg9n4ojMjVb22XpYjAQ9qfrFlVbru1vXDUA==} + '@radix-ui/react-dialog@1.3.1': + resolution: {integrity: sha512-+0E4qvVTwjAWra9sEhJ+9BTsvHE00zkUuNw1VGh7S+Gc13dfYk+S1PVQdchWDj+XYHhAai7Z7IpzXVDCGsDplg==} peerDependencies: '@types/react': '*' '@types/react-dom': '*' @@ -1591,8 +1592,8 @@ packages: '@types/react-dom': optional: true - '@radix-ui/react-direction@1.1.4': - resolution: {integrity: sha512-5pzg4FGQNpExhnhT2zlrP1wZFaYCd1K0nYWoFAdcYoYK868IEigqMX3B3f8yIoRlAhAeDWciLI6ZdCKHF9P4Vg==} + '@radix-ui/react-direction@1.2.0': + resolution: {integrity: sha512-FtRA52a/r+LKStFT+neLUm+8vSe7wbzkbQGGeU8ixFiwC8NU14Evoq9ATECqL3eGbcUzJR4fyfA4KkK/q6dfqg==} peerDependencies: '@types/react': '*' react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc @@ -1600,8 +1601,8 @@ packages: '@types/react': optional: true - '@radix-ui/react-dismissable-layer@1.1.19': - resolution: {integrity: sha512-8g4pfOL9HoKKLWGiypT+dphVqjFfmcXO5GBnhsG6zI+lxAx/8feQpr+1LSN8Re3hiZ+XkLNS4O9ztK11/LzQ6w==} + '@radix-ui/react-dismissable-layer@1.2.1': + resolution: {integrity: sha512-KIfDcAsx+oVylFZ4xryVKusJUrLLhTQmfnJW4kwk4Km5myvhHCrj04hnWWUC166+xD4DHdH8tQGylwYX1h6+Pg==} peerDependencies: '@types/react': '*' '@types/react-dom': '*' @@ -1613,8 +1614,8 @@ packages: '@types/react-dom': optional: true - '@radix-ui/react-focus-guards@1.1.6': - resolution: {integrity: sha512-RNOJjfZMTyBM6xYmV3IVGXkPjIhcBAuv48POevAXwrGJhkWZ9p1rFoIS1JFooPuT193AZmRsCPhpoVJxx6OPoQ==} + '@radix-ui/react-focus-guards@1.2.0': + resolution: {integrity: sha512-MPm5R0iRGUDrDnPNxmLBkv+X7pN4XKzt+MbWJEuJQsH3NFH4omrbpXpucyYCCKTSt+na/ZxGhEWQrWTZ0285cA==} peerDependencies: '@types/react': '*' react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc @@ -1622,8 +1623,8 @@ packages: '@types/react': optional: true - '@radix-ui/react-focus-scope@1.1.16': - resolution: {integrity: sha512-wmRZ2WWLvmt6KHy2rNPOdPUjwq5xOHY02+m+udwJTn0aNIox/rkskAvJTyTLGhPK6KgrUjlJUJpgmx/+wFiFIQ==} + '@radix-ui/react-focus-scope@1.3.1': + resolution: {integrity: sha512-ugeMhbXt4y5S2T1GnIqbWDKEN962PDwnX1fN0eKOOgf5f63Dh2mn8F1FUySlgW0iF6GiVsRF32DzuDIWTUyQJg==} peerDependencies: '@types/react': '*' '@types/react-dom': '*' @@ -1644,8 +1645,8 @@ packages: '@types/react': optional: true - '@radix-ui/react-navigation-menu@1.2.22': - resolution: {integrity: sha512-ou7iLEJ+yrhQndkkA4U21XIdS/CS45F4iXIkTZcb6/Ne9EMsOuDudVmCwmDnfFZZ+y1FZqXRNSIgBy+YMvZVZg==} + '@radix-ui/react-navigation-menu@1.4.1': + resolution: {integrity: sha512-XPPZjkeyCSMNNvt0FyDv/PUauG7Ow4GwHQ/XZSwW36F/TS7rR4HFTsXH8ewLnXTOLn3x96/pmTPNQIVoTX/86g==} peerDependencies: '@types/react': '*' '@types/react-dom': '*' @@ -1657,8 +1658,8 @@ packages: '@types/react-dom': optional: true - '@radix-ui/react-popover@1.1.23': - resolution: {integrity: sha512-mw58MrBlyHWFisTOYignD0vf/3gdcgAR+9of1s9G/38CbFiUwH1nCDkc0AUM9IrXFgN5Ue8n45j9WCgyM1sbiQ==} + '@radix-ui/react-popover@1.3.1': + resolution: {integrity: sha512-ZNxvXRx5W2Wos4fXCXb5lpdqN0Z5chf+mStOUOTr4ik7d+62MRvoe9rzCA/eGNg36lxXqSrKEKmwuZEcUrIstw==} peerDependencies: '@types/react': '*' '@types/react-dom': '*' @@ -1670,8 +1671,8 @@ packages: '@types/react-dom': optional: true - '@radix-ui/react-popper@1.3.7': - resolution: {integrity: sha512-UsJrrd7w4wuKKTdvd/DNERVlwSlUcyXzjhyDwBk+3aPOsCjOY6ZSbxuw8E6lZTjjfP8Cpd0J8VVkrYUWyGYXyg==} + '@radix-ui/react-popper@1.4.0': + resolution: {integrity: sha512-yCWRvLeGv9Pz3+efwHqGPp70mZ56r3kfIgQVF56Oj2aAa4uP/Tb+IE59wNcc+758rctqbCKx4LbK8II/r7Bn0Q==} peerDependencies: '@types/react': '*' '@types/react-dom': '*' @@ -1683,8 +1684,8 @@ packages: '@types/react-dom': optional: true - '@radix-ui/react-portal@1.1.17': - resolution: {integrity: sha512-vKQLcWypUnwZVvfV7UkGahH2g6ySe8M8R+zYBwPrv5byZ9QAW6cQVvNKo7GgmD+p8aYb6D9JBuvy8/WhOno2wQ==} + '@radix-ui/react-portal@1.2.0': + resolution: {integrity: sha512-StX7xXnaRU41VvFtMm9zlhVGz8XF6GmWWTXftkQaY+tqVkbs/R9UmAp5mLzHHapk5hM9RMZQvO/3usyIP/g42g==} peerDependencies: '@types/react': '*' '@types/react-dom': '*' @@ -1696,8 +1697,8 @@ packages: '@types/react-dom': optional: true - '@radix-ui/react-presence@1.1.10': - resolution: {integrity: sha512-3wyzCQ6+ubRA+D4uv9m95JYLXxmOHp05qjrkjeA7uKHHtjpPggQzc6DAb0URl7j67oR0K2foO4ip27TiX037Bw==} + '@radix-ui/react-presence@1.1.11': + resolution: {integrity: sha512-Z7/atlkab36Z8hm+V8zYc79r0W+tiOB1o0tun1By94JyadkekLQmtEAnBSP9XKXBNQsStoStS4+gX10JpS5akA==} peerDependencies: '@types/react': '*' '@types/react-dom': '*' @@ -1709,8 +1710,8 @@ packages: '@types/react-dom': optional: true - '@radix-ui/react-primitive@2.1.10': - resolution: {integrity: sha512-MucOnzh6hR5mid6VpkbglRAMYMjKLqRnGBbjXkzjK52fuQDd1qbkx78a5P40mkcnVXJdEVxm26E9OPAiUq7nBg==} + '@radix-ui/react-primitive@2.2.0': + resolution: {integrity: sha512-HCTSPMNqv55Qk0IX4geJbpyXazmqulcimwuyjxTkKi29v+QZbG2Zho9BnbBq4YS2PF+KlNb2CXoLz66uUmblkg==} peerDependencies: '@types/react': '*' '@types/react-dom': '*' @@ -1722,8 +1723,8 @@ packages: '@types/react-dom': optional: true - '@radix-ui/react-roving-focus@1.1.19': - resolution: {integrity: sha512-V9jI6hDjT7l3jsCQD9bLNvDLM3tH/gdbOTp7Tefp3hbbgCGQoK7tUvrWiRlcoBHIZ809ElXwNQwVo0B98LuTXQ==} + '@radix-ui/react-roving-focus@1.2.1': + resolution: {integrity: sha512-UwraORzVUeEPMclhO1p0vz0qI+TbdDLO9i+FiOqhJyHKwdpCRCck9yVEscUnAMIzCiuNoQa8D4A9bIpOPXGt6Q==} peerDependencies: '@types/react': '*' '@types/react-dom': '*' @@ -1735,8 +1736,8 @@ packages: '@types/react-dom': optional: true - '@radix-ui/react-scroll-area@1.2.18': - resolution: {integrity: sha512-Zn5Cd171wxsO3Dfg8HaW6RifTb9CYTKQJHs/G4+LN1GfmJpaQMZQyQxMprVPHpaz7QY4l9BxK2JwQuzHsXC8nA==} + '@radix-ui/react-scroll-area@1.4.0': + resolution: {integrity: sha512-CFrLqHNejWq5FhKAcj9V/WPGRsol76HBQto81NdOBVFEOqIEkJkKIJt0Z824A/9hHLCtoiR/Kw3euRgzXP2pxg==} peerDependencies: '@types/react': '*' '@types/react-dom': '*' @@ -1748,8 +1749,8 @@ packages: '@types/react-dom': optional: true - '@radix-ui/react-slot@1.3.3': - resolution: {integrity: sha512-qx7oqnYbxnK9kYI9m317qmFmEgo6ywqWvbTogdj7cL9p3/yx4M48p7Rnw5z3H890cL/ow/EeWJsuTykeZVXP5Q==} + '@radix-ui/react-slot@1.5.0': + resolution: {integrity: sha512-tyYd9ddPXAysAbdbD9eYxgwpCSv6f3PncqVSNKQFSR5lcJVLz3cb/pANDoYrLiHBpXv7skortyUgGUWsYuPPFQ==} peerDependencies: '@types/react': '*' react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc @@ -1757,8 +1758,8 @@ packages: '@types/react': optional: true - '@radix-ui/react-tabs@1.1.21': - resolution: {integrity: sha512-UKxJlZid7FVtsk/WTxj4i4uSEgj2Au+KBbS7SQyTlzMhhn+86Cz3tISZdTa87bfEfcuvZezf2ZsxD4xuEKtkog==} + '@radix-ui/react-tabs@1.2.1': + resolution: {integrity: sha512-hRoJlode+hg5ZNlR+3tkfkUliIybdTpD5lkAvHQ9yaXseGf7XVO9Ib2GPEIOuaJJbo7YWYbNpDDRfo8Dhf6/xA==} peerDependencies: '@types/react': '*' '@types/react-dom': '*' @@ -1770,8 +1771,8 @@ packages: '@types/react-dom': optional: true - '@radix-ui/react-use-callback-ref@1.1.4': - resolution: {integrity: sha512-R6OUY2e2fA6Yn6s+VSx5KBV6Nx8LQEhu+cz7LCej18rQ1HLyg9PSC9jP/ZNx0o6FAIK9c0F1kHylzSxKsdlkrQ==} + '@radix-ui/react-use-callback-ref@1.1.5': + resolution: {integrity: sha512-Y5GBf4NKeADoXI1geiMlMuMoURT3k9MizzzKhGb/m55H94aGigZ01PIpkvsO6lML13BA6XYAXSJ6gza7vTn5nw==} peerDependencies: '@types/react': '*' react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc @@ -1779,8 +1780,8 @@ packages: '@types/react': optional: true - '@radix-ui/react-use-controllable-state@1.2.6': - resolution: {integrity: sha512-uEQJGT97ZA/TgP/Hydw47lHu+/vQj6z/0jA+WeTbK1o9Rx45GImjpD0tc3W5ad3D6XTSR6e1yEO0FvGq6WQfVQ==} + '@radix-ui/react-use-controllable-state@1.3.0': + resolution: {integrity: sha512-TAcBI7bw2ljYCbv4+zuTSd6zICu8pRt6SDN2vJ/Z06K2MXh6I9WYFe/A9ovlFDtR5HVHGm5iDxDoABm/++dbKg==} peerDependencies: '@types/react': '*' react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc @@ -1833,8 +1834,8 @@ packages: '@types/react': optional: true - '@radix-ui/react-use-size@1.1.4': - resolution: {integrity: sha512-D3anSY15EJoxrihpsXI6SMrmmonnQtR2ni7arO+Lfdg3O95b9hNXxONk8jA5C8ANdF/h5HMAxejgs8PWJ6rlhw==} + '@radix-ui/react-use-size@1.1.5': + resolution: {integrity: sha512-V1McDQkMGzgivwqdu7u96APs7oi0Jvj9LTzgq3WWrDZqxWdAqU9yZnZQqk5OizGFR8badUQwZsrlao7MOlWYOA==} peerDependencies: '@types/react': '*' react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc @@ -1842,8 +1843,8 @@ packages: '@types/react': optional: true - '@radix-ui/react-visually-hidden@1.2.11': - resolution: {integrity: sha512-NFS86RYYZb4/exihaESBGOpMJFz8MGLAfu3mOBSGByVnVPC9JPASfYubxd/8KbkQK0sYAv8lVQDEQukDX/qXvQ==} + '@radix-ui/react-visually-hidden@1.2.13': + resolution: {integrity: sha512-feijiN1oPk4rck4u9Dm9tsU4mT6Wp9oeEEhaz1WUEs1VuqLf8xzsFG+Qk+uWq6TnMH9O+WRECRg0NftyP9E4Fw==} peerDependencies: '@types/react': '*' '@types/react-dom': '*' @@ -1970,24 +1971,24 @@ packages: resolution: {integrity: sha512-4zPzuNTXObDUtZS93xzAoK83ddHDgBGifv/vKFe6bHqEl5i+IMLTTtEHOaaOZK4dusPEXcXsU5TBSaY/I6Mi+A==} engines: {node: '>=22'} - '@scalar/helpers@0.12.0': - resolution: {integrity: sha512-rcX0rFLiWWc0VBr/E+HkatubL0I0ZzxASQkd3032NWEMAEfNd2TiJ9kH46HwbSAOOl696ghxymWegjpjjvxwzA==} + '@scalar/helpers@0.16.4': + resolution: {integrity: sha512-9eILWzUcAkHEuYMMvijpSIy69t+Vkq+NudLB/7lgARFTWqXfQpIxW1L3VH7ogKyRie5+E4CNZ3PSvlw6IIfLGw==} engines: {node: '>=22'} '@scalar/json-magic@0.13.4': resolution: {integrity: sha512-pOZdlzkgLB+/4OlIlzMToV/cr4vsvWy/MtbtJoRcNHIzDnT8sfNtv/cH8MR2pNDg/29sPpTV1HaE4SZ8b9jUOQ==} engines: {node: '>=22'} - '@scalar/json-magic@0.13.5': - resolution: {integrity: sha512-w5eENfKAkc4CYiLva3nGUhTaJfyi3szmZ3E7+EHlzahOUnbDmB9rAWyzt8GFCXbwxeTuR+1m7lO1PyV/QAid4A==} + '@scalar/json-magic@0.16.1': + resolution: {integrity: sha512-yWQJUrkufUsShizF+rGKO4BoZ/ijMpnrgwRjtCA2cYqjxkQOYaQCd+WVF+b3ihmXE7amr768pLItFCx5UV/ObQ==} engines: {node: '>=22'} - '@scalar/openapi-types@0.9.6': - resolution: {integrity: sha512-hge0dhllV70dwqgUiucmDY5yZLq91BOV/78lWSqQMTY67x+LHcQplJUZDomfFi5oepROpWDs5iaKMr7ubqDBOA==} + '@scalar/openapi-types@0.9.8': + resolution: {integrity: sha512-pGcpkZObsGBC7nRKYte+6gstoe0C4hp7B2UWQYjg5To1wE68s3OHVvin+muL3tn3ZAoahXeJAkn1+aEcMi802w==} engines: {node: '>=22'} - '@scalar/openapi-upgrader@0.2.17': - resolution: {integrity: sha512-HoSgjb57UNH2OACVmbo4yLPnvP3BPnvtSMJVqRhjOspJhz945XEZYnfwgk2C3hET0bFvkc7aLSabm/K1nbjp8Q==} + '@scalar/openapi-upgrader@0.4.6': + resolution: {integrity: sha512-wkTbowGZAlDA5AhCAnBVft6y3veoE17P+okH/zrwM/BZWBSzPghGpa4BPTCg3+IzRmRP/8ZeaYO7LfxCDAEmcA==} engines: {node: '>=22'} '@sec-ant/readable-stream@0.4.1': @@ -2021,36 +2022,36 @@ packages: peerDependencies: semantic-release: '>=20.1.0' - '@shikijs/core@4.5.0': - resolution: {integrity: sha512-6CIgwq+bt2JZ3OSjb/nBkkwEf/CfpHcbam+Mg5Pllco7HAGRQ2/EFhZrrJtbyNTgKwknfVS+llsXGygiDGwJWw==} + '@shikijs/core@4.6.0': + resolution: {integrity: sha512-bfd4OKgvoyXYiYmMRuleA656P4V7M/Du9lcTl38Ngm6KszMj7bq4J1IGZwSYR4c95Tv5UQALtYNWUwaI9UT3xw==} engines: {node: '>=20'} - '@shikijs/engine-javascript@4.5.0': - resolution: {integrity: sha512-Ed6UdEj84LyYkwnxM5CvSMWAD+id9ExTYri0/+x41U9zrgNifPSS9lZm0JqBP0VfYI8yr8tY5nbNq9+p9R0kFA==} + '@shikijs/engine-javascript@4.6.0': + resolution: {integrity: sha512-K0oqxFoL+kEMdz89mHLFO15Tsbv3kFZ6WR1cXZKMvLSc+oqaM00A6pyga1qSeXB22dP0tTiSApRcGBaKWsEccg==} engines: {node: '>=20'} - '@shikijs/engine-oniguruma@4.5.0': - resolution: {integrity: sha512-dKVmbJecVdB9recl8a/CU4jdpNXyjJQrIcesIkpS70s5HS02ohpnCSpMUbotPnEUzbAcLQ+S4hwZYbkBBiTcJw==} + '@shikijs/engine-oniguruma@4.6.0': + resolution: {integrity: sha512-aggd6Q7SuJOXNnsUbfG2XesxBJKBMAw/PDTUo9PyRjMaaJJ2dNrI+q0C+25ARXAK9yLHAlwxc9oRT2u68YKZ7w==} engines: {node: '>=20'} - '@shikijs/langs@4.5.0': - resolution: {integrity: sha512-wwBTqwduXSz0X4v9Qa2EWeFaYJEw1clCncWjoRNQRbVDu3SPRTRWucnouYapKj3b8Q+sk/41Vbc4B5c8nuYzLA==} + '@shikijs/langs@4.6.0': + resolution: {integrity: sha512-1yMEX3oCVV54LUq/ovfpRkDQoYDkcvjSWFFa/YLUDMiSoRzMi2uxLJYbv41ahT8Lu9lFMaa7hecd3Q39trqUyg==} engines: {node: '>=20'} - '@shikijs/primitive@4.5.0': - resolution: {integrity: sha512-UM7ShlA8oz0OWxLLO8BmO9Ip6fVqdkt8yF0EH7nOCqHfrx1eEAzF0ZUVK7L+I8NEgeu1PEWSRlxaiPPeCb4iDg==} + '@shikijs/primitive@4.6.0': + resolution: {integrity: sha512-c54+TQEo9ToqgfL/AU8FpjnV09+GA9Oa7M5ROkkXteZfp5XzpAJGXjjvZQFQioJOwm/w/6Z3lIzQstAkl8coag==} engines: {node: '>=20'} - '@shikijs/themes@4.5.0': - resolution: {integrity: sha512-zGb87H3UBbpuI4yoh5UguB1XbU+2BDU3kflM7UfZ+Cy2hWo9lBtqjSVK20gmLY6ukYl040hAypGXMgud9vul8Q==} + '@shikijs/themes@4.6.0': + resolution: {integrity: sha512-qHAVAs80RiGD+IRuH9G+JPDOEc9A/kHsng4EzCUCwB9bLzW6Z0y9WETh2YyCcADJBmfrIaJ1Jp7KBNP6FHkgtQ==} engines: {node: '>=20'} - '@shikijs/types@4.5.0': - resolution: {integrity: sha512-drtPrtD8N0DENyD2cyt6Ajy+IWsiCLgMxODwLTpvH1UsN6a9jf90tNTPjqwHvA+0Lzu9e0txk8DjfqH1p9UJRw==} + '@shikijs/types@4.6.0': + resolution: {integrity: sha512-+ENG1adsKt/X7cRYw1Nl7BEpBmPOjmQ7bR/eGmHuMlT8gtOFf3KEi5l31DJYyAWhW6Y6bjP1plU7FmaxWGENFw==} engines: {node: '>=20'} - '@shikijs/vscode-textmate@10.0.2': - resolution: {integrity: sha512-83yeghZ2xxin3Nj8z1NMd/NCuca+gsYXswywDy5bHvwlWL8tpTQmzGeUuHd9FC3E/SBEMvzJRwWEOz5gGes9Qg==} + '@shikijs/vscode-textmate@10.1.0': + resolution: {integrity: sha512-cVBuhDQjBZaNMTwBquYfPydrUP+E3hE6oYGasx8h6ZrODIM7/r+gxLDXdd66oszbrggZHEntdE6j+5gYIVyMWQ==} '@simple-git/args-pathspec@1.0.3': resolution: {integrity: sha512-ngJMaHlsWDTfjyq9F3VIQ8b7NXbBLq5j9i5bJ6XLYtD6qlDXT7fdKY2KscWWUF8t18xx052Y/PUO1K1TRc9yKA==} @@ -2102,7 +2103,9 @@ packages: '@smithy/core@3.24.0': resolution: {integrity: sha512-rZ5YfycIXX6puoGjthnDiMpUgtKNOq3c7CndQYkCNYQTv26AiCrZQOJPy7ANSfZ6Okk3UvCRnmO1OYWlLnYZgg==} engines: {node: '>=18.0.0'} - deprecated: Deprecated due to incompatibility with Node.js 18 in some environments https://github.com/smithy-lang/smithy-typescript/issues/2022 + deprecated: |- + Deprecated due to a bug in custom logger data redaction. Upgrade to the latest version. If you used a custom logger with this + version, review your logs and rotate any credentials or other secrets. See https://github.com/aws/aws-sdk-js-v3/issues/8393. '@smithy/credential-provider-imds@4.2.14': resolution: {integrity: sha512-Au28zBN48ZAoXdooGUHemuVBrkE+Ie6RPmGNIAJsFqj33Vhb6xAgRifUydZ2aY+M+KaMAETAlKk5NC5h1G7wpg==} @@ -3286,14 +3289,9 @@ packages: engines: {node: '>=20'} hasBin: true - cn@0.3.3: - resolution: {integrity: sha512-OEiyJkSpYm2kOuNOKQ+c2wmzZRG8orrb9fnObtHTbCGNx/E9KLnGcmcocItOzREKk5KzQN5I2e3BUCj563KEpw==} - engines: {node: '>=20'} - hasBin: true - - cn@0.4.0: - resolution: {integrity: sha512-qOAeUhPwPzBxx6jaeQdo646XIKliKHc2j1ZF7Ngb1o0pJZKH5gq8FkA0aVdUdPFUDXNXyUCXpCtoJISo6dhizg==} - engines: {node: '>=20'} + cn@0.5.2: + resolution: {integrity: sha512-wm10E6iuJ37rALOw3D+3cfaXXZSLNMh2uxpQn3dNICqfJM59yXqgbA9/9Iiz155j5kYNLdK6WreNdW3NQtx3OQ==} + engines: {node: '>=22'} hasBin: true collapse-white-space@2.1.0: @@ -3926,16 +3924,19 @@ packages: resolution: {integrity: sha512-8RipRLol37bNs2bhoV67fiTEvdTrbMUYcFTiy3+wuuOnUog2QBHCZWXDRijWQfAkhBj2Uf5UnVaiWwA5vdd82w==} engines: {node: '>= 6'} - framer-motion@14.1.0: - resolution: {integrity: sha512-QsdZSdWoyQfUmgi+GZfow8Du5COG6VRYEo9FlgKUPgH87/Le/fYekHCAKwLdYKHdCZcZfWHg4iOxlD6RoqXciQ==} + framer-motion@14.9.1: + resolution: {integrity: sha512-WDWNT2ixHdmpvGg02BZWI/SWwRYzPiMUf4aIkTBgrxxD8RYFdZO3fCM4pnLMo6j8mUpj0+BuJRHQBChI4v3Anw==} peerDependencies: react: ^18.0.0 || ^19.0.0 react-dom: ^18.0.0 || ^19.0.0 + remix: ^3.1.0 peerDependenciesMeta: react: optional: true react-dom: optional: true + remix: + optional: true fromentries@1.3.2: resolution: {integrity: sha512-cHEpEQHUg0f8XdtZCc2ZAhrHzKzT0MrFUTcvx+hfxYu7rGMDc5SKoXFh+n4YigxsHXRzc6OrCshdR1bWH6HHyg==} @@ -3953,14 +3954,15 @@ packages: engines: {node: ^8.16.0 || ^10.6.0 || >=11.0.0} os: [darwin] - fumadocs-core@16.17.1: - resolution: {integrity: sha512-zquUMPZaCEdsxFZ6ReZPzVN2yCP9tS3GZRndK0WtxbsvZ9KvvUDCeoLIpOZ6d3JU0uwSsclaIUGxI5ifvTftOQ==} + fumadocs-core@16.18.0: + resolution: {integrity: sha512-vXTPCu/vcHcqX+5m+02hOvKa8Izv2EC9nT0c6vTFv441gQedSSpHReVk9JmwgJQEILPdIhgCRc2DgkFUYFIc3w==} peerDependencies: '@mdx-js/mdx': '*' '@mixedbread/sdk': 0.x.x '@modelcontextprotocol/server': 2.x.x '@orama/core': 1.x.x '@oramacloud/client': 2.x.x + '@pierre/highlights': ^0.2.0 '@tanstack/react-router': 1.x.x '@types/estree-jsx': '*' '@types/hast': '*' @@ -3987,6 +3989,8 @@ packages: optional: true '@oramacloud/client': optional: true + '@pierre/highlights': + optional: true '@tanstack/react-router': optional: true '@types/estree-jsx': @@ -4055,13 +4059,13 @@ packages: vite: optional: true - fumadocs-openapi@12.1.1: - resolution: {integrity: sha512-7NirdbnoE2cxxTdzUSfAFJEdSqjQq74IamNsaRXBrMHtHZ/2l2sMnD3TTE0eB5YK9dQBc3PB/aHcx4fQTAv59w==} + fumadocs-openapi@12.6.0: + resolution: {integrity: sha512-N0dsXKwpbMQVQ4BICy/XqO0EGkAYshL6kDssEBAofsm2ogT9/4HXtgPxNE8ipuCrEs3rpOqqm+nQJV/savfGZA==} peerDependencies: '@scalar/api-client-react': ^2.0.20 '@types/react': '*' - fumadocs-core: ^16.15.0 - fumadocs-ui: ^16.15.0 + fumadocs-core: ^16.17.11 + fumadocs-ui: ^16.17.8 json-schema-typed: '*' react: ^19.2.0 react-dom: ^19.2.0 @@ -4073,12 +4077,12 @@ packages: json-schema-typed: optional: true - fumadocs-ui@16.17.1: - resolution: {integrity: sha512-ByW1NbvEbMfsZfW+DkWewSEX7Ituv732K0y2ga1ri+Zghf+4zu2sa0QjJetC3DaKffyvx5vbPVxwjyYCeNtRhg==} + fumadocs-ui@16.18.0: + resolution: {integrity: sha512-VecAJGSs/YSxQjrROeoYtWxQ3cU36c8IVIwNw87gdTVuMDESMexspiFaJjYuYGNT3nAvjouPycLfIJD+aiV7Xg==} peerDependencies: '@types/mdx': '*' '@types/react': '*' - fumadocs-core: 16.17.1 + fumadocs-core: 16.18.0 next: 16.x.x react: ^19.2.0 react-dom: ^19.2.0 @@ -4286,8 +4290,8 @@ packages: hast-util-to-estree@3.1.3: resolution: {integrity: sha512-48+B/rJWAp0jamNbAAf9M7Uf//UVqAoMmgXhBdxTDJLGKY+LRnZ99qcG+Qjl5HfMpYNzS5v4EAwVEF34LeAj7w==} - hast-util-to-html@9.0.5: - resolution: {integrity: sha512-OguPdidb+fbHQSU4Q4ZiLKnzWo8Wwsf5bZfbvu7//a9oTYoqD/fWpe96NuHkoS9h0ccGOTe0C4NGXdtS0iObOw==} + hast-util-to-html@9.0.6: + resolution: {integrity: sha512-1SZUxCN3TtJAE7e2BQN2MBHsoZ1gnmi9GoCP5Di59CSWptIezSAW09yDZyVbanb78V9eCwrKqdQsjtfVTxYHWA==} hast-util-to-jsx-runtime@2.3.6: resolution: {integrity: sha512-zl6s8LwNyo1P9uw+XJGvZtdFF1GdAkOg8ujOw+4Pyb76874fLps4ueHXDhXWdk6YHQ6OgUtinliG7RsYvCbbBg==} @@ -4335,6 +4339,7 @@ packages: http-call@5.3.0: resolution: {integrity: sha512-ahwimsC23ICE4kPl9xTBjKB4inbRaeLyZeRunC/1Jy/Z6X8tv22MEAjK+KBOMSVLaqXPTTmd8638waVIKLGx2w==} engines: {node: '>=8.0.0'} + deprecated: Renamed to @heroku/http-call — please install @heroku/http-call instead. http-proxy-agent@7.0.2: resolution: {integrity: sha512-T1gkAiYYDWYx3V5Bmyu7HcfcvL7mUrTWiM6yOfa3PIphViJ/gFPbvidQ+veqSOHci/PxBcDabeUNCzpOODJZig==} @@ -4992,8 +4997,8 @@ packages: lru-cache@5.1.1: resolution: {integrity: sha512-KpNARQA3Iwv+jTA0utUVVbrh+Jlrr1Fv0e56GGzAFOXN7dk/FviaDW8LHmK52DlcH4WP2n6gI8vN1aesBFgo9w==} - lucide-react@1.54.0: - resolution: {integrity: sha512-kVmnVCBoLztTGe3S76xu8utwxijRLOinknNq9e8btZ0R2fm6WCgxY+weaLiA50odo/yi+apm/4B2A/LsFZhTrw==} + lucide-react@1.69.0: + resolution: {integrity: sha512-UTFECm4yEgkgMN0kfLuxWcmlk+4u02Jrqehgk3ZXRx/Ud68OpP7hjkp67bvkBHmIpMaZCIveF1QDYeupO7XmYQ==} peerDependencies: '@types/react': '*' react: ^16.5.1 || ^17.0.0 || ^18.0.0 || ^19.0.0 @@ -5171,6 +5176,9 @@ packages: micromark-util-decode-string@2.0.1: resolution: {integrity: sha512-nDV/77Fj6eH1ynwscYTOsbK7rR//Uj0bZXBwJZRfaLEJ1iGBR6kIfNmlNqaqJf649EP0F3NWNdeJi03elllNUQ==} + micromark-util-edit-map@1.0.0: + resolution: {integrity: sha512-Pa2ljlsEL6sVwFaYeyrOLSYbQt73JvGbPOYFq+9AElXiSnfI5Q4465RRZ1sHv7lDjDOnGRDDaqPXqClqWK/q1Q==} + micromark-util-encode@2.0.1: resolution: {integrity: sha512-c3cVx2y4KqUnwopcO9b/SCdo2O67LwJJ/UyqGfbigahfegL9myoEFoDYZgkT7f36T0bLrM9hZTAaAyH+PCAXjw==} @@ -5198,8 +5206,8 @@ packages: micromark-util-types@2.0.3: resolution: {integrity: sha512-oxB2Ik03hI0gv+VNn9tnh1t1YEe9MDPptViAEgfdf3YQHsn0pzGTgCdlSCJXcwhqm8phaEuM7zeEu3QQzVBrPg==} - micromark@4.0.2: - resolution: {integrity: sha512-zpe98Q6kvavpCr1NPVSCMebCKfD7CA2NqZ+rykeNhONIJBpc1tFKt9hucLGwha3jNTNI8lHpctWJWoimVF4PfA==} + micromark@4.0.3: + resolution: {integrity: sha512-oGYfQzHSG5dOMovQcJ3fyTmZlWAWpi0XA0sJwJs+i6OT88o1+Jtw/8z0CmdowSLxGhhFK89rQ/oXph/wN02PNw==} micromatch@4.0.8: resolution: {integrity: sha512-PXwfBhYu0hBCPw8Dn0E+WDYb7af3dSLVWKi3HGv84IdF4TyFoC0ysxFd0Goxw7nSv4T/PzEJQxsYsEiFCKo2BA==} @@ -5261,22 +5269,25 @@ packages: engines: {node: ^18.18.0 || ^20.9.0 || >=21.1.0} hasBin: true - motion-dom@14.1.0: - resolution: {integrity: sha512-FyFLkNUAAETzCvf851mZcl+v+kaZrKq+UM+XmkY4G8n+ny/WYfiWh9j0fhSQ1KOKVQrM9/cLO11THO2k71HJlg==} + motion-dom@14.9.1: + resolution: {integrity: sha512-2eCCGXH2Yv09lM8GHK3TdfChrcvHxzVY19LD9VraoHEaQl5+PuGnTNnmJaBAR+5MdxUVdsLFXygFJjR9RwRSxw==} - motion-utils@14.1.0: - resolution: {integrity: sha512-xd4FeWOnnXsJHmAaRCLNbOS7mEaNOangjMt3Pl241H07f1kxW48fADQ/8O5hLLNhf1qdlozgY3PPAHBdOoU7AA==} + motion-utils@14.7.0: + resolution: {integrity: sha512-woO0/Nb7ys75f94fjvQi/6leiHGvZUYkeHUPEZ3vxsV+9OpEVhkxp01x8MlRwX0zt31EqgXsKDAoBoJLC148Tw==} - motion@14.1.0: - resolution: {integrity: sha512-lsCsW9uJ+iMJj8MSiLccpUC+ZUpoSspaX6Pm78KrnZKMioCPAPG6WeG1d1d/Ywg+z1mny+STP6VyEYW+3nAqNw==} + motion@14.9.1: + resolution: {integrity: sha512-u58zTNOs6vefAwvPncTJ8vkQm+P08V4+mhNgap8p/mFZjl8+gWp7SG4cMTamebVSgpX6PcDtqzWpZngqKcfd7A==} peerDependencies: react: ^18.0.0 || ^19.0.0 react-dom: ^18.0.0 || ^19.0.0 + remix: ^3.1.0 peerDependenciesMeta: react: optional: true react-dom: optional: true + remix: + optional: true ms@2.1.3: resolution: {integrity: sha512-6FlzubTLZG3J2a/NVCAleEhjzq5oxgHyaCU9yYXvcLsvoVaHJq/s5xXI6/XXP6tz7R9xAOtHnSO/tXtF3WRTlA==} @@ -6040,8 +6051,8 @@ packages: resolution: {integrity: sha512-7++dFhtcx3353uBaq8DDR4NuxBetBzC7ZQOhmTQInHEd6bSrXdiEyzCvG07Z44UYdLShWUyXt5M/yhz8ekcb1A==} engines: {node: '>=8'} - shiki@4.5.0: - resolution: {integrity: sha512-OcRW72ngQvc+MSVWBRIovC/BTW589iUE/Vxav7VeM4RcY9MUjqB+IR6ILG1k9nuW6LiG/nct9uma4/MBtnZbmQ==} + shiki@4.6.0: + resolution: {integrity: sha512-imjLsVHgPuWhvpU3P+zOekvMYqnel7QmKsFC4Sn0fCuAvaaalBsxwKEsrU8Ko5BdFnZA6Go/8a0RzahS634UgA==} engines: {node: '>=20'} side-channel-list@1.0.1: @@ -6450,8 +6461,8 @@ packages: resolution: {integrity: sha512-4yqz8a3n5HmGTlsbADNtr/dJlhkh/55Rq798G6ibiULcXbDtaLpTl1pvdqcbFfeoj3iSi52lePFM7h9H21cw/A==} engines: {node: '>=18.17'} - undici@7.29.1: - resolution: {integrity: sha512-RYONW2MeafgYlkVOKYKkA/Ag7BmXqgIWCa8t1m0JcxrQg9pI9lEqRhAOruOBCbAohOa/gkCF+iPi9hrgvTzu6Q==} + undici@7.30.1: + resolution: {integrity: sha512-03KrMbjIFDWQR5RNPrSw3bd1r12JpyFQl9/yxjUbJtqkjmllqC5lFjZh6ujeuJCKr8EOQvRW872Oy/az+nLYxg==} engines: {node: '>=20.18.1'} unicode-emoji-modifier-base@1.0.0: @@ -6581,8 +6592,8 @@ packages: '@types/react': optional: true - use-sync-external-store@1.6.0: - resolution: {integrity: sha512-Pp6GSwGP/NrPIrxVFAIkOQeyw8lFenOHijQWkUTrDvrF4ALqylP2C/KCkeS9dpUM3KvYRQhna5vt7IL95+ZQ9w==} + use-sync-external-store@1.7.0: + resolution: {integrity: sha512-6L+EeigHMQhdaIPNIFUKwfWJSwWFQ8gJbJ2DLOs5sDIegTwR9fRxvnM3uciHKjIZhFz+KAv2emhWMRvDmMcY8A==} peerDependencies: react: ^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0 @@ -6817,8 +6828,8 @@ packages: resolution: {integrity: sha512-4BgHT4euQ62wr/9h5UWoMzt4QTrmT3WUo96aRiY2R6RRCyKjCveU23MNwNJISzYvNnbFGZ7O2E1SU5zgWqzS+Q==} engines: {node: '>=14.18.0'} - zbsearch@4.0.1: - resolution: {integrity: sha512-lmnEEnb93QQcNv7qARDr7jBVPxYdZbZ9XdZ0dbZ0qaOvGne4jJMW4fjwPfVaUKQXv3FNWvGbDwRDgyaSb1pc8w==} + zbsearch@4.0.2: + resolution: {integrity: sha512-ma4P7eyXSX5kNPU7yJvCyqa/X8E8aA90Fyd/vMz2K2wFhb4i+Yw1Qezo8/X8hNVzot3+oq5XmwgMcKcFgMOz4Q==} engines: {node: '>= 20.0.0'} zod@4.6.5: @@ -7537,26 +7548,26 @@ snapshots: '@babel/helper-string-parser': 7.27.1 '@babel/helper-validator-identifier': 7.28.5 - '@base-ui/react@1.8.0(@types/react@19.3.0)(react-dom@19.2.8(react@19.2.8))(react@19.2.8)': + '@base-ui/react@1.9.0(@types/react@19.3.0)(react-dom@19.2.8(react@19.2.8))(react@19.2.8)': dependencies: '@babel/runtime': 7.29.7 - '@base-ui/utils': 0.4.0(@types/react@19.3.0)(react-dom@19.2.8(react@19.2.8))(react@19.2.8) + '@base-ui/utils': 0.5.0(@types/react@19.3.0)(react-dom@19.2.8(react@19.2.8))(react@19.2.8) '@floating-ui/react-dom': 2.1.9(react-dom@19.2.8(react@19.2.8))(react@19.2.8) '@floating-ui/utils': 0.2.12 react: 19.2.8 react-dom: 19.2.8(react@19.2.8) - use-sync-external-store: 1.6.0(react@19.2.8) + use-sync-external-store: 1.7.0(react@19.2.8) optionalDependencies: '@types/react': 19.3.0 - '@base-ui/utils@0.4.0(@types/react@19.3.0)(react-dom@19.2.8(react@19.2.8))(react@19.2.8)': + '@base-ui/utils@0.5.0(@types/react@19.3.0)(react-dom@19.2.8(react@19.2.8))(react@19.2.8)': dependencies: '@babel/runtime': 7.29.7 '@floating-ui/utils': 0.2.12 react: 19.2.8 react-dom: 19.2.8(react@19.2.8) reselect: 5.3.0 - use-sync-external-store: 1.6.0(react@19.2.8) + use-sync-external-store: 1.7.0(react@19.2.8) optionalDependencies: '@types/react': 19.3.0 @@ -7923,18 +7934,18 @@ snapshots: optionalDependencies: '@types/react': 19.3.0 - '@fumadocs/api-docs@0.2.8(@types/react@19.3.0)(fumadocs-core@16.17.1(@mdx-js/mdx@3.1.1)(@tanstack/react-router@1.170.33(react-dom@19.2.8(react@19.2.8))(react@19.2.8))(@types/estree-jsx@1.0.5)(@types/hast@3.0.5)(@types/mdast@4.0.4)(@types/react@19.3.0)(lucide-react@1.54.0(@types/react@19.3.0)(react@19.2.8))(react-dom@19.2.8(react@19.2.8))(react@19.2.8)(zod@4.6.5))(fumadocs-ui@16.17.1(@types/mdx@2.0.14)(@types/react-dom@19.3.0(@types/react@19.3.0))(@types/react@19.3.0)(fumadocs-core@16.17.1(@mdx-js/mdx@3.1.1)(@tanstack/react-router@1.170.33(react-dom@19.2.8(react@19.2.8))(react@19.2.8))(@types/estree-jsx@1.0.5)(@types/hast@3.0.5)(@types/mdast@4.0.4)(@types/react@19.3.0)(lucide-react@1.54.0(@types/react@19.3.0)(react@19.2.8))(react-dom@19.2.8(react@19.2.8))(react@19.2.8)(zod@4.6.5))(react-dom@19.2.8(react@19.2.8))(react@19.2.8)(tailwindcss@4.3.3))(react-dom@19.2.8(react@19.2.8))(react@19.2.8)': + '@fumadocs/api-docs@0.2.8(@types/react@19.3.0)(fumadocs-core@16.18.0(@mdx-js/mdx@3.1.1)(@tanstack/react-router@1.170.33(react-dom@19.2.8(react@19.2.8))(react@19.2.8))(@types/estree-jsx@1.0.5)(@types/hast@3.0.5)(@types/mdast@4.0.4)(@types/react@19.3.0)(lucide-react@1.69.0(@types/react@19.3.0)(react@19.2.8))(react-dom@19.2.8(react@19.2.8))(react@19.2.8)(zod@4.6.5))(fumadocs-ui@16.18.0(@types/mdx@2.0.14)(@types/react-dom@19.3.0(@types/react@19.3.0))(@types/react@19.3.0)(fumadocs-core@16.18.0(@mdx-js/mdx@3.1.1)(@tanstack/react-router@1.170.33(react-dom@19.2.8(react@19.2.8))(react@19.2.8))(@types/estree-jsx@1.0.5)(@types/hast@3.0.5)(@types/mdast@4.0.4)(@types/react@19.3.0)(lucide-react@1.69.0(@types/react@19.3.0)(react@19.2.8))(react-dom@19.2.8(react@19.2.8))(react@19.2.8)(zod@4.6.5))(react-dom@19.2.8(react@19.2.8))(react@19.2.8)(tailwindcss@4.3.3))(react-dom@19.2.8(react@19.2.8))(react@19.2.8)': dependencies: - '@base-ui/react': 1.8.0(@types/react@19.3.0)(react-dom@19.2.8(react@19.2.8))(react@19.2.8) + '@base-ui/react': 1.9.0(@types/react@19.3.0)(react-dom@19.2.8(react@19.2.8))(react@19.2.8) '@fuma-translate/react': 1.0.2(@types/react@19.3.0)(react-dom@19.2.8(react@19.2.8))(react@19.2.8) '@fumari/stf': 1.1.0(@types/react@19.3.0)(react-dom@19.2.8(react@19.2.8))(react@19.2.8) '@scalar/json-magic': 0.13.4 class-variance-authority: 0.7.1 cn: 0.2.6 - fumadocs-core: 16.17.1(@mdx-js/mdx@3.1.1)(@tanstack/react-router@1.170.33(react-dom@19.2.8(react@19.2.8))(react@19.2.8))(@types/estree-jsx@1.0.5)(@types/hast@3.0.5)(@types/mdast@4.0.4)(@types/react@19.3.0)(lucide-react@1.54.0(@types/react@19.3.0)(react@19.2.8))(react-dom@19.2.8(react@19.2.8))(react@19.2.8)(zod@4.6.5) - fumadocs-ui: 16.17.1(@types/mdx@2.0.14)(@types/react-dom@19.3.0(@types/react@19.3.0))(@types/react@19.3.0)(fumadocs-core@16.17.1(@mdx-js/mdx@3.1.1)(@tanstack/react-router@1.170.33(react-dom@19.2.8(react@19.2.8))(react@19.2.8))(@types/estree-jsx@1.0.5)(@types/hast@3.0.5)(@types/mdast@4.0.4)(@types/react@19.3.0)(lucide-react@1.54.0(@types/react@19.3.0)(react@19.2.8))(react-dom@19.2.8(react@19.2.8))(react@19.2.8)(zod@4.6.5))(react-dom@19.2.8(react@19.2.8))(react@19.2.8)(tailwindcss@4.3.3) + fumadocs-core: 16.18.0(@mdx-js/mdx@3.1.1)(@tanstack/react-router@1.170.33(react-dom@19.2.8(react@19.2.8))(react@19.2.8))(@types/estree-jsx@1.0.5)(@types/hast@3.0.5)(@types/mdast@4.0.4)(@types/react@19.3.0)(lucide-react@1.69.0(@types/react@19.3.0)(react@19.2.8))(react-dom@19.2.8(react@19.2.8))(react@19.2.8)(zod@4.6.5) + fumadocs-ui: 16.18.0(@types/mdx@2.0.14)(@types/react-dom@19.3.0(@types/react@19.3.0))(@types/react@19.3.0)(fumadocs-core@16.18.0(@mdx-js/mdx@3.1.1)(@tanstack/react-router@1.170.33(react-dom@19.2.8(react@19.2.8))(react@19.2.8))(@types/estree-jsx@1.0.5)(@types/hast@3.0.5)(@types/mdast@4.0.4)(@types/react@19.3.0)(lucide-react@1.69.0(@types/react@19.3.0)(react@19.2.8))(react-dom@19.2.8(react@19.2.8))(react@19.2.8)(zod@4.6.5))(react-dom@19.2.8(react@19.2.8))(react@19.2.8)(tailwindcss@4.3.3) github-slugger: 2.0.0 - lucide-react: 1.54.0(@types/react@19.3.0)(react@19.2.8) + lucide-react: 1.69.0(@types/react@19.3.0)(react@19.2.8) react: 19.2.8 react-dom: 19.2.8(react@19.2.8) optionalDependencies: @@ -7943,17 +7954,17 @@ snapshots: - '@date-fns/tz' - date-fns - '@fumadocs/json-schema@0.2.0(@types/react@19.3.0)(react-dom@19.2.8(react@19.2.8))(react@19.2.8)': + '@fumadocs/json-schema@0.3.5(@types/react@19.3.0)(react-dom@19.2.8(react@19.2.8))(react@19.2.8)': dependencies: '@fuma-translate/react': 1.0.2(@types/react@19.3.0)(react-dom@19.2.8(react@19.2.8))(react@19.2.8) - '@scalar/json-magic': 0.13.5 + '@scalar/json-magic': 0.16.1 optionalDependencies: react: 19.2.8 transitivePeerDependencies: - '@types/react' - react-dom - '@fumadocs/tailwind@0.1.3(tailwindcss@4.3.3)': + '@fumadocs/tailwind@0.1.5(tailwindcss@4.3.3)': optionalDependencies: tailwindcss: 4.3.3 @@ -7968,7 +7979,7 @@ snapshots: optionalDependencies: '@types/react': 19.3.0 - '@fumari/stf@1.1.1(@types/react@19.3.0)(react-dom@19.2.8(react@19.2.8))(react@19.2.8)': + '@fumari/stf@1.1.2(@types/react@19.3.0)(react-dom@19.2.8(react@19.2.8))(react@19.2.8)': dependencies: react: 19.2.8 react-dom: 19.2.8(react@19.2.8) @@ -8399,43 +8410,43 @@ snapshots: '@radix-ui/number@1.1.3': {} - '@radix-ui/primitive@1.1.7': {} + '@radix-ui/primitive@1.2.0': {} - '@radix-ui/react-accordion@1.2.20(@types/react-dom@19.3.0(@types/react@19.3.0))(@types/react@19.3.0)(react-dom@19.2.8(react@19.2.8))(react@19.2.8)': + '@radix-ui/react-accordion@1.3.1(@types/react-dom@19.3.0(@types/react@19.3.0))(@types/react@19.3.0)(react-dom@19.2.8(react@19.2.8))(react@19.2.8)': dependencies: - '@radix-ui/primitive': 1.1.7 - '@radix-ui/react-collapsible': 1.1.20(@types/react-dom@19.3.0(@types/react@19.3.0))(@types/react@19.3.0)(react-dom@19.2.8(react@19.2.8))(react@19.2.8) - '@radix-ui/react-collection': 1.1.15(@types/react-dom@19.3.0(@types/react@19.3.0))(@types/react@19.3.0)(react-dom@19.2.8(react@19.2.8))(react@19.2.8) + '@radix-ui/primitive': 1.2.0 + '@radix-ui/react-collapsible': 1.2.1(@types/react-dom@19.3.0(@types/react@19.3.0))(@types/react@19.3.0)(react-dom@19.2.8(react@19.2.8))(react@19.2.8) + '@radix-ui/react-collection': 1.2.0(@types/react-dom@19.3.0(@types/react@19.3.0))(@types/react@19.3.0)(react-dom@19.2.8(react@19.2.8))(react@19.2.8) '@radix-ui/react-compose-refs': 1.1.5(@types/react@19.3.0)(react@19.2.8) - '@radix-ui/react-context': 1.2.2(@types/react@19.3.0)(react@19.2.8) - '@radix-ui/react-direction': 1.1.4(@types/react@19.3.0)(react@19.2.8) + '@radix-ui/react-context': 1.3.0(@types/react@19.3.0)(react@19.2.8) + '@radix-ui/react-direction': 1.2.0(@types/react@19.3.0)(react@19.2.8) '@radix-ui/react-id': 1.1.4(@types/react@19.3.0)(react@19.2.8) - '@radix-ui/react-primitive': 2.1.10(@types/react-dom@19.3.0(@types/react@19.3.0))(@types/react@19.3.0)(react-dom@19.2.8(react@19.2.8))(react@19.2.8) - '@radix-ui/react-use-controllable-state': 1.2.6(@types/react@19.3.0)(react@19.2.8) + '@radix-ui/react-primitive': 2.2.0(@types/react-dom@19.3.0(@types/react@19.3.0))(@types/react@19.3.0)(react-dom@19.2.8(react@19.2.8))(react@19.2.8) + '@radix-ui/react-use-controllable-state': 1.3.0(@types/react@19.3.0)(react@19.2.8) react: 19.2.8 react-dom: 19.2.8(react@19.2.8) optionalDependencies: '@types/react': 19.3.0 '@types/react-dom': 19.3.0(@types/react@19.3.0) - '@radix-ui/react-arrow@1.1.15(@types/react-dom@19.3.0(@types/react@19.3.0))(@types/react@19.3.0)(react-dom@19.2.8(react@19.2.8))(react@19.2.8)': + '@radix-ui/react-arrow@1.1.17(@types/react-dom@19.3.0(@types/react@19.3.0))(@types/react@19.3.0)(react-dom@19.2.8(react@19.2.8))(react@19.2.8)': dependencies: - '@radix-ui/react-primitive': 2.1.10(@types/react-dom@19.3.0(@types/react@19.3.0))(@types/react@19.3.0)(react-dom@19.2.8(react@19.2.8))(react@19.2.8) + '@radix-ui/react-primitive': 2.2.0(@types/react-dom@19.3.0(@types/react@19.3.0))(@types/react@19.3.0)(react-dom@19.2.8(react@19.2.8))(react@19.2.8) react: 19.2.8 react-dom: 19.2.8(react@19.2.8) optionalDependencies: '@types/react': 19.3.0 '@types/react-dom': 19.3.0(@types/react@19.3.0) - '@radix-ui/react-collapsible@1.1.20(@types/react-dom@19.3.0(@types/react@19.3.0))(@types/react@19.3.0)(react-dom@19.2.8(react@19.2.8))(react@19.2.8)': + '@radix-ui/react-collapsible@1.2.1(@types/react-dom@19.3.0(@types/react@19.3.0))(@types/react@19.3.0)(react-dom@19.2.8(react@19.2.8))(react@19.2.8)': dependencies: - '@radix-ui/primitive': 1.1.7 + '@radix-ui/primitive': 1.2.0 '@radix-ui/react-compose-refs': 1.1.5(@types/react@19.3.0)(react@19.2.8) - '@radix-ui/react-context': 1.2.2(@types/react@19.3.0)(react@19.2.8) + '@radix-ui/react-context': 1.3.0(@types/react@19.3.0)(react@19.2.8) '@radix-ui/react-id': 1.1.4(@types/react@19.3.0)(react@19.2.8) - '@radix-ui/react-presence': 1.1.10(@types/react-dom@19.3.0(@types/react@19.3.0))(@types/react@19.3.0)(react-dom@19.2.8(react@19.2.8))(react@19.2.8) - '@radix-ui/react-primitive': 2.1.10(@types/react-dom@19.3.0(@types/react@19.3.0))(@types/react@19.3.0)(react-dom@19.2.8(react@19.2.8))(react@19.2.8) - '@radix-ui/react-use-controllable-state': 1.2.6(@types/react@19.3.0)(react@19.2.8) + '@radix-ui/react-presence': 1.1.11(@types/react-dom@19.3.0(@types/react@19.3.0))(@types/react@19.3.0)(react-dom@19.2.8(react@19.2.8))(react@19.2.8) + '@radix-ui/react-primitive': 2.2.0(@types/react-dom@19.3.0(@types/react@19.3.0))(@types/react@19.3.0)(react-dom@19.2.8(react@19.2.8))(react@19.2.8) + '@radix-ui/react-use-controllable-state': 1.3.0(@types/react@19.3.0)(react@19.2.8) '@radix-ui/react-use-layout-effect': 1.1.4(@types/react@19.3.0)(react@19.2.8) react: 19.2.8 react-dom: 19.2.8(react@19.2.8) @@ -8443,12 +8454,13 @@ snapshots: '@types/react': 19.3.0 '@types/react-dom': 19.3.0(@types/react@19.3.0) - '@radix-ui/react-collection@1.1.15(@types/react-dom@19.3.0(@types/react@19.3.0))(@types/react@19.3.0)(react-dom@19.2.8(react@19.2.8))(react@19.2.8)': + '@radix-ui/react-collection@1.2.0(@types/react-dom@19.3.0(@types/react@19.3.0))(@types/react@19.3.0)(react-dom@19.2.8(react@19.2.8))(react@19.2.8)': dependencies: '@radix-ui/react-compose-refs': 1.1.5(@types/react@19.3.0)(react@19.2.8) - '@radix-ui/react-context': 1.2.2(@types/react@19.3.0)(react@19.2.8) - '@radix-ui/react-primitive': 2.1.10(@types/react-dom@19.3.0(@types/react@19.3.0))(@types/react@19.3.0)(react-dom@19.2.8(react@19.2.8))(react@19.2.8) - '@radix-ui/react-slot': 1.3.3(@types/react@19.3.0)(react@19.2.8) + '@radix-ui/react-context': 1.3.0(@types/react@19.3.0)(react@19.2.8) + '@radix-ui/react-primitive': 2.2.0(@types/react-dom@19.3.0(@types/react@19.3.0))(@types/react@19.3.0)(react-dom@19.2.8(react@19.2.8))(react@19.2.8) + '@radix-ui/react-slot': 1.5.0(@types/react@19.3.0)(react@19.2.8) + '@radix-ui/react-use-layout-effect': 1.1.4(@types/react@19.3.0)(react@19.2.8) react: 19.2.8 react-dom: 19.2.8(react@19.2.8) optionalDependencies: @@ -8461,26 +8473,26 @@ snapshots: optionalDependencies: '@types/react': 19.3.0 - '@radix-ui/react-context@1.2.2(@types/react@19.3.0)(react@19.2.8)': + '@radix-ui/react-context@1.3.0(@types/react@19.3.0)(react@19.2.8)': dependencies: react: 19.2.8 optionalDependencies: '@types/react': 19.3.0 - '@radix-ui/react-dialog@1.1.23(@types/react-dom@19.3.0(@types/react@19.3.0))(@types/react@19.3.0)(react-dom@19.2.8(react@19.2.8))(react@19.2.8)': + '@radix-ui/react-dialog@1.3.1(@types/react-dom@19.3.0(@types/react@19.3.0))(@types/react@19.3.0)(react-dom@19.2.8(react@19.2.8))(react@19.2.8)': dependencies: - '@radix-ui/primitive': 1.1.7 + '@radix-ui/primitive': 1.2.0 '@radix-ui/react-compose-refs': 1.1.5(@types/react@19.3.0)(react@19.2.8) - '@radix-ui/react-context': 1.2.2(@types/react@19.3.0)(react@19.2.8) - '@radix-ui/react-dismissable-layer': 1.1.19(@types/react-dom@19.3.0(@types/react@19.3.0))(@types/react@19.3.0)(react-dom@19.2.8(react@19.2.8))(react@19.2.8) - '@radix-ui/react-focus-guards': 1.1.6(@types/react@19.3.0)(react@19.2.8) - '@radix-ui/react-focus-scope': 1.1.16(@types/react-dom@19.3.0(@types/react@19.3.0))(@types/react@19.3.0)(react-dom@19.2.8(react@19.2.8))(react@19.2.8) + '@radix-ui/react-context': 1.3.0(@types/react@19.3.0)(react@19.2.8) + '@radix-ui/react-dismissable-layer': 1.2.1(@types/react-dom@19.3.0(@types/react@19.3.0))(@types/react@19.3.0)(react-dom@19.2.8(react@19.2.8))(react@19.2.8) + '@radix-ui/react-focus-guards': 1.2.0(@types/react@19.3.0)(react@19.2.8) + '@radix-ui/react-focus-scope': 1.3.1(@types/react-dom@19.3.0(@types/react@19.3.0))(@types/react@19.3.0)(react-dom@19.2.8(react@19.2.8))(react@19.2.8) '@radix-ui/react-id': 1.1.4(@types/react@19.3.0)(react@19.2.8) - '@radix-ui/react-portal': 1.1.17(@types/react-dom@19.3.0(@types/react@19.3.0))(@types/react@19.3.0)(react-dom@19.2.8(react@19.2.8))(react@19.2.8) - '@radix-ui/react-presence': 1.1.10(@types/react-dom@19.3.0(@types/react@19.3.0))(@types/react@19.3.0)(react-dom@19.2.8(react@19.2.8))(react@19.2.8) - '@radix-ui/react-primitive': 2.1.10(@types/react-dom@19.3.0(@types/react@19.3.0))(@types/react@19.3.0)(react-dom@19.2.8(react@19.2.8))(react@19.2.8) - '@radix-ui/react-slot': 1.3.3(@types/react@19.3.0)(react@19.2.8) - '@radix-ui/react-use-controllable-state': 1.2.6(@types/react@19.3.0)(react@19.2.8) + '@radix-ui/react-portal': 1.2.0(@types/react-dom@19.3.0(@types/react@19.3.0))(@types/react@19.3.0)(react-dom@19.2.8(react@19.2.8))(react@19.2.8) + '@radix-ui/react-presence': 1.1.11(@types/react-dom@19.3.0(@types/react@19.3.0))(@types/react@19.3.0)(react-dom@19.2.8(react@19.2.8))(react@19.2.8) + '@radix-ui/react-primitive': 2.2.0(@types/react-dom@19.3.0(@types/react@19.3.0))(@types/react@19.3.0)(react-dom@19.2.8(react@19.2.8))(react@19.2.8) + '@radix-ui/react-slot': 1.5.0(@types/react@19.3.0)(react@19.2.8) + '@radix-ui/react-use-controllable-state': 1.3.0(@types/react@19.3.0)(react@19.2.8) '@radix-ui/react-use-layout-effect': 1.1.4(@types/react@19.3.0)(react@19.2.8) aria-hidden: 1.2.6 react: 19.2.8 @@ -8490,18 +8502,18 @@ snapshots: '@types/react': 19.3.0 '@types/react-dom': 19.3.0(@types/react@19.3.0) - '@radix-ui/react-direction@1.1.4(@types/react@19.3.0)(react@19.2.8)': + '@radix-ui/react-direction@1.2.0(@types/react@19.3.0)(react@19.2.8)': dependencies: react: 19.2.8 optionalDependencies: '@types/react': 19.3.0 - '@radix-ui/react-dismissable-layer@1.1.19(@types/react-dom@19.3.0(@types/react@19.3.0))(@types/react@19.3.0)(react-dom@19.2.8(react@19.2.8))(react@19.2.8)': + '@radix-ui/react-dismissable-layer@1.2.1(@types/react-dom@19.3.0(@types/react@19.3.0))(@types/react@19.3.0)(react-dom@19.2.8(react@19.2.8))(react@19.2.8)': dependencies: - '@radix-ui/primitive': 1.1.7 + '@radix-ui/primitive': 1.2.0 '@radix-ui/react-compose-refs': 1.1.5(@types/react@19.3.0)(react@19.2.8) - '@radix-ui/react-primitive': 2.1.10(@types/react-dom@19.3.0(@types/react@19.3.0))(@types/react@19.3.0)(react-dom@19.2.8(react@19.2.8))(react@19.2.8) - '@radix-ui/react-use-callback-ref': 1.1.4(@types/react@19.3.0)(react@19.2.8) + '@radix-ui/react-primitive': 2.2.0(@types/react-dom@19.3.0(@types/react@19.3.0))(@types/react@19.3.0)(react-dom@19.2.8(react@19.2.8))(react@19.2.8) + '@radix-ui/react-use-callback-ref': 1.1.5(@types/react@19.3.0)(react@19.2.8) '@radix-ui/react-use-effect-event': 0.0.5(@types/react@19.3.0)(react@19.2.8) react: 19.2.8 react-dom: 19.2.8(react@19.2.8) @@ -8509,17 +8521,17 @@ snapshots: '@types/react': 19.3.0 '@types/react-dom': 19.3.0(@types/react@19.3.0) - '@radix-ui/react-focus-guards@1.1.6(@types/react@19.3.0)(react@19.2.8)': + '@radix-ui/react-focus-guards@1.2.0(@types/react@19.3.0)(react@19.2.8)': dependencies: react: 19.2.8 optionalDependencies: '@types/react': 19.3.0 - '@radix-ui/react-focus-scope@1.1.16(@types/react-dom@19.3.0(@types/react@19.3.0))(@types/react@19.3.0)(react-dom@19.2.8(react@19.2.8))(react@19.2.8)': + '@radix-ui/react-focus-scope@1.3.1(@types/react-dom@19.3.0(@types/react@19.3.0))(@types/react@19.3.0)(react-dom@19.2.8(react@19.2.8))(react@19.2.8)': dependencies: '@radix-ui/react-compose-refs': 1.1.5(@types/react@19.3.0)(react@19.2.8) - '@radix-ui/react-primitive': 2.1.10(@types/react-dom@19.3.0(@types/react@19.3.0))(@types/react@19.3.0)(react-dom@19.2.8(react@19.2.8))(react@19.2.8) - '@radix-ui/react-use-callback-ref': 1.1.4(@types/react@19.3.0)(react@19.2.8) + '@radix-ui/react-primitive': 2.2.0(@types/react-dom@19.3.0(@types/react@19.3.0))(@types/react@19.3.0)(react-dom@19.2.8(react@19.2.8))(react@19.2.8) + '@radix-ui/react-use-callback-ref': 1.1.5(@types/react@19.3.0)(react@19.2.8) react: 19.2.8 react-dom: 19.2.8(react@19.2.8) optionalDependencies: @@ -8533,43 +8545,45 @@ snapshots: optionalDependencies: '@types/react': 19.3.0 - '@radix-ui/react-navigation-menu@1.2.22(@types/react-dom@19.3.0(@types/react@19.3.0))(@types/react@19.3.0)(react-dom@19.2.8(react@19.2.8))(react@19.2.8)': + '@radix-ui/react-navigation-menu@1.4.1(@types/react-dom@19.3.0(@types/react@19.3.0))(@types/react@19.3.0)(react-dom@19.2.8(react@19.2.8))(react@19.2.8)': dependencies: - '@radix-ui/primitive': 1.1.7 - '@radix-ui/react-collection': 1.1.15(@types/react-dom@19.3.0(@types/react@19.3.0))(@types/react@19.3.0)(react-dom@19.2.8(react@19.2.8))(react@19.2.8) + '@radix-ui/primitive': 1.2.0 + '@radix-ui/react-collection': 1.2.0(@types/react-dom@19.3.0(@types/react@19.3.0))(@types/react@19.3.0)(react-dom@19.2.8(react@19.2.8))(react@19.2.8) '@radix-ui/react-compose-refs': 1.1.5(@types/react@19.3.0)(react@19.2.8) - '@radix-ui/react-context': 1.2.2(@types/react@19.3.0)(react@19.2.8) - '@radix-ui/react-direction': 1.1.4(@types/react@19.3.0)(react@19.2.8) - '@radix-ui/react-dismissable-layer': 1.1.19(@types/react-dom@19.3.0(@types/react@19.3.0))(@types/react@19.3.0)(react-dom@19.2.8(react@19.2.8))(react@19.2.8) + '@radix-ui/react-context': 1.3.0(@types/react@19.3.0)(react@19.2.8) + '@radix-ui/react-direction': 1.2.0(@types/react@19.3.0)(react@19.2.8) + '@radix-ui/react-dismissable-layer': 1.2.1(@types/react-dom@19.3.0(@types/react@19.3.0))(@types/react@19.3.0)(react-dom@19.2.8(react@19.2.8))(react@19.2.8) '@radix-ui/react-id': 1.1.4(@types/react@19.3.0)(react@19.2.8) - '@radix-ui/react-presence': 1.1.10(@types/react-dom@19.3.0(@types/react@19.3.0))(@types/react@19.3.0)(react-dom@19.2.8(react@19.2.8))(react@19.2.8) - '@radix-ui/react-primitive': 2.1.10(@types/react-dom@19.3.0(@types/react@19.3.0))(@types/react@19.3.0)(react-dom@19.2.8(react@19.2.8))(react@19.2.8) - '@radix-ui/react-use-callback-ref': 1.1.4(@types/react@19.3.0)(react@19.2.8) - '@radix-ui/react-use-controllable-state': 1.2.6(@types/react@19.3.0)(react@19.2.8) + '@radix-ui/react-presence': 1.1.11(@types/react-dom@19.3.0(@types/react@19.3.0))(@types/react@19.3.0)(react-dom@19.2.8(react@19.2.8))(react@19.2.8) + '@radix-ui/react-primitive': 2.2.0(@types/react-dom@19.3.0(@types/react@19.3.0))(@types/react@19.3.0)(react-dom@19.2.8(react@19.2.8))(react@19.2.8) + '@radix-ui/react-slot': 1.5.0(@types/react@19.3.0)(react@19.2.8) + '@radix-ui/react-use-callback-ref': 1.1.5(@types/react@19.3.0)(react@19.2.8) + '@radix-ui/react-use-controllable-state': 1.3.0(@types/react@19.3.0)(react@19.2.8) '@radix-ui/react-use-layout-effect': 1.1.4(@types/react@19.3.0)(react@19.2.8) '@radix-ui/react-use-previous': 1.1.4(@types/react@19.3.0)(react@19.2.8) - '@radix-ui/react-visually-hidden': 1.2.11(@types/react-dom@19.3.0(@types/react@19.3.0))(@types/react@19.3.0)(react-dom@19.2.8(react@19.2.8))(react@19.2.8) + '@radix-ui/react-visually-hidden': 1.2.13(@types/react-dom@19.3.0(@types/react@19.3.0))(@types/react@19.3.0)(react-dom@19.2.8(react@19.2.8))(react@19.2.8) react: 19.2.8 react-dom: 19.2.8(react@19.2.8) optionalDependencies: '@types/react': 19.3.0 '@types/react-dom': 19.3.0(@types/react@19.3.0) - '@radix-ui/react-popover@1.1.23(@types/react-dom@19.3.0(@types/react@19.3.0))(@types/react@19.3.0)(react-dom@19.2.8(react@19.2.8))(react@19.2.8)': + '@radix-ui/react-popover@1.3.1(@types/react-dom@19.3.0(@types/react@19.3.0))(@types/react@19.3.0)(react-dom@19.2.8(react@19.2.8))(react@19.2.8)': dependencies: - '@radix-ui/primitive': 1.1.7 + '@radix-ui/primitive': 1.2.0 '@radix-ui/react-compose-refs': 1.1.5(@types/react@19.3.0)(react@19.2.8) - '@radix-ui/react-context': 1.2.2(@types/react@19.3.0)(react@19.2.8) - '@radix-ui/react-dismissable-layer': 1.1.19(@types/react-dom@19.3.0(@types/react@19.3.0))(@types/react@19.3.0)(react-dom@19.2.8(react@19.2.8))(react@19.2.8) - '@radix-ui/react-focus-guards': 1.1.6(@types/react@19.3.0)(react@19.2.8) - '@radix-ui/react-focus-scope': 1.1.16(@types/react-dom@19.3.0(@types/react@19.3.0))(@types/react@19.3.0)(react-dom@19.2.8(react@19.2.8))(react@19.2.8) + '@radix-ui/react-context': 1.3.0(@types/react@19.3.0)(react@19.2.8) + '@radix-ui/react-dismissable-layer': 1.2.1(@types/react-dom@19.3.0(@types/react@19.3.0))(@types/react@19.3.0)(react-dom@19.2.8(react@19.2.8))(react@19.2.8) + '@radix-ui/react-focus-guards': 1.2.0(@types/react@19.3.0)(react@19.2.8) + '@radix-ui/react-focus-scope': 1.3.1(@types/react-dom@19.3.0(@types/react@19.3.0))(@types/react@19.3.0)(react-dom@19.2.8(react@19.2.8))(react@19.2.8) '@radix-ui/react-id': 1.1.4(@types/react@19.3.0)(react@19.2.8) - '@radix-ui/react-popper': 1.3.7(@types/react-dom@19.3.0(@types/react@19.3.0))(@types/react@19.3.0)(react-dom@19.2.8(react@19.2.8))(react@19.2.8) - '@radix-ui/react-portal': 1.1.17(@types/react-dom@19.3.0(@types/react@19.3.0))(@types/react@19.3.0)(react-dom@19.2.8(react@19.2.8))(react@19.2.8) - '@radix-ui/react-presence': 1.1.10(@types/react-dom@19.3.0(@types/react@19.3.0))(@types/react@19.3.0)(react-dom@19.2.8(react@19.2.8))(react@19.2.8) - '@radix-ui/react-primitive': 2.1.10(@types/react-dom@19.3.0(@types/react@19.3.0))(@types/react@19.3.0)(react-dom@19.2.8(react@19.2.8))(react@19.2.8) - '@radix-ui/react-slot': 1.3.3(@types/react@19.3.0)(react@19.2.8) - '@radix-ui/react-use-controllable-state': 1.2.6(@types/react@19.3.0)(react@19.2.8) + '@radix-ui/react-popper': 1.4.0(@types/react-dom@19.3.0(@types/react@19.3.0))(@types/react@19.3.0)(react-dom@19.2.8(react@19.2.8))(react@19.2.8) + '@radix-ui/react-portal': 1.2.0(@types/react-dom@19.3.0(@types/react@19.3.0))(@types/react@19.3.0)(react-dom@19.2.8(react@19.2.8))(react@19.2.8) + '@radix-ui/react-presence': 1.1.11(@types/react-dom@19.3.0(@types/react@19.3.0))(@types/react@19.3.0)(react-dom@19.2.8(react@19.2.8))(react@19.2.8) + '@radix-ui/react-primitive': 2.2.0(@types/react-dom@19.3.0(@types/react@19.3.0))(@types/react@19.3.0)(react-dom@19.2.8(react@19.2.8))(react@19.2.8) + '@radix-ui/react-slot': 1.5.0(@types/react@19.3.0)(react@19.2.8) + '@radix-ui/react-use-controllable-state': 1.3.0(@types/react@19.3.0)(react@19.2.8) + '@radix-ui/react-use-layout-effect': 1.1.4(@types/react@19.3.0)(react@19.2.8) aria-hidden: 1.2.6 react: 19.2.8 react-dom: 19.2.8(react@19.2.8) @@ -8578,17 +8592,17 @@ snapshots: '@types/react': 19.3.0 '@types/react-dom': 19.3.0(@types/react@19.3.0) - '@radix-ui/react-popper@1.3.7(@types/react-dom@19.3.0(@types/react@19.3.0))(@types/react@19.3.0)(react-dom@19.2.8(react@19.2.8))(react@19.2.8)': + '@radix-ui/react-popper@1.4.0(@types/react-dom@19.3.0(@types/react@19.3.0))(@types/react@19.3.0)(react-dom@19.2.8(react@19.2.8))(react@19.2.8)': dependencies: '@floating-ui/react-dom': 2.1.9(react-dom@19.2.8(react@19.2.8))(react@19.2.8) - '@radix-ui/react-arrow': 1.1.15(@types/react-dom@19.3.0(@types/react@19.3.0))(@types/react@19.3.0)(react-dom@19.2.8(react@19.2.8))(react@19.2.8) + '@radix-ui/react-arrow': 1.1.17(@types/react-dom@19.3.0(@types/react@19.3.0))(@types/react@19.3.0)(react-dom@19.2.8(react@19.2.8))(react@19.2.8) '@radix-ui/react-compose-refs': 1.1.5(@types/react@19.3.0)(react@19.2.8) - '@radix-ui/react-context': 1.2.2(@types/react@19.3.0)(react@19.2.8) - '@radix-ui/react-primitive': 2.1.10(@types/react-dom@19.3.0(@types/react@19.3.0))(@types/react@19.3.0)(react-dom@19.2.8(react@19.2.8))(react@19.2.8) - '@radix-ui/react-use-callback-ref': 1.1.4(@types/react@19.3.0)(react@19.2.8) + '@radix-ui/react-context': 1.3.0(@types/react@19.3.0)(react@19.2.8) + '@radix-ui/react-primitive': 2.2.0(@types/react-dom@19.3.0(@types/react@19.3.0))(@types/react@19.3.0)(react-dom@19.2.8(react@19.2.8))(react@19.2.8) + '@radix-ui/react-use-callback-ref': 1.1.5(@types/react@19.3.0)(react@19.2.8) '@radix-ui/react-use-layout-effect': 1.1.4(@types/react@19.3.0)(react@19.2.8) '@radix-ui/react-use-rect': 1.1.4(@types/react@19.3.0)(react@19.2.8) - '@radix-ui/react-use-size': 1.1.4(@types/react@19.3.0)(react@19.2.8) + '@radix-ui/react-use-size': 1.1.5(@types/react@19.3.0)(react@19.2.8) '@radix-ui/rect': 1.1.3 react: 19.2.8 react-dom: 19.2.8(react@19.2.8) @@ -8596,9 +8610,9 @@ snapshots: '@types/react': 19.3.0 '@types/react-dom': 19.3.0(@types/react@19.3.0) - '@radix-ui/react-portal@1.1.17(@types/react-dom@19.3.0(@types/react@19.3.0))(@types/react@19.3.0)(react-dom@19.2.8(react@19.2.8))(react@19.2.8)': + '@radix-ui/react-portal@1.2.0(@types/react-dom@19.3.0(@types/react@19.3.0))(@types/react@19.3.0)(react-dom@19.2.8(react@19.2.8))(react@19.2.8)': dependencies: - '@radix-ui/react-primitive': 2.1.10(@types/react-dom@19.3.0(@types/react@19.3.0))(@types/react@19.3.0)(react-dom@19.2.8(react@19.2.8))(react@19.2.8) + '@radix-ui/react-primitive': 2.2.0(@types/react-dom@19.3.0(@types/react@19.3.0))(@types/react@19.3.0)(react-dom@19.2.8(react@19.2.8))(react@19.2.8) '@radix-ui/react-use-layout-effect': 1.1.4(@types/react@19.3.0)(react@19.2.8) react: 19.2.8 react-dom: 19.2.8(react@19.2.8) @@ -8606,7 +8620,7 @@ snapshots: '@types/react': 19.3.0 '@types/react-dom': 19.3.0(@types/react@19.3.0) - '@radix-ui/react-presence@1.1.10(@types/react-dom@19.3.0(@types/react@19.3.0))(@types/react@19.3.0)(react-dom@19.2.8(react@19.2.8))(react@19.2.8)': + '@radix-ui/react-presence@1.1.11(@types/react-dom@19.3.0(@types/react@19.3.0))(@types/react@19.3.0)(react-dom@19.2.8(react@19.2.8))(react@19.2.8)': dependencies: '@radix-ui/react-use-layout-effect': 1.1.4(@types/react@19.3.0)(react@19.2.8) react: 19.2.8 @@ -8615,26 +8629,26 @@ snapshots: '@types/react': 19.3.0 '@types/react-dom': 19.3.0(@types/react@19.3.0) - '@radix-ui/react-primitive@2.1.10(@types/react-dom@19.3.0(@types/react@19.3.0))(@types/react@19.3.0)(react-dom@19.2.8(react@19.2.8))(react@19.2.8)': + '@radix-ui/react-primitive@2.2.0(@types/react-dom@19.3.0(@types/react@19.3.0))(@types/react@19.3.0)(react-dom@19.2.8(react@19.2.8))(react@19.2.8)': dependencies: - '@radix-ui/react-slot': 1.3.3(@types/react@19.3.0)(react@19.2.8) + '@radix-ui/react-slot': 1.5.0(@types/react@19.3.0)(react@19.2.8) react: 19.2.8 react-dom: 19.2.8(react@19.2.8) optionalDependencies: '@types/react': 19.3.0 '@types/react-dom': 19.3.0(@types/react@19.3.0) - '@radix-ui/react-roving-focus@1.1.19(@types/react-dom@19.3.0(@types/react@19.3.0))(@types/react@19.3.0)(react-dom@19.2.8(react@19.2.8))(react@19.2.8)': + '@radix-ui/react-roving-focus@1.2.1(@types/react-dom@19.3.0(@types/react@19.3.0))(@types/react@19.3.0)(react-dom@19.2.8(react@19.2.8))(react@19.2.8)': dependencies: - '@radix-ui/primitive': 1.1.7 - '@radix-ui/react-collection': 1.1.15(@types/react-dom@19.3.0(@types/react@19.3.0))(@types/react@19.3.0)(react-dom@19.2.8(react@19.2.8))(react@19.2.8) + '@radix-ui/primitive': 1.2.0 + '@radix-ui/react-collection': 1.2.0(@types/react-dom@19.3.0(@types/react@19.3.0))(@types/react@19.3.0)(react-dom@19.2.8(react@19.2.8))(react@19.2.8) '@radix-ui/react-compose-refs': 1.1.5(@types/react@19.3.0)(react@19.2.8) - '@radix-ui/react-context': 1.2.2(@types/react@19.3.0)(react@19.2.8) - '@radix-ui/react-direction': 1.1.4(@types/react@19.3.0)(react@19.2.8) + '@radix-ui/react-context': 1.3.0(@types/react@19.3.0)(react@19.2.8) + '@radix-ui/react-direction': 1.2.0(@types/react@19.3.0)(react@19.2.8) '@radix-ui/react-id': 1.1.4(@types/react@19.3.0)(react@19.2.8) - '@radix-ui/react-primitive': 2.1.10(@types/react-dom@19.3.0(@types/react@19.3.0))(@types/react@19.3.0)(react-dom@19.2.8(react@19.2.8))(react@19.2.8) - '@radix-ui/react-use-callback-ref': 1.1.4(@types/react@19.3.0)(react@19.2.8) - '@radix-ui/react-use-controllable-state': 1.2.6(@types/react@19.3.0)(react@19.2.8) + '@radix-ui/react-primitive': 2.2.0(@types/react-dom@19.3.0(@types/react@19.3.0))(@types/react@19.3.0)(react-dom@19.2.8(react@19.2.8))(react@19.2.8) + '@radix-ui/react-use-callback-ref': 1.1.5(@types/react@19.3.0)(react@19.2.8) + '@radix-ui/react-use-controllable-state': 1.3.0(@types/react@19.3.0)(react@19.2.8) '@radix-ui/react-use-is-hydrated': 0.1.3(@types/react@19.3.0)(react@19.2.8) '@radix-ui/react-use-layout-effect': 1.1.4(@types/react@19.3.0)(react@19.2.8) react: 19.2.8 @@ -8643,16 +8657,17 @@ snapshots: '@types/react': 19.3.0 '@types/react-dom': 19.3.0(@types/react@19.3.0) - '@radix-ui/react-scroll-area@1.2.18(@types/react-dom@19.3.0(@types/react@19.3.0))(@types/react@19.3.0)(react-dom@19.2.8(react@19.2.8))(react@19.2.8)': + '@radix-ui/react-scroll-area@1.4.0(@types/react-dom@19.3.0(@types/react@19.3.0))(@types/react@19.3.0)(react-dom@19.2.8(react@19.2.8))(react@19.2.8)': dependencies: '@radix-ui/number': 1.1.3 - '@radix-ui/primitive': 1.1.7 + '@radix-ui/primitive': 1.2.0 '@radix-ui/react-compose-refs': 1.1.5(@types/react@19.3.0)(react@19.2.8) - '@radix-ui/react-context': 1.2.2(@types/react@19.3.0)(react@19.2.8) - '@radix-ui/react-direction': 1.1.4(@types/react@19.3.0)(react@19.2.8) - '@radix-ui/react-presence': 1.1.10(@types/react-dom@19.3.0(@types/react@19.3.0))(@types/react@19.3.0)(react-dom@19.2.8(react@19.2.8))(react@19.2.8) - '@radix-ui/react-primitive': 2.1.10(@types/react-dom@19.3.0(@types/react@19.3.0))(@types/react@19.3.0)(react-dom@19.2.8(react@19.2.8))(react@19.2.8) - '@radix-ui/react-use-callback-ref': 1.1.4(@types/react@19.3.0)(react@19.2.8) + '@radix-ui/react-context': 1.3.0(@types/react@19.3.0)(react@19.2.8) + '@radix-ui/react-direction': 1.2.0(@types/react@19.3.0)(react@19.2.8) + '@radix-ui/react-presence': 1.1.11(@types/react-dom@19.3.0(@types/react@19.3.0))(@types/react@19.3.0)(react-dom@19.2.8(react@19.2.8))(react@19.2.8) + '@radix-ui/react-primitive': 2.2.0(@types/react-dom@19.3.0(@types/react@19.3.0))(@types/react@19.3.0)(react-dom@19.2.8(react@19.2.8))(react@19.2.8) + '@radix-ui/react-slot': 1.5.0(@types/react@19.3.0)(react@19.2.8) + '@radix-ui/react-use-callback-ref': 1.1.5(@types/react@19.3.0)(react@19.2.8) '@radix-ui/react-use-layout-effect': 1.1.4(@types/react@19.3.0)(react@19.2.8) react: 19.2.8 react-dom: 19.2.8(react@19.2.8) @@ -8660,38 +8675,39 @@ snapshots: '@types/react': 19.3.0 '@types/react-dom': 19.3.0(@types/react@19.3.0) - '@radix-ui/react-slot@1.3.3(@types/react@19.3.0)(react@19.2.8)': + '@radix-ui/react-slot@1.5.0(@types/react@19.3.0)(react@19.2.8)': dependencies: '@radix-ui/react-compose-refs': 1.1.5(@types/react@19.3.0)(react@19.2.8) react: 19.2.8 optionalDependencies: '@types/react': 19.3.0 - '@radix-ui/react-tabs@1.1.21(@types/react-dom@19.3.0(@types/react@19.3.0))(@types/react@19.3.0)(react-dom@19.2.8(react@19.2.8))(react@19.2.8)': + '@radix-ui/react-tabs@1.2.1(@types/react-dom@19.3.0(@types/react@19.3.0))(@types/react@19.3.0)(react-dom@19.2.8(react@19.2.8))(react@19.2.8)': dependencies: - '@radix-ui/primitive': 1.1.7 - '@radix-ui/react-context': 1.2.2(@types/react@19.3.0)(react@19.2.8) - '@radix-ui/react-direction': 1.1.4(@types/react@19.3.0)(react@19.2.8) + '@radix-ui/primitive': 1.2.0 + '@radix-ui/react-context': 1.3.0(@types/react@19.3.0)(react@19.2.8) + '@radix-ui/react-direction': 1.2.0(@types/react@19.3.0)(react@19.2.8) '@radix-ui/react-id': 1.1.4(@types/react@19.3.0)(react@19.2.8) - '@radix-ui/react-presence': 1.1.10(@types/react-dom@19.3.0(@types/react@19.3.0))(@types/react@19.3.0)(react-dom@19.2.8(react@19.2.8))(react@19.2.8) - '@radix-ui/react-primitive': 2.1.10(@types/react-dom@19.3.0(@types/react@19.3.0))(@types/react@19.3.0)(react-dom@19.2.8(react@19.2.8))(react@19.2.8) - '@radix-ui/react-roving-focus': 1.1.19(@types/react-dom@19.3.0(@types/react@19.3.0))(@types/react@19.3.0)(react-dom@19.2.8(react@19.2.8))(react@19.2.8) - '@radix-ui/react-use-controllable-state': 1.2.6(@types/react@19.3.0)(react@19.2.8) + '@radix-ui/react-presence': 1.1.11(@types/react-dom@19.3.0(@types/react@19.3.0))(@types/react@19.3.0)(react-dom@19.2.8(react@19.2.8))(react@19.2.8) + '@radix-ui/react-primitive': 2.2.0(@types/react-dom@19.3.0(@types/react@19.3.0))(@types/react@19.3.0)(react-dom@19.2.8(react@19.2.8))(react@19.2.8) + '@radix-ui/react-roving-focus': 1.2.1(@types/react-dom@19.3.0(@types/react@19.3.0))(@types/react@19.3.0)(react-dom@19.2.8(react@19.2.8))(react@19.2.8) + '@radix-ui/react-use-controllable-state': 1.3.0(@types/react@19.3.0)(react@19.2.8) react: 19.2.8 react-dom: 19.2.8(react@19.2.8) optionalDependencies: '@types/react': 19.3.0 '@types/react-dom': 19.3.0(@types/react@19.3.0) - '@radix-ui/react-use-callback-ref@1.1.4(@types/react@19.3.0)(react@19.2.8)': + '@radix-ui/react-use-callback-ref@1.1.5(@types/react@19.3.0)(react@19.2.8)': dependencies: + '@radix-ui/react-use-layout-effect': 1.1.4(@types/react@19.3.0)(react@19.2.8) react: 19.2.8 optionalDependencies: '@types/react': 19.3.0 - '@radix-ui/react-use-controllable-state@1.2.6(@types/react@19.3.0)(react@19.2.8)': + '@radix-ui/react-use-controllable-state@1.3.0(@types/react@19.3.0)(react@19.2.8)': dependencies: - '@radix-ui/primitive': 1.1.7 + '@radix-ui/primitive': 1.2.0 '@radix-ui/react-use-effect-event': 0.0.5(@types/react@19.3.0)(react@19.2.8) '@radix-ui/react-use-layout-effect': 1.1.4(@types/react@19.3.0)(react@19.2.8) react: 19.2.8 @@ -8730,16 +8746,16 @@ snapshots: optionalDependencies: '@types/react': 19.3.0 - '@radix-ui/react-use-size@1.1.4(@types/react@19.3.0)(react@19.2.8)': + '@radix-ui/react-use-size@1.1.5(@types/react@19.3.0)(react@19.2.8)': dependencies: '@radix-ui/react-use-layout-effect': 1.1.4(@types/react@19.3.0)(react@19.2.8) react: 19.2.8 optionalDependencies: '@types/react': 19.3.0 - '@radix-ui/react-visually-hidden@1.2.11(@types/react-dom@19.3.0(@types/react@19.3.0))(@types/react@19.3.0)(react-dom@19.2.8(react@19.2.8))(react@19.2.8)': + '@radix-ui/react-visually-hidden@1.2.13(@types/react-dom@19.3.0(@types/react@19.3.0))(@types/react@19.3.0)(react-dom@19.2.8(react@19.2.8))(react@19.2.8)': dependencies: - '@radix-ui/react-primitive': 2.1.10(@types/react-dom@19.3.0(@types/react@19.3.0))(@types/react@19.3.0)(react-dom@19.2.8(react@19.2.8))(react@19.2.8) + '@radix-ui/react-primitive': 2.2.0(@types/react-dom@19.3.0(@types/react@19.3.0))(@types/react@19.3.0)(react-dom@19.2.8(react@19.2.8))(react@19.2.8) react: 19.2.8 react-dom: 19.2.8(react@19.2.8) optionalDependencies: @@ -8802,7 +8818,7 @@ snapshots: '@scalar/helpers@0.11.3': {} - '@scalar/helpers@0.12.0': {} + '@scalar/helpers@0.16.4': {} '@scalar/json-magic@0.13.4': dependencies: @@ -8810,19 +8826,19 @@ snapshots: pathe: 2.0.3 yaml: 2.9.1 - '@scalar/json-magic@0.13.5': + '@scalar/json-magic@0.16.1': dependencies: - '@scalar/helpers': 0.12.0 + '@scalar/helpers': 0.16.4 pathe: 2.0.3 - undici: 7.29.1 + undici: 7.30.1 yaml: 2.9.1 - '@scalar/openapi-types@0.9.6': {} + '@scalar/openapi-types@0.9.8': {} - '@scalar/openapi-upgrader@0.2.17': + '@scalar/openapi-upgrader@0.4.6': dependencies: - '@scalar/helpers': 0.12.0 - '@scalar/openapi-types': 0.9.6 + '@scalar/helpers': 0.16.4 + '@scalar/openapi-types': 0.9.8 '@sec-ant/readable-stream@0.4.1': {} @@ -8860,7 +8876,7 @@ snapshots: p-filter: 4.1.0 semantic-release: 25.0.3(@typescript/typescript6@6.0.2) tinyglobby: 0.2.17 - undici: 7.29.1 + undici: 7.30.1 url-join: 5.0.0 transitivePeerDependencies: - supports-color @@ -8898,45 +8914,45 @@ snapshots: transitivePeerDependencies: - supports-color - '@shikijs/core@4.5.0': + '@shikijs/core@4.6.0': dependencies: - '@shikijs/primitive': 4.5.0 - '@shikijs/types': 4.5.0 - '@shikijs/vscode-textmate': 10.0.2 + '@shikijs/primitive': 4.6.0 + '@shikijs/types': 4.6.0 + '@shikijs/vscode-textmate': 10.1.0 '@types/hast': 3.0.5 - hast-util-to-html: 9.0.5 + hast-util-to-html: 9.0.6 - '@shikijs/engine-javascript@4.5.0': + '@shikijs/engine-javascript@4.6.0': dependencies: - '@shikijs/types': 4.5.0 - '@shikijs/vscode-textmate': 10.0.2 + '@shikijs/types': 4.6.0 + '@shikijs/vscode-textmate': 10.1.0 oniguruma-to-es: 4.3.6 - '@shikijs/engine-oniguruma@4.5.0': + '@shikijs/engine-oniguruma@4.6.0': dependencies: - '@shikijs/types': 4.5.0 - '@shikijs/vscode-textmate': 10.0.2 + '@shikijs/types': 4.6.0 + '@shikijs/vscode-textmate': 10.1.0 - '@shikijs/langs@4.5.0': + '@shikijs/langs@4.6.0': dependencies: - '@shikijs/types': 4.5.0 + '@shikijs/types': 4.6.0 - '@shikijs/primitive@4.5.0': + '@shikijs/primitive@4.6.0': dependencies: - '@shikijs/types': 4.5.0 - '@shikijs/vscode-textmate': 10.0.2 + '@shikijs/types': 4.6.0 + '@shikijs/vscode-textmate': 10.1.0 '@types/hast': 3.0.5 - '@shikijs/themes@4.5.0': + '@shikijs/themes@4.6.0': dependencies: - '@shikijs/types': 4.5.0 + '@shikijs/types': 4.6.0 - '@shikijs/types@4.5.0': + '@shikijs/types@4.6.0': dependencies: - '@shikijs/vscode-textmate': 10.0.2 + '@shikijs/vscode-textmate': 10.1.0 '@types/hast': 3.0.5 - '@shikijs/vscode-textmate@10.0.2': {} + '@shikijs/vscode-textmate@10.1.0': {} '@simple-git/args-pathspec@1.0.3': {} @@ -9450,7 +9466,7 @@ snapshots: '@tanstack/store': 0.9.3 react: 19.2.8 react-dom: 19.2.8(react@19.2.8) - use-sync-external-store: 1.6.0(react@19.2.8) + use-sync-external-store: 1.7.0(react@19.2.8) '@tanstack/router-core@1.171.28': dependencies: @@ -10282,9 +10298,7 @@ snapshots: cn@0.2.6: {} - cn@0.3.3: {} - - cn@0.4.0: {} + cn@0.5.2: {} collapse-white-space@2.1.0: {} @@ -11047,10 +11061,10 @@ snapshots: hasown: 2.0.3 mime-types: 2.1.35 - framer-motion@14.1.0(react-dom@19.2.8(react@19.2.8))(react@19.2.8): + framer-motion@14.9.1(react-dom@19.2.8(react@19.2.8))(react@19.2.8): dependencies: - motion-dom: 14.1.0 - motion-utils: 14.1.0 + motion-dom: 14.9.1 + motion-utils: 14.7.0 tslib: 2.8.1 optionalDependencies: react: 19.2.8 @@ -11073,28 +11087,27 @@ snapshots: fsevents@2.3.3: optional: true - fumadocs-core@16.17.1(@mdx-js/mdx@3.1.1)(@tanstack/react-router@1.170.33(react-dom@19.2.8(react@19.2.8))(react@19.2.8))(@types/estree-jsx@1.0.5)(@types/hast@3.0.5)(@types/mdast@4.0.4)(@types/react@19.3.0)(lucide-react@1.54.0(@types/react@19.3.0)(react@19.2.8))(react-dom@19.2.8(react@19.2.8))(react@19.2.8)(zod@4.6.5): + fumadocs-core@16.18.0(@mdx-js/mdx@3.1.1)(@tanstack/react-router@1.170.33(react-dom@19.2.8(react@19.2.8))(react@19.2.8))(@types/estree-jsx@1.0.5)(@types/hast@3.0.5)(@types/mdast@4.0.4)(@types/react@19.3.0)(lucide-react@1.69.0(@types/react@19.3.0)(react@19.2.8))(react-dom@19.2.8(react@19.2.8))(react@19.2.8)(zod@4.6.5): dependencies: '@fumari/image-size': 0.1.1 estree-util-value-to-estree: 3.5.0 github-slugger: 2.0.0 hast-util-from-dom: 5.0.1 hast-util-to-estree: 3.1.3 - hast-util-to-jsx-runtime: 2.3.6 mdast-util-mdx: 3.0.0 - micromark: 4.0.2 + micromark: 4.0.3 micromark-extension-gfm-table: 2.1.2 npm-to-yarn: 3.2.0 remark: 15.0.1 remark-gfm: 4.0.1 remark-rehype: 11.1.2 scroll-into-view-if-needed: 3.1.0 - shiki: 4.5.0 + shiki: 4.6.0 tinyglobby: 0.2.17 unified: 11.0.5 vfile: 6.0.3 yaml: 2.9.1 - zbsearch: 4.0.1 + zbsearch: 4.0.2 optionalDependencies: '@mdx-js/mdx': 3.1.1 '@tanstack/react-router': 1.170.33(react-dom@19.2.8(react@19.2.8))(react@19.2.8) @@ -11102,21 +11115,21 @@ snapshots: '@types/hast': 3.0.5 '@types/mdast': 4.0.4 '@types/react': 19.3.0 - lucide-react: 1.54.0(@types/react@19.3.0)(react@19.2.8) + lucide-react: 1.69.0(@types/react@19.3.0)(react@19.2.8) react: 19.2.8 react-dom: 19.2.8(react@19.2.8) zod: 4.6.5 transitivePeerDependencies: - supports-color - fumadocs-mdx@15.4.7(@types/mdast@4.0.4)(@types/mdx@2.0.14)(@types/react@19.3.0)(fumadocs-core@16.17.1(@mdx-js/mdx@3.1.1)(@tanstack/react-router@1.170.33(react-dom@19.2.8(react@19.2.8))(react@19.2.8))(@types/estree-jsx@1.0.5)(@types/hast@3.0.5)(@types/mdast@4.0.4)(@types/react@19.3.0)(lucide-react@1.54.0(@types/react@19.3.0)(react@19.2.8))(react-dom@19.2.8(react@19.2.8))(react@19.2.8)(zod@4.6.5))(react@19.2.8)(rolldown@1.2.8)(vite@8.2.2(@types/node@22.14.1)(esbuild@0.28.2)(jiti@2.7.0)(tsx@4.21.0)(yaml@2.9.1)): + fumadocs-mdx@15.4.7(@types/mdast@4.0.4)(@types/mdx@2.0.14)(@types/react@19.3.0)(fumadocs-core@16.18.0(@mdx-js/mdx@3.1.1)(@tanstack/react-router@1.170.33(react-dom@19.2.8(react@19.2.8))(react@19.2.8))(@types/estree-jsx@1.0.5)(@types/hast@3.0.5)(@types/mdast@4.0.4)(@types/react@19.3.0)(lucide-react@1.69.0(@types/react@19.3.0)(react@19.2.8))(react-dom@19.2.8(react@19.2.8))(react@19.2.8)(zod@4.6.5))(react@19.2.8)(rolldown@1.2.8)(vite@8.2.2(@types/node@22.14.1)(esbuild@0.28.2)(jiti@2.7.0)(tsx@4.21.0)(yaml@2.9.1)): dependencies: '@mdx-js/mdx': 3.1.1 '@standard-schema/spec': 1.1.0 chokidar: 5.0.0 esbuild: 0.28.2 estree-util-value-to-estree: 3.5.0 - fumadocs-core: 16.17.1(@mdx-js/mdx@3.1.1)(@tanstack/react-router@1.170.33(react-dom@19.2.8(react@19.2.8))(react@19.2.8))(@types/estree-jsx@1.0.5)(@types/hast@3.0.5)(@types/mdast@4.0.4)(@types/react@19.3.0)(lucide-react@1.54.0(@types/react@19.3.0)(react@19.2.8))(react-dom@19.2.8(react@19.2.8))(react@19.2.8)(zod@4.6.5) + fumadocs-core: 16.18.0(@mdx-js/mdx@3.1.1)(@tanstack/react-router@1.170.33(react-dom@19.2.8(react@19.2.8))(react@19.2.8))(@types/estree-jsx@1.0.5)(@types/hast@3.0.5)(@types/mdast@4.0.4)(@types/react@19.3.0)(lucide-react@1.69.0(@types/react@19.3.0)(react@19.2.8))(react-dom@19.2.8(react@19.2.8))(react@19.2.8)(zod@4.6.5) github-slugger: 2.0.0 magic-string: 1.4.3 mdast-util-mdx: 3.0.0 @@ -11140,28 +11153,28 @@ snapshots: transitivePeerDependencies: - supports-color - fumadocs-openapi@12.1.1(@types/react@19.3.0)(fumadocs-core@16.17.1(@mdx-js/mdx@3.1.1)(@tanstack/react-router@1.170.33(react-dom@19.2.8(react@19.2.8))(react@19.2.8))(@types/estree-jsx@1.0.5)(@types/hast@3.0.5)(@types/mdast@4.0.4)(@types/react@19.3.0)(lucide-react@1.54.0(@types/react@19.3.0)(react@19.2.8))(react-dom@19.2.8(react@19.2.8))(react@19.2.8)(zod@4.6.5))(fumadocs-ui@16.17.1(@types/mdx@2.0.14)(@types/react-dom@19.3.0(@types/react@19.3.0))(@types/react@19.3.0)(fumadocs-core@16.17.1(@mdx-js/mdx@3.1.1)(@tanstack/react-router@1.170.33(react-dom@19.2.8(react@19.2.8))(react@19.2.8))(@types/estree-jsx@1.0.5)(@types/hast@3.0.5)(@types/mdast@4.0.4)(@types/react@19.3.0)(lucide-react@1.54.0(@types/react@19.3.0)(react@19.2.8))(react-dom@19.2.8(react@19.2.8))(react@19.2.8)(zod@4.6.5))(react-dom@19.2.8(react@19.2.8))(react@19.2.8)(tailwindcss@4.3.3))(react-dom@19.2.8(react@19.2.8))(react@19.2.8): + fumadocs-openapi@12.6.0(@types/react@19.3.0)(fumadocs-core@16.18.0(@mdx-js/mdx@3.1.1)(@tanstack/react-router@1.170.33(react-dom@19.2.8(react@19.2.8))(react@19.2.8))(@types/estree-jsx@1.0.5)(@types/hast@3.0.5)(@types/mdast@4.0.4)(@types/react@19.3.0)(lucide-react@1.69.0(@types/react@19.3.0)(react@19.2.8))(react-dom@19.2.8(react@19.2.8))(react@19.2.8)(zod@4.6.5))(fumadocs-ui@16.18.0(@types/mdx@2.0.14)(@types/react-dom@19.3.0(@types/react@19.3.0))(@types/react@19.3.0)(fumadocs-core@16.18.0(@mdx-js/mdx@3.1.1)(@tanstack/react-router@1.170.33(react-dom@19.2.8(react@19.2.8))(react@19.2.8))(@types/estree-jsx@1.0.5)(@types/hast@3.0.5)(@types/mdast@4.0.4)(@types/react@19.3.0)(lucide-react@1.69.0(@types/react@19.3.0)(react@19.2.8))(react-dom@19.2.8(react@19.2.8))(react@19.2.8)(zod@4.6.5))(react-dom@19.2.8(react@19.2.8))(react@19.2.8)(tailwindcss@4.3.3))(react-dom@19.2.8(react@19.2.8))(react@19.2.8): dependencies: - '@base-ui/react': 1.8.0(@types/react@19.3.0)(react-dom@19.2.8(react@19.2.8))(react@19.2.8) + '@base-ui/react': 1.9.0(@types/react@19.3.0)(react-dom@19.2.8(react@19.2.8))(react@19.2.8) '@fuma-translate/react': 1.0.2(@types/react@19.3.0)(react-dom@19.2.8(react@19.2.8))(react@19.2.8) - '@fumadocs/json-schema': 0.2.0(@types/react@19.3.0)(react-dom@19.2.8(react@19.2.8))(react@19.2.8) + '@fumadocs/json-schema': 0.3.5(@types/react@19.3.0)(react-dom@19.2.8(react@19.2.8))(react@19.2.8) '@fumari/json-schema-ts': 1.0.2 - '@fumari/stf': 1.1.1(@types/react@19.3.0)(react-dom@19.2.8(react@19.2.8))(react@19.2.8) - '@scalar/json-magic': 0.13.5 - '@scalar/openapi-upgrader': 0.2.17 + '@fumari/stf': 1.1.2(@types/react@19.3.0)(react-dom@19.2.8(react@19.2.8))(react@19.2.8) + '@scalar/json-magic': 0.16.1 + '@scalar/openapi-upgrader': 0.4.6 chokidar: 5.0.0 class-variance-authority: 0.7.1 - cn: 0.3.3 - fumadocs-core: 16.17.1(@mdx-js/mdx@3.1.1)(@tanstack/react-router@1.170.33(react-dom@19.2.8(react@19.2.8))(react@19.2.8))(@types/estree-jsx@1.0.5)(@types/hast@3.0.5)(@types/mdast@4.0.4)(@types/react@19.3.0)(lucide-react@1.54.0(@types/react@19.3.0)(react@19.2.8))(react-dom@19.2.8(react@19.2.8))(react@19.2.8)(zod@4.6.5) - fumadocs-ui: 16.17.1(@types/mdx@2.0.14)(@types/react-dom@19.3.0(@types/react@19.3.0))(@types/react@19.3.0)(fumadocs-core@16.17.1(@mdx-js/mdx@3.1.1)(@tanstack/react-router@1.170.33(react-dom@19.2.8(react@19.2.8))(react@19.2.8))(@types/estree-jsx@1.0.5)(@types/hast@3.0.5)(@types/mdast@4.0.4)(@types/react@19.3.0)(lucide-react@1.54.0(@types/react@19.3.0)(react@19.2.8))(react-dom@19.2.8(react@19.2.8))(react@19.2.8)(zod@4.6.5))(react-dom@19.2.8(react@19.2.8))(react@19.2.8)(tailwindcss@4.3.3) + cn: 0.5.2 + fumadocs-core: 16.18.0(@mdx-js/mdx@3.1.1)(@tanstack/react-router@1.170.33(react-dom@19.2.8(react@19.2.8))(react@19.2.8))(@types/estree-jsx@1.0.5)(@types/hast@3.0.5)(@types/mdast@4.0.4)(@types/react@19.3.0)(lucide-react@1.69.0(@types/react@19.3.0)(react@19.2.8))(react-dom@19.2.8(react@19.2.8))(react@19.2.8)(zod@4.6.5) + fumadocs-ui: 16.18.0(@types/mdx@2.0.14)(@types/react-dom@19.3.0(@types/react@19.3.0))(@types/react@19.3.0)(fumadocs-core@16.18.0(@mdx-js/mdx@3.1.1)(@tanstack/react-router@1.170.33(react-dom@19.2.8(react@19.2.8))(react@19.2.8))(@types/estree-jsx@1.0.5)(@types/hast@3.0.5)(@types/mdast@4.0.4)(@types/react@19.3.0)(lucide-react@1.69.0(@types/react@19.3.0)(react@19.2.8))(react-dom@19.2.8(react@19.2.8))(react@19.2.8)(zod@4.6.5))(react-dom@19.2.8(react@19.2.8))(react@19.2.8)(tailwindcss@4.3.3) github-slugger: 2.0.0 - hast-util-to-jsx-runtime: 2.3.6 - lucide-react: 1.54.0(@types/react@19.3.0)(react@19.2.8) + lucide-react: 1.69.0(@types/react@19.3.0)(react@19.2.8) react: 19.2.8 react-dom: 19.2.8(react@19.2.8) remark: 15.0.1 remark-rehype: 11.1.2 - shiki: 4.5.0 + shiki: 4.6.0 + undici: 7.30.1 yaml: 2.9.1 optionalDependencies: '@types/react': 19.3.0 @@ -11170,38 +11183,37 @@ snapshots: - date-fns - supports-color - fumadocs-ui@16.17.1(@types/mdx@2.0.14)(@types/react-dom@19.3.0(@types/react@19.3.0))(@types/react@19.3.0)(fumadocs-core@16.17.1(@mdx-js/mdx@3.1.1)(@tanstack/react-router@1.170.33(react-dom@19.2.8(react@19.2.8))(react@19.2.8))(@types/estree-jsx@1.0.5)(@types/hast@3.0.5)(@types/mdast@4.0.4)(@types/react@19.3.0)(lucide-react@1.54.0(@types/react@19.3.0)(react@19.2.8))(react-dom@19.2.8(react@19.2.8))(react@19.2.8)(zod@4.6.5))(react-dom@19.2.8(react@19.2.8))(react@19.2.8)(tailwindcss@4.3.3): + fumadocs-ui@16.18.0(@types/mdx@2.0.14)(@types/react-dom@19.3.0(@types/react@19.3.0))(@types/react@19.3.0)(fumadocs-core@16.18.0(@mdx-js/mdx@3.1.1)(@tanstack/react-router@1.170.33(react-dom@19.2.8(react@19.2.8))(react@19.2.8))(@types/estree-jsx@1.0.5)(@types/hast@3.0.5)(@types/mdast@4.0.4)(@types/react@19.3.0)(lucide-react@1.69.0(@types/react@19.3.0)(react@19.2.8))(react-dom@19.2.8(react@19.2.8))(react@19.2.8)(zod@4.6.5))(react-dom@19.2.8(react@19.2.8))(react@19.2.8)(tailwindcss@4.3.3): dependencies: '@fuma-translate/react': 1.0.2(@types/react@19.3.0)(react-dom@19.2.8(react@19.2.8))(react@19.2.8) - '@fumadocs/tailwind': 0.1.3(tailwindcss@4.3.3) - '@radix-ui/react-accordion': 1.2.20(@types/react-dom@19.3.0(@types/react@19.3.0))(@types/react@19.3.0)(react-dom@19.2.8(react@19.2.8))(react@19.2.8) - '@radix-ui/react-collapsible': 1.1.20(@types/react-dom@19.3.0(@types/react@19.3.0))(@types/react@19.3.0)(react-dom@19.2.8(react@19.2.8))(react@19.2.8) - '@radix-ui/react-dialog': 1.1.23(@types/react-dom@19.3.0(@types/react@19.3.0))(@types/react@19.3.0)(react-dom@19.2.8(react@19.2.8))(react@19.2.8) - '@radix-ui/react-direction': 1.1.4(@types/react@19.3.0)(react@19.2.8) - '@radix-ui/react-navigation-menu': 1.2.22(@types/react-dom@19.3.0(@types/react@19.3.0))(@types/react@19.3.0)(react-dom@19.2.8(react@19.2.8))(react@19.2.8) - '@radix-ui/react-popover': 1.1.23(@types/react-dom@19.3.0(@types/react@19.3.0))(@types/react@19.3.0)(react-dom@19.2.8(react@19.2.8))(react@19.2.8) - '@radix-ui/react-presence': 1.1.10(@types/react-dom@19.3.0(@types/react@19.3.0))(@types/react@19.3.0)(react-dom@19.2.8(react@19.2.8))(react@19.2.8) - '@radix-ui/react-scroll-area': 1.2.18(@types/react-dom@19.3.0(@types/react@19.3.0))(@types/react@19.3.0)(react-dom@19.2.8(react@19.2.8))(react@19.2.8) - '@radix-ui/react-slot': 1.3.3(@types/react@19.3.0)(react@19.2.8) - '@radix-ui/react-tabs': 1.1.21(@types/react-dom@19.3.0(@types/react@19.3.0))(@types/react@19.3.0)(react-dom@19.2.8(react@19.2.8))(react@19.2.8) + '@fumadocs/tailwind': 0.1.5(tailwindcss@4.3.3) + '@radix-ui/react-accordion': 1.3.1(@types/react-dom@19.3.0(@types/react@19.3.0))(@types/react@19.3.0)(react-dom@19.2.8(react@19.2.8))(react@19.2.8) + '@radix-ui/react-collapsible': 1.2.1(@types/react-dom@19.3.0(@types/react@19.3.0))(@types/react@19.3.0)(react-dom@19.2.8(react@19.2.8))(react@19.2.8) + '@radix-ui/react-dialog': 1.3.1(@types/react-dom@19.3.0(@types/react@19.3.0))(@types/react@19.3.0)(react-dom@19.2.8(react@19.2.8))(react@19.2.8) + '@radix-ui/react-direction': 1.2.0(@types/react@19.3.0)(react@19.2.8) + '@radix-ui/react-navigation-menu': 1.4.1(@types/react-dom@19.3.0(@types/react@19.3.0))(@types/react@19.3.0)(react-dom@19.2.8(react@19.2.8))(react@19.2.8) + '@radix-ui/react-popover': 1.3.1(@types/react-dom@19.3.0(@types/react@19.3.0))(@types/react@19.3.0)(react-dom@19.2.8(react@19.2.8))(react@19.2.8) + '@radix-ui/react-presence': 1.1.11(@types/react-dom@19.3.0(@types/react@19.3.0))(@types/react@19.3.0)(react-dom@19.2.8(react@19.2.8))(react@19.2.8) + '@radix-ui/react-scroll-area': 1.4.0(@types/react-dom@19.3.0(@types/react@19.3.0))(@types/react@19.3.0)(react-dom@19.2.8(react@19.2.8))(react@19.2.8) + '@radix-ui/react-slot': 1.5.0(@types/react@19.3.0)(react@19.2.8) + '@radix-ui/react-tabs': 1.2.1(@types/react-dom@19.3.0(@types/react@19.3.0))(@types/react@19.3.0)(react-dom@19.2.8(react@19.2.8))(react@19.2.8) class-variance-authority: 0.7.1 - cn: 0.4.0 - fumadocs-core: 16.17.1(@mdx-js/mdx@3.1.1)(@tanstack/react-router@1.170.33(react-dom@19.2.8(react@19.2.8))(react@19.2.8))(@types/estree-jsx@1.0.5)(@types/hast@3.0.5)(@types/mdast@4.0.4)(@types/react@19.3.0)(lucide-react@1.54.0(@types/react@19.3.0)(react@19.2.8))(react-dom@19.2.8(react@19.2.8))(react@19.2.8)(zod@4.6.5) - hast-util-to-jsx-runtime: 2.3.6 - lucide-react: 1.54.0(@types/react@19.3.0)(react@19.2.8) - motion: 14.1.0(react-dom@19.2.8(react@19.2.8))(react@19.2.8) + cn: 0.5.2 + fumadocs-core: 16.18.0(@mdx-js/mdx@3.1.1)(@tanstack/react-router@1.170.33(react-dom@19.2.8(react@19.2.8))(react@19.2.8))(@types/estree-jsx@1.0.5)(@types/hast@3.0.5)(@types/mdast@4.0.4)(@types/react@19.3.0)(lucide-react@1.69.0(@types/react@19.3.0)(react@19.2.8))(react-dom@19.2.8(react@19.2.8))(react@19.2.8)(zod@4.6.5) + lucide-react: 1.69.0(@types/react@19.3.0)(react@19.2.8) + motion: 14.9.1(react-dom@19.2.8(react@19.2.8))(react@19.2.8) next-themes: 0.4.6(react-dom@19.2.8(react@19.2.8))(react@19.2.8) react: 19.2.8 react-dom: 19.2.8(react@19.2.8) react-remove-scroll: 2.7.2(@types/react@19.3.0)(react@19.2.8) scroll-into-view-if-needed: 3.1.0 - shiki: 4.5.0 + shiki: 4.6.0 optionalDependencies: '@types/mdx': 2.0.14 '@types/react': 19.3.0 transitivePeerDependencies: - '@types/react-dom' - - supports-color + - remix - tailwindcss function-bind@1.1.2: {} @@ -11439,7 +11451,7 @@ snapshots: transitivePeerDependencies: - supports-color - hast-util-to-html@9.0.5: + hast-util-to-html@9.0.6: dependencies: '@types/hast': 3.0.5 '@types/unist': 3.0.3 @@ -12109,7 +12121,7 @@ snapshots: dependencies: yallist: 3.1.1 - lucide-react@1.54.0(@types/react@19.3.0)(react@19.2.8): + lucide-react@1.69.0(@types/react@19.3.0)(react@19.2.8): dependencies: react: 19.2.8 optionalDependencies: @@ -12170,7 +12182,7 @@ snapshots: decode-named-character-reference: 1.3.0 devlop: 1.1.0 mdast-util-to-string: 4.0.0 - micromark: 4.0.2 + micromark: 4.0.3 micromark-util-decode-numeric-character-reference: 2.0.2 micromark-util-decode-string: 2.0.1 micromark-util-normalize-identifier: 2.0.1 @@ -12528,6 +12540,10 @@ snapshots: micromark-util-decode-numeric-character-reference: 2.0.2 micromark-util-symbol: 2.0.1 + micromark-util-edit-map@1.0.0: + dependencies: + micromark-util-types: 2.0.3 + micromark-util-encode@2.0.1: {} micromark-util-events-to-acorn@2.0.3: @@ -12567,7 +12583,7 @@ snapshots: micromark-util-types@2.0.3: {} - micromark@4.0.2: + micromark@4.0.3: dependencies: '@types/debug': 4.1.13 debug: 4.4.3(supports-color@8.1.1) @@ -12579,6 +12595,7 @@ snapshots: micromark-util-chunked: 2.0.1 micromark-util-combine-extensions: 2.0.1 micromark-util-decode-numeric-character-reference: 2.0.2 + micromark-util-edit-map: 1.0.0 micromark-util-encode: 2.0.1 micromark-util-normalize-identifier: 2.0.1 micromark-util-resolve-all: 2.0.1 @@ -12654,15 +12671,15 @@ snapshots: yargs-parser: 21.1.1 yargs-unparser: 2.0.0 - motion-dom@14.1.0: + motion-dom@14.9.1: dependencies: - motion-utils: 14.1.0 + motion-utils: 14.7.0 - motion-utils@14.1.0: {} + motion-utils@14.7.0: {} - motion@14.1.0(react-dom@19.2.8(react@19.2.8))(react@19.2.8): + motion@14.9.1(react-dom@19.2.8(react@19.2.8))(react@19.2.8): dependencies: - framer-motion: 14.1.0(react-dom@19.2.8(react@19.2.8))(react@19.2.8) + framer-motion: 14.9.1(react-dom@19.2.8(react@19.2.8))(react@19.2.8) tslib: 2.8.1 optionalDependencies: react: 19.2.8 @@ -13518,15 +13535,15 @@ snapshots: shebang-regex@3.0.0: {} - shiki@4.5.0: + shiki@4.6.0: dependencies: - '@shikijs/core': 4.5.0 - '@shikijs/engine-javascript': 4.5.0 - '@shikijs/engine-oniguruma': 4.5.0 - '@shikijs/langs': 4.5.0 - '@shikijs/themes': 4.5.0 - '@shikijs/types': 4.5.0 - '@shikijs/vscode-textmate': 10.0.2 + '@shikijs/core': 4.6.0 + '@shikijs/engine-javascript': 4.6.0 + '@shikijs/engine-oniguruma': 4.6.0 + '@shikijs/langs': 4.6.0 + '@shikijs/themes': 4.6.0 + '@shikijs/types': 4.6.0 + '@shikijs/vscode-textmate': 10.1.0 '@types/hast': 3.0.5 side-channel-list@1.0.1: @@ -13979,7 +13996,7 @@ snapshots: undici@6.26.0: {} - undici@7.29.1: {} + undici@7.30.1: {} unicode-emoji-modifier-base@1.0.0: {} @@ -14086,7 +14103,7 @@ snapshots: optionalDependencies: '@types/react': 19.3.0 - use-sync-external-store@1.6.0(react@19.2.8): + use-sync-external-store@1.7.0(react@19.2.8): dependencies: react: 19.2.8 @@ -14342,7 +14359,7 @@ snapshots: '@yuku-core/binding-win32-arm64': 0.17.0 '@yuku-core/binding-win32-x64': 0.17.0 - zbsearch@4.0.1: {} + zbsearch@4.0.2: {} zod@4.6.5: {} diff --git a/pnpm-workspace.yaml b/pnpm-workspace.yaml index 7539a8192..4a7ea2993 100644 --- a/pnpm-workspace.yaml +++ b/pnpm-workspace.yaml @@ -17,5 +17,12 @@ overrides: '@oclif/core': "4.11.0" oclif: "4.17.34" browserslist: "4.24.4" - '@scalar/json-magic>undici': 7.29.1 + # fumadocs-openapi 12.6 asks for chokidar 6 (Node 22.22 and up) and undici 8 (22.19 and up), above + # the CLI's 22.14 floor, which fails CI's `--engine-strict` install. The CLI loads neither: chokidar + # serves `generateFiles()` in watch mode, undici the server proxy. Held at chokidar 5, which 12.5.0 + # shipped with, and at the patched undici 7.30.1 that @scalar/json-magic 0.16 pins as well. The + # overrides reach CI alone: `npm install -g` ignores them, prints an EBADENGINE warning for each of + # the two on Node 22.14, and installs all the same. + 'fumadocs-openapi>chokidar': ^5.0.0 + 'fumadocs-openapi>undici': 7.30.1 '@types/node': $@types/node diff --git a/portal-template/src/components/authorization-failure.tsx b/portal-template/src/components/authorization-failure.tsx index e77fcd9ad..d98741f05 100644 --- a/portal-template/src/components/authorization-failure.tsx +++ b/portal-template/src/components/authorization-failure.tsx @@ -22,7 +22,7 @@ export function AuthorizationFailure({ failure }: { failure: OAuthCallbackFailur <> This page completes an authorization started from an endpoint's playground, and none was started in this - browser. Open the endpoint's page and authorize from there. + tab. Open the endpoint's page and authorize from there. diff --git a/portal-template/src/lib/oauth-callback.ts b/portal-template/src/lib/oauth-callback.ts index a592192bb..cf8cf74df 100644 --- a/portal-template/src/lib/oauth-callback.ts +++ b/portal-template/src/lib/oauth-callback.ts @@ -5,9 +5,8 @@ */ export const oauthCallbackPath = '/oauth/callback'; -/** The cookie the playground writes before it leaves, naming the page that started the flow. */ -const PAGE_COOKIE_NAME = 'fumadocs-openapi-oauth'; -const PAGE_COOKIE = new RegExp(`(?:^|;\\s*)${PAGE_COOKIE_NAME}=([^;]+)`); +/** Where the playground notes the path of the page that started the flow before it leaves: this tab's session storage. */ +const STARTING_PAGE_KEY = 'fumadocs-openapi-oauth'; /** What the callback does with the browser that lands on it. */ export type OAuthCallback = @@ -15,9 +14,9 @@ export type OAuthCallback = | { kind: 'return'; url: string } /** Stays, to show the error the provider ended the authorization with, and a link back to that page. */ | { kind: 'providerError'; error: string; description: string | null; page: string } - /** Stays, since the cookie names no page: no authorization was started in this browser. */ + /** Stays, since no page is noted: no authorization was started in this tab. */ | { kind: 'notStarted' } - /** Stays, since the cookie names a page on another site, or one that cannot be read. */ + /** Stays, since the noted page is on another site, or cannot be read as an address. */ | { kind: 'unknownPage' }; /** Every outcome but sending the browser on, which leaves the callback before it renders again. */ @@ -25,16 +24,18 @@ export type OAuthCallbackFailure = Exclude; /** * The provider answers in the query for the authorization code flow and in the fragment for the - * implicit one, an error included. Only an authorization this browser started is answered with + * implicit one, an error included. Only an authorization this tab started is answered with * the provider's error: anyone can link here with an `error_description` of their own. */ -export function oauthCallback(cookie: string, location: Pick): OAuthCallback { - const value = PAGE_COOKIE.exec(cookie)?.[1]; - if (value === undefined) return { kind: 'notStarted' }; +export function oauthCallback( + startingPage: string | null, + location: Pick +): OAuthCallback { + if (startingPage === null) return { kind: 'notStarted' }; let page: URL; try { - page = new URL(decodeURIComponent(value), location.origin); + page = new URL(startingPage, location.origin); } catch { return { kind: 'unknownPage' }; } @@ -55,9 +56,12 @@ export function oauthCallback(cookie: string, location: Pick; +type PageOutput = Omit | Omit; /** Fumadocs' own page name with its spaces made hyphens, noting in `unsafe` what else it cannot hold. */ function pageName(this: PagesBuilder, output: PageOutput, unsafe: Set): string { @@ -107,7 +107,7 @@ type SectionFile = Awaited['staticSo * Fumadocs writes a page per tag an operation lists, in the tag's folder and named after the * operationId, so two pages land at one path, and one is left out without a word, when two * operations share an operationId (or have none, and paths that read alike), or when one - * operation lists a tag twice, or two tags that differ only in case or spacing. + * operation lists two tags that differ only in case or spacing. */ function refuseSharedPages(files: SectionFile[], specName: string): void { const pages = new Map(); @@ -191,16 +191,12 @@ function sameLocation(a: DocumentedOperation['location'], b: DocumentedOperation return a.in === b.in && a.key === b.key && a.method === b.method; } -/** One operation lands twice on a page when two of its tags name the page's folder. */ +/** + * One operation lands twice on a page when two of its tags name the page's folder. A tag listed + * twice is not one of them: Fumadocs writes one page for it, so each tag is named once. + */ function sharedTagFolderMessage(folder: string, operation: DocumentedOperation, specName: string): string { - const tags = operation.tags.filter((tag) => slugify(tag) === folder); - const repeated = tags.find((tag, index) => tags.indexOf(tag) !== index); - if (repeated !== undefined) { - return [ - `The operation ${operation.label} in '${specName}' lists the tag '${repeated}' more than once.`, - 'Remove the repeated tag.' - ].join('\n'); - } + const tags = [...new Set(operation.tags)].filter((tag) => slugify(tag) === folder); if (tags.length >= 2) { return [ `The operation ${operation.label} in '${specName}' lists the tags '${tags[0]}' and '${tags[1]}', which the portal shows as one section.`, diff --git a/portal-template/src/routes/oauth.callback.tsx b/portal-template/src/routes/oauth.callback.tsx index 4ced996a4..7a56c71cc 100644 --- a/portal-template/src/routes/oauth.callback.tsx +++ b/portal-template/src/routes/oauth.callback.tsx @@ -3,36 +3,42 @@ import { HomeLayout } from 'fumadocs-ui/layouts/home'; import { useEffect, useState } from 'react'; import { AuthorizationFailure } from '@/components/authorization-failure'; import { baseOptions } from '@/lib/layout.shared'; -import { forgetStartingPage, oauthCallback, type OAuthCallback, type OAuthCallbackFailure } from '@/lib/oauth-callback'; +import { oauthCallback, takeStartingPage, type OAuthCallback, type OAuthCallbackFailure } from '@/lib/oauth-callback'; import { portal } from '@/lib/portal'; // Published portals are static, so this page does in the browser what Fumadocs' // `createOAuthHandler()` route does on a server. export const Route = createFileRoute('/oauth/callback')({ - head: () => ({ meta: [{ title: `Authorization | ${portal.name}` }, { name: 'robots', content: 'noindex' }] }), + head: () => ({ + meta: [ + { title: `Authorization | ${portal.name}` }, + { name: 'robots', content: 'noindex' }, + // The provider's answer is in this page's address, which a referrer would carry on. + { name: 'referrer', content: 'no-referrer' } + ] + }), component: OAuthCallbackPage }); let completion: OAuthCallback | undefined; /** - * Reading the cookie and sending the browser on can each happen only once per page load, not - * once per mount: the StrictMode `portal serve` runs under mounts the page twice, and the second - * mount would find the cookie gone. The answer is kept, so a later mount in the same load, such - * as Back after leaving through the header, shows the same outcome. Every arrival from a provider - * is a new load. + * Reading the starting page and sending the browser on can each happen only once per page load, + * not once per mount: the StrictMode `portal serve` runs under mounts the page twice, and the + * second mount would find the note gone. The answer is kept, so a later mount in the same load, + * such as Back after leaving through the header, shows the same outcome. Every arrival from a + * provider is a new load. */ function completeAuthorization(): OAuthCallback { if (completion === undefined) { - completion = oauthCallback(document.cookie, window.location); - forgetStartingPage(); + completion = oauthCallback(takeStartingPage(), window.location); if (completion.kind === 'return') window.location.replace(completion.url); } return completion; } function OAuthCallbackPage() { - // Null until the effect has read the cookie, which the prerendered page cannot. + // Null until the effect has read the tab's session storage, which the prerendered page cannot. const [failure, setFailure] = useState(null); useEffect(() => { diff --git a/test/e2e/portal-build.test.ts b/test/e2e/portal-build.test.ts index 9550eec1f..3bf144d25 100644 --- a/test/e2e/portal-build.test.ts +++ b/test/e2e/portal-build.test.ts @@ -227,7 +227,9 @@ const stylesheetOf = (output: DirectoryPath) => { it('writes the one OAuth redirect URI every endpoint page authorizes through, kept out of search', () => { expect(read('oauth/callback/index.html')).to.contain(' { // Tailwind reads the template and the copy of the pages, and nothing else. A scan that missed the // template stacked the SDK cards; one that took in node_modules grew this from 93 KB to 134 KB. + // Fumadocs UI 16.18 and fumadocs-openapi 12.6 brought it to 119 KB with their own components. it('builds the stylesheet from the template and the pages alone', () => { const css = stylesheetOf(portal.output()); @@ -528,7 +531,7 @@ const stylesheetOf = (output: DirectoryPath) => { expect(css).to.contain('.\\@2xl\\:grid-cols-2'); expect(read('authentication/index.html')).to.contain('class="tracking-[0.3125em]"'); expect(css).to.contain('.tracking-\\[0\\.3125em\\]'); - expect(css.length).to.be.below(100 * 1024); + expect(css.length).to.be.below(128 * 1024); }); // The counterpart of the branded portal's forced mode: the same label, present here. @@ -877,7 +880,11 @@ const stylesheetOf = (output: DirectoryPath) => { const page = read('api/apimatic-calculator/simple-calculator/Calculate/index.html'); expect(page).to.match(/]* src="\/api\/images\/diagram\.png"/); - expect(page).to.match(/]*>\{ "calculated": 9 \}<\/span><\/code><\/pre>/); + // Highlighted, so the text is spread over spans: read as text, the block is what the description wrote. + const codeBlocks = (page.match(/]*>[\s\S]*?<\/code><\/pre>/g) ?? []).map((block) => + block.replace(/<[^>]+>/g, '') + ); + expect(codeBlocks).to.include('{ "calculated": 9 }'); }); // The dialog would load a result's image from the host's root, as Fumadocs prefixes none. diff --git a/test/portal-template/authorization-failure.test.ts b/test/portal-template/authorization-failure.test.ts index f54128a72..3b8ad6b98 100644 --- a/test/portal-template/authorization-failure.test.ts +++ b/test/portal-template/authorization-failure.test.ts @@ -83,11 +83,11 @@ describe('the OAuth callback when it cannot complete the authorization', functio expect(text).to.contain('The provider ended the authorization with server_error.'); }); - it('says no authorization was started in this browser, and leads to the home page', () => { + it('says no authorization was started in this tab, and leads to the home page', () => { expect(shown({ kind: 'notStarted' })).to.deep.equal({ text: "Authorization could not be completed This page completes an authorization started from an endpoint's playground, and none " + - "was started in this browser. Open the endpoint's page and authorize from there. Go to the home page", + "was started in this tab. Open the endpoint's page and authorize from there. Go to the home page", link: { label: 'Go to the home page', href: '/docs/' } }); }); diff --git a/test/portal-template/navigation.test.ts b/test/portal-template/navigation.test.ts index ad57857a6..e5631da8f 100644 --- a/test/portal-template/navigation.test.ts +++ b/test/portal-template/navigation.test.ts @@ -116,8 +116,9 @@ describe('navigationTransformer', () => { describe('a nav.json it cannot use', () => { // The CLI reports these, but under `portal serve` a half-typed file still reloads into the transformer. - it('leaves the order alone for a file that is null, a string or an array', () => { - for (const data of [null, 'hi', ['index']]) { + // Not `null`: Fumadocs' loader reads a metadata file's data itself before any transformer runs. + it('leaves the order alone for a file that is a string or an array', () => { + for (const data of ['hi', ['index']]) { const docs = [...CONTENT, { type: 'meta' as const, path: 'nav.json', data: data as never }]; expect(treeOf({ docs, openapi: API })).to.deep.equal(['Welcome', 'Authentication', 'API Reference']); diff --git a/test/portal-template/oauth-callback.test.ts b/test/portal-template/oauth-callback.test.ts index 35ff8ff12..a370e8dc1 100644 --- a/test/portal-template/oauth-callback.test.ts +++ b/test/portal-template/oauth-callback.test.ts @@ -1,5 +1,7 @@ import { expect } from 'chai'; -import { oauthCallback, oauthCallbackPath } from '../../portal-template/src/lib/oauth-callback'; +import type { SecuritySchemeObject } from 'fumadocs-openapi'; +import { requestOAuthToken } from 'fumadocs-openapi/playground'; +import { oauthCallback, oauthCallbackPath, takeStartingPage } from '../../portal-template/src/lib/oauth-callback'; import { OAUTH_CALLBACK_ADDRESS } from '../../src/types/portal/content-tree'; // The CLI refuses a page of the user's at the address the template serves the callback at. @@ -9,13 +11,82 @@ describe('oauthCallbackPath', () => { }); }); +/** + * The playground notes the page under a key of its own before it leaves for the provider, and the + * callback takes the note from the same place. The playground's flow is run here, in a stand-in + * tab, so a move of the note, as 12.5.7 made from a cookie, fails this test and not a portal. + */ +describe('takeStartingPage', () => { + const origin = 'https://docs.test'; + const pathname = '/api/pets/pets/listPets'; + const scheme: SecuritySchemeObject = { + type: 'oauth2', + flows: { + authorizationCode: { + authorizationUrl: 'https://provider.test/authorize', + tokenUrl: 'https://provider.test/token', + scopes: {} + } + } + }; + // As the template starts a flow: the callback page as the redirect URL, see `api-page.tsx`. + const flow = { + schemeId: 'oauth', + scopes: [], + clientId: 'client', + serverUrl: 'https://api.test', + redirectUrl: oauthCallbackPath + }; + + const tab = globalThis as Record; + const before: Record = {}; + let storage: Map; + let leftFor: URL | undefined; + + beforeEach(() => { + storage = new Map(); + leftFor = undefined; + for (const name of ['sessionStorage', 'window']) before[name] = tab[name]; + tab.sessionStorage = { + getItem: (key: string) => storage.get(key) ?? null, + setItem: (key: string, value: string) => void storage.set(key, value), + removeItem: (key: string) => void storage.delete(key) + }; + tab.window = { location: { origin, pathname, replace: (url: URL) => void (leftFor = url) } }; + }); + + afterEach(() => { + for (const name of ['sessionStorage', 'window']) { + if (before[name] === undefined) delete tab[name]; + else tab[name] = before[name]; + } + }); + + it("sends the provider's answer back to the page the playground noted before it left", async () => { + await requestOAuthToken(scheme, 'authorizationCode', flow); + expect(leftFor?.origin, 'left for the provider').to.equal('https://provider.test'); + expect(leftFor?.searchParams.get('redirect_uri')).to.equal(`${origin}${oauthCallbackPath}`); + const state = leftFor?.searchParams.get('state'); + + const callback = oauthCallback(takeStartingPage(), { origin, search: `?code=abc&state=${state}`, hash: '' }); + + expect(callback).to.deep.equal({ kind: 'return', url: `${origin}${pathname}?code=abc&state=${state}` }); + }); + + it('takes the note once', async () => { + await requestOAuthToken(scheme, 'authorizationCode', flow); + + expect(takeStartingPage()).to.equal(pathname); + expect(takeStartingPage()).to.equal(null); + }); +}); + describe('oauthCallback', () => { const origin = 'https://docs.test'; - const pageCookie = (path: string) => `theme=dark; fumadocs-openapi-oauth=${encodeURIComponent(path)}`; const answered = (search: string, hash = '') => ({ origin, search, hash }); it("sends the authorization code back to the page that started the flow, in the provider's query", () => { - const callback = oauthCallback(pageCookie('/api/pets/pets/listPets'), answered('?code=abc&state=123')); + const callback = oauthCallback('/api/pets/pets/listPets', answered('?code=abc&state=123')); expect(callback).to.deep.equal({ kind: 'return', @@ -25,7 +96,7 @@ describe('oauthCallback', () => { // The implicit flow answers in the fragment, which a browser never sends to a server either. it("sends the implicit flow's token back in the provider's fragment", () => { - const callback = oauthCallback(pageCookie('/api/pets/pets/listPets'), answered('', '#access_token=xyz&state=123')); + const callback = oauthCallback('/api/pets/pets/listPets', answered('', '#access_token=xyz&state=123')); expect(callback).to.deep.equal({ kind: 'return', @@ -33,18 +104,16 @@ describe('oauthCallback', () => { }); }); - it('keeps an encoded page address as the page wrote it', () => { - const callback = oauthCallback(pageCookie('/api/pets/Get%20Pets'), answered('?code=abc')); + // The playground notes `location.pathname`, which the browser has already percent-encoded. + it('keeps an encoded page path as the playground wrote it', () => { + const callback = oauthCallback('/api/pets/Get%20Pets', answered('?code=abc')); expect(callback).to.deep.equal({ kind: 'return', url: 'https://docs.test/api/pets/Get%20Pets?code=abc' }); }); // As a bare path, `//evil.test/x?code=abc` would send the code to evil.test. it('keeps the code on this site for a page whose path reads as another site', () => { - const callback = oauthCallback( - pageCookie('https://docs.test//evil.test/x'), - answered('?code=abc', '#access_token=xyz') - ); + const callback = oauthCallback('https://docs.test//evil.test/x', answered('?code=abc', '#access_token=xyz')); expect(callback).to.deep.equal({ kind: 'return', url: 'https://docs.test//evil.test/x?code=abc#access_token=xyz' }); }); @@ -52,7 +121,7 @@ describe('oauthCallback', () => { // The playground's own return handling finds no code or token in it, and says nothing. it("stays to show the provider's error, in the query, with a way back to the page", () => { const callback = oauthCallback( - pageCookie('/api/pets/listPets'), + '/api/pets/listPets', answered('?error=access_denied&error_description=The+user+said+no&state=123') ); @@ -65,7 +134,7 @@ describe('oauthCallback', () => { }); it("stays to show the implicit flow's error, in the fragment, without a description it was not given", () => { - const callback = oauthCallback(pageCookie('/api/pets/listPets'), answered('', '#error=access_denied&state=123')); + const callback = oauthCallback('/api/pets/listPets', answered('', '#error=access_denied&state=123')); expect(callback).to.deep.equal({ kind: 'providerError', @@ -75,27 +144,21 @@ describe('oauthCallback', () => { }); }); - it('says no authorization was started without the cookie', () => { - expect(oauthCallback('theme=dark', answered('?code=abc'))).to.deep.equal({ kind: 'notStarted' }); - expect(oauthCallback('', answered('?code=abc'))).to.deep.equal({ kind: 'notStarted' }); + it('says no authorization was started without a noted page', () => { + expect(oauthCallback(null, answered('?code=abc'))).to.deep.equal({ kind: 'notStarted' }); }); - // Anyone can link here, so an error and its description are only shown for an authorization this browser started. - it("shows no provider's error for an authorization this browser did not start", () => { - const callback = oauthCallback('', answered('?error=access_denied&error_description=Call+this+number')); + // Anyone can link here, so an error and its description are only shown for an authorization this tab started. + it("shows no provider's error for an authorization this tab did not start", () => { + const callback = oauthCallback(null, answered('?error=access_denied&error_description=Call+this+number')); expect(callback).to.deep.equal({ kind: 'notStarted' }); }); - it('refuses to send the code to another site', () => { - for (const page of ['https://evil.test/steal', '//evil.test/steal']) { - expect(oauthCallback(pageCookie(page), answered('?code=abc')), page).to.deep.equal({ kind: 'unknownPage' }); + // The last is the path of a page at `//a b/x`, which does not read as an address at all. + it('refuses to send the code to another site, or to a page that does not read as one', () => { + for (const page of ['https://evil.test/steal', '//evil.test/steal', '//a%20b/x']) { + expect(oauthCallback(page, answered('?code=abc')), page).to.deep.equal({ kind: 'unknownPage' }); } }); - - it('refuses a cookie that is not encoded the way the playground writes it', () => { - const callback = oauthCallback('fumadocs-openapi-oauth=%E0%A4%A', answered('?code=abc')); - - expect(callback).to.deep.equal({ kind: 'unknownPage' }); - }); }); diff --git a/test/portal-template/openapi-section.test.ts b/test/portal-template/openapi-section.test.ts index dd5fca1aa..fa63a0b41 100644 --- a/test/portal-template/openapi-section.test.ts +++ b/test/portal-template/openapi-section.test.ts @@ -501,15 +501,11 @@ describe('openApiSection', () => { ); }); - // Fumadocs writes a page for each tag an operation lists, the same one twice included. - it('refuses an operation that lists one tag twice, naming the tag', async () => { + // Fumadocs writes one page for the operation however often it repeats a tag, so there is nothing to refuse. + it('documents an operation that lists one tag twice on one page', async () => { expect( - await failureFor({ '/pets': { post: { operationId: 'createPet', tags: ['pets', 'pets'], responses: ok } } }) - ).to.equal( - ["The operation POST /pets in 'api.json' lists the tag 'pets' more than once.", 'Remove the repeated tag.'].join( - '\n' - ) - ); + await pagesFor({ '/pets': { post: { operationId: 'createPet', tags: ['pets', 'pets'], responses: ok } } }) + ).to.deep.equal(['api/pets/pets/createPet.mdx']); }); // A tag's folder is its slug, so these two tags share one; the repeated 'x' has a folder of its own. @@ -526,6 +522,20 @@ describe('openApiSection', () => { ); }); + // Fumadocs writes one page for the repeated 'pets', so the collision is with 'Pets', and the message names each once. + it('names a repeated tag once, against the one it collides with', async () => { + expect( + await failureFor({ + '/pets': { post: { operationId: 'createPet', tags: ['pets', 'pets', 'Pets'], responses: ok } } + }) + ).to.equal( + [ + "The operation POST /pets in 'api.json' lists the tags 'pets' and 'Pets', which the portal shows as one section.", + 'Rename one of them so they differ in more than case or spacing.' + ].join('\n') + ); + }); + /** The pages a section builds for these paths. */ const pagesFor = async (paths: Record, extra: Record = {}) => { writeSpec(paths, extra); diff --git a/test/portal-template/request-examples.test.ts b/test/portal-template/request-examples.test.ts index 209e90651..5fa26c0b2 100644 --- a/test/portal-template/request-examples.test.ts +++ b/test/portal-template/request-examples.test.ts @@ -1,6 +1,5 @@ import { expect } from 'chai'; -import type { ParameterObject } from 'fumadocs-openapi'; -import type { OperationParameters } from 'fumadocs-openapi/operation'; +import type { OperationParameter, OperationParameters } from 'fumadocs-openapi/operation'; import { Parameter, requestExamples, type RequestExample } from '../../portal-template/src/lib/request-examples'; type Location = OperationParameters['in']; @@ -8,7 +7,7 @@ type Location = OperationParameters['in']; const example = (id: string): RequestExample => ({ id, name: id }); // Fumadocs groups an operation's parameters by location. -const group = (location: Location, item: Omit): OperationParameters => ({ +const group = (location: Location, item: Omit): OperationParameters => ({ in: location, items: [{ ...item, in: location }] }); From e62f58481ebd28a9a907f45ac21347e237d69bb8 Mon Sep 17 00:00:00 2001 From: Wasif Israr <50007050+WasifIsrar@users.noreply.github.com> Date: Fri, 13 Nov 2026 14:11:32 +0500 Subject: [PATCH 2/5] ci: add functional tests step (#475) --- .github/workflows/portal_tests.yml | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) diff --git a/.github/workflows/portal_tests.yml b/.github/workflows/portal_tests.yml index 7792d5e26..3dc440cff 100644 --- a/.github/workflows/portal_tests.yml +++ b/.github/workflows/portal_tests.yml @@ -210,6 +210,28 @@ jobs: PLAYWRIGHT_BROWSERS_PATH: ${{ github.workspace }}\.playwright-browsers run: pnpm test:functional + # Functional against the suite's petstore build: server selection, server + # variables and request parameters on the playground + # (tests/functional/petstore/). The tests intercept their own calls, so + # this needs no API Tester and no secrets beyond generation. + - name: generate the petstore portal + id: generate-petstore + if: ${{ !cancelled() }} + working-directory: tests + env: + PORTAL: petstore + run: pnpm portal:generate + + - name: functional — petstore + if: ${{ !cancelled() && steps.generate-petstore.outcome == 'success' }} + working-directory: tests + shell: bash + env: + PORTAL: petstore + PORTAL_PREBUILT: '1' + PLAYWRIGHT_BROWSERS_PATH: ${{ github.workspace }}\.playwright-browsers + run: pnpm test:functional + - name: upload playwright report if: ${{ !cancelled() }} uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4 From 6e4b2156b432f81f2c62693ddf755369b6bd99ba Mon Sep 17 00:00:00 2001 From: Muhammad Sohail <62895181+sohail2721@users.noreply.github.com> Date: Mon, 16 Nov 2026 15:01:44 +0500 Subject: [PATCH 3/5] feat(portal): load Google Tag Manager and GA4 from portal.analytics (#473) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit PR 1 of apimatic/apimatic-io#2348, with PR 3 (the other seven events) following in this same PR since 2026-11-12, so GA4 and GTM can be tested with every event before anything merges. PR 1: `portal.analytics` loads Google Tag Manager and GA4 from `apimatic.json`, and the template reports each page view once as `docs_page_view`. The detail and the code sketches are in apimatic/apimatic-io#2349. The build plan and the docs draft are kept out of the repository, so the squash brings neither into `dev`. Draft until the gate: `pnpm test` green, the manual list in apimatic/apimatic-io#2349 ("Manual, on a test portal") checked, and each of PR 3's events seen once in GTM Preview with all of its keys. The squash title then covers both: `feat(portal): load Google Tag Manager and GA4 from portal.analytics and report the portal events`. ## What is on the branch Read it from the entry point down. - **The root route** (`portal-template/src/routes/__root.tsx`) reports the first page's view on mount and one per `onRendered`; `head()` lists no script, and writes the `google-site-verification` meta when the identity file holds a value. - **The API page** (`portal-template/src/components/api-page.tsx`) renders the playground's header inside one element carrying the opt-out markers of the session replay tools a GTM tag may load (PostHog, FullStory, rrweb, Amplitude, Hotjar, Clarity, LogRocket) and the `data-portal-playground` test hook, with Fumadocs' endpoint bar while the playground's chunk loads. The cURL sample carries the same markers, since it follows what the reader types. The client is lazy-loaded from Fumadocs' public export, as Fumadocs itself loads it. - **The bundle's start** (`portal-template/src/lib/portal-analytics.ts`) runs at module evaluation, before React and before any vendor tag, never during prerendering: first `markPlaygroundDialogs()` (`lib/replay-markers.ts`), one observer that marks the playground's dialog as Fumadocs adds it, ahead of any replay tool's observer (until fuma-nama/fumadocs#3824 takes the markers itself), then `new Analytics(portal.analytics).start()`. - **The module** (`portal-template/src/lib/analytics.ts`) holds the event table and the `Analytics` class: `start()` creates `window.dataLayer`, pushes every vendor's setup entries and inserts the tags, once per page load, and under `portal serve` reloads the page when a config save changes the vendors; `report()` adds the cleaned `page_location` (`pageLocation()`), pushes `{ docs: null }` then `{ event, docs }`, and calls each adapter that sends for itself; `reportPageView()` and `reportNotFound()` keep the page history the two events need, and the not-found page reports only once the router has settled on it (`components/not-found.tsx`), so leaving it reports nothing for the page the reader goes to. Nothing is reported on `/oauth/callback`, and the tags wait while the address holds an OAuth answer (`holdsOAuthAnswer()` in `lib/oauth-callback.ts`): on the callback, and on the page a sign-in returns to until the playground has taken the answer out, which loads them (`analytics.loadTags()` from `components/playground.tsx`). - **The vendors** (`portal-template/src/lib/vendor-tags.ts`): the `adapters` registry is keyed by both vendors, so a vendor without an adapter does not compile. GTM pushes `gtm.start` and loads `gtm.js` (with the `environment` suffix when set), and reads the data layer itself. GA4 defines `window.gtag` only when missing, pushes `js` and `config` with `send_page_view: false`, loads `gtag/js`, sends each event under GA4's own name, and sets `page_location` on each page view, so GA4's own scroll and click events carry the cleaned address too. `insertTags()` appends each tag once, none while the address holds an OAuth answer. - **The reporters**: code copies report from each block's own copy button (`components/code-copy.tsx`, through Fumadocs' `Actions` slot) with the block's language ID, the IDs SDK downloads send too (`csharp`, `shellscript`), both through `languageId()`, which reads a name in lowercase and knows the common short names of languages outside the bundle (`kt` is `kotlin`), so one language is one value; MDX blocks get theirs at build time (`lib/transformer-language.ts`), the API reference's at render, and "Example Response", whose button Fumadocs keeps to itself, through a click handler on its card. The playground times its requests in a ref of its own and reports each result once (`components/playground.tsx`, `lib/api-request.ts`). The search dialog's report is `searchOutcome()` (`lib/search-report.ts`): the result picked goes out as a whole address in the form of `page_location`, and the term at most 100 characters long, which is what GA4 keeps. - **The shared type** (`portal-template/src/lib/portal-types.ts`, `PortalIdentity` in `src/types/portal/portal-config.ts`) carries `analytics` and `seo`, filled by `AnalyticsConfig` and `SeoConfig` from the `portal` block, with #2348's messages less its format rules: an ID, an environment value, the verification token and a kept name are any non-empty string, and no name is refused (decided 2026-11-12, to record in #2347); `portal generate` and `portal serve` warn when GA4 is set. - **The flag** (`--no-analytics` on `portal generate` and `portal serve`, defined once in `FlagsProvider`) reaches the actions as `PortalBuildOptions`, and `PortalSourceContext` applies it where the settings are read, for a build and for each config save under `portal serve`: both vendors are dropped, the kept query names stay. The options have no default, so every caller chooses. `portal serve` loads exactly what a hosted portal loads: no debug mode, no preview distinction, so the sketched `PortalDelivery` is not built (decided 2026-11-12, to record in #2347). - **The schema** (`apimatic.schema.json`) describes both blocks with no pattern, as the parser reads them; the schema test holds the two to one verdict per case. - **The end-to-end proof** (`test/e2e/portal-build.test.ts`, behind `APIMATIC_E2E=1`) builds the default fixture with both vendors and a verification value set: the IDs sit in a browser script, no prerendered page names the tag host, every page carries the meta, and the operation page holds the playground's prerendered header and the cURL sample each inside an element replays skip, and the copy button of "Example Response" as the `button[aria-live]` its copies are reported by, so a Fumadocs update that changes either fails here. `test/commands/portal/*-flags.test.ts` run both commands to see the flag reach the settings reader. Steps, as the plan numbers them: 1.1 the pure functions, 1.2 adapters and page views, 1.3 the loader's wait (built, then removed, see below), 1.4 the bundle wiring, 1.5 the verification meta and the playground out of replays, 1.6 the parser and the GA4 warning, 1.7 `--no-analytics`, 1.8 the schema, 1.9 the end-to-end proof, 1.10 README and docs. PR 1 is complete. In this PR, PR 3: 3.1 the three click reporters, 3.2 `docs_code_copy`, 3.3 `docs_search`, 3.4 `docs_not_found`, 3.5 `docs_api_request`, 3.6 the docs (done). PR 1 and PR 3 are complete; the gate below is what remains. PR 2 (`portal.scripts`) follows in its own PR. ## Before merging - [x] **No vendor tag reads an OAuth answer from the address** (`1bb6dfbb`): with 12.6.0 the playground reads a returned sign-in's answer from the address, so the tags wait until Fumadocs has taken it out, and an answer nothing takes out waits for the next page. Seen in headless Chrome against `portal serve` with both vendors: no tag at `#access_token=…&state=…`, both once the address was clean, and no GA4 hit carrying the token. - [ ] **Later, not a merge gate: take fumadocs-openapi 12.6.2 and have the callback hand the answer over as Fumadocs' `createOAuthHandler()` does**, so the answer never reaches the address at all. After a playground sign-in the provider lands on `/oauth/callback`, and our own callback copies its query and `#` part (`?code=…&state=…` or `#access_token=…`) onto the starting page, where the vendor tags read the address for themselves; the portal's own events are clean, since `pageLocation()` strips both. 12.6.2's `getReturnedFlow()` reads the answer from `sessionStorage` under `fumadocs-openapi-oauth-returned` and falls back to the address; 12.6.0 reads the address only, so the callback cannot store it there before the bump. With the bump: `oauthCallback()` returns the bare starting page and the route stores `location.href` under that key, with `test/portal-template/oauth-callback.test.ts` and the comment at `oauth-callback.ts:20` following. `dev` pins 12.6.0 since #472 merged on 2026-11-12, under the seven-day release-age rule in `pnpm-workspace.yaml`; 12.6.2 clears it on 2026-11-19, and this branch takes it then. The 5-second wait that held the tags back (step 1.3, commit `1c616d56`) was removed on 2026-11-12. - [ ] **Release together with PR 2 (`portal.scripts`).** PR 2 makes `--no-analytics` also leave out the `analytics` and `marketing` scripts, and updates the flag's help. Released alone, this PR would have the flag drop more in a later release than it does in this one. - [ ] **Follow-up, not a merge gate: a browser smoke test in apimatic/v4-test-automation**, from the Playwright scripts of the review of 2026-11-16: each of the eight events once with its keys, and leaving the not-found page. The components that report are not unit-tested, and they lean on Fumadocs' markup, storage keys and render order; what guards them here is the pinned event table, `searchOutcome()`, `apiRequest()` and the built-page checks. - [ ] **The manual list in apimatic/apimatic-io#2349** ("Manual, on a test portal with GTM Preview and GA4 DebugView"), with no debug mode: DebugView needs Tag Assistant or the Google Analytics Debugger extension on the test browser. - [ ] **Each of the eight events once in GTM Preview, with all of its keys**, as the docs draft's table lists them: a page view, a Markdown copy, an install copy (one `docs_plugin_install`, no `docs_code_copy`), an SDK download, a code copy from a page's block, the API reference's cURL sample and "Example Response", each with its language ID, a search with a pick and one without, a reopen without typing (nothing), a broken portal link (`docs_not_found` with the page left, plus its page view), and a playground request with a response and one that fails (`client_error`), with `docs_api_request` never carrying the request address. - [ ] **The "Done when" lines in apimatic/apimatic-io#2348** for loading, counting, nothing private, verification and events. ## Base Was stacked on #472 (fumadocs-openapi 12.6) while it was open, as the plan's section 3 says, so the diff showed only this work. #472 merged on 2026-11-12 as `f7fe7dff`, and this branch was rebased onto `dev` and retargeted the same day. An end-to-end run on 2026-11-13 (headless Chrome against `portal serve` and a built portal, with a real GA4 property) saw seven of the eight events arrive once each with their keys, and the playground dialog marked in the browser; the plugin event needs a project with a `plugin` block. It also found the first page view in `portal serve` carrying the site name as its title, fixed in `__root.tsx` by reporting directly only when the router is idle at mount. Decisions on record: the e2e list's "a `--no-analytics` build holds no ID" check is not in `test/e2e/portal-build.test.ts`; `test/infrastructure/portal-project-service.test.ts` checks the identity file written from a config without vendors instead, which saves a full build in CI (plan step 1.9). The code review of 2026-11-13 and the reviewer's findings of the same day are addressed from `be8cc928` on; the review of 2026-11-13 requesting changes from `09a22ba3` to `96885d4d`, with the OAuth return page in `1bb6dfbb`, but for a playground result that arrives after the reader closed the dialog, which Fumadocs gives no callback for in 12.6.0 or 12.6.2. The review of 2026-11-16 is addressed from `f54b30ef` to `02200bbc`, and settled four things customers will build on. The event names and keys are pinned by a test, as plain text apart from the interface, so a rename is a change made there on purpose. `status` stays one text value, the HTTP status as digits or `client_error`. A search's `result` is a whole address in the form of `page_location`. `ref` left the built-in kept names: no platform reads it from the address, sites use it for codes of their own, and a customer can add a name through `keepQueryParams` but cannot take one out. The same review found the not-found page reporting `docs_not_found` for the page a reader left it for; fixed, and seen in headless Chrome on a served and a built portal. 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Muhammad Sohail Co-authored-by: Claude Fable 5.1 --- README.md | 6 +- apimatic.schema.json | 73 ++ portal-pages/sdk.mdx | 2 +- .../src/components/api-markdown.tsx | 4 +- portal-template/src/components/api-page.tsx | 18 +- portal-template/src/components/code-copy.tsx | 34 + .../src/components/command-block.tsx | 11 +- .../src/components/endpoint-bar.tsx | 35 + .../src/components/example-layout.tsx | 12 +- .../src/components/markdown-copy-button.tsx | 6 +- portal-template/src/components/mdx.tsx | 11 + portal-template/src/components/not-found.tsx | 12 + portal-template/src/components/playground.tsx | 49 ++ .../src/components/plugin-install.tsx | 5 +- .../src/components/sdk-actions.tsx | 19 +- portal-template/src/components/sdk-cards.tsx | 10 +- portal-template/src/components/search.tsx | 51 +- portal-template/src/components/usage-tabs.tsx | 9 +- portal-template/src/lib/analytics.ts | 126 +++ portal-template/src/lib/api-request.ts | 15 + portal-template/src/lib/code-titles.ts | 3 +- portal-template/src/lib/languages.ts | 99 +++ portal-template/src/lib/oauth-callback.ts | 17 + portal-template/src/lib/portal-analytics.ts | 10 + portal-template/src/lib/portal-types.ts | 28 + portal-template/src/lib/rehype-code-titles.ts | 2 +- portal-template/src/lib/replay-markers.ts | 28 + portal-template/src/lib/search-report.ts | 28 + portal-template/src/lib/shiki-bundle.ts | 44 +- portal-template/src/lib/source.ts | 4 +- .../src/lib/transformer-language.ts | 16 + portal-template/src/lib/vendor-tags.ts | 67 ++ portal-template/src/routes/__root.tsx | 15 +- portal-template/vite.config.ts | 4 +- src/actions/portal/generate.ts | 7 +- src/actions/portal/prepare-project.ts | 8 +- src/actions/portal/serve.ts | 28 +- src/actions/quickstart.ts | 1 + src/commands/portal/generate.ts | 7 +- src/commands/portal/serve.ts | 5 +- src/prompts/portal/prepare-project.ts | 10 + src/types/flags-provider.ts | 7 + src/types/portal-source-context.ts | 17 +- src/types/portal/config/analytics-config.ts | 118 +++ src/types/portal/config/fields.ts | 16 +- src/types/portal/config/seo-config.ts | 30 + src/types/portal/portal-config.ts | 36 +- src/types/portal/portal-source.ts | 6 + test/actions/portal/generate.test.ts | 9 +- test/actions/portal/prepare-project-stubs.ts | 16 + test/actions/portal/prepare-project.test.ts | 55 +- test/actions/portal/serve.test.ts | 24 +- test/actions/quickstart.test.ts | 3 + test/commands/portal/build-options.ts | 35 + test/commands/portal/generate-flags.test.ts | 10 + test/commands/portal/serve-flags.test.ts | 10 + test/e2e/portal-build.test.ts | 89 +- test/e2e/portal-serve.test.ts | 2 +- .../portal-pages-service.test.ts | 2 +- .../portal-project-service.test.ts | 22 + test/portal-template.test.ts | 11 +- test/portal-template/analytics.test.ts | 772 ++++++++++++++++++ test/portal-template/api-request.test.ts | 54 ++ test/portal-template/languages.test.ts | 66 ++ test/portal-template/oauth-callback.test.ts | 47 +- test/portal-template/search-report.test.ts | 64 ++ test/prompts/portal/prepare-project.test.ts | 13 + test/types/apimatic-config/schema.test.ts | 76 +- test/types/portal-source-context.test.ts | 56 +- test/types/portal/portal-config.test.ts | 180 +++- 70 files changed, 2633 insertions(+), 152 deletions(-) create mode 100644 portal-template/src/components/code-copy.tsx create mode 100644 portal-template/src/components/endpoint-bar.tsx create mode 100644 portal-template/src/components/playground.tsx create mode 100644 portal-template/src/lib/analytics.ts create mode 100644 portal-template/src/lib/api-request.ts create mode 100644 portal-template/src/lib/languages.ts create mode 100644 portal-template/src/lib/portal-analytics.ts create mode 100644 portal-template/src/lib/replay-markers.ts create mode 100644 portal-template/src/lib/search-report.ts create mode 100644 portal-template/src/lib/transformer-language.ts create mode 100644 portal-template/src/lib/vendor-tags.ts create mode 100644 src/types/portal/config/analytics-config.ts create mode 100644 src/types/portal/config/seo-config.ts create mode 100644 test/commands/portal/build-options.ts create mode 100644 test/commands/portal/generate-flags.test.ts create mode 100644 test/commands/portal/serve-flags.test.ts create mode 100644 test/portal-template/analytics.test.ts create mode 100644 test/portal-template/api-request.test.ts create mode 100644 test/portal-template/languages.test.ts create mode 100644 test/portal-template/search-report.test.ts diff --git a/README.md b/README.md index a1bf9676b..8ee8c6b4f 100644 --- a/README.md +++ b/README.md @@ -298,7 +298,7 @@ Generate a static API Documentation Portal. ``` USAGE - $ apimatic portal generate [--zip] [-i ] [-d ] [-f] [-k ] + $ apimatic portal generate [--zip] [--no-analytics] [-i ] [-d ] [-f] [-k ] FLAGS -d, --destination= [default: /portal] path where the portal will be generated. @@ -306,6 +306,7 @@ FLAGS -i, --input= [default: ./] path to the parent directory containing the 'src' directory, which includes API specifications and configuration files. -k, --auth-key= override current authentication state with an authentication key. + --no-analytics leave out the Google Tag Manager and Google Analytics tags set in 'portal.analytics'. --zip write the generated portal as a .zip archive. DESCRIPTION @@ -338,7 +339,7 @@ Preview your API Documentation Portal with live reload. ``` USAGE - $ apimatic portal serve [-p 23513] [-o] [-i ] [-k ] + $ apimatic portal serve [-p 23513] [-o] [--no-analytics] [-i ] [-k ] FLAGS -i, --input= [default: ./] path to the parent directory containing the 'src' directory, which includes API @@ -346,6 +347,7 @@ FLAGS -k, --auth-key= override current authentication state with an authentication key. -o, --open open the portal in the default browser. -p, --port=23513 [default: 23513] port to serve the portal on. + --no-analytics leave out the Google Tag Manager and Google Analytics tags set in 'portal.analytics'. DESCRIPTION Preview your API Documentation Portal with live reload. diff --git a/apimatic.schema.json b/apimatic.schema.json index f3dae7b92..78ea007da 100644 --- a/apimatic.schema.json +++ b/apimatic.schema.json @@ -177,6 +177,79 @@ } } }, + "analytics": { + "type": "object", + "description": "Analytics the portal loads. Every page view goes to window.dataLayer as docs_page_view, and to GA4 when a measurement ID is set.", + "additionalProperties": false, + "properties": { + "googleTagManager": { + "type": "object", + "additionalProperties": false, + "required": ["containerId"], + "properties": { + "containerId": { + "allOf": [ + { + "$ref": "#/definitions/nonBlank" + } + ], + "description": "The container's ID, for example 'GTM-ABC123'." + }, + "environment": { + "type": "object", + "description": "A GTM environment, for a staging build only, which loads the container's staging version: the gtm_auth and gtm_preview values from the environment's snippet. Both are public in the built portal, so a production portal sets none.", + "additionalProperties": false, + "required": ["auth", "preview"], + "properties": { + "auth": { + "$ref": "#/definitions/nonBlank" + }, + "preview": { + "$ref": "#/definitions/nonBlank" + } + } + } + } + }, + "googleAnalytics": { + "type": "object", + "additionalProperties": false, + "required": ["measurementId"], + "properties": { + "measurementId": { + "allOf": [ + { + "$ref": "#/definitions/nonBlank" + } + ], + "description": "The GA4 web stream's measurement ID, for example 'G-ABC123'. The portal sends its own page views, so turn off the stream's 'Page changes based on browser history events'. Don't also add a GA4 tag to the GTM container: every hit would count twice." + } + } + }, + "keepQueryParams": { + "type": "array", + "description": "Your own link tags to keep in reported page addresses. Campaign (utm_), ad-click and cross-domain tags are kept already; every other query parameter is dropped.", + "items": { + "$ref": "#/definitions/nonBlank" + } + } + } + }, + "seo": { + "type": "object", + "description": "Search engine settings.", + "additionalProperties": false, + "properties": { + "googleSiteVerification": { + "allOf": [ + { + "$ref": "#/definitions/nonBlank" + } + ], + "description": "The content value of Google's site verification meta tag, for Search Console. Not needed for a Domain property verified by DNS." + } + } + }, "pluginUrl": { "type": "string", "description": "Where the context plugin is hosted, starting with 'https://' and with no spaces. The Context Plugin page installs it from here, and the portal carries no copy of its own.", diff --git a/portal-pages/sdk.mdx b/portal-pages/sdk.mdx index b6f558c3b..5792c0a6a 100644 --- a/portal-pages/sdk.mdx +++ b/portal-pages/sdk.mdx @@ -3,6 +3,6 @@ title: "{{name}} SDK" description: "Install and start using the {{name}} SDK." --- - + {{docs}} diff --git a/portal-template/src/components/api-markdown.tsx b/portal-template/src/components/api-markdown.tsx index 884582c22..e3e26b206 100644 --- a/portal-template/src/components/api-markdown.tsx +++ b/portal-template/src/components/api-markdown.tsx @@ -1,10 +1,10 @@ import { createMarkdownRenderer } from 'fumadocs-core/content/md'; import { remarkGfm } from 'fumadocs-core/mdx-plugins/remark-gfm'; -import { DynamicCodeBlock } from 'fumadocs-ui/components/dynamic-codeblock'; import defaultMdxComponents from 'fumadocs-ui/mdx'; import { Children, type ComponentProps, type ReactElement } from 'react'; import { withBasePath } from '@/lib/base-path'; import { languageOf } from '@/lib/code-titles'; +import { ReportedCodeBlock } from './code-copy'; const { Markdown } = createMarkdownRenderer({ remarkPlugins: [remarkGfm] }); @@ -28,5 +28,5 @@ function CodeBlock({ children }: ComponentProps<'pre'>) { const text = code.props.children; if (typeof text !== 'string') return null; const language = languageOf(code.props.className?.split(' ') ?? []) ?? 'text'; - return ; + return ; } diff --git a/portal-template/src/components/api-page.tsx b/portal-template/src/components/api-page.tsx index 219e28517..6b135aabe 100644 --- a/portal-template/src/components/api-page.tsx +++ b/portal-template/src/components/api-page.tsx @@ -1,18 +1,34 @@ +import { lazy, Suspense } from 'react'; import { createOpenAPIPage } from 'fumadocs-openapi/ui'; import { withBasePath } from '@/lib/base-path'; import { mediaAdapters } from '@/lib/media-adapters'; import { oauthCallbackPath } from '@/lib/oauth-callback'; +import { REPLAY_MARKERS } from '@/lib/replay-markers'; import { ApiMarkdown } from './api-markdown'; +import { ReportedCodeBlock } from './code-copy'; +import { EndpointBar } from './endpoint-bar'; import { renderExampleLayout } from './example-layout'; import { codeUsages, renderUsageTabs } from './usage-tabs'; +// Its own chunk, as Fumadocs loads it: the playground's forms are not in every page's bundle. +const Playground = lazy(() => import('./playground')); + export const OpenAPIPage = createOpenAPIPage({ codeUsages, generateTypeScriptDefinitions: false, content: { renderAPIExampleLayout: renderExampleLayout, renderAPIExampleUsageTabs: renderUsageTabs }, - components: { Markdown: ApiMarkdown }, + components: { Markdown: ApiMarkdown, CodeBlock: ReportedCodeBlock }, mediaAdapters, oauthRedirectUrl: withBasePath(oauthCallbackPath), + playground: { + render: ({ method, path }) => ( +
+ }> + + +
+ ) + }, // Portals under paths of one host keep their playground's saved values apart; at the root the keys stay Fumadocs' own. storageKeyPrefix: `fumadocs-openapi-${withBasePath('/').slice(1)}` }); diff --git a/portal-template/src/components/code-copy.tsx b/portal-template/src/components/code-copy.tsx new file mode 100644 index 000000000..4414d5388 --- /dev/null +++ b/portal-template/src/components/code-copy.tsx @@ -0,0 +1,34 @@ +import type { CodeBlockProps as BlockProps } from 'fumadocs-ui/components/codeblock'; +import { DynamicCodeBlock } from 'fumadocs-ui/components/dynamic-codeblock'; +import type { CodeBlockProps } from 'fumadocs-openapi'; +import { languageId } from '@/lib/languages'; +import { analytics } from '@/lib/portal-analytics'; + +type Actions = NonNullable; + +export const reportCodeCopy = (language: string) => + analytics.report('docs_code_copy', { language: languageId(language) }); + +// Fumadocs' own, which any Actions a block is given replaces. +const DefaultActions: Actions = ({ className, children }) => ( +
{children}
+); + +/** A block's Actions slot, which Fumadocs hands the copy button: a click on it calls `onCopy`. */ +export function reportCopies(onCopy: () => void, Actions: Actions = DefaultActions): Actions { + return ({ className, children }) => + Actions({ + className, + children: children && ( + + {children} + + ) + }); +} + +/** Fumadocs' highlighted block, as the API reference renders each, reporting its copies with its language. */ +export function ReportedCodeBlock({ codeblock, ...props }: CodeBlockProps) { + const Actions = reportCopies(() => reportCodeCopy(props.lang), codeblock?.Actions); + return ; +} diff --git a/portal-template/src/components/command-block.tsx b/portal-template/src/components/command-block.tsx index 4d0c8454b..19b54ddf6 100644 --- a/portal-template/src/components/command-block.tsx +++ b/portal-template/src/components/command-block.tsx @@ -2,11 +2,14 @@ import type { ReactNode } from 'react'; import { asMarkdown } from 'fumadocs-core/server'; import { CodeBlock, Pre } from 'fumadocs-ui/components/codeblock'; import { CODE_BLOCK_TITLES } from '@/lib/code-titles'; +import { reportCodeCopy, reportCopies } from './code-copy'; interface CommandBlockProps { command: string; /** One line that truncates, for a card; the full command is still what the button copies. */ compact?: boolean; + /** Called as the copy button is clicked; a copy of a shell command otherwise. */ + onCopy?: () => void; } // Centred on the one line, where the block's own placement pins the button to the top corner. @@ -15,13 +18,15 @@ function CentredActions({ children }: Readonly<{ children?: ReactNode }>) { } /** One shell command in a copyable block: an MDX page has no highlighter to hand, so it is plain. */ -export function CommandBlock({ command, compact = false }: Readonly) { +const reportShellCopy = () => reportCodeCopy('shellscript'); + +export function CommandBlock({ command, compact = false, onCopy = reportShellCopy }: Readonly) { if (asMarkdown()) { return `\`\`\`bash\n${command}\n\`\`\``; } if (!compact) { return ( - +
           
             {/* A highlighted block's lines carry this class, which is what the block pads. */}
@@ -35,7 +40,7 @@ export function CommandBlock({ command, compact = false }: Readonly
       
         
diff --git a/portal-template/src/components/endpoint-bar.tsx b/portal-template/src/components/endpoint-bar.tsx
new file mode 100644
index 000000000..85890ea2a
--- /dev/null
+++ b/portal-template/src/components/endpoint-bar.tsx
@@ -0,0 +1,35 @@
+const METHOD_COLORS: Record = {
+  PUT: 'text-yellow-600 dark:text-yellow-400',
+  PATCH: 'text-orange-600 dark:text-orange-400',
+  POST: 'text-blue-600 dark:text-blue-400',
+  DELETE: 'text-red-600 dark:text-red-400'
+};
+
+/** Fumadocs' endpoint bar, which it shows while the playground loads but does not export: the method and the route. */
+export function EndpointBar({ method, route }: Readonly<{ method: string; route: string }>) {
+  const verb = method.toUpperCase();
+  return (
+    
+ + {verb} + +
+ {route.split(/(\{[^}]*\}|\/)/).map((part, index) => { + if (index % 2 === 0) return part; + if (part === '/') { + return ( + + / + + ); + } + return ( + + {part} + + ); + })} +
+
+ ); +} diff --git a/portal-template/src/components/example-layout.tsx b/portal-template/src/components/example-layout.tsx index 8c904800d..aa3c0a310 100644 --- a/portal-template/src/components/example-layout.tsx +++ b/portal-template/src/components/example-layout.tsx @@ -1,9 +1,10 @@ -import { createContext, useContext, useMemo, useState, type ReactNode } from 'react'; +import { createContext, useContext, useMemo, useState, type MouseEvent, type ReactNode } from 'react'; import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from '@fumadocs/api-docs/components/select'; import { useOpenAPI } from 'fumadocs-openapi'; import { useExampleRequests, useOperation } from 'fumadocs-openapi/operation'; import { CodeSample } from '@/lib/code-samples'; import { Parameter, requestExamples, type RequestExample } from '@/lib/request-examples'; +import { reportCodeCopy } from './code-copy'; interface ExampleSelection { operation: unknown; @@ -20,6 +21,11 @@ interface LayoutSlots { const SelectionContext = createContext(undefined); +// "Example Response" copies through a button of Fumadocs' own in the card's header, which takes no callback. +const reportResponseCopy = (event: MouseEvent) => { + if (event.target instanceof Element && event.target.closest('button[aria-live]') !== null) reportCodeCopy('json'); +}; + export function useExampleSelection(): ExampleSelection { const selection = useContext(SelectionContext); if (selection === undefined) throw new Error('useExampleSelection needs an ExampleLayout above it'); @@ -63,7 +69,9 @@ function ExampleLayout({ selector, usageTabs, responseTabs }: Readonly {selector === null ? null : } {usageTabs} - {responseTabs} +
+ {responseTabs} +
); diff --git a/portal-template/src/components/markdown-copy-button.tsx b/portal-template/src/components/markdown-copy-button.tsx index ed4ea43eb..2064b733b 100644 --- a/portal-template/src/components/markdown-copy-button.tsx +++ b/portal-template/src/components/markdown-copy-button.tsx @@ -2,6 +2,7 @@ import { useEffect, useState } from 'react'; import { buttonVariants } from 'fumadocs-ui/components/ui/button'; import { Check, Copy, X } from 'lucide-react'; import { copyMarkdown } from '@/lib/copy-markdown'; +import { analytics } from '@/lib/portal-analytics'; type CopyState = 'idle' | 'copying' | 'copied' | 'failed'; @@ -24,7 +25,10 @@ export function MarkdownCopyButton({ markdownUrl }: Readonly<{ markdownUrl: stri const copy = () => { setState('copying'); copyMarkdown(markdownUrl).then( - () => setState('copied'), + () => { + setState('copied'); + analytics.report('docs_markdown_copy', {}); + }, (error: unknown) => { console.error(error); setState('failed'); diff --git a/portal-template/src/components/mdx.tsx b/portal-template/src/components/mdx.tsx index 8661f5e65..cbd8b5b88 100644 --- a/portal-template/src/components/mdx.tsx +++ b/portal-template/src/components/mdx.tsx @@ -1,10 +1,13 @@ +import type { HTMLAttributes } from 'react'; import defaultMdxComponents from 'fumadocs-ui/mdx'; import { Accordion, Accordions } from 'fumadocs-ui/components/accordion'; +import { CodeBlock, Pre } from 'fumadocs-ui/components/codeblock'; import { File, Files, Folder } from 'fumadocs-ui/components/files'; import { InlineTOC } from 'fumadocs-ui/components/inline-toc'; import { Step, Steps } from 'fumadocs-ui/components/steps'; import { Tab, Tabs } from 'fumadocs-ui/components/tabs'; import { TypeTable } from 'fumadocs-ui/components/type-table'; +import { reportCodeCopy, reportCopies } from './code-copy'; import { PluginInstall } from './plugin-install'; import { PluginLanguage, PluginLanguages, PluginPlatforms } from './plugin-support'; import { SdkActions } from './sdk-actions'; @@ -12,9 +15,17 @@ import { SdkCard, SdkCards } from './sdk-cards'; type MDXComponents = Record; +type HighlightedPre = HTMLAttributes & { 'data-language'?: string }; + export function getMDXComponents(components?: MDXComponents) { return { ...defaultMdxComponents, + // Fumadocs' own, its copy button reporting the language the build names on the block. + pre: ({ 'data-language': language = 'plaintext', ...props }: HighlightedPre) => ( + reportCodeCopy(language))}> +
{props.children}
+
+ ), // Fumadocs' components beyond its defaults, so an author's page can use them without importing. Accordion, Accordions, diff --git a/portal-template/src/components/not-found.tsx b/portal-template/src/components/not-found.tsx index 375aacb7e..3eba7d789 100644 --- a/portal-template/src/components/not-found.tsx +++ b/portal-template/src/components/not-found.tsx @@ -1,8 +1,20 @@ +import { useEffect } from 'react'; +import { useRouterState } from '@tanstack/react-router'; import { baseOptions } from '@/lib/layout.shared'; +import { analytics } from '@/lib/portal-analytics'; import { HomeLayout } from 'fumadocs-ui/layouts/home'; import { DefaultNotFound } from 'fumadocs-ui/layouts/home/not-found'; export function NotFound() { + // The path the router has settled on: its location alone already names the page a reader is leaving this one for. + const settled = useRouterState({ + select: ({ location, resolvedLocation }) => + resolvedLocation?.pathname === location.pathname ? location.pathname : null + }); + // Keyed on the path: the same component shows the next missing page too. + useEffect(() => { + if (settled !== null) analytics.reportNotFound(); + }, [settled]); return ( diff --git a/portal-template/src/components/playground.tsx b/portal-template/src/components/playground.tsx new file mode 100644 index 000000000..0908ea9ae --- /dev/null +++ b/portal-template/src/components/playground.tsx @@ -0,0 +1,49 @@ +import { createContext, use, useEffect, useMemo, useRef, type RefObject } from 'react'; +import { useOperation } from 'fumadocs-openapi/operation'; +import type { FetchResult } from 'fumadocs-openapi/playground'; +import PlaygroundClient, { DefaultResultDisplay, type ResultDisplayProps } from 'fumadocs-openapi/ui/playground/client'; +import { apiRequest } from '@/lib/api-request'; +import { analytics } from '@/lib/portal-analytics'; + +/** When this playground last sent a request, for a result that has no duration of its own. */ +const SentAt = createContext>({ current: null }); + +// The display mounts again with the same result on each reopen, and twice in a dev build. +const reported = new WeakSet(); + +function ResultDisplay(props: ResultDisplayProps) { + const { method, path } = useOperation(); + const sentAt = use(SentAt); + useEffect(() => { + if (reported.has(props.data)) return; + reported.add(props.data); + const endpoint = `${method.toUpperCase()} ${path}`; + analytics.report('docs_api_request', apiRequest(endpoint, props.data, sentAt.current, Date.now())); + sentAt.current = null; + }, [method, path, props.data, sentAt]); + return ; +} + +const components = { ResultDisplay }; + +/** The playground with the reporting around it, in the one chunk the API page loads lazily. */ +export default function Playground() { + const sentAt = useRef(null); + // Fumadocs' request has no callback of its own: the time is noted here, and the request goes on unchanged. + const fetchOptions = useMemo( + () => ({ + onRequestInit: (requestInit: RequestInit) => { + sentAt.current = Date.now(); + return requestInit; + } + }), + [] + ); + // Fumadocs takes a returned sign-in's answer out of the address in the effects of the playground below this one. + useEffect(() => analytics.loadTags(), []); + return ( + + + + ); +} diff --git a/portal-template/src/components/plugin-install.tsx b/portal-template/src/components/plugin-install.tsx index 9c810b52f..2ecc911c1 100644 --- a/portal-template/src/components/plugin-install.tsx +++ b/portal-template/src/components/plugin-install.tsx @@ -3,11 +3,14 @@ import { asMarkdown } from 'fumadocs-core/server'; import { CommandBlock } from './command-block'; import { fullAddress } from '@/lib/base-path'; import { installCommand } from '@/lib/install-command'; +import { analytics } from '@/lib/portal-analytics'; import { portal } from '@/lib/portal'; // The address never changes while the page is open, so there is nothing to subscribe to. const noSubscribe = () => () => {}; +const reportInstall = () => analytics.report('docs_plugin_install', {}); + /** The prerender cannot know where the portal is hosted, so the browser swaps in its own address. */ export function PluginInstall({ path }: Readonly<{ path: string }>) { // Ahead of the hook, which only React may call; either branch is taken in every render of one environment. @@ -19,5 +22,5 @@ export function PluginInstall({ path }: Readonly<{ path: string }>) { () => fullAddress('/'), () => portal.siteUrl ); - return ; + return ; } diff --git a/portal-template/src/components/sdk-actions.tsx b/portal-template/src/components/sdk-actions.tsx index 4c90cfb18..541e21229 100644 --- a/portal-template/src/components/sdk-actions.tsx +++ b/portal-template/src/components/sdk-actions.tsx @@ -3,8 +3,11 @@ import { asMarkdown } from 'fumadocs-core/server'; import { buttonVariants } from 'fumadocs-ui/components/ui/button'; import { Code, Download, Package } from 'lucide-react'; import { withBasePath } from '@/lib/base-path'; +import { languageId } from '@/lib/languages'; +import { analytics } from '@/lib/portal-analytics'; export interface SdkActionsProps { + language: string; download: string; /** Empty when no source repository is recorded. */ source: string; @@ -19,7 +22,7 @@ export const LINK = export const QUIET_LINK = `${LINK} text-fd-muted-foreground hover:text-fd-foreground`; /** Download, View source and View package: each shown only when there is something behind it. */ -export function SdkActions({ download, source, packageUrl, registry }: Readonly) { +export function SdkActions({ language, download, source, packageUrl, registry }: Readonly) { // The page's Markdown twin, which the page actions and llms-full.txt hand to an AI assistant. if (asMarkdown()) { const links = [ @@ -35,6 +38,7 @@ export function SdkActions({ download, source, packageUrl, registry }: Readonly<
@@ -62,10 +66,19 @@ interface LinkProps { children: ReactNode; } +interface DownloadLinkProps extends LinkProps { + language: string; +} + /** A plain link, not a route: the zip is a file the site serves beside its pages. */ -export function DownloadLink({ href, className, children }: Readonly) { +export function DownloadLink({ href, className, language, children }: Readonly) { return ( - + analytics.report('docs_sdk_download', { language: languageId(language) })} + > {children} ); diff --git a/portal-template/src/components/sdk-cards.tsx b/portal-template/src/components/sdk-cards.tsx index fda88b91e..b79013469 100644 --- a/portal-template/src/components/sdk-cards.tsx +++ b/portal-template/src/components/sdk-cards.tsx @@ -8,7 +8,6 @@ import { LanguageLogo, LogoTile } from './logos'; import { DownloadLink, ExternalLink, LINK, QUIET_LINK, SdkActions, type SdkActionsProps } from './sdk-actions'; interface SdkCardProps extends SdkActionsProps { - language: string; name: string; /** The language's own page. */ page: string; @@ -41,7 +40,10 @@ function LinkContext({ name }: Readonly<{ name: string }>) { export function SdkCard({ language, name, page, install, ...actions }: Readonly) { if (asMarkdown()) { const command = install ? `\`${install}\` · ` : ''; - return [`- [${name}](${withBasePath(page)}): ${command}`, ]; + return [ + `- [${name}](${withBasePath(page)}): ${command}`, + + ]; } const { download, source, packageUrl, registry } = actions; return ( @@ -57,7 +59,7 @@ export function SdkCard({ language, name, page, install, ...actions }: Readonly< {install ? ( ) : ( - + Download SDK @@ -65,7 +67,7 @@ export function SdkCard({ language, name, page, install, ...actions }: Readonly< )}
{install ? ( - + Download SDK diff --git a/portal-template/src/components/search.tsx b/portal-template/src/components/search.tsx index 8180d4108..db1450481 100644 --- a/portal-template/src/components/search.tsx +++ b/portal-template/src/components/search.tsx @@ -8,13 +8,16 @@ import { SearchDialogInput, SearchDialogList, SearchDialogOverlay, + type SearchItemType, type SharedProps } from 'fumadocs-ui/components/dialog/search'; import { useDocsSearch } from 'fumadocs-core/search/client'; import { staticClient } from 'fumadocs-core/search/client/orama-static'; import { useI18n } from 'fumadocs-ui/contexts/i18n'; -import { useMemo } from 'react'; +import { useEffect, useMemo, useRef } from 'react'; import { withBasePath } from '@/lib/base-path'; +import { analytics } from '@/lib/portal-analytics'; +import { searchOutcome } from '@/lib/search-report'; export default function DefaultSearchDialog(props: SharedProps) { const { locale } = useI18n(); @@ -32,8 +35,52 @@ export default function DefaultSearchDialog(props: SharedProps) { [query.data] ); + const typed = useRef(false); + const picked = useRef(''); + const openedAt = useRef(''); + const wasOpen = useRef(false); + + // The page the search is made on: a pick changes the address before the dialog reports its close. + useEffect(() => { + if (!props.open) return; + wasOpen.current = true; + openedAt.current = window.location.href; + }, [props.open]); + + // A close is seen from the prop, which the hotkey changes too. + useEffect(() => { + if (!wasOpen.current) return; + const outcome = searchOutcome({ + open: props.open, + loading: query.isLoading, + typed: typed.current, + picked: picked.current, + term: search, + resultCount: results?.length ?? 0 + }); + if (!outcome.ended) return; + wasOpen.current = false; + typed.current = false; + picked.current = ''; + if (outcome.report !== null) analytics.report('docs_search', outcome.report, openedAt.current); + }, [props.open, query.isLoading, search, results]); + + const onSearchChange = (value: string) => { + typed.current = true; + setSearch(value); + }; + const onSelect = (item: SearchItemType) => { + picked.current = 'url' in item ? new URL(item.url, window.location.href).href : ''; + }; + return ( - + diff --git a/portal-template/src/components/usage-tabs.tsx b/portal-template/src/components/usage-tabs.tsx index a5e59fcf5..43cb1d7ba 100644 --- a/portal-template/src/components/usage-tabs.tsx +++ b/portal-template/src/components/usage-tabs.tsx @@ -5,6 +5,7 @@ import { useCodeUsage } from 'fumadocs-openapi/operation'; import { createCodeUsageGeneratorRegistry } from 'fumadocs-openapi/requests/generators'; import { curl } from 'fumadocs-openapi/requests/generators/curl'; import { CodeSample } from '@/lib/code-samples'; +import { REPLAY_MARKERS } from '@/lib/replay-markers'; import { useExampleSelection } from './example-layout'; interface UsageTab { @@ -64,9 +65,13 @@ function SampleCode({ sample }: Readonly<{ sample: CodeSample }>) { return ; } -// Follows the playground's edits to the selected example, on the selected server. +// Follows the playground's edits, typed credentials included, so it carries the playground's replay markers. function CurlCode() { const { CodeBlock } = useComponents(); const code = useCodeUsage(CURL_USAGE_ID); - return code === undefined ? null : ; + return code === undefined ? null : ( +
+ +
+ ); } diff --git a/portal-template/src/lib/analytics.ts b/portal-template/src/lib/analytics.ts new file mode 100644 index 000000000..10e59cffd --- /dev/null +++ b/portal-template/src/lib/analytics.ts @@ -0,0 +1,126 @@ +import { isOAuthCallbackPath } from './oauth-callback'; +import type { PortalAnalytics } from './portal-types'; +import { type Adapter, adapters, insertTags } from './vendor-tags'; + +/** The query parameters an ad or mail platform reads from an address itself; a customer adds names and removes none. */ +const KEPT_PREFIXES = ['utm_', 'hsa_']; +const KEPT_NAMES = new Set([ + '_gl', + 'gclid', + 'gbraid', + 'wbraid', + 'gad_source', + 'dclid', + 'fbclid', + 'msclkid', + 'ttclid', + 'twclid', + 'li_fat_id', + 'mc_cid', + '_hsenc', + '_hsmi' +]); + +/** Customers' GTM triggers match these names, so renaming or removing one breaks them without an error. */ +export interface PortalEvents { + docs_page_view: { page_title: string }; + docs_markdown_copy: Record; + docs_plugin_install: Record; + docs_sdk_download: { language: string }; + docs_code_copy: { language: string }; + docs_search: { search_term: string; result: string; result_count: number }; + docs_not_found: { page_referrer: string }; + /** `status` is always text: the HTTP status in digits, or `client_error` for a request that never reached the API. */ + docs_api_request: { endpoint: string; status: string; duration_ms: number }; +} +export type PortalEventName = keyof PortalEvents; + +type DataLayerEntry = { docs: null } | { event: PortalEventName; docs: Readonly> }; + +declare global { + interface Window { + dataLayer?: unknown[]; + /** Held by the window: a config save under `portal serve` evaluates this module again. */ + portalAnalyticsStarted?: string; + } +} + +/** The address as reported: no `#` part, and no query but the kept tags. */ +export function pageLocation(href: string, keep: readonly string[]): string { + const url = new URL(href); + url.search = new URLSearchParams( + [...url.searchParams].filter( + ([name]) => KEPT_PREFIXES.some((prefix) => name.startsWith(prefix)) || KEPT_NAMES.has(name) || keep.includes(name) + ) + ).toString(); + url.hash = ''; + return url.href; +} + +export class Analytics { + private readonly live: Adapter[]; + private lastPageView: string | null = null; + private previousPageView: string | null = null; + private lastNotFound: string | null = null; + + public constructor(private readonly settings: PortalAnalytics) { + 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(); + return; + } + window.portalAnalyticsStarted = settings; + const dataLayer = (window.dataLayer ??= []); + for (const adapter of this.live) adapter.setup(dataLayer); + insertTags(this.live); + } + + /** The tags held back while the address held an OAuth answer, once something has taken it out. */ + public loadTags(): void { + insertTags(this.live); + } + + /** `href` is the page the event belongs to, when the caller saw the address move on first. */ + public report(name: E, params: PortalEvents[E], href = window.location.href): void { + if (isOAuthCallbackPath(new URL(href).pathname)) return; + const docs = { ...params, page_location: pageLocation(href, this.settings.keepQueryParams) }; + const dataLayer = (window.dataLayer ??= []); + // GTM merges every push into what it holds, so a tag would send the last event's details without this. + dataLayer.push({ docs: null } satisfies DataLayerEntry); + dataLayer.push({ event: name, docs } satisfies DataLayerEntry); + for (const adapter of this.live) adapter.send?.(name, docs); + } + + public reportPageView(): void { + if (isOAuthCallbackPath(window.location.pathname)) return; + this.loadTags(); + const page = pageLocation(window.location.href, this.settings.keepQueryParams); + if (page === this.lastPageView) return; + this.previousPageView = this.lastPageView; + this.lastPageView = page; + if (this.lastNotFound !== page) this.lastNotFound = null; + this.report('docs_page_view', { page_title: document.title }); + } + + public reportNotFound(): void { + const page = pageLocation(window.location.href, this.settings.keepQueryParams); + if (page === this.lastNotFound) return; + this.lastNotFound = page; + const referrer = document.referrer === '' ? null : new URL(document.referrer); + if (referrer !== null) { + referrer.search = ''; + referrer.hash = ''; + } + // The missing page's own view may be reported before this or after it. + const left = this.lastPageView === page ? this.previousPageView : this.lastPageView; + this.report('docs_not_found', { page_referrer: left ?? referrer?.href ?? '' }); + } +} diff --git a/portal-template/src/lib/api-request.ts b/portal-template/src/lib/api-request.ts new file mode 100644 index 000000000..19db41dc4 --- /dev/null +++ b/portal-template/src/lib/api-request.ts @@ -0,0 +1,15 @@ +import type { FetchResult } from 'fumadocs-openapi/playground'; +import type { PortalEvents } from './analytics'; + +/** A playground result as `docs_api_request` reports it; a request that never reached the API is timed from `sentAt`. */ +export function apiRequest( + endpoint: string, + result: FetchResult, + sentAt: number | null, + now: number +): PortalEvents['docs_api_request'] { + if (result.type === 'response') { + return { endpoint, status: String(result.status), duration_ms: Math.round(result.duration) }; + } + return { endpoint, status: 'client_error', duration_ms: sentAt === null ? 0 : now - sentAt }; +} diff --git a/portal-template/src/lib/code-titles.ts b/portal-template/src/lib/code-titles.ts index 6d6cdbca6..73005bf35 100644 --- a/portal-template/src/lib/code-titles.ts +++ b/portal-template/src/lib/code-titles.ts @@ -1,5 +1,4 @@ -// A type alone, so a page naming a title does not load the highlighter the bundle builds. -import type { BundledLanguage } from './shiki-bundle'; +import type { BundledLanguage } from './languages'; /** What a code block's header calls its language; a shell is named for where the command runs. */ export const CODE_BLOCK_TITLES: Readonly> = { diff --git a/portal-template/src/lib/languages.ts b/portal-template/src/lib/languages.ts new file mode 100644 index 000000000..0d1865c4e --- /dev/null +++ b/portal-template/src/lib/languages.ts @@ -0,0 +1,99 @@ +/** The languages the portal highlights, by Shiki's IDs; apart from `shiki-bundle.ts`, so naming one loads no grammar. */ +export const BUNDLED_LANGUAGES = [ + // The seven the CLI generates SDKs for (src/types/sdk/generate.ts). + 'csharp', + 'go', + 'java', + 'php', + 'python', + 'ruby', + 'typescript', + + // Shell commands, and the shapes a response or a specification is shown in. + 'http', + 'json', + 'jsonc', + 'shellscript', + 'shellsession', + 'xml', + 'yaml', + + // What the Markdown pages beside the reference are written in. + 'css', + 'diff', + 'graphql', + 'html', + 'javascript', + 'jsx', + 'markdown', + 'sql', + 'tsx' +] as const; + +export type BundledLanguage = (typeof BUNDLED_LANGUAGES)[number]; + +/** Shiki's aliases, which a hand-built bundle lacks; `test/portal-template.test.ts` holds them to Shiki's own. */ +export const languageAliases: Readonly> = { + 'c#': 'csharp', + cs: 'csharp', + py: 'python', + rb: 'ruby', + ts: 'typescript', + cts: 'typescript', + mts: 'typescript', + js: 'javascript', + cjs: 'javascript', + mjs: 'javascript', + bash: 'shellscript', + sh: 'shellscript', + shell: 'shellscript', + zsh: 'shellscript', + console: 'shellsession', + yml: 'yaml', + md: 'markdown', + gql: 'graphql' +}; + +/** The grammar a fence's language names, by its own name or an alias; null for one not bundled. */ +export function bundledLanguage(name: string): BundledLanguage | null { + if ((BUNDLED_LANGUAGES as readonly string[]).includes(name)) { + return name as BundledLanguage; + } + return Object.hasOwn(languageAliases, name) ? languageAliases[name] : null; +} + +/** Short names of languages outside the bundle, by Shiki's ID: for reports only, so one language is one value. */ +export const reportedAliases: Readonly> = { + kt: 'kotlin', + kts: 'kotlin', + rs: 'rust', + 'c++': 'cpp', + objc: 'objective-c', + 'f#': 'fsharp', + fs: 'fsharp', + hs: 'haskell', + clj: 'clojure', + erl: 'erlang', + jl: 'julia', + ps: 'powershell', + ps1: 'powershell', + pwsh: 'powershell', + batch: 'bat', + cmd: 'bat', + dockerfile: 'docker', + makefile: 'make', + tf: 'terraform', + tfvars: 'terraform', + protobuf: 'proto', + properties: 'ini', + // Shiki's other names for a block in no language, which a page's own blocks report as `plaintext`. + text: 'plaintext', + txt: 'plaintext', + plain: 'plaintext' +}; + +/** A language as the portal reports it: its ID for any name it goes by, bundled or not, else the name in lowercase. */ +export function languageId(name: string): string { + const lowered = name.toLowerCase(); + return bundledLanguage(lowered) ?? (Object.hasOwn(reportedAliases, lowered) ? reportedAliases[lowered] : lowered); +} diff --git a/portal-template/src/lib/oauth-callback.ts b/portal-template/src/lib/oauth-callback.ts index cf8cf74df..ad878ec7a 100644 --- a/portal-template/src/lib/oauth-callback.ts +++ b/portal-template/src/lib/oauth-callback.ts @@ -1,3 +1,5 @@ +import { withBasePath } from './base-path'; + /** * The one redirect URI a portal owner registers with their OAuth provider, instead of the * address of every endpoint page that can start an authorization. The CLI keeps the user's @@ -5,6 +7,21 @@ */ export const oauthCallbackPath = '/oauth/callback'; +/** Whether a path is the callback's under `base`, Vite's own unless one is given; a static host may add a slash. */ +export function isOAuthCallbackPath(pathname: string, base?: string): boolean { + return pathname.replace(/\/$/, '') === withBasePath(oauthCallbackPath, base); +} + +/** The callback's address always holds a provider's answer; a page a sign-in returned to does until the playground reads it. */ +export function holdsOAuthAnswer({ pathname, search, hash }: Pick): boolean { + // Fumadocs sends a `state` with every authorization, and the answer carries it back in the query or the `#` part. + return ( + isOAuthCallbackPath(pathname) || + new URLSearchParams(search).has('state') || + new URLSearchParams(hash.slice(1)).has('state') + ); +} + /** Where the playground notes the path of the page that started the flow before it leaves: this tab's session storage. */ const STARTING_PAGE_KEY = 'fumadocs-openapi-oauth'; diff --git a/portal-template/src/lib/portal-analytics.ts b/portal-template/src/lib/portal-analytics.ts new file mode 100644 index 000000000..d23527eb9 --- /dev/null +++ b/portal-template/src/lib/portal-analytics.ts @@ -0,0 +1,10 @@ +import { Analytics } from './analytics'; +import { portal } from './portal'; +import { markPlaygroundDialogs } from './replay-markers'; + +export const analytics = new Analytics(portal.analytics); +// When the bundle starts, before React and before any vendor tag. Never during prerendering. +if (typeof window !== 'undefined') { + markPlaygroundDialogs(); + analytics.start(); +} diff --git a/portal-template/src/lib/portal-types.ts b/portal-template/src/lib/portal-types.ts index 8762b2eb2..cbc8cc0e1 100644 --- a/portal-template/src/lib/portal-types.ts +++ b/portal-template/src/lib/portal-types.ts @@ -22,6 +22,32 @@ export interface PortalFavicon { type: string | null; } +export interface GoogleTagManagerEnvironment { + auth: string; + preview: string; +} + +export interface GoogleTagManagerSetting { + containerId: string; + environment: GoogleTagManagerEnvironment | null; +} + +export interface GoogleAnalyticsSetting { + measurementId: string; +} + +/** Public values: they sit in every page's scripts. */ +export interface PortalAnalytics { + googleTagManager: GoogleTagManagerSetting | null; + googleAnalytics: GoogleAnalyticsSetting | null; + keepQueryParams: string[]; +} + +export interface PortalSeo { + /** The content value of Google's site verification meta tag, for Search Console. */ + googleSiteVerification: string | null; +} + export interface Portal { name: string; description: string | null; @@ -33,4 +59,6 @@ export interface Portal { links: PortalLink[]; /** Whether each page offers to open itself in an external AI assistant. */ pageActions: boolean; + analytics: PortalAnalytics; + seo: PortalSeo; } diff --git a/portal-template/src/lib/rehype-code-titles.ts b/portal-template/src/lib/rehype-code-titles.ts index e563fe269..01fd1ec13 100644 --- a/portal-template/src/lib/rehype-code-titles.ts +++ b/portal-template/src/lib/rehype-code-titles.ts @@ -1,6 +1,6 @@ import { parseCodeBlockAttributes } from 'fumadocs-core/mdx-plugins/codeblock-utils'; import { CODE_BLOCK_TITLES, languageOf } from './code-titles'; -import { bundledLanguage } from './shiki-bundle'; +import { bundledLanguage } from './languages'; interface HastNode { type: string; diff --git a/portal-template/src/lib/replay-markers.ts b/portal-template/src/lib/replay-markers.ts new file mode 100644 index 000000000..d1ab35424 --- /dev/null +++ b/portal-template/src/lib/replay-markers.ts @@ -0,0 +1,28 @@ +/** The opt-out markers of the session replay tools a GTM tag may load; each keeps its tool out of the element. */ +export const REPLAY_MARKERS = { + className: 'ph-no-capture fs-exclude rr-block amp-block', + 'data-hj-suppress': '', + 'data-clarity-mask': 'True', + 'data-private': '' +} as const; + +function markForReplay(element: Element): void { + element.classList.add(...REPLAY_MARKERS.className.split(' ')); + for (const [name, value] of Object.entries(REPLAY_MARKERS)) { + if (name !== 'className') element.setAttribute(name, value); + } +} + +/** Observers are told in the order they were made, so this one, made before any tag's, marks the dialog first. */ +export function markPlaygroundDialogs(): void { + new MutationObserver((mutations) => { + for (const { addedNodes } of mutations) { + for (const node of addedNodes) { + if (!(node instanceof Element)) continue; + // Told from the search dialog by its request form, until fuma-nama/fumadocs#3824 takes the markers itself. + const dialog = node.matches('[role="dialog"]') ? node : node.querySelector('[role="dialog"]'); + if (dialog !== null && dialog.querySelector('form') !== null) markForReplay(dialog); + } + } + }).observe(document.body, { childList: true, subtree: true }); +} diff --git a/portal-template/src/lib/search-report.ts b/portal-template/src/lib/search-report.ts new file mode 100644 index 000000000..2b347b3ae --- /dev/null +++ b/portal-template/src/lib/search-report.ts @@ -0,0 +1,28 @@ +import { pageLocation, type PortalEvents } from './analytics'; + +/** The search dialog on a render after it opened. */ +export interface SearchDialogState { + open: boolean; + /** The last keystrokes' results are still on their way. */ + loading: boolean; + typed: boolean; + /** The whole address of the result picked, or empty. */ + picked: string; + term: string; + resultCount: number; +} + +export type SearchOutcome = { ended: false } | { ended: true; report: PortalEvents['docs_search'] | null }; + +/** What GA4 keeps of a parameter's value, so no other tag gets more of what a reader pasted into search. */ +const TERM_LIMIT = 100; + +/** A search ends once the dialog has closed with its results in; it reports when the reader typed or picked a term. */ +export function searchOutcome(state: SearchDialogState): SearchOutcome { + if (state.open || state.loading) return { ended: false }; + const search_term = state.term.trim().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 }; +} diff --git a/portal-template/src/lib/shiki-bundle.ts b/portal-template/src/lib/shiki-bundle.ts index 2ab73b5c3..e5e02869a 100644 --- a/portal-template/src/lib/shiki-bundle.ts +++ b/portal-template/src/lib/shiki-bundle.ts @@ -1,5 +1,6 @@ import { createBundledHighlighter } from 'shiki/core'; import { createJavaScriptRegexEngine } from 'shiki/engine/javascript'; +import { languageAliases, type BundledLanguage } from './languages'; // Re-exported untouched: Fumadocs imports it from the `shiki` entry point this file stands // in for, though the bundle itself builds its highlighter on the JavaScript engine. @@ -44,49 +45,12 @@ const languages = { markdown: () => import('shiki/dist/langs/markdown.mjs'), sql: () => import('shiki/dist/langs/sql.mjs'), tsx: () => import('shiki/dist/langs/tsx.mjs') -} satisfies Record; - -/** - * Shiki's own bundle resolves `ts` or `yml` through an alias table beside its grammars; a - * hand-built map has none, so an alias reaches Fumadocs as an unknown language and is replaced - * with `text`. Each shares its grammar's import, as Shiki's `bundledLanguagesAlias` does, so - * the bundler still emits one chunk per language rather than one per spelling. Taken from - * Shiki's `bundledLanguagesInfo`; `test/portal-template.test.ts` holds them to it. - */ -const aliases: Record = { - 'c#': 'csharp', - cs: 'csharp', - py: 'python', - rb: 'ruby', - ts: 'typescript', - cts: 'typescript', - mts: 'typescript', - js: 'javascript', - cjs: 'javascript', - mjs: 'javascript', - bash: 'shellscript', - sh: 'shellscript', - shell: 'shellscript', - zsh: 'shellscript', - console: 'shellsession', - yml: 'yaml', - md: 'markdown', - gql: 'graphql' -}; - -export type BundledLanguage = keyof typeof languages; - -/** The grammar a fence's language names, by its own name or an alias; null for one not bundled. */ -export function bundledLanguage(name: string): BundledLanguage | null { - if (Object.hasOwn(languages, name)) { - return name as BundledLanguage; - } - return Object.hasOwn(aliases, name) ? aliases[name] : null; -} +} satisfies Record; +// Each alias shares its grammar's import, as Shiki's `bundledLanguagesAlias` does: one chunk per language, not per spelling. const bundledLanguages = { ...languages, - ...Object.fromEntries(Object.entries(aliases).map(([alias, id]) => [alias, languages[id]])) + ...Object.fromEntries(Object.entries(languageAliases).map(([alias, id]) => [alias, languages[id]])) } as never; /** The two Fumadocs asks for by default; the rest of Shiki's themes are never requested. */ diff --git a/portal-template/src/lib/source.ts b/portal-template/src/lib/source.ts index f6eae85e3..e239a1405 100644 --- a/portal-template/src/lib/source.ts +++ b/portal-template/src/lib/source.ts @@ -1,9 +1,9 @@ import { defineDocs } from 'fumadocs-mdx/macro'; import { applyMdxPreset } from 'fumadocs-mdx/config'; -import { rehypeCodeDefaultOptions } from 'fumadocs-core/mdx-plugins'; import rehypeRaw from 'rehype-raw'; import { rehypeCodeTitles, rehypeKeepCodeMeta } from './rehype-code-titles'; import { navigationSchema } from './navigation-schema'; +import { rehypeCodeOptions } from './transformer-language'; // What `rehype-raw` must hand on untouched, being MDX's own nodes rather than HTML. const MDX_NODE_TYPES = ['mdxFlowExpression', 'mdxJsxFlowElement', 'mdxJsxTextElement', 'mdxTextExpression', 'mdxjsEsm']; @@ -35,7 +35,7 @@ export const generated = defineDocs({ // A remote image is never fetched for its size, which would make the build depend on its host. remarkImageOptions: { external: false }, // The SDK pages' design heads a block with its title alone, without Fumadocs' language icon. - rehypeCodeOptions: { ...rehypeCodeDefaultOptions, icon: false }, + rehypeCodeOptions: { ...rehypeCodeOptions, icon: false }, // The SDK docs' HTML fails the build unrendered; not sanitized, as it comes from the owner's own spec. // The titles go in after it, and ahead of `rehypeCode`, the first of the defaults, which reads them. rehypePlugins: (defaults) => [ diff --git a/portal-template/src/lib/transformer-language.ts b/portal-template/src/lib/transformer-language.ts new file mode 100644 index 000000000..be12cf340 --- /dev/null +++ b/portal-template/src/lib/transformer-language.ts @@ -0,0 +1,16 @@ +import { rehypeCodeDefaultOptions } from 'fumadocs-core/mdx-plugins'; +import type { ShikiTransformer } from 'shiki'; + +/** Names each highlighted block's language on its `pre`, which the MDX `pre` hands to the block's copy button. */ +export const transformerLanguage: ShikiTransformer = { + name: 'portal:language', + pre(node) { + node.properties['data-language'] = this.options.lang; + } +}; + +/** Fumadocs' code options for every collection, with each block's language named for its copy button. */ +export const rehypeCodeOptions = { + ...rehypeCodeDefaultOptions, + transformers: [...(rehypeCodeDefaultOptions.transformers ?? []), transformerLanguage] +}; diff --git a/portal-template/src/lib/vendor-tags.ts b/portal-template/src/lib/vendor-tags.ts new file mode 100644 index 000000000..76f7922e0 --- /dev/null +++ b/portal-template/src/lib/vendor-tags.ts @@ -0,0 +1,67 @@ +import { holdsOAuthAnswer } from './oauth-callback'; +import type { PortalAnalytics } from './portal-types'; + +type Gtag = (...command: unknown[]) => void; + +declare global { + interface Window { + gtag?: Gtag; + } +} + +export interface Adapter { + setup(dataLayer: unknown[]): void; + script: string; + /** For a vendor that does not read the data layer itself, as GTM does. */ + send?(name: string, params: Record): void; +} + +type Vendor = Exclude; +const GOOGLE = 'https://www.googletagmanager.com'; + +/** Keyed by every vendor `PortalAnalytics` names, so a vendor without an adapter does not compile. */ +export const adapters: { [V in Vendor]: (settings: PortalAnalytics) => Adapter | null } = { + googleTagManager: ({ googleTagManager: setting }) => { + if (setting === null) return null; + const env = setting.environment; + const environment = env + ? `>m_auth=${encodeURIComponent(env.auth)}>m_preview=${encodeURIComponent(env.preview)}>m_cookies_win=x` + : ''; + return { + setup: (dataLayer) => dataLayer.push({ 'gtm.start': Date.now(), event: 'gtm.js' }), + script: `${GOOGLE}/gtm.js?id=${encodeURIComponent(setting.containerId)}${environment}` + }; + }, + googleAnalytics: ({ googleAnalytics: setting }) => { + 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); + }); + gtag('js', new Date()); + gtag('config', setting.measurementId, { send_page_view: false }); + }, + script: `${GOOGLE}/gtag/js?id=${encodeURIComponent(setting.measurementId)}`, + send: (name, params) => { + // GA4's own events, such as a scroll, read this instead of the address, which may hold more. + if (name === 'docs_page_view') window.gtag?.('set', { page_location: params.page_location }); + // The page's gtag, since a second instance under `portal serve` never runs its setup. + window.gtag?.('event', name.replace(/^docs_/, ''), params); + } + }; + } +}; + +/** None while the address holds an OAuth answer, which the tags read for themselves; each once, so a later call adds the rest. */ +export function insertTags(live: Adapter[]): void { + if (holdsOAuthAnswer(window.location)) return; + for (const { script: src } of live) { + if (document.head.querySelector(`script[src="${src}"]`) !== null) continue; + const script = document.createElement('script'); + script.async = true; + script.src = src; + document.head.append(script); + } +} diff --git a/portal-template/src/routes/__root.tsx b/portal-template/src/routes/__root.tsx index ba8d973df..1186941d8 100644 --- a/portal-template/src/routes/__root.tsx +++ b/portal-template/src/routes/__root.tsx @@ -1,5 +1,6 @@ -import { createRootRoute, HeadContent, Outlet, Scripts } from '@tanstack/react-router'; +import { createRootRoute, HeadContent, Outlet, Scripts, useRouter } from '@tanstack/react-router'; import { createServerFn } from '@tanstack/react-start'; +import { useEffect } from 'react'; import { staticFunctionMiddleware } from '@tanstack/start-static-server-functions'; import { source } from '@/lib/source.server'; import appCss from '@/styles/app.css?url'; @@ -7,6 +8,7 @@ import { RootProvider } from 'fumadocs-ui/provider/tanstack'; import SearchDialog from '@/components/search'; import { withBasePath } from '@/lib/base-path'; import { portal } from '@/lib/portal'; +import { analytics } from '@/lib/portal-analytics'; // The sidebar tree is the same on every page. Loaded here, once, it is written to a single // cache file instead of being repeated in every page's own loader payload. @@ -39,7 +41,10 @@ export const Route = createRootRoute({ { charSet: 'utf-8' }, { name: 'viewport', content: 'width=device-width, initial-scale=1' }, { title: portal.name }, - ...(portal.description ? [{ name: 'description', content: portal.description }] : []) + ...(portal.description ? [{ name: 'description', content: portal.description }] : []), + ...(portal.seo.googleSiteVerification + ? [{ name: 'google-site-verification', content: portal.seo.googleSiteVerification }] + : []) ], links: [{ rel: 'stylesheet', href: appCss }, ...iconLinks] }), @@ -47,6 +52,12 @@ export const Route = createRootRoute({ }); function RootComponent() { + const router = useRouter(); + useEffect(() => { + // A prerendered page mounts idle with no `onRendered` to come; `portal serve` mounts pending, and one follows. + if (router.state.status === 'idle') analytics.reportPageView(); + return router.subscribe('onRendered', () => analytics.reportPageView()); + }, [router]); return ( diff --git a/portal-template/vite.config.ts b/portal-template/vite.config.ts index 1151c6ff5..9fd1975e4 100644 --- a/portal-template/vite.config.ts +++ b/portal-template/vite.config.ts @@ -12,6 +12,7 @@ import { prerenderPages } from './prerender-pages.ts'; import { remarkJsxImages } from './remark-jsx-images.ts'; import { specReload } from './spec-reload.ts'; import { remarkImageReferences } from './src/lib/remark-image-references.ts'; +import { rehypeCodeOptions } from './src/lib/transformer-language.ts'; import { staticFunctionsBase } from './static-functions-base.ts'; import { staticImages } from './static-images.ts'; @@ -37,7 +38,8 @@ export default defineConfig(async ({ command, isPreview }) => { mdxOptions: { remarkImageOptions: { publicDir: publicDir || undefined, external: false }, // A function, so it runs ahead of the preset's own plugins, `remarkImage` among them. - remarkPlugins: (plugins) => [remarkImageReferences, [remarkJsxImages, { publicDir }], ...plugins] + remarkPlugins: (plugins) => [remarkImageReferences, [remarkJsxImages, { publicDir }], ...plugins], + rehypeCodeOptions } } }), diff --git a/src/actions/portal/generate.ts b/src/actions/portal/generate.ts index 2a1f42b3b..ac126945f 100644 --- a/src/actions/portal/generate.ts +++ b/src/actions/portal/generate.ts @@ -5,6 +5,7 @@ import { CommandMetadata } from '../../types/common/command-metadata.js'; import { DirectoryPath } from '../../types/file/directoryPath.js'; import { PortalContext } from '../../types/portal-context.js'; import { SiteAddress } from '../../types/portal/config/site-address.js'; +import { PortalBuildOptions } from '../../types/portal/portal-source.js'; import { ProjectContext } from '../../types/project-context.js'; import { ActionResult } from '../action-result.js'; import { PreparePortalProjectAction } from './prepare-project.js'; @@ -26,7 +27,8 @@ export class GenerateAction { project: ProjectContext, portalDirectory: DirectoryPath, force: boolean, - zipPortal: boolean + zipPortal: boolean, + build: PortalBuildOptions ): Promise => { if (project.isSourceDirectory(portalDirectory)) { this.prompts.directoryCannotBeSame(portalDirectory); @@ -41,7 +43,8 @@ export class GenerateAction { } const portalContext = new PortalContext(portalDirectory); - return await new PreparePortalProjectAction(this.configDir, this.commandMetadata, this.authKey).execute(project, { + const prepare = new PreparePortalProjectAction(this.configDir, this.commandMetadata, this.authKey); + return await prepare.execute(project, build, { confirm: () => this.confirmOverwrite(portalContext, portalDirectory, force), onPrepared: (portalProject, source) => this.build(portalProject, source.config.siteAddress(), portalContext, portalDirectory, zipPortal) diff --git a/src/actions/portal/prepare-project.ts b/src/actions/portal/prepare-project.ts index 1aea7782d..415d5bc98 100644 --- a/src/actions/portal/prepare-project.ts +++ b/src/actions/portal/prepare-project.ts @@ -6,7 +6,7 @@ import { PreparePortalProjectPrompts } from '../../prompts/portal/prepare-projec import { CommandMetadata } from '../../types/common/command-metadata.js'; import { DirectoryPath } from '../../types/file/directoryPath.js'; import { PortalArtifacts } from '../../types/portal/portal-artifacts.js'; -import { PortalSource } from '../../types/portal/portal-source.js'; +import { PortalBuildOptions, PortalSource } from '../../types/portal/portal-source.js'; import { ProjectContext } from '../../types/project-context.js'; import { ActionResult } from '../action-result.js'; @@ -36,6 +36,7 @@ export class PreparePortalProjectAction { /** Takes the caller's next step rather than returning, because its temporary directories must outlive this call. */ public readonly execute = async ( project: ProjectContext, + build: PortalBuildOptions, { confirm = async () => true, onPrepared }: PreparationSteps ): Promise => { const sourceDirectory = project.sourceDirectory(); @@ -63,7 +64,7 @@ export class PreparePortalProjectAction { } // Ahead of the server run, which can take minutes: a mistake or a question should not wait on it. - const source = await project.portalSource().resolve(); + const source = await project.portalSource().resolve(build); if (source.isErr()) { this.prompts.sourceProblem(source.error, sourceDirectory); return ActionResult.failed(); @@ -72,6 +73,9 @@ export class PreparePortalProjectAction { this.prompts.contentNotices(source.value.contentNotices, sourceDirectory); this.prompts.unmergedSpecs(source.value.unmergedSpecs, sourceDirectory); this.prompts.leftOutSpecs(source.value.leftOutSpecs, sourceDirectory); + if (source.value.config.usesGoogleAnalytics()) { + this.prompts.googleAnalyticsCountsPageChanges(); + } if (!(await confirm())) { return ActionResult.cancelled(); diff --git a/src/actions/portal/serve.ts b/src/actions/portal/serve.ts index 1c190afeb..8c644e9a5 100644 --- a/src/actions/portal/serve.ts +++ b/src/actions/portal/serve.ts @@ -9,7 +9,7 @@ import { ProjectContext } from '../../types/project-context.js'; import { isSkippedByGlob } from '../../types/portal/content-tree.js'; import { GeneratedPages } from '../../types/portal/generated-pages.js'; import { PortalArtifacts } from '../../types/portal/portal-artifacts.js'; -import { PortalSettings, PortalSource, WatchedSource } from '../../types/portal/portal-source.js'; +import { PortalBuildOptions, PortalSettings, PortalSource, WatchedSource } from '../../types/portal/portal-source.js'; import { PreviewConfig } from '../../types/portal/preview-config.js'; import { PreviewContent } from '../../types/portal/preview-content.js'; import { PreviewSpecs } from '../../types/portal/preview-specs.js'; @@ -45,9 +45,11 @@ export class PortalServeAction { project: ProjectContext, port: number, openInBrowser: boolean, + build: PortalBuildOptions, onServing?: () => void ): Promise => { - return await new PreparePortalProjectAction(this.configDir, this.commandMetadata, this.authKey).execute(project, { + const prepare = new PreparePortalProjectAction(this.configDir, this.commandMetadata, this.authKey); + return await prepare.execute(project, build, { onPrepared: async (portalProject, source, artifacts) => { const servePort = await this.networkService.getServerPort([port, 3000, 3001, 3002]); if (servePort !== port) { @@ -73,13 +75,20 @@ export class PortalServeAction { // adds and removes, and which the root nav.json makes tabs of or places in Home. let generatedPages = source.generatedPages; const contentWatch = this.watchContent(project, source, () => generatedPages, portalProject.projectDirectory); - const configWatch = this.watchConfig(project, source, artifacts, portalProject.projectDirectory, (settings) => { - const sectionsChanged = !settings.generatedPages.makesSameSectionsAs(generatedPages); - generatedPages = settings.generatedPages; - if (sectionsChanged) { - contentWatch?.recheck(); + const configWatch = this.watchConfig( + project, + source, + artifacts, + portalProject.projectDirectory, + build, + (settings) => { + const sectionsChanged = !settings.generatedPages.makesSameSectionsAs(generatedPages); + generatedPages = settings.generatedPages; + if (sectionsChanged) { + contentWatch?.recheck(); + } } - }); + ); const specWatch = this.watchSpecs(project, source); const closeWatches = async () => { await specWatch?.close(); @@ -122,6 +131,7 @@ export class PortalServeAction { source: PortalSource, artifacts: PortalArtifacts, portalProjectDirectory: DirectoryPath, + build: PortalBuildOptions, onApplied: (settings: PortalSettings) => void ): FileWatch | undefined { const sourceDirectory = project.sourceDirectory(); @@ -129,7 +139,7 @@ export class PortalServeAction { const preview = new PreviewConfig(source.config, source.staticDirectory !== null); const applyEdit = async () => { - const reloaded = await sourceContext.resolveSettings(source.suggestedSite); + const reloaded = await sourceContext.resolveSettings(source.suggestedSite, build); if (reloaded.isErr()) { preview.refuse(); this.prompts.configRejected(reloaded.error, sourceDirectory); diff --git a/src/actions/quickstart.ts b/src/actions/quickstart.ts index 1c620ffe7..7b7b2069d 100644 --- a/src/actions/quickstart.ts +++ b/src/actions/quickstart.ts @@ -244,6 +244,7 @@ export class QuickstartAction { project, DEFAULT_PORTAL_PORT, true, + { analytics: true }, () => this.prompts.nextSteps(configFile) ); diff --git a/src/commands/portal/generate.ts b/src/commands/portal/generate.ts index a4f1223cd..87ba963e9 100644 --- a/src/commands/portal/generate.ts +++ b/src/commands/portal/generate.ts @@ -28,6 +28,7 @@ The portal is built on your machine and written as static files for any static h default: false, description: 'write the generated portal as a .zip archive.' }), + ...FlagsProvider.noAnalytics, ...FlagsProvider.input, ...FlagsProvider.destination('portal', 'portal'), ...FlagsProvider.force, @@ -36,7 +37,7 @@ The portal is built on your machine and written as static files for any static h async run(): Promise { const { - flags: { input, destination, force, zip: zipPortal, 'auth-key': authKey } + flags: { input, destination, force, zip: zipPortal, 'no-analytics': noAnalytics, 'auth-key': authKey } } = await this.parse(PortalGenerate); const project = ProjectContext.at(input); @@ -47,7 +48,9 @@ The portal is built on your machine and written as static files for any static h intro('Generate Portal'); const action = new GenerateAction(this.getConfigDir(), commandMetadata, authKey); - const result = await action.execute(project, project.portalDirectory(destination), force, zipPortal); + const result = await action.execute(project, project.portalDirectory(destination), force, zipPortal, { + analytics: !noAnalytics + }); outro(result); } diff --git a/src/commands/portal/serve.ts b/src/commands/portal/serve.ts index ba4d41c1c..e13b4bf72 100644 --- a/src/commands/portal/serve.ts +++ b/src/commands/portal/serve.ts @@ -36,13 +36,14 @@ Nothing is written to disk; run 'apimatic portal generate' to produce the static description: 'open the portal in the default browser.', default: false }), + ...FlagsProvider.noAnalytics, ...FlagsProvider.input, ...FlagsProvider.authKey }; public async run() { const { - flags: { input, port, open, 'auth-key': authKey } + flags: { input, port, open, 'no-analytics': noAnalytics, 'auth-key': authKey } } = await this.parse(PortalServe); const commandMetadata: CommandMetadata = { @@ -52,7 +53,7 @@ Nothing is written to disk; run 'apimatic portal generate' to produce the static intro('Portal Serve'); const action = new PortalServeAction(this.getConfigDir(), commandMetadata, authKey); - const result = await action.execute(ProjectContext.at(input), port, open); + const result = await action.execute(ProjectContext.at(input), port, open, { analytics: !noAnalytics }); outro(result); } diff --git a/src/prompts/portal/prepare-project.ts b/src/prompts/portal/prepare-project.ts index cf50a4be3..24ce0f2e6 100644 --- a/src/prompts/portal/prepare-project.ts +++ b/src/prompts/portal/prepare-project.ts @@ -41,6 +41,16 @@ export class PreparePortalProjectPrompts { reportAuthorizationFailure(failure); } + /** The portal reports its own page views, so a GA4 stream that also counts history changes counts each page twice. */ + public googleAnalyticsCountsPageChanges() { + const message = + `Google Analytics is set, so the portal sends its own page views. In GA4, turn off the stream's ` + + `"Page changes based on browser history events" (Admin → Data streams → your stream → Enhanced ` + + `measurement → Page views → advanced settings), or every page change counts twice. ` + + `See the analytics page on ${f.link('https://docs.apimatic.io/v4/')}.`; + log.warn(message); + } + public sourceNotZipped(problem: FileProblem, sourceDirectory: DirectoryPath) { log.error(notZippedForUpload(sourceDirectory, problem.reason)); } diff --git a/src/types/flags-provider.ts b/src/types/flags-provider.ts index 44f7a516e..899b955c0 100644 --- a/src/types/flags-provider.ts +++ b/src/types/flags-provider.ts @@ -33,6 +33,13 @@ export class FlagsProvider { }; } + public static readonly noAnalytics = { + 'no-analytics': Flags.boolean({ + default: false, + description: "leave out the Google Tag Manager and Google Analytics tags set in 'portal.analytics'." + }) + }; + // Auth key group public static authKey = { 'auth-key': Flags.string({ diff --git a/src/types/portal-source-context.ts b/src/types/portal-source-context.ts index f81e4e271..8dd06d313 100644 --- a/src/types/portal-source-context.ts +++ b/src/types/portal-source-context.ts @@ -30,6 +30,7 @@ import { MissingFile, MissingImage, MissingStaticFile, + PortalBuildOptions, PortalScaffoldProblem, PortalSettings, PortalSource, @@ -135,7 +136,7 @@ export class PortalSourceContext { } /** Reads and validates the whole source directory, or reports the first problem found. */ - public async resolve(): Promise> { + public async resolve(build: PortalBuildOptions): Promise> { const document = await this.readConfigDocument(); if (document.isErr()) { return err(document.error); @@ -149,7 +150,7 @@ export class PortalSourceContext { } const { specs, suggestedSite, unmergedSpecs, leftOutSpecs } = discovered.value; - const settings = await this.settingsFrom(document.value, suggestedSite); + const settings = await this.settingsFrom(document.value, suggestedSite, build); if (settings.isErr()) { return err(settings.error); } @@ -279,17 +280,21 @@ export class PortalSourceContext { * is accepted exactly when a build would accept it. `suggested` is what `resolve` found in the * specifications, which are not read again; changing them needs a restart anyway. */ - public async resolveSettings(suggested: SuggestedSite | null): Promise> { + public async resolveSettings( + suggested: SuggestedSite | null, + build: PortalBuildOptions + ): Promise> { const document = await this.readConfigDocument(); if (document.isErr()) { return err(document.error); } - return this.settingsFrom(document.value, suggested); + return this.settingsFrom(document.value, suggested, build); } private async settingsFrom( document: ApimaticConfigDocument, - suggested: SuggestedSite | null + suggested: SuggestedSite | null, + build: PortalBuildOptions ): Promise> { const settings = PortalSourceContext.parseSettings(document, suggested); if (settings.isErr()) { @@ -301,7 +306,7 @@ export class PortalSourceContext { if (missingFiles.length > 0) { return err({ kind: 'missingStaticFiles', files: missingFiles }); } - return ok(settings.value); + return ok(build.analytics ? settings.value : { ...settings.value, config: settings.value.config.withoutVendors() }); } private async readConfigDocument(): Promise> { diff --git a/src/types/portal/config/analytics-config.ts b/src/types/portal/config/analytics-config.ts new file mode 100644 index 000000000..76ec59d2b --- /dev/null +++ b/src/types/portal/config/analytics-config.ts @@ -0,0 +1,118 @@ +import { err, ok, Result } from 'neverthrow'; +import { isJsonObject } from '../../../utils/json-utils.js'; +import { allOf, namespace, nonEmptyString, optional, Parsed, required, unknownKeys } from './fields.js'; + +/** From a GTM environment's own snippet, so a staging build can still be checked in GTM. */ +export interface GoogleTagManagerEnvironment { + auth: string; + preview: string; +} + +export interface GoogleTagManagerSetting { + containerId: string; + environment: GoogleTagManagerEnvironment | null; +} + +export interface GoogleAnalyticsSetting { + measurementId: string; +} + +/** Public values: they sit in every page's scripts. */ +export interface PortalAnalytics { + googleTagManager: GoogleTagManagerSetting | null; + googleAnalytics: GoogleAnalyticsSetting | null; + keepQueryParams: string[]; +} + +const KNOWN = ['googleTagManager', 'googleAnalytics', 'keepQueryParams']; + +export class AnalyticsConfig { + private constructor( + private readonly googleTagManager: GoogleTagManagerSetting | null, + private readonly googleAnalytics: GoogleAnalyticsSetting | null, + private readonly keepQueryParams: string[] + ) {} + + public static readonly defaults = new AnalyticsConfig(null, null, []); + + public static parse(value: unknown, path: string): Parsed { + return namespace(value, path).andThen((data) => + allOf( + unknownKeys(data, KNOWN, path), + Result.combineWithAllErrors([ + optional(data.googleTagManager, (vendor) => googleTagManager(vendor, `${path}.googleTagManager`)), + optional(data.googleAnalytics, (vendor) => googleAnalytics(vendor, `${path}.googleAnalytics`)), + keptQueryParams(data.keepQueryParams, `${path}.keepQueryParams`) + ]) + ).map(([gtm, ga, keep]) => new AnalyticsConfig(gtm, ga, keep)) + ); + } + + /** `portal generate` and `portal serve` warn when this is true: the customer has a GA4 stream setting to turn off. */ + public usesGoogleAnalytics(): boolean { + return this.googleAnalytics !== null; + } + + public identity(): PortalAnalytics { + return { + googleTagManager: this.googleTagManager, + googleAnalytics: this.googleAnalytics, + keepQueryParams: this.keepQueryParams + }; + } + + /** For a staging build: neither vendor tag loads, while a reported address still keeps the same names. */ + public withoutVendors(): AnalyticsConfig { + return new AnalyticsConfig(null, null, this.keepQueryParams); + } +} + +// Each ID is required and nothing more: its format is the vendor's to check, since a wrong value fails there, not here. +function googleTagManager(value: unknown, path: string): Parsed { + if (!isJsonObject(value)) { + return err([`'${path}' must be a JSON object with 'containerId'.`]); + } + return allOf( + unknownKeys(value, ['containerId', 'environment'], path), + Result.combineWithAllErrors([ + required(value.containerId, `${path}.containerId`, nonEmptyString), + optional(value.environment, (given) => environment(given, `${path}.environment`)) + ]) + ).map(([containerId, environment]) => ({ containerId, environment })); +} + +function environment(value: unknown, path: string): Parsed { + if (!isJsonObject(value)) { + return err([`'${path}' must be a JSON object with 'auth' and 'preview'.`]); + } + return allOf( + unknownKeys(value, ['auth', 'preview'], path), + Result.combineWithAllErrors([ + required(value.auth, `${path}.auth`, nonEmptyString), + required(value.preview, `${path}.preview`, nonEmptyString) + ]) + ).map(([auth, preview]) => ({ auth, preview })); +} + +function googleAnalytics(value: unknown, path: string): Parsed { + if (!isJsonObject(value)) { + return err([`'${path}' must be a JSON object with 'measurementId'.`]); + } + return allOf( + unknownKeys(value, ['measurementId'], path), + Result.combineWithAllErrors([required(value.measurementId, `${path}.measurementId`, nonEmptyString)]) + ).map(([measurementId]) => ({ measurementId })); +} + +/** Names a reported address keeps, beyond the campaign names it always keeps. */ +function keptQueryParams(value: unknown, path: string): Parsed { + if (value === undefined) { + return ok([]); + } + if (!Array.isArray(value)) { + return err([`'${path}' must be a list of query parameter names.`]); + } + return Result.combineWithAllErrors(value.map((name, index) => nonEmptyString(name, `${path}[${index}]`))).mapErr( + (errors) => errors.flat() + ); +} diff --git a/src/types/portal/config/fields.ts b/src/types/portal/config/fields.ts index 4755f3d46..ef581704a 100644 --- a/src/types/portal/config/fields.ts +++ b/src/types/portal/config/fields.ts @@ -52,11 +52,12 @@ export function lightDark( if (!isJsonObject(value)) { return err([`'${path}' must be a string, or an object with 'light' and 'dark'.`]); } - const mode = (name: 'light' | 'dark'): Parsed => - value[name] === undefined ? err([`'${path}.${name}' is required.`]) : parse(value[name], `${path}.${name}`); return allOf( unknownKeys(value, ['light', 'dark'], path), - Result.combineWithAllErrors([mode('light'), mode('dark')]) + Result.combineWithAllErrors([ + required(value.light, `${path}.light`, parse), + required(value.dark, `${path}.dark`, parse) + ]) ).map(([light, dark]) => ({ light, dark, single: false })); } @@ -64,6 +65,15 @@ export function optional(value: unknown, parse: (present: unknown) => Parsed< return value === undefined ? ok(null) : parse(value); } +/** Present, then parsed: a field left out is named as missing rather than as the wrong type. */ +export function required( + value: unknown, + path: string, + parse: (present: unknown, path: string) => Parsed +): Parsed { + return value === undefined ? err([`'${path}' is required.`]) : parse(value, path); +} + export function optionalBoolean(value: unknown, path: string, fallback: boolean): Parsed { if (value === undefined) { return ok(fallback); diff --git a/src/types/portal/config/seo-config.ts b/src/types/portal/config/seo-config.ts new file mode 100644 index 000000000..e775fdd5f --- /dev/null +++ b/src/types/portal/config/seo-config.ts @@ -0,0 +1,30 @@ +import { Result } from 'neverthrow'; +import { allOf, namespace, nonEmptyString, optional, Parsed, unknownKeys } from './fields.js'; + +export interface PortalSeo { + /** The content value of Google's site verification meta tag, for Search Console. */ + googleSiteVerification: string | null; +} + +const KNOWN = ['googleSiteVerification']; + +export class SeoConfig { + private constructor(private readonly googleSiteVerification: string | null) {} + + public static readonly defaults = new SeoConfig(null); + + public static parse(value: unknown, path: string): Parsed { + return namespace(value, path).andThen((data) => + allOf( + unknownKeys(data, KNOWN, path), + Result.combineWithAllErrors([ + optional(data.googleSiteVerification, (given) => nonEmptyString(given, `${path}.googleSiteVerification`)) + ]) + ).map(([googleSiteVerification]) => new SeoConfig(googleSiteVerification)) + ); + } + + public identity(): PortalSeo { + return { googleSiteVerification: this.googleSiteVerification }; + } +} diff --git a/src/types/portal/portal-config.ts b/src/types/portal/portal-config.ts index 56cf2ce4b..acc020305 100644 --- a/src/types/portal/portal-config.ts +++ b/src/types/portal/portal-config.ts @@ -2,10 +2,12 @@ import { err, ok, Result } from 'neverthrow'; import { isJsonObject } from '../../utils/json-utils.js'; import { UrlPath } from '../file/urlPath.js'; import { AiConfig } from './config/ai-config.js'; +import { AnalyticsConfig, PortalAnalytics } from './config/analytics-config.js'; import { BrandConfig, ColorMode } from './config/brand-config.js'; import { allOf, optional, Parsed, unknownKeys } from './config/fields.js'; import { Link } from './config/link.js'; import { NavigationConfig } from './config/navigation-config.js'; +import { PortalSeo, SeoConfig } from './config/seo-config.js'; import { SiteAddress } from './config/site-address.js'; import { SiteConfig, SuggestedSite } from './config/site-config.js'; import { StaticAsset } from './config/static-asset.js'; @@ -35,11 +37,13 @@ export interface PortalIdentity { links: PortalLink[]; /** Whether each page offers to open itself in an external AI assistant. */ pageActions: boolean; + analytics: PortalAnalytics; + seo: PortalSeo; } const BLOCK = 'portal'; -const NAMESPACES = ['site', 'brand', 'navigation', 'ai']; +const NAMESPACES = ['site', 'brand', 'navigation', 'ai', 'analytics', 'seo']; /** The one setting outside the namespaces, named as the portal artifacts endpoint reads it. */ const PLUGIN_URL = 'pluginUrl'; @@ -50,6 +54,8 @@ export class PortalConfig { private readonly brand: BrandConfig, private readonly navigation: NavigationConfig, private readonly ai: AiConfig, + private readonly analytics: AnalyticsConfig, + private readonly seo: SeoConfig, private readonly pluginAddress: UrlPath | null ) {} @@ -60,6 +66,8 @@ export class PortalConfig { BrandConfig.defaults, NavigationConfig.defaults, AiConfig.defaults, + AnalyticsConfig.defaults, + SeoConfig.defaults, null ); } @@ -86,6 +94,8 @@ export class PortalConfig { BrandConfig.parse(block.brand, `${BLOCK}.brand`), NavigationConfig.parse(block.navigation, `${BLOCK}.navigation`), AiConfig.parse(block.ai, `${BLOCK}.ai`), + AnalyticsConfig.parse(block.analytics, `${BLOCK}.analytics`), + SeoConfig.parse(block.seo, `${BLOCK}.seo`), optional(block.pluginUrl, (value) => secureAddress(value, `${BLOCK}.${PLUGIN_URL}`)) ]) ).map((settings) => new PortalConfig(...settings)); @@ -113,6 +123,11 @@ export class PortalConfig { return this.brand.files(); } + /** `portal generate` and `portal serve` warn when this is true: the customer has a GA4 stream setting to turn off. */ + public usesGoogleAnalytics(): boolean { + return this.analytics.usesGoogleAnalytics(); + } + public identity(): PortalIdentity { const address = this.site.siteAddress(); const logo = this.brand.logoImages(); @@ -125,11 +140,26 @@ export class PortalConfig { favicon: favicon === null ? null : { url: favicon.portalPath(), type: favicon.imageType() }, colorMode: this.brand.mode(), links: this.navigation.headerLinks().map(portalLink), - pageActions: this.ai.offersPageActions() + pageActions: this.ai.offersPageActions(), + analytics: this.analytics.identity(), + seo: this.seo.identity() }; } - /** Every namespace included, defaults and all, which is what quickstart writes. */ + /** The same portal with neither vendor tag, for a staging build under `--no-analytics`. */ + public withoutVendors(): PortalConfig { + return new PortalConfig( + this.site, + this.brand, + this.navigation, + this.ai, + this.analytics.withoutVendors(), + this.seo, + this.pluginAddress + ); + } + + /** Every namespace included, defaults and all, which is what quickstart writes; `analytics` and `seo` start unset. */ public toJSON(): PortalBlock { return { site: this.site.toJSON(), diff --git a/src/types/portal/portal-source.ts b/src/types/portal/portal-source.ts index bf5c8ccf8..c5adac07c 100644 --- a/src/types/portal/portal-source.ts +++ b/src/types/portal/portal-source.ts @@ -47,6 +47,12 @@ export interface PortalSource extends PortalSettings { contentNotices: ContentNotices; } +/** What a run's flags change in the portal it builds from the source. */ +export interface PortalBuildOptions { + /** False under `--no-analytics`: the portal loads neither vendor tag. */ + analytics: boolean; +} + /** Why a source directory could not be written; each variant maps to its own message. */ export type PortalScaffoldProblem = | { kind: 'configUnreadable' } diff --git a/test/actions/portal/generate.test.ts b/test/actions/portal/generate.test.ts index c5f30bf22..72f610d51 100644 --- a/test/actions/portal/generate.test.ts +++ b/test/actions/portal/generate.test.ts @@ -38,12 +38,13 @@ describe('GenerateAction', () => { let authorize: sinon.SinonStub; let build: sinon.SinonStub; - const execute = (projectDirectory = FIXTURE, force = false, zip = false) => + const execute = (projectDirectory = FIXTURE, force = false, zip = false, analytics = true) => new GenerateAction(new DirectoryPath(root), COMMAND_METADATA, 'auth-key').execute( ProjectContext.in(projectDirectory), portalDirectory, force, - zip + zip, + { analytics } ); const inPortal = (relative: string) => fs.existsSync(path.join(portalDirectory.toString(), relative)); @@ -119,7 +120,9 @@ describe('GenerateAction', () => { it('fails when the source and destination are the same directory', async () => { const action = new GenerateAction(new DirectoryPath(root), COMMAND_METADATA); - const result = await action.execute(ProjectContext.in(FIXTURE), FIXTURE.join('src'), false, false); + const result = await action.execute(ProjectContext.in(FIXTURE), FIXTURE.join('src'), false, false, { + analytics: true + }); expect(result.isFailed()).to.be.true; expect(prompts.directoryCannotBeSame.calledOnce).to.be.true; diff --git a/test/actions/portal/prepare-project-stubs.ts b/test/actions/portal/prepare-project-stubs.ts index 5357b97e1..28f6909ff 100644 --- a/test/actions/portal/prepare-project-stubs.ts +++ b/test/actions/portal/prepare-project-stubs.ts @@ -1,3 +1,5 @@ +import fs from 'fs'; +import path from 'path'; import { ok } from 'neverthrow'; import sinon from 'sinon'; import { PortalProjectService } from '../../../src/infrastructure/portal-project-service'; @@ -34,6 +36,20 @@ export function completeArtifacts( ); } +/** A copy of `fixture` at `directory`, its `portal.analytics` set to `analytics`. */ +export function fixtureWithAnalytics( + fixture: DirectoryPath, + directory: DirectoryPath, + analytics: object +): DirectoryPath { + fs.cpSync(fixture.toString(), directory.toString(), { recursive: true }); + const configFile = path.join(directory.toString(), 'src', 'apimatic.json'); + const config = JSON.parse(fs.readFileSync(configFile, 'utf8')); + config.portal.analytics = analytics; + fs.writeFileSync(configFile, JSON.stringify(config)); + return directory; +} + /** * What `PreparePortalProjectAction` reaches for, stubbed the same way for both commands that run * it. A test that cares about one of these overrides it afterwards; the defaults are the happy path. diff --git a/test/actions/portal/prepare-project.test.ts b/test/actions/portal/prepare-project.test.ts index cbb8aa5bb..cb60ea153 100644 --- a/test/actions/portal/prepare-project.test.ts +++ b/test/actions/portal/prepare-project.test.ts @@ -1,4 +1,6 @@ +import fs from 'fs'; import os from 'os'; +import path from 'path'; import AdmZip from 'adm-zip'; import sinon from 'sinon'; import { expect } from 'chai'; @@ -12,7 +14,12 @@ import { FilePath } from '../../../src/types/file/filePath'; import { CommandMetadata } from '../../../src/types/common/command-metadata'; import { ProjectContext } from '../../../src/types/project-context'; import { TempContext } from '../../../src/types/temp-context'; -import { completeArtifacts, PreparePortalProjectStubs, stubPreparePortalProject } from './prepare-project-stubs'; +import { + completeArtifacts, + fixtureWithAnalytics, + PreparePortalProjectStubs, + stubPreparePortalProject +} from './prepare-project-stubs'; const COMMAND_METADATA: CommandMetadata = { commandName: 'portal generate', shell: 'test' }; @@ -31,6 +38,7 @@ describe('PreparePortalProjectAction', () => { const result = await new PreparePortalProjectAction(new DirectoryPath(os.tmpdir()), COMMAND_METADATA).execute( ProjectContext.in(share), + { analytics: true }, { onPrepared } ); @@ -45,9 +53,10 @@ describe('PreparePortalProjectAction', () => { let shared: PreparePortalProjectStubs; let onPrepared: sinon.SinonStub; - const execute = () => + const execute = (analytics = true, project = FIXTURE) => new PreparePortalProjectAction(new DirectoryPath(os.tmpdir()), COMMAND_METADATA).execute( - ProjectContext.in(FIXTURE), + ProjectContext.in(project), + { analytics }, { onPrepared } ); @@ -71,6 +80,46 @@ describe('PreparePortalProjectAction', () => { expect(uploaded.filter((entry) => entry.startsWith('static/'))).to.be.empty; }); + describe('with both vendors set', () => { + let root: string; + const project = () => + fixtureWithAnalytics(FIXTURE, new DirectoryPath(root), { + googleTagManager: { containerId: 'GTM-ABC123' }, + googleAnalytics: { measurementId: 'G-ABC123' } + }); + + beforeEach(() => { + root = fs.mkdtempSync(path.join(os.tmpdir(), 'portal-prepare-')); + }); + + afterEach(() => { + fs.rmSync(root, { recursive: true, force: true }); + }); + + it('warns that Google Analytics counts page changes, before the artifacts are asked for', async () => { + await execute(true, project()); + + expect(shared.prompts.googleAnalyticsCountsPageChanges.calledOnce).to.be.true; + expect(shared.prompts.googleAnalyticsCountsPageChanges.calledBefore(shared.artifacts)).to.be.true; + expect(onPrepared.firstCall.args[1].config.usesGoogleAnalytics()).to.be.true; + }); + + it('prepares the project, and hands on the source, with neither vendor tag and no warning under --no-analytics', async () => { + await execute(false, project()); + + expect(shared.prepare.firstCall.args[1].config.identity().analytics.googleTagManager).to.be.null; + expect(onPrepared.firstCall.args[1].config.identity().analytics.googleTagManager).to.be.null; + expect(onPrepared.firstCall.args[1].config.usesGoogleAnalytics()).to.be.false; + expect(shared.prompts.googleAnalyticsCountsPageChanges.called).to.be.false; + }); + }); + + it('does not warn about Google Analytics when it is not set', async () => { + await execute(); + + expect(shared.prompts.googleAnalyticsCountsPageChanges.called).to.be.false; + }); + it('reports a source it could not zip, without asking for the artifacts', async () => { const problem: FileProblem = { kind: 'zipFailed', reason: 'EBUSY: resource busy or locked' }; sinon.stub(TempContext.prototype, 'zip').resolves(err(problem)); diff --git a/test/actions/portal/serve.test.ts b/test/actions/portal/serve.test.ts index 60f2ba9fb..1d381ae3e 100644 --- a/test/actions/portal/serve.test.ts +++ b/test/actions/portal/serve.test.ts @@ -45,11 +45,12 @@ describe('PortalServeAction', () => { /** Stands in for the preview process dying, with what it printed on the way out. */ let exit: (output: string) => void; - const execute = (projectDirectory = FIXTURE, openInBrowser = false) => + const execute = (projectDirectory = FIXTURE, openInBrowser = false, analytics = true) => new PortalServeAction(new DirectoryPath(root), COMMAND_METADATA, 'auth-key').execute( ProjectContext.in(projectDirectory), PORT, - openInBrowser + openInBrowser, + { analytics } ); /** Stands in for the watch on `directory`, answered by `watching`; any other tree's watch is left alone. */ @@ -608,8 +609,8 @@ describe('PortalServeAction', () => { fs.writeFileSync(path.join(source.toString(), 'apimatic.json'), JSON.stringify(config)); /** Runs the preview until `body` is done with it, then stops it as CTRL+C would. */ - const whileServing = async (body: () => Promise) => { - const running = execute(new DirectoryPath(root)); + const whileServing = async (body: () => Promise, analytics = true) => { + const running = execute(new DirectoryPath(root), false, analytics); const { onChange } = await watched; save = async (config: object) => { writeConfig(config); @@ -890,6 +891,21 @@ describe('PortalServeAction', () => { }); }); + it('leaves the vendor tags out of the project and of each rewrite under --no-analytics', async () => { + const applyConfig = sinon.spy(PortalProjectService.prototype, 'applyConfig'); + const config = originalConfig(); + config.portal.analytics = { googleTagManager: { containerId: 'GTM-ABC123' } }; + writeConfig(config); + + await whileServing(async () => { + config.portal.site.name = 'Renamed API'; + await save(config); + }, false); + + expect(shared.prepare.firstCall.args[1].config.identity().analytics.googleTagManager).to.be.null; + expect(applyConfig.lastCall.args[1].config.identity().analytics.googleTagManager).to.be.null; + }); + it('reports a change it could not write to the preview', async () => { await whileServing(async () => { sinon.stub(PortalProjectService.prototype, 'applyConfig').resolves(err('EACCES: permission denied')); diff --git a/test/actions/quickstart.test.ts b/test/actions/quickstart.test.ts index 66d4cc314..0b571f1d5 100644 --- a/test/actions/quickstart.test.ts +++ b/test/actions/quickstart.test.ts @@ -22,6 +22,7 @@ import { FileDownloadService } from '../../src/infrastructure/services/file-down import { ServiceError } from '../../src/infrastructure/service-error'; import { UrlPath } from '../../src/types/file/urlPath'; import { ProjectContext } from '../../src/types/project-context'; +import { PortalConfig } from '../../src/types/portal/portal-config'; import { completeArtifacts } from './portal/prepare-project-stubs'; const COMMAND_METADATA: CommandMetadata = { commandName: 'portal quickstart', shell: 'test' }; @@ -107,6 +108,7 @@ describe('QuickstartAction', () => { .stub(PortalArtifactsService.prototype, 'generate') .resolves(ok(completeArtifacts([Language.TYPESCRIPT, Language.PYTHON]))); const prepare = sinon.stub(PortalProjectService.prototype, 'prepare').resolves(err('stopped here')); + const withoutVendors = sinon.spy(PortalConfig.prototype, 'withoutVendors'); await execute(); @@ -127,6 +129,7 @@ describe('QuickstartAction', () => { // prepares a project. expect(artifacts.called, 'the wizard asked for the artifacts').to.be.true; expect(prepare.called, 'the wizard reached the preview').to.be.true; + expect(withoutVendors.called, 'the preview counts like a hosted portal').to.be.false; }); it('asks for nothing more and stops when no language is chosen', async () => { diff --git a/test/commands/portal/build-options.ts b/test/commands/portal/build-options.ts new file mode 100644 index 000000000..ab7d09d4d --- /dev/null +++ b/test/commands/portal/build-options.ts @@ -0,0 +1,35 @@ +import os from 'os'; +import sinon from 'sinon'; +import { Config } from '@oclif/core'; +import { err, ok } from 'neverthrow'; +import { PortalAuthorizationService } from '../../../src/infrastructure/services/portal-authorization-service.js'; +import { PortalSourceContext } from '../../../src/types/portal-source-context.js'; +import { stubPreparePortalProject } from '../../actions/portal/prepare-project-stubs.js'; + +const FIXTURE = 'test/resources/portal-inputs/default'; + +/** Just enough of oclif's config for a command to parse its flags and name its config directory. */ +const config = { + configDir: os.tmpdir(), + shell: 'test', + runHook: async () => ({ successes: [], failures: [] }) +} as unknown as Config; + +/** Runs a portal command up to its read of the source, and gives what its flags asked that read for. */ +export async function buildOptionsOf( + command: new (argv: string[], config: Config) => { run(): Promise }, + argv: string[] +): Promise { + stubPreparePortalProject(); + sinon.stub(PortalAuthorizationService.prototype, 'authorize').resolves(ok(undefined)); + const resolve = sinon.stub(PortalSourceContext.prototype, 'resolve').resolves(err({ kind: 'missingConfig' })); + sinon.stub(process.stdout, 'write').returns(true); + const exitCode = process.exitCode; + try { + await new command([...argv, '--input', FIXTURE], config).run(); + } finally { + process.exitCode = exitCode; + sinon.restore(); + } + return resolve.firstCall.args[0]; +} diff --git a/test/commands/portal/generate-flags.test.ts b/test/commands/portal/generate-flags.test.ts new file mode 100644 index 000000000..b5917aad4 --- /dev/null +++ b/test/commands/portal/generate-flags.test.ts @@ -0,0 +1,10 @@ +import { expect } from 'chai'; +import PortalGenerate from '../../../src/commands/portal/generate.js'; +import { buildOptionsOf } from './build-options.js'; + +describe('portal generate flags', () => { + it('reads the source without the vendor tags under --no-analytics, and with them otherwise', async () => { + expect(await buildOptionsOf(PortalGenerate, ['--no-analytics'])).to.deep.equal({ analytics: false }); + expect(await buildOptionsOf(PortalGenerate, [])).to.deep.equal({ analytics: true }); + }); +}); diff --git a/test/commands/portal/serve-flags.test.ts b/test/commands/portal/serve-flags.test.ts new file mode 100644 index 000000000..f3607c004 --- /dev/null +++ b/test/commands/portal/serve-flags.test.ts @@ -0,0 +1,10 @@ +import { expect } from 'chai'; +import PortalServe from '../../../src/commands/portal/serve.js'; +import { buildOptionsOf } from './build-options.js'; + +describe('portal serve flags', () => { + it('reads the source without the vendor tags under --no-analytics, and with them otherwise', async () => { + expect(await buildOptionsOf(PortalServe, ['--no-analytics'])).to.deep.equal({ analytics: false }); + expect(await buildOptionsOf(PortalServe, [])).to.deep.equal({ analytics: true }); + }); +}); diff --git a/test/e2e/portal-build.test.ts b/test/e2e/portal-build.test.ts index 3bf144d25..84489d291 100644 --- a/test/e2e/portal-build.test.ts +++ b/test/e2e/portal-build.test.ts @@ -39,6 +39,8 @@ interface BuiltPortal { root: string; project: DirectoryPath; output: DirectoryPath; + /** What the build read: the fixture, or its copy when settings were added to it. */ + source: DirectoryPath; } interface Delivered { @@ -64,12 +66,22 @@ function deliveredInto( ); } -/** Resolves, prepares, builds and saves a fixture as `portal generate` does. */ -async function buildFixture(name: string, delivered: Delivered = {}): Promise { - const fixture = new DirectoryPath(process.cwd()).join('test/resources/portal-inputs').join(name).join('src'); +/** Resolves, prepares, builds and saves a fixture as `portal generate` does, with `settings` added to its `portal` block. */ +async function buildFixture(name: string, delivered: Delivered = {}, settings?: object): Promise { + let fixture = new DirectoryPath(process.cwd()).join('test/resources/portal-inputs').join(name).join('src'); const root = canonical(fs.mkdtempSync(path.join(os.tmpdir(), 'portal-e2e-'))); - const source = (await new PortalSourceContext(fixture).resolve())._unsafeUnwrap(); + if (settings !== undefined) { + // A copy, so the fixture the other suites read stays as it is. + const copy = new DirectoryPath(root).join('src'); + fs.cpSync(fixture.toString(), copy.toString(), { recursive: true }); + const configFile = path.join(copy.toString(), 'apimatic.json'); + const config = JSON.parse(fs.readFileSync(configFile, 'utf8')); + fs.writeFileSync(configFile, JSON.stringify({ ...config, portal: { ...config.portal, ...settings } })); + fixture = copy; + } + + const source = (await new PortalSourceContext(fixture).resolve({ analytics: true }))._unsafeUnwrap(); const project = new DirectoryPath(root).join('build'); fs.mkdirSync(project.toString(), { recursive: true }); @@ -85,7 +97,7 @@ async function buildFixture(name: string, delivered: Delivered = {}): Promise { if (built === undefined) throw new Error(`${name} is not built`); @@ -104,7 +116,7 @@ function portalBuilt(name: string, delivered: Delivered = {}) { }; before(async () => { - built = await buildFixture(name, delivered); + built = await buildFixture(name, delivered, settings); }); after(() => removeBuilt(built)); @@ -112,6 +124,7 @@ function portalBuilt(name: string, delivered: Delivered = {}) { return { output: () => have().output, project: () => have().project, + source: () => have().source, read: (relative: string) => fs.readFileSync(path.join(have().output.toString(), relative), 'utf8'), exists: (relative: string) => fs.existsSync(path.join(have().output.toString(), relative)) }; @@ -179,8 +192,14 @@ const stylesheetOf = (output: DirectoryPath) => { (enabled ? describe : describe.skip)('portal build (end to end)', function () { this.timeout(10 * 60 * 1000); - const fixture = new DirectoryPath(process.cwd()).join('test/resources/portal-inputs/default/src'); - const portal = portalBuilt('default', { codeSampleCatalogs: CODE_SAMPLES }); + const portal = portalBuilt( + 'default', + { codeSampleCatalogs: CODE_SAMPLES }, + { + analytics: { googleTagManager: { containerId: 'GTM-E2ETEST' }, googleAnalytics: { measurementId: 'G-E2ETEST' } }, + seo: { googleSiteVerification: 'e2e-verification' } + } + ); const { read, exists } = portal; /** The prerendered server-function cache entries carrying the sidebar tree. */ @@ -248,6 +267,54 @@ const stylesheetOf = (output: DirectoryPath) => { expect(read('index.html')).to.contain(' + fs + .readdirSync(portal.output().toString(), { recursive: true, withFileTypes: true }) + .filter((entry) => entry.isFile() && entry.name.endsWith('.html')) + .map((entry) => path.relative(portal.output().toString(), path.join(entry.parentPath, entry.name))); + + it('tells the browser both vendor IDs in a script, and names the tag host in no prerendered page', () => { + const scripts = scriptsOf(portal.output()); + expect(scripts.some(({ text }) => text.includes('GTM-E2ETEST') && text.includes('G-E2ETEST'))).to.be.true; + // The loader itself, not only the identity file the IDs sit in. + expect(scripts.some(({ text }) => text.includes('gtm.js?id=') && text.includes('/gtag/js?id='))).to.be.true; + for (const page of pages()) { + expect(read(page), page).to.not.contain('googletagmanager.com'); + } + }); + + it('carries the verification meta on every prerendered page', () => { + expect(pages()).to.have.length.greaterThan(3); + for (const page of pages()) { + expect(read(page), page).to.contain(' { + const parts = read('api/apimatic-calculator/simple-calculator/Calculate/index.html').split( + 'data-portal-playground' + ); + expect(parts, 'one element').to.have.length(2); + // What Fumadocs' playground renders on the server: its header, with the method, the route and the trigger. + expect(parts[1].slice(0, 2000)).to.match(/>GET<[\s\S]*\{operation\}[\s\S]*aria-haspopup="dialog"/); + expect(parts[0].slice(parts[0].lastIndexOf(' { + // The marked element's one child, past React's own comment, is the sample's block, with the command in it. + expect(read('api/apimatic-calculator/simple-calculator/Calculate/index.html')).to.match( + /data-private="">(?:)*)[\s\S])*>curl<[\s\S]*?> -X<[\s\S]*?> GET { + // Fumadocs' own button, in the card's header: after the title, before the header closes. + expect(read('api/apimatic-calculator/simple-calculator/Calculate/index.html')).to.match( + />Example Response<\/span>(?:(?!<\/div>)[\s\S])*]*\baria-live=/ + ); + }); + it('keeps the server-side specification loader out of the browser bundle', () => { const scripts = fs .readdirSync(path.join(portal.output().toString(), 'assets')) @@ -288,13 +355,13 @@ const stylesheetOf = (output: DirectoryPath) => { // published: `portal.server.ts` holds the absolute path of every specification, and the // prepared project's own location has no business in the output either. it('publishes neither the specification paths nor the project directory', () => { - expect(filesNaming(portal.project().toString(), fixture.join('spec').toString())).to.deep.equal([]); + expect(filesNaming(portal.project().toString(), portal.source().join('spec').toString())).to.deep.equal([]); }); // `defineDocs({ dir })` compiles its directory into the client bundle as the collection's // `base`, which is why the project reads a copy of the content by a relative name. it('publishes no absolute path from the build machine at all', () => { - expect(filesNaming(fixture.join('content').toString(), fixture.toString())).to.deep.equal([]); + expect(filesNaming(portal.source().join('content').toString(), portal.source().toString())).to.deep.equal([]); }); it('writes the sidebar tree to one cache file instead of into every page payload', () => { diff --git a/test/e2e/portal-serve.test.ts b/test/e2e/portal-serve.test.ts index b11324e75..d9f8ee159 100644 --- a/test/e2e/portal-serve.test.ts +++ b/test/e2e/portal-serve.test.ts @@ -30,7 +30,7 @@ const enabled = process.env.APIMATIC_E2E === '1'; const root = canonical(fs.mkdtempSync(path.join(os.tmpdir(), 'portal-serve-e2e-'))); roots.push(root); - const resolved = (await new PortalSourceContext(source).resolve())._unsafeUnwrap(); + const resolved = (await new PortalSourceContext(source).resolve({ analytics: true }))._unsafeUnwrap(); const delivered = path.join(root, 'delivered'); fs.mkdirSync(delivered, { recursive: true }); fs.writeFileSync(path.join(delivered, 'typescript.zip'), 'PK typescript'); diff --git a/test/infrastructure/portal-pages-service.test.ts b/test/infrastructure/portal-pages-service.test.ts index 65fb95b61..3f88fdf83 100644 --- a/test/infrastructure/portal-pages-service.test.ts +++ b/test/infrastructure/portal-pages-service.test.ts @@ -90,7 +90,7 @@ describe('PortalPagesService', () => { 'install="npm install @acme/calc" packageUrl="https://www.npmjs.com/package/@acme/calc" registry="npm" />' ); expect(read('sdks/typescript.mdx')).to.contain( - '' ); }); diff --git a/test/infrastructure/portal-project-service.test.ts b/test/infrastructure/portal-project-service.test.ts index 5724fe4cd..9c3a74d43 100644 --- a/test/infrastructure/portal-project-service.test.ts +++ b/test/infrastructure/portal-project-service.test.ts @@ -540,6 +540,28 @@ describe('PortalProjectService', () => { const themeFile = () => path.join(project.toString(), 'src/styles/theme.css'); const identityFile = () => path.join(project.toString(), 'portal.identity.json'); + it('writes the vendors the config holds, and none from a config without them', async () => { + const config = configFor({ + site: { name: 'My API' }, + analytics: { googleTagManager: { containerId: 'GTM-ABC123' }, googleAnalytics: { measurementId: 'G-ABC123' } } + }); + (await service.prepare(project, sourceFor({ config: config.withoutVendors() }), NO_ARTIFACTS))._unsafeUnwrap(); + + expect(readIdentity().analytics).to.deep.equal({ + googleTagManager: null, + googleAnalytics: null, + keepQueryParams: [] + }); + + expect((await service.applyConfig(project, settingsFor(config)))._unsafeUnwrap()).to.be.true; + + expect(readIdentity().analytics).to.deep.equal({ + googleTagManager: { containerId: 'GTM-ABC123', environment: null }, + googleAnalytics: { measurementId: 'G-ABC123' }, + keepQueryParams: [] + }); + }); + it('writes nothing, and says so, when the block makes the same site', async () => { const config = configFor({ site: { name: 'My API' }, brand: { colors: { primary: '#1d4ed8' } } }); (await service.prepare(project, sourceFor({ config }), NO_ARTIFACTS))._unsafeUnwrap(); diff --git a/test/portal-template.test.ts b/test/portal-template.test.ts index 5c5c4f321..51aba5680 100644 --- a/test/portal-template.test.ts +++ b/test/portal-template.test.ts @@ -16,6 +16,7 @@ import { GENERATED_INCLUDES_DIRECTORY_NAME } from '../src/types/portal/page-frag import { PortalIdentity } from '../src/types/portal/portal-config'; import type { BuildPaths } from '../portal-template/portal-config'; import type { CodeSamplesFile as TemplateCodeSamplesFile } from '../portal-template/src/lib/code-samples.server'; +import { languageAliases } from '../portal-template/src/lib/languages'; import type { Portal } from '../portal-template/src/lib/portal-types'; /** True only when the two types are identical, every nested field and union member included. */ @@ -232,12 +233,7 @@ describe('portal template packaging', () => { /** The language ids the bundle imports a grammar for. */ const bundledIds = (): string[] => [...source().matchAll(/shiki\/dist\/langs\/([\w-]+)\.mjs/g)].map((m) => m[1]); - const keys = (): Set => { - const text = source(); - const block = /const aliases[^{]*{([\s\S]*?)\n};/.exec(text); - const aliasKeys = [...(block?.[1] ?? '').matchAll(/^\s*'?([\w#-]+)'?\s*:/gm)].map((m) => m[1]); - return new Set([...bundledIds(), ...aliasKeys]); - }; + const keys = (): Set => new Set([...bundledIds(), ...Object.keys(languageAliases)]); it('names every grammar it imports by a file that exists', async () => { const shiki = path.dirname(createRequire(import.meta.url).resolve('shiki/package.json')); @@ -265,8 +261,7 @@ describe('portal template packaging', () => { }); it('points every alias at a language it actually bundles', () => { - const block = /const aliases[^{]*{([\s\S]*?)\n};/.exec(source()); - const targets = [...(block?.[1] ?? '').matchAll(/:\s*'([\w-]+)'/g)].map((m) => m[1]); + const targets = Object.values(languageAliases); const bundled = new Set(bundledIds()); expect(targets).to.not.be.empty; diff --git a/test/portal-template/analytics.test.ts b/test/portal-template/analytics.test.ts new file mode 100644 index 000000000..8b04e0057 --- /dev/null +++ b/test/portal-template/analytics.test.ts @@ -0,0 +1,772 @@ +import { expect } from 'chai'; +import { Analytics, pageLocation, PortalEventName, PortalEvents } from '../../portal-template/src/lib/analytics'; +import type { PortalAnalytics } from '../../portal-template/src/lib/portal-types'; +import { Adapter, adapters } from '../../portal-template/src/lib/vendor-tags'; + +// The list is written out here, not imported: the test is the contract, and a name the module drops fails it. +const KEPT_NAMES = [ + '_gl', + 'gclid', + 'gbraid', + 'wbraid', + 'gad_source', + 'dclid', + 'fbclid', + 'msclkid', + 'ttclid', + 'twclid', + 'li_fat_id', + 'mc_cid', + '_hsenc', + '_hsmi' +]; + +describe('pageLocation', () => { + const page = 'https://docs.test/guides/quickstart'; + + it('drops the query and the # part', () => { + expect(pageLocation(`${page}?tab=python&page=2#install`, [])).to.equal(page); + expect(pageLocation(`${page}#install`, [])).to.equal(page); + }); + + it('keeps campaign tags', () => { + expect(pageLocation(`${page}?utm_source=newsletter&utm_medium=email&session=abc`, [])).to.equal( + `${page}?utm_source=newsletter&utm_medium=email` + ); + }); + + it('keeps HubSpot ad tags', () => { + expect(pageLocation(`${page}?hsa_acc=1&hsa_cam=2&session=abc`, [])).to.equal(`${page}?hsa_acc=1&hsa_cam=2`); + }); + + it('keeps each ad-click and cross-domain tag', () => { + for (const name of KEPT_NAMES) { + expect(pageLocation(`${page}?${name}=x&session=abc`, []), name).to.equal(`${page}?${name}=x`); + } + }); + + it("keeps the customer's own names", () => { + expect(pageLocation(`${page}?campaign_id=7&session=abc`, ['campaign_id'])).to.equal(`${page}?campaign_id=7`); + }); + + it('drops a name that only starts with a kept one', () => { + expect(pageLocation(`${page}?gclidx=1`, [])).to.equal(page); + }); + + // No platform reads it from the address, and a customer can add a name but cannot take one out. + it('drops ref, which sites use for codes of their own, unless the customer keeps it', () => { + expect(pageLocation(`${page}?ref=invite-4821`, [])).to.equal(page); + expect(pageLocation(`${page}?ref=newsletter`, ['ref'])).to.equal(`${page}?ref=newsletter`); + }); + + it('leaves the address otherwise unchanged', () => { + expect(pageLocation(page, [])).to.equal(page); + expect(pageLocation('https://docs.test/', [])).to.equal('https://docs.test/'); + expect(pageLocation('https://docs.test/docs/api/pets/Get%20Pets', [])).to.equal( + 'https://docs.test/docs/api/pets/Get%20Pets' + ); + expect(pageLocation('http://localhost:3000/guides/quickstart', [])).to.equal( + 'http://localhost:3000/guides/quickstart' + ); + }); +}); + +describe('PortalEvents', () => { + // The compiler holds this table to the interface: a missing event, a missing key, or an extra key on an event with + // keys does not compile; an event with no keys takes none at report(). + const events: { [E in PortalEventName]: Record } = { + docs_page_view: { page_title: true }, + docs_markdown_copy: {}, + docs_plugin_install: {}, + docs_sdk_download: { language: true }, + docs_code_copy: { language: true }, + docs_search: { search_term: true, result: true, result_count: true }, + docs_not_found: { page_referrer: true }, + docs_api_request: { endpoint: true, status: true, duration_ms: true } + }; + + // Customers build GTM triggers and GA4 reports on these. They are plain text here, apart from the interface, so + // a rename or a new key is a change made in this list on purpose, never the side effect of a refactor. + it('ships exactly these events, each with exactly these keys', () => { + expect(Object.entries(events).map(([name, keys]) => [name, Object.keys(keys)])).to.deep.equal([ + ['docs_page_view', ['page_title']], + ['docs_markdown_copy', []], + ['docs_plugin_install', []], + ['docs_sdk_download', ['language']], + ['docs_code_copy', ['language']], + ['docs_search', ['search_term', 'result', 'result_count']], + ['docs_not_found', ['page_referrer']], + ['docs_api_request', ['endpoint', 'status', 'duration_ms']] + ]); + }); + + it('names every event docs_ plus lowercase snake_case, at most 40 characters', () => { + for (const name of Object.keys(events)) { + expect(name).to.match(/^docs_[a-z0-9_]+$/); + expect(name.length, name).to.be.at.most(40); + } + }); + + // GA4 takes at most 25 parameters per event, and report() adds page_location to each. + it('gives every event at most 24 keys, so 25 with page_location', () => { + for (const [name, keys] of Object.entries(events)) { + expect(Object.keys(keys).length, name).to.be.at.most(24); + } + }); +}); + +interface FakeScript { + async: boolean; + src: string; + textContent: string; +} + +interface FakeWindow { + location: URL & { reload: () => void }; + dataLayer?: unknown[]; + gtag?: (...command: unknown[]) => void; +} + +/** A page in the browser: the `window` and `document` the module reads, and the scripts the loader appends. */ +function browser(href: string, title = 'Quickstart | Acme API', referrer = '') { + const scripts: FakeScript[] = []; + let reloads = 0; + const window: FakeWindow = { location: Object.assign(new URL(href), { reload: () => (reloads += 1) }) }; + const document = { + title, + referrer, + createElement: (): FakeScript => ({ async: false, src: '', textContent: '' }), + head: { + append: (script: FakeScript) => scripts.push(script), + querySelector: (selector: string) => scripts.find((script) => selector === `script[src="${script.src}"]`) ?? null + } + }; + Object.assign(globalThis, { window, document }); + return { + window, + scripts, + dataLayer: () => window.dataLayer ?? [], + reloads: () => reloads, + go: (next: string, nextTitle = title) => { + window.location.href = next; + document.title = nextTitle; + } + }; +} + +const isArguments = (entry: unknown) => Object.prototype.toString.call(entry) === '[object Arguments]'; +const isPlainObject = (value: unknown): value is Record => + typeof value === 'object' && value !== null && !Array.isArray(value) && !isArguments(value); +const gtagCalls = (entries: unknown[]) => + entries.filter(isArguments).map((entry) => Array.from(entry as ArrayLike)); +const pageViews = (entries: unknown[]) => + entries.filter((entry) => isPlainObject(entry) && entry.event === 'docs_page_view'); +/** What the data layer reads as, once GTM has merged every push: objects recursively, `null` replacing. */ +function mergedLikeGtm(entries: unknown[]): Record { + const merge = (into: Record, from: Record): Record => { + for (const [key, value] of Object.entries(from)) { + const current = into[key]; + into[key] = isPlainObject(value) && isPlainObject(current) ? merge({ ...current }, value) : value; + } + return into; + }; + return entries.filter(isPlainObject).reduce(merge, {}); +} + +const none: PortalAnalytics = { googleTagManager: null, googleAnalytics: null, keepQueryParams: [] }; +const withGtm = (environment: { auth: string; preview: string } | null = null): PortalAnalytics => ({ + ...none, + googleTagManager: { containerId: 'GTM-ABC123', environment } +}); +const withGa4: PortalAnalytics = { ...none, googleAnalytics: { measurementId: 'G-ABC123' } }; +const withBoth: PortalAnalytics = { + ...none, + googleTagManager: withGtm().googleTagManager, + googleAnalytics: withGa4.googleAnalytics +}; +const GTM_SCRIPT = 'https://www.googletagmanager.com/gtm.js?id=GTM-ABC123'; +const GA4_SCRIPT = 'https://www.googletagmanager.com/gtag/js?id=G-ABC123'; + +describe('Analytics', () => { + const quickstart = 'https://docs.test/guides/quickstart'; + const quickstartView = { + event: 'docs_page_view', + docs: { page_title: 'Quickstart | Acme API', page_location: quickstart } + }; + const global = globalThis as { window?: unknown; document?: unknown }; + + afterEach(() => { + delete global.window; + delete global.document; + }); + + describe('with neither vendor set', () => { + it('pushes a reset entry and one clean page view entry, and nothing else', () => { + const page = browser(`${quickstart}?utm_source=newsletter&tab=python#install`); + const analytics = new Analytics(none); + + analytics.start(); + analytics.reportPageView(); + + expect(page.dataLayer()).to.deep.equal([ + { docs: null }, + { + event: 'docs_page_view', + docs: { page_title: 'Quickstart | Acme API', page_location: `${quickstart}?utm_source=newsletter` } + } + ]); + expect(page.window.gtag).to.be.undefined; + expect(page.scripts).to.be.empty; + }); + + it('writes to a data layer the page already has', () => { + const page = browser(quickstart); + const existing = { 'host-tag': true }; + page.window.dataLayer = [existing]; + const analytics = new Analytics(none); + + analytics.start(); + analytics.reportPageView(); + + expect(page.dataLayer()).to.deep.equal([existing, { docs: null }, quickstartView]); + }); + }); + + describe('with Google Tag Manager', () => { + it('pushes the gtm.start entry first, inserts gtm.js, then pushes the page view', () => { + const page = browser(quickstart); + const analytics = new Analytics(withGtm()); + + analytics.start(); + analytics.reportPageView(); + + const [start, reset, view, ...rest] = page.dataLayer(); + expect(start).to.have.property('event', 'gtm.js'); + expect(start).to.have.property('gtm.start').that.is.a('number'); + expect(reset).to.deep.equal({ docs: null }); + expect(view).to.deep.equal(quickstartView); + expect(rest).to.be.empty; + expect(page.scripts.map((script) => script.src)).to.deep.equal([GTM_SCRIPT]); + expect(page.scripts[0].async).to.be.true; + expect(page.window.gtag).to.be.undefined; + }); + + it("escapes the container's ID and the environment's values in the tag's address", () => { + const page = browser(quickstart); + const setting = { containerId: 'GTM-A&B', environment: { auth: 'a&b', preview: 'env 3' } }; + + new Analytics({ ...none, googleTagManager: setting }).start(); + + expect(page.scripts.map((script) => script.src)).to.deep.equal([ + 'https://www.googletagmanager.com/gtm.js?id=GTM-A%26B>m_auth=a%26b>m_preview=env%203>m_cookies_win=x' + ]); + }); + + it("loads the container's environment when one is set", () => { + const page = browser(quickstart); + + new Analytics(withGtm({ auth: 'abc123', preview: 'env-3' })).start(); + + expect(page.scripts.map((script) => script.src)).to.deep.equal([ + `${GTM_SCRIPT}>m_auth=abc123>m_preview=env-3>m_cookies_win=x` + ]); + }); + }); + + describe('with Google Analytics', () => { + it('pushes js and config with its own page view off, and inserts gtag.js', () => { + const page = browser(quickstart); + + new Analytics(withGa4).start(); + + const [js, config, ...rest] = gtagCalls(page.dataLayer()); + expect(js[0]).to.equal('js'); + expect(js[1]).to.be.an.instanceOf(Date); + expect(config).to.deep.equal(['config', 'G-ABC123', { send_page_view: false }]); + expect(rest).to.be.empty; + expect(page.scripts.map((script) => script.src)).to.deep.equal([GA4_SCRIPT]); + expect(page.window.gtag).to.be.a('function'); + }); + + it('sends each page view as page_view, without the prefix, after the reset and event entries', () => { + const page = browser(quickstart); + const analytics = new Analytics(withGa4); + + analytics.start(); + analytics.reportPageView(); + + const entries = page.dataLayer(); + expect(entries).to.have.length(6); + expect(entries[2]).to.deep.equal({ docs: null }); + expect(entries[3]).to.deep.equal(quickstartView); + expect(gtagCalls(entries.slice(4))).to.deep.equal([ + ['set', { page_location: quickstart }], + ['event', 'page_view', quickstartView.docs] + ]); + }); + + it("gives GA4's own events the reported address of each page, never the one in the address bar", () => { + const page = browser('https://docs.test/api/pets/listPets?code=x&state=y#access_token=z', 'List pets'); + const analytics = new Analytics(withGa4); + + analytics.start(); + analytics.reportPageView(); + page.go(`${quickstart}?utm_source=mail&tab=python#install`); + analytics.reportPageView(); + analytics.report('docs_markdown_copy', {}); + + expect(gtagCalls(page.dataLayer()).filter((command) => command[0] === 'set')).to.deep.equal([ + ['set', { page_location: 'https://docs.test/api/pets/listPets' }], + ['set', { page_location: `${quickstart}?utm_source=mail` }] + ]); + }); + + it('pushes Arguments objects, which gtag.js reads, never arrays of the same values', () => { + const page = browser(quickstart); + const analytics = new Analytics(withGa4); + + analytics.start(); + analytics.reportPageView(); + + expect(page.dataLayer().filter(isArguments)).to.have.length(4); + expect(page.dataLayer().some(Array.isArray)).to.be.false; + }); + + it("escapes the measurement ID in the tag's address", () => { + const page = browser(quickstart); + + new Analytics({ ...none, googleAnalytics: { measurementId: 'G-A#B' } }).start(); + + expect(page.scripts.map((script) => script.src)).to.deep.equal([ + 'https://www.googletagmanager.com/gtag/js?id=G-A%23B' + ]); + }); + + it('uses a gtag the page already defines, rather than replacing it', () => { + const page = browser(quickstart); + const calls: unknown[][] = []; + const existing = (...command: unknown[]) => { + calls.push(command); + }; + page.window.gtag = existing; + const analytics = new Analytics(withGa4); + + analytics.start(); + analytics.reportPageView(); + + expect(page.window.gtag).to.equal(existing); + expect(calls.map((command) => command[0])).to.deep.equal(['js', 'config', 'set', 'event']); + expect(page.dataLayer().filter(isArguments)).to.be.empty; + }); + + it("sends through the page's gtag from a second instance, as a config save under portal serve makes", () => { + const page = browser(quickstart); + new Analytics(withGa4).start(); + const second = new Analytics(withGa4); + second.start(); + + second.report('docs_markdown_copy', {}); + + expect(gtagCalls(page.dataLayer()).map((command) => command[0])).to.deep.equal(['js', 'config', 'event']); + }); + }); + + describe('with both vendors', () => { + it('pushes every setup entry once, gtm.start first, before the first event', () => { + const page = browser(quickstart); + const analytics = new Analytics(withBoth); + + analytics.start(); + analytics.reportPageView(); + + const entries = page.dataLayer(); + expect(entries).to.have.length(7); + expect(entries[0]).to.have.property('event', 'gtm.js'); + expect(gtagCalls(entries.slice(1, 3)).map((command) => command[0])).to.deep.equal(['js', 'config']); + expect(entries[3]).to.deep.equal({ docs: null }); + expect(entries[4]).to.deep.equal(quickstartView); + expect(gtagCalls(entries.slice(5)).map((command) => command[0])).to.deep.equal(['set', 'event']); + expect(gtagCalls([entries[6]])[0]).to.deep.equal(['event', 'page_view', quickstartView.docs]); + expect(page.scripts.map((script) => script.src)).to.deep.equal([GTM_SCRIPT, GA4_SCRIPT]); + }); + + it('starts once per page, for a second start and for a second instance alike', () => { + const page = browser(quickstart); + const analytics = new Analytics(withBoth); + + analytics.start(); + analytics.start(); + new Analytics(withBoth).start(); + + expect(page.dataLayer()).to.have.length(3); + expect(page.scripts).to.have.length(2); + expect(page.reloads()).to.equal(0); + }); + + it('reloads the page for a start with other vendors, as a config save under portal serve makes', () => { + const page = browser(quickstart); + new Analytics(withGtm()).start(); + + new Analytics(withBoth).start(); + + expect(page.reloads()).to.equal(1); + expect(page.dataLayer()).to.have.length(1); + expect(page.scripts.map((script) => script.src)).to.deep.equal([GTM_SCRIPT]); + }); + }); + + describe('after a playground sign-in', () => { + it('reports with the OAuth answer stripped from page_location', () => { + const page = browser('https://docs.test/api/pets/listPets#access_token=xyz&state=123', 'List pets'); + const analytics = new Analytics(withBoth); + + analytics.start(); + analytics.reportPageView(); + + expect(pageViews(page.dataLayer())).to.deep.equal([ + { + event: 'docs_page_view', + docs: { page_title: 'List pets', page_location: 'https://docs.test/api/pets/listPets' } + } + ]); + }); + }); + + describe('on the page a playground sign-in returned to', () => { + const answered = 'https://docs.test/api/pets/listPets?code=abc&state=123'; + + it('holds the tags back while the answer is in the address, and loads them once the playground took it out', () => { + const page = browser(answered, 'List pets'); + const analytics = new Analytics(withBoth); + + analytics.start(); + analytics.reportPageView(); + analytics.loadTags(); + + expect(page.scripts).to.be.empty; + expect(pageViews(page.dataLayer())).to.have.length(1); + + page.go('https://docs.test/api/pets/listPets'); + analytics.loadTags(); + analytics.reportPageView(); + + expect(page.scripts.map((script) => script.src)).to.deep.equal([GTM_SCRIPT, GA4_SCRIPT]); + expect(pageViews(page.dataLayer())).to.have.length(1); + }); + }); + + describe('on the OAuth callback', () => { + for (const href of [ + 'https://docs.test/oauth/callback?code=abc&state=123', + 'https://docs.test/oauth/callback/?code=abc&state=123', + 'https://docs.test/oauth/callback#access_token=xyz&state=123' + ]) { + it(`holds the tags and the page view back at ${href}, and inserts the tags on the next page`, () => { + const page = browser(href); + const analytics = new Analytics(withBoth); + + analytics.start(); + analytics.reportPageView(); + + expect(page.dataLayer()).to.have.length(3); + expect(pageViews(page.dataLayer())).to.be.empty; + expect(page.scripts).to.be.empty; + + page.go(quickstart); + analytics.reportPageView(); + analytics.reportPageView(); + + expect(page.scripts.map((script) => script.src)).to.deep.equal([GTM_SCRIPT, GA4_SCRIPT]); + expect(pageViews(page.dataLayer())).to.have.length(1); + }); + + it(`sends nothing for any event reported at ${href}`, () => { + const page = browser(href); + const analytics = new Analytics(withBoth); + analytics.start(); + + analytics.report('docs_code_copy', { language: 'cURL' }); + analytics.report('docs_markdown_copy', {}); + + expect(page.dataLayer()).to.have.length(3); + expect(gtagCalls(page.dataLayer()).map((command) => command[0])).to.deep.equal(['js', 'config']); + }); + } + }); + + describe('every adapter', () => { + const suite: { + vendor: keyof typeof adapters; + settings: PortalAnalytics; + pageViewCall: (entries: unknown[]) => void; + }[] = [ + { + vendor: 'googleTagManager', + settings: withGtm(), + // The data layer entry is the call; GTM sends nothing of its own. + pageViewCall: (entries) => expect(entries.filter(isArguments)).to.be.empty + }, + { + vendor: 'googleAnalytics', + settings: withGa4, + pageViewCall: (entries) => expect(gtagCalls(entries).at(-1)?.slice(0, 2)).to.deep.equal(['event', 'page_view']) + } + ]; + + it('is covered by this suite', () => { + expect(suite.map((row) => row.vendor)).to.have.members(Object.keys(adapters)); + }); + + for (const { vendor, settings, pageViewCall } of suite) { + describe(vendor, () => { + const adapter = (): Adapter => adapters[vendor](settings) ?? expect.fail(`${vendor} builds no adapter`); + + it('builds no adapter from settings without its vendor', () => { + expect(adapters[vendor](none)).to.be.null; + }); + + it('turns no session recording or input capture on, nor so much as names them', () => { + browser(quickstart); + const pushed: unknown[] = []; + adapter().setup(pushed); + + // A later adapter that has to name them, to turn them off, says here how it does. + const named = /record|capture|replay/i; + const entries = pushed.map((entry) => (isArguments(entry) ? Array.from(entry as ArrayLike) : entry)); + expect(JSON.stringify(entries)).to.not.match(named); + expect(adapter().script).to.not.match(named); + }); + + it("turns the vendor's own page view off in its setup", () => { + browser(quickstart); + const pushed: unknown[] = []; + + adapter().setup(pushed); + + expect(pushed).to.not.be.empty; + for (const entry of pushed) { + expect(entry).to.not.have.property('event', 'page_view'); + const [command, , options] = isArguments(entry) ? Array.from(entry as ArrayLike) : []; + if (command === 'config') expect(options).to.include({ send_page_view: false }); + } + }); + + it('maps docs_page_view to its page view call', () => { + const page = browser(quickstart); + const analytics = new Analytics(settings); + + analytics.start(); + analytics.reportPageView(); + + expect(pageViews(page.dataLayer())).to.have.length(1); + pageViewCall(page.dataLayer()); + }); + + it('receives nothing holding code=, token= or a # part from a report made with an OAuth answer in the address', () => { + const page = browser('https://docs.test/api/pets/listPets?code=x&state=y#access_token=z', 'List pets'); + const analytics = new Analytics(settings); + + analytics.start(); + analytics.report('docs_page_view', { page_title: 'List pets' }); + + const received = JSON.stringify( + page.dataLayer().map((entry) => (isArguments(entry) ? Array.from(entry as ArrayLike) : entry)) + ); + expect(received).to.include('https://docs.test/api/pets/listPets'); + expect(received).to.not.match(/code=|token=|#/); + }); + + it('inserts only https scripts, none inline', () => { + expect(adapter().script).to.match(/^https:\/\//); + const page = browser(quickstart); + + new Analytics(settings).start(); + + expect(page.scripts).to.not.be.empty; + for (const script of page.scripts) { + expect(script.src).to.match(/^https:\/\//); + expect(script.textContent).to.equal(''); + } + }); + }); + } + }); + + describe('report', () => { + it('pushes a reset entry right before every event entry, which holds event and docs only', () => { + const page = browser(quickstart); + const analytics = new Analytics(none); + analytics.start(); + + analytics.report('docs_page_view', { page_title: 'A' }); + analytics.report('docs_page_view', { page_title: 'B' }); + + const entries = page.dataLayer(); + expect(entries).to.have.length(4); + for (const index of [1, 3]) { + expect(entries[index - 1]).to.deep.equal({ docs: null }); + expect(Object.keys(entries[index] as object)).to.deep.equal(['event', 'docs']); + } + }); + + it("clears the previous event's details for a tag that reads the merged data layer", () => { + const page = browser(quickstart); + const analytics = new Analytics(none); + analytics.start(); + analytics.report('docs_code_copy', { language: 'python' }); + analytics.report('docs_page_view', { page_title: 'B' }); + + expect(mergedLikeGtm(page.dataLayer()).docs).to.deep.equal({ page_title: 'B', page_location: quickstart }); + const withoutResets = page.dataLayer().filter((entry) => !(isPlainObject(entry) && entry.docs === null)); + expect(mergedLikeGtm(withoutResets).docs).to.have.property('language', 'python'); + }); + + it('reports the page the caller names, not the one the address has moved on to', () => { + const page = browser(quickstart); + const analytics = new Analytics(none); + page.go('https://docs.test/guides/authentication'); + + analytics.report( + 'docs_search', + { search_term: 'auth', result: '/guides/authentication', result_count: 3 }, + quickstart + ); + + expect(page.dataLayer().at(-1)).to.have.nested.property('docs.page_location', quickstart); + }); + }); + + // The root effect calls this once on mount and once per page change the router renders. + describe('reportPageView', () => { + const components = 'https://docs.test/guides/components'; + + it('sends the current page, each with its own title', () => { + const page = browser(quickstart); + const analytics = new Analytics(none); + analytics.start(); + + analytics.reportPageView(); + page.go(components, 'Components | Acme API'); + analytics.reportPageView(); + + expect(pageViews(page.dataLayer())).to.deep.equal([ + quickstartView, + { event: 'docs_page_view', docs: { page_title: 'Components | Acme API', page_location: components } } + ]); + }); + + it('sends none when only the # part or the query changed, or nothing changed', () => { + const page = browser(quickstart); + const analytics = new Analytics(none); + analytics.start(); + + analytics.reportPageView(); + page.go(`${quickstart}#install`); + analytics.reportPageView(); + page.go(`${quickstart}?tab=python`); + analytics.reportPageView(); + analytics.reportPageView(); + + expect(pageViews(page.dataLayer())).to.have.length(1); + }); + + it('sends three for A, then B, then A', () => { + const page = browser(quickstart); + const analytics = new Analytics(none); + analytics.start(); + + analytics.reportPageView(); + page.go(components); + analytics.reportPageView(); + page.go(quickstart); + analytics.reportPageView(); + + expect( + pageViews(page.dataLayer()).map((view) => (view as { docs: { page_location: string } }).docs.page_location) + ).to.deep.equal([quickstart, components, quickstart]); + }); + }); + describe('reportNotFound', () => { + const missing = 'https://docs.acme.com/guides/missing'; + const referrers = (entries: unknown[]) => + entries + .filter((entry) => isPlainObject(entry) && entry.event === 'docs_not_found') + .map((entry) => (entry as { docs: { page_referrer: string } }).docs.page_referrer); + + it('names the portal page the reader left for it, whatever the document says', () => { + const page = browser( + 'https://docs.acme.com/guides/quickstart', + 'Quickstart', + 'https://www.google.com/search?q=acme+docs' + ); + const analytics = new Analytics(none); + analytics.reportPageView(); + page.go(missing); + analytics.reportPageView(); + + analytics.reportNotFound(); + + expect(referrers(page.dataLayer())).to.deep.equal(['https://docs.acme.com/guides/quickstart']); + expect(page.dataLayer().at(-1)).to.have.nested.property('docs.page_location', missing); + }); + + it('names the page left when the missing page’s own view is yet to be reported', () => { + const page = browser( + 'https://docs.acme.com/guides/quickstart', + 'Quickstart', + 'https://www.google.com/search?q=acme+docs' + ); + const analytics = new Analytics(none); + analytics.reportPageView(); + page.go(missing); + + analytics.reportNotFound(); + analytics.reportPageView(); + + expect(referrers(page.dataLayer())).to.deep.equal(['https://docs.acme.com/guides/quickstart']); + }); + + it('names the referrer without its query or # part on a first load, and nothing when the browser sends none', () => { + const fromSearch = browser(missing, 'Not found', 'https://www.google.com/search?q=acme+docs#top'); + new Analytics(none).reportNotFound(); + const typedIn = browser(missing, 'Not found'); + new Analytics(none).reportNotFound(); + + expect(referrers(fromSearch.dataLayer())).to.deep.equal(['https://www.google.com/search']); + expect(referrers(typedIn.dataLayer())).to.deep.equal(['']); + }); + + it('reports a missing page once, however often its page mounts, and the next missing page again', () => { + const page = browser(missing); + const analytics = new Analytics(none); + + analytics.reportNotFound(); + analytics.reportNotFound(); + page.go('https://docs.acme.com/guides/also-missing'); + analytics.reportNotFound(); + + expect(referrers(page.dataLayer())).to.deep.equal(['', '']); + }); + + it('reports a missing page again when the reader comes back to it from another page', () => { + const page = browser('https://docs.acme.com/guides/quickstart'); + const analytics = new Analytics(none); + analytics.reportPageView(); + page.go(missing); + analytics.reportNotFound(); + analytics.reportPageView(); + analytics.reportNotFound(); + page.go('https://docs.acme.com/guides/quickstart'); + analytics.reportPageView(); + page.go(missing); + analytics.reportPageView(); + analytics.reportNotFound(); + + expect(referrers(page.dataLayer())).to.deep.equal([ + 'https://docs.acme.com/guides/quickstart', + 'https://docs.acme.com/guides/quickstart' + ]); + expect(pageViews(page.dataLayer())).to.have.length(4); + }); + }); +}); diff --git a/test/portal-template/api-request.test.ts b/test/portal-template/api-request.test.ts new file mode 100644 index 000000000..d8b33d37d --- /dev/null +++ b/test/portal-template/api-request.test.ts @@ -0,0 +1,54 @@ +import { expect } from 'chai'; +import type { FetchErrorResult, FetchResponseResult } from 'fumadocs-openapi/playground'; +import { apiRequest } from '../../portal-template/src/lib/api-request'; + +describe('apiRequest', () => { + const endpoint = 'GET /{operation}'; + // The request's own address, which holds filled-in values: never reported. + const url = 'https://api.acme.com/v1/calc/SUM?x=4&api_key=s3cret'; + const response = (status: number, duration: number): FetchResponseResult => ({ + type: 'response', + url, + status, + headers: new globalThis.Headers({ 'x-key': 's3cret' }), + body: new ArrayBuffer(0), + duration, + text: () => 's3cret' + }); + const clientError: FetchErrorResult = { type: 'client_error', url, message: 'Failed to fetch' }; + + it('reports a response by its status and its own duration, rounded', () => { + expect(apiRequest(endpoint, response(200, 123.4), 1000, 9000)).to.deep.equal({ + endpoint, + status: '200', + duration_ms: 123 + }); + }); + + // One GA4 dimension holds both forms, so a report filters on `status = 500` and on `status = client_error` alike. + it('reports the status as text either way: the HTTP status in digits, or client_error', () => { + for (const status of [200, 204, 404, 500]) { + expect(apiRequest(endpoint, response(status, 1), null, 0).status).to.equal(String(status)); + } + expect(apiRequest(endpoint, clientError, null, 0).status).to.equal('client_error'); + }); + + it('times a request that never reached the API from when it was sent', () => { + expect(apiRequest(endpoint, clientError, 1000, 1250)).to.deep.equal({ + endpoint, + status: 'client_error', + duration_ms: 250 + }); + }); + + it('gives no duration to a request that failed before it was sent', () => { + expect(apiRequest(endpoint, clientError, null, 1250)).to.deep.include({ status: 'client_error', duration_ms: 0 }); + }); + + it('carries the endpoint, the status and the duration, and nothing of the request', () => { + const reported = apiRequest(endpoint, response(401, 8), null, 0); + + expect(Object.keys(reported).sort()).to.deep.equal(['duration_ms', 'endpoint', 'status']); + expect(JSON.stringify(reported)).to.not.contain('s3cret'); + }); +}); diff --git a/test/portal-template/languages.test.ts b/test/portal-template/languages.test.ts new file mode 100644 index 000000000..d726f8c80 --- /dev/null +++ b/test/portal-template/languages.test.ts @@ -0,0 +1,66 @@ +import { expect } from 'chai'; +import { bundledLanguage, languageId, reportedAliases } from '../../portal-template/src/lib/languages'; +import { Language } from '../../src/types/sdk/generate'; + +describe('languageId', () => { + // A download and a copy both send this, so one GA4 dimension holds one set of values. + it('is the key of every language the CLI generates an SDK in', () => { + for (const language of Object.values(Language)) { + expect(languageId(language)).to.equal(language); + } + }); + + it('names a language by its ID, whichever alias the block was written with', () => { + expect(['ts', 'cs', 'c#', 'py', 'bash', 'sh', 'yml'].map(languageId)).to.deep.equal([ + 'typescript', + 'csharp', + 'csharp', + 'python', + 'shellscript', + 'shellscript', + 'yaml' + ]); + }); + + it('reads a name or an alias written in capitals as the same language', () => { + expect(['TypeScript', 'TS', 'C#', 'JSON'].map(languageId)).to.deep.equal([ + 'typescript', + 'typescript', + 'csharp', + 'json' + ]); + }); + + it('sends a language the bundle does not know in lowercase, so one language is one value', () => { + expect(languageId('plaintext')).to.equal('plaintext'); + expect(['rust', 'Rust', 'Kotlin'].map(languageId)).to.deep.equal(['rust', 'rust', 'kotlin']); + }); + + it('names a language outside the bundle by its ID too, whichever short name the block was written with', () => { + expect(['kt', 'KT', 'rs', 'c++', 'ps1', 'dockerfile'].map(languageId)).to.deep.equal([ + 'kotlin', + 'kotlin', + 'rust', + 'cpp', + 'powershell', + 'docker' + ]); + }); + + // A page's own block in no language reports `plaintext`; a description's reports `text`. + it('reports a block in no language as plaintext, by any of the names Shiki has for it', () => { + expect(['text', 'txt', 'plain', 'plaintext'].map(languageId)).to.deep.equal(Array(4).fill('plaintext')); + }); + + it('gives each short name outside the bundle the ID Shiki gives it, and shadows no bundled name', async () => { + const { bundledLanguagesInfo } = (await import('shiki/bundle/full')) as { + bundledLanguagesInfo: { id: string; aliases?: string[] }[]; + }; + + for (const [alias, id] of Object.entries(reportedAliases)) { + expect(bundledLanguage(alias), alias).to.be.null; + if (id === 'plaintext') continue; + expect(bundledLanguagesInfo.find((entry) => entry.id === id)?.aliases, `${alias} for ${id}`).to.include(alias); + } + }); +}); diff --git a/test/portal-template/oauth-callback.test.ts b/test/portal-template/oauth-callback.test.ts index a370e8dc1..7d016570b 100644 --- a/test/portal-template/oauth-callback.test.ts +++ b/test/portal-template/oauth-callback.test.ts @@ -1,7 +1,13 @@ import { expect } from 'chai'; import type { SecuritySchemeObject } from 'fumadocs-openapi'; import { requestOAuthToken } from 'fumadocs-openapi/playground'; -import { oauthCallback, oauthCallbackPath, takeStartingPage } from '../../portal-template/src/lib/oauth-callback'; +import { + holdsOAuthAnswer, + isOAuthCallbackPath, + oauthCallback, + oauthCallbackPath, + takeStartingPage +} from '../../portal-template/src/lib/oauth-callback'; import { OAUTH_CALLBACK_ADDRESS } from '../../src/types/portal/content-tree'; // The CLI refuses a page of the user's at the address the template serves the callback at. @@ -16,6 +22,45 @@ describe('oauthCallbackPath', () => { * callback takes the note from the same place. The playground's flow is run here, in a stand-in * tab, so a move of the note, as 12.5.7 made from a cookie, fails this test and not a portal. */ +describe('isOAuthCallbackPath', () => { + it('is the callback at the root, and under a base path', () => { + expect(isOAuthCallbackPath('/oauth/callback')).to.be.true; + expect(isOAuthCallbackPath('/docs/oauth/callback', '/docs/')).to.be.true; + }); + + // A static host may answer `/oauth/callback` at `/oauth/callback/`. + it('is the callback with a trailing slash', () => { + expect(isOAuthCallbackPath('/oauth/callback/')).to.be.true; + expect(isOAuthCallbackPath('/docs/oauth/callback/', '/docs/')).to.be.true; + }); + + it('is not the callback at the root when the portal is under a base path, nor any other page', () => { + expect(isOAuthCallbackPath('/oauth/callback', '/docs/')).to.be.false; + expect(isOAuthCallbackPath('/guides/quickstart')).to.be.false; + expect(isOAuthCallbackPath('/oauth/callback/more')).to.be.false; + }); +}); + +describe('holdsOAuthAnswer', () => { + const at = (href: string) => holdsOAuthAnswer(new URL(href)); + + it('holds on the callback, with or without an answer', () => { + expect(at('https://docs.test/oauth/callback')).to.be.true; + expect(at('https://docs.test/oauth/callback?code=abc&state=123')).to.be.true; + }); + + it('holds on a page a sign-in returned to, with a code, a token or an error', () => { + expect(at('https://docs.test/api/pets/listPets?code=abc&state=123')).to.be.true; + expect(at('https://docs.test/api/pets/listPets#access_token=xyz&token_type=Bearer&state=123')).to.be.true; + expect(at('https://docs.test/api/pets/listPets?error=access_denied&state=123')).to.be.true; + }); + + it('does not hold on any other address, a query or a # part of its own included', () => { + expect(at('https://docs.test/api/pets/listPets')).to.be.false; + expect(at('https://docs.test/guides/quickstart?utm_source=mail&code=SAVE10#install')).to.be.false; + }); +}); + describe('takeStartingPage', () => { const origin = 'https://docs.test'; const pathname = '/api/pets/pets/listPets'; diff --git a/test/portal-template/search-report.test.ts b/test/portal-template/search-report.test.ts new file mode 100644 index 000000000..31fa82466 --- /dev/null +++ b/test/portal-template/search-report.test.ts @@ -0,0 +1,64 @@ +import { expect } from 'chai'; +import { searchOutcome, type SearchDialogState } from '../../portal-template/src/lib/search-report'; + +describe('searchOutcome', () => { + const closed: SearchDialogState = { + open: false, + loading: false, + typed: true, + picked: '', + term: 'pets', + resultCount: 3 + }; + + it('waits while the dialog is open, and while the last keystrokes’ results load after it closed', () => { + expect(searchOutcome({ ...closed, open: true })).to.deep.equal({ ended: false }); + expect(searchOutcome({ ...closed, loading: true })).to.deep.equal({ ended: false }); + }); + + it('reports a typed term with the count shown once the results are in', () => { + expect(searchOutcome(closed)).to.deep.equal({ + ended: true, + report: { search_term: 'pets', result: '', result_count: 3 } + }); + }); + + // Fumadocs hands over the pick before the close renders, so a pick made with the hotkey's term counts too. + it('reports the result picked, typed or not', () => { + const picked = 'https://docs.acme.com/api/pets/listPets'; + + expect(searchOutcome({ ...closed, typed: false, picked })).to.deep.equal({ + ended: true, + report: { search_term: 'pets', result: picked, result_count: 3 } + }); + }); + + // Every event's page_location has this shape, so a report can join a search to the page it led to. + it('reports the result as a whole address, without the # part of a heading hit', () => { + const picked = 'https://docs.acme.com/docs/guides/intro#install'; + + expect(searchOutcome({ ...closed, picked })).to.have.nested.property( + 'report.result', + 'https://docs.acme.com/docs/guides/intro' + ); + }); + + it('ends without a report when the reader neither typed nor picked, or left no term', () => { + expect(searchOutcome({ ...closed, typed: false })).to.deep.equal({ ended: true, report: null }); + expect(searchOutcome({ ...closed, term: ' ' })).to.deep.equal({ ended: true, report: null }); + }); + + it('reports the term without the spaces around it', () => { + expect(searchOutcome({ ...closed, term: ' list pets ' })).to.have.nested.property( + 'report.search_term', + 'list pets' + ); + }); + + it('reports at most the 100 characters of a term that GA4 keeps', () => { + expect(searchOutcome({ ...closed, term: 'k'.repeat(300) })).to.have.nested.property( + 'report.search_term', + 'k'.repeat(100) + ); + }); +}); diff --git a/test/prompts/portal/prepare-project.test.ts b/test/prompts/portal/prepare-project.test.ts index 419d40e96..7dacc65f7 100644 --- a/test/prompts/portal/prepare-project.test.ts +++ b/test/prompts/portal/prepare-project.test.ts @@ -12,6 +12,19 @@ describe('PreparePortalProjectPrompts', () => { sinon.restore(); }); + it('says what to turn off in GA4, where, and why', () => { + const warn = sinon.stub(log, 'warn'); + + new PreparePortalProjectPrompts().googleAnalyticsCountsPageChanges(); + + expect(stripVTControlCharacters(String(warn.firstCall.args[0]))).to.equal( + "Google Analytics is set, so the portal sends its own page views. In GA4, turn off the stream's " + + '"Page changes based on browser history events" (Admin → Data streams → your stream → Enhanced ' + + 'measurement → Page views → advanced settings), or every page change counts twice. ' + + 'See the analytics page on https://docs.apimatic.io/v4/.' + ); + }); + // A run delivers everything or nothing, so a gap is the server's to fix. it('names what the artifacts left out, and says to try again', () => { const error = sinon.stub(log, 'error'); diff --git a/test/types/apimatic-config/schema.test.ts b/test/types/apimatic-config/schema.test.ts index 4626ee62e..14718590d 100644 --- a/test/types/apimatic-config/schema.test.ts +++ b/test/types/apimatic-config/schema.test.ts @@ -99,7 +99,13 @@ describe('apimatic.schema.json', () => { { label: 'Home', url: '/' } ] }, - ai: { pageActions: false } + ai: { pageActions: false }, + analytics: { + googleTagManager: { containerId: 'GTM-ABC123', environment: { auth: 'abc', preview: 'env-3' } }, + googleAnalytics: { measurementId: 'G-ABC123' }, + keepQueryParams: ['campaign_id'] + }, + seo: { googleSiteVerification: 'abc' } } ], ['an address with a port', { site: { url: 'https://docs.example.com:8443' } }], @@ -117,7 +123,37 @@ describe('apimatic.schema.json', () => { ['a link through a parent segment', { navigation: { links: [{ label: 'Start', url: '/guides/../start' }] } }], ['a link with two slashes in its query', { navigation: { links: [{ label: 'Next', url: '/start?next=//x' }] } }], ['a context plugin hosted elsewhere', { pluginUrl: 'https://plugins.acme.test/calc.zip?v=2' }], - ['a plugin address with several query parameters', { pluginUrl: 'https://s3.test/calc.zip?a=1&b=2' }] + ['a plugin address with several query parameters', { pluginUrl: 'https://s3.test/calc.zip?a=1&b=2' }], + ['a GTM container', { analytics: { googleTagManager: { containerId: 'GTM-ABC123' } } }], + [ + 'a GTM container with an environment', + { + analytics: { googleTagManager: { containerId: 'GTM-ABC123', environment: { auth: 'abc', preview: 'env-3' } } } + } + ], + ['a GA4 stream', { analytics: { googleAnalytics: { measurementId: 'G-ABC123' } } }], + [ + 'both vendors, with spaces around the IDs', + { + analytics: { + googleTagManager: { containerId: ' GTM-ABC123 ' }, + googleAnalytics: { measurementId: ' G-ABC123 ' } + } + } + ], + ['a kept query parameter name', { analytics: { keepQueryParams: ['campaign_id'] } }], + ['an empty analytics block', { analytics: {} }], + ['a verification value', { seo: { googleSiteVerification: 'abc_123-XYZ' } }], + // The vendors' formats are theirs to check, so each ID and value is any non-blank string. + ['a lowercase container ID', { analytics: { googleTagManager: { containerId: 'gtm-abc123' } } }], + [ + 'an environment value with a space, and a preview without env-', + { analytics: { googleTagManager: { containerId: 'GTM-1', environment: { auth: 'a b', preview: '3' } } } } + ], + ['a Universal Analytics ID as the measurement ID', { analytics: { googleAnalytics: { measurementId: 'UA-1' } } }], + ['a kept name with a space, and an OAuth answer name', { analytics: { keepQueryParams: ['a b', 'code'] } }], + ['an empty list of kept names', { analytics: { keepQueryParams: [] } }], + ['a verification value with a space', { seo: { googleSiteVerification: 'abc 123' } }] ]; const invalid: [string, object][] = [ @@ -219,7 +255,41 @@ describe('apimatic.schema.json', () => { ['a plugin address without a host', { pluginUrl: 'https://' }], ['a plugin address that is not a string', { pluginUrl: 7 }], ['a plugin address with a space', { pluginUrl: 'https://plugins.acme.test/my plugin.zip' }], - ['a plugin address with trailing whitespace', { pluginUrl: 'https://plugins.acme.test/calc.zip ' }] + ['a plugin address with trailing whitespace', { pluginUrl: 'https://plugins.acme.test/calc.zip ' }], + ['analytics that is not an object', { analytics: 'GTM-ABC123' }], + ['an unknown vendor', { analytics: { posthog: {} } }], + ['a bare container ID', { analytics: { googleTagManager: 'GTM-ABC123' } }], + ['a GTM block without its ID', { analytics: { googleTagManager: {} } }], + ['a blank container ID', { analytics: { googleTagManager: { containerId: ' ' } } }], + [ + 'a key beside the container ID', + { analytics: { googleTagManager: { containerId: 'GTM-ABC123', serverUrl: 'x' } } } + ], + [ + 'an environment that is not an object', + { analytics: { googleTagManager: { containerId: 'GTM-ABC123', environment: 'env-3' } } } + ], + [ + 'an environment without its preview', + { analytics: { googleTagManager: { containerId: 'GTM-ABC123', environment: { auth: 'abc' } } } } + ], + ['a GA4 block without its ID', { analytics: { googleAnalytics: {} } }], + ['a measurement ID that is not a string', { analytics: { googleAnalytics: { measurementId: 7 } } }], + ['kept names that are not a list', { analytics: { keepQueryParams: 'campaign_id' } }], + ['a kept name that is not a string', { analytics: { keepQueryParams: [1] } }], + ['seo that is not an object', { seo: 'abc' }], + ['analytics that is null', { analytics: null }], + [ + 'an environment without its auth', + { analytics: { googleTagManager: { containerId: 'GTM-ABC123', environment: { preview: 'env-3' } } } } + ], + [ + 'a GA4 block with a key beside the ID', + { analytics: { googleAnalytics: { measurementId: 'G-ABC123', debug: true } } } + ], + ['a blank kept name', { analytics: { keepQueryParams: [' '] } }], + ['an unknown seo key', { seo: { foo: 1 } }], + ['a blank verification value', { seo: { googleSiteVerification: ' ' } }] ]; for (const [label, block] of valid) { diff --git a/test/types/portal-source-context.test.ts b/test/types/portal-source-context.test.ts index 27d6e4998..cc3c6f4b3 100644 --- a/test/types/portal-source-context.test.ts +++ b/test/types/portal-source-context.test.ts @@ -49,7 +49,7 @@ describe('PortalSourceContext', () => { const REQUIRED_LANGUAGES = /^'languages' must name at least one SDK language/; - const resolve = () => new PortalSourceContext(new DirectoryPath(root)).resolve(); + const resolve = () => new PortalSourceContext(new DirectoryPath(root)).resolve({ analytics: true }); /** The ignored navigation files as the warning names them, relative to the source directory. */ const ignored = (source: PortalSource): string[] => @@ -349,7 +349,7 @@ describe('PortalSourceContext', () => { writeConfig({ brand: { colors: { primary: '#1d4ed8' } } }); const resolved = (await resolve())._unsafeUnwrap(); - const reloaded = (await context().resolveSettings(resolved.suggestedSite))._unsafeUnwrap(); + const reloaded = (await context().resolveSettings(resolved.suggestedSite, { analytics: true }))._unsafeUnwrap(); expect(reloaded.config.toJSON()).to.deep.equal(resolved.config.toJSON()); expect(reloaded.config.siteTitle()).to.equal(resolved.config.siteTitle()); @@ -359,7 +359,7 @@ describe('PortalSourceContext', () => { it('holds the file to the rules resolve holds it to', async () => { writeConfig({}); - const errors = (await context().resolveSettings(null))._unsafeUnwrapErr(); + const errors = (await context().resolveSettings(null, { analytics: true }))._unsafeUnwrapErr(); expect(errors).to.deep.equal({ kind: 'invalidConfig', @@ -371,13 +371,39 @@ describe('PortalSourceContext', () => { it('reports a file the block names that is not on disk', async () => { writeConfig({ site: { name: 'Calc' }, brand: { favicon: 'static/favicon.ico' } }); - expect(missingFiles(await context().resolveSettings(null))).to.deep.equal([ + expect(missingFiles(await context().resolveSettings(null, { analytics: true }))).to.deep.equal([ ['portal.brand.favicon', 'static/favicon.ico', null] ]); }); + it('leaves out the vendor tags under --no-analytics, as resolve does, and keeps the query names to keep', async () => { + writeConfig({ + site: { name: 'Calc' }, + analytics: { googleTagManager: { containerId: 'GTM-ABC123' }, keepQueryParams: ['campaign_id'] } + }); + const off = { analytics: false }; + + const resolved = (await new PortalSourceContext(new DirectoryPath(root)).resolve(off))._unsafeUnwrap(); + const reloaded = (await context().resolveSettings(null, off))._unsafeUnwrap(); + const kept = (await context().resolveSettings(null, { analytics: true }))._unsafeUnwrap(); + + for (const { config } of [resolved, reloaded]) { + expect(config.identity().analytics).to.deep.equal({ + googleTagManager: null, + googleAnalytics: null, + keepQueryParams: ['campaign_id'] + }); + } + expect(kept.config.identity().analytics.googleTagManager).to.deep.equal({ + containerId: 'GTM-ABC123', + environment: null + }); + }); + it('reports a file removed while the preview runs', async () => { - expect((await context().resolveSettings(null))._unsafeUnwrapErr()).to.deep.equal({ kind: 'missingConfig' }); + expect((await context().resolveSettings(null, { analytics: true }))._unsafeUnwrapErr()).to.deep.equal({ + kind: 'missingConfig' + }); }); }); @@ -1531,7 +1557,9 @@ describe('PortalSourceContext', () => { // Named, because nothing suggests a site when the specifications are not read again. writeFile({ portal: { site: { name: 'Calc' } }, languages: { csharp: {} }, plugin: {} }); - const reloaded = (await new PortalSourceContext(new DirectoryPath(root)).resolveSettings(null))._unsafeUnwrap(); + const reloaded = ( + await new PortalSourceContext(new DirectoryPath(root)).resolveSettings(null, { analytics: true }) + )._unsafeUnwrap(); expect(generated(reloaded)).to.deep.equal(['sdks/index.mdx', 'sdks/csharp.mdx', 'context-plugin/index.mdx']); }); @@ -2601,11 +2629,11 @@ describe('PortalSourceContext', () => { it('writes a source directory it accepts itself, once a language is named', async () => { await scaffold(writeSpec({ title: 'Petstore', version: '1' })); - const unnamed = (await new PortalSourceContext(source).resolve())._unsafeUnwrapErr(); + const unnamed = (await new PortalSourceContext(source).resolve({ analytics: true }))._unsafeUnwrapErr(); expect(unnamed.kind === 'invalidConfig' ? unnamed.errors : []).to.have.lengthOf(1); addLanguages(); - const resolved = (await new PortalSourceContext(source).resolve())._unsafeUnwrap(); + const resolved = (await new PortalSourceContext(source).resolve({ analytics: true }))._unsafeUnwrap(); expect(resolved.config.siteTitle()).to.equal('Petstore'); expect(resolved.specs.map((spec) => spec.slug)).to.deep.equal(['petstore']); expect(resolved.contentDirectory).to.not.be.null; @@ -2630,10 +2658,10 @@ describe('PortalSourceContext', () => { it('writes a block that resolves to the portal an empty block makes', async () => { await scaffold(writeSpec({ title: 'Petstore', version: '1', description: 'All the pets.' })); addLanguages(); - const scaffolded = (await new PortalSourceContext(source).resolve())._unsafeUnwrap().config; + const scaffolded = (await new PortalSourceContext(source).resolve({ analytics: true }))._unsafeUnwrap().config; write('project/src/apimatic.json', JSON.stringify({ portal: {}, languages: LANGUAGES })); - const empty = (await new PortalSourceContext(source).resolve())._unsafeUnwrap().config; + const empty = (await new PortalSourceContext(source).resolve({ analytics: true }))._unsafeUnwrap().config; expect(scaffolded.toJSON()).to.deep.equal(empty.toJSON()); expect(scaffolded.identity()).to.deep.equal(empty.identity()); @@ -2671,7 +2699,7 @@ describe('PortalSourceContext', () => { addLanguages(); const contentFiles = fs.readdirSync(path.join(source.toString(), 'content')).sort(); - const scaffolded = (await new PortalSourceContext(source).resolve())._unsafeUnwrap(); + const scaffolded = (await new PortalSourceContext(source).resolve({ analytics: true }))._unsafeUnwrap(); expect(contentFiles).to.deep.equal(['index.md', 'nav.json']); expect(scaffolded.contentNotices.ignoredNavigationFiles).to.deep.equal([]); @@ -2788,7 +2816,7 @@ describe('PortalSourceContext', () => { await adopt(); - const resolved = (await new PortalSourceContext(source).resolve())._unsafeUnwrap(); + const resolved = (await new PortalSourceContext(source).resolve({ analytics: true }))._unsafeUnwrap(); expect(resolved.config.siteTitle()).to.equal('Petstore'); // The one that was there, and no copy of it beside itself. expect(fs.readdirSync(path.join(source.toString(), 'spec'))).to.deep.equal(['petstore.json']); @@ -2901,7 +2929,7 @@ describe('PortalSourceContext', () => { await adopt(); expect(portalBlock().site.name).to.equal(name); - const resolved = (await new PortalSourceContext(source).resolve())._unsafeUnwrap(); + const resolved = (await new PortalSourceContext(source).resolve({ analytics: true }))._unsafeUnwrap(); expect(resolved.config.siteTitle()).to.equal(name); }); }); @@ -2920,7 +2948,7 @@ describe('PortalSourceContext', () => { await adopt(); expect(portalBlock().site.name).to.equal('Alpha'); - expect((await new PortalSourceContext(source).resolve()).isOk()).to.be.true; + expect((await new PortalSourceContext(source).resolve({ analytics: true })).isOk()).to.be.true; }); }); }); diff --git a/test/types/portal/portal-config.test.ts b/test/types/portal/portal-config.test.ts index 6f0e692f3..d90e1cbce 100644 --- a/test/types/portal/portal-config.test.ts +++ b/test/types/portal/portal-config.test.ts @@ -395,6 +395,178 @@ describe('PortalConfig', () => { }); }); + describe('analytics', () => { + const gtm = 'portal.analytics.googleTagManager'; + const ga = 'portal.analytics.googleAnalytics'; + const keep = 'portal.analytics.keepQueryParams'; + + it('tells the browser to load nothing when the block sets nothing', () => { + expect(config({}).identity().analytics).to.deep.equal({ + googleTagManager: null, + googleAnalytics: null, + keepQueryParams: [] + }); + }); + + it('keeps both vendors with their IDs trimmed, the environment and every kept name, an OAuth answer’s included', () => { + const analytics = { + googleTagManager: { containerId: ' GTM-ABC123 ', environment: { auth: 'a1_b-2', preview: 'env-3' } }, + googleAnalytics: { measurementId: ' G-ABC123 ' }, + keepQueryParams: ['campaign_id', ' code '] + }; + + expect(config({ analytics }).identity().analytics).to.deep.equal({ + googleTagManager: { containerId: 'GTM-ABC123', environment: { auth: 'a1_b-2', preview: 'env-3' } }, + googleAnalytics: { measurementId: 'G-ABC123' }, + keepQueryParams: ['campaign_id', 'code'] + }); + }); + + it('refuses a block, a vendor or an environment that is not an object, as a bare ID is the likely slip', () => { + expect(errorsOf({ analytics: 'GTM-ABC123' })).to.deep.equal(["'portal.analytics' must be a JSON object."]); + expect(errorsOf({ analytics: { googleTagManager: 'GTM-ABC123' } })).to.deep.equal([ + `'${gtm}' must be a JSON object with 'containerId'.` + ]); + expect(errorsOf({ analytics: { googleAnalytics: 'G-ABC123' } })).to.deep.equal([ + `'${ga}' must be a JSON object with 'measurementId'.` + ]); + expect( + errorsOf({ analytics: { googleTagManager: { containerId: 'GTM-ABC123', environment: 'env-3' } } }) + ).to.deep.equal([`'${gtm}.environment' must be a JSON object with 'auth' and 'preview'.`]); + }); + + it('requires each ID as a non-empty string, and leaves its format to the vendor', () => { + expect(errorsOf({ analytics: { googleTagManager: {}, googleAnalytics: {} } })).to.deep.equal([ + `'${gtm}.containerId' is required.`, + `'${ga}.measurementId' is required.` + ]); + expect( + errorsOf({ analytics: { googleTagManager: { containerId: ' ' }, googleAnalytics: { measurementId: 1 } } }) + ).to.deep.equal([ + `'${gtm}.containerId' must be a non-empty string.`, + `'${ga}.measurementId' must be a non-empty string.` + ]); + expect( + config({ analytics: { googleTagManager: { containerId: 'gtm-abc123' } } }).identity().analytics.googleTagManager + ).to.deep.equal({ containerId: 'gtm-abc123', environment: null }); + }); + + it('requires both environment values as non-empty strings', () => { + const withEnvironment = (environment: unknown) => + errorsOf({ analytics: { googleTagManager: { containerId: 'GTM-ABC123', environment } } }); + + expect(withEnvironment({})).to.deep.equal([ + `'${gtm}.environment.auth' is required.`, + `'${gtm}.environment.preview' is required.` + ]); + expect(withEnvironment({ auth: '', preview: 3 })).to.deep.equal([ + `'${gtm}.environment.auth' must be a non-empty string.`, + `'${gtm}.environment.preview' must be a non-empty string.` + ]); + }); + + it('names an unknown key beside a vendor or an environment like any other', () => { + expect( + errorsOf({ + analytics: { + posthog: {}, + googleTagManager: { + containerId: 'GTM-ABC123', + serverUrl: 'x', + environment: { auth: 'a', preview: 'env-1', url: 'x' } + }, + googleAnalytics: { measurementId: 'G-ABC123', debug: true } + } + }) + ).to.deep.equal([ + "'portal.analytics.posthog' is not a 'portal' setting.", + `'${gtm}.serverUrl' is not a 'portal' setting.`, + `'${gtm}.environment.url' is not a 'portal' setting.`, + `'${ga}.debug' is not a 'portal' setting.` + ]); + }); + + it('takes a list of kept names, each a non-empty string', () => { + expect(errorsOf({ analytics: { keepQueryParams: 'campaign_id' } })).to.deep.equal([ + `'${keep}' must be a list of query parameter names.` + ]); + expect(errorsOf({ analytics: { keepQueryParams: ['', ' ', 1] } })).to.deep.equal([ + `'${keep}[0]' must be a non-empty string.`, + `'${keep}[1]' must be a non-empty string.`, + `'${keep}[2]' must be a non-empty string.` + ]); + }); + + it('reports every fault at once, unknown keys first', () => { + expect( + errorsOf({ + analytics: { + posthog: {}, + googleTagManager: { containerId: '' }, + googleAnalytics: 'G-1', + keepQueryParams: [1] + } + }) + ).to.deep.equal([ + "'portal.analytics.posthog' is not a 'portal' setting.", + `'${gtm}.containerId' must be a non-empty string.`, + `'${ga}' must be a JSON object with 'measurementId'.`, + `'${keep}[0]' must be a non-empty string.` + ]); + }); + + it('tells the browser to load neither vendor without them, and still which names to keep', () => { + const analytics = { + googleTagManager: { containerId: 'GTM-ABC123' }, + googleAnalytics: { measurementId: 'G-ABC123' }, + keepQueryParams: ['campaign_id'] + }; + const portal = config({ analytics }); + + expect(portal.withoutVendors().identity()).to.deep.equal({ + ...portal.identity(), + analytics: { googleTagManager: null, googleAnalytics: null, keepQueryParams: ['campaign_id'] } + }); + }); + + it('refuses a null block, and an environment without its auth value', () => { + expect(errorsOf({ analytics: null })).to.deep.equal(["'portal.analytics' must be a JSON object."]); + expect( + errorsOf({ analytics: { googleTagManager: { containerId: 'GTM-ABC123', environment: { preview: 'env-3' } } } }) + ).to.deep.equal([`'${gtm}.environment.auth' is required.`]); + }); + + it('keeps an empty list of names as none', () => { + expect(config({ analytics: { keepQueryParams: [] } }).identity().analytics.keepQueryParams).to.deep.equal([]); + }); + + it('uses Google Analytics only with a measurement ID', () => { + expect(config({}).usesGoogleAnalytics()).to.be.false; + expect(config({ analytics: { googleTagManager: { containerId: 'GTM-ABC123' } } }).usesGoogleAnalytics()).to.be + .false; + expect(config({ analytics: { googleAnalytics: { measurementId: 'G-ABC123' } } }).usesGoogleAnalytics()).to.be + .true; + }); + }); + + describe('seo', () => { + it('carries the verification value to the browser, or null without one', () => { + expect(config({ seo: { googleSiteVerification: 'abc_123-XYZ' } }).identity().seo).to.deep.equal({ + googleSiteVerification: 'abc_123-XYZ' + }); + expect(config({}).identity().seo).to.deep.equal({ googleSiteVerification: null }); + }); + + it('refuses a block that is not an object, and a blank value', () => { + expect(errorsOf({ seo: 'abc' })).to.deep.equal(["'portal.seo' must be a JSON object."]); + expect(errorsOf({ seo: null })).to.deep.equal(["'portal.seo' must be a JSON object."]); + expect(errorsOf({ seo: { foo: 1 } })).to.deep.equal(["'portal.seo.foo' is not a 'portal' setting."]); + expect(errorsOf({ seo: { googleSiteVerification: ' ' } })).to.deep.equal([ + "'portal.seo.googleSiteVerification' must be a non-empty string." + ]); + }); + }); + describe('pluginUrl', () => { const REFUSED = "'portal.pluginUrl' must be an address starting with 'https://', with no spaces, for example " + @@ -486,7 +658,9 @@ describe('PortalConfig', () => { { label: 'Status', url: 'https://status.example.com', external: true }, { label: 'Changelog', url: '/changelog', external: false } ], - pageActions: false + pageActions: false, + analytics: { googleTagManager: null, googleAnalytics: null, keepQueryParams: [] }, + seo: { googleSiteVerification: null } }); }); @@ -499,7 +673,9 @@ describe('PortalConfig', () => { favicon: null, colorMode: 'both', links: [], - pageActions: true + pageActions: true, + analytics: { googleTagManager: null, googleAnalytics: null, keepQueryParams: [] }, + seo: { googleSiteVerification: null } }); }); From 8e394e5db35b96ac827f6a310379b3ee7ec099ca Mon Sep 17 00:00:00 2001 From: Muhammad Sohail <62895181+sohail2721@users.noreply.github.com> Date: Mon, 16 Nov 2026 16:01:52 +0500 Subject: [PATCH 4/5] fix(portal): stop a long example response running over the previous and next page cards (#476) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Point 2 of apimatic/apimatic-io#2350: on an operation page, a long "Example Response" ran over the page's previous and next cards. ## What was wrong Since fumadocs-openapi 12.6 the example column of an operation page is sticky and no taller than the window, and the cards in it are meant to shrink to fit. Ours could not. The layout we render around them was a plain block, so each card kept its full height, and a long response ran out of the bottom of the column and over the previous and next cards. Because the column is sticky, the end of that response could not be scrolled to either. ## The fix - **The layout** (`example-layout.tsx`) takes the classes of Fumadocs' own default layout, `flex min-h-0 flex-col`, so the column's height reaches the cards. - **The request card** (`usage-tabs.tsx`) passes that height on at each box down to its code: the tabs, the open tab, the element marked for session replays, the block and its scroller. This is what Fumadocs' own request card does. With the layout change alone the overlap is gone, but our request card keeps its full height and the response card under a long sample is squeezed: to 131 px in a 1617 x 887 window, and to 44 px, its header only, at 1280 x 800. - **The example selector** loses `mb-2`. That margin used to collapse into the request card's own top margin; in a flex column it would add 8 px. The gap under the selector stays 16 px. Below the width where the column sits beside the page, nothing changes: the column is not capped there, and both cards keep their height. ## Pictures A neutral spec with a long request body and a long response, built with `portal generate`. Before, 1617 x 887, scrolled to the end of the page: ![The response card over the previous and next cards](https://gist.githubusercontent.com/sohail2721/09bcf246f8c354c186c77a5ff902f830/raw/example-column-before.png) After, the same view: ![Both cards inside the column, above the previous and next cards](https://gist.githubusercontent.com/sohail2721/09bcf246f8c354c186c77a5ff902f830/raw/example-column-after.png) After, 1280 x 800, at the top of the page: ![Both cards sharing the column](https://gist.githubusercontent.com/sohail2721/09bcf246f8c354c186c77a5ff902f830/raw/example-column-after-1280.png) ## Checked Measured in headless Chrome on a portal built from this branch: | Window | Before | After | | --- | --- | --- | | 1617 x 887 | cards of 636 and 642 px in a 799 px column: 511 px past it, over the footer cards | 382 and 385 px, inside the column | | 1280 x 800 | 598 px past a 712 px column | 338 and 342 px, inside the column | - Each card's code scrolls inside its card. - The TypeScript tab shrinks the same way, and the closed tab stays hidden. - A page with the example selector fits its column too, with the same 16 px under the selector as before. - At 1000 px and 390 px wide, where the column sits under the page, both cards are 636 and 642 px, as before. - `test/e2e/portal-build.test.ts`, the "portal build (end to end)" fixture: 45 passing. That includes a new check of the built page's boxes, the existing cURL marker check, and the template's type-check. I did not run the whole suite, and there is no browser test for this yet: the layout itself can only be held in `apimatic/v4-test-automation`. The other points of the issue are not in this PR. Points 3 to 6 are Fumadocs' own and are reported as fuma-nama/fumadocs#3864 and fuma-nama/fumadocs#3865. 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Muhammad Sohail Co-authored-by: Claude Fable 5.2 --- .../src/components/example-layout.tsx | 7 +++++-- portal-template/src/components/usage-tabs.tsx | 17 ++++++++++------- test/e2e/portal-build.test.ts | 12 ++++++++++++ 3 files changed, 27 insertions(+), 9 deletions(-) diff --git a/portal-template/src/components/example-layout.tsx b/portal-template/src/components/example-layout.tsx index aa3c0a310..911359761 100644 --- a/portal-template/src/components/example-layout.tsx +++ b/portal-template/src/components/example-layout.tsx @@ -21,6 +21,9 @@ interface LayoutSlots { const SelectionContext = createContext(undefined); +/** Fumadocs keeps the example column no taller than the window: each box down to the code passes that height on. */ +export const SHRINKS_WITH_COLUMN = 'flex min-h-0 flex-col'; + // "Example Response" copies through a button of Fumadocs' own in the card's header, which takes no callback. const reportResponseCopy = (event: MouseEvent) => { if (event.target instanceof Element && event.target.closest('button[aria-live]') !== null) reportCodeCopy('json'); @@ -66,7 +69,7 @@ function ExampleLayout({ selector, usageTabs, responseTabs }: Readonly -
+
{selector === null ? null : } {usageTabs}
@@ -92,7 +95,7 @@ function ExampleSelector() { })); return (