@nlxai/cli 1.2.2-alpha.2

package/LICENSE

@@ -0,0 +1,19 @@
+Copyright (c) 2020, NLX Inc. 
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,86 @@
+# `@nlxai/cli`
+
+> Tools for integrating with NLX apps
+
+**Warning:** This is an alpha package and will likely not work for you. Keep an eye on this space for a more feature complete release later.
+
+## Usage
+
+```
+> npm -g i cli
+
+> nlx
+
+Usage: nlx [options] [command]
+
+Intereact with NLX from the command line
+
+Options:
+  -h, --help                             display help for command
+
+Commands:
+  auth                                   Authentication and user management
+  auth login                             Authenticate with NLX
+  auth logout                            Clear stored authentication tokens
+  auth switch                            Switch to the next saved NLX account
+  auth whoami                            Show current team, role, and available applications count (requires login)
+  modalities                             Work with NLX modalities
+  modalities generate [options]          Fetch modalities and generate TypeScript interfaces
+  modalities check [file]                Type check local TypeScript definitions against server schemas
+  data-requests                          Data Requests
+  data-requests sync [opts] <input>      Sync Data Requests from an OpenAPI Specification or Swagger
+  test [options] <applicationId>         Run conversation tests for a given application ID
+  http [options] <method> <path> [body]  Perform an authenticated request to the management API
+  help [command]                         display help for command
+
+> nlx auth login
+Please visit https://nlxdev.us.auth0.com/activate?user_code=JCVM-MQHX and enter code: JCVM-MQHX
+Login successful! Access token stored securely.
+
+> nlx modalities generate
+✔ TypeScript interfaces written to /Users/jakub.hampl/Programming/nlx/sdk/packages/cli/modalities-types.d.ts
+
+> nlx modalities check
+✔ Type check passed: all remote types are assignable to local types.
+
+> echo "export interface Foo { bar: string; }" >> modalities-types.d.ts
+
+> nlx modalities check
+
+ ERROR  Type check failed:
+  - Type/interface 'Foo' does not correspond to any model on the server.
+
+> bin/nlx data-requests sync __tests__/input-files/sample-openapi.yaml --dry-run  --folder OpenAPI
+ℹ Would create new data request CreateTest POST https://api.example.com/test, but skipping because --dry-run.
+
+> bin/nlx data-requests sync __tests__/input-files/sample-openapi.yaml --interactive  --folder OpenAPI
+# Interactive session where individual requests can be created or updated starts
+
+> bin/nlx test 9bf7404f-8636-4cc6-a33f-cb72ba6a062d --enterprise-region EU
+Fetched 3 tests. Running...
+
+ ERROR  BadTest failed: 0/1
+
+✔ SimpleDataRequest 01
+✔ SimpleCarousel 02
+--------------------------------
+1 tests failed
+
+ ERROR  Test: BadTest
+
+Assertions met: 0/1
+Transcript:
+  1. User: SimpleCarousel
+  2. Bot:
+    ┌─────────────────────────────────────┐
+    │Which invoice would you like to view?│
+    └─────────────────────────────────────┘
+
+  3. User: ➡️ Invoice 001
+  4. Bot:
+    ┌───────┐
+    │Success│
+    └───────┘
+
+Debug at:  https://dev.platform.nlx.ai/flows/SimpleCarousel
+```

package/bin/nlx

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+
+"use strict";
+
+// eslint-disable-next-line no-unused-expressions
+import("../lib/index.js");

package/lib/commands/auth/index.js

@@ -0,0 +1,11 @@
+import { Command } from "commander";
+import { loginCommand } from "./login.js";
+import { logoutCommand } from "./logout.js";
+import { authSwitchCommand } from "./switch.js";
+import { whoamiCommand } from "./whoami.js";
+export const authCommand = new Command("auth")
+    .description("Authentication and user management")
+    .addCommand(loginCommand)
+    .addCommand(logoutCommand)
+    .addCommand(authSwitchCommand)
+    .addCommand(whoamiCommand);

package/lib/commands/auth/login.js

