@paikko/contract 0.1.0

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -0,0 +1,374 @@
+/**
+ * paikko ticket bundle contract.
+ *
+ * This is THE shared interface. Every module imports from here: the
+ * `<ReportButton>` that produces a bundle, the API that persists it, the ticket
+ * UI that renders it, and the agent runner that consumes it. Change a shape here
+ * and you change it for everyone, so it lives in one file with types and zod
+ * schemas side by side.
+ *
+ * ## Two tiers
+ *
+ * A ticket is split so the agent's context stays cheap:
+ *
+ *   - TIER 1 - the HEAD ({@link TicketHead}). Small, always loaded into agent
+ *     context. Carries the user's message, where it happened (route + clicked
+ *     element provenance), the conversation thread, and an INDEX of artifacts.
+ *     The index lists each artifact by name with a `ref` (how to fetch it) and a
+ *     `summary` (one line) plus a few cheap stats, so the agent can decide from
+ *     the head alone whether it even needs the heavy payload. Most tickets are
+ *     solved from the head with zero fetches.
+ *
+ *   - TIER 2 - the ARTIFACT PAYLOADS. Heavy, immutable, captured once at report
+ *     time (a photograph, not a live window). Fetched by ref only when a fix
+ *     needs them: console, network, client state, storage, DOM snapshot, backend
+ *     trace. Stored as JSONB rows keyed by ticket+name, served at
+ *     `GET /tickets/:id/artifacts/:name`.
+ *
+ * ## The spine: traceId
+ *
+ * `traceId` stitches the two halves of a single request together. A frontend
+ * {@link NetworkEntry} and the backend {@link TraceRequest} it triggered share
+ * the same `traceId`. That is how the agent walks from "this fetch on the page"
+ * to "this handler + these queries on the server" without guessing.
+ *
+ * ## Provenance: src
+ *
+ * `src` ("file:line:col") appears on every layer the user or agent can point at -
+ * the clicked element, the API handler, each DB query - so provenance runs end to
+ * end. It is injected at build time (see PROVENANCE.md).
+ */
+import { z } from "zod";
+/* ------------------------------------------------------------------ */
+/* Shared primitives                                                  */
+/* ------------------------------------------------------------------ */
+/**
+ * Ticket lifecycle. `status` is persisted as a free `String` in
+ * prisma/schema.prisma; this enum is the app-side validator for it.
+ *
+ * Terminal states are `closed` (accepted: the ticket's branch was merged to main
+ * and the live app redeployed) and `rejected` (discarded: the ticket's branch +
+ * worktree were dropped, the live app untouched). `reviewing` is the parked state
+ * where the fix lives on its own branch with an isolated preview; a user reply on
+ * a `reviewing` ticket re-engages the agent (no separate reject needed to request
+ * changes).
+ */
+export const TicketStatusSchema = z.enum([
+    "open",
+    "reproducing",
+    "needs_info",
+    "reviewing",
+    "closed",
+    "rejected",
+]);
+/**
+ * The canonical names an artifact can have. The artifact index is keyed by these,
+ * and `GET /tickets/:id/artifacts/:name` expects one of them.
+ */
+export const ArtifactNameSchema = z.enum([
+    "console",
+    "network",
+    "clientState",
+    "storage",
+    "dom",
+    "trace",
+    "screenshot",
+]);
+/**
+ * Source provenance, "file:line:col" (e.g. "src/components/Cart.tsx:42:7").
+ * Injected at build time onto JSX, attached to handlers and queries.
+ */
+export const SrcSchema = z.string();
+/** ISO-8601 timestamp string. Used everywhere a time is recorded. */
+export const IsoTimeSchema = z.string().datetime();
+/**
+ * The id that stitches a frontend network entry to its backend request.
+ * Generated client-side per request, echoed by the server.
+ */
+export const TraceIdSchema = z.string();
+/* ------------------------------------------------------------------ */
+/* TIER 1 - the head                                                  */
+/* ------------------------------------------------------------------ */
+/**
+ * What the user pointed at when they hit report: the clicked DOM element resolved
+ * to a CSS selector, its source location, and the owning component. All optional
+ * because a report can be fired without a specific target (e.g. a global "this
+ * page is wrong").
+ */
+export const ReportTargetSchema = z.object({
+    /** CSS selector identifying the clicked element in the live DOM. */
+    selector: z.string().nullable(),
+    /** Build-time source provenance of the element ("file:line:col"). */
+    src: SrcSchema.nullable(),
+    /** Display name of the React component that owns the element. */
+    component: z.string().nullable(),
+});
+/** The user-authored core of a report: what's wrong and where. */
+export const ReportSchema = z.object({
+    /** Free-text description from the reporter. Capped so a single report can't be
+     * an unbounded blob (intake has no other size gate on this field). */
+    message: z.string().max(16_384),
+    /** Report category (e.g. "bug", "visual", "crash"). Free-form in v0. */
+    kind: z.string().max(64),
+    /** App route the report was fired from (e.g. "/cart"). */
+    route: z.string().max(2_048),
+    /** The clicked element, resolved to selector + provenance + component. */
+    target: ReportTargetSchema,
+});
+/** One message in the ticket's conversation (reporter, agent, or reviewer). */
+export const ThreadMessageSchema = z.object({
+    id: z.string(),
+    /** Author handle: reporter id, "agent", reviewer id, etc. */
+    by: z.string().max(256),
+    text: z.string().max(16_384),
+    at: IsoTimeSchema,
+});
+/**
+ * One entry in the artifact index. Lives in the head so the agent can read the
+ * `summary` and stats and decide whether to fetch the heavy payload via `ref`.
+ *
+ * `count` and `size` are cheap, type-agnostic stats:
+ *   - `count`: number of records in the payload (console lines, network calls,
+ *     backend requests, ...). Null for single-object artifacts (clientState).
+ *   - `size`: serialized payload size in bytes.
+ */
+export const ArtifactIndexEntrySchema = z.object({
+    /** Fetch handle: `GET /tickets/:id/artifacts/:name`. */
+    ref: z.string(),
+    /** One-line human/agent summary so the head is decision-complete. */
+    summary: z.string(),
+    /** Record count for collection artifacts; null for singletons. */
+    count: z.number().int().nullable(),
+    /** Serialized payload size in bytes. */
+    size: z.number().int(),
+});
+/**
+ * The artifacts index: a map from artifact name to its index entry. Partial -
+ * a ticket only indexes the artifacts that were actually captured.
+ */
+export const ArtifactIndexSchema = z.record(ArtifactNameSchema, ArtifactIndexEntrySchema);
+/**
+ * TIER 1. The ticket head - always loaded into agent context. Small and
+ * self-sufficient: message, where it happened, the thread, and the index of
+ * heavy artifacts behind refs.
+ */
+export const TicketHeadSchema = z.object({
+    id: z.string(),
+    status: TicketStatusSchema,
+    createdAt: IsoTimeSchema,
+    /** Who filed it (user id / handle). */
+    reporter: z.string(),
+    report: ReportSchema,
+    thread: z.array(ThreadMessageSchema),
+    artifacts: ArtifactIndexSchema,
+    /**
+     * Which project/tenant this ticket belongs to (the SaaS seam). Persisted from
+     * the `projectKey` the widget sent on the {@link ReportBundle}. Null in the
+     * current single-tenant deployment; making multi-tenancy real is a later flip of
+     * this value, not a schema rewrite.
+     */
+    projectKey: z.string().nullable(),
+    /**
+     * The git branch the fix lives on (e.g. "ticket/{id}"). Branch-isolated review:
+     * each ticket is fixed in its own worktree + branch off main, so main stays
+     * pristine until Accept. Null until the agent has cut the branch.
+     */
+    branch: z.string().nullable(),
+    /**
+     * The isolated preview URL where ONLY this ticket's fix is viewable
+     * (e.g. "http://localhost:8788"), distinct from the pristine main app. "View
+     * fix" links here, not to the live app. Null until the isolated preview is up.
+     */
+    previewUrl: z.string().nullable(),
+});
+/* ------------------------------------------------------------------ */
+/* TIER 2 - artifact payloads                                         */
+/* ------------------------------------------------------------------ */
+/* ---- console ---- */
+/** One captured console line from the ring buffer. */
+export const ConsoleEntrySchema = z.object({
+    level: z.enum(["log", "info", "warn", "error", "debug"]),
+    /** Already-formatted message text. */
+    message: z.string(),
+    /** Structured args as captured (best-effort serialized). */
+    args: z.array(z.unknown()).optional(),
+    at: IsoTimeSchema,
+});
+/** Payload for the `console` artifact: the console ring buffer, oldest first.
+ * Length-capped so a forged bundle can't ship an unbounded array. */
+export const ConsoleArtifactSchema = z.array(ConsoleEntrySchema).max(5_000);
+/* ---- network ---- */
+/**
+ * One captured frontend network call. `traceId` is the spine: it matches the
+ * `traceId` on the {@link TraceRequest} the call hit on the backend.
+ */
+export const NetworkEntrySchema = z.object({
+    /** Spine id linking this call to its backend request. */
+    traceId: TraceIdSchema,
+    method: z.string(),
+    url: z.string(),
+    /** HTTP status; null if the request never completed. */
+    status: z.number().int().nullable(),
+    /** Request body as captured (serialized; null if none). */
+    reqBody: z.unknown().nullable(),
+    /** Response body as captured (serialized; null if none). */
+    resBody: z.unknown().nullable(),
+    startedAt: IsoTimeSchema,
+    /** Round-trip duration in milliseconds; null if unknown. */
+    durationMs: z.number().nullable(),
+});
+/** Payload for the `network` artifact: last N network calls, oldest first.
+ * Length-capped so a forged bundle can't ship an unbounded array. */
+export const NetworkArtifactSchema = z.array(NetworkEntrySchema).max(5_000);
+/* ---- client state ---- */
+/**
+ * Payload for the `clientState` artifact: a snapshot of the mandated state store
+ * at report time. Shape is app-defined, so it's an opaque record.
+ */
+export const ClientStateArtifactSchema = z.record(z.string(), z.unknown());
+/* ---- storage ---- */
+/**
+ * Payload for the `storage` artifact: localStorage / sessionStorage / cookies
+ * captured at report time. Each is a flat string->string map.
+ */
+export const StorageArtifactSchema = z.object({
+    local: z.record(z.string(), z.string()),
+    session: z.record(z.string(), z.string()),
+    cookies: z.record(z.string(), z.string()),
+});
+/* ---- dom ---- */
+/**
+ * Payload for the `dom` artifact: a snapshot of the DOM at report time. `html` is
+ * the serialized document/subtree; `targetSelector` points back at the clicked
+ * element within it.
+ */
+export const DomArtifactSchema = z.object({
+    /** Serialized DOM (full document or relevant subtree). Capped (~8MB) so a
+     * crafted bundle can't bloat a D1 row / OOM the worker on intake. */
+    html: z.string().max(8_000_000),
+    /** Selector of the reported element within `html`. */
+    targetSelector: z.string().nullable(),
+    /** Viewport size at capture time. */
+    viewport: z.object({
+        width: z.number().int(),
+        height: z.number().int(),
+    }),
+});
+/* ---- backend trace ---- */
+/** One database query recorded inside a backend request. */
+export const TraceQuerySchema = z.object({
+    /** SQL or query string as executed. */
+    sql: z.string(),
+    /** Bound parameters, serialized. */
+    params: z.array(z.unknown()).optional(),
+    /** Execution time in milliseconds. */
+    durationMs: z.number().nullable(),
+    /** Provenance of the call site issuing the query ("file:line:col"). */
+    src: SrcSchema.nullable(),
+});
+/**
+ * One backend request captured by the `withCapture()` handler wrapper. Joined to
+ * a frontend {@link NetworkEntry} by `traceId`.
+ */
+export const TraceRequestSchema = z.object({
+    /** Spine id - matches the frontend NetworkEntry that triggered this request. */
+    traceId: TraceIdSchema,
+    /** Name/identity of the handler that ran. */
+    handler: z.string(),
+    /** Provenance of the handler ("file:line:col"). */
+    src: SrcSchema.nullable(),
+    method: z.string(),
+    url: z.string(),
+    status: z.number().int().nullable(),
+    /** Queries issued during this request, in order. */
+    queries: z.array(TraceQuerySchema),
+    /** Serialized error if the handler threw; null on success. */
+    threw: z.unknown().nullable(),
+    durationMs: z.number().nullable(),
+});
+/**
+ * Payload for the `trace` artifact: the backend side of the report. One capture
+ * session containing every backend request that ran during the reported
+ * interaction, each stitched to its frontend call by `traceId`.
+ */
+export const TraceArtifactSchema = z.object({
+    /** Backend capture session id for the reported interaction. */
+    sessionId: z.string(),
+    requests: z.array(TraceRequestSchema),
+});
+/* ---- screenshot ---- */
+/**
+ * Payload for the `screenshot` artifact: an actual rendered image of the page at
+ * report time, so the agent (which can see images) and the human reviewer can
+ * directly judge "this looks off" / visual reports that a DOM/CSS snapshot can't
+ * convey. The widget's own report UI is excluded from the shot.
+ *
+ * Kept small on purpose: the longest side is capped (~1280px) and the image is
+ * JPEG-compressed, so the base64 `dataUrl` typically lands well under ~1MB. `png`
+ * is allowed as a fallback but is larger; prefer `jpeg`.
+ */
+export const ScreenshotArtifactSchema = z.object({
+    /** A `data:` URL holding the base64-encoded image (e.g. `data:image/jpeg;base64,...`).
+     * Scheme-locked to an inline image (a remote http(s) src would turn opening
+     * the artifact into an outbound request to an attacker host) and size-capped
+     * (~12MB) so it can't be used as a DoS payload. */
+    dataUrl: z
+        .string()
+        .max(12_000_000)
+        .regex(/^data:image\/(png|jpeg|jpg|gif|webp);base64,/, "must be an inline image data URL"),
+    /** Pixel width of the rendered image. */
+    width: z.number().int(),
+    /** Pixel height of the rendered image. */
+    height: z.number().int(),
+    /** Encoding of the image embedded in `dataUrl`. */
+    format: z.enum(["jpeg", "png"]),
+});
+/* ------------------------------------------------------------------ */
+/* Payload routing                                                    */
+/* ------------------------------------------------------------------ */
+/**
+ * Maps each artifact name to the zod schema for its payload. Use this to validate
+ * a payload before persisting it or after fetching it by ref:
+ *
+ *   ArtifactPayloadSchemas[name].parse(payload)
+ */
+export const ArtifactPayloadSchemas = {
+    console: ConsoleArtifactSchema,
+    network: NetworkArtifactSchema,
+    clientState: ClientStateArtifactSchema,
+    storage: StorageArtifactSchema,
+    dom: DomArtifactSchema,
+    trace: TraceArtifactSchema,
+    screenshot: ScreenshotArtifactSchema,
+};
+/* ------------------------------------------------------------------ */
+/* Bundle assembly                                                    */
+/* ------------------------------------------------------------------ */
+/**
+ * What the `<ReportButton>` produces and POSTs to create a ticket: the head's
+ * report core plus every captured artifact payload inline. The server splits this
+ * into the persisted head (with a built index) and the artifact rows.
+ */
+export const ReportBundleSchema = z.object({
+    reporter: z.string(),
+    /**
+     * Which project/tenant this report belongs to (the SaaS seam). The widget is
+     * configured with a `projectKey` and stamps it here; the server persists it onto
+     * the {@link TicketHead}. Null when the widget is unkeyed (single-tenant); making
+     * multi-tenancy real is a later flip, not a schema rewrite.
+     */
+    projectKey: z.string().nullable(),
+    report: ReportSchema,
+    artifacts: z
+        .object({
+        console: ConsoleArtifactSchema.optional(),
+        network: NetworkArtifactSchema.optional(),
+        clientState: ClientStateArtifactSchema.optional(),
+        storage: StorageArtifactSchema.optional(),
+        dom: DomArtifactSchema.optional(),
+        trace: TraceArtifactSchema.optional(),
+        screenshot: ScreenshotArtifactSchema.optional(),
+    })
+        .partial(),
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@paikko/contract",
+  "version": "0.1.0",
+  "description": "paikko shared wire contract: TS types + zod schemas. Pure, no React, no prisma.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/willyt3hwhale/paikko.git",
+    "directory": "packages/contract"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "prepare": "tsc -p tsconfig.json"
+  },
+  "dependencies": {
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "typescript": "^5.6.3"
+  }
+}