@fixback/sdk-core 0.2.0 → 0.3.0

package/src/wire.ts

@@ -1,116 +0,0 @@
-/**
- * The shared **ingest wire shapes** (ADR-0028) — the value contract a captured
- * report carries to `POST /api/ingest/feedback`, shared by every Fixback capture
- * SDK so they all speak the same shape.
- *
- * Like the rest of the core these are runtime-agnostic value types: the browser
- * and (future) backend SDKs both assemble a {@link ReportContent} from what they
- * captured. Keep them in lock-step with the server: the JSON `payload` part the
- * ingest controller parses (`apps/api/src/ingest/ingest.controller.ts`) and the
- * `SubmissionContent` it maps to (`apps/api/src/ingest/reporter-identity.ts`).
- * Each SDK keeps vendoring its own transport envelope (ticket #47) — the core
- * carries the pure content shape, not the multipart envelope.
- */
-
-import type { Annotation } from "./annotation";
-import type { Breadcrumb } from "./breadcrumb";
-
-/**
- * Where a Feedback came from — a human in the overlay (`reporter`, the default) or
- * a runtime error the SDK captured (`error`, ADR-0025: covers both an uncaught
- * crash and a manual capture, on any runtime). Mirrors the server's
- * `FEEDBACK_SOURCES`; the server derives trust independently and ignores anything
- * else the client claims.
- */
-export type FeedbackSource = "reporter" | "error";
-
-/**
- * The **Platform** a Feedback was captured on (ADR-0025): `browser` (the web SDK),
- * `node` (the backend SDK), or `expo` (the mobile SDK). Additive — future runtimes
- * become new values. Mirrors the server's `PLATFORMS` (`@fixback/shared`) by value;
- * the server stamps it from the ingest route, so it is **not** carried on
- * {@link ReportContent} (the client never declares its own platform).
- */
-export type Platform = "browser" | "node" | "expo";
-
-/** The capture environment recorded alongside a report. */
-export interface CaptureEnvironment {
-  readonly viewportWidth?: number;
-  readonly viewportHeight?: number;
-  readonly browser?: string;
-  readonly sdkVersion?: string;
-  /**
-   * The host app's **Release** — the build identifier the builder configured at
-   * `init` (#117, ADR-0024). Uploaded sourcemaps are keyed by it, so the server
-   * can symbolicate this session's stack traces against the exact build that
-   * produced them. Omitted when the Project doesn't set one.
-   */
-  readonly release?: string;
-}
-
-/**
- * One structured frame of a captured stack trace (#117, ADR-0024), top of stack
- * first — the server's `errorFrames` wire shape. `file` is the scrubbed script
- * URL; `line`/`column` are 1-based as browsers report them.
- */
-export interface CapturedFrame {
-  readonly file: string;
-  readonly line: number;
-  readonly column: number | null;
-  readonly function: string | null;
-}
-
-/**
- * The JSON content of a feedback submission — the object serialised into the
- * multipart `payload` part next to the `key` and identity evidence. Every field
- * is optional: none of it feeds the server's trust decision, so a submission may
- * carry any subset. `annotation` is the structured `{ element?, region?, marks? }`
- * (spec §D); the screenshot is a separate binary part, never part of this JSON.
- */
-export interface ReportContent {
-  readonly comment?: string;
-  /**
-   * The Reporter's self-provided display **name / email** (spec §F), captured in the
-   * invite onboarding step and riding along with every submission so a Member sees
-   * who reported an Issue. **Display only, never a trust signal** — the server derives
-   * the tier from identity evidence alone and ignores these. Omitted when the Reporter
-   * gave none (a Public/anonymous visitor).
-   */
-  readonly reporterName?: string;
-  readonly reporterEmail?: string;
-  readonly url?: string;
-  readonly environment?: CaptureEnvironment;
-  readonly annotation?: Annotation;
-  /** The masked breadcrumb trace buffer that rode on this report (spec §C). */
-  readonly trace?: readonly Breadcrumb[];
-  /**
-   * Provenance (spec §D/§E). Omitted for a manual report — the transport stamps the
-   * `reporter` default on the wire; set to `error` by the SDK's error capture.
-   */
-  readonly source?: FeedbackSource;
-  /**
-   * For `source: error` only — whether the error was **handled** (ADR-0025):
-   * `false` = an uncaught crash, `true` = a manual capture. Set by the backend SDK
-   * (`@fixback/node`), which distinguishes the two; the browser SDK captures only
-   * uncaught errors and leaves it unset.
-   */
-  readonly handled?: boolean;
-  /**
-   * The deploy **Environment** the SDK was configured with (ADR-0025) —
-   * `production` / `staging` / … — distinct from {@link CaptureEnvironment.release}
-   * (a build version). Named apart from `environment` (the capture bag above) to
-   * avoid the collision. Set by the backend SDK; unset by the browser SDK for now.
-   */
-  readonly deployEnvironment?: string;
-  /** For `source: error` only — the SDK's per-session error fingerprint (spec §E). */
-  readonly errorSignature?: string;
-  /** For `source: error` only — the running occurrence count within the session (spec §E). */
-  readonly occurrences?: number;
-  /**
-   * For `source: error` only — the captured error's parsed stack frames (#117,
-   * ADR-0024), top of stack first, capped client-side. The analysis worker
-   * matches them against the release's uploaded sourcemaps to write the Issue's
-   * Code-area pointer.
-   */
-  readonly errorFrames?: readonly CapturedFrame[];
-}