@@ -0,0 +1,145 @@
+import { Command } from "commander";
+import * as fs from "fs";
+import open from "open";
+import * as os from "os";
+import * as path from "path";
+import { consola } from "consola";
+import keytar from "keytar";
+export const ACCOUNTS_PATH = path.join(os.homedir(), ".nlx-cli-auth.json");
+async function saveTokens(account, tokenData) {
+    await keytar.setPassword("nlx-cli", account, JSON.stringify(tokenData));
+}
+async function loadTokens() {
+    try {
+        const data = fs.readFileSync(ACCOUNTS_PATH, "utf8");
+        const accounts = JSON.parse(data);
+        if (accounts.currentAccount) {
+            const res = await keytar.getPassword("nlx-cli", accounts.currentAccount);
+            if (res)
+                return [accounts.currentAccount, JSON.parse(res)];
+        }
+        throw new Error("No tokens found for current account");
+    }
+    catch {
+        throw new Error("Failed to load tokens");
+    }
+}
+async function refreshTokenIfNeeded() {
+    let account, tokens;
+    try {
+        [account, tokens] = await loadTokens();
+    }
+    catch (error) {
+        consola.error("Error loading tokens");
+        return null;
+    }
+    if (!tokens || !tokens.refresh_token)
+        return null;
+    // Check expiry
+    const now = Math.floor(Date.now() / 1000);
+    if (tokens.expires_in &&
+        tokens.obtained_at &&
+        now < tokens.obtained_at + tokens.expires_in - 60) {
+        consola.debug("Access token is still valid.");
+        return tokens.access_token;
+    }
+    consola.debug("Access token is expired or invalid. Refreshing...");
+    // Refresh
+    const res = await fetch(`https://${AUTH0_DOMAIN}/oauth/token`, {
+        method: "POST",
+        headers: { "Content-Type": "application/x-www-form-urlencoded" },
+        body: new URLSearchParams({
+            grant_type: "refresh_token",
+            client_id: CLIENT_ID,
+            refresh_token: tokens.refresh_token,
+        }),
+    });
+    const newTokens = await res.json();
+    if (newTokens.access_token) {
+        newTokens.refresh_token = newTokens.refresh_token || tokens.refresh_token;
+        newTokens.obtained_at = now;
+        await saveTokens(account, newTokens);
+        return newTokens.access_token;
+    }
+    return null;
+}
+const AUTH0_DOMAIN = process.env.AUTH0_DOMAIN || "nlxdev.us.auth0.com"; // e.g. 'dev-xxxxxx.us.auth0.com'
+const CLIENT_ID = process.env.AUTH0_CLIENT_ID || "A0qluq7wJQjFjMLle9pvrWWaVHM1QHE3";
+const AUDIENCE = process.env.AUTH0_AUDIENCE || "https://nlxdev.us.auth0.com/api/v2/";
+export const loginCommand = new Command("login")
+    .description("Authenticate with NLX")
+    .action(async () => {
+    // Step 1: Start device flow
+    const deviceCodeRes = await fetch(`https://${AUTH0_DOMAIN}/oauth/device/code`, {
+        method: "POST",
+        headers: { "Content-Type": "application/x-www-form-urlencoded" },
+        body: new URLSearchParams({
+            client_id: CLIENT_ID,
+            scope: "openid profile email offline_access",
+            audience: AUDIENCE,
+        }),
+    });
+    const deviceCodeData = await deviceCodeRes.json();
+    open(deviceCodeData.verification_uri_complete);
+    consola.box(`Please visit ${deviceCodeData.verification_uri_complete} and enter code: ${deviceCodeData.user_code}`);
+    // Step 2: Poll for token
+    let tokenData;
+    while (!tokenData) {
+        await new Promise((r) => setTimeout(r, deviceCodeData.interval * 1000));
+        const tokenRes = await fetch(`https://${AUTH0_DOMAIN}/oauth/token`, {
+            method: "POST",
+            headers: { "Content-Type": "application/x-www-form-urlencoded" },
+            body: new URLSearchParams({
+                grant_type: "urn:ietf:params:oauth:grant-type:device_code",
+                device_code: deviceCodeData.device_code,
+                client_id: CLIENT_ID,
+            }),
+        });
+        const resData = await tokenRes.json();
+        if (resData.access_token) {
+            tokenData = resData;
+        }
+        else if (resData.error !== "authorization_pending") {
+            consola.error("Error:", resData.error_description || resData.error);
+            return;
+        }
+    }
+    // Step 3: Fetch user object
+    let accounts = { currentAccount: null, accounts: [] };
+    if (fs.existsSync(ACCOUNTS_PATH)) {
+        const data = fs.readFileSync(ACCOUNTS_PATH, "utf8");
+        accounts = JSON.parse(data);
+    }
+    const userRes = await fetch(`https://${AUTH0_DOMAIN}/userinfo`, {
+        headers: {
+            Authorization: `Bearer ${tokenData.access_token}`,
+        },
+    });
+    const userData = await userRes.json();
+    if (!accounts.currentAccount) {
+        await fs.promises.writeFile(ACCOUNTS_PATH, JSON.stringify({
+            currentAccount: userData.email,
+            accounts: [userData.email],
+        }));
+    }
+    else if (accounts.currentAccount !== userData.email) {
+        accounts.currentAccount = userData.email;
+        await fs.promises.writeFile(ACCOUNTS_PATH, JSON.stringify({
+            currentAccount: userData.email,
+            accounts: [userData.email, ...accounts.accounts],
+        }));
+    }
+    // Step 4: Store token securely
+    tokenData.obtained_at = Math.floor(Date.now() / 1000);
+    await saveTokens(userData.email, tokenData);
+    consola.success("Login successful! Access token stored securely.");
+});
+// Example usage: get a valid access token
+export async function ensureToken() {
+    const accessToken = await refreshTokenIfNeeded();
+    if (!accessToken) {
+        consola.error("Not authenticated. Please run 'login' first.");
+        process.exit(1);
+    }
+    return accessToken;
+}

package/lib/commands/auth/logout.js

@@ -0,0 +1,32 @@
+import { Command } from "commander";
+import { consola } from "consola";
+import { ACCOUNTS_PATH } from "./login.js";
+import keytar from "keytar";
+import * as fs from "fs";
+export const logoutCommand = new Command("logout")
+    .description("Clear stored authentication tokens")
+    .action(async () => {
+    try {
+        let accounts = { currentAccount: null, accounts: [] };
+        if (fs.existsSync(ACCOUNTS_PATH)) {
+            const data = fs.readFileSync(ACCOUNTS_PATH, "utf8");
+            accounts = JSON.parse(data);
+        }
+        if (accounts.currentAccount) {
+            await keytar.deletePassword("nlx-cli", accounts.currentAccount);
+            accounts.accounts = accounts.accounts.filter((acc) => acc !== accounts.currentAccount);
+            if (accounts.accounts.length > 0) {
+                accounts.currentAccount = accounts.accounts[0];
+                await fs.promises.writeFile(ACCOUNTS_PATH, JSON.stringify(accounts));
+            }
+            else {
+                await fs.promises.unlink(ACCOUNTS_PATH);
+            }
+        }
+        consola.success("Logged out. Tokens cleared from storage.");
+    }
+    catch (err) {
+        consola.error(`Logout failed: ${err?.message || err}`);
+        process.exitCode = 1;
+    }
+});

package/lib/commands/auth/switch.js

