@nzila/sdk 0.1.0

package/README.md

@@ -0,0 +1,70 @@
+# @nzila/sdk
+
+Send test runs to Nzila and trace **live** errors on the same **feature** names as your Vitest suites.
+
+**Silent by design:** webhook and runtime delivery never throw, never log to the console, and skip work when URL/key are missing — your app and CI are unaffected if Nzila is down or misconfigured.
+
+## Install
+
+```bash
+npm install @nzila/sdk
+# Vitest projects also need vitest as a peer
+```
+
+## Exports
+
+| Path | Purpose |
+|------|---------|
+| `@nzila/sdk` | Webhook delivery, reporters, runtime tracing |
+| `@nzila/sdk/vitest` | Vitest reporter |
+| `@nzila/sdk/jest` | Jest reporter |
+| `@nzila/sdk/mocha` | Mocha reporter |
+| `@nzila/sdk/react` | `useNzilaFeature`, error boundary |
+| `@nzila/sdk/runtime` | `initNzilaRuntime`, `traceNzilaFeature` |
+
+## Quick start
+
+**Tests (CI):**
+
+```ts
+import NzilaVitestReporter from "@nzila/sdk/vitest";
+
+export default defineConfig({
+  test: {
+    reporters: [
+      "default",
+      new NzilaVitestReporter({
+        webhookUrl: process.env.NZILA_WEBHOOK_URL!,
+        apiKey: process.env.NZILA_API_KEY!,
+        appName: "my-app",
+        mapFeature: (path) => path[0] ?? "general",
+      }),
+    ],
+  },
+});
+```
+
+**React (runtime):**
+
+```ts
+import { initNzilaRuntime } from "@nzila/sdk";
+import { useNzilaFeature } from "@nzila/sdk/react";
+
+initNzilaRuntime({ signalsUrl: "…/api/signals/runtime", apiKey: "nzl_…" });
+
+function Checkout() {
+  const nzila = useNzilaFeature("Checkout");
+  // nzila.captureError(err) in catch; nzila.runApi("label", () => fetch(...))
+}
+```
+
+**Backend:**
+
+```ts
+import { initNzilaRuntime, traceNzilaFeature } from "@nzila/sdk";
+
+const nzila = traceNzilaFeature("Checkout");
+await nzila.runApi("charge", () => charge());
+```
+
+See JSDoc on each export in `src/` and the monorepo guide [examples/COMPLEX-USAGE.md](../../examples/COMPLEX-USAGE.md).

package/dist/deliver.d.ts

@@ -0,0 +1,26 @@
+import type { NzilaRunPayload } from "./types.js";
+/** Options for {@link sendNzilaRun}. */
+export type DeliverOptions = {
+    /** Full URL to `POST /api/webhooks/tests` on your Nzila host. */
+    webhookUrl: string;
+    /** Project API key (`Authorization: Bearer …`). */
+    apiKey: string;
+    /** Retry count on non-2xx (default 3). */
+    maxRetries?: number;
+};
+/**
+ * POST a completed test run payload to Nzila.
+ * Never throws and never logs — failures are ignored so CI and apps stay unaffected.
+ *
+ * @param payload - Run metadata and `tests[]` from your runner.
+ * @param options - Webhook URL and API key.
+ */
+export declare function sendNzilaRun(payload: NzilaRunPayload, options: DeliverOptions): Promise<void>;
+/**
+ * Resolve dashboard locale for summaries from explicit value or `NZILA_LOCALE` env.
+ *
+ * @param explicit - Reporter option or caller override.
+ * @returns A supported locale or `undefined` if unset/invalid.
+ */
+export declare function resolveLocale(explicit?: string): "en" | "pt" | "fr" | "zh" | undefined;
+//# sourceMappingURL=deliver.d.ts.map

package/dist/deliver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"deliver.d.ts","sourceRoot":"","sources":["../src/deliver.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAGlD,wCAAwC;AACxC,MAAM,MAAM,cAAc,GAAG;IAC3B,iEAAiE;IACjE,UAAU,EAAE,MAAM,CAAC;IACnB,mDAAmD;IACnD,MAAM,EAAE,MAAM,CAAC;IACf,0CAA0C;IAC1C,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB,CAAC;AAEF;;;;;;GAMG;AACH,wBAAsB,YAAY,CAChC,OAAO,EAAE,eAAe,EACxB,OAAO,EAAE,cAAc,GACtB,OAAO,CAAC,IAAI,CAAC,CA+Bf;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAC3B,QAAQ,CAAC,EAAE,MAAM,GAChB,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,SAAS,CAOvC"}

package/dist/deliver.js

@@ -0,0 +1,52 @@
+import { nzilaSafeAsync } from "./silent.js";
+/**
+ * POST a completed test run payload to Nzila.
+ * Never throws and never logs — failures are ignored so CI and apps stay unaffected.
+ *
+ * @param payload - Run metadata and `tests[]` from your runner.
+ * @param options - Webhook URL and API key.
+ */
+export async function sendNzilaRun(payload, options) {
+    await nzilaSafeAsync(async () => {
+        const webhookUrl = options?.webhookUrl?.trim();
+        const apiKey = options?.apiKey?.trim();
+        if (!webhookUrl || !apiKey)
+            return;
+        const maxRetries = options.maxRetries ?? 3;
+        let attempt = 0;
+        while (attempt < maxRetries) {
+            attempt += 1;
+            try {
+                const res = await fetch(webhookUrl, {
+                    method: "POST",
+                    headers: {
+                        Authorization: `Bearer ${apiKey}`,
+                        "Content-Type": "application/json",
+                    },
+                    body: JSON.stringify(payload),
+                });
+                if (res.ok || res.status === 200 || res.status === 202) {
+                    return;
+                }
+            }
+            catch {
+                /* network — retry */
+            }
+            await new Promise((r) => setTimeout(r, attempt * 1000));
+        }
+    });
+}
+/**
+ * Resolve dashboard locale for summaries from explicit value or `NZILA_LOCALE` env.
+ *
+ * @param explicit - Reporter option or caller override.
+ * @returns A supported locale or `undefined` if unset/invalid.
+ */
+export function resolveLocale(explicit) {
+    const fromEnv = process.env?.NZILA_LOCALE;
+    const value = explicit ?? fromEnv;
+    if (value === "en" || value === "pt" || value === "fr" || value === "zh") {
+        return value;
+    }
+    return undefined;
+}

