@nzila/sdk 0.1.0 → 0.1.3

package/examples/backend/sample-tracing-payload.json

@@ -0,0 +1,90 @@
+{
+  "runId": "tracing-demo-manual-001",
+  "appName": "checkout-api",
+  "framework": "vitest",
+  "startedAt": "2026-05-16T16:00:00.000Z",
+  "finishedAt": "2026-05-16T16:00:05.000Z",
+  "locale": "en",
+  "tests": [
+    {
+      "appName": "checkout-api",
+      "framework": "vitest",
+      "startedAt": "2026-05-16T16:00:00.000Z",
+      "finishedAt": "2026-05-16T16:00:01.000Z",
+      "describePath": ["Checkout", "Payment"],
+      "feature": "Checkout",
+      "testName": "should accept valid card payloads",
+      "status": "passed",
+      "duration": 10,
+      "errors": []
+    },
+    {
+      "appName": "checkout-api",
+      "framework": "vitest",
+      "startedAt": "2026-05-16T16:00:01.000Z",
+      "finishedAt": "2026-05-16T16:00:02.200Z",
+      "describePath": ["Checkout", "Payment"],
+      "feature": "Checkout",
+      "testName": "should reject expired cards",
+      "status": "failed",
+      "duration": 45,
+      "errors": [
+        {
+          "message": "expected false to be true — card marked valid but expiry check failed",
+          "stack": "AssertionError: expected false to be true\n    at examples/backend/error-tracing.test.ts:18:26"
+        }
+      ]
+    },
+    {
+      "appName": "checkout-api",
+      "framework": "vitest",
+      "startedAt": "2026-05-16T16:00:02.200Z",
+      "finishedAt": "2026-05-16T16:00:03.000Z",
+      "describePath": ["Checkout", "Coupons"],
+      "feature": "Checkout",
+      "testName": "should apply percentage discounts",
+      "status": "failed",
+      "duration": 30,
+      "errors": [
+        {
+          "message": "expected 90 to be 80 — coupon math mismatch",
+          "stack": "AssertionError: expected 90 to be 80\n    at examples/backend/error-tracing.test.ts:26:25"
+        }
+      ]
+    },
+    {
+      "appName": "checkout-api",
+      "framework": "vitest",
+      "startedAt": "2026-05-16T16:00:03.000Z",
+      "finishedAt": "2026-05-16T16:00:04.000Z",
+      "describePath": ["Inventory"],
+      "feature": "Inventory",
+      "testName": "should block checkout when stock is zero",
+      "status": "failed",
+      "duration": 22,
+      "errors": [
+        {
+          "message": "expected false to be true — checkout allowed with zero stock",
+          "stack": "AssertionError: expected false to be true\n    at examples/backend/error-tracing.test.ts:35:24"
+        }
+      ]
+    },
+    {
+      "appName": "checkout-api",
+      "framework": "vitest",
+      "startedAt": "2026-05-16T16:00:04.000Z",
+      "finishedAt": "2026-05-16T16:00:05.000Z",
+      "describePath": ["Auth API"],
+      "feature": "Auth API",
+      "testName": "should rate-limit repeated login failures",
+      "status": "failed",
+      "duration": 18,
+      "errors": [
+        {
+          "message": "expected false to be true — account should lock after threshold",
+          "stack": "AssertionError: expected false to be true\n    at examples/backend/error-tracing.test.ts:43:19"
+        }
+      ]
+    }
+  ]
+}

package/examples/complex/api-services.demo.ts

