@nzila/sdk 0.1.0 → 0.1.3

package/examples/RUNTIME-TRACE.md

@@ -0,0 +1,222 @@
+# Runtime feature tracing (`traceNzilaFeature` / `useNzilaFeature`)
+
+Pair **Vitest** failures (webhook) with **live** signals on the same **feature** name (e.g. `Checkout`). Call one function at the top of the UI component or backend handler that owns that feature; use **`captureError`** when you already handle errors.
+
+## SDK package exports
+
+| Import path | Use for |
+|-------------|---------|
+| `@nzila/sdk` | `initNzilaRuntime`, `traceNzilaFeature`, `reportFeatureError`, Vitest/Jest reporters |
+| `@nzila/sdk/react` | `useNzilaFeature`, `NzilaFeatureBoundary`, `reportFeatureError` |
+| `@nzila/sdk/runtime` | Low-level runtime client only |
+| `@nzila/sdk/vitest` | `NzilaVitestReporter` |
+
+---
+
+## Setup (once per app)
+
+```ts
+import { initNzilaRuntime } from "@nzila/sdk/runtime";
+// or: import { initNzilaRuntime } from "@nzila/sdk";
+
+initNzilaRuntime({
+  signalsUrl: process.env.NZILA_SIGNALS_URL!, // https://your-app.vercel.app/api/signals/runtime
+  apiKey: process.env.NZILA_API_KEY!,
+  locale: "en",
+  renderLoopThreshold: 40, // optional — React render-loop detection
+});
+```
+
+| Variable | Where |
+|----------|--------|
+| `NZILA_SIGNALS_URL` | Node / Route Handlers |
+| `NEXT_PUBLIC_NZILA_SIGNALS_URL` | Browser (Next.js) |
+| `NZILA_API_KEY` / `NEXT_PUBLIC_NZILA_API_KEY` | Same project key as test webhooks |
+
+Requires DB migration `0003_feature_intelligence.sql` (`npm run db:migrate`).
+
+---
+
+## API reference
+
+| Function | Signature | When to use |
+|----------|-----------|-------------|
+| `initNzilaRuntime` | `(config)` once | Before any trace calls |
+| `useNzilaFeature` | `(feature, options?)` | **Top of React component** |
+| `traceNzilaFeature` | `(feature)` | **Top of backend handler** |
+| `handle.captureError` | `(error, detail?)` | Your `try/catch`, toasts, form errors |
+| `handle.captureApiError` | `(error, label, detail?)` | Caught fetch/HTTP without `runApi` |
+| `handle.runApi` | `(label, fn)` | Wrap async API calls |
+| `handle.reportError` | same as `captureError` | Alias |
+| `reportFeatureError` | `(feature, error, detail?)` | Shared util; pass feature + error |
+| `captureFeatureError` | alias of `reportFeatureError` | |
+| `extractErrorFields` | `(error)` | `message`, `name`, `stack` normalization |
+
+Returned **handle** (from hook or `traceNzilaFeature`): `{ feature, runApi, captureError, captureApiError, reportError, reportUi }`.
+
+---
+
+## React — `useNzilaFeature` at the top of the component
+
+```tsx
+"use client";
+
+import { useNzilaFeature } from "@nzila/sdk/react";
+import { initNzilaRuntime } from "@nzila/sdk/react";
+
+// e.g. app/layout.tsx or instrumentation.ts (once)
+initNzilaRuntime({
+  signalsUrl: process.env.NEXT_PUBLIC_NZILA_SIGNALS_URL!,
+  apiKey: process.env.NEXT_PUBLIC_NZILA_API_KEY!,
+});
+
+export function CheckoutPage() {
+  const nzila = useNzilaFeature("Checkout"); // same feature as Vitest mapFeature
+
+  async function pay() {
+    await nzila.runApi("POST /api/checkout", () =>
+      fetch("/api/checkout", { method: "POST", body: "{}" }),
+    );
+  }
+
+  return <button onClick={() => void pay()}>Pay</button>;
+}
+```
+
+### Manual error handling (your `try/catch`)
+
+Use the handle from the hook (feature is already bound):
+
+```tsx
+export function CheckoutPage() {
+  const nzila = useNzilaFeature("Checkout");
+
+  async function pay() {
+    try {
+      await nzila.runApi("POST /api/checkout", () =>
+        fetch("/api/checkout", { method: "POST" }),
+      );
+    } catch (err) {
+      nzila.captureError(err, { step: "pay", handled: true });
+      // your toast / form error state
+    }
+  }
+}
+```
+
+Or pass **feature + error** from anywhere (e.g. shared error util):
+
+```ts
+import { reportFeatureError } from "@nzila/sdk/react";
+
+reportFeatureError("Checkout", error, { step: "validation" });
+```
+
+`captureError` uses `extractErrorFields` — works with `Error`, strings, and unknown values.
+
+### What is reported automatically
+
+| Issue | Signal `type` | `payload` notes |
+|-------|---------------|-----------------|
+| Too many re-renders in ~1s | `ui` | `kind: "render_loop"`, `renderCount` |
+| `window.onerror` | `error` | while component mounted |
+| Unhandled promise rejection | `error` | while mounted |
+| `runApi` failure | `api` | `success: false`, message |
+| `runApi` success | `api` | `success: true`, `label` |
+
+Optional error boundary:
+
+```tsx
+import { NzilaFeatureBoundary } from "@nzila/sdk/react";
+
+<NzilaFeatureBoundary feature="Checkout" nzila={nzila}>
+  <CheckoutForm />
+</NzilaFeatureBoundary>
+```
+
+---
+
+## Backend — `traceNzilaFeature` at the top of the handler
+
+```ts
+import { initNzilaRuntime, traceNzilaFeature } from "@nzila/sdk";
+
+initNzilaRuntime({
+  signalsUrl: process.env.NZILA_SIGNALS_URL!,
+  apiKey: process.env.NZILA_API_KEY!,
+});
+
+export async function postCheckout(req: Request) {
+  const nzila = traceNzilaFeature("Checkout");
+
+  try {
+    const upstream = await nzila.runApi("payment-gateway", () =>
+      fetch("https://api.example.com/charge", { method: "POST" }),
+    );
+    if (!upstream.ok) throw new Error(`charge failed: ${upstream.status}`);
+    return Response.json({ ok: true });
+  } catch (err) {
+    nzila.captureError(err, { route: "POST /checkout", handled: true });
+    return Response.json({ error: "payment_failed" }, { status: 502 });
+  }
+}
+```
+
+Caught an API error without `runApi`?
+
+```ts
+nzila.captureApiError(err, "payment-gateway", { status: 502 });
+```
+
+From a nested helper without the handle:
+
+```ts
+import { reportFeatureError } from "@nzila/sdk";
+
+reportFeatureError("Checkout", err, { layer: "inventory-service" });
+```
+
+Call **`traceNzilaFeature("Checkout")` as the first line** of the route/service that matches your tested feature.
+
+Repo example: [backend/runtime-trace.example.ts](./backend/runtime-trace.example.ts).
+
+---
+
+## Dashboard
+
+Open **Feature health** for the project — compare **tests** (from webhooks) with **runtime** (`api` / `ui` / `error` signals).
+
+Use the **same feature string** everywhere:
+
+| Source | Example |
+|--------|---------|
+| Vitest `describe` / `mapFeature` | `"Checkout"` |
+| `useNzilaFeature("…")` | `"Checkout"` |
+| `traceNzilaFeature("…")` | `"Checkout"` |
+| `reportFeatureError("…", err)` | `"Checkout"` |
+| Manual HTTP (advanced) | `POST /api/signals/runtime` |
+
+Test-side tracing: [TRACING-FAILURES.md](./TRACING-FAILURES.md).  
+Deploy (Vercel + Render): [../docs/DEPLOY-VERCEL-RENDER.md](../docs/DEPLOY-VERCEL-RENDER.md).
+
+---
+
+## Manual HTTP (optional)
+
+Same payload the SDK sends:
+
+```json
+{
+  "locale": "en",
+  "signals": [
+    {
+      "feature": "Checkout",
+      "type": "error",
+      "success": false,
+      "payload": { "message": "card declined", "handled": true }
+    }
+  ]
+}
+```
+
+Types: `navigation`, `api`, `ui`, `error`, `custom`.