package/dist/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * @nzila/sdk — test webhooks (Vitest/Jest/Mocha) and runtime feature tracing.
+ *
+ * @packageDocumentation
+ */
+export { NZILA_TEST_FRAMEWORKS, type NzilaTestFramework, type NzilaTestStatus, type NzilaLocale, type NzilaTestCase, type NzilaRunPayload, type NzilaClientOptions, } from "./types.js";
+export { sendNzilaRun, resolveLocale, type DeliverOptions } from "./deliver.js";
+export { initNzilaRuntime, isNzilaRuntimeReady, traceNzilaFeature, createFeatureHandle, reportFeatureError, captureFeatureError, extractErrorFields, type NzilaFeatureHandle, type NzilaRuntimeConfig, type NzilaRuntimeSignal, } from "./runtime/index.js";
+export { default as NzilaVitestReporter } from "./vitest-reporter.js";
+export { default as NzilaJestReporter } from "./jest-reporter.js";
+export { createMochaNzilaReporter, default as mochaNzilaReporterFactory } from "./mocha-reporter.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EACL,qBAAqB,EACrB,KAAK,kBAAkB,EACvB,KAAK,eAAe,EACpB,KAAK,WAAW,EAChB,KAAK,aAAa,EAClB,KAAK,eAAe,EACpB,KAAK,kBAAkB,GACxB,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,KAAK,cAAc,EAAE,MAAM,cAAc,CAAC;AAChF,OAAO,EACL,gBAAgB,EAChB,mBAAmB,EACnB,iBAAiB,EACjB,mBAAmB,EACnB,kBAAkB,EAClB,mBAAmB,EACnB,kBAAkB,EAClB,KAAK,kBAAkB,EACvB,KAAK,kBAAkB,EACvB,KAAK,kBAAkB,GACxB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,OAAO,IAAI,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AACtE,OAAO,EAAE,OAAO,IAAI,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAClE,OAAO,EAAE,wBAAwB,EAAE,OAAO,IAAI,yBAAyB,EAAE,MAAM,qBAAqB,CAAC"}

package/dist/index.js

@@ -0,0 +1,11 @@
+/**
+ * @nzila/sdk — test webhooks (Vitest/Jest/Mocha) and runtime feature tracing.
+ *
+ * @packageDocumentation
+ */
+export { NZILA_TEST_FRAMEWORKS, } from "./types.js";
+export { sendNzilaRun, resolveLocale } from "./deliver.js";
+export { initNzilaRuntime, isNzilaRuntimeReady, traceNzilaFeature, createFeatureHandle, reportFeatureError, captureFeatureError, extractErrorFields, } from "./runtime/index.js";
+export { default as NzilaVitestReporter } from "./vitest-reporter.js";
+export { default as NzilaJestReporter } from "./jest-reporter.js";
+export { createMochaNzilaReporter, default as mochaNzilaReporterFactory } from "./mocha-reporter.js";

package/dist/jest-reporter.d.ts

@@ -0,0 +1,41 @@
+import type { NzilaClientOptions } from "./types.js";
+type JestAssertion = {
+    failureMessages?: string[];
+};
+type JestTestResult = {
+    title: string;
+    fullName: string;
+    status: "passed" | "failed" | "pending" | "skipped" | "todo" | "disabled";
+    duration?: number | null;
+    failureMessages?: string[];
+    ancestorTitles: string[];
+};
+type JestAggregated = {
+    testResults: {
+        testFilePath: string;
+        perfStats: {
+            start: number;
+            end: number;
+        };
+        testResults: JestTestResult[];
+    }[];
+};
+/**
+ * Jest reporter: aggregates results and POSTs one {@link sendNzilaRun} payload on `onRunComplete`.
+ *
+ * @example
+ * ```js
+ * reporters: [["@nzila/sdk/jest", { webhookUrl, apiKey, appName: "my-app" }]],
+ * ```
+ */
+export default class NzilaJestReporter {
+    private readonly options;
+    private readonly runId;
+    private sent;
+    constructor(options: NzilaClientOptions, _globalConfig?: unknown);
+    onRunComplete(_contexts: unknown, results: JestAggregated): void;
+    private mapStatus;
+}
+/** Unused — satisfies older Jest typings */
+export type { JestAssertion };
+//# sourceMappingURL=jest-reporter.d.ts.map

package/dist/jest-reporter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"jest-reporter.d.ts","sourceRoot":"","sources":["../src/jest-reporter.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACV,kBAAkB,EAInB,MAAM,YAAY,CAAC;AAEpB,KAAK,aAAa,GAAG;IAAE,eAAe,CAAC,EAAE,MAAM,EAAE,CAAA;CAAE,CAAC;AAEpD,KAAK,cAAc,GAAG;IACpB,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,QAAQ,GAAG,QAAQ,GAAG,SAAS,GAAG,SAAS,GAAG,MAAM,GAAG,UAAU,CAAC;IAC1E,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;IAC3B,cAAc,EAAE,MAAM,EAAE,CAAC;CAC1B,CAAC;AAEF,KAAK,cAAc,GAAG;IACpB,WAAW,EAAE;QACX,YAAY,EAAE,MAAM,CAAC;QACrB,SAAS,EAAE;YAAE,KAAK,EAAE,MAAM,CAAC;YAAC,GAAG,EAAE,MAAM,CAAA;SAAE,CAAC;QAC1C,WAAW,EAAE,cAAc,EAAE,CAAC;KAC/B,EAAE,CAAC;CACL,CAAC;AAEF;;;;;;;GAOG;AACH,MAAM,CAAC,OAAO,OAAO,iBAAiB;IACpC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAqB;IAC7C,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;IAC/B,OAAO,CAAC,IAAI,CAAS;gBAET,OAAO,EAAE,kBAAkB,EAAE,aAAa,CAAC,EAAE,OAAO;IAKhE,aAAa,CAAC,SAAS,EAAE,OAAO,EAAE,OAAO,EAAE,cAAc;IA8CzD,OAAO,CAAC,SAAS;CAQlB;AAED,4CAA4C;AAC5C,YAAY,EAAE,aAAa,EAAE,CAAC"}

package/dist/jest-reporter.js