@@ -0,0 +1,72 @@
+/**
+ * Complex backend example: multiple features, runApi, captureError, reportFeatureError.
+ *
+ * Run with: npx tsx examples/complex/api-services.demo.ts
+ * Env: NZILA_SIGNALS_URL, NZILA_API_KEY
+ */
+import { config } from "dotenv";
+import { resolve } from "node:path";
+import {
+  initNzilaRuntime,
+  reportFeatureError,
+  traceNzilaFeature,
+} from "@nzila/sdk/runtime";
+
+config({ path: resolve(process.cwd(), ".env.local") });
+
+initNzilaRuntime({
+  signalsUrl:
+    process.env.NZILA_SIGNALS_URL ?? "http://localhost:3000/api/signals/runtime",
+  apiKey: process.env.NZILA_API_KEY ?? "",
+  locale: "en",
+});
+
+async function fakePaymentGateway(amount: number): Promise<{ ok: boolean }> {
+  if (amount > 10_000) throw new Error("limit_exceeded");
+  return { ok: true };
+}
+
+export async function checkoutHandler(body: { amount: number; sku: string }) {
+  const nzila = traceNzilaFeature("Checkout");
+
+  try {
+    const inventory = await nzila.runApi("inventory.reserve", async () => {
+      if (body.sku === "OUT_OF_STOCK") throw new Error("no_stock");
+      return { reserved: true };
+    });
+
+    if (!inventory.reserved) {
+      const err = new Error("reservation_failed");
+      nzila.captureError(err, { sku: body.sku, handled: true });
+      return { status: 409 as const, body: { error: "out_of_stock" } };
+    }
+
+    await nzila.runApi("payment.charge", () => fakePaymentGateway(body.amount));
+    return { status: 200 as const, body: { ok: true } };
+  } catch (error) {
+    nzila.captureApiError(error, "checkout.pipeline", { sku: body.sku });
+    return { status: 502 as const, body: { error: "checkout_failed" } };
+  }
+}
+
+export async function inventorySyncJob() {
+  const nzila = traceNzilaFeature("Inventory");
+  try {
+    await nzila.runApi("warehouse.pull", async () => {
+      throw new Error("warehouse_timeout");
+    });
+  } catch (error) {
+    reportFeatureError("Inventory", error, { job: "nightly-sync", handled: true });
+  }
+}
+
+async function main() {
+  console.log("checkout 200:", await checkoutHandler({ amount: 50, sku: "SKU-1" }));
+  console.log("checkout 409:", await checkoutHandler({ amount: 50, sku: "OUT_OF_STOCK" }));
+  console.log("inventory job:");
+  await inventorySyncJob();
+  console.log("Signals queued — wait ~1s for flush.");
+  await new Promise((r) => setTimeout(r, 1500));
+}
+
+void main();

package/examples/complex/full-platform.demo.test.ts

@@ -0,0 +1,46 @@
+/**
+ * Complex Vitest demo: multiple features, mapFeature, passes and failures.
+ * Sends one webhook when the file finishes (NzilaVitestReporter).
+ *
+ * npm run example:test:complex
+ */
+import { describe, expect, it } from "vitest";
+
+describe("Checkout UI", () => {
+  it("shows pay button when cart has items", () => {
+    expect([{ sku: "a" }].length).toBeGreaterThan(0);
+  });
+
+  it("validates card expiry format", () => {
+    const expiry = "13/99";
+    expect(/^\d{2}\/\d{2}$/.test(expiry)).toBe(true);
+  });
+
+  it("surfaces gateway error when charge fails", () => {
+    const gateway = { status: 502, message: "upstream unavailable" };
+    expect(gateway.status).toBe(200);
+  });
+});
+
+describe("Inventory", () => {
+  it("computes available quantity", () => {
+    expect(10 - 3).toBe(7);
+  });
+
+  it("flags oversell when reserved exceeds on-hand", () => {
+    const onHand = 2;
+    const reserved = 5;
+    expect(reserved).toBeLessThanOrEqual(onHand);
+  });
+});
+
+describe("Authentication", () => {
+  it("accepts valid session token shape", () => {
+    expect("sess_abc".startsWith("sess_")).toBe(true);
+  });
+
+  it("rejects expired session", () => {
+    const expired = true;
+    expect(expired).toBe(false);
+  });
+});

package/examples/frontend/checkout-form.test.ts