package/examples/TRACING-FAILURES.md

@@ -0,0 +1,186 @@
+# Tracing test failures in Nzila
+
+How failures move from **backend** and **frontend** test runs into the dashboard, how to **attach tests to a feature**, and how to trace an error even when the test was already in your suite.
+
+## Mental model
+
+```text
+describe() tree  →  describePath + fingerprint
+mapFeature / feature field  →  dashboard "Feature" column
+test name        →  human label
+errors[]         →  processed into Failure analysis (not raw stacks in UI)
+worker           →  summaries + feature health
+```
+
+1. Vitest finishes one run → reporter sends **one** webhook (`runId` is idempotent).
+2. Each test becomes a row with `describePath`, `feature`, `testName`, `status`, `errors`.
+3. The worker enriches failures and updates **Stability**, **Failures**, and **Feature health**.
+
+## Developer setup (one-time)
+
+### 1. Run Nzila locally
+
+From the repo root (see [README](../README.md)):
+
+```bash
+npm install
+cp .env.example .env.local   # fill DATABASE_URL, AUTH_SECRET, etc.
+npm run db:migrate
+npm run dev                  # http://localhost:3000
+npm run worker               # second terminal — processes webhooks
+```
+
+### 2. Create two projects (API + web)
+
+In the dashboard, create **two** projects so backend and frontend keys do not mix:
+
+| Project display name | **App name** (must match Vitest `appName`) | Example tests |
+|----------------------|------------------------------------------|---------------|
+| Checkout API         | `checkout-api`                           | `examples/backend/` |
+| Checkout Web         | `checkout-web`                           | `examples/frontend/` |
+
+For each project: **Settings → API keys** → create a key. You can use one key for both demos if both projects belong to your org and you switch `NZILA_API_KEY` when running each suite — separate keys are clearer.
+
+### 3. Configure `.env.local`
+
+```bash
+NZILA_WEBHOOK_URL=http://localhost:3000/api/webhooks/tests
+NZILA_API_KEY=nzl_your_key_for_checkout_api
+```
+
+For frontend tracing, use the **checkout-web** key (or change the key before `example:test:tracing:frontend`).
+
+### 4. Run tracing demos
+
+```bash
+npm run example:test:tracing:backend    # failures → checkout-api
+npm run example:test:tracing:frontend   # failures → checkout-web
+npm run example:test:tracing:all        # both
+```
+
+Tracing-only Vitest configs (reporter + `mapFeature`):
+
+- `examples/vitest.tracing.backend.config.ts`
+- `examples/vitest.tracing.frontend.config.ts`
+
+## Attach tests to a feature
+
+Nzila groups failures and health by **feature** string. You have three ways to set it:
+
+### A. Top-level `describe` name (default)
+
+The Vitest reporter uses the **first** `describe()` segment as `feature` unless you override with `mapFeature`.
+
+```ts
+describe("Checkout", () => {
+  it("should reject expired cards", () => { /* ... */ });
+});
+```
+
+→ `feature: "Checkout"`, fingerprint includes full `describePath`.
+
+### B. `mapFeature` in the reporter (recommended for UI vs product names)
+
+When suite titles are long (e.g. `"Checkout UI"`) but the product feature is `"Checkout"`, map them in config:
+
+```ts
+// examples/shared/feature-map.ts
+export function resolveFrontendFeature(describePath: string[], _testName: string) {
+  if (describePath[0] === "Checkout UI") return "Checkout";
+  return describePath[0] ?? "general";
+}
+```
+
+Wire it in `NzilaVitestReporter({ mapFeature: resolveFrontendFeature, ... })`.
+
+### C. Explicit `feature` in webhook JSON
+
+For manual/CI payloads, set `feature` on each test (see `examples/backend/sample-tracing-payload.json` and `examples/frontend/sample-tracing-payload.json`):
+
+```json
+{
+  "describePath": ["Checkout UI", "email field"],
+  "feature": "Checkout",
+  "testName": "should reject malformed email addresses",
+  "status": "failed",
+  "errors": [{ "message": "...", "stack": "..." }]
+}
+```
+
+Server fallback: `feature ?? describePath[0] ?? "general"` (`ensureTestCase`).
+
+**Runtime signals** should use the **same** feature string so **Feature health** lines up tests and production.
+
+**Recommended (live app):** use the SDK so production matches tests:
+
+| Layer | Call at top of unit | Manual `catch` |
+|-------|---------------------|----------------|
+| React | `const nzila = useNzilaFeature("Checkout")` | `nzila.captureError(err, { … })` |
+| Backend | `const nzila = traceNzilaFeature("Checkout")` | `nzila.captureError(err, { … })` |
+| Either | — | `reportFeatureError("Checkout", err, { … })` |
+
+Auto-reported: render loops (`ui`), `runApi` failures (`api`), unhandled window errors. Full API: **[RUNTIME-TRACE.md](./RUNTIME-TRACE.md)**.
+
+## Example suites
+
+| Layer | File | App name | Script |
+|-------|------|----------|--------|
+| Backend | `examples/backend/error-tracing.test.ts` | `checkout-api` | `npm run example:test:tracing:backend` |
+| Frontend | `examples/frontend/error-tracing.test.ts` | `checkout-web` | `npm run example:test:tracing:frontend` |
+
+Failures are intentional so you can practice tracing without breaking production code paths.
+
+## Trace a failure after tests ran (even with tests in CI)
+
+Tests passing or failing does not block tracing: each **run** is stored with per-test `errors`. When a test **fails** (or starts failing in a new run):
+
+1. **Test runs** (`/en/runs`) — open the latest run for `checkout-api` or `checkout-web`.
+2. **Failure analysis** (`/en/failures`) — read processed summaries (from `errors[].message`, not raw stacks).
+3. **Feature insights** / **Feature health** — filter by the same `feature` you attached in the suite or payload.
+4. **Code** — match **fingerprint**: `describePath[0] › … › testName` (same `describe` + `it` names as in repo).
+
+Optional: send runtime signals for the same feature and compare on **Feature health**.
+
+## Manual webhook (no Vitest)
+
+```bash
+npm run example:webhook:tracing           # backend sample
+npm run example:webhook:tracing:frontend  # frontend sample
+```
+
+Requires `NZILA_API_KEY` and `NZILA_WEBHOOK_URL` in `.env.local` (script loads env via `send-webhook.mjs`).
+
+## Webhook error fields
+
+Per test in `tests[]`:
+
+```json
+{
+  "describePath": ["Checkout", "Payment"],
+  "feature": "Checkout",
+  "testName": "should reject expired cards",
+  "status": "failed",
+  "duration": 42,
+  "errors": [
+    { "message": "expected false to be true", "stack": "AssertionError: ..." }
+  ]
+}
+```
+
+- **message** — drives operator-facing copy after processing.
+- **stack** — optional; used server-side, not shown as-is on **Failures**.
+
+## Related files
+
+| File | Role |
+|------|------|
+| `examples/shared/feature-map.ts` | Backend/frontend feature mapping |
+| `@nzila/sdk/vitest-reporter.ts` | Vitest → webhook + `mapFeature` |
+| `src/lib/webhook-schema.ts` | Payload validation |
+| `src/server/test-cases.ts` | `feature` resolution |
+| `src/server/process-run.ts` | Worker enrichment |
+| `examples/TRACING-FAILURES.md` | This guide (tests) |
+| `examples/RUNTIME-TRACE.md` | Live `useNzilaFeature`, `captureError` |
+| `examples/backend/runtime-trace.example.ts` | Backend handler sample |
+| `@nzila/sdk/runtime/` | Runtime client |
+| `@nzila/sdk/react/` | React hook + boundary |