@@ -0,0 +1,68 @@
+import { randomUUID } from "node:crypto";
+import { sendNzilaRun, resolveLocale } from "./deliver.js";
+/**
+ * Jest reporter: aggregates results and POSTs one {@link sendNzilaRun} payload on `onRunComplete`.
+ *
+ * @example
+ * ```js
+ * reporters: [["@nzila/sdk/jest", { webhookUrl, apiKey, appName: "my-app" }]],
+ * ```
+ */
+export default class NzilaJestReporter {
+    constructor(options, _globalConfig) {
+        this.sent = false;
+        this.options = options;
+        this.runId = options.runId ?? randomUUID();
+    }
+    onRunComplete(_contexts, results) {
+        if (this.sent)
+            return;
+        this.sent = true;
+        const framework = this.options.framework ?? "jest";
+        const tests = [];
+        let startedAt = Date.now();
+        let finishedAt = Date.now();
+        for (const file of results.testResults ?? []) {
+            startedAt = Math.min(startedAt, file.perfStats.start);
+            finishedAt = Math.max(finishedAt, file.perfStats.end);
+            for (const test of file.testResults) {
+                const describePath = test.ancestorTitles ?? [];
+                tests.push({
+                    appName: this.options.appName,
+                    framework,
+                    startedAt: new Date(file.perfStats.start).toISOString(),
+                    finishedAt: new Date(file.perfStats.end).toISOString(),
+                    describePath,
+                    feature: describePath[0],
+                    testName: test.title,
+                    status: this.mapStatus(test.status),
+                    duration: test.duration ?? 0,
+                    errors: (test.failureMessages ?? []).map((message) => ({ message })),
+                });
+            }
+        }
+        if (!tests.length)
+            return;
+        const locale = resolveLocale(this.options.locale);
+        const payload = {
+            runId: this.runId,
+            appName: this.options.appName,
+            framework,
+            startedAt: new Date(startedAt).toISOString(),
+            finishedAt: new Date(finishedAt).toISOString(),
+            tests,
+            ...(locale ? { locale } : {}),
+        };
+        void sendNzilaRun(payload, this.options);
+    }
+    mapStatus(status) {
+        if (status === "passed")
+            return "passed";
+        if (status === "failed")
+            return "failed";
+        if (status === "skipped" || status === "pending" || status === "todo" || status === "disabled") {
+            return status === "pending" || status === "todo" ? "pending" : "skipped";
+        }
+        return "pending";
+    }
+}

package/dist/mocha-reporter.d.ts

@@ -0,0 +1,24 @@
+import type { NzilaClientOptions } from "./types.js";
+type MochaTest = {
+    title: string;
+    fullTitle: () => string;
+    parent?: MochaTest & {
+        title: string;
+        parent?: MochaTest;
+    };
+    duration?: number;
+    err?: Error;
+    state?: "passed" | "failed";
+    pending?: boolean;
+};
+type MochaRunner = {
+    on(event: "pass" | "fail" | "pending" | "end", fn: (test: MochaTest) => void): void;
+    stats?: {
+        start?: Date;
+        end?: Date;
+    };
+};
+export type MochaNzilaOptions = NzilaClientOptions;
+export declare function createMochaNzilaReporter(options: MochaNzilaOptions): (runner: MochaRunner) => void;
+export default createMochaNzilaReporter;
+//# sourceMappingURL=mocha-reporter.d.ts.map

package/dist/mocha-reporter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mocha-reporter.d.ts","sourceRoot":"","sources":["../src/mocha-reporter.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,kBAAkB,EAAmD,MAAM,YAAY,CAAC;AAEtG,KAAK,SAAS,GAAG;IACf,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,MAAM,CAAC;IACxB,MAAM,CAAC,EAAE,SAAS,GAAG;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,SAAS,CAAA;KAAE,CAAC;IAC3D,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,GAAG,CAAC,EAAE,KAAK,CAAC;IACZ,KAAK,CAAC,EAAE,QAAQ,GAAG,QAAQ,CAAC;IAC5B,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB,CAAC;AAEF,KAAK,WAAW,GAAG;IACjB,EAAE,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,GAAG,KAAK,EAAE,EAAE,EAAE,CAAC,IAAI,EAAE,SAAS,KAAK,IAAI,GAAG,IAAI,CAAC;IACpF,KAAK,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,IAAI,CAAC;QAAC,GAAG,CAAC,EAAE,IAAI,CAAA;KAAE,CAAC;CACtC,CAAC;AAEF,MAAM,MAAM,iBAAiB,GAAG,kBAAkB,CAAC;AAEnD,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,iBAAiB,IAC9B,QAAQ,WAAW,UA4DvD;AAED,eAAe,wBAAwB,CAAC"}

package/dist/mocha-reporter.js

@@ -0,0 +1,58 @@
+import { randomUUID } from "node:crypto";
+import { sendNzilaRun, resolveLocale } from "./deliver.js";
+export function createMochaNzilaReporter(options) {
+    return function mochaNzilaReporter(runner) {
+        const runId = options.runId ?? randomUUID();
+        const framework = options.framework ?? "mocha";
+        const cases = [];
+        const startedAt = new Date();
+        const describePath = (test) => {
+            const parts = [];
+            let node = test.parent;
+            while (node?.title) {
+                parts.unshift(node.title);
+                node = node.parent;
+            }
+            return parts;
+        };
+        const push = (test, status) => {
+            const path = describePath(test);
+            const finishedAt = new Date().toISOString();
+            cases.push({
+                appName: options.appName,
+                framework,
+                startedAt: startedAt.toISOString(),
+                finishedAt,
+                describePath: path,
+                feature: path[0],
+                testName: test.title,
+                status,
+                duration: test.duration ?? 0,
+                errors: test.err != null
+                    ? [{ message: test.err.message ?? String(test.err), stack: test.err.stack }]
+                    : [],
+            });
+        };
+        runner.on("pass", (test) => push(test, "passed"));
+        runner.on("fail", (test) => push(test, "failed"));
+        runner.on("pending", (test) => push(test, "skipped"));
+        runner.on("end", () => {
+            if (!cases.length)
+                return;
+            const end = runner.stats?.end ?? new Date();
+            const start = runner.stats?.start ?? startedAt;
+            const locale = resolveLocale(options.locale);
+            const payload = {
+                runId,
+                appName: options.appName,
+                framework,
+                startedAt: start.toISOString(),
+                finishedAt: end.toISOString(),
+                tests: cases,
+                ...(locale ? { locale } : {}),
+            };
+            void sendNzilaRun(payload, options);
+        });
+    };
+}
+export default createMochaNzilaReporter;

package/dist/react/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * React bindings: {@link useNzilaFeature} and {@link NzilaFeatureBoundary}.
+ * Call {@link initNzilaRuntime} once in your app entry (re-exported here).
+ *
+ * @packageDocumentation
+ */
+export { useNzilaFeature, type UseNzilaFeatureOptions } from "./use-nzila-feature.js";
+export { NzilaFeatureBoundary } from "./nzila-feature-boundary.js";
+export { initNzilaRuntime, reportFeatureError, captureFeatureError, } from "../runtime/client.js";
+export { extractErrorFields } from "../runtime/extract-error.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/react/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/react/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,eAAe,EAAE,KAAK,sBAAsB,EAAE,MAAM,wBAAwB,CAAC;AACtF,OAAO,EAAE,oBAAoB,EAAE,MAAM,6BAA6B,CAAC;AACnE,OAAO,EACL,gBAAgB,EAChB,kBAAkB,EAClB,mBAAmB,GACpB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAE,kBAAkB,EAAE,MAAM,6BAA6B,CAAC"}

package/dist/react/index.js