@@ -0,0 +1,54 @@
+import { describe, it, expect } from "vitest";
+import {
+  canSubmitCheckout,
+  formatCardDisplay,
+  isValidEmail,
+  shippingLabel,
+} from "./checkout-form";
+
+describe("Checkout UI", () => {
+  describe("email field", () => {
+    it("should accept a valid customer email", () => {
+      expect(isValidEmail("buyer@example.com")).toBe(true);
+    });
+
+    it("should reject malformed email addresses", () => {
+      expect(isValidEmail("not-an-email")).toBe(false);
+    });
+  });
+
+  describe("payment display", () => {
+    it("should mask card number showing last four digits", () => {
+      expect(formatCardDisplay("4242")).toBe("•••• •••• •••• 4242");
+    });
+
+    it("should block submit when terms are not accepted", () => {
+      expect(
+        canSubmitCheckout({
+          email: "a@b.co",
+          cardLast4: "1234",
+          country: "US",
+          acceptTerms: false,
+        }),
+      ).toBe(false);
+    });
+  });
+
+  describe("shipping banner", () => {
+    it("should show free shipping over threshold for US", () => {
+      expect(shippingLabel("US", 6000)).toBe("Free shipping");
+    });
+  });
+});
+
+describe("Product card component", () => {
+  it("should render sale badge when discount is active", () => {
+    const discountPct = 20;
+    expect(discountPct >= 15).toBe(true);
+  });
+
+  it("should hide add-to-cart when out of stock", () => {
+    const inStock = 0;
+    expect(inStock > 0).toBe(true);
+  });
+});

package/examples/frontend/checkout-form.ts

@@ -0,0 +1,29 @@
+export type CheckoutForm = {
+  email: string;
+  cardLast4: string;
+  country: string;
+  acceptTerms: boolean;
+};
+
+export function isValidEmail(email: string): boolean {
+  return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email.trim());
+}
+
+export function formatCardDisplay(last4: string): string {
+  const digits = last4.replace(/\D/g, "");
+  if (digits.length !== 4) return "•••• •••• •••• ••••";
+  return `•••• •••• •••• ${digits}`;
+}
+
+export function canSubmitCheckout(form: CheckoutForm): boolean {
+  if (!form.acceptTerms) return false;
+  if (!isValidEmail(form.email)) return false;
+  if (form.country.length !== 2) return false;
+  return form.cardLast4.replace(/\D/g, "").length === 4;
+}
+
+export function shippingLabel(country: string, subtotalCents: number): string {
+  if (country === "US" && subtotalCents >= 5000) return "Free shipping";
+  if (country === "US") return "Standard (3–5 days)";
+  return "International";
+}

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

@@ -0,0 +1,59 @@
+/**
+ * Frontend tracing demo — failures attached to features via mapFeature in
+ * examples/vitest.tracing.frontend.config.ts (Checkout UI → feature "Checkout").
+ *
+ * Run: npm run example:test:tracing:frontend
+ */
+import { describe, it, expect } from "vitest";
+import {
+  canSubmitCheckout,
+  formatCardDisplay,
+  isValidEmail,
+  shippingLabel,
+} from "./checkout-form";
+
+describe("Checkout UI", () => {
+  describe("email field", () => {
+    it("should accept a valid customer email", () => {
+      expect(isValidEmail("buyer@example.com")).toBe(true);
+    });
+
+    it("should reject malformed email addresses", () => {
+      expect(isValidEmail("not-an-email")).toBe(true);
+    });
+  });
+
+  describe("payment display", () => {
+    it("should mask card number showing last four digits", () => {
+      expect(formatCardDisplay("4242")).toBe("•••• •••• •••• 9999");
+    });
+
+    it("should block submit when terms are not accepted", () => {
+      expect(
+        canSubmitCheckout({
+          email: "a@b.co",
+          cardLast4: "1234",
+          country: "US",
+          acceptTerms: false,
+        }),
+      ).toBe(true);
+    });
+  });
+
+  describe("shipping banner", () => {
+    it("should show free shipping over threshold for US", () => {
+      expect(shippingLabel("US", 6000)).toBe("Paid shipping");
+    });
+  });
+});
+
+describe("Product card component", () => {
+  it("should render sale badge when discount is active", () => {
+    expect(20 >= 15).toBe(false);
+  });
+
+  it("should hide add-to-cart when out of stock", () => {
+    const inStock = 0;
+    expect(inStock > 0).toBe(true);
+  });
+});