package/examples/backend/error-tracing.test.ts

@@ -0,0 +1,44 @@
+/**
+ * Demo suite for tracing failures in Nzila.
+ * Top-level describe() names become "feature" in the webhook and dashboard.
+ *
+ * Run: npm run example:test:tracing
+ */
+import { describe, it, expect } from "vitest";
+
+describe("Checkout", () => {
+  describe("Payment", () => {
+    it("should accept valid card payloads", () => {
+      expect({ status: "authorized" }).toEqual({ status: "authorized" });
+    });
+
+    it("should reject expired cards", () => {
+      const cardExpired = false;
+      expect(cardExpired).toBe(true);
+    });
+  });
+
+  describe("Coupons", () => {
+    it("should apply percentage discounts", () => {
+      const total = 100;
+      const discounted = total * 0.9;
+      expect(discounted).toBe(80);
+    });
+  });
+});
+
+describe("Inventory", () => {
+  it("should block checkout when stock is zero", () => {
+    const available = 0;
+    const canCheckout = available > 0;
+    expect(canCheckout).toBe(true);
+  });
+});
+
+describe("Auth API", () => {
+  it("should rate-limit repeated login failures", () => {
+    const attempts = 3;
+    const locked = attempts >= 5;
+    expect(locked).toBe(true);
+  });
+});