@@ -0,0 +1,10 @@
+/**
+ * React bindings: {@link useNzilaFeature} and {@link NzilaFeatureBoundary}.
+ * Call {@link initNzilaRuntime} once in your app entry (re-exported here).
+ *
+ * @packageDocumentation
+ */
+export { useNzilaFeature } from "./use-nzila-feature.js";
+export { NzilaFeatureBoundary } from "./nzila-feature-boundary.js";
+export { initNzilaRuntime, reportFeatureError, captureFeatureError, } from "../runtime/client.js";
+export { extractErrorFields } from "../runtime/extract-error.js";

package/dist/react/nzila-feature-boundary.d.ts

@@ -0,0 +1,26 @@
+import React from "react";
+import type { NzilaFeatureHandle } from "../runtime/types.js";
+type Props = {
+    feature: string;
+    nzila: NzilaFeatureHandle;
+    children: React.ReactNode;
+    fallback?: React.ReactNode;
+};
+/**
+ * Optional: wrap children to report React render errors for this feature.
+ * Pair with useNzilaFeature(feature) on the parent.
+ */
+export declare class NzilaFeatureBoundary extends React.Component<Props, {
+    error: Error | null;
+}> {
+    state: {
+        error: Error | null;
+    };
+    static getDerivedStateFromError(error: Error): {
+        error: Error;
+    };
+    componentDidCatch(error: Error, info: React.ErrorInfo): void;
+    render(): string | number | bigint | boolean | Iterable<React.ReactNode> | Promise<string | number | bigint | boolean | React.ReactPortal | React.ReactElement<unknown, string | React.JSXElementConstructor<any>> | Iterable<React.ReactNode> | null | undefined> | import("react/jsx-runtime").JSX.Element | null | undefined;
+}
+export {};
+//# sourceMappingURL=nzila-feature-boundary.d.ts.map

package/dist/react/nzila-feature-boundary.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"nzila-feature-boundary.d.ts","sourceRoot":"","sources":["../../src/react/nzila-feature-boundary.tsx"],"names":[],"mappings":"AAEA,OAAO,KAAK,MAAM,OAAO,CAAC;AAE1B,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAE9D,KAAK,KAAK,GAAG;IACX,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,kBAAkB,CAAC;IAC1B,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAC;IAC1B,QAAQ,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC;CAC5B,CAAC;AAEF;;;GAGG;AACH,qBAAa,oBAAqB,SAAQ,KAAK,CAAC,SAAS,CACvD,KAAK,EACL;IAAE,KAAK,EAAE,KAAK,GAAG,IAAI,CAAA;CAAE,CACxB;IACC,KAAK;eAAoB,KAAK,GAAG,IAAI;MAAG;IAExC,MAAM,CAAC,wBAAwB,CAAC,KAAK,EAAE,KAAK;;;IAI5C,iBAAiB,CAAC,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,KAAK,CAAC,SAAS;IASrD,MAAM;CAYP"}

package/dist/react/nzila-feature-boundary.js

@@ -0,0 +1,31 @@
+"use client";
+import { jsxs as _jsxs } from "react/jsx-runtime";
+import React from "react";
+import { nzilaSafe } from "../silent.js";
+/**
+ * Optional: wrap children to report React render errors for this feature.
+ * Pair with useNzilaFeature(feature) on the parent.
+ */
+export class NzilaFeatureBoundary extends React.Component {
+    constructor() {
+        super(...arguments);
+        this.state = { error: null };
+    }
+    static getDerivedStateFromError(error) {
+        return { error };
+    }
+    componentDidCatch(error, info) {
+        nzilaSafe(() => {
+            this.props?.nzila?.captureError(error, {
+                source: "react.error_boundary",
+                componentStack: info?.componentStack,
+            });
+        });
+    }
+    render() {
+        if (this.state.error) {
+            return (this.props.fallback ?? (_jsxs("div", { role: "alert", "data-nzila-feature": this.props.feature, children: ["Something went wrong in ", this.props.feature, "."] })));
+        }
+        return this.props.children;
+    }
+}

package/dist/react/use-nzila-feature.d.ts

@@ -0,0 +1,11 @@
+import type { NzilaFeatureHandle } from "../runtime/types.js";
+export type UseNzilaFeatureOptions = {
+    /** Report unhandled errors/rejections while this component is mounted (default true). */
+    captureUnhandled?: boolean;
+};
+/**
+ * Call once at the top of a React component that maps to a tested Nzila feature.
+ * Safe when {@link initNzilaRuntime} was not called — telemetry is skipped silently.
+ */
+export declare function useNzilaFeature(feature: string, options?: UseNzilaFeatureOptions): NzilaFeatureHandle;
+//# sourceMappingURL=use-nzila-feature.d.ts.map

package/dist/react/use-nzila-feature.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-nzila-feature.d.ts","sourceRoot":"","sources":["../../src/react/use-nzila-feature.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAE9D,MAAM,MAAM,sBAAsB,GAAG;IACnC,yFAAyF;IACzF,gBAAgB,CAAC,EAAE,OAAO,CAAC;CAC5B,CAAC;AAEF;;;GAGG;AACH,wBAAgB,eAAe,CAC7B,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE,sBAAsB,GAC/B,kBAAkB,CAoEpB"}

package/dist/react/use-nzila-feature.js

@@ -0,0 +1,63 @@
+"use client";
+import { useCallback, useEffect, useMemo, useRef } from "react";
+import { nzilaSafe } from "../silent.js";
+import { createFeatureHandle, getRenderLoopLimits, isNzilaRuntimeReady, } from "../runtime/client.js";
+/**
+ * Call once at the top of a React component that maps to a tested Nzila feature.
+ * Safe when {@link initNzilaRuntime} was not called — telemetry is skipped silently.
+ */
+export function useNzilaFeature(feature, options) {
+    const nzila = useMemo(() => createFeatureHandle(feature), [feature]);
+    const runtimeReady = isNzilaRuntimeReady();
+    const captureUnhandled = options?.captureUnhandled !== false;
+    const loopReportedRef = useRef(false);
+    const renderWindowRef = useRef({ count: 0, startedAt: 0 });
+    const { threshold, windowMs } = getRenderLoopLimits();
+    const now = typeof performance !== "undefined" ? performance.now() : Date.now();
+    if (runtimeReady) {
+        if (renderWindowRef.current.startedAt === 0) {
+            renderWindowRef.current = { count: 1, startedAt: now };
+        }
+        else if (now - renderWindowRef.current.startedAt > windowMs) {
+            renderWindowRef.current = { count: 1, startedAt: now };
+            loopReportedRef.current = false;
+        }
+        else {
+            renderWindowRef.current.count += 1;
+            if (!loopReportedRef.current &&
+                renderWindowRef.current.count >= threshold) {
+                loopReportedRef.current = true;
+                nzilaSafe(() => {
+                    nzila.reportUi("render_loop", {
+                        renderCount: renderWindowRef.current.count,
+                        windowMs,
+                    });
+                });
+            }
+        }
+    }
+    const onError = useCallback((event) => {
+        nzilaSafe(() => {
+            nzila.captureError(event?.error ?? event?.message, {
+                source: "window.error",
+            });
+        });
+    }, [nzila]);
+    const onRejection = useCallback((event) => {
+        nzilaSafe(() => {
+            nzila.captureError(event?.reason, { source: "unhandledrejection" });
+        });
+    }, [nzila]);
+    useEffect(() => {
+        if (!captureUnhandled || !runtimeReady || typeof window === "undefined") {
+            return;
+        }
+        window.addEventListener("error", onError);
+        window.addEventListener("unhandledrejection", onRejection);
+        return () => {
+            window.removeEventListener("error", onError);
+            window.removeEventListener("unhandledrejection", onRejection);
+        };
+    }, [captureUnhandled, runtimeReady, onError, onRejection]);
+    return nzila;
+}