@@ -0,0 +1,30 @@
+import { Command } from "commander";
+import * as fs from "fs";
+import * as path from "path";
+import * as os from "os";
+import { consola } from "consola";
+const ACCOUNTS_PATH = path.join(os.homedir(), ".nlx-cli-auth.json");
+export const authSwitchCommand = new Command("switch")
+    .description("Switch to the next saved NLX account")
+    .action(async () => {
+    if (!fs.existsSync(ACCOUNTS_PATH)) {
+        consola.error("No accounts file found. Please login first.");
+        process.exit(1);
+    }
+    const data = fs.readFileSync(ACCOUNTS_PATH, "utf8");
+    const accounts = JSON.parse(data);
+    if (!accounts.accounts || accounts.accounts.length === 0) {
+        consola.error("No saved accounts found.");
+        process.exit(1);
+    }
+    if (!accounts.currentAccount) {
+        accounts.currentAccount = accounts.accounts[0];
+    }
+    else {
+        const idx = accounts.accounts.indexOf(accounts.currentAccount);
+        const nextIdx = (idx + 1) % accounts.accounts.length;
+        accounts.currentAccount = accounts.accounts[nextIdx];
+    }
+    fs.writeFileSync(ACCOUNTS_PATH, JSON.stringify(accounts, null, 2));
+    consola.success(`Switched to account: ${accounts.currentAccount}`);
+});

package/lib/commands/auth/whoami.js

@@ -0,0 +1,33 @@
+import { Command } from "commander";
+import { consola } from "consola";
+import { fetchManagementApi } from "../../utils/index.js";
+const WHOAMI_DESCRIPTION = "Show current team, role, and available applications count (requires login)";
+function countBots(response) {
+    if (!response || !Array.isArray(response.bots))
+        return 0;
+    return response.bots.length;
+}
+export async function runWhoami() {
+    const [team, bots] = await Promise.all([
+        fetchManagementApi("team"),
+        fetchManagementApi("bots"),
+    ]);
+    const teamName = team?.name ?? "Unknown";
+    const applicationsCount = countBots(bots);
+    consola.success("You are authenticated");
+    consola.info(`Workspace: ${teamName}`);
+    consola.info(`Role: ${team?.currentRole ?? "Unknown"}`);
+    consola.info(`Applications: ${applicationsCount}`);
+}
+export const whoamiCommand = new Command("whoami")
+    .description(WHOAMI_DESCRIPTION)
+    .action(async () => {
+    try {
+        await runWhoami();
+    }
+    catch (err) {
+        const message = err?.response?.data?.message || err?.message || String(err);
+        consola.error(`whoami failed: ${message}`);
+        process.exitCode = 1;
+    }
+});

package/lib/commands/data-requests/index.js

@@ -0,0 +1,5 @@
+import { Command } from "commander";
+import { syncCommand } from "./sync.js";
+export const dataRequestsCommand = new Command("data-requests")
+    .description("Data Requests")
+    .addCommand(syncCommand);

package/lib/commands/data-requests/sync.js

