@mondaydotcomorg/z2h-cli 0.32.2 → 0.33.1

package/dist/esm/commands/deploy.mjs

@@ -142,6 +142,9 @@ async function deployPreview({ paths, consumerName, appName, token, opts }) {
         entry,
         gitRemote: '',
         isPreview: true,
+        // The base app this preview is for — bigbrain-zth links the preview's row
+        // to it (once the caller's EDITOR access on it is confirmed) so custom
+        // integrations set on the base app are inherited by the preview.
         masterAppName: appName,
     });
     const previewUrl = `https://bigbrain.me/bigbrain-vibe/${previewSlug}`;

package/dist/esm/index.mjs

@@ -9,6 +9,7 @@ import { cleanCommand } from './commands/clean.mjs';
 import { deployCommand } from './commands/deploy.mjs';
 import { deleteCommand } from './commands/delete.mjs';
 import { grantCommand, revokeCommand, transferOwnerCommand } from './commands/grant.mjs';
+import { listCustomIntegrationsCommand, removeCustomIntegrationCommand } from './commands/custom-integrations.mjs';
 import { createWorkspaceCommand } from './commands/create-workspace.mjs';
 import { createCommand } from './commands/create.mjs';
 import { generateCommand } from './commands/generate.mjs';
@@ -164,6 +165,14 @@ async function main() {
         .command('transfer-owner [email]')
         .description('Transfer ownership of the current app to another monday.com user')
         .action(runCommand({}, (email) => transferOwnerCommand(email)));
+    program
+        .command('custom-integration:list')
+        .description("List the current app's registered custom integrations (never shows the PAT)")
+        .action(runCommand({}, () => listCustomIntegrationsCommand()));
+    program
+        .command('custom-integration:remove <name>')
+        .description('Remove a registered custom integration from the current app')
+        .action(runCommand({}, (name) => removeCustomIntegrationCommand(name)));
     program
         .command('delete')
         .description('Permanently delete the current app and take it offline (owners/admins only)')
@@ -171,15 +180,18 @@ async function main() {
         .action(runCommand({ data: cwdApp }, (opts) => deleteCommand(opts)));
     const backend = program
         .command('backend')
-        .description("Inspect the app's backend: validate handler sources or invoke a deployed handler by name");
+        .description("Inspect the app's backend: validate handler sources or run a handler from the working tree");
     backend
         .command('validate')
         .description('Validate backend/handlers/*.js exactly as deploy would (syntax, isolate rules, integrations) without uploading')
         .action(runCommand({ data: cwdApp }, () => backendValidateCommand()));
     backend
         .command('invoke <handlerName>')
-        .description('Invoke a deployed backend handler by name (the filename without .ts) — mainly for testing a handler without going through the frontend')
-        .option('--input <json>', 'JSON payload passed as ctx.input')
+        .description("Run backend/handlers/<handlerName>.js from the working tree — not the deployed handler — against the app's real " +
+        'channels (real db data, real monday calls), and print a trace of every channel call and the ' +
+        'result. Nothing is deployed. Exits 1 when the handler fails.')
+        .option('--input <json>', 'JSON passed to the handler as ctx.input (what the frontend would send)')
+        .option('--code <source>', 'run this source instead of backend/handlers/<handlerName>.js — <handlerName> is then just a label')
         .action(runCommand({
         data: ([handlerName]) => ({ app_name: getCwdAppName(), handler: handlerName }),
     }, (handlerName, opts) => backendInvokeCommand(handlerName, opts)));
@@ -206,7 +218,9 @@ void main()
     if (getOutputMode() === 'human') {
         selfUpdate();
     }
-    process.exit(0);
+    // A command can finish normally and still report a non-zero code (e.g.
+    // `backend invoke` when the handler failed) via process.exitCode.
+    process.exit(process.exitCode ?? 0);
 })
     .catch(async (err) => {
     const errorMsg = err instanceof Error ? err.message : String(err);

package/dist/esm/util/app-name.mjs

@@ -27,7 +27,7 @@ function mfAppName(name) {
 // Names reserved by the host MF (mf-bigbrain-zth) for platform pages under
 // /bigbrain-vibe/<name>. Creating an app with one of these would shadow the
 // platform page in the URL, so we refuse upfront.
-const RESERVED_APP_NAMES = new Set(['generate-z2h-token']);
+const RESERVED_APP_NAMES = new Set(['generate-z2h-token', 'set-custom-integration']);
 /**
  * Validates a de-scoped, kebab-case app name against every rule shared by
  * `create` and `deploy` (incl. `deploy --preview`) — pattern, reserved

package/dist/esm/util/broker/app.d.ts

@@ -30,7 +30,10 @@ export interface RegisterOrUpdateOptions {
     gitRemote: string;
     integrations?: string[];
     description?: string;
-    /** For a preview app's first registration, the real app it previews. Ignored past v1. */
+    /**
+     * The base app a preview is for, sent only on first registration — the link
+     * is set once and is immutable thereafter, so a later update doesn't need it.
+     */
     masterAppName?: string;
 }
 /**

package/dist/esm/util/broker/app.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"app.d.ts","sourceRoot":"","sources":["../../../../src/util/broker/app.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAEjD,MAAM,WAAW,OAAO;IACtB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,0FAA0F;IAC1F,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IACtC,uGAAuG;IACvG,QAAQ,EAAE,OAAO,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;GAGG;AACH,wBAAsB,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC,CAsBvE;AAED;;;;;GAKG;AACH,wBAAsB,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAWhF;AA6CD,MAAM,WAAW,uBAAuB;IACtC,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,aAAa,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,yFAAyF;IACzF,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;;;;GAKG;AACH,wBAAsB,mBAAmB,CAAC,IAAI,EAAE,uBAAuB,GAAG,OAAO,CAAC,IAAI,CAAC,CA2BtF"}
+{"version":3,"file":"app.d.ts","sourceRoot":"","sources":["../../../../src/util/broker/app.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAEjD,MAAM,WAAW,OAAO;IACtB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,0FAA0F;IAC1F,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IACtC,uGAAuG;IACvG,QAAQ,EAAE,OAAO,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;GAGG;AACH,wBAAsB,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC,CAsBvE;AAED;;;;;GAKG;AACH,wBAAsB,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAWhF;AA6CD,MAAM,WAAW,uBAAuB;IACtC,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,aAAa,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;;;;GAKG;AACH,wBAAsB,mBAAmB,CAAC,IAAI,EAAE,uBAAuB,GAAG,OAAO,CAAC,IAAI,CAAC,CA2BtF"}

package/dist/index.js

@@ -9,6 +9,7 @@ const commands_clean = require('./commands/clean.js');
 const commands_deploy = require('./commands/deploy.js');
 const commands_delete = require('./commands/delete.js');
 const commands_grant = require('./commands/grant.js');
+const commands_customIntegrations = require('./commands/custom-integrations.js');
 const commands_createWorkspace = require('./commands/create-workspace.js');
 const commands_create = require('./commands/create.js');
 const commands_generate = require('./commands/generate.js');
@@ -170,6 +171,14 @@ async function main() {
         .command('transfer-owner [email]')
         .description('Transfer ownership of the current app to another monday.com user')
         .action(util_runCommand.runCommand({}, (email) => commands_grant.transferOwnerCommand(email)));
+    program
+        .command('custom-integration:list')
+        .description("List the current app's registered custom integrations (never shows the PAT)")
+        .action(util_runCommand.runCommand({}, () => commands_customIntegrations.listCustomIntegrationsCommand()));
+    program
+        .command('custom-integration:remove <name>')
+        .description('Remove a registered custom integration from the current app')
+        .action(util_runCommand.runCommand({}, (name) => commands_customIntegrations.removeCustomIntegrationCommand(name)));
     program
         .command('delete')
         .description('Permanently delete the current app and take it offline (owners/admins only)')
@@ -177,15 +186,18 @@ async function main() {
         .action(util_runCommand.runCommand({ data: cwdApp }, (opts) => commands_delete.deleteCommand(opts)));
     const backend = program
         .command('backend')
-        .description("Inspect the app's backend: validate handler sources or invoke a deployed handler by name");
+        .description("Inspect the app's backend: validate handler sources or run a handler from the working tree");
     backend
         .command('validate')
         .description('Validate backend/handlers/*.js exactly as deploy would (syntax, isolate rules, integrations) without uploading')
         .action(util_runCommand.runCommand({ data: cwdApp }, () => commands_backend.backendValidateCommand()));
     backend
         .command('invoke <handlerName>')
-        .description('Invoke a deployed backend handler by name (the filename without .ts) — mainly for testing a handler without going through the frontend')
-        .option('--input <json>', 'JSON payload passed as ctx.input')
+        .description("Run backend/handlers/<handlerName>.js from the working tree — not the deployed handler — against the app's real " +
+        'channels (real db data, real monday calls), and print a trace of every channel call and the ' +
+        'result. Nothing is deployed. Exits 1 when the handler fails.')
+        .option('--input <json>', 'JSON passed to the handler as ctx.input (what the frontend would send)')
+        .option('--code <source>', 'run this source instead of backend/handlers/<handlerName>.js — <handlerName> is then just a label')
         .action(util_runCommand.runCommand({
         data: ([handlerName]) => ({ app_name: util_appName.getCwdAppName(), handler: handlerName }),
     }, (handlerName, opts) => commands_backend.backendInvokeCommand(handlerName, opts)));
@@ -212,7 +224,9 @@ void main()
     if (util_logger.getOutputMode() === 'human') {
         selfUpdate();
     }
-    process.exit(0);
+    // A command can finish normally and still report a non-zero code (e.g.
+    // `backend invoke` when the handler failed) via process.exitCode.
+    process.exit(process.exitCode ?? 0);
 })
     .catch(async (err) => {
     const errorMsg = err instanceof Error ? err.message : String(err);

package/dist/util/app-name.js

@@ -29,7 +29,7 @@ function mfAppName(name) {
 // Names reserved by the host MF (mf-bigbrain-zth) for platform pages under
 // /bigbrain-vibe/<name>. Creating an app with one of these would shadow the
 // platform page in the URL, so we refuse upfront.
-const RESERVED_APP_NAMES = new Set(['generate-z2h-token']);
+const RESERVED_APP_NAMES = new Set(['generate-z2h-token', 'set-custom-integration']);
 /**
  * Validates a de-scoped, kebab-case app name against every rule shared by
  * `create` and `deploy` (incl. `deploy --preview`) — pattern, reserved

package/dist/util/broker/app.d.ts

@@ -30,7 +30,10 @@ export interface RegisterOrUpdateOptions {
     gitRemote: string;
     integrations?: string[];
     description?: string;
-    /** For a preview app's first registration, the real app it previews. Ignored past v1. */
+    /**
+     * The base app a preview is for, sent only on first registration — the link
+     * is set once and is immutable thereafter, so a later update doesn't need it.
+     */
     masterAppName?: string;
 }
 /**

package/dist/util/broker/app.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"app.d.ts","sourceRoot":"","sources":["../../../src/util/broker/app.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAEjD,MAAM,WAAW,OAAO;IACtB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,0FAA0F;IAC1F,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IACtC,uGAAuG;IACvG,QAAQ,EAAE,OAAO,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;GAGG;AACH,wBAAsB,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC,CAsBvE;AAED;;;;;GAKG;AACH,wBAAsB,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAWhF;AA6CD,MAAM,WAAW,uBAAuB;IACtC,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,aAAa,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,yFAAyF;IACzF,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;;;;GAKG;AACH,wBAAsB,mBAAmB,CAAC,IAAI,EAAE,uBAAuB,GAAG,OAAO,CAAC,IAAI,CAAC,CA2BtF"}
+{"version":3,"file":"app.d.ts","sourceRoot":"","sources":["../../../src/util/broker/app.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAEjD,MAAM,WAAW,OAAO;IACtB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,0FAA0F;IAC1F,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IACtC,uGAAuG;IACvG,QAAQ,EAAE,OAAO,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;GAGG;AACH,wBAAsB,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC,CAsBvE;AAED;;;;;GAKG;AACH,wBAAsB,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAWhF;AA6CD,MAAM,WAAW,uBAAuB;IACtC,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,aAAa,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;;;;GAKG;AACH,wBAAsB,mBAAmB,CAAC,IAAI,EAAE,uBAAuB,GAAG,OAAO,CAAC,IAAI,CAAC,CA2BtF"}

package/handler-api/backend-runner/backend-runner.errors.ts

@@ -39,6 +39,7 @@ export class BackendNotFoundError extends BackendRunnerError {
  * traces, SQL text, or upstream error payloads.
  */
 export interface ChannelErrorDetails {
+  /** Which integration was at fault — an OAuth one (`monday`) or a custom PAT connection name (e.g. `stripe`); `code` tells you which. */
   integration?: string;
 }
 
@@ -53,3 +54,15 @@ export class ChannelError extends BackendRunnerError {
     this.name = 'ChannelError';
   }
 }
