@nzila/sdk 0.1.0 → 0.1.1

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 };
+}

package/examples/shared/send-webhook.mjs

@@ -0,0 +1,43 @@
+/**
+ * POST a sample payload to Nzila (backend or frontend JSON under examples/).
+ *
+ * Usage:
+ *   node examples/shared/send-webhook.mjs examples/backend/sample-payload.json
+ *   node examples/shared/send-webhook.mjs examples/frontend/sample-payload.json
+ */
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import axios from "axios";
+import { getWebhookEnv } from "./load-env.mjs";
+
+const payloadArg = process.argv[2];
+if (!payloadArg) {
+  console.error("Usage: node examples/shared/send-webhook.mjs <path-to-payload.json>");
+  process.exit(1);
+}
+
+const { apiKey, webhookUrl, projectRoot } = getWebhookEnv();
+const payloadPath = resolve(projectRoot, payloadArg);
+const payload = JSON.parse(readFileSync(payloadPath, "utf8"));
+payload.runId = `${payload.appName ?? "example"}-${Date.now()}`;
+
+const res = await axios.post(webhookUrl, payload, {
+  headers: {
+    Authorization: `Bearer ${apiKey}`,
+    "Content-Type": "application/json",
+  },
+  validateStatus: () => true,
+});
+
+console.log("Payload:", payloadPath);
+console.log("Status:", res.status);
+console.log("Body:", JSON.stringify(res.data, null, 2));
+
+if (res.status === 403 && res.data?.code === "API_KEY_EXPIRED") {
+  console.error("\nAPI key expired — create a new one at /en/keys");
+  process.exit(1);
+}
+
+if (res.status === 202 || res.status === 200) {
+  console.log("\nView the run: http://localhost:3000/en");
+}

package/examples/vitest.config.example.ts

@@ -0,0 +1,20 @@
+/**
+ * Copy into your app or merge the reporters block into your vitest.config.ts.
+ * Nzila repo uses examples/vitest.config.ts (and backend/frontend-specific configs).
+ */
+import { defineConfig } from "vitest/config";
+import NzilaVitestReporter from "@nzila/sdk/vitest";
+
+export default defineConfig({
+  test: {
+    reporters: [
+      "default",
+      new NzilaVitestReporter({
+        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",
+        maxRetries: 3,
+      }),
+    ],
+  },
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nzila/sdk",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Send test runs to Nzila and trace live feature errors (Vitest, Jest, Mocha, React, Node).",
   "type": "module",
   "license": "MIT",
@@ -14,7 +14,8 @@
   },
   "files": [
     "dist",
-    "README.md"
+    "README.md",
+    "examples"
   ],
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -46,7 +47,8 @@
   },
   "scripts": {
     "build": "tsc -p tsconfig.build.json",
-    "prepublishOnly": "npm run build"
+    "prepare-examples": "node scripts/sync-examples.mjs",
+    "prepublishOnly": "npm run prepare-examples && npm run build"
   },
   "peerDependencies": {
     "react": ">=18.0.0",