@mondaydotcomorg/z2h-cli 0.32.2 → 0.33.0

package/dist/commands/__tests__/custom-integrations.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=custom-integrations.test.d.ts.map

package/dist/commands/__tests__/custom-integrations.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"custom-integrations.test.d.ts","sourceRoot":"","sources":["../../../src/commands/__tests__/custom-integrations.test.ts"],"names":[],"mappings":""}

package/dist/commands/custom-integrations.d.ts

@@ -0,0 +1,3 @@
+export declare function listCustomIntegrationsCommand(): Promise<void>;
+export declare function removeCustomIntegrationCommand(name: string | undefined): Promise<void>;
+//# sourceMappingURL=custom-integrations.d.ts.map

package/dist/commands/custom-integrations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"custom-integrations.d.ts","sourceRoot":"","sources":["../../src/commands/custom-integrations.ts"],"names":[],"mappings":"AAyBA,wBAAsB,6BAA6B,IAAI,OAAO,CAAC,IAAI,CAAC,CAsBnE;AAED,wBAAsB,8BAA8B,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC,CAkB5F"}

package/dist/commands/custom-integrations.js

@@ -0,0 +1,51 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+
+const util_logger = require('../util/logger.js');
+const util_appName = require('../util/app-name.js');
+const constants = require('../constants.js');
+const util_auth_authStore = require('../util/auth/auth-store.js');
+
+function getTargetAppName() {
+    const consumerName = util_appName.getCwdAppName();
+    if (!consumerName) {
+        throw new Error('Run this from inside a consumer app directory (the one with your package.json).');
+    }
+    return util_appName.mfAppName(consumerName);
+}
+async function listCustomIntegrationsCommand() {
+    const appName = getTargetAppName();
+    const { token } = await util_auth_authStore.readZthAuth();
+    const res = await fetch(`${constants.brokerBaseUrl()}/z2h-apps/${appName}/custom-integrations`, {
+        headers: { Authorization: `Bearer ${token}`, ...constants.routingHeaders() },
+    });
+    if (!res.ok) {
+        const text = await res.text();
+        throw new Error(`Listing custom integrations failed (${res.status}): ${text.slice(0, 1024)}`);
+    }
+    const { connections } = (await res.json());
+    if (connections.length === 0) {
+        util_logger.output(`[z2h-cli] "${appName}" has no custom integrations registered`, { ok: true, appName, connections: [] });
+        return;
+    }
+    const lines = connections.map(c => `  ${c.name}  →  ${c.allowedHost}  (${c.authHeaderName})${c.inherited ? '  [inherited from base app]' : ''}`);
+    util_logger.output(`[z2h-cli] "${appName}" custom integrations:\n${lines.join('\n')}`, { ok: true, appName, connections });
+}
+async function removeCustomIntegrationCommand(name) {
+    if (!name) {
+        throw new Error('Specify the connection name to remove — e.g. z2h-cli custom-integration:remove stripe');
+    }
+    const appName = getTargetAppName();
+    const { token } = await util_auth_authStore.readZthAuth();
+    const res = await fetch(`${constants.brokerBaseUrl()}/z2h-apps/${appName}/custom-integrations/${encodeURIComponent(name)}`, {
+        method: 'DELETE',
+        headers: { Authorization: `Bearer ${token}`, ...constants.routingHeaders() },
+    });
+    if (!res.ok) {
+        const text = await res.text();
+        throw new Error(`Removing custom integration failed (${res.status}): ${text.slice(0, 1024)}`);
+    }
+    util_logger.output(`[z2h-cli] custom integration "${name}" removed from "${appName}"`, { ok: true, appName, name });
+}
+
+exports.listCustomIntegrationsCommand = listCustomIntegrationsCommand;
+exports.removeCustomIntegrationCommand = removeCustomIntegrationCommand;

package/dist/commands/deploy.js

@@ -148,6 +148,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/commands/__tests__/custom-integrations.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=custom-integrations.test.d.ts.map

package/dist/esm/commands/__tests__/custom-integrations.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"custom-integrations.test.d.ts","sourceRoot":"","sources":["../../../../src/commands/__tests__/custom-integrations.test.ts"],"names":[],"mappings":""}

package/dist/esm/commands/custom-integrations.d.ts

@@ -0,0 +1,3 @@
+export declare function listCustomIntegrationsCommand(): Promise<void>;
+export declare function removeCustomIntegrationCommand(name: string | undefined): Promise<void>;
+//# sourceMappingURL=custom-integrations.d.ts.map