package/dist/runtime/client.d.ts

@@ -0,0 +1,36 @@
+import type { NzilaFeatureHandle, NzilaRuntimeConfig, NzilaRuntimeSignal } from "./types.js";
+/**
+ * Configure runtime signal delivery. Call once before
+ * {@link traceNzilaFeature} or {@link useNzilaFeature}.
+ */
+export declare function initNzilaRuntime(config: NzilaRuntimeConfig): void;
+/** True when {@link initNzilaRuntime} was called with a usable URL and key. */
+export declare function isNzilaRuntimeReady(): boolean;
+/** @internal — no throw; returns null if not configured. */
+export declare function getNzilaRuntime(): NzilaRuntimeConfig | null;
+/**
+ * Queue a signal (batched flush to `/api/signals/runtime`).
+ * No-op when runtime is not configured.
+ */
+export declare function enqueueSignal(signal: NzilaRuntimeSignal): void;
+/**
+ * Create a handle bound to a feature name (low-level).
+ * Usually use {@link traceNzilaFeature} or the React hook instead.
+ */
+export declare function createFeatureHandle(feature: string): NzilaFeatureHandle;
+/**
+ * Report a caught error when you have the feature name but no handle in scope.
+ */
+export declare function reportFeatureError(feature: string, error: unknown, detail?: Record<string, unknown>): void;
+/** Alias of {@link reportFeatureError}. */
+export declare const captureFeatureError: typeof reportFeatureError;
+/**
+ * Start tracing for a backend route or service method.
+ */
+export declare function traceNzilaFeature(feature: string): NzilaFeatureHandle;
+/** Limits used by {@link useNzilaFeature} for render-loop detection. */
+export declare function getRenderLoopLimits(): {
+    threshold: number;
+    windowMs: number;
+};
+//# sourceMappingURL=client.d.ts.map

package/dist/runtime/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/runtime/client.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACV,kBAAkB,EAClB,kBAAkB,EAClB,kBAAkB,EACnB,MAAM,YAAY,CAAC;AAOpB;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,kBAAkB,GAAG,IAAI,CAQjE;AAED,+EAA+E;AAC/E,wBAAgB,mBAAmB,IAAI,OAAO,CAI7C;AAED,4DAA4D;AAC5D,wBAAgB,eAAe,IAAI,kBAAkB,GAAG,IAAI,CAG3D;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,kBAAkB,GAAG,IAAI,CAS9D;AA0CD;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,MAAM,GAAG,kBAAkB,CA4CvE;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,OAAO,EACd,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC/B,IAAI,CAEN;AAED,2CAA2C;AAC3C,eAAO,MAAM,mBAAmB,2BAAqB,CAAC;AAEtD;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,GAAG,kBAAkB,CAErE;AAED,wEAAwE;AACxE,wBAAgB,mBAAmB,IAAI;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAM7E"}

package/dist/runtime/client.js

@@ -0,0 +1,145 @@
+import { extractErrorFields } from "./extract-error.js";
+import { nzilaSafe, nzilaSafeAsync } from "../silent.js";
+let globalConfig = null;
+const queue = [];
+let flushTimer = null;
+/**
+ * Configure runtime signal delivery. Call once before
+ * {@link traceNzilaFeature} or {@link useNzilaFeature}.
+ */
+export function initNzilaRuntime(config) {
+    nzilaSafe(() => {
+        globalConfig = {
+            renderLoopThreshold: 40,
+            renderLoopWindowMs: 1000,
+            ...config,
+        };
+    });
+}
+/** True when {@link initNzilaRuntime} was called with a usable URL and key. */
+export function isNzilaRuntimeReady() {
+    const url = globalConfig?.signalsUrl?.trim();
+    const key = globalConfig?.apiKey?.trim();
+    return Boolean(url && key);
+}
+/** @internal — no throw; returns null if not configured. */
+export function getNzilaRuntime() {
+    if (!isNzilaRuntimeReady())
+        return null;
+    return globalConfig;
+}
+/**
+ * Queue a signal (batched flush to `/api/signals/runtime`).
+ * No-op when runtime is not configured.
+ */
+export function enqueueSignal(signal) {
+    nzilaSafe(() => {
+        if (!isNzilaRuntimeReady())
+            return;
+        queue.push({
+            ...signal,
+            occurredAt: signal.occurredAt ?? new Date().toISOString(),
+        });
+        scheduleFlush();
+    });
+}
+function scheduleFlush() {
+    if (flushTimer)
+        return;
+    flushTimer = setTimeout(() => {
+        flushTimer = null;
+        void nzilaSafeAsync(flushSignals);
+    }, 400);
+}
+async function flushSignals() {
+    const config = globalConfig;
+    if (!config?.signalsUrl?.trim() || !config?.apiKey?.trim() || queue.length === 0) {
+        return;
+    }
+    const batch = queue.splice(0, 200);
+    const maxRetries = config.maxRetries ?? 2;
+    let attempt = 0;
+    while (attempt < maxRetries) {
+        attempt += 1;
+        try {
+            const res = await fetch(config.signalsUrl, {
+                method: "POST",
+                headers: {
+                    Authorization: `Bearer ${config.apiKey}`,
+                    "Content-Type": "application/json",
+                },
+                body: JSON.stringify({
+                    locale: config.locale,
+                    signals: batch,
+                }),
+            });
+            if (res.ok)
+                return;
+        }
+        catch {
+            /* retry */
+        }
+        await new Promise((r) => setTimeout(r, attempt * 500));
+    }
+}
+/**
+ * Create a handle bound to a feature name (low-level).
+ * Usually use {@link traceNzilaFeature} or the React hook instead.
+ */
+export function createFeatureHandle(feature) {
+    const report = (type, success, payload) => {
+        enqueueSignal({ feature, type, success, payload });
+    };
+    const captureError = (error, detail) => {
+        nzilaSafe(() => {
+            report("error", false, { ...extractErrorFields(error), ...detail });
+        });
+    };
+    const captureApiError = (error, label, detail) => {
+        nzilaSafe(() => {
+            report("api", false, { label, ...extractErrorFields(error), ...detail });
+        });
+    };
+    return {
+        feature,
+        async runApi(label, fn) {
+            try {
+                const result = await fn();
+                nzilaSafe(() => report("api", true, { label }));
+                return result;
+            }
+            catch (error) {
+                captureApiError(error, label);
+                throw error;
+            }
+        },
+        captureError,
+        reportError: captureError,
+        captureApiError,
+        reportUi(kind, detail, success = false) {
+            nzilaSafe(() => report("ui", success, { kind, ...detail }));
+        },
+    };
+}
+/**
+ * Report a caught error when you have the feature name but no handle in scope.
+ */
+export function reportFeatureError(feature, error, detail) {
+    nzilaSafe(() => createFeatureHandle(feature).captureError(error, detail));
+}
+/** Alias of {@link reportFeatureError}. */
+export const captureFeatureError = reportFeatureError;
+/**
+ * Start tracing for a backend route or service method.
+ */
+export function traceNzilaFeature(feature) {
+    return createFeatureHandle(feature);
+}
+/** Limits used by {@link useNzilaFeature} for render-loop detection. */
+export function getRenderLoopLimits() {
+    const c = globalConfig;
+    return {
+        threshold: c?.renderLoopThreshold ?? 40,
+        windowMs: c?.renderLoopWindowMs ?? 1000,
+    };
+}