package/examples/backend/order-pricing.test.ts

@@ -0,0 +1,54 @@
+import { describe, it, expect } from "vitest";
+import { applyCoupon, lineTotal, orderTotal, reserveInventory } from "./order-pricing";
+
+describe("Payment API", () => {
+  describe("order pricing", () => {
+    it("should compute line totals from quantity and unit price", () => {
+      expect(lineTotal({ sku: "SKU-1", qty: 2, unitCents: 1500 })).toBe(3000);
+    });
+
+    it("should apply SAVE10 coupon to subtotal", () => {
+      expect(applyCoupon(10_000, "save10")).toBe(9000);
+    });
+
+    it("should reject negative quantities", () => {
+      expect(() => lineTotal({ sku: "SKU-2", qty: -1, unitCents: 100 })).toThrow();
+    });
+  });
+
+  describe("checkout total", () => {
+    it("should sum multiple line items before coupon", () => {
+      const total = orderTotal(
+        [
+          { sku: "A", qty: 1, unitCents: 2500 },
+          { sku: "B", qty: 2, unitCents: 500 },
+        ],
+        "FREESHIP",
+      );
+      expect(total).toBe(3500);
+    });
+  });
+});
+
+describe("Inventory service", () => {
+  it("should reserve stock when quantity is available", () => {
+    expect(reserveInventory("widget", 3, 10)).toBe(true);
+  });
+
+  it("should fail reservation when stock is insufficient", () => {
+    expect(reserveInventory("widget", 50, 10)).toBe(false);
+  });
+});
+
+describe("Auth API", () => {
+  it("should reject invalid password attempts", () => {
+    const attempts = 6;
+    const maxAttempts = 5;
+    expect(attempts > maxAttempts).toBe(true);
+  });
+
+  it("should lock account after 5 failures", () => {
+    const accountLocked = false;
+    expect(accountLocked).toBe(true);
+  });
+});

