@nzila/sdk 0.1.1 → 0.1.4

package/README.md

@@ -11,6 +11,35 @@ npm install @nzila/sdk
 # Vitest projects also need vitest as a peer
 ```
 
+### TypeScript
+
+Subpaths such as `@nzila/sdk/vitest` need **`moduleResolution`** set to **`bundler`**, **`node16`**, or **`nodenext`** (recommended for Vitest/Vite repos). If you still use legacy `"node"` resolution, upgrade to one of those options in `tsconfig.json`:
+
+```json
+{
+  "compilerOptions": {
+    "moduleResolution": "bundler"
+  }
+}
+```
+
+`@nzila/sdk@0.1.4+` also ships root `.d.ts` shims and `typesVersions` for broader editor support.
+
+## CLI (onboarding)
+
+`npx @nzila/sdk` opens the [Nzila dashboard](https://nzila-kappa.vercel.app) and prints setup commands. No separate CLI package.
+
+```bash
+npx @nzila/sdk              # open app + help
+npx @nzila/sdk login
+npx @nzila/sdk link --api-key <key> --project-id <uuid>
+npx @nzila/sdk doctor
+```
+
+Also available as `npx nzila` after install. Override platform with `NZILA_APP_URL` or `--endpoint`.
+
+After you sign in on [nzila-kappa.vercel.app](https://nzila-kappa.vercel.app), the dashboard runs a **first-visit tour** per section (localized). Use **Guide** in the header to replay.
+
 ## Exports
 
 | Path | Purpose |

package/dist/cli/constants.d.ts

@@ -0,0 +1,13 @@
+/** Hosted Nzila dashboard — override with NZILA_APP_URL or --endpoint */
+export declare const NZILA_PLATFORM_URL = "https://nzila-kappa.vercel.app";
+export declare function resolvePlatformUrl(): string;
+export declare function platformPaths(base: string): {
+    home: string;
+    login: string;
+    register: string;
+    docs: string;
+    keys: string;
+    webhook: string;
+    signals: string;
+};
+//# sourceMappingURL=constants.d.ts.map

package/dist/cli/constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../../src/cli/constants.ts"],"names":[],"mappings":"AAAA,yEAAyE;AACzE,eAAO,MAAM,kBAAkB,mCAAmC,CAAC;AAEnE,wBAAgB,kBAAkB,IAAI,MAAM,CAM3C;AAED,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM;;;;;;;;EAWzC"}

package/dist/cli/constants.js

@@ -0,0 +1,20 @@
+/** Hosted Nzila dashboard — override with NZILA_APP_URL or --endpoint */
+export const NZILA_PLATFORM_URL = "https://nzila-kappa.vercel.app";
+export function resolvePlatformUrl() {
+    const raw = process.env.NZILA_APP_URL?.trim() ||
+        process.env.NZILA_ENDPOINT?.trim() ||
+        NZILA_PLATFORM_URL;
+    return raw.replace(/\/$/, "");
+}
+export function platformPaths(base) {
+    const root = base.replace(/\/$/, "");
+    return {
+        home: `${root}/en`,
+        login: `${root}/en/login`,
+        register: `${root}/en/register`,
+        docs: `${root}/en/docs`,
+        keys: `${root}/en/keys`,
+        webhook: `${root}/api/webhooks/tests`,
+        signals: `${root}/api/signals/runtime`,
+    };
+}

package/dist/cli/main.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=main.d.ts.map

package/dist/cli/main.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../../src/cli/main.ts"],"names":[],"mappings":""}

package/dist/cli/main.js

@@ -0,0 +1,223 @@
+#!/usr/bin/env node
+import { readFile, writeFile } from "node:fs/promises";
+import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
+import { platformPaths, resolvePlatformUrl } from "./constants.js";
+import { openBrowser } from "./open-browser.js";
+const PKG = "@nzila/sdk";
+const CONFIG_FILE = "nzila.config.ts";
+function defaultEndpoint() {
+    return resolvePlatformUrl();
+}
+async function loadConfig(cwd) {
+    const file = path.join(cwd, CONFIG_FILE);
+    if (!existsSync(file))
+        return null;
+    const source = await readFile(file, "utf8");
+    const match = source.match(/apiKey:\s*["']([^"']+)["']/);
+    const projectMatch = source.match(/projectId:\s*["']([^"']+)["']/);
+    const endpointMatch = source.match(/endpoint:\s*["']([^"']+)["']/);
+    const frameworkMatch = source.match(/framework:\s*["']([^"']+)["']/);
+    if (!match?.[1] || !projectMatch?.[1])
+        return null;
+    return {
+        apiKey: match[1],
+        projectId: projectMatch[1],
+        endpoint: endpointMatch?.[1] ?? defaultEndpoint(),
+        framework: frameworkMatch?.[1] ?? "vitest",
+    };
+}
+async function writeConfig(cwd, config) {
+    const body = `/** Generated by ${PKG} — do not commit secrets to public repos */
+export default {
+  apiKey: "${config.apiKey}",
+  projectId: "${config.projectId}",
+  endpoint: "${config.endpoint.replace(/"/g, '\\"')}",
+  framework: "${config.framework}",
+} as const;
+`;
+    await writeFile(path.join(cwd, CONFIG_FILE), body, "utf8");
+}
+function detectFramework(cwd) {
+    const pkgPath = path.join(cwd, "package.json");
+    if (existsSync(pkgPath)) {
+        try {
+            const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
+            const deps = { ...pkg.dependencies, ...pkg.devDependencies };
+            if (deps["@playwright/test"] || deps.playwright)
+                return "playwright";
+            if (deps.jest)
+                return "jest";
+            if (deps.vitest)
+                return "vitest";
+        }
+        catch {
+            /* fall through */
+        }
+    }
+    if (existsSync(path.join(cwd, "vitest.config.ts")) || existsSync(path.join(cwd, "vitest.config.mts"))) {
+        return "vitest";
+    }
+    if (existsSync(path.join(cwd, "jest.config.js")) || existsSync(path.join(cwd, "jest.config.ts"))) {
+        return "jest";
+    }
+    if (existsSync(path.join(cwd, "playwright.config.ts")))
+        return "playwright";
+    return "vitest";
+}
+function printEnvSnippet(endpoint) {
+    const paths = platformPaths(endpoint);
+    console.log("");
+    console.log("Add to your project .env.local:");
+    console.log(`NZILA_WEBHOOK_URL=${paths.webhook}`);
+    console.log(`NZILA_SIGNALS_URL=${paths.signals}`);
+    console.log("NZILA_API_KEY=<from dashboard → API Keys>");
+    console.log("");
+    console.log(`SDK already installed via ${PKG}; add Vitest reporter from docs.`);
+    console.log(`Docs: ${paths.docs}`);
+}
+async function tryOpen(url, quiet = false) {
+    try {
+        await openBrowser(url);
+        if (!quiet)
+            console.log(`Opened ${url}`);
+    }
+    catch {
+        if (!quiet)
+            console.log(`Open in your browser: ${url}`);
+    }
+}
+async function cmdOpen(flags) {
+    const base = String(flags.endpoint ?? defaultEndpoint()).replace(/\/$/, "");
+    const paths = platformPaths(base);
+    const target = flags.register ? paths.register : flags.login ? paths.login : paths.home;
+    await tryOpen(target);
+}
+async function cmdInit(flags) {
+    const cwd = process.cwd();
+    const framework = detectFramework(cwd);
+    const base = defaultEndpoint();
+    const paths = platformPaths(base);
+    console.log(`Nzila — platform: ${base}`);
+    console.log(`Detected test framework: ${framework}`);
+    console.log("");
+    console.log("Quick start:");
+    console.log(`  1. npx ${PKG} login     → sign in (opens browser)`);
+    console.log("  2. Create a project + API key in the dashboard");
+    console.log(`  3. npx ${PKG} link --api-key nzl_… --project-id <uuid>`);
+    console.log("  4. Wire @nzila/sdk/vitest and run tests");
+    printEnvSnippet(base);
+    if (flags.open !== false) {
+        await tryOpen(paths.register, true);
+    }
+}
+async function cmdLogin(flags) {
+    const base = String(flags.endpoint ?? defaultEndpoint()).replace(/\/$/, "");
+    const loginUrl = `${platformPaths(base).login}?cli=1`;
+    console.log(`Nzila platform: ${base}`);
+    console.log("Sign in, then create an API key:");
+    console.log(`  ${platformPaths(base).keys}`);
+    console.log("");
+    console.log("Then link this repo:");
+    console.log(`  npx ${PKG} link --api-key <key> --project-id <uuid>`);
+    await tryOpen(loginUrl);
+}
+async function cmdLink(flags) {
+    const apiKey = String(flags["api-key"] ?? flags.apiKey ?? "");
+    const projectId = String(flags["project-id"] ?? flags.projectId ?? "");
+    const endpoint = String(flags.endpoint ?? defaultEndpoint()).replace(/\/$/, "");
+    if (!apiKey || !projectId) {
+        console.error(`Usage: npx ${PKG} link --api-key <token> --project-id <uuid> [--endpoint <url>]`);
+        process.exit(1);
+    }
+    const cwd = process.cwd();
+    const framework = detectFramework(cwd);
+    await writeConfig(cwd, { apiKey, projectId, endpoint, framework });
+    console.log(`Wrote ${CONFIG_FILE} (endpoint: ${endpoint})`);
+    printEnvSnippet(endpoint);
+}
+async function cmdDoctor() {
+    const cwd = process.cwd();
+    const config = await loadConfig(cwd);
+    if (!config) {
+        console.log(`No nzila.config.ts — run \`npx ${PKG} link\` first.`);
+        process.exit(1);
+    }
+    const paths = platformPaths(config.endpoint);
+    console.log("Config OK:", {
+        projectId: config.projectId,
+        endpoint: config.endpoint,
+        framework: config.framework,
+    });
+    console.log("Webhook URL:", paths.webhook);
+}
+function printHelp(base) {
+    const paths = platformPaths(base);
+    console.log(`Nzila (${PKG}) — ${base}
+
+Commands:
+  open       Open the dashboard in your browser (default)
+  init       Detect framework + show setup steps
+  login      Open sign-in and linking instructions
+  link       Write nzila.config.ts (--api-key, --project-id)
+  doctor     Validate nzila.config.ts
+
+Examples:
+  npx ${PKG}
+  npx ${PKG} login
+  npx ${PKG} link --api-key nzl_… --project-id <uuid>
+
+Docs: ${paths.docs}
+`);
+}
+function parseArgs(argv) {
+    const [command, ...rest] = argv;
+    const flags = {};
+    for (let i = 0; i < rest.length; i++) {
+        const token = rest[i];
+        if (token.startsWith("--")) {
+            const key = token.slice(2);
+            const next = rest[i + 1];
+            if (next && !next.startsWith("--")) {
+                flags[key] = next;
+                i++;
+            }
+            else {
+                flags[key] = true;
+            }
+        }
+    }
+    return { command: command ?? "", flags };
+}
+async function main() {
+    const { command, flags } = parseArgs(process.argv.slice(2));
+    const base = defaultEndpoint();
+    if (!command || command === "open" || command === "start") {
+        if (!command)
+            await tryOpen(platformPaths(base).home);
+        else
+            await cmdOpen(flags);
+        if (!command)
+            printHelp(base);
+        return;
+    }
+    if (command === "init")
+        return cmdInit(flags);
+    if (command === "login")
+        return cmdLogin(flags);
+    if (command === "link")
+        return cmdLink(flags);
+    if (command === "doctor")
+        return cmdDoctor();
+    if (command === "help" || command === "-h" || command === "--help") {
+        printHelp(base);
+        return;
+    }
+    console.error(`Unknown command: ${command}`);
+    printHelp(base);
+    process.exit(1);
+}
+main().catch((err) => {
+    console.error(err instanceof Error ? err.message : err);
+    process.exit(1);
+});