package/dist/runtime/extract-error.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Normalize unknown thrown values for Nzila runtime signals.
+ *
+ * @param error - `Error`, string, or any thrown value.
+ * @returns `message`, `name`, and optional `stack` for signal payloads.
+ */
+export declare function extractErrorFields(error: unknown): {
+    message: string;
+    name: string;
+    stack?: string;
+};
+//# sourceMappingURL=extract-error.d.ts.map

package/dist/runtime/extract-error.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"extract-error.d.ts","sourceRoot":"","sources":["../../src/runtime/extract-error.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,GAAG;IAClD,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,CAgBA"}

package/dist/runtime/extract-error.js

@@ -0,0 +1,24 @@
+/**
+ * Normalize unknown thrown values for Nzila runtime signals.
+ *
+ * @param error - `Error`, string, or any thrown value.
+ * @returns `message`, `name`, and optional `stack` for signal payloads.
+ */
+export function extractErrorFields(error) {
+    if (error instanceof Error) {
+        return {
+            message: error?.message ?? "Unknown error",
+            name: error?.name ?? "Error",
+            stack: error?.stack,
+        };
+    }
+    if (typeof error === "string") {
+        return { message: error, name: "Error" };
+    }
+    try {
+        return { message: JSON.stringify(error), name: "Error" };
+    }
+    catch {
+        return { message: String(error), name: "Error" };
+    }
+}

package/dist/runtime/index.d.ts

@@ -0,0 +1,4 @@
+export type { NzilaFeatureHandle, NzilaRuntimeConfig, NzilaRuntimeSignal, NzilaSignalType, } from "./types.js";
+export { extractErrorFields } from "./extract-error.js";
+export { captureFeatureError, createFeatureHandle, enqueueSignal, getNzilaRuntime, getRenderLoopLimits, initNzilaRuntime, isNzilaRuntimeReady, reportFeatureError, traceNzilaFeature, } from "./client.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/runtime/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/runtime/index.ts"],"names":[],"mappings":"AAAA,YAAY,EACV,kBAAkB,EAClB,kBAAkB,EAClB,kBAAkB,EAClB,eAAe,GAChB,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AACxD,OAAO,EACL,mBAAmB,EACnB,mBAAmB,EACnB,aAAa,EACb,eAAe,EACf,mBAAmB,EACnB,gBAAgB,EAChB,mBAAmB,EACnB,kBAAkB,EAClB,iBAAiB,GAClB,MAAM,aAAa,CAAC"}

package/dist/runtime/index.js

@@ -0,0 +1,2 @@
+export { extractErrorFields } from "./extract-error.js";
+export { captureFeatureError, createFeatureHandle, enqueueSignal, getNzilaRuntime, getRenderLoopLimits, initNzilaRuntime, isNzilaRuntimeReady, reportFeatureError, traceNzilaFeature, } from "./client.js";

package/dist/runtime/types.d.ts

