feat: TypeScript client + goatcounter-stats web component #10

Merged

synapse merged 1 commit from feat/ts-client into develop

2026-08-21 19:57:21 +00:00

synapse commented

2026-08-21 19:43:34 +00:00

Owner

Implements the ts-client OpenSpec change — operator decision wth: headless client + web component as ONE deliverable, contract-locked, in this repo.

Headless core (@byteflavour/goatcounter-stats-client): typed fetchSummary/fetchPages/fetchOpenApi, Result values instead of exceptions, gateway error codes passed through, network/shape failures classified. Zero runtime dependencies, ESM + d.ts.
<goatcounter-stats> (…/element): shadow-DOM custom element (total, CSS-bar chart, top pages), data-state lifecycle, styleable via --gcs-* custom properties and named parts — plain HTML, Vue, React, Angular, no adapters.
Contract coupling: bun test suite imports the committed openapi.json and asserts path coverage, period/error-code enum equality, and required-field lists. Server and client are now gated on the same snapshot from both sides.
Hermetic: tsc + bun from nixpkgs, no node_modules anywhere. packages.ts-client, checks.ts-build, checks.ts-test in the gate.
Publishing: guarded npm step in release.yml (skips loudly until the runner's ~/.npmrc exists — scope claim in progress), version stamped from the tag ⇒ client version ≡ gateway version. Forgejo npm registry as secondary when configured.
Live-verified against the full local stack: total=45/7 days/top pages typed end-to-end; dead gateway → network; bad period → invalid_period.
Also: .forgejo/pull_request_template.md — this PR is the last one whose creation 404-bursts (fj short-circuits on the first template path from now on).

Full nix flake check green including the new checks.

🤖 Generated with Claude Code

https://claude.ai/code/session_01T5j3dAJVcUjZv9k76sRTt9

Implements the `ts-client` OpenSpec change — operator decision wth: headless client + web component as ONE deliverable, contract-locked, in this repo. - **Headless core** (`@byteflavour/goatcounter-stats-client`): typed fetchSummary/fetchPages/fetchOpenApi, Result values instead of exceptions, gateway error codes passed through, network/shape failures classified. Zero runtime dependencies, ESM + d.ts. - **`<goatcounter-stats>`** (`…/element`): shadow-DOM custom element (total, CSS-bar chart, top pages), `data-state` lifecycle, styleable via `--gcs-*` custom properties and named parts — plain HTML, Vue, React, Angular, no adapters. - **Contract coupling**: bun test suite imports the committed `openapi.json` and asserts path coverage, period/error-code enum equality, and required-field lists. Server and client are now gated on the same snapshot from both sides. - **Hermetic**: tsc + bun from nixpkgs, no node_modules anywhere. `packages.ts-client`, `checks.ts-build`, `checks.ts-test` in the gate. - **Publishing**: guarded npm step in release.yml (skips loudly until the runner's ~/.npmrc exists — scope claim in progress), version stamped from the tag ⇒ client version ≡ gateway version. Forgejo npm registry as secondary when configured. - **Live-verified** against the full local stack: total=45/7 days/top pages typed end-to-end; dead gateway → `network`; bad period → `invalid_period`. - Also: `.forgejo/pull_request_template.md` — this PR is the last one whose creation 404-bursts (fj short-circuits on the first template path from now on). Full `nix flake check` green including the new checks. 🤖 Generated with [Claude Code](https://claude.com/claude-code) https://claude.ai/code/session_01T5j3dAJVcUjZv9k76sRTt9

synapse added 1 commit

2026-08-21 19:43:34 +00:00

feat: TypeScript client + <goatcounter-stats> web component (clients/ts)

ci / gate (pull_request) Successful in 24s

Details

d4cafb6fe5

Headless zero-dependency client (Result-typed, error classification) and
a shadow-DOM custom element styleable via custom properties + parts. 18
bun tests incl. a contract-coupling suite asserting types/paths/enums
against the committed openapi.json — the client-side half of the snapshot
gate. Hermetic toolchain from nixpkgs (tsc build, bun test), no
node_modules. packages.ts-client + checks.{ts-build,ts-test}; guarded
npm publish in the release workflow (version stamped from tag). Book
chapter, demo page, PR template (ends the forgejo-cli 404 burst).

Live-verified against dev-goatcounter + gateway: summary/pages typed
end-to-end, dead-gateway and invalid-period classified correctly.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01T5j3dAJVcUjZv9k76sRTt9

synapse merged commit af196b9c4a into develop

2026-08-21 19:57:21 +00:00

synapse deleted branch feat/ts-client

2026-08-21 19:57:22 +00:00

synapse referenced this pull request from a commit

2026-08-21 19:57:22 +00:00

Merge pull request 'feat: TypeScript client + goatcounter-stats web component' (#10) from feat/ts-client into develop