package/examples/backend/order-pricing.ts

@@ -0,0 +1,27 @@
+export type LineItem = { sku: string; qty: number; unitCents: number };
+
+export function lineTotal(item: LineItem): number {
+  if (item.qty < 0 || item.unitCents < 0) {
+    throw new Error("Invalid line item");
+  }
+  return item.qty * item.unitCents;
+}
+
+export function applyCoupon(subtotalCents: number, code: string): number {
+  if (subtotalCents < 0) throw new Error("Invalid subtotal");
+  const normalized = code.trim().toUpperCase();
+  if (normalized === "SAVE10") return Math.round(subtotalCents * 0.9);
+  if (normalized === "FREESHIP") return subtotalCents;
+  return subtotalCents;
+}
+
+export function orderTotal(items: LineItem[], coupon?: string): number {
+  const subtotal = items.reduce((sum, item) => sum + lineTotal(item), 0);
+  return coupon ? applyCoupon(subtotal, coupon) : subtotal;
+}
+
+export function reserveInventory(sku: string, qty: number, onHand: number): boolean {
+  if (!sku.trim()) return false;
+  if (qty <= 0) return false;
+  return onHand >= qty;
+}

package/examples/backend/runtime-trace.example.ts

@@ -0,0 +1,31 @@
+/**
+ * Backend pattern: call traceNzilaFeature at the top of the handler
+ * that owns the same feature name as your Vitest suite.
+ *
+ * Env: NZILA_SIGNALS_URL, NZILA_API_KEY
+ */
+import { initNzilaRuntime, traceNzilaFeature } from "@nzila/sdk/runtime";
+
+initNzilaRuntime({
+  signalsUrl:
+    process.env.NZILA_SIGNALS_URL ??
+    "http://localhost:3000/api/signals/runtime",
+  apiKey: process.env.NZILA_API_KEY ?? "",
+  locale: "en",
+});
+
+export async function exampleCheckoutHandler(): Promise<{ ok: boolean }> {
+  const nzila = traceNzilaFeature("Checkout");
+
+  try {
+    await nzila.runApi("inventory-reserve", async () => {
+      const res = await fetch("https://httpbin.org/status/500");
+      if (!res.ok) throw new Error(`inventory ${res.status}`);
+      return res;
+    });
+    return { ok: true };
+  } catch (error) {
+    nzila.captureError(error, { handler: "exampleCheckoutHandler", handled: true });
+    return { ok: false };
+  }
+}