package/examples/frontend/sample-payload.json

@@ -0,0 +1,62 @@
+{
+  "runId": "frontend-run-placeholder",
+  "appName": "checkout-web",
+  "framework": "vitest",
+  "startedAt": "2026-05-16T14:05:00.000Z",
+  "finishedAt": "2026-05-16T14:05:03.800Z",
+  "tests": [
+    {
+      "appName": "checkout-web",
+      "framework": "vitest",
+      "startedAt": "2026-05-16T14:05:00.000Z",
+      "finishedAt": "2026-05-16T14:05:00.600Z",
+      "describePath": ["Checkout UI", "email field"],
+      "feature": "Checkout UI",
+      "testName": "should accept a valid customer email",
+      "status": "passed",
+      "duration": 22,
+      "errors": []
+    },
+    {
+      "appName": "checkout-web",
+      "framework": "vitest",
+      "startedAt": "2026-05-16T14:05:00.600Z",
+      "finishedAt": "2026-05-16T14:05:01.200Z",
+      "describePath": ["Checkout UI", "payment display"],
+      "feature": "Checkout UI",
+      "testName": "should mask card number showing last four digits",
+      "status": "passed",
+      "duration": 18,
+      "errors": []
+    },
+    {
+      "appName": "checkout-web",
+      "framework": "vitest",
+      "startedAt": "2026-05-16T14:05:01.200Z",
+      "finishedAt": "2026-05-16T14:05:02.400Z",
+      "describePath": ["Checkout UI", "shipping banner"],
+      "feature": "Checkout UI",
+      "testName": "should show free shipping over threshold for US",
+      "status": "passed",
+      "duration": 11,
+      "errors": []
+    },
+    {
+      "appName": "checkout-web",
+      "framework": "vitest",
+      "startedAt": "2026-05-16T14:05:02.400Z",
+      "finishedAt": "2026-05-16T14:05:03.800Z",
+      "describePath": ["Product card component"],
+      "feature": "Product card",
+      "testName": "should hide add-to-cart when out of stock",
+      "status": "failed",
+      "duration": 40,
+      "errors": [
+        {
+          "message": "Expected inStock > 0 to be true, received false",
+          "stack": "AssertionError: expected false to be true\n    at examples/frontend/checkout-form.test.ts"
+        }
+      ]
+    }
+  ]
+}

package/examples/frontend/sample-tracing-payload.json

@@ -0,0 +1,73 @@
+{
+  "runId": "tracing-frontend-manual-001",
+  "appName": "checkout-web",
+  "framework": "vitest",
+  "startedAt": "2026-05-16T17:00:00.000Z",
+  "finishedAt": "2026-05-16T17:00:04.500Z",
+  "locale": "en",
+  "tests": [
+    {
+      "appName": "checkout-web",
+      "framework": "vitest",
+      "startedAt": "2026-05-16T17:00:00.000Z",
+      "finishedAt": "2026-05-16T17:00:01.000Z",
+      "describePath": ["Checkout UI", "email field"],
+      "feature": "Checkout",
+      "testName": "should accept a valid customer email",
+      "status": "passed",
+      "duration": 8,
+      "errors": []
+    },
+    {
+      "appName": "checkout-web",
+      "framework": "vitest",
+      "startedAt": "2026-05-16T17:00:01.000Z",
+      "finishedAt": "2026-05-16T17:00:01.800Z",
+      "describePath": ["Checkout UI", "email field"],
+      "feature": "Checkout",
+      "testName": "should reject malformed email addresses",
+      "status": "failed",
+      "duration": 35,
+      "errors": [
+        {
+          "message": "expected false to be true — invalid email was accepted in the form",
+          "stack": "AssertionError: expected false to be true\n    at examples/frontend/error-tracing.test.ts:22:45"
+        }
+      ]
+    },
+    {
+      "appName": "checkout-web",
+      "framework": "vitest",
+      "startedAt": "2026-05-16T17:00:01.800Z",
+      "finishedAt": "2026-05-16T17:00:02.600Z",
+      "describePath": ["Checkout UI", "payment display"],
+      "feature": "Checkout",
+      "testName": "should block submit when terms are not accepted",
+      "status": "failed",
+      "duration": 28,
+      "errors": [
+        {
+          "message": "expected false to be true — checkout allowed without accepting terms",
+          "stack": "AssertionError: expected false to be true\n    at examples/frontend/error-tracing.test.ts:38:9"
+        }
+      ]
+    },
+    {
+      "appName": "checkout-web",
+      "framework": "vitest",
+      "startedAt": "2026-05-16T17:00:02.600Z",
+      "finishedAt": "2026-05-16T17:00:03.400Z",
+      "describePath": ["Product card component"],
+      "feature": "Product catalog",
+      "testName": "should hide add-to-cart when out of stock",
+      "status": "failed",
+      "duration": 22,
+      "errors": [
+        {
+          "message": "expected false to be true — add-to-cart visible with zero stock",
+          "stack": "AssertionError: expected false to be true\n    at examples/frontend/error-tracing.test.ts:56:24"
+        }
+      ]
+    }
+  ]
+}