@@ -0,0 +1,328 @@
+import { editor, expand, select } from "@inquirer/prompts";
+import boxen from "boxen";
+import chalk from "chalk";
+import { Command } from "commander";
+import { fetchManagementApi } from "../../utils/index.js";
+import OASNormalize from "oas-normalize";
+import Oas from "oas";
+import open from "open";
+import { consola } from "consola";
+const categorizeServers = async (spec, interactive) => {
+    const { servers } = spec.getDefinition();
+    if (servers == null)
+        throw new Error("No servers defined in the specification");
+    if (servers.length === 1)
+        return { production: 0 };
+    const guess = servers.reduce((acc, server, idx) => {
+        if (server.description != null &&
+            server.description.match(/prod(uction)?/i))
+            acc.production = idx;
+        else if (server.description != null &&
+            server.description.match(/dev(elopment)?|staging/i))
+            acc.development = idx;
+        return acc;
+    }, {});
+    if (interactive) {
+        const servers = spec.getDefinition().servers;
+        if (servers && servers.length > 1) {
+            const serverChoices = servers.map((srv, idx) => ({
+                name: `${srv.url}`,
+                value: idx,
+                description: srv.description,
+            }));
+            const prodIdx = await select({
+                message: "Select production server:",
+                choices: serverChoices,
+                default: guess.production,
+            });
+            const devIdx = await select({
+                message: "Select development server:",
+                choices: serverChoices.concat([
+                    {
+                        name: "No development server",
+                        value: undefined,
+                        description: undefined,
+                    },
+                ]),
+                default: guess.development,
+            });
+            return { production: prodIdx, development: devIdx };
+        }
+    }
+    return guess;
+};
+const resolveAmbiguity = (arr, interactive, id, label) => {
+    if (arr.length === 0)
+        return Promise.resolve(undefined);
+    if (arr.length === 1)
+        return Promise.resolve(arr[0]);
+    if (interactive) {
+        return select({
+            message: `Select ${label} in ${id}:`,
+            choices: arr.map((item, index) => ({
+                name: JSON.stringify(item, null, 2),
+                value: item,
+            })),
+        });
+    }
+    return Promise.resolve(arr[0]);
+};
+const capitalize = (str) => {
+    return str[0].toUpperCase() + str.slice(1);
+};
+export const syncCommand = new Command("sync")
+    .summary("Sync Data Requests from an OpenAPI Specification or Swagger")
+    .description(`Takes an OpenAPI Specification or Swagger file and creates or updates data requests in your NLX account to match the API definition.
+
+Supports OpenAPI 2.0, 3.0, 3.1, Swagger in JSON and YAML formats. Also experimentally supports Postman collections.
+
+NLX Data Requests only support a subset of HTTP functionality described in the OpenAPI Specification. 
+Operations that don't meet the following will be skipped:
+
+  - Request and response bodies must be in JSON format.
+  - Endpoints must either be unsecured or use API key or Bearer token authentication.
+  - Operations must not be marked deprecated.
+
+The following features are not supported and will be silently ignored:
+
+  - Query parameters.
+  - Cookies.
+  - Fancier JSON Schema features outside the NLX data model.
+  - Multiple response schemas (only the first 2xx response is used).
+`)
+    .argument("<input-spec>", "Path to the OpenAPI Specification or Swagger file")
+    .requiredOption("--folder <folder>", "Folder where the data requests will be organized")
+    .optionsGroup("Security mechanism:")
+    .option("--api-key-secret <secret>", "Name of the NLX Secret containing the secret to use for the API key security mechanism")
+    .option("--bearer-secret <secret>", "Name of the NLX Secret containing the secret to use for the Bearer token security mechanism")
+    .optionsGroup("Run modes:")
+    .option("--dry-run", "Simulate the sync process without making any changes")
+    .option("--interactive", "Prompt for each operation before syncing, allowing user to approve, skip, or resolve ambiguities")
+    .action(async (inputSpec, options) => {
+    const currentData = new Map((await fetchManagementApi("variables?size=1000")).variables.map((variable) => [variable.variableId, variable]));
+    let oas = new OASNormalize(inputSpec, { enablePaths: true });
+    try {
+        await oas.validate();
+    }
+    catch (error) {
+        consola.error("Failed to validate OpenAPI Specification:", error);
+        process.exit(1);
+    }
+    const spec = Oas.init((await oas.convert()));
+    await spec.dereference();
+    const serverIndices = await categorizeServers(spec, options.interactive ?? false);
+    const newData = await Promise.all(Object.entries(spec.getPaths()).flatMap(([path, methods]) => {
+        return Object.values(methods)
+            .filter((operation) => {
+            return (operation.getContentType() === "application/json" &&
+                !operation.isDeprecated() &&
+                !operation.isWebhook());
+        })
+            .filter((operation) => {
+            const keys = Object.keys(operation.prepareSecurity());
+            if (keys.length === 0 ||
+                keys.includes("Header") ||
+                keys.includes("Bearer")) {
+                return true;
+            }
+            else {
+                consola.warn(`Skipping operation ${operation.getOperationId()} due to unsupported security schemes: ${keys.join(", ")}`);
+                return false;
+            }
+        })
+            .map(async (operation) => {
+            const variableId = capitalize(operation
+                .getOperationId()
+                .replace(/[^a-zA-Z0-9]+([a-zA-Z0-9]|$)/g, (_, v) => {
+                return v.toUpperCase();
+            }));
+            const codes = await resolveAmbiguity(operation
+                .getResponseStatusCodes()
+                .map(parseInt)
+                .filter((r) => r >= 200 && r < 300), options.interactive, variableId, "response status codes");
+            operation
+                .getParameters()
+                .filter((op) => ["cookie", "query"].includes(op.in))
+                .forEach((param) => {
+                consola.warn(`${param.in} param ${param.name} not supported, skipping.`);
+            });
+            let headers = operation.getHeaders().request.map((header) => ({
+                key: header,
+                value: "",
+                dynamic: true,
+                required: false,
+            }));
+            const security = operation.prepareSecurity();
+            if (security.Header &&
+                security.Header.length === 1 &&
+                options.apiKeySecret &&
+                security.Header[0].type === "apiKey") {
+                if (options.apiKeySecret) {
+                    const apiSecretSecurity = security.Header.filter((h) => h.type === "apiKey");
+                    if (apiSecretSecurity.length === 1 &&
+                        apiSecretSecurity[0].type === "apiKey" &&
+                        apiSecretSecurity[0].in === "header") {
+                        const name = apiSecretSecurity[0].name;
+                        headers = [
+                            ...headers.filter((h) => h.key !== name),
+                            {
+                                key: name,
+                                value: `{${options.apiKeySecret}:NLX.Secret}`,
+                                dynamic: false,
+                                required: true,
+                            },
+                        ];
+                    }
+                }
+            }
+            if (options.bearerSecret) {
+                const bearerSecurity = security.Bearer?.filter((h) => h.type === "http" && h.scheme === "bearer") ?? [];
+                if (bearerSecurity.length === 1) {
+                    headers = [
+                        ...headers.filter((h) => h.key !== "Authorization"),
+                        {
+                            key: "Authorization",
+                            value: `Bearer {${options.bearerSecret}:NLX.Secret}`,
+                            dynamic: false,
+                            required: true,
+                        },
+                    ];
+                }
+            }
+            return {
+                variableId,
+                path: options.folder,
+                type: "text",
+                description: operation.getSummary() || operation.getDescription(),
+                requestSchema: await extractSchema(operation.getRequestBody("application/json") || undefined, options.interactive, variableId, "request schema"),
+                responseSchema: await extractSchema(codes ? operation.getResponseAsJSONSchema(codes) : undefined, options.interactive, variableId, "response schema"),
+                webhook: {
+                    implementation: "external",
+                    method: operation.method.toUpperCase(),
+                    sendContext: false,
+                    version: "v3",
+                    environments: {
+                        production: {
+                            url: spec.url(serverIndices.production) + operation.path,
+                            headers,
+                        },
+                        development: serverIndices.development == null
+                            ? undefined
+                            : {
+                                url: spec.url(serverIndices.development) +
+                                    operation.path,
+                                headers,
+                            },
+                    },
+                },
+            };
+        });
+    }));
+    for (const dataRequest of newData) {
+        let proceed = true;
+        let resolvedRequest = { ...dataRequest };
+        let action;
+        if (options.interactive) {
+            const preview = [
+                chalk.bold(dataRequest.webhook.method +
+                    " " +
+                    chalk.underline(dataRequest.webhook.environments.production.url)),
+                chalk.dim(dataRequest.description),
+                "",
+                chalk.bold.magenta(`Request Schema:`),
+                chalk.white(JSON.stringify(dataRequest.requestSchema, null, 2)),
+                "",
+                chalk.bold.magenta(`Response Schema:`),
+                chalk.white(JSON.stringify(dataRequest.responseSchema, null, 2)),
+            ].join("\n");
+            consola.log(boxen(preview, {
+                padding: 1,
+                margin: 1,
+                borderStyle: "round",
+                borderColor: "cyan",
+                backgroundColor: "black",
+                title: dataRequest.variableId,
+            }));
+            action = await expand({
+                message: "Sync this operation?",
+                choices: [
+                    { key: "y", name: "Sync", value: "sync" },
+                    { key: "n", name: "Skip", value: "skip" },
+                    { key: "e", name: "Edit in your $EDITOR", value: "edit" },
+                    { key: "u", name: "Sync then edit in UI", value: "edit-ui" },
+                ],
+                default: "y",
+            });
+            if (action === "skip") {
+                proceed = false;
+            }
+            else if (action === "edit") {
+                const res = await editor({
+                    message: "Open JSON in your editor",
+                    default: JSON.stringify(dataRequest, null, 2),
+                    postfix: ".json",
+                    waitForUseInput: false,
+                    validate: (text) => {
+                        try {
+                            JSON.parse(text);
+                            return true;
+                        }
+                        catch {
+                            return "Invalid JSON";
+                        }
+                    },
+                });
+                resolvedRequest = JSON.parse(res);
+            }
+        }
+        if (!proceed)
+            continue;
+        const existing = currentData.get(resolvedRequest.variableId);
+        if (existing) {
+            if (!Object.entries(resolvedRequest).every(([key, value]) => {
+                return eq(value, existing[key]);
+            })) {
+                await wrapDataReqCU(false, resolvedRequest, options.dryRun, action);
+            }
+        }
+        else {
+            await wrapDataReqCU(true, resolvedRequest, options.dryRun, action);
+        }
+    }
+});
+const wrapDataReqCU = async (create, dataRequest, dryRun, action) => {
+    if (dryRun) {
+        consola.info(`Would ${create ? "create new" : "update existing"} data request ${dataRequest.variableId} ${dataRequest.webhook.method} ${dataRequest.webhook.environments.production.url}, but skipping because --dry-run.`);
+    }
+    else {
+        consola.start(`${create ? "Creating new" : "Updating existing"} data request ${dataRequest.variableId} ${dataRequest.webhook.method} ${dataRequest.webhook.environments.production.url}...`);
+        await fetchManagementApi(`variables/${dataRequest.variableId}`, create ? "PUT" : "POST", dataRequest);
+        consola.success(`Successfully ${create ? "Created new" : "Updated existing"} data request ${dataRequest.variableId} ${dataRequest.webhook.method} ${dataRequest.webhook.environments.production.url}.`);
+        if (action === "edit-ui") {
+            open(`https://dev.platform.nlx.ai/data-requests/${dataRequest.variableId}`);
+        }
+    }
+};
+const extractSchema = async (schema, interactive, id, label) => {
+    if (schema == null)
+        return undefined;
+    if (Array.isArray(schema) && schema.length > 0) {
+        schema = await resolveAmbiguity(schema, interactive, id, label);
+    }
+    if (schema != null && "schema" in schema) {
+        schema = schema.schema;
+    }
+    return schema;
+};
+const eq = (a, b) => {
+    if (a === b)
+        return true;
+    if (a == null && b == null)
+        return true;
+    if (typeof a == "object" && typeof b == "object") {
+        const aKeys = Object.keys(a);
+        const bKeys = Object.keys(b);
+        return aKeys.every((key) => eq(a[key], b[key]));
+    }
+    return false;
+};

