@cherrypeak-org/cherryboard-web 1.0.1

package/CHANGELOG.md

@@ -0,0 +1,72 @@
+# Changelog
+
+All notable changes to `@cherrypeak-org/cherryboard-web` are documented here.
+This project adheres to [Semantic Versioning](https://semver.org/).
+
+## [1.0.1]
+
+### Fixed
+- **Source maps are no longer published.** 1.0.0 shipped `.map` files whose
+  `sourcesContent` embedded this package's full TypeScript source, so the
+  original code was readable by anyone who downloaded the tarball. Maps are now
+  disabled in the build entirely, which also avoids leaving dangling
+  `sourceMappingURL` comments. The tarball drops from 16 files to 12.
+
+  1.0.0 should be treated as containing published source and is unpublished.
+
+---
+
+## [1.0.0]
+
+First published release.
+
+### Added
+- **Source maps**: `cherryboard-upload-sourcemaps` CLI uploads a build's maps so the
+  backend resolves minified stacks into original files, lines and function names.
+  The `release` passed to `init()` must match the one uploaded.
+- **Next.js server-side capture**: `captureRequestError` for `instrumentation.ts`,
+  covering RSC render, route handler and server action errors.
+- **Discarded-event counts**: `getDiscardedEvents()` reports events dropped by
+  sampling, dedupe, filters, rate limiting or failed sends, so a missing error is
+  explainable instead of silently absent.
+
+### Changed
+- `429` responses are no longer retried. The SDK honours `Retry-After` and pauses
+  sending until it elapses, per the Sentry SDK spec — retrying a rate limit only
+  deepens the backlog. Events keep buffering meanwhile.
+
+### Fixed
+- Closing or unloading while rate-limited scheduled a self-renewing flush timer that
+  outlived the client.
+
+---
+
+## [0.1.0] — Unreleased
+
+Initial release. Browser + React error-tracking client for the CherryBoard dashboard.
+
+### Added
+
+- **Automatic capture**: uncaught errors (`window` `error`), unhandled promise
+  rejections, failed resource loads (img/script/css), and `console.error` /
+  `console.warn` as breadcrumbs.
+- **React layer** (`@cherrypeak-org/cherryboard-web/react`): `ErrorBoundary`,
+  `CherryBoardProvider`, `useCaptureError`, `useCherryBoard`, and
+  `captureRouteError` for the Next.js App Router `error.tsx` / `global-error.tsx`.
+- **Manual API**: `init`, `captureException`, `captureMessage`, `addBreadcrumb`,
+  `setUser`, `setTag`, `setContext`, `flush`, `close`.
+- **Delivery**: batched, wire-compatible with the CherryBoard `/api/v1/errors/batch`
+  ingest endpoint (`X-API-Key`), `fetch` with `keepalive` (survives page unload),
+  exponential-backoff retry (5xx / network only), a durable `localStorage` offline
+  queue, client-side rate limiting, and same-error deduplication.
+- **Data quality**: breadcrumbs (navigation / click / fetch), `release` +
+  `environment` tags, browser/viewport context, `error.cause` chains, and React
+  component stacks.
+- **Privacy**: built-in PII scrubbing (auth headers/tokens, emails, sensitive
+  query params and object keys) plus a `beforeSend` hook, applied before anything
+  leaves the browser.
+- **SSR-safe**: no browser globals are touched at import time; safe to import from
+  React Server Components / the Next.js App Router. The React entry ships
+  `"use client"`.
+- Framework-agnostic core with zero runtime dependencies; `react` / `react-dom`
+  are optional peer dependencies. Dual ESM + CJS builds with type declarations.

package/README.md

@@ -0,0 +1,489 @@
+# @cherrypeak-org/cherryboard-web
+
+Browser & React error tracking for the **CherryBoard** dashboard. Drop it into any
+React app (Next.js, Vite, CRA) and uncaught errors, promise rejections, and React
+render errors are captured, batched, and shipped to your CherryBoard project —
+where they show up as grouped issues alongside your backend errors.
+
+- **Zero-config capture** — global errors, unhandled rejections, resource failures.
+- **React-native** — `ErrorBoundary`, a provider, hooks, and Next.js App Router helpers.
+- **Reliable** — batching, offline queue, retry, dedupe, rate-limiting, `keepalive`.
+- **Private & safe** — PII scrubbing before send, SSR-safe, tiny, zero-dependency core.
+- **Readable stacks** — upload source maps and see original files, lines and functions.
+
+> Wire-compatible with the same `/api/v1/errors` ingest the .NET
+> `CherryPeak.CherryBoard.Client` uses — one dashboard, both stacks.
+
+---
+
+## Contents
+
+1. [Install](#1-install)
+2. [Get an ingest API key](#2-get-an-ingest-api-key)
+3. [Quick start — Next.js (App Router)](#3-quick-start--nextjs-app-router)
+4. [Quick start — Vite / CRA / plain React](#4-quick-start--vite--cra--plain-react)
+5. [Reporting errors manually](#5-reporting-errors-manually)
+6. [Identifying users & adding context](#6-identifying-users--adding-context)
+7. [Configuration reference](#7-configuration-reference)
+8. [What gets captured](#8-what-gets-captured)
+9. [Security & privacy](#9-security--privacy-read-this)
+10. [Troubleshooting](#10-troubleshooting)
+11. [Readable stack traces (source maps)](#11-readable-stack-traces-source-maps)
+12. [Server-side errors (Next.js)](#12-server-side-errors-nextjs)
+13. [Why didn't my error show up?](#13-why-didnt-my-error-show-up)
+
+---
+
+## 1. Install
+
+```bash
+npm install @cherrypeak-org/cherryboard-web
+# or: pnpm add / yarn add
+```
+
+`react` and `react-dom` are **optional peer dependencies** — you only need them if
+you import from `@cherrypeak-org/cherryboard-web/react`. The core works in any browser app.
+
+---
+
+## 2. Get an ingest API key
+
+1. Open the CherryBoard dashboard → your **Project** → the **Environment** you want
+   errors filed under (e.g. *Production*).
+2. Create an **API key** and copy it. This key resolves the project + environment
+   server-side, so front-end errors land in the right place automatically.
+
+> ⚠️ This key ships in your browser bundle and is **public**. That's expected (it's
+> how every browser error tracker works), but see [Security](#9-security--privacy-read-this)
+> for how to keep it safe (write-only scope, CORS, rate limiting).
+
+Put the key and API host in **public** env vars:
+
+```bash
+# .env.local  (Next.js)   — NEXT_PUBLIC_ vars are exposed to the browser
+NEXT_PUBLIC_CHERRYBOARD_KEY=cpd_xxxxxxxxxxxxxxxxxxxxxxxx
+NEXT_PUBLIC_CHERRYBOARD_URL=https://<your-cherryboard-api-host>
+```
+
+```bash
+# .env  (Vite)
+VITE_CHERRYBOARD_KEY=cpd_xxxxxxxxxxxxxxxxxxxxxxxx
+VITE_CHERRYBOARD_URL=https://<your-cherryboard-api-host>
+```
+
+`apiUrl` is the API host root — the SDK appends `/api/v1/errors/batch` for you.
+
+---
+
+## 3. Quick start — Next.js (App Router)
+
+Works with Next.js 13.4+ (App Router) including **Next.js 16 / React 19**.
+
+### 3a. Initialize once, as early as possible
+
+Create **`instrumentation-client.ts`** at your project root (or `src/`). Next.js runs
+this on the client before your app hydrates — the ideal place to start the tracker.
+
+```ts
+// instrumentation-client.ts
+import { init } from '@cherrypeak-org/cherryboard-web';
+
+init({
+  apiKey: process.env.NEXT_PUBLIC_CHERRYBOARD_KEY!,
+  apiUrl: process.env.NEXT_PUBLIC_CHERRYBOARD_URL!,
+  environment: process.env.NEXT_PUBLIC_ENV ?? 'production',
+  release: process.env.NEXT_PUBLIC_COMMIT_SHA, // optional, recommended
+});
+```
+
+> On **older Next** without `instrumentation-client.ts`, use the
+> [`<CherryBoardProvider>`](#3d-alternative-provider) instead.
+
+### 3b. Report render errors from the App Router boundaries
+
+Next catches render errors with `error.tsx` (per route) and `global-error.tsx` (root
+layout). They only render a fallback — add one line to also report them:
+
+```tsx
+// app/error.tsx
+'use client';
+import { useEffect } from 'react';
+import { captureRouteError } from '@cherrypeak-org/cherryboard-web/react';
+
+export default function Error({ error, reset }: { error: Error & { digest?: string }; reset: () => void }) {
+  useEffect(() => {
+    captureRouteError(error); // includes the Next.js `digest` for correlation
+  }, [error]);
+
+  return (
+    <div>
+      <h2>Something went wrong.</h2>
+      <button onClick={reset}>Try again</button>
+    </div>
+  );
+}
+```
+
+```tsx
+// app/global-error.tsx
+'use client';
+import { useEffect } from 'react';
+import { captureRouteError } from '@cherrypeak-org/cherryboard-web/react';
+
+export default function GlobalError({ error, reset }: { error: Error & { digest?: string }; reset: () => void }) {
+  useEffect(() => {
+    captureRouteError(error);
+  }, [error]);
+
+  return (
+    <html>
+      <body>
+        <h2>Application error.</h2>
+        <button onClick={reset}>Reload</button>
+      </body>
+    </html>
+  );
+}
+```
+
+That's it — global errors, unhandled rejections, and route-level render errors are now
+tracked.
+
+### 3c. (Optional) Wrap a subtree in an ErrorBoundary
+
+For a nicer fallback around a specific area (and to keep the rest of the page alive):
+
+```tsx
+'use client';
+import { ErrorBoundary } from '@cherrypeak-org/cherryboard-web/react';
+
+export function Widget() {
+  return (
+    <ErrorBoundary fallback={({ reset }) => <button onClick={reset}>Reload widget</button>}>
+      <FlakyChart />
+    </ErrorBoundary>
+  );
+}
+```
+
+### 3d. Alternative: the provider
+
+If you'd rather not use `instrumentation-client.ts`, initialize with the provider in
+your root layout. It's a client component, so it's safe to render from the (server)
+layout:
+
+```tsx
+// app/layout.tsx
+import { CherryBoardProvider } from '@cherrypeak-org/cherryboard-web/react';
+
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <html lang="en">
+      <body>
+        <CherryBoardProvider
+          config={{
+            apiKey: process.env.NEXT_PUBLIC_CHERRYBOARD_KEY!,
+            apiUrl: process.env.NEXT_PUBLIC_CHERRYBOARD_URL!,
+            environment: process.env.NEXT_PUBLIC_ENV ?? 'production',
+          }}
+        >
+          {children}
+        </CherryBoardProvider>
+      </body>
+    </html>
+  );
+}
+```
+
+> **Amplify note:** on AWS Amplify, only env vars matching the build's allowlist reach
+> the runtime. `NEXT_PUBLIC_*` vars are picked up automatically — make sure your key
+> uses that prefix.
+
+---
+
+## 4. Quick start — Vite / CRA / plain React
+
+Call `init` once at your entry point, before rendering:
+
+```ts
+// main.tsx
+import { init } from '@cherrypeak-org/cherryboard-web';
+
+init({
+  apiKey: import.meta.env.VITE_CHERRYBOARD_KEY,
+  apiUrl: import.meta.env.VITE_CHERRYBOARD_URL,
+  environment: import.meta.env.MODE,
+});
+
+// ...then ReactDOM.createRoot(...).render(<App />)
+```
+
+Wrap your tree in the boundary to catch render errors:
+
+```tsx
+import { ErrorBoundary } from '@cherrypeak-org/cherryboard-web/react';
+
+<ErrorBoundary fallback={<p>Something went wrong.</p>}>
+  <App />
+</ErrorBoundary>
+```
+
+---
+
+## 5. Reporting errors manually
+
+Error boundaries and global handlers can't see errors you catch yourself (in `try/catch`,
+event handlers, or async code). Report those explicitly:
+
+```ts
+import { captureException, captureMessage } from '@cherrypeak-org/cherryboard-web';
+
+try {
+  await riskyThing();
+} catch (err) {
+  captureException(err, { context: { orderId, step: 'checkout' } });
+}
+
+// Log a noteworthy non-error event
+captureMessage('Payment provider returned an unexpected shape', 'Warning');
+```
+
+In components, the hook gives you a stable callback:
+
+```tsx
+'use client';
+import { useCaptureError } from '@cherrypeak-org/cherryboard-web/react';
+
+function SaveButton() {
+  const capture = useCaptureError();
+  const onClick = async () => {
+    try {
+      await save();
+    } catch (err) {
+      capture(err, { context: { feature: 'save' } });
+    }
+  };
+  return <button onClick={onClick}>Save</button>;
+}
+```
+
+---
+
+## 6. Identifying users & adding context
+
+```ts
+import { setUser, setTag, addBreadcrumb } from '@cherrypeak-org/cherryboard-web';
+
+// After login — keep it to an opaque id; do NOT pass emails/names.
+setUser({ id: user.id });
+
+// Global tags attached to every subsequent event
+setTag('tenant', tenantId);
+setTag('plan', 'pro');
+
+// A manual breadcrumb
+addBreadcrumb({ category: 'ui', message: 'Opened export dialog' });
+
+// On logout
+setUser(null);
+```
+
+Navigation, clicks, and `fetch` calls are recorded as breadcrumbs automatically.
+
+---
+
+## 7. Configuration reference
+
+Only `apiKey` and `apiUrl` are required.
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `apiKey` | `string` | — | Ingest API key, sent as `X-API-Key`. |
+| `apiUrl` | `string` | — | API host root; `/api/v1/errors/batch` is appended. |
+| `environment` | `string` | `"production"` | Tag shown in the dashboard metadata. |
+| `release` | `string` | – | App version / git SHA (regression tracking, source maps). |
+| `enabled` | `boolean` | `true` | Master switch — set `false` to disable entirely. |
+| `sampleRate` | `number` | `1` | Fraction of events kept (0–1). |
+| `maxBatchSize` | `number` | `20` | Events per request (backend caps at 100). |
+| `flushIntervalMs` | `number` | `4000` | Debounce before an idle buffer flushes. |
+| `maxQueueItems` | `number` | `100` | Max events persisted to the offline queue. |
+| `maxRetries` | `number` | `3` | Retry attempts (5xx / network only). |
+| `maxBreadcrumbs` | `number` | `30` | Breadcrumbs retained per event. |
+| `offlineStorage` | `boolean` | `true` | Persist undelivered events to `localStorage`. |
+| `captureUnhandledErrors` | `boolean` | `true` | Capture `window` uncaught errors. |
+| `captureUnhandledRejections` | `boolean` | `true` | Capture unhandled promise rejections. |
+| `captureResourceErrors` | `boolean` | `true` | Capture failed img/script/css loads. |
+| `captureConsole` | `boolean` | `true` | Turn `console.error/warn` into breadcrumbs. |
+| `autoBreadcrumbs` | `boolean` | `true` | Auto navigation/click/fetch breadcrumbs. |
+| `denyUrls` | `(string \| RegExp)[]` | `[]` | Drop events whose stack/URL matches. |
+| `allowUrls` | `(string \| RegExp)[]` | `[]` | If set, keep only matching events. |
+| `beforeSend` | `(event) => event \| null` | – | Mutate/scrub, or drop (`return null`). |
+| `debug` | `boolean` | `false` | Log SDK diagnostics to the console. |
+
+### `beforeSend`
+
+Runs after the built-in PII scrub, right before an event is queued:
+
+```ts
+init({
+  apiKey, apiUrl,
+  beforeSend(event) {
+    if (event.message.includes('ResizeObserver loop')) return null; // drop noise
+    event.context.build = '2026.7.1';
+    return event;
+  },
+});
+```
+
+---
+
+## 8. What gets captured
+
+| Source | How | Severity |
+|---|---|---|
+| Uncaught exceptions | `window` `error` | `Error` |
+| Unhandled promise rejections | `unhandledrejection` | `Error` |
+| React render/lifecycle errors | `<ErrorBoundary>` / Next `error.tsx` | `Error` |
+| Failed resource loads | `error` (capture phase) | `Warning` |
+| Manual `captureException` | you | `Error` (override via hint) |
+| Manual `captureMessage` | you | your choice |
+| `console.error` / `console.warn` | breadcrumb only (not an event) | – |
+
+Each event carries: message, stack, exception type, `error.cause` chain, the current
+route, user agent, viewport, `release` + `environment`, your tags, and the recent
+breadcrumb trail (all under the dashboard's **Additional data**). The same error hitting
+multiple hooks is **de-duplicated** into a single report.
+
+---
+
+## 9. Security & privacy (read this)
+
+- **The API key is public.** Use a **write-only / ingest-only** key so a leaked key can
+  only submit errors — never read or manage data. (Ask your CherryBoard admin to scope
+  the key to error ingest.)
+- **CORS & rate limiting** live on the backend. The ingest endpoint should allow your
+  app's origin(s) and rate-limit per key to blunt abuse of the public key.
+- **PII scrubbing is on by default** — `Authorization`/tokens/cookies, emails, and
+  sensitive query params/keys (`password`, `secret`, `token`, …) are redacted *before*
+  anything leaves the browser. Add your own rules via `beforeSend`. The SDK never sends
+  request/response bodies or form values.
+- **Source maps**: see [Readable stack traces](#11-readable-stack-traces-source-maps). Don't
+  serve `.map` files publicly — upload them instead.
+- **SSR-safe**: the core touches no browser globals at import time; the React entry is
+  marked `"use client"`. Don't call the SDK from `"use server"` modules — it's for the
+  browser.
+
+---
+
+## 10. Troubleshooting
+
+- **No errors appear.** Confirm `init` ran (set `debug: true`), the key/URL are correct,
+  and the browser Network tab shows a `POST …/api/v1/errors/batch`. A `401/403` means a
+  bad/expired key; a **CORS error** means the backend must allow your origin.
+- **"Script error." with no stack.** A cross-origin script threw. Add
+  `crossorigin="anonymous"` to the script tag and `Access-Control-Allow-Origin` on the
+  asset host. The SDK already drops bare `Script error.` noise.
+- **Duplicate reports.** Shouldn't happen (built-in dedupe), but avoid manually calling
+  `captureException` for an error your `ErrorBoundary` already handles.
+- **`window is not defined` during build.** You imported the SDK into server-only code.
+  Call it from client components / `instrumentation-client.ts` only.
+- **Events lost on tab close.** Handled — the SDK flushes via `keepalive` on `pagehide`/
+  visibility change, and persists to an offline queue that drains when you're back online.
+
+---
+
+## 11. Readable stack traces (source maps)
+
+Production stacks are minified (`main.4f2c1b.js:1:24817`). Upload your build's source
+maps and CherryBoard resolves them server-side into real files, lines and function
+names — shown on the issue page as **original sources**.
+
+Two things must line up: the `release` you pass to `init()` and the `--release` you
+upload with. **If they differ, nothing is symbolicated** (silently — it's recorded as
+"not applicable", not an error).
+
+Add to CI, after the build:
+
+```bash
+npx cherryboard-upload-sourcemaps \
+  --dir .next/static \
+  --url-prefix /_next/static \
+  --release "$GIT_SHA" \
+  --api-url https://<your-cherryboard-api-host> \
+  --api-key "$CHERRYBOARD_UPLOAD_KEY"
+```
+
+- Use a **General (server) key** — never the browser key. The write-only browser scope
+  deliberately cannot upload build artifacts.
+- `--dry-run` lists what would upload without sending anything.
+- Uploading the same file for a release again **replaces** it, so re-running a build is safe.
+- Maps are stored privately and expire after 90 days.
+
+Next.js needs `productionBrowserSourceMaps: true` in `next.config.ts` to emit them.
+Prefer not serving the `.map` files to the public — uploading is enough.
+
+## 12. Server-side errors (Next.js)
+
+Browser capture never sees RSC render, route handler or server action errors. Catch
+them in `instrumentation.ts`:
+
+```ts
+// instrumentation.ts
+import { init, captureRequestError } from '@cherrypeak-org/cherryboard-web';
+
+export function register() {
+  init({
+    apiKey: process.env.CHERRYBOARD_KEY!,   // server-side key
+    apiUrl: process.env.CHERRYBOARD_URL!,
+    environment: process.env.NEXT_PUBLIC_ENV ?? 'production',
+    release: process.env.NEXT_PUBLIC_COMMIT_SHA,
+  });
+}
+
+export const onRequestError = captureRequestError;
+```
+
+The core runs fine outside the browser: it installs no window handlers there and
+delivers over `fetch`.
+
+## 13. Why didn't my error show up?
+
+Events can be dropped on purpose (sampling, dedupe, filters) — ask the SDK:
+
+```ts
+import { getDiscardedEvents } from '@cherrypeak-org/cherryboard-web';
+console.log(getDiscardedEvents());
+// { deduped: 3, sampled: 1, rate_limited: 0, filtered: 0, send_failed: 0 }
+```
+
+## API summary
+
+```ts
+// Core — @cherrypeak-org/cherryboard-web
+init(config): CherryBoardClient
+captureException(error, hint?): void
+captureMessage(message, severity?, hint?): void
+addBreadcrumb(crumb): void
+setUser(user | null): void
+setTag(key, value): void
+setContext(key, value): void
+flush(): Promise<void>
+close(): void
+getClient(): CherryBoardClient | null
+getDiscardedEvents(): Record<string, number>
+captureRequestError(error, request?, context?)   // Next.js instrumentation.ts
+
+// CLI
+cherryboard-upload-sourcemaps --dir <dir> --release <id> --api-url <url> --api-key <key>
+
+// React — @cherrypeak-org/cherryboard-web/react
+<CherryBoardProvider config withBoundary? fallback?>
+<ErrorBoundary fallback? onError? resetKeys?>
+useCaptureError(): (error, hint?) => void
+useCherryBoard(): CherryBoardClient | null
+captureRouteError(error): void   // for Next error.tsx / global-error.tsx
+```
+
+## License
+
+UNLICENSED — internal to CherryPeak.

package/bin/cherryboard-upload-sourcemaps.mjs

@@ -0,0 +1,138 @@
+#!/usr/bin/env node
+/**
+ * Uploads a build's source maps to CherryBoard so production stack traces can be
+ * resolved to original files, lines and function names.
+ *
+ * Run this in CI after building, with the SAME release identifier the SDK is
+ * configured with — frames are matched by release, so a mismatch silently means
+ * no symbolication.
+ *
+ *   cherryboard-upload-sourcemaps \
+ *     --dir .next/static \
+ *     --url-prefix /_next/static \
+ *     --release "$GIT_SHA" \
+ *     --api-url https://api.example.com \
+ *     --api-key "$CHERRYBOARD_UPLOAD_KEY"
+ *
+ * Use a General (server) key, never the write-only browser key.
+ */
+import { readFile, readdir, stat } from 'node:fs/promises';
+import { join, relative, sep } from 'node:path';
+import { parseArgs } from 'node:util';
+
+const { values } = parseArgs({
+  options: {
+    dir: { type: 'string' },
+    'url-prefix': { type: 'string', default: '/' },
+    release: { type: 'string' },
+    'api-url': { type: 'string' },
+    'api-key': { type: 'string' },
+    'dry-run': { type: 'boolean', default: false },
+    help: { type: 'boolean', default: false },
+  },
+});
+
+if (values.help) {
+  console.log(`
+Usage: cherryboard-upload-sourcemaps --dir <build-dir> --release <id> --api-url <url> --api-key <key>
+
+  --dir          Directory to scan recursively for .map files (e.g. .next/static)
+  --url-prefix   URL path the directory is served under (e.g. /_next/static)
+  --release      Release id; MUST match the SDK's \`release\` option
+  --api-url      CherryBoard API host
+  --api-key      A General (server) API key — not the browser key
+  --dry-run      List what would be uploaded, upload nothing
+`);
+  process.exit(0);
+}
+
+const required = ['dir', 'release'];
+if (!values['dry-run']) required.push('api-url', 'api-key');
+const missing = required.filter((k) => !values[k]);
+if (missing.length) {
+  console.error(`Missing required option(s): ${missing.map((m) => `--${m}`).join(', ')}`);
+  process.exit(1);
+}
+
+/** Recursively collect every .map file under a directory. */
+async function findMaps(dir) {
+  const found = [];
+  let entries;
+  try {
+    entries = await readdir(dir, { withFileTypes: true });
+  } catch (err) {
+    console.error(`Cannot read directory ${dir}: ${err.message}`);
+    process.exit(1);
+  }
+  for (const entry of entries) {
+    const full = join(dir, entry.name);
+    if (entry.isDirectory()) found.push(...(await findMaps(full)));
+    else if (entry.name.endsWith('.map')) found.push(full);
+  }
+  return found;
+}
+
+/**
+ * ".next/static/chunks/a.js.map" under prefix "/_next/static"
+ *   -> "/_next/static/chunks/a.js"  (the path stack frames report)
+ */
+function toUrlPath(mapFile, baseDir, urlPrefix) {
+  const rel = relative(baseDir, mapFile).split(sep).join('/');
+  const generated = rel.replace(/\.map$/, '');
+  const prefix = urlPrefix.endsWith('/') ? urlPrefix.slice(0, -1) : urlPrefix;
+  return `${prefix}/${generated}`.replace(/\/{2,}/g, '/');
+}
+
+const maps = await findMaps(values.dir);
+if (maps.length === 0) {
+  // Not an error: many builds legitimately produce none (e.g. maps disabled).
+  console.log(`No .map files found under ${values.dir} — nothing to upload.`);
+  process.exit(0);
+}
+
+console.log(`Found ${maps.length} source map(s) for release ${values.release}`);
+
+let uploaded = 0;
+let failed = 0;
+
+for (const mapFile of maps) {
+  const filePath = toUrlPath(mapFile, values.dir, values['url-prefix']);
+  const { size } = await stat(mapFile);
+
+  if (values['dry-run']) {
+    console.log(`  [dry-run] ${filePath}  (${(size / 1024).toFixed(0)} KB)`);
+    continue;
+  }
+
+  try {
+    const content = await readFile(mapFile, 'utf8');
+    const res = await fetch(`${values['api-url'].replace(/\/+$/, '')}/api/v1/SourceMaps`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json', 'X-API-Key': values['api-key'] },
+      body: JSON.stringify({ release: values.release, filePath, content }),
+    });
+
+    if (!res.ok) {
+      const body = await res.text().catch(() => '');
+      console.error(`  ✗ ${filePath} → HTTP ${res.status} ${body.slice(0, 200)}`);
+      failed++;
+      continue;
+    }
+
+    uploaded++;
+    console.log(`  ✓ ${filePath}  (${(size / 1024).toFixed(0)} KB)`);
+  } catch (err) {
+    console.error(`  ✗ ${filePath} → ${err.message}`);
+    failed++;
+  }
+}
+
+if (values['dry-run']) {
+  console.log(`\nDry run: ${maps.length} map(s) would be uploaded.`);
+  process.exit(0);
+}
+
+console.log(`\nUploaded ${uploaded}/${maps.length} source map(s)${failed ? `, ${failed} failed` : ''}.`);
+// Failing the build on upload errors would block deploys over telemetry, so
+// this exits non-zero only if nothing at all got through.
+process.exit(uploaded === 0 ? 1 : 0);