+
+/**
+ * A sandbox run request the runner refuses before any code runs — the code is
+ * unusable or the app doesn't exist. Carries a `code` so
+ * the CLI can say exactly which, the same way a channel error does.
+ */
+export class SandboxRequestError extends BackendRunnerError {
+  constructor(statusCode: number, message: string, public readonly code: string) {
+    super(statusCode, message);
+    this.name = 'SandboxRequestError';
+  }
+}

package/handler-api/backend-runner/backend-runner.types.ts

@@ -34,6 +34,9 @@ export type ChannelHandler = (args: unknown[]) => Promise<unknown> | unknown;
  */
 export type ChannelMap = Record<string, ChannelHandler>;
 
+/** Which path built the channels — a deployed handler (`invoke`) or source sent to the sandbox. Tags channel telemetry. */
+export type RunMode = 'invoke' | 'sandbox';
+
 /**
  * A breakdown of where the isolate wall-clock went, in ms. Lets us see whether a
  * slow invoke is the V8 setup (create + compile) or the guest's own work + its

package/handler-api/backend-runner/channels/channel-map.ts

@@ -1,16 +1,24 @@
 import { logger } from '@mondaydotcomorg/trident-backend-runtime';
 
 import { withChannelTelemetry } from './channel-telemetry';
+import { makeCustomIntegrationChannel } from './custom-integration-channel/custom-integration.channel';
 import { makeDbChannel } from './db-channel/db.channel';
 import { makeLlmChannel } from './llm-channel/llm.channel';
 import { makeMondayChannel } from './monday-channel/monday.channel';
 import { makeSnowflakeChannel } from './snowflake-channel/snowflake.channel';
-import type { Caller, ChannelMap } from '../backend-runner.types';
+import type { Caller, ChannelMap, RunMode } from '../backend-runner.types';
+import type { RunnerCustomIntegration } from '../runner-data.store';
 
 const OAUTH_CHANNELS: Record<string, (caller: Caller) => ChannelMap> = {
   monday: (caller) => makeMondayChannel(caller),
 };
 
+/**
+ * Every integration with a registered channel. Sandbox runs build all of them —
+ * safe because each fetches the caller's token only when a method is called.
+ */
+export const OAUTH_INTEGRATIONS = Object.keys(OAUTH_CHANNELS);
+
 /**
  * Builds the complete channel surface for one invocation — the only way out of
  * the isolate.
@@ -39,8 +47,11 @@ const OAUTH_CHANNELS: Record<string, (caller: Caller) => ChannelMap> = {
  *
  * ## Always-on vs declared
  *
- * - **Always on** — `db`, `snowflake`, `llm`. No user setup, no OAuth, nothing to
- *   declare. Every app gets them.
+ * - **Always on** — `db`, `snowflake`, `llm`, `customIntegration`. No user setup,
+ *   no OAuth, nothing to declare. Every app gets them. `customIntegration` is a
+ *   generic PAT-authenticated HTTP proxy — the connection `name` a handler
+ *   passes is a runtime dispatch argument, resolved against whatever the app
+ *   registered for itself, not a manifest declaration.
  * - **Declared** — everything in {@link OAUTH_CHANNELS} (currently just `monday`).
  *   These need a per-user OAuth token, so the app must list the integration in its
  *   manifest *and* the running user must have connected it. Undeclared means the
@@ -58,14 +69,21 @@ const OAUTH_CHANNELS: Record<string, (caller: Caller) => ChannelMap> = {
  * setup) is wrong and retrying won't help; `502` means the upstream failed.
  *
  * Each key emits a unified call counter, duration distribution, and BI event tagged
- * by app, channel, method, and outcome. Uncaught failures also reach BI at the
+ * by app, mode (`invoke` or `sandbox`), channel, method, and outcome. Uncaught failures also reach BI at the
  * invocation level — see `runner.service.ts`.
  */