package/lib/commands/http.js

@@ -0,0 +1,60 @@
+import { Command } from "commander";
+import * as fs from "fs";
+import { fetchManagementApi } from "../utils/index.js";
+import { consola } from "consola";
+export const httpCommand = new Command("http")
+    .description("Perform an authenticated request to the management API")
+    .argument("<method>", "HTTP method (GET, POST, PUT, DELETE, etc.)")
+    .argument("<path>", "API path (e.g. /models)")
+    .argument("[body]", "Request body as JSON string, name of a JSON file or -- for Standard Input")
+    .option("-p, --paginate", "Enable pagination", false)
+    .action(async (method, apiPath, body, opts) => {
+    if (body === "--") {
+        // Read from stdin
+        body = "";
+        process.stdin.setEncoding("utf8");
+        for await (const chunk of process.stdin)
+            body += chunk;
+        try {
+            body = JSON.parse(body);
+        }
+        catch (ed) {
+            consola.error("Invalid JSON string from stdin: " + ed);
+            process.exit(1);
+        }
+    }
+    else if (body != null) {
+        // Try to parse as file path or JSON string
+        try {
+            if (fs.existsSync(body)) {
+                body = JSON.parse(fs.readFileSync(body, "utf8"));
+            }
+            else {
+                body = JSON.parse(body);
+            }
+        }
+        catch {
+            consola.error("Invalid JSON string or file path: " + body);
+            process.exit(1);
+        }
+    }
+    let result = await fetchManagementApi(apiPath +
+        (opts.paginate
+            ? apiPath.includes("?")
+                ? "&size=1000"
+                : "?size=1000"
+            : ""), method.toUpperCase(), body);
+    let agg;
+    if (opts.paginate) {
+        const key = Object.keys(result).filter((k) => k !== "nextPageId")[0];
+        agg = result[key];
+        while (result.nextPageId) {
+            result = await fetchManagementApi(apiPath + `?pageId=${result.nextPageId}`, method.toUpperCase(), body);
+            agg.push(...result[key]);
+        }
+    }
+    else {
+        agg = result;
+    }
+    console.log(JSON.stringify(agg, null, 2));
+});