package/examples/frontend-webhook-client.ts

@@ -0,0 +1,32 @@
+/**
+ * Call the Nzila webhook from your **backend** (Next.js Route Handler, BFF, CI).
+ * Never import this from client components — API keys must stay server-side.
+ */
+import axios from "axios";
+import type { WebhookPayload } from "../src/lib/webhook-schema";
+
+export type SendWebhookOptions = {
+  baseUrl?: string;
+  apiKey: string;
+  payload: WebhookPayload;
+};
+
+export async function sendNzilaWebhook({
+  baseUrl = process.env.NZILA_WEBHOOK_URL ?? "http://localhost:3000/api/webhooks/tests",
+  apiKey,
+  payload,
+}: SendWebhookOptions) {
+  return axios.post(baseUrl, payload, {
+    headers: {
+      Authorization: `Bearer ${apiKey}`,
+      "Content-Type": "application/json",
+    },
+    validateStatus: () => true,
+  });
+}
+
+/** Backend (API) sample — use after `npm run example:webhook:backend` or build your own payload. */
+export const backendPayloadHint = "examples/backend/sample-payload.json";
+
+/** Frontend (web) sample — use after `npm run example:webhook:frontend`. */
+export const frontendPayloadHint = "examples/frontend/sample-payload.json";

package/examples/jest.config.example.cjs

@@ -0,0 +1,18 @@
+/** @type {import('jest').Config} */
+const NzilaJestReporter = require("../@nzila/sdk/jest-reporter.ts").default;
+
+module.exports = {
+  testEnvironment: "node",
+  reporters: [
+    "default",
+    [
+      NzilaJestReporter,
+      {
+        webhookUrl: process.env.NZILA_WEBHOOK_URL ?? "http://localhost:3000/api/webhooks/tests",
+        apiKey: process.env.NZILA_API_KEY,
+        appName: process.env.NZILA_APP_NAME ?? "my-app",
+        framework: "jest",
+      },
+    ],
+  ],
+};

package/examples/mocharc.nzila.example.cjs

@@ -0,0 +1,21 @@
+const { createMochaNzilaReporter } = require("../@nzila/sdk/mocha-reporter.ts");
+
+module.exports = {
+  reporter: "spec",
+  reporterOptions: undefined,
+  require: [],
+  /** Register in .mocharc.cjs: */
+  // reporter: createMochaNzilaReporter({ ... }),
+};
+
+/** Usage in .mocharc.cjs:
+ * const { createMochaNzilaReporter } = require("./@nzila/sdk/mocha-reporter.ts");
+ * module.exports = {
+ *   reporter: createMochaNzilaReporter({
+ *     webhookUrl: process.env.NZILA_WEBHOOK_URL,
+ *     apiKey: process.env.NZILA_API_KEY,
+ *     appName: process.env.NZILA_APP_NAME,
+ *     framework: "mocha",
+ *   }),
+ * };
+ */

package/examples/react/checkout-feature.example.tsx

