@botonic/nx-plugin 2.30.0 → 2.31.1-alpha.0

package/src/lib/credentials-handler.d.ts

@@ -1,4 +1,4 @@
-import type { BotCredentials, GlobalCredentialsStore, JSONObject } from './interfaces';
+import type { BotRegistryEntry, BotsRegistry, GlobalCredentialsStore, JSONObject } from './interfaces';
 export declare class CredentialsHandler {
     homeDir: string;
     pathToCredentials: string;
@@ -9,12 +9,12 @@ export declare class CredentialsHandler {
     initialize(): void;
     createDirIfNotExists(): void;
     loadJSON(): JSONObject | undefined;
-    dumpJSON(obj: JSONObject): void;
+    dumpJSON(obj: JSONObject | JSONObject[]): void;
 }
 export declare class GlobalCredentialsHandler extends CredentialsHandler {
     /**
      * @param baseDir - Optional directory for credentials (e.g. monorepo_root/.botonic).
-     * When provided, credentials are stored at baseDir/credentials.json (source of truth in monorepo).
+     * When provided, credentials are stored at baseDir/env-credentials.json.
      * When omitted, uses ~/.botonic (user home).
      */
     constructor(baseDir?: string);
@@ -22,19 +22,10 @@ export declare class GlobalCredentialsHandler extends CredentialsHandler {
     load(): GlobalCredentialsStore | undefined;
     dump(obj: GlobalCredentialsStore): void;
 }
-declare class BaseBotCredentialsHandler<T> extends CredentialsHandler {
-    constructor(args: {
-        homeDir: string;
-        filename: string;
-    });
-    load(): T | undefined;
-    dump(obj: T): void;
-}
-export declare class BotCredentialsHandler extends BaseBotCredentialsHandler<BotCredentials> {
-    /**
-     * @param projectRoot - Directory for app/project .botonic.json (e.g. apps/my-bot).
-     * When omitted, uses process.cwd() (may write to repo root when Nx cwd is workspace root).
-     */
-    constructor(projectRoot?: string);
+export declare class BotsRegistryHandler extends CredentialsHandler {
+    constructor();
+    load(): BotsRegistry;
+    dump(registry: BotsRegistry): void;
+    upsert(env: string, entry: BotRegistryEntry): void;
+    findLatestForEnv(env: string): BotRegistryEntry | undefined;
 }
-export {};

package/src/lib/delegate/delegate-executor.d.ts

@@ -0,0 +1,6 @@
+import type { ExecutorContext } from '@nx/devkit';
+export declare function runLocalExecutor<T = unknown>(wrapperFilename: string, executorName: string, options: T, ctx: ExecutorContext): Promise<{
+    success: boolean;
+} | AsyncIterableIterator<{
+    success: boolean;
+}>>;

package/src/lib/delegate/delegate-generator.d.ts

@@ -0,0 +1,2 @@
+import type { GeneratorCallback, Tree } from '@nx/devkit';
+export declare function runLocalGenerator<T>(wrapperFilename: string, generatorName: string, tree: Tree, options: T): Promise<GeneratorCallback | void>;

package/src/lib/interfaces.d.ts

@@ -24,23 +24,20 @@ export interface EnvironmentCredentials {
 }
 /** Store: one entry per environment so multiple envs can be logged in. */
 export type GlobalCredentialsStore = Record<string, EnvironmentCredentials>;
+export interface ProviderAccountEntry {
+    id: string;
+    provider: string;
+    is_test: boolean;
+    is_active: boolean;
+}
 export interface BotDetail {
     id: string;
     name: string;
-    organization: string;
-    last_update: any;
-    created_at: string;
-    provider_accounts: any[];
-    is_debug: boolean;
-    is_published: boolean;
-    active_users: number;
-}
-export interface BotCredentials {
-    bot: BotDetail | null;
-}
-export interface LocalRuntimeBotCredentials {
-    localRuntimeBot: BotDetail | null;
+    providers?: ProviderAccountEntry[];
+    [key: string]: unknown;
 }
+export type BotRegistryEntry = BotDetail;
+export type BotsRegistry = Record<string, BotRegistryEntry[]>;
 export type JSONPrimitive = string | number | boolean | null;
 export type JSONValue = JSONPrimitive | JSONObject | JSONArray;
 export type JSONObject = {

package/src/lib/serve-mode/index.d.ts

@@ -0,0 +1,25 @@
+import type { Plugin } from 'vite';
+export interface ChannelCredentials {
+    botId?: string;
+    apiUrl?: string;
+    tunnelUrl?: string;
+    lambdaFn?: string;
+    accessToken?: string;
+    refreshToken?: string;
+    clientId?: string;
+}
+export interface WhatsappPanelOptions extends ChannelCredentials {
+    registeredPhone?: string;
+}
+export interface DevPanelsOptions {
+    panels: Array<'whatsapp' | 'webchat'>;
+    registeredPhone?: string;
+}
+/** Injects the WhatsApp channel routing panel. Serve-only. */
+export declare function createWhatsappPanelPlugin(opts?: WhatsappPanelOptions): Plugin;
+/** Injects the Webchat channel routing panel. Serve-only. */
+export declare function createWebchatPanelPlugin(opts?: ChannelCredentials): Plugin;
+/** Injects the log-viewer split layout. Serve-only. No per-panel configuration needed. */
+export declare function createLogViewerPlugin(): Plugin;
+/** Convenience wrapper — creates all requested panel plugins in one call. */
+export declare function createDevPanelsPlugin(opts: DevPanelsOptions): Plugin[];

package/src/lib/util/executor-helpers.d.ts

@@ -1,6 +1,5 @@
 import type { ExecutorContext } from '@nx/devkit';
 import { BotonicAPIService } from '../api-service';
-import type { BotDetail } from '../interfaces';
 export declare function resolveProjectPath(context: ExecutorContext): string;
 export declare function askEmailPassword(): Promise<{
     email: string;
@@ -15,7 +14,7 @@ export declare function handleAuthentication(botonicApiService: BotonicAPIServic
  */
 export declare function logWorkingAsAndEnvironment(botonicApiService: BotonicAPIService): Promise<void>;
 export declare function getAvailableBots(botonicApiService: BotonicAPIService): Promise<any[]>;
-export declare function createNewBotWithName(botonicApiService: BotonicAPIService, botName: string): Promise<void>;
+export declare function createNewBotWithName(botonicApiService: BotonicAPIService, botName: string, isTest?: boolean): Promise<void>;
 export declare function getAppIdFromEnvFile(projectRoot: string, appIdKey: string): string | null;
 /**
  * Reads VITE_HUBTYPE_APP_ID from .env.[configuration] (e.g. .env.dev) or .env.local when configuration is 'local'.
@@ -53,24 +52,14 @@ export declare function resolveHubtypeEnvironment(context: ExecutorContext, opti
 };
 /**
  * Ensures the user is logged in to Hubtype before starting the tunnel flow.
- * Run this before Lambda + cloudflared + deploy_local_runtime so the login prompt happens first.
  */
-export declare function ensureHubtypeLoginBeforeTunnel(context: ExecutorContext, projectRoot: string, options?: PerformDeployLocalRuntimeOptions): Promise<void>;
+export declare function ensureHubtypeLoginBeforeTunnel(context: ExecutorContext, projectRoot: string, options?: DeployDevSessionOptions): Promise<void>;
 /**
- * Ensures a local runtime bot is selected or created and persisted to .botonic.json.
- * Call this after ensureHubtypeLoginBeforeTunnel and before starting the tunnel, so bot detection runs after login but before tunnel setup.
- * Does not log "Working as..." (already logged by ensureHubtypeLoginBeforeTunnel).
+ * Ensures a bot is set: reuses one from bots.json registry, or prompts to select an existing
+ * deployed bot or create a new one. The selected bot must be deployed with botonic_v2 strategy before
+ * dev session registration will succeed — the user is informed of this requirement.
  */
-export declare function ensureLocalRuntimeBotBeforeTunnel(context: ExecutorContext, projectRoot: string, options?: PerformDeployLocalRuntimeOptions): Promise<void>;
-/**
- * Writes the local runtime bot to .botonic.json in the app folder so the created bot is persisted per project.
- */
-export declare function writeLocalRuntimeBotToAppFolder(projectRoot: string, bot: BotDetail): void;
-/**
- * Removes the app folder .botonic.json so the next run will prompt to create/select a new bot (e.g. after 404 when bot was deleted).
- */
-export declare function removeAppBotonicJson(projectRoot: string): void;
-export declare function ensureLocalRuntimeBot(botonicApiService: BotonicAPIService): Promise<void>;
+export declare function ensureBot(botonicApiService: BotonicAPIService): Promise<void>;
 export type ProviderAccountListItem = {
     id: string;
     provider?: string;
@@ -78,26 +67,66 @@ export type ProviderAccountListItem = {
     is_active?: boolean;
 };
 /**
- * APP_ID for local runtime must be the webchat test provider — not WhatsApp
+ * Returns the imp_id of the first active real (non-test) webchat PA on the bot.
+ * Used by serve to auto-write VITE_HUBTYPE_APP_ID so the local widget connects.
+ */
+export declare function getActiveWebchatProviderAppId(results: ProviderAccountListItem[] | undefined): string | undefined;
+/**
+ * APP_ID for the dev session must be the webchat test provider — not WhatsApp
  * or other channels, which may also be test+active on the same bot.
  */
 export declare function getActiveTestWebchatProviderAppId(results: ProviderAccountListItem[] | undefined): string | undefined;
-export interface PerformDeployLocalRuntimeOptions {
+export interface DeployDevSessionOptions {
     email?: string;
     password?: string;
     env?: Record<string, unknown>;
     /** Explicit configuration name (e.g. 'dev') so deploy uses the right environment when Nx does not merge config. */
     configuration?: string;
+    /** E.164 phone number to register for WhatsApp local routing (e.g. +34612345678). */
+    whatsappPhone?: string;
+    /** Bot id pre-selected by selectBotForServe — skips ensureBot lookup so the correct bot is used. */
+    selectedBotId?: string;
 }
-export interface PerformDeployLocalRuntimeResult {
+export interface DeployDevSessionResult {
     botId: string;
+    apiUrl: string;
+    accessToken: string;
+    refreshToken: string;
+    clientId: string;
     targetEnvironment: string;
     environmentVariables: Record<string, unknown>;
+    lambdaFunctionName: string | undefined;
+    teardownWebchat: () => Promise<void>;
 }
 /**
- * Performs deploy_local_runtime with the given endpoint (e.g. tunnel URL).
- * Handles auth, bot creation/selection, and deploy. Returns the bot id and env for later cleanup (e.g. deleteBot on shutdown).
+ * Registers a dev session with the given tunnel endpoint.
+ * Handles auth, bot creation/selection, and registration. Returns the bot id and env.
  * Used by serve-bot (tunnel is always on).
  */
-export declare function performDeployLocalRuntimeWithEndpoint(context: ExecutorContext, projectRoot: string, endpoint: string, options?: PerformDeployLocalRuntimeOptions): Promise<PerformDeployLocalRuntimeResult>;
+export declare function performDeployLocalRuntimeWithEndpoint(context: ExecutorContext, projectRoot: string, endpoint: string, options?: DeployDevSessionOptions): Promise<DeployDevSessionResult>;
+/**
+ * Always prompts the user to select or create a bot for local development.
+ * Pre-selects the previously used bot (from registry). When botName is provided,
+ * skips the prompt entirely. For newly created bots, auto-deploys before returning
+ * so the serve flow can proceed without manual intervention.
+ *
+ * Must be called before tunnel startup so that auto-deploys don't waste tunnel
+ * resources and the selected bot is saved to the registry for
+ * performDeployLocalRuntimeWithEndpoint to load.
+ */
+export declare function selectBotForServe(context: ExecutorContext, projectRoot: string, options?: DeployDevSessionOptions & {
+    botName?: string;
+}): Promise<string | undefined>;
+export declare function isBotDeployedRestartRequired(error: unknown): boolean;
+/**
+ * Returns true if the currently selected bot (last entry in bots.json for the
+ * given env) has an active WhatsApp provider. Used by the serve executor to
+ * decide whether to enable the WhatsApp dev panel.
+ */
+export declare function selectedBotHasActiveWhatsapp(botId: string): boolean;
+/**
+ * Builds the bot and deploys it to Hubtype Cloud. Shared by the deploy executor
+ * and the serve executor's auto-deploy path for newly created bots.
+ */
+export declare function deployBotToHubtype(botonicApiService: BotonicAPIService, projectRoot: string, projectName: string): Promise<void>;
 export {};

package/src/executors/deploy-local-runtime/executor.d.ts

@@ -1,5 +0,0 @@
-import type { ExecutorContext } from '@nx/devkit';
-import type { DeployLocalRuntimeExecutorSchema } from './schema';
-export default function deployLocalRuntimeExecutor(options: DeployLocalRuntimeExecutorSchema, context: ExecutorContext): Promise<{
-    success: boolean;
-}>;

package/src/executors/deploy-local-runtime/executor.js

@@ -1,148 +0,0 @@
-"use strict";
-var __create = Object.create;
-var __defProp = Object.defineProperty;
-var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
-var __getOwnPropNames = Object.getOwnPropertyNames;
-var __getProtoOf = Object.getPrototypeOf;
-var __hasOwnProp = Object.prototype.hasOwnProperty;
-var __export = (target, all) => {
-  for (var name in all)
-    __defProp(target, name, { get: all[name], enumerable: true });
-};
-var __copyProps = (to, from, except, desc) => {
-  if (from && typeof from === "object" || typeof from === "function") {
-    for (let key of __getOwnPropNames(from))
-      if (!__hasOwnProp.call(to, key) && key !== except)
-        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
-  }
-  return to;
-};
-var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
-  // If the importer is in node compatibility mode or this is not an ESM
-  // file that has been converted to a CommonJS file using a Babel-
-  // compatible transform (i.e. "__esModule" has not been set), then set
-  // "default" to the CommonJS "module.exports" for node compatibility.
-  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
-  mod
-));
-var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
-var executor_exports = {};
-__export(executor_exports, {
-  default: () => deployLocalRuntimeExecutor
-});
-module.exports = __toCommonJS(executor_exports);
-var import_enquirer = require("enquirer");
-var fs = __toESM(require("fs"));
-var path = __toESM(require("path"));
-var import_lib = require("../../lib");
-var import_api_service = require("../../lib/api-service");
-var import_executor_helpers = require("../../lib/util/executor-helpers");
-async function deployLocalRuntimeExecutor(options, context) {
-  const projectRoot = (0, import_executor_helpers.resolveProjectPath)(context);
-  try {
-    const { targetEnvironment, environmentVariables } = (0, import_executor_helpers.resolveHubtypeEnvironment)(context, options);
-    const botonicApiService = new import_api_service.BotonicAPIService({
-      isLocalRuntimeDeployment: true,
-      projectRoot,
-      workspaceRoot: path.resolve(context.root),
-      environmentVariables,
-      targetEnvironment
-    });
-    if (!botonicApiService.oauth) {
-      if (options.email && options.password) {
-        await botonicApiService.login(options.email, options.password);
-        botonicApiService.saveAllCredentials();
-      } else {
-        await (0, import_executor_helpers.handleAuthentication)(botonicApiService);
-      }
-    }
-    await (0, import_executor_helpers.logWorkingAsAndEnvironment)(botonicApiService);
-    console.log(
-      `\u{1F680} Deploying to Hubtype Local Runtime...[${environmentVariables["VITE_HUBTYPE_API_URL"]}]
-`
-    );
-    await (0, import_executor_helpers.ensureLocalRuntimeBot)(botonicApiService);
-    const lambdaFunctionName = options.lambdaFunctionName || environmentVariables["VITE_HUBTYPE_LAMBDA_FUNCTION_NAME"];
-    const lambdaEndpoint = options.lambdaEndpoint || environmentVariables["VITE_HUBTYPE_LOCAL_LAMBDA_ENDPOINT"];
-    await deployLocalRuntime(botonicApiService, projectRoot, {
-      lambdaFunctionName,
-      lambdaEndpoint
-    });
-    return { success: true };
-  } catch (error) {
-    return (0, import_executor_helpers.handleExecutorError)(error, "Local runtime deployment");
-  }
-}
-function updateEnvLocal(projectRoot, appId) {
-  const envLocalPath = path.join(projectRoot, ".env.local");
-  const envKey = "VITE_HUBTYPE_APP_ID";
-  try {
-    if (fs.existsSync(envLocalPath)) {
-      let content = fs.readFileSync(envLocalPath, "utf-8");
-      const regex = new RegExp(`^${envKey}=.*$`, "m");
-      if (regex.test(content)) {
-        content = content.replace(regex, `${envKey}=${appId}`);
-        console.log(`\u{1F4DD} Updated ${envKey} in .env.local`);
-      } else {
-        content = content.trimEnd() + `
-${envKey}=${appId}
-`;
-        console.log(`\u{1F4DD} Added ${envKey} to .env.local`);
-      }
-      fs.writeFileSync(envLocalPath, content);
-    } else {
-      const content = `# HUBTYPE
-${envKey}=${appId}
-`;
-      fs.writeFileSync(envLocalPath, content);
-      console.log(`\u{1F4DD} Created .env.local with ${envKey}`);
-    }
-  } catch (error) {
-    console.warn(`\u26A0\uFE0F  Could not update .env.local: ${error}`);
-    console.log(`\u{1F194} Manually add to .env.local: ${envKey}=${appId}`);
-  }
-}
-async function deployLocalRuntime(botonicApiService, projectRoot, params) {
-  console.log("\u{1F528} Generating bot config for local runtime deployment...\n");
-  const botConfigJson = await import_lib.BotConfig.get(projectRoot);
-  let { lambdaEndpoint } = params;
-  if (!lambdaEndpoint) {
-    const response = await (0, import_enquirer.prompt)({
-      type: "input",
-      name: "lambda_endpoint",
-      message: "\u{1F310} Local runtime URL (e.g. http://localhost:3001):",
-      validate: (input) => {
-        try {
-          new URL(input);
-          return true;
-        } catch {
-          return "Please enter a valid URL";
-        }
-      }
-    });
-    lambdaEndpoint = response.lambda_endpoint;
-  }
-  console.log("\u{1F680} Deploying to Hubtype Local Runtime...");
-  try {
-    await botonicApiService.deployLocalRuntime({
-      botConfigJson,
-      lambdaFunctionName: params.lambdaFunctionName,
-      lambdaEndpoint
-    });
-    const allProviders = await botonicApiService.getProviders();
-    const appId = (0, import_executor_helpers.getActiveTestWebchatProviderAppId)(allProviders.data?.results);
-    if (!appId) {
-      console.error(
-        "\u274C No active test webchat provider found. Local runtime needs a webchat test provider on this bot."
-      );
-    } else {
-      console.log("\u2705 Local runtime deployment completed!");
-      updateEnvLocal(projectRoot, appId);
-      console.log(`\u{1F194} APP_ID: ${appId}`);
-    }
-  } catch (error) {
-    console.error("\u274C Local runtime deployment failed");
-    console.error(`${String(error)}`);
-  }
-  botonicApiService.saveAllCredentials();
-}

package/src/executors/deploy-local-runtime/schema.json

@@ -1,34 +0,0 @@
-{
-  "$schema": "http://json-schema.org/schema",
-  "$id": "DeployLocalRuntimeExecutor",
-  "title": "Deploy to Hubtype Local Runtime executor",
-  "type": "object",
-  "properties": {
-    "configuration": {
-      "type": "string",
-      "enum": ["local"],
-      "description": "Environment to deploy to"
-    },
-    "command": {
-      "type": "string",
-      "description": "Command to execute from the package scripts object"
-    },
-    "email": {
-      "type": "string",
-      "description": "Email from Hubtype Organization"
-    },
-    "password": {
-      "type": "string",
-      "description": "Password from Hubtype Organization"
-    },
-    "lambdaFunctionName": {
-      "type": "string",
-      "description": "Name of the Lambda function for the local runtime. Falls back to VITE_HUBTYPE_LAMBDA_FUNCTION_NAME or prompts if missing."
-    },
-    "lambdaEndpoint": {
-      "type": "string",
-      "description": "URL where the local runtime is reachable (e.g. http://localhost:3001). Falls back to VITE_HUBTYPE_LOCAL_LAMBDA_ENDPOINT env or prompts if missing."
-    }
-  },
-  "additionalProperties": false
-}