package/lib/commands/modalities/check.js

@@ -0,0 +1,99 @@
+import { Command } from "commander";
+import { promises as fs, existsSync } from "fs";
+import * as path from "path";
+import * as os from "os";
+import { fetchManagementApi } from "../../utils/index.js";
+import ts from "typescript";
+import { compile } from "json-schema-to-typescript";
+import chalk from "chalk";
+import { consola } from "consola";
+export const modalitiesCheckCommand = new Command("check")
+    .description("Type check local TypeScript definitions against server schemas")
+    .argument("[file]", "TypeScript file to check (e.g. one generated by 'modalities generate')", "modalities-types.d.ts")
+    .action(async (file) => {
+    // Fetch server models
+    const data = await fetchManagementApi(`models`);
+    const serverModels = {};
+    for (const item of data.items) {
+        serverModels[item.modelId] = item.schema;
+    }
+    // Read local TypeScript file
+    const filePath = path.resolve(process.cwd(), file);
+    if (!existsSync(filePath)) {
+        consola.error(`File not found: ${filePath}`);
+        process.exit(1);
+    }
+    const tsSource = await fs.readFile(filePath, "utf8");
+    // Generate remote types from schemas
+    let remoteTypesSource = "";
+    for (const modelId in serverModels) {
+        const typeName = modelId.replace(/[^a-zA-Z0-9_]/g, "");
+        const tsType = await compile(serverModels[modelId], typeName, {
+            bannerComment: "",
+            additionalProperties: false,
+        });
+        remoteTypesSource += tsType + "\n";
+    }
+    // Create a virtual TypeScript program with both local and remote types
+    const tmpRemotePath = path.join(os.tmpdir(), `modalities-remote-${Date.now()}.d.ts`);
+    await fs.writeFile(tmpRemotePath, remoteTypesSource);
+    const program = ts.createProgram([filePath, tmpRemotePath], {});
+    const checker = program.getTypeChecker();
+    // Get local and remote type symbols
+    const localSourceFile = program.getSourceFile(filePath);
+    const remoteSourceFile = program.getSourceFile(tmpRemotePath);
+    if (!localSourceFile || !remoteSourceFile) {
+        consola.error("Could not load source files for type checking.");
+        process.exit(1);
+    }
+    // Map type names to symbols
+    const getTypeSymbols = (sourceFile) => {
+        const symbols = {};
+        sourceFile.forEachChild((node) => {
+            if (ts.isInterfaceDeclaration(node) ||
+                ts.isTypeAliasDeclaration(node)) {
+                const name = node.name.text;
+                const symbol = checker.getSymbolAtLocation(node.name);
+                if (symbol)
+                    symbols[name] = symbol;
+            }
+        });
+        return symbols;
+    };
+    const localSymbols = getTypeSymbols(localSourceFile);
+    const remoteSymbols = getTypeSymbols(remoteSourceFile);
+    // Check assignability
+    let errors = [];
+    for (const typeName in localSymbols) {
+        if (!remoteSymbols[typeName]) {
+            errors.push(`Type/interface '${typeName}' does not correspond to any model on the server.`);
+            continue;
+        }
+        const localType = checker.getDeclaredTypeOfSymbol(localSymbols[typeName]);
+        const remoteType = checker.getDeclaredTypeOfSymbol(remoteSymbols[typeName]);
+        if (!checker.isTypeAssignableTo(remoteType, localType)) {
+            errors.push(`NLX modality type for '${typeName}' is not assignable to local type.
+
+${chalk.bold("NLX modality type definition:")}
+
+${remoteSymbols[typeName].declarations?.[0]?.getText() ?? checker.typeToString(remoteType)}
+
+${chalk.bold("Local type definition:")}
+
+${localSymbols[typeName].declarations?.[0]?.getText() ?? checker.typeToString(localType)}
+          `);
+        }
+    }
+    await fs.unlink(tmpRemotePath);
+    if (errors.length) {
+        let errorMsg = "Type check failed:\n";
+        for (const err of errors)
+            errorMsg += `  - ${err}\n`;
+        consola.error(errorMsg.trim());
+        process.exit(1);
+    }
+    else {
+        consola.success("Type check passed: all remote types are assignable to local types.");
+        process.exit(0);
+    }
+});

package/lib/commands/modalities/generate.js

@@ -0,0 +1,27 @@
+import { Command } from "commander";
+import { compile } from "json-schema-to-typescript";
+import * as fs from "fs";
+import * as path from "path";
+import { fetchManagementApi } from "../../utils/index.js";
+import { consola } from "consola";
+export const modalitiesGenerateCommand = new Command("generate")
+    .description("Fetch modalities and generate TypeScript interfaces")
+    .option("-o, --out <file>", "Output TypeScript file", "modalities-types.d.ts")
+    .action(async (opts) => {
+    const data = await fetchManagementApi(`models`);
+    // Generate TypeScript interfaces for each modelId
+    let output = "// Auto-generated from NLX\n// Please do not edit manually\n\n";
+    for (const item of data.items) {
+        const name = item.modelId.replace(/[^a-zA-Z0-9_]/g, "");
+        const schema = item.schema;
+        const ts = await compile(schema, name, {
+            bannerComment: "",
+            additionalProperties: false,
+        });
+        output += ts + "\n";
+    }
+    // Write to file specified by flag or default
+    const outPath = path.resolve(process.cwd(), opts.out);
+    fs.writeFileSync(outPath, output);
+    consola.success(`TypeScript interfaces written to ${outPath}`);
+});

package/lib/commands/modalities/index.js

@@ -0,0 +1,7 @@
+import { Command } from "commander";
+import { modalitiesGenerateCommand } from "./generate.js";
+import { modalitiesCheckCommand } from "./check.js";
+export const modalitiesCommand = new Command("modalities")
+    .description("Work with NLX modalities")
+    .addCommand(modalitiesGenerateCommand)
+    .addCommand(modalitiesCheckCommand);