-export function buildChannels(appName: string, caller: Caller, declaredIntegrations: string[]): ChannelMap {
+export function buildChannels(
+  appName: string,
+  caller: Caller,
+  declaredIntegrations: string[],
+  customIntegrations: RunnerCustomIntegration[],
+  mode: RunMode,
+): ChannelMap {
   const channels: ChannelMap = {
     ...makeDbChannel(appName),
     ...makeSnowflakeChannel(appName),
     ...makeLlmChannel(appName, caller),
+    ...makeCustomIntegrationChannel(appName, customIntegrations),
   };
 
   for (const integration of declaredIntegrations) {
@@ -80,5 +98,7 @@ export function buildChannels(appName: string, caller: Caller, declaredIntegrati
     }
   }
 
-  return Object.fromEntries(Object.entries(channels).map(([key, fn]) => [key, withChannelTelemetry(appName, key, fn)]));
+  return Object.fromEntries(
+    Object.entries(channels).map(([key, fn]) => [key, withChannelTelemetry(appName, mode, key, fn)]),
+  );
 }

package/handler-api/backend-runner/channels/channel-telemetry.ts

@@ -3,8 +3,8 @@ import { BackendRunnerEvents } from '@mondaydotcomorg/z2h-shared-utils/observabi
 import { trackEvent } from '@mondaydotcomorg/z2h-shared-utils/observability/trident';
 
 import { ChannelError } from '../backend-runner.errors';
-import type { ChannelHandler } from '../backend-runner.types';
 import { BI_SOURCE } from '../constants';
+import type { ChannelHandler, RunMode } from '../backend-runner.types';
 
 type ChannelOutcome = 'success' | 'failure';
 
@@ -26,6 +26,7 @@ function isPromiseLike(value: unknown): value is PromiseLike<unknown> {
 
 function recordChannelCall(
   appName: string,
+  mode: RunMode,
   channel: string,
   method: string,
   outcome: ChannelOutcome,
@@ -33,7 +34,7 @@ function recordChannelCall(
   error?: unknown,
 ): void {
   const durationMs = performance.now() - startedAt;
-  const dimensions = { appName, channel, method };
+  const dimensions = { appName, mode, channel, method };
 
   metric.increment(BackendRunnerEvents.channel.callMetric, { ...dimensions, outcome });
   metric.distribution(BackendRunnerEvents.channel.durationMetric, durationMs, dimensions);
@@ -49,7 +50,12 @@ function recordChannelCall(
   );
 }
 
-export function withChannelTelemetry(appName: string, key: string, handler: ChannelHandler): ChannelHandler {
+export function withChannelTelemetry(
+  appName: string,
+  mode: RunMode,
+  key: string,
+  handler: ChannelHandler,
+): ChannelHandler {
   const { channel, method } = parseChannelKey(key);
 
   return (args) => {
@@ -59,20 +65,20 @@ export function withChannelTelemetry(appName: string, key: string, handler: Chan
       if (isPromiseLike(result)) {
         return Promise.resolve(result).then(
           (value) => {
-            recordChannelCall(appName, channel, method, 'success', startedAt);
+            recordChannelCall(appName, mode, channel, method, 'success', startedAt);
             return value;
           },
           (error: unknown) => {
-            recordChannelCall(appName, channel, method, 'failure', startedAt, error);
+            recordChannelCall(appName, mode, channel, method, 'failure', startedAt, error);
             throw error;
           },
         );
       }
 
-      recordChannelCall(appName, channel, method, 'success', startedAt);
+      recordChannelCall(appName, mode, channel, method, 'success', startedAt);
       return result;
     } catch (error) {
-      recordChannelCall(appName, channel, method, 'failure', startedAt, error);
+      recordChannelCall(appName, mode, channel, method, 'failure', startedAt, error);
       throw error;
     }
   };

package/handler-api/backend-runner/channels/channel-trace.ts

@@ -0,0 +1,52 @@
+import { ChannelError } from '../backend-runner.errors';
+import type { ChannelHandler, ChannelMap } from '../backend-runner.types';
+
+/**
+ * One channel call as the sandbox reports it back to the author. Raw args are
+ * recorded — for `snowflake.query` that is the SQL text and its params, not the
+ * bound SQL the channel builds from them.
+ */
+export interface ChannelCallTrace {
+  method: string;
+  args: unknown[];
+  durationMs: number;
+  ok: boolean;
+  /** Why the call failed — same shape as the run's `error`. A non-`ChannelError` is a 500 with no code. */
+  error?: { status: number; code?: string; message: string };
+  /** What the channel returned to the handler, as-is — e.g. Snowflake rows or monday's GraphQL `data`. */
+  result?: unknown;
+}
+
+type CallOutcome = Pick<ChannelCallTrace, 'ok' | 'error' | 'result'>;
+
+function withChannelTrace(calls: ChannelCallTrace[], method: string, handler: ChannelHandler): ChannelHandler {
+  return async (args) => {
+    const startedAt = performance.now();
+    const record = (outcome: CallOutcome): void => {
+      calls.push({ method, args, durationMs: performance.now() - startedAt, ...outcome });
+    };
+
+    try {
+      const result = await handler(args);
+      record({ ok: true, result });
+      return result;
+    } catch (err) {
+      record({
+        ok: false,
+        error:
+          err instanceof ChannelError
+            ? { status: err.statusCode, code: err.code, message: err.message }
+            : { status: 500, message: err instanceof Error ? err.message : String(err) },
+      });
+      throw err;
+    }
+  };
+}
+
+/**
+ * Wraps every channel so each call is appended to `calls` in the order it
+ * finished. Sandbox-only: the deployed invoke path never records a trace.
+ */
+export function traceChannels(channels: ChannelMap, calls: ChannelCallTrace[]): ChannelMap {
+  return Object.fromEntries(Object.entries(channels).map(([key, fn]) => [key, withChannelTrace(calls, key, fn)]));
+}

package/handler-api/backend-runner/channels/custom-integration-channel/custom-integration.channel.ts

@@ -0,0 +1,243 @@
+import { httpClient } from '@mondaydotcomorg/trident-backend-runtime';
+import { decryptSecret } from '@mondaydotcomorg/z2h-shared-utils/secrets';
+
+import { ChannelError } from '../../backend-runner.errors';
+import { UPSTREAM_TIMEOUT_MS, withTimeout } from '../with-timeout';
+import type { RunnerCustomIntegration } from '../../runner-data.store';
+import type { ChannelMap } from '../../backend-runner.types';
+
+const ALLOWED_METHODS = ['GET', 'POST', 'PUT', 'PATCH', 'DELETE'] as const;
+type AllowedMethod = (typeof ALLOWED_METHODS)[number];
+
+interface CustomIntegrationRequestOptions {
+  url: string;
+  method?: string;
+  headers?: Record<string, string>;
+  body?: unknown;
+  query?: Record<string, string>;
+}
+
+function isRequestOptions(value: unknown): value is CustomIntegrationRequestOptions {
+  return !!value && typeof value === 'object' && typeof (value as { url?: unknown }).url === 'string';
+}
+
+/**
+ * The `customIntegration` channel — a generic, PAT-authenticated HTTP proxy for
+ * apps that connect to a third-party API by credential rather than OAuth (e.g.
+ * Stripe, an internal CRM). Distinct from `monday` (per-user OAuth token) and
+ * always-on like `db`/`snowflake`/`llm` — every app gets `ctx.api.v1.customIntegration`,
+ * and the connection `name` is a runtime dispatch argument rather than a
+ * manifest-declared channel.
+ *
+ * The handler supplies a URL, but only its path and query ever reach the
+ * upstream request — host and scheme are always the registered connection's:
+ *   1. Each named connection is pinned to one exact `allowedHost` at registration
+ *      time. The actual request is always built as `https://${allowedHost}${path}`,
+ *      so nothing in the handler-supplied URL — host, port, or scheme — can steer
+ *      the org's credential to an unintended host or send it over plaintext http.
+ *   2. The actual request goes through `httpClient.untrustedExternal.fetchRaw`,
+ *      never a raw fetch client — defense in depth against internal/private
+ *      targets and cloud metadata endpoints (SSRF).
+ *
+ * The auth header is always set by the host, last, after any handler-supplied
+ * headers — a handler can never override it, and the decrypted PAT never
+ * crosses into the isolate.
+ */
+export function makeCustomIntegrationChannel(appName: string, connections: RunnerCustomIntegration[]): ChannelMap {
+  return {
+    /**
+     * `ctx.api.v1.customIntegration.request(name, options)` — call a third-party
+     * API using a named, PAT-authenticated connection the app owner registered
+     * at `bigbrain.me/bigbrain-vibe/set-custom-integration`.
+     *
+     * The connection must already be registered — this channel does not create
+     * one, and there is no CLI command for it either: the PAT is entered only on
+     * that page, posted straight to the platform over the owner's own session,
+     * and never touches a terminal or an agent. The handler supplies the full
+     * request itself (URL, method, headers, body); the host looks up the named
+     * connection, decrypts its PAT, and injects it as the configured auth header
+     * (`Authorization: Bearer …` by default). The handler never sees the PAT,
+     * and cannot override the auth header even by supplying one with the same
+     * name.
+     *
+     * **Before registering, check the target API's real auth docs — do not
+     * assume `Authorization: Bearer`.** Many APIs use a different header (e.g.
+     * `x-api-key`, no scheme). Getting this wrong doesn't fail at registration —
+     * it fails later here, as an opaque `custom_integration_upstream_error` (502)
+     * wrapping a `401` from the upstream. Registration is browser-only — the PAT
+     * never touches a terminal or an agent — at
+     * `bigbrain.me/bigbrain-vibe/set-custom-integration`, where the host/header
+     * name/scheme are set (an empty scheme sends the raw token, no prefix).
+     * Before re-deriving the header/scheme from scratch, check what's already
+     * stored with `z2h-cli custom-integration:list` — always the base app; a
+     * preview has no connections of its own, see below.
+     *
+     * **Only the path and query of `options.url` are used** — the host and scheme
+     * are always the connection's registered `allowedHost`, over https, regardless
+     * of what you pass. Paste the full URL from the target API's docs for
+     * readability; the actual request always goes to the registered host. This is
+     * what keeps a credential scoped to the API it was meant for.
+     *
+     * **Previews:** a preview always uses its base app's connections, live,
+     * resolved fresh on every invoke — it can never register or remove its
+     * own. Registering (the page rejects a preview app name) or removing both
+     * reject with an error telling you to manage it on the base app instead.
+     * Change a connection there and every one of its previews picks it up
+     * immediately, no redeploy needed.
+     *
+     * @param name - The connection name it was registered under, e.g. `"stripe"`.
+     * @param options - `{ url, method?, headers?, body?, query? }`. Only `url`'s path and
+     *   query are used — its host and scheme are ignored; the request always goes to the
+     *   connection's registered host over https. `method` defaults to `"GET"` (one of GET,
+     *   POST, PUT, PATCH, DELETE). `headers` are optional extra headers — the auth header is
+     *   always set by the host afterward, so a header of that name here is ignored. `body` is
+     *   forwarded as-is. `query` params are merged into the URL.
+     * @returns `{ status, headers, body }` — `body` is JSON-parsed when the response is JSON, otherwise the raw text. The response never includes the auth header, even if the upstream reflects it back.
+     *
+     * @throws `custom_integration_not_found` (404) — no connection with this name is registered for the app; register it at bigbrain.me/bigbrain-vibe/set-custom-integration first.
+     * @throws `custom_integration_invalid_argument` (400) — missing/malformed name, url, or method.
+     * @throws `custom_integration_upstream_error` (502) — the upstream request failed or returned a non-2xx status.
+     *
+     * @example
+     * // A Stripe connection registered as "stripe" / api.stripe.com at bigbrain.me/bigbrain-vibe/set-custom-integration
+     * const res = await ctx.api.v1.customIntegration.request('stripe', {
+     *   url: 'https://api.stripe.com/v1/charges',
+     *   method: 'GET',
+     * });
+     * return res.body;
+     *
+     * @example
+     * // POST with a JSON body and an extra (non-auth) header
+     * await ctx.api.v1.customIntegration.request('acme-crm', {
+     *   url: 'https://api.acme-crm.example.com/v2/contacts',
+     *   method: 'POST',
+     *   headers: { 'Content-Type': 'application/json' },
+     *   body: { name: ctx.input.name, email: ctx.input.email },
+     * });
+     */
+    'customIntegration.request': async ([name, options]: unknown[]) => {
+      if (typeof name !== 'string' || !name) {
+        throw new ChannelError(
+          400,
+          'customIntegration.request requires a connection name as its first argument',
+          'custom_integration_invalid_argument',
+        );
+      }
+
+      const connection = connections.find((c) => c.name === name);
+      if (!connection) {
+        throw new ChannelError(
+          404,
+          `customIntegration: no connection named "${name}" is registered for app "${appName}"`,
+          'custom_integration_not_found',
+          { integration: name },
+        );
+      }
+
+      if (!isRequestOptions(options)) {
+        throw new ChannelError(
+          400,
+          'customIntegration.request requires { url, method?, headers?, body?, query? } as its second argument',
+          'custom_integration_invalid_argument',
+          { integration: name },
+        );
+      }
+
+      let requestedUrl: URL;
+      try {
+        requestedUrl = new URL(options.url);
+      } catch {
+        throw new ChannelError(
+          400,
+          `customIntegration.request: "${options.url}" is not a valid URL`,
+          'custom_integration_invalid_argument',
+          { integration: name },
+        );
+      }
+
+      // Only the path and query of the handler-supplied URL are used — host and
+      // scheme are always the registered connection's, over https, so no handler
+      // input can steer the PAT to an unintended host or send it over plaintext http.
+      // (Any fragment is dropped too, but that's moot — fragments never reach the
+      // wire in an HTTP request regardless of who builds the URL.)
+      const target = new URL(`https://${connection.allowedHost}${requestedUrl.pathname}${requestedUrl.search}`);
+
+      const method = (options.method ?? 'GET').toUpperCase();
+      if (!ALLOWED_METHODS.includes(method as AllowedMethod)) {
+        throw new ChannelError(
+          400,
+          `customIntegration.request: unsupported method "${options.method}"`,
+          'custom_integration_invalid_argument',
+          { integration: name },
+        );
+      }
+
+      let pat: string;
+      try {
+        pat = decryptSecret(connection.ciphertext);
+      } catch {
+        throw new ChannelError(
+          500,
+          `customIntegration: connection "${name}" could not be decrypted`,
+          'custom_integration_decrypt_failed',
+          { integration: name },
+        );
+      }
+
+      // Handler-supplied headers pass through, but the auth header is always
+      // set/overwritten host-side last — a handler can never inject, read, or
+      // override it, and it never crosses into the isolate.
+      const headers: Record<string, string> = { ...(options.headers ?? {}) };
+      const scheme = connection.authScheme ? `${connection.authScheme} ` : '';
+      headers[connection.authHeaderName] = `${scheme}${pat}`;
+
+      try {
+        const res = await withTimeout(
+          httpClient.untrustedExternal.fetchRaw({
+            url: target.toString(),
+            method: method as AllowedMethod,
+            headers,
+            body: options.body as never,
+            query: options.query,
+          }),
+          UPSTREAM_TIMEOUT_MS,
+          `customIntegration.request(${name})`,
+        );
+
+        const text = await res.text();
+        let body: unknown = text;
+        try {
+          body = text ? JSON.parse(text) : null;
+        } catch {
+          // Not JSON — return the raw text.
+        }
+
+        if (!res.ok) {
+          throw new ChannelError(
+            502,
+            `customIntegration: upstream returned ${res.status}`,
+            'custom_integration_upstream_error',
+            { integration: name },
+          );
+        }
+
+        // Strip the injected auth header from what crosses back to the handler —
+        // defense in depth in case the upstream ever reflects a request header
+        // back in its response (some APIs do this on error responses).
+        const responseHeaders = Object.fromEntries(res.headers.entries());
+        delete responseHeaders[connection.authHeaderName.toLowerCase()];
+        return { status: res.status, headers: responseHeaders, body };
+      } catch (err) {
+        if (err instanceof ChannelError) {
+          throw err;
+        }
+        throw new ChannelError(
+          502,
+          `customIntegration: request failed: ${err instanceof Error ? err.message : String(err)}`,
+          'custom_integration_upstream_error',
+          { integration: name },
+        );
+      }
+    },
+  } satisfies ChannelMap;
+}