[kirtimanmishrazipstack]

What

• Gives the new (v1) frontend one shared way to load and save data from the backend.
• Every page now shows loading and errors the same way, so pages don't build their own.
• The demo page uses it to show the organisation's LLM adapters.
• An automatic check stops pages from calling the backend any other way.

Why

• Without it, each page would handle loading and errors in its own way. That causes bugs and errors that users never see. Now every v1 page gets the same behaviour, and it's tested once.

How

• services/http.ts is the only HTTP client, and builds the org-scoped paths (orgPath()). It:
  • adds X-CSRFToken to same-origin POST, PUT, PATCH and DELETE requests;
  • adds an X-Request-ID to every request;
  • rejects with an ApiError;
  • treats only the auth middleware's 401 as session expiry, and redirects once per page load, so concurrent 401s redirect once. A typed 401, such as a provider rejecting its key, is an ordinary client error.
• Errors fall into nine kinds: validation, subscription, unauthenticated, forbidden, not_found, client, server, network, unknown.
  • mapFieldErrors() turns errors for fields the form doesn't show into one form-level error, and gives nothing before the first submit.
• In the TanStack Query defaults (app/query.ts):
  • reads retry twice, and only on network, 502, 503 or 504 errors;
  • mutations never retry;
  • networkMode: "always", so offline fails at once instead of pausing, and a save is never sent later;
  • each failure is reported once: inline by QueryView when the first fetch fails, otherwise as a toast;
  • query keys start with the org id, and each query fetches for the org in its key.
• lint:v1 rejects backend URLs, axios, the client and fetch / XMLHttpRequest / EventSource outside services/ (and a cloud plugin's plugins/<plugin>/services/).
• The rules for writing service modules are in services/README.md.
• To run the v1 tests on Node 26, set NODE_OPTIONS=--no-experimental-webstorage. CI uses Node 22 and needs nothing extra.

Can this PR break any existing features. If yes, please list possible items. If no, please explain why. (PS: Admins do not merge the PR without this section filled)

• No. It only changes the new v1 frontend, which users see only after switching to it. The current frontend is untouched.

Database Migrations

• None

Env Config

• None

Relevant Docs

• Spec: https://zipstack.atlassian.net/wiki/x/FgCYYQ

Related Issues or PRs

• UN-4313
• UN-4314 (sign-in session) will tell this code which organisation the user is in. Until then, the demo page takes it from the page address, which doesn't work on cloud. UN-4314 also moves sign-out on session expiry to the POST logout, since the GET one goes when v0 is retired.
• UN-4290 [FEAT] Add the v1 account menu and organisation switcher #2395 adds a temporary copy of this client. Whichever PR merges second moves that code onto this one. This is still pending.

Dependencies Versions

• None

Notes on Testing

• The new tests, the existing frontend tests and the production build all pass.
• The tests cover:
  • the security token sent with saves;
  • signing the user out when their session ends;
  • requests cancelled when a page closes;
  • each kind of error.
• Tried against a local backend in a browser:
  • the demo page lists the organisation's LLM adapters;
  • when the session ends, the user goes to the sign-in page once;
  • an error from a provider or a connector doesn't sign the user out;
  • offline, the page shows an error instead of loading forever, and a save fails instead of being sent later.

Screenshots

Checklist

I have read and understood the Contribution Guidelines.

🤖 Generated with Claude Code

[kirtimanmishrazipstack]

Standardized review (unstract v2.1.80): REQUEST CHANGES

Summary: Critical: 0 · High: 2 · Medium: 7 · Low: 8 · Lenses run: 19/19 (15 examined, 4 N/A)

• Security deep-dive: done, no findings at confidence >= 8.
• Boundary sweep: 7 sinks traced, clean.
• test:v1 passes on Node 26 (720 tests, 182/182 guardrail fixtures).
• lint:v1, typecheck:v1 and Biome 2.3.13 are clean on the changed files.

Lens checklist

1. Spec & intent: See findings #4
2. Architectural fit: See findings #7, #15, #17
3. Correctness: See findings #1, #6, #10
4. Security: Clean
5. Data integrity: N/A (frontend only)
6. Concurrency: See findings #5, #7
7. API & contract: See findings #3, #11
8. Reliability: See findings #6
9. Performance: Clean
10. Observability: Clean
11. Operational safety: Clean (v1 only, behind the version switch)
12. LLM/agent: N/A
13. Testing: See findings #2, #8, #16
14. Dependencies: Clean (no manifest change)
15. Code quality: See findings #15
16. Doc accuracy: See findings #1, #5, #12, #13, #14
17. Cross-document: See findings #9
18. On-prem: N/A
19. Scaling: N/A

Open questions

• #5: must UN-4314's expiry handler leave the page, or should the latch re-arm?
• #3: for typed 401s, a client-side check or a backend remap of SdkError 401?
• v0 sends subscription_error to /subscription-expired, but v1 shows a toast. Is that intended?
• The defaults keep staleTime: 0 with refetch on focus, so every mounted query refetches on each tab focus. Is that the default you want?
• A page past the end returns 404 "Invalid page.". Should paged queries step back a page?

Unanchored findings

• frontend/src/v1/test/README.md:153 (outside the diff hunk): 9. [Medium] [Lens 17] — This fixture example contradicts the real test/fixtures/adapters.ts

The real file this PR adds has adapterFixtures.llm and adapterHandlers(session, rows, seen), and the new Adapter type needs more fields than this example has (satisfies would fail). L110 uses adapterFixtures.list, which doesn't exist. Suggest deleting the block, pointing to the real file, and fixing L110. Made stale by test/fixtures/adapters.ts:L6.

• frontend/src/v1/README.md:143 (outside the diff hunk): 13. [Low] [Lens 16] — A 401 from a service call now redirects to sign in, so "no … login redirect" is out of date.

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[kirtimanmishrazipstack]

Answers to the findings and questions in the review body. The fixes are in 74db2e1.

• Prompt Studio - Summarize, Output Analyzer and other UI Improvements #9 (test/README.md): fixed. The section now points to test/fixtures/adapters.ts instead of showing an example, and the mock example uses adapterFixtures.llm.
• [WIP] [FEAT] V1 - Time based trials  #13 (README.md:143): fixed. It now says that a page registered before P0-T06 sends the user to sign in only when a service call gets a 401.

Open questions:

• Add support for configuring and using OCR adapters #5 and connectors #3: answered in their threads. The expiry handler must leave the page, and typed 401s are told apart on the client.
• v0's /subscription-expired redirect: v1 not redirecting is intended for now. Plan gates and their redirects belong to UN-4314 (P0-T06: session, guards and plan gates). Until then, a subscription error is a toast that stays until dismissed.
• staleTime: 0 with refetch on focus: keeping TanStack's defaults. Other members change an organisation's data, so returning to the tab should show their changes, and a page mounts only a few queries. A costly or polling query sets its own staleTime.
• A page past the end (404 "Invalid page."): the data layer can't change the page number, because it's part of the query key. Whoever holds the page number steps back to the last page (count) after a delete. services/README.md now says so under pagination.