package/lib/commands/test.js

@@ -0,0 +1,208 @@
+import { Command } from "commander";
+import { fetchManagementApi } from "../utils/index.js";
+import { consola } from "consola";
+import { createConversation, } from "@nlxai/core";
+import { ensureToken } from "./auth/login.js";
+import { flatten, uniq } from "ramda";
+import chalk from "chalk";
+import boxen from "boxen";
+export const testCommand = new Command("test")
+    .description("Run conversation tests for a given application ID")
+    .argument("<applicationId>", "Application ID to fetch tests for")
+    .option("--env <environment>", "Specify the environment", "production")
+    .option("--language <language>", "Specify the language code", "en-US")
+    .option("--channel <channel>", "Specify the channel type", "API")
+    .option("--applications-url-base-override <url>", "Override the base URL for applications")
+    .option("--enterprise-region <region>", "Specify the enterprise region")
+    .action(async (applicationId, opts) => {
+    try {
+        const { tests } = (await fetchManagementApi(`bots/${applicationId}/conversationTests`, "GET"));
+        consola.log("Fetched %i tests. Running...", tests.length);
+        const baseUrl = getBaseUrl(opts.enterpriseRegion == null, opts.applicationsUrlBaseOverride ?? "", opts.enterpriseRegion ?? "US");
+        const applicationUrl = `${baseUrl}/c/${applicationId}/sandbox`;
+        consola.debug("Application URL:", applicationUrl);
+        const accessToken = await ensureToken();
+        const handlerConfig = {
+            applicationUrl,
+            headers: {
+                "nlx-api-key": accessToken,
+                Authorization: `Bearer ${accessToken}`,
+            },
+            environment: opts.env,
+            languageCode: opts.language,
+            experimental: {
+                channelType: opts.channel,
+                completeApplicationUrl: true,
+            },
+        };
+        const failures = [];
+        for await (const test of tests) {
+            const result = await runTest(test, handlerConfig, applicationId);
+            if (result.met.length === result.total.length) {
+                consola.success(test.name);
+            }
+            else {
+                failures.push({
+                    name: test.name,
+                    met: result.met.length,
+                    total: result.total.length,
+                    responses: result.responses,
+                    intentId: test.steps[0]?.raw?.intentId,
+                });
+                consola.error(`${test.name} failed: ${result.met.length}/${result.total.length}`);
+            }
+        }
+        if (failures.length > 0) {
+            consola.log("--------------------------------");
+            consola.log("%i tests failed", failures.length);
+            failures.forEach((failure) => {
+                consola.error("Test: %s", failure.name);
+                consola.log("Assertions met: %i/%i", failure.met, failure.total);
+                console.log("Transcript:");
+                failure.responses.forEach((response, index) => {
+                    if (response.type === "user") {
+                        consola.log(`  %i. ${chalk.blue("User")}: %s`, index + 1, response.payload.type === "structured"
+                            ? `${chalk.underline(response.payload.intentId)}`
+                            : response.payload.type == "choice"
+                                ? `➡️ ${response.payload.choiceId}`
+                                : response.payload.text);
+                    }
+                    else if (response.type === "bot") {
+                        consola.log(`  %i. ${chalk.yellow("Bot")}:`, index + 1);
+                        consola.log(response.payload.messages
+                            .map((msg) => boxen(msg.text, { margin: { left: 4, bottom: 1 } }))
+                            .join("\n"));
+                    }
+                });
+                consola.log("Debug at: ", chalk.underline(`https://dev.platform.nlx.ai/flows/${failure.intentId}`));
+            });
+            process.exit(1);
+        }
+        else {
+            consola.success("All tests passed!");
+        }
+    }
+    catch (err) {
+        consola.error("Failed to fetch tests:", err);
+        process.exit(1);
+    }
+});
+const runTest = async (test, config, applicationId) => {
+    const handler = createConversation(config);
+    const responses = await replayConversation({
+        steps: test.steps,
+        conversationHandler: handler,
+    });
+    const { total, met } = assertionsSummary(responses, test.assertions);
+    handler.destroy();
+    await fetchReset(applicationId);
+    return { total, met, responses };
+};
+const fetchReset = async (applicationId) => {
+    return await fetchManagementApi(`bots/${applicationId}/sandbox/reset`, "POST");
+};
+const replayConversation = async ({ steps, conversationHandler, }) => {
+    if (steps.length === 0) {
+        return [];
+    }
+    const [firstStep, ...restSteps] = steps;
+    if (firstStep.raw.type === "structured" && (firstStep.raw.poll ?? false)) {
+        return replayConversation({
+            steps: restSteps,
+            conversationHandler,
+        });
+    }
+    return await new Promise((resolve) => {
+        const handleResponse = (responses, newResponse) => {
+            if (newResponse == null) {
+                return;
+            }
+            if (newResponse.type === "bot" &&
+                !(newResponse.payload.metadata?.hasPendingDataRequest ?? false)) {
+                setTimeout(() => {
+                    conversationHandler.unsubscribe(handleResponse);
+                    if (restSteps.length === 0) {
+                        resolve(responses);
+                    }
+                    else {
+                        resolve(replayConversation({
+                            steps: restSteps,
+                            conversationHandler,
+                        }));
+                    }
+                }, 250);
+            }
+            else if (isTestCompleted(responses, steps)) {
+                resolve(responses);
+            }
+        };
+        conversationHandler.subscribe(handleResponse);
+        if (firstStep.raw.type === "text") {
+            conversationHandler.sendText(firstStep.raw.text, firstStep.raw.context);
+        }
+        else if (firstStep.raw.type === "choice") {
+            // TODO: add response and message indices to fix button click states
+            conversationHandler.sendChoice(firstStep.raw.choiceId, firstStep.raw.context);
+        }
+        else if (firstStep.raw.type === "structured") {
+            conversationHandler.sendStructured({
+                // eslint-disable-next-line deprecation/deprecation
+                intentId: firstStep.raw.intentId,
+                choiceId: firstStep.raw.choiceId,
+                slots: firstStep.raw.slots,
+            }, firstStep.raw.context);
+        }
+    });
+};
+const isTestCompleted = (responses, steps) => {
+    let pendingTestStepIndex = 0;
+    let index = 0;
+    for (const response of responses) {
+        if (response.type === "user") {
+            pendingTestStepIndex++;
+        }
+        // If all test steps have been triggered and there is a subsequent application response available, the test is considered complete
+        if (pendingTestStepIndex === steps.length + 1 && response.type === "bot") {
+            return true;
+        }
+        index++;
+    }
+    return false;
+};
+export const assertionsSummary = (responses, assertions) => {
+    const assertionNodes = getAssertionNodes(assertions);
+    const applicationResponses = responses.filter((res) => res.type === "bot");
+    const payloads = applicationResponses.map((res) => res.payload);
+    const nodesHit = applicationResponseTraversedNodeIds(payloads);
+    return {
+        met: nodesHit.filter((nodeId) => assertionNodes.includes(nodeId)),
+        total: assertionNodes,
+    };
+};
+const applicationResponseTraversedNodeIds = (application) => uniq(flatten(application.map((payload) => traversalNodeIds(payload.debugEvents ?? []))));
+const traversalNodeIds = (events) => {
+    const nodeIds = [];
+    events.forEach((event) => {
+        if (event.eventType === "NodeTraversal" &&
+            typeof event.nodeId === "string") {
+            nodeIds.push(event.nodeId);
+        }
+    });
+    return nodeIds;
+};
+const getAssertionNodes = (assertions) => {
+    return uniq(assertions
+        .map(({ nodeId }) => nodeId)
+        .filter((nodeId) => nodeId != null));
+};
+const getBaseUrl = (isGa, applicationsUrlBaseOverride, region) => {
+    const httpsBaseUrl = isGa
+        ? `https://dev.apps.nlx.ai`
+        : `https://bots.dev.studio.nlx.ai`;
+    const baseUrl = applicationsUrlBaseOverride.length > 0
+        ? applicationsUrlBaseOverride
+        : region === "EU"
+            ? httpsBaseUrl.replace("//", "//eu-central-1.")
+            : httpsBaseUrl;
+    return baseUrl;
+};