@@ -0,0 +1,46 @@
+import type { NzilaLocale } from "../types.js";
+/** Runtime signal category accepted by `POST /api/signals/runtime`. */
+export type NzilaSignalType = "navigation" | "api" | "ui" | "error" | "custom";
+/** One runtime observation for a product feature. */
+export type NzilaRuntimeSignal = {
+    /** Must match Vitest `mapFeature` / `describe` feature name. */
+    feature: string;
+    type: NzilaSignalType;
+    success: boolean;
+    occurredAt?: string;
+    payload?: Record<string, unknown>;
+};
+/** Global config for {@link initNzilaRuntime}. */
+export type NzilaRuntimeConfig = {
+    /** e.g. `https://host/api/signals/runtime` */
+    signalsUrl: string;
+    apiKey: string;
+    locale?: NzilaLocale;
+    /** Renders in this window before a `ui` render_loop signal (default 40). */
+    renderLoopThreshold?: number;
+    renderLoopWindowMs?: number;
+    maxRetries?: number;
+};
+/**
+ * Scoped reporter for one feature. Returned by
+ * {@link traceNzilaFeature} and {@link useNzilaFeature}.
+ */
+export type NzilaFeatureHandle = {
+    feature: string;
+    /**
+     * Run an async call; records `api` success or failure.
+     * Re-throws the error after reporting.
+     */
+    runApi: <T>(label: string, fn: () => Promise<T>) => Promise<T>;
+    /**
+     * Report a caught error (`type: error`). Use in `catch` blocks and error UI.
+     * Alias: {@link NzilaFeatureHandle.reportError}.
+     */
+    captureError: (error: unknown, detail?: Record<string, unknown>) => void;
+    reportError: (error: unknown, detail?: Record<string, unknown>) => void;
+    /** Report a caught HTTP/upstream failure without using `runApi`. */
+    captureApiError: (error: unknown, label: string, detail?: Record<string, unknown>) => void;
+    /** Custom UI issues, e.g. `reportUi("render_loop", { renderCount: 50 })`. */
+    reportUi: (kind: string, detail?: Record<string, unknown>, success?: boolean) => void;
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/runtime/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/runtime/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE/C,uEAAuE;AACvE,MAAM,MAAM,eAAe,GAAG,YAAY,GAAG,KAAK,GAAG,IAAI,GAAG,OAAO,GAAG,QAAQ,CAAC;AAE/E,qDAAqD;AACrD,MAAM,MAAM,kBAAkB,GAAG;IAC/B,gEAAgE;IAChE,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,eAAe,CAAC;IACtB,OAAO,EAAE,OAAO,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACnC,CAAC;AAEF,kDAAkD;AAClD,MAAM,MAAM,kBAAkB,GAAG;IAC/B,8CAA8C;IAC9C,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,4EAA4E;IAC5E,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB,CAAC;AAEF;;;GAGG;AACH,MAAM,MAAM,kBAAkB,GAAG;IAC/B,OAAO,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,MAAM,EAAE,CAAC,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,CAAC;IAC/D;;;OAGG;IACH,YAAY,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,CAAC;IACzE,WAAW,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,CAAC;IACxE,oEAAoE;IACpE,eAAe,EAAE,CACf,KAAK,EAAE,OAAO,EACd,KAAK,EAAE,MAAM,EACb,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAC7B,IAAI,CAAC;IACV,6EAA6E;IAC7E,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,CAAC,EAAE,OAAO,KAAK,IAAI,CAAC;CACvF,CAAC"}

package/dist/runtime/types.js

@@ -0,0 +1 @@
+export {};

package/dist/silent.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Nzila never logs or throws to the host app for telemetry failures.
+ * @internal
+ */
+/** Run sync telemetry code; swallow all errors. */
+export declare function nzilaSafe<T>(fn: () => T): T | undefined;
+/** Run async telemetry code; swallow all errors. */
+export declare function nzilaSafeAsync(fn: () => Promise<void>): Promise<void>;
+//# sourceMappingURL=silent.d.ts.map

package/dist/silent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"silent.d.ts","sourceRoot":"","sources":["../src/silent.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,mDAAmD;AACnD,wBAAgB,SAAS,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC,GAAG,SAAS,CAMvD;AAED,oDAAoD;AACpD,wBAAsB,cAAc,CAAC,EAAE,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAM3E"}

package/dist/silent.js

@@ -0,0 +1,22 @@
+/**
+ * Nzila never logs or throws to the host app for telemetry failures.
+ * @internal
+ */
+/** Run sync telemetry code; swallow all errors. */
+export function nzilaSafe(fn) {
+    try {
+        return fn();
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Run async telemetry code; swallow all errors. */
+export async function nzilaSafeAsync(fn) {
+    try {
+        await fn();
+    }
+    catch {
+        /* silent */
+    }
+}

package/dist/types.d.ts

@@ -0,0 +1,53 @@
+/** Supported test runner identifiers in webhook payloads. */
+export declare const NZILA_TEST_FRAMEWORKS: readonly ["vitest", "jest", "mocha", "playwright", "jasmine", "cypress", "karma", "node-test", "other"];
+export type NzilaTestFramework = (typeof NZILA_TEST_FRAMEWORKS)[number];
+export type NzilaTestStatus = "passed" | "failed" | "skipped" | "pending";
+/** Locales for AI summaries and failure copy on the dashboard. */
+export type NzilaLocale = "en" | "pt" | "fr" | "zh";
+/** One test case inside a completed run webhook. */
+export type NzilaTestCase = {
+    appName: string;
+    framework: NzilaTestFramework;
+    startedAt: string;
+    finishedAt: string;
+    describePath: string[];
+    /** Overrides feature; default is first `describePath` segment or `mapFeature`. */
+    feature?: string;
+    context?: Record<string, unknown>;
+    testName: string;
+    status: NzilaTestStatus;
+    duration: number;
+    errors: {
+        message: string;
+        stack?: string;
+    }[];
+};
+/** Body sent to `POST /api/webhooks/tests` (one per finished run). */
+export type NzilaRunPayload = {
+    /** Idempotent external id (CI build id, UUID, etc.). */
+    runId: string;
+    /** Must match the project App name in the Nzila dashboard. */
+    appName: string;
+    framework: NzilaTestFramework;
+    startedAt: string;
+    finishedAt: string;
+    tests: NzilaTestCase[];
+    locale?: NzilaLocale;
+};
+/** Options for Vitest/Jest/Mocha reporters and {@link sendNzilaRun}. */
+export type NzilaClientOptions = {
+    webhookUrl: string;
+    apiKey: string;
+    appName: string;
+    framework?: NzilaTestFramework;
+    /** Defaults to a random UUID per reporter instance. */
+    runId?: string;
+    maxRetries?: number;
+    locale?: NzilaLocale;
+    /**
+     * Map describe suite titles to dashboard feature names.
+     * Default: `describePath[0] ?? "general"`.
+     */
+    mapFeature?: (describePath: string[], testName: string) => string;
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,6DAA6D;AAC7D,eAAO,MAAM,qBAAqB,yGAUxB,CAAC;AAEX,MAAM,MAAM,kBAAkB,GAAG,CAAC,OAAO,qBAAqB,CAAC,CAAC,MAAM,CAAC,CAAC;AAExE,MAAM,MAAM,eAAe,GAAG,QAAQ,GAAG,QAAQ,GAAG,SAAS,GAAG,SAAS,CAAC;AAE1E,kEAAkE;AAClE,MAAM,MAAM,WAAW,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,CAAC;AAEpD,oDAAoD;AACpD,MAAM,MAAM,aAAa,GAAG;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,kBAAkB,CAAC;IAC9B,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,kFAAkF;IAClF,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,eAAe,CAAC;IACxB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;CAC/C,CAAC;AAEF,sEAAsE;AACtE,MAAM,MAAM,eAAe,GAAG;IAC5B,wDAAwD;IACxD,KAAK,EAAE,MAAM,CAAC;IACd,8DAA8D;IAC9D,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,kBAAkB,CAAC;IAC9B,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,aAAa,EAAE,CAAC;IACvB,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB,CAAC;AAEF,wEAAwE;AACxE,MAAM,MAAM,kBAAkB,GAAG;IAC/B,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,kBAAkB,CAAC;IAC/B,uDAAuD;IACvD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB;;;OAGG;IACH,UAAU,CAAC,EAAE,CAAC,YAAY,EAAE,MAAM,EAAE,EAAE,QAAQ,EAAE,MAAM,KAAK,MAAM,CAAC;CACnE,CAAC"}

package/dist/types.js

@@ -0,0 +1,12 @@
+/** Supported test runner identifiers in webhook payloads. */
+export const NZILA_TEST_FRAMEWORKS = [
+    "vitest",
+    "jest",
+    "mocha",
+    "playwright",
+    "jasmine",
+    "cypress",
+    "karma",
+    "node-test",
+    "other",
+];

package/dist/vitest-reporter.d.ts

@@ -0,0 +1,37 @@
+import type { File } from "@vitest/runner";
+import type { NzilaClientOptions } from "./types.js";
+interface VitestReporter {
+    onFinished?: (files?: File[], errors?: unknown[]) => void;
+}
+/**
+ * Vitest reporter that POSTs one webhook per finished run via {@link sendNzilaRun}.
+ *
+ * @example
+ * ```ts
+ * reporters: [
+ *   "default",
+ *   new NzilaVitestReporter({
+ *     webhookUrl: process.env.NZILA_WEBHOOK_URL!,
+ *     apiKey: process.env.NZILA_API_KEY!,
+ *     appName: "checkout-api",
+ *     mapFeature: (path) => path[0] ?? "general",
+ *   }),
+ * ],
+ * ```
+ */
+export default class NzilaVitestReporter implements VitestReporter {
+    private readonly options;
+    private startedAt;
+    private sent;
+    private readonly runId;
+    private tests;
+    /**
+     * @param options - Webhook URL, API key, and project `appName` (required).
+     */
+    constructor(options: NzilaClientOptions);
+    onFinished(files?: File[], _errors?: unknown[]): void;
+    private walkTasks;
+    private mapStatus;
+}
+export {};
+//# sourceMappingURL=vitest-reporter.d.ts.map

package/dist/vitest-reporter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vitest-reporter.d.ts","sourceRoot":"","sources":["../src/vitest-reporter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAQ,MAAM,gBAAgB,CAAC;AAGjD,OAAO,KAAK,EAAE,kBAAkB,EAAmD,MAAM,YAAY,CAAC;AAEtG,UAAU,cAAc;IACtB,UAAU,CAAC,EAAE,CAAC,KAAK,CAAC,EAAE,IAAI,EAAE,EAAE,MAAM,CAAC,EAAE,OAAO,EAAE,KAAK,IAAI,CAAC;CAC3D;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,CAAC,OAAO,OAAO,mBAAoB,YAAW,cAAc;IAChE,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAqB;IAC7C,OAAO,CAAC,SAAS,CAAc;IAC/B,OAAO,CAAC,IAAI,CAAS;IACrB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;IAC/B,OAAO,CAAC,KAAK,CAAuB;IAEpC;;OAEG;gBACS,OAAO,EAAE,kBAAkB;IAKvC,UAAU,CAAC,KAAK,CAAC,EAAE,IAAI,EAAE,EAAE,OAAO,CAAC,EAAE,OAAO,EAAE;IA2B9C,OAAO,CAAC,SAAS;IAuCjB,OAAO,CAAC,SAAS;CAMlB"}

package/dist/vitest-reporter.js

@@ -0,0 +1,95 @@
+import { randomUUID } from "node:crypto";
+import { sendNzilaRun, resolveLocale } from "./deliver.js";
+/**
+ * Vitest reporter that POSTs one webhook per finished run via {@link sendNzilaRun}.
+ *
+ * @example
+ * ```ts
+ * reporters: [
+ *   "default",
+ *   new NzilaVitestReporter({
+ *     webhookUrl: process.env.NZILA_WEBHOOK_URL!,
+ *     apiKey: process.env.NZILA_API_KEY!,
+ *     appName: "checkout-api",
+ *     mapFeature: (path) => path[0] ?? "general",
+ *   }),
+ * ],
+ * ```
+ */
+export default class NzilaVitestReporter {
+    /**
+     * @param options - Webhook URL, API key, and project `appName` (required).
+     */
+    constructor(options) {
+        this.startedAt = new Date();
+        this.sent = false;
+        this.tests = [];
+        this.options = options;
+        this.runId = options.runId ?? randomUUID();
+    }
+    onFinished(files, _errors) {
+        if (this.sent)
+            return;
+        this.sent = true;
+        const finishedAt = new Date();
+        for (const file of files ?? []) {
+            this.walkTasks(file.tasks, file.name.split("/").slice(0, -1));
+        }
+        if (!this.tests.length)
+            return;
+        const framework = this.options.framework ?? "vitest";
+        const locale = resolveLocale(this.options.locale);
+        const payload = {
+            runId: this.runId,
+            appName: this.options.appName,
+            framework,
+            startedAt: this.startedAt.toISOString(),
+            finishedAt: finishedAt.toISOString(),
+            tests: this.tests,
+            ...(locale ? { locale } : {}),
+        };
+        void sendNzilaRun(payload, this.options);
+    }
+    walkTasks(tasks, describePath) {
+        const framework = this.options.framework ?? "vitest";
+        const now = new Date().toISOString();
+        for (const task of tasks) {
+            if (task.type === "suite") {
+                this.walkTasks(task.tasks, [...describePath, task.name]);
+                continue;
+            }
+            if (task.type !== "test")
+                continue;
+            const result = task?.result;
+            const errors = result?.errors?.map((e) => ({
+                message: e?.message ?? String(e),
+                stack: e?.stack,
+            })) ?? [];
+            const feature = this.options.mapFeature?.(describePath, task.name) ??
+                describePath[0] ??
+                "general";
+            this.tests.push({
+                appName: this.options.appName,
+                framework,
+                startedAt: this.startedAt.toISOString(),
+                finishedAt: now,
+                describePath,
+                feature,
+                context: { layer: this.options.appName },
+                testName: task.name,
+                status: this.mapStatus(result?.state),
+                duration: result?.duration ?? 0,
+                errors,
+            });
+        }
+    }
+    mapStatus(state) {
+        if (state === "pass")
+            return "passed";
+        if (state === "fail")
+            return "failed";
+        if (state === "skip")
+            return "skipped";
+        return "pending";
+    }
+}

package/package.json

@@ -0,0 +1,69 @@
+{
+  "name": "@nzila/sdk",
+  "version": "0.1.0",
+  "description": "Send test runs to Nzila and trace live feature errors (Vitest, Jest, Mocha, React, Node).",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/joel2011140/nzila.git",
+    "directory": "packages/nzila-sdk"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./vitest": {
+      "types": "./dist/vitest-reporter.d.ts",
+      "import": "./dist/vitest-reporter.js"
+    },
+    "./jest": {
+      "types": "./dist/jest-reporter.d.ts",
+      "import": "./dist/jest-reporter.js"
+    },
+    "./mocha": {
+      "types": "./dist/mocha-reporter.d.ts",
+      "import": "./dist/mocha-reporter.js"
+    },
+    "./runtime": {
+      "types": "./dist/runtime/index.d.ts",
+      "import": "./dist/runtime/index.js"
+    },
+    "./react": {
+      "types": "./dist/react/index.d.ts",
+      "import": "./dist/react/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "prepublishOnly": "npm run build"
+  },
+  "peerDependencies": {
+    "react": ">=18.0.0",
+    "vitest": ">=1.0.0"
+  },
+  "peerDependenciesMeta": {
+    "vitest": {
+      "optional": true
+    },
+    "react": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/react": "^19.2.14",
+    "react": "^19.2.6",
+    "typescript": "^5",
+    "vitest": "^3.2.4"
+  }
+}