package/dist/cli/open-browser.d.ts

@@ -0,0 +1,2 @@
+export declare function openBrowser(url: string): Promise<void>;
+//# sourceMappingURL=open-browser.d.ts.map

package/dist/cli/open-browser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"open-browser.d.ts","sourceRoot":"","sources":["../../src/cli/open-browser.ts"],"names":[],"mappings":"AAEA,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAsBtD"}

package/dist/cli/open-browser.js

@@ -0,0 +1,26 @@
+import { execFile } from "node:child_process";
+export function openBrowser(url) {
+    return new Promise((resolve, reject) => {
+        const platform = process.platform;
+        let command;
+        let args;
+        if (platform === "win32") {
+            command = "cmd";
+            args = ["/c", "start", "", url];
+        }
+        else if (platform === "darwin") {
+            command = "open";
+            args = [url];
+        }
+        else {
+            command = "xdg-open";
+            args = [url];
+        }
+        execFile(command, args, (err) => {
+            if (err)
+                reject(err);
+            else
+                resolve();
+        });
+    });
+}

package/jest.d.ts

@@ -0,0 +1,2 @@
+export { default } from "./dist/jest-reporter.js";
+export * from "./dist/jest-reporter.js";

package/mocha.d.ts

@@ -0,0 +1,2 @@
+export { default } from "./dist/mocha-reporter.js";
+export * from "./dist/mocha-reporter.js";

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@nzila/sdk",
-  "version": "0.1.1",
-  "description": "Send test runs to Nzila and trace live feature errors (Vitest, Jest, Mocha, React, Node).",
+  "version": "0.1.4",
+  "description": "Send test runs to Nzila, trace live feature errors, and onboard via npx @nzila/sdk.",
   "type": "module",
   "license": "MIT",
   "repository": {
@@ -14,35 +14,57 @@
   },
   "files": [
     "dist",
+    "vitest.d.ts",
+    "jest.d.ts",
+    "mocha.d.ts",
+    "runtime.d.ts",
+    "react.d.ts",
     "README.md",
     "examples"
   ],