package/lib/index.js

@@ -0,0 +1,13 @@
+import { program } from "commander";
+import { authCommand } from "./commands/auth/index.js";
+import { modalitiesCommand } from "./commands/modalities/index.js";
+import { dataRequestsCommand } from "./commands/data-requests/index.js";
+import { httpCommand } from "./commands/http.js";
+import { testCommand } from "./commands/test.js";
+program.description("Intereact with NLX from the command line");
+program.addCommand(authCommand);
+program.addCommand(modalitiesCommand);
+program.addCommand(dataRequestsCommand);
+program.addCommand(testCommand);
+program.addCommand(httpCommand);
+program.parse(process.argv);

package/lib/utils/index.js

@@ -0,0 +1,19 @@
+import { ensureToken } from "../commands/auth/login.js";
+import { consola } from "consola";
+const API_BASE_URL = process.env.NLX_API_BASE_URL || "https://api.dev.studio.nlx.ai/v1";
+export const fetchManagementApi = async (path, method = "GET", body) => {
+    const accessToken = await ensureToken();
+    const res = await fetch(`${API_BASE_URL}/${path}`, {
+        headers: {
+            Authorization: `Bearer ${accessToken}`,
+            Accept: "application/json",
+        },
+        method,
+        body: body ? JSON.stringify(body) : undefined,
+    });
+    if (!res.ok) {
+        consola.error("Failed to fetch:", res.status, await res.text());
+        process.exit(1);
+    }
+    return await res.json();
+};

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@nlxai/cli",
+  "version": "1.2.2-alpha.2",
+  "description": "Tools for integrating with NLX apps",
+  "keywords": [
+    "NLX",
+    "AI",
+    "typescript"
+  ],
+  "type": "module",
+  "author": "Jakub Hampl <jakub@nlx.ai>",
+  "homepage": "https://github.com/nlxai/sdk#readme",
+  "license": "MIT",
+  "main": "lib/index.ts",
+  "bin": {
+    "npx": "bin/npx"
+  },
+  "directories": {
+    "lib": "lib"
+  },
+  "files": [
+    "bin",
+    "lib"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nlxai/sdk.git"
+  },
+  "scripts": {
+    "dev": "vitest",
+    "test": "vitest run",
+    "build": "tsc",
+    "tsc": "tsc"
+  },
+  "dependencies": {
+    "@inquirer/prompts": "^7.8.4",
+    "@nlxai/core": "^1.1.8-alpha.0",
+    "boxen": "^8.0.1",
+    "chalk": "^4.1.0",
+    "commander": "^14.0",
+    "consola": "^3.4.2",
+    "json-schema-to-typescript": "^15.0.4",
+    "keytar": "^7.9.0",
+    "oas": "^28.1.0",
+    "oas-normalize": "^15.0.1",
+    "open": "^8.4.2",
+    "typescript": "^5.4.5"
+  },
+  "bugs": {
+    "url": "https://github.com/nlxai/sdk/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@vitest/coverage-istanbul": "^3.2.4",
+    "@vitest/coverage-v8": "^3.2.4",
+    "@vitest/ui": "^3.2.4",
+    "vitest": "^3.2.4"
+  },
+  "gitHead": "326f4ca5d7362bf8f3c01acfd9f01844fdf53904"
+}