@nzila/sdk 0.1.0 → 0.1.1

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"
+        }
+      ]
+    }
+  ]
+}

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"
+        }
+      ]
+    }
+  ]
+}