package/examples/backend/sample-payload.json

@@ -0,0 +1,62 @@
+{
+  "runId": "backend-run-placeholder",
+  "appName": "checkout-api",
+  "framework": "vitest",
+  "startedAt": "2026-05-16T14:00:00.000Z",
+  "finishedAt": "2026-05-16T14:00:04.200Z",
+  "tests": [
+    {
+      "appName": "checkout-api",
+      "framework": "vitest",
+      "startedAt": "2026-05-16T14:00:00.000Z",
+      "finishedAt": "2026-05-16T14:00:00.800Z",
+      "describePath": ["Payment API", "order pricing"],
+      "feature": "Payment API",
+      "testName": "should compute line totals from quantity and unit price",
+      "status": "passed",
+      "duration": 12,
+      "errors": []
+    },
+    {
+      "appName": "checkout-api",
+      "framework": "vitest",
+      "startedAt": "2026-05-16T14:00:00.800Z",
+      "finishedAt": "2026-05-16T14:00:01.400Z",
+      "describePath": ["Payment API", "order pricing"],
+      "feature": "Payment API",
+      "testName": "should apply SAVE10 coupon to subtotal",
+      "status": "passed",
+      "duration": 8,
+      "errors": []
+    },
+    {
+      "appName": "checkout-api",
+      "framework": "vitest",
+      "startedAt": "2026-05-16T14:00:01.400Z",
+      "finishedAt": "2026-05-16T14:00:02.000Z",
+      "describePath": ["Inventory service"],
+      "feature": "Inventory",
+      "testName": "should reserve stock when quantity is available",
+      "status": "passed",
+      "duration": 15,
+      "errors": []
+    },
+    {
+      "appName": "checkout-api",
+      "framework": "vitest",
+      "startedAt": "2026-05-16T14:00:02.000Z",
+      "finishedAt": "2026-05-16T14:00:03.200Z",
+      "describePath": ["Auth API"],
+      "feature": "Auth API",
+      "testName": "should lock account after 5 failures",
+      "status": "failed",
+      "duration": 95,
+      "errors": [
+        {
+          "message": "Expected accountLocked to be true, received false",
+          "stack": "AssertionError: expected false to be true\n    at examples/backend/order-pricing.test.ts"
+        }
+      ]
+    }
+  ]
+}