@@ -0,0 +1,41 @@
+"use client";
+
+/**
+ * React runtime tracing — same feature name as your Vitest `mapFeature` / describe.
+ * Env: NEXT_PUBLIC_NZILA_SIGNALS_URL or NZILA_SIGNALS_URL, NZILA_API_KEY (server init recommended).
+ */
+import { initNzilaRuntime } from "@nzila/sdk";
+import { useNzilaFeature, NzilaFeatureBoundary } from "@nzila/sdk/react";
+
+initNzilaRuntime({
+  signalsUrl:
+    process.env.NEXT_PUBLIC_NZILA_SIGNALS_URL ??
+    process.env.NZILA_SIGNALS_URL ??
+    "https://your-app.com/api/signals/runtime",
+  apiKey: process.env.NZILA_API_KEY ?? "",
+  locale: "en",
+});
+
+export function CheckoutPage() {
+  const nzila = useNzilaFeature("Checkout");
+
+  async function submit() {
+    try {
+      await nzila.runApi("checkout.submit", async () => {
+        const res = await fetch("/api/checkout", { method: "POST" });
+        if (!res.ok) throw new Error(`HTTP ${res.status}`);
+        return res.json();
+      });
+    } catch (error) {
+      nzila.captureError(error, { step: "submit" });
+    }
+  }
+
+  return (
+    <NzilaFeatureBoundary feature="Checkout" nzila={nzila}>
+      <button type="button" onClick={() => void submit()}>
+        Pay
+      </button>
+    </NzilaFeatureBoundary>
+  );
+}

package/examples/send-run-manual.mjs

@@ -0,0 +1,16 @@
+/**
+ * POST a test run manually with {@link sendNzilaRun} (CI, custom runners).
+ */
+import { sendNzilaRun, type NzilaRunPayload } from "@nzila/sdk";
+import { readFileSync } from "node:fs";
+
+const payload = JSON.parse(
+  readFileSync(new URL("./backend/sample-payload.json", import.meta.url), "utf8"),
+) as NzilaRunPayload;
+
+await sendNzilaRun(payload, {
+  webhookUrl: process.env.NZILA_WEBHOOK_URL ?? "http://localhost:3000/api/webhooks/tests",
+  apiKey: process.env.NZILA_API_KEY ?? "",
+});
+
+console.log("Webhook sent (silent on failure).");

package/examples/shared/feature-map.ts

@@ -0,0 +1,24 @@
+/**
+ * Map Vitest describe() titles to Nzila **feature** names (dashboard grouping).
+ * Use the same strings in runtime signals: POST /api/signals/runtime { "feature": "Checkout" }.
+ */
+
+export function resolveBackendFeature(describePath: string[], _testName: string): string {
+  const root = describePath[0] ?? "general";
+  const map: Record<string, string> = {
+    Checkout: "Checkout",
+    Inventory: "Inventory",
+    "Auth API": "Authentication",
+    "Payment API": "Payment",
+  };
+  return map[root] ?? root;
+}
+
+export function resolveFrontendFeature(describePath: string[], _testName: string): string {
+  const root = describePath[0] ?? "general";
+  const map: Record<string, string> = {
+    "Checkout UI": "Checkout",
+    "Product card component": "Product catalog",
+  };
+  return map[root] ?? root;
+}

package/examples/shared/load-env.mjs

@@ -0,0 +1,24 @@
+import { config } from "dotenv";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const examplesDir = dirname(fileURLToPath(import.meta.url));
+const projectRoot = resolve(examplesDir, "../..");
+
+config({ path: resolve(projectRoot, ".env.local") });
+config({ path: resolve(projectRoot, ".env") });
+
+export function getWebhookEnv() {
+  const apiKey = process.env.NZILA_API_KEY?.trim();
+  const webhookUrl =
+    process.env.NZILA_WEBHOOK_URL?.trim() ??
+    "http://localhost:3000/api/webhooks/tests";
+
+  if (!apiKey) {
+    console.error("Missing NZILA_API_KEY in .env.local");
+    console.error("Create a key at http://localhost:3000/en/keys");
+    process.exit(1);
+  }
+
+  return { apiKey, webhookUrl, projectRoot };
+}