package/dist/esm/commands/custom-integrations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"custom-integrations.d.ts","sourceRoot":"","sources":["../../../src/commands/custom-integrations.ts"],"names":[],"mappings":"AAyBA,wBAAsB,6BAA6B,IAAI,OAAO,CAAC,IAAI,CAAC,CAsBnE;AAED,wBAAsB,8BAA8B,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC,CAkB5F"}

package/dist/esm/commands/custom-integrations.mjs

@@ -0,0 +1,48 @@
+import { output } from '../util/logger.mjs';
+import { getCwdAppName, mfAppName } from '../util/app-name.mjs';
+import { brokerBaseUrl, routingHeaders } from '../constants.mjs';
+import { readZthAuth } from '../util/auth/auth-store.mjs';
+
+function getTargetAppName() {
+    const consumerName = getCwdAppName();
+    if (!consumerName) {
+        throw new Error('Run this from inside a consumer app directory (the one with your package.json).');
+    }
+    return mfAppName(consumerName);
+}
+async function listCustomIntegrationsCommand() {
+    const appName = getTargetAppName();
+    const { token } = await readZthAuth();
+    const res = await fetch(`${brokerBaseUrl()}/z2h-apps/${appName}/custom-integrations`, {
+        headers: { Authorization: `Bearer ${token}`, ...routingHeaders() },
+    });
+    if (!res.ok) {
+        const text = await res.text();
+        throw new Error(`Listing custom integrations failed (${res.status}): ${text.slice(0, 1024)}`);
+    }
+    const { connections } = (await res.json());
+    if (connections.length === 0) {
+        output(`[z2h-cli] "${appName}" has no custom integrations registered`, { ok: true, appName, connections: [] });
+        return;
+    }
+    const lines = connections.map(c => `  ${c.name}  →  ${c.allowedHost}  (${c.authHeaderName})${c.inherited ? '  [inherited from base app]' : ''}`);
+    output(`[z2h-cli] "${appName}" custom integrations:\n${lines.join('\n')}`, { ok: true, appName, connections });
+}
+async function removeCustomIntegrationCommand(name) {
+    if (!name) {
+        throw new Error('Specify the connection name to remove — e.g. z2h-cli custom-integration:remove stripe');
+    }
+    const appName = getTargetAppName();
+    const { token } = await readZthAuth();
+    const res = await fetch(`${brokerBaseUrl()}/z2h-apps/${appName}/custom-integrations/${encodeURIComponent(name)}`, {
+        method: 'DELETE',
+        headers: { Authorization: `Bearer ${token}`, ...routingHeaders() },
+    });
+    if (!res.ok) {
+        const text = await res.text();
+        throw new Error(`Removing custom integration failed (${res.status}): ${text.slice(0, 1024)}`);
+    }
+    output(`[z2h-cli] custom integration "${name}" removed from "${appName}"`, { ok: true, appName, name });
+}
+
+export { listCustomIntegrationsCommand, removeCustomIntegrationCommand };

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)')

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)')

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;
 }
 

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