+  "typesVersions": {
+    "*": {
+      "vitest": ["./dist/vitest-reporter.d.ts"],
+      "jest": ["./dist/jest-reporter.d.ts"],
+      "mocha": ["./dist/mocha-reporter.d.ts"],
+      "runtime": ["./dist/runtime/index.d.ts"],
+      "react": ["./dist/react/index.d.ts"]
+    }
+  },
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
+  "bin": {
+    "nzila": "dist/cli/main.js"
+  },
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
     },
     "./vitest": {
-      "types": "./dist/vitest-reporter.d.ts",
-      "import": "./dist/vitest-reporter.js"
+      "types": "./vitest.d.ts",
+      "import": "./dist/vitest-reporter.js",
+      "default": "./dist/vitest-reporter.js"
     },
     "./jest": {
-      "types": "./dist/jest-reporter.d.ts",
-      "import": "./dist/jest-reporter.js"
+      "types": "./jest.d.ts",
+      "import": "./dist/jest-reporter.js",
+      "default": "./dist/jest-reporter.js"
     },
     "./mocha": {
-      "types": "./dist/mocha-reporter.d.ts",
-      "import": "./dist/mocha-reporter.js"
+      "types": "./mocha.d.ts",
+      "import": "./dist/mocha-reporter.js",
+      "default": "./dist/mocha-reporter.js"
     },
     "./runtime": {
-      "types": "./dist/runtime/index.d.ts",
-      "import": "./dist/runtime/index.js"
+      "types": "./runtime.d.ts",
+      "import": "./dist/runtime/index.js",
+      "default": "./dist/runtime/index.js"
     },
     "./react": {
-      "types": "./dist/react/index.d.ts",
-      "import": "./dist/react/index.js"
+      "types": "./react.d.ts",
+      "import": "./dist/react/index.js",
+      "default": "./dist/react/index.js"
     }
   },
   "scripts": {

package/react.d.ts

@@ -0,0 +1 @@
+export * from "./dist/react/index.js";

package/runtime.d.ts

@@ -0,0 +1 @@
+export * from "./dist/runtime/index.js";

package/vitest.d.ts

@@ -0,0 +1,2 @@
+export { default } from "./dist/vitest-reporter.js";
+export * from "./dist/vitest-reporter.js";