@@ -1,11 +1,13 @@
 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 { RunnerCustomIntegration } from '../runner-data.store';
 
 const OAUTH_CHANNELS: Record<string, (caller: Caller) => ChannelMap> = {
   monday: (caller) => makeMondayChannel(caller),
@@ -39,8 +41,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
@@ -61,11 +66,17 @@ const OAUTH_CHANNELS: Record<string, (caller: Caller) => ChannelMap> = {
  * by app, 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[],
+): ChannelMap {
   const channels: ChannelMap = {
     ...makeDbChannel(appName),
     ...makeSnowflakeChannel(appName),
     ...makeLlmChannel(appName, caller),
+    ...makeCustomIntegrationChannel(appName, customIntegrations),
   };
 
   for (const integration of declaredIntegrations) {

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 } from '../backend-runner.types';
 
 type ChannelOutcome = 'success' | 'failure';
 

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;
+}

package/handler-api/signatures.json

@@ -1,4 +1,8 @@
 {
+  "customIntegration.request": [
+    "name",
+    "options"
+  ],
   "db.delete": [
     "key"
   ],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mondaydotcomorg/z2h-cli",
-  "version": "0.32.2",
+  "version": "0.33.0",
   "bin": "./bin/z2h-cli.js",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -52,7 +52,7 @@
   "dependencies": {
     "@aws-sdk/client-s3": "^3.706.0",
     "@mondaydotcomorg/z2h-dashboard-templates": "^0.4.0",
-    "@mondaydotcomorg/z2h-shared-utils": "^0.6.2",
+    "@mondaydotcomorg/z2h-shared-utils": "^0.7.0",
     "acorn": "^8.14.0",
     "acorn-walk": "^8.3.4",
     "chokidar": "^3.6.0",

package/src/commands/__tests__/custom-integrations.test.ts

@@ -0,0 +1,62 @@
+import path from 'node:path';
+import os from 'node:os';
+import { mkdtemp, rm, remove, ensureDir, writeJson } from 'fs-extra';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { listCustomIntegrationsCommand, removeCustomIntegrationCommand } from '../custom-integrations';
+import * as authStore from '../../util/auth/auth-store';
+
+vi.spyOn(authStore, 'readZthAuth').mockResolvedValue({ token: 'jwt-stub' });
+
+function mockFetchOnce(status = 200, body: unknown = {}) {
+  const fetchMock = vi
+    .fn()
+    .mockResolvedValue({ ok: status < 400, status, text: async () => '', json: async () => body });
+  vi.stubGlobal('fetch', fetchMock);
+  return fetchMock;
+}
+
+describe('custom-integration commands — app-name resolution', () => {
+  let tmp: string;
+  let cwd: string;
+
+  beforeEach(async () => {
+    tmp = await mkdtemp(path.join(os.tmpdir(), 'z2h-custom-integration-'));
+    cwd = process.cwd();
+    process.chdir(tmp);
+    tmp = process.cwd();
+    await writeJson(path.join(tmp, 'package.json'), { name: 'my-app' });
+  });
+
+  afterEach(async () => {
+    process.chdir(cwd);
+    vi.unstubAllGlobals();
+    await rm(tmp, { recursive: true, force: true });
+  });
+
+  it('throws a clear error instead of crashing when run outside a consumer app directory', async () => {
+    await remove(path.join(tmp, 'package.json'));
+
+    await expect(listCustomIntegrationsCommand()).rejects.toThrow(/consumer app directory/);
+    await expect(removeCustomIntegrationCommand('stripe')).rejects.toThrow(/consumer app directory/);
+  });
+
+  it('targets the base app', async () => {
+    const fetchMock = mockFetchOnce(200, { connections: [] });
+
+    await listCustomIntegrationsCommand();
+
+    const [url] = fetchMock.mock.calls[0] as [string];
+    expect(url).toContain('/z2h-apps/mf-my-app/custom-integrations');
+  });
+
+  it('remove targets the base app', async () => {
+    await ensureDir(path.join(tmp, '.zth'));
+    const fetchMock = mockFetchOnce(204);
+
+    await removeCustomIntegrationCommand('stripe');
+
+    const [url] = fetchMock.mock.calls[0] as [string];
+    expect(url).toContain('/z2h-apps/mf-my-app/custom-integrations/stripe');
+  });
+});

package/src/commands/custom-integrations.ts

@@ -0,0 +1,68 @@
+import { output } from '../util/logger';
+import { getCwdAppName, mfAppName } from '../util/app-name';
+import { brokerBaseUrl, routingHeaders } from '../constants';
+import { readZthAuth } from '../util/auth/auth-store';
+
+function getTargetAppName(): string {
+  const consumerName = getCwdAppName();
+  if (!consumerName) {
+    throw new Error('Run this from inside a consumer app directory (the one with your package.json).');
+  }
+  return mfAppName(consumerName);
+}
+
+interface CustomIntegrationSummary {
+  name: string;
+  allowedHost: string;
+  authHeaderName: string;
+  authScheme: string;
+  createdBy: string;
+  createdAt: string;
+  updatedAt: string;
+  /** True when this is a preview showing an entry inherited from its base app, not its own. */
+  inherited?: boolean;
+}
+
+export async function listCustomIntegrationsCommand(): Promise<void> {
+  const appName = getTargetAppName();
+  const { token } = await readZthAuth();
+
+  const res = await fetch(`${brokerBaseUrl()}/z2h-apps/${appName}/custom-integrations`, {
+    headers: { Authorization: `Bearer ${token}`, ...routingHeaders() },
+  });
+  if (!res.ok) {
+    const text = await res.text();
+    throw new Error(`Listing custom integrations failed (${res.status}): ${text.slice(0, 1024)}`);
+  }
+
+  const { connections } = (await res.json()) as { connections: CustomIntegrationSummary[] };
+  if (connections.length === 0) {
+    output(`[z2h-cli] "${appName}" has no custom integrations registered`, { ok: true, appName, connections: [] });
+    return;
+  }
+
+  const lines = connections.map(
+    c => `  ${c.name}  →  ${c.allowedHost}  (${c.authHeaderName})${c.inherited ? '  [inherited from base app]' : ''}`
+  );
+  output(`[z2h-cli] "${appName}" custom integrations:\n${lines.join('\n')}`, { ok: true, appName, connections });
+}
+
+export async function removeCustomIntegrationCommand(name: string | undefined): Promise<void> {
+  if (!name) {
+    throw new Error('Specify the connection name to remove — e.g. z2h-cli custom-integration:remove stripe');
+  }
+
+  const appName = getTargetAppName();
+  const { token } = await readZthAuth();
+
+  const res = await fetch(`${brokerBaseUrl()}/z2h-apps/${appName}/custom-integrations/${encodeURIComponent(name)}`, {
+    method: 'DELETE',
+    headers: { Authorization: `Bearer ${token}`, ...routingHeaders() },
+  });
+  if (!res.ok) {
+    const text = await res.text();
+    throw new Error(`Removing custom integration failed (${res.status}): ${text.slice(0, 1024)}`);
+  }
+
+  output(`[z2h-cli] custom integration "${name}" removed from "${appName}"`, { ok: true, appName, name });
+}

package/src/commands/deploy.ts

@@ -206,6 +206,9 @@ async function deployPreview({ paths, consumerName, appName, token, opts }: Depl
     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,
   });
 

package/src/index.ts

@@ -9,6 +9,7 @@ import { cleanCommand } from './commands/clean';
 import { deployCommand } from './commands/deploy';
 import { deleteCommand } from './commands/delete';
 import { grantCommand, revokeCommand, transferOwnerCommand } from './commands/grant';
+import { listCustomIntegrationsCommand, removeCustomIntegrationCommand } from './commands/custom-integrations';
 import { createWorkspaceCommand } from './commands/create-workspace';
 import { createCommand, CreateOptions } from './commands/create';
 import { generateCommand, GenerateOptions } from './commands/generate';
@@ -260,6 +261,16 @@ async function main(): Promise<void> {
     .description('Transfer ownership of the current app to another monday.com user')
     .action(runCommand({}, (email: string | undefined) => 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: string) => removeCustomIntegrationCommand(name)));
+
   program
     .command('delete')
     .description('Permanently delete the current app and take it offline (owners/admins only)')

package/src/util/app-name.ts

@@ -29,7 +29,7 @@ export function mfAppName(name: string): string {
 // 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

package/src/util/broker/__tests__/app.test.ts

@@ -60,6 +60,38 @@ describe('registerOrUpdateApp', () => {
     });
   });
 
+  it('forwards masterAppName on registration only', async () => {
+    const fetchMock = mockFetchOnce();
+
+    await registerOrUpdateApp({
+      appName: 'mf-zth-preview-abc-my-app',
+      token: 'jwt',
+      nextVersion: 1,
+      entry: ENTRY,
+      gitRemote: '',
+      masterAppName: 'mf-my-app',
+    });
+
+    const [, init] = fetchMock.mock.calls[0] as [string, RequestInit];
+    expect(JSON.parse(init.body as string)).toMatchObject({ masterAppName: 'mf-my-app' });
+  });
+
+  it('does not send masterAppName on update — the link is immutable after registration', async () => {
+    const fetchMock = mockFetchOnce();
+
+    await registerOrUpdateApp({
+      appName: 'mf-zth-preview-abc-my-app',
+      token: 'jwt',
+      nextVersion: 2,
+      entry: ENTRY,
+      gitRemote: '',
+      masterAppName: 'mf-my-app',
+    });
+
+    const [, init] = fetchMock.mock.calls[0] as [string, RequestInit];
+    expect(JSON.parse(init.body as string)).not.toHaveProperty('masterAppName');
+  });
+
   it('updates (not registers) when nextVersion > 1, without prompting for visibility', async () => {
     const fetchMock = mockFetchOnce();
 

package/src/util/broker/app.ts

@@ -115,7 +115,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;
 }