@realtimex/sdk 2.0.29 → 2.0.31

package/README.md

@@ -19,5 +19,29 @@ const workspaces = await client.request("listWorkspaces");
 `REALTIMEX_BASE_URL`. Desktop and `dev:all` runtimes propagate the resolved
 dynamic `/cli` endpoint; the SDK does not guess a localhost port.
 
+## Public webhook task delivery
+
+Use a separate webhook client to trigger an existing public webhook endpoint.
+Webhook endpoint creation and editing remain in RealtimeX settings.
+
+```js
+const { createRealtimeXWebhookClient } = require("@realtimex/sdk");
+
+const webhook = createRealtimeXWebhookClient({
+  endpointUrl: process.env.REALTIMEX_WEBHOOK_URL,
+  secret: process.env.REALTIMEX_WEBHOOK_SECRET,
+});
+
+const receipt = await webhook.trigger(
+  { prompt: "Review this task", context: { sourceId: "task-123" } },
+  { deliveryId: "task-123" }
+);
+```
+
+The client signs the exact UTF-8 request bytes with HMAC-SHA256. Network and
+server-error retries reuse the serialized body, timestamp, and delivery ID so
+the receiving endpoint can deduplicate delivery safely. A successful receipt
+confirms acceptance and routing, not agent-task completion.
+
 The package also publishes generated skill assets under
 `skills/realtimex-moderator-sdk`.

package/index.d.ts

@@ -423,6 +423,25 @@ export interface GetWorkspaceOptions extends RealtimeXRequestOptions {
   body?: GetWorkspaceBody;
 }
 
+export type GoalKickoffComposerParams = Record<string, never>;
+export type GoalKickoffComposerQuery = Record<string, never>;
+export type GoalKickoffComposerHeaders = Record<string, never>;
+export type GoalKickoffComposerBody = {
+  cdpUrl?: string;
+  mainAppUrl?: string;
+  artifactPath?: string;
+  screenshotDir?: string;
+  timeoutMs?: number;
+  confirmDestructive?: boolean;
+};
+export type GoalKickoffComposerResponse = Record<string, unknown>;
+export interface GoalKickoffComposerOptions extends RealtimeXRequestOptions {
+  params?: GoalKickoffComposerParams;
+  query?: GoalKickoffComposerQuery;
+  headers?: GoalKickoffComposerHeaders & Record<string, string>;
+  body?: GoalKickoffComposerBody;
+}
+
 export type InstallPluginParams = Record<string, never>;
 export type InstallPluginQuery = Record<string, never>;
 export type InstallPluginHeaders = {
@@ -826,7 +845,7 @@ export type RespondTerminalIdlePromptHeaders = {
   "x-app-id"?: string;
 };
 export type RespondTerminalIdlePromptBody = {
-  responseAction: "confirm-selected-option" | "cancel-prompt";
+  responseAction: "confirm-selected-option" | "confirm-persistent-workspace-trust" | "cancel-prompt";
   expectedEventSeq: number;
   dispatchKey: string;
 };
@@ -1457,6 +1476,47 @@ export interface RealtimeXRequestOptions {
   signal?: AbortSignal;
 }
 
+export interface RealtimeXWebhookClientOptions {
+  endpointUrl?: string;
+  url?: string;
+  secret?: string;
+  signatureHeader?: string;
+  signaturePrefix?: string;
+  timestampHeader?: string;
+  deliveryIdHeader?: string;
+  eventTypeHeader?: string;
+  sourceHeader?: string;
+  eventType?: string;
+  source?: string;
+  headers?: Record<string, string>;
+  maxRetries?: number;
+  retryDelayMs?: number;
+  timeoutMs?: number;
+  fetch?: typeof fetch;
+}
+
+export interface RealtimeXWebhookTriggerOptions {
+  deliveryId?: string;
+  timestamp?: string | number;
+  eventType?: string;
+  source?: string;
+  headers?: Record<string, string>;
+  maxRetries?: number;
+  retryDelayMs?: number;
+  timeoutMs?: number;
+  signal?: AbortSignal;
+}
+
+export interface RealtimeXWebhookReceipt {
+  success: boolean;
+  accepted: boolean;
+  duplicate: boolean;
+  deliveryId: string;
+  threadId: string | number | null;
+  taskId: string | number | null;
+  [key: string]: unknown;
+}
+
 export declare class RealtimeXApiError extends Error {
   status?: number;
   statusText?: string;
@@ -1464,6 +1524,21 @@ export declare class RealtimeXApiError extends Error {
   response: Response;
 }
 
+export declare class RealtimeXWebhookError extends Error {
+  status?: number;
+  statusText?: string;
+  body: unknown;
+  response: Response | null;
+}
+
+export declare class RealtimeXWebhookClient {
+  constructor(options?: RealtimeXWebhookClientOptions);
+  trigger(
+    payload: unknown,
+    options?: RealtimeXWebhookTriggerOptions
+  ): Promise<RealtimeXWebhookReceipt>;
+}
+
 export declare class RealtimeXClient {
   constructor(options?: RealtimeXClientOptions);
   request(operationName: string, options?: RealtimeXRequestOptions): Promise<unknown>;
@@ -1533,6 +1608,9 @@ export declare class RealtimeXClient {
   /** Get one workspace by exact workspace slug. */
   getWorkspace(options?: GetWorkspaceOptions): Promise<GetWorkspaceResponse>;
   getWorkspace(workspaceSlug: string, options?: Omit<GetWorkspaceOptions, 'params'>): Promise<GetWorkspaceResponse>;
+  /** Verify the shared Project/global Goal kickoff composer, routing, attachment authorization, retry, preview, and responsive layouts. */
+  goalKickoffComposer(options?: GoalKickoffComposerOptions): Promise<GoalKickoffComposerResponse>;
+  goalKickoffComposer(body: GoalKickoffComposerBody, options?: Omit<GoalKickoffComposerOptions, 'body'>): Promise<GoalKickoffComposerResponse>;
   /** Install a plugin from a local source directory on the same machine as the server. Pass an absolute path containing realtimex.plugin.json. Pass force=true to replace an already-installed version; its saved configuration (including secrets) is preserved. */
   installPlugin(options?: InstallPluginOptions): Promise<InstallPluginResponse>;
   installPlugin(body: InstallPluginBody, options?: Omit<InstallPluginOptions, 'body'>): Promise<InstallPluginResponse>;
@@ -1689,6 +1767,9 @@ export declare class RealtimeXClient {
 export declare function createRealtimeXClient(
   options?: RealtimeXClientOptions
 ): RealtimeXClient;
+export declare function createRealtimeXWebhookClient(
+  options?: RealtimeXWebhookClientOptions
+): RealtimeXWebhookClient;
 export declare const createClient: typeof createRealtimeXClient;
 export declare const operations: Record<
   string,

package/index.js

@@ -1,5 +1,7 @@
 'use strict';
 
+const crypto = require('node:crypto');
+
 const operations = {
   "approveChannelPairingCode": {
     "method": "POST",
@@ -268,6 +270,14 @@ const operations = {
     ],
     "hasBody": false
   },
+  "goalKickoffComposer": {
+    "method": "POST",
+    "path": "/goal-kickoff-composer",
+    "pathParams": [],
+    "queryParams": [],
+    "headerParams": [],
+    "hasBody": true
+  },
   "installPlugin": {
     "method": "POST",
     "path": "/install-plugin",
@@ -876,6 +886,17 @@ class RealtimeXApiError extends Error {
   }
 }
 
+class RealtimeXWebhookError extends Error {
+  constructor(message, response = null, body = null, cause = null) {
+    super(message, cause ? { cause } : undefined);
+    this.name = 'RealtimeXWebhookError';
+    this.status = response && response.status;
+    this.statusText = response && response.statusText;
+    this.body = body;
+    this.response = response;
+  }
+}
+
 function joinUrl(baseUrl, pathname) {
   const base = String(baseUrl || '').replace(/\/+$/g, '');
   const path = String(pathname || '').replace(/^\/+/, '');
@@ -929,6 +950,220 @@ async function parseResponseBody(response) {
   }
 }
 
+function normalizeWebhookEndpointUrl(value) {
+  const normalized = String(value || '').trim();
+  if (!normalized) {
+    throw new Error(
+      'RealtimeX webhook URL is unavailable; pass { endpointUrl } or set REALTIMEX_WEBHOOK_URL.'
+    );
+  }
+  const parsed = new URL(normalized);
+  if (!['http:', 'https:'].includes(parsed.protocol)) {
+    throw new Error('RealtimeX webhook URL must use http or https.');
+  }
+  if (parsed.username || parsed.password) {
+    throw new Error('RealtimeX webhook URL must not contain embedded credentials.');
+  }
+  return parsed.toString();
+}
+
+function normalizeRetryCount(value, fallback = 2) {
+  const parsed = Number(value);
+  if (!Number.isInteger(parsed) || parsed < 0 || parsed > 10) return fallback;
+  return parsed;
+}
+
+function normalizeTimeout(value, fallback = 15000) {
+  const parsed = Number(value);
+  if (!Number.isFinite(parsed) || parsed <= 0) return fallback;
+  return Math.min(Math.floor(parsed), 120000);
+}
+
+function waitForRetry(delayMs, signal) {
+  const delay = Math.max(0, Number(delayMs) || 0);
+  if (delay === 0) return Promise.resolve();
+  return new Promise((resolve, reject) => {
+    const finish = () => {
+      if (signal) signal.removeEventListener('abort', abort);
+      resolve();
+    };
+    const timeout = setTimeout(finish, delay);
+    const abort = () => {
+      clearTimeout(timeout);
+      signal.removeEventListener('abort', abort);
+      reject(signal.reason || new Error('Webhook request aborted.'));
+    };
+    if (signal) {
+      if (signal.aborted) return abort();
+      signal.addEventListener('abort', abort, { once: true });
+    }
+  });
+}
+
+function createAttemptSignal(externalSignal, timeoutMs) {
+  const controller = new AbortController();
+  const abortFromExternal = () => {
+    controller.abort(externalSignal.reason || new Error('Webhook request aborted.'));
+  };
+  if (externalSignal) {
+    if (externalSignal.aborted) abortFromExternal();
+    else externalSignal.addEventListener('abort', abortFromExternal, { once: true });
+  }
+  const timeout = setTimeout(
+    () => controller.abort(new Error('Webhook request timed out.')),
+    timeoutMs
+  );
+  return {
+    signal: controller.signal,
+    cleanup() {
+      clearTimeout(timeout);
+      if (externalSignal) {
+        externalSignal.removeEventListener('abort', abortFromExternal);
+      }
+    },
+  };
+}
+
+class RealtimeXWebhookClient {
+  constructor(options = {}) {
+    const env = typeof process !== 'undefined' ? process.env || {} : {};
+    this.endpointUrl = normalizeWebhookEndpointUrl(
+      options.endpointUrl || options.url || env.REALTIMEX_WEBHOOK_URL
+    );
+    this.secret = String(options.secret || env.REALTIMEX_WEBHOOK_SECRET || '');
+    if (!this.secret) {
+      throw new Error(
+        'RealtimeX webhook secret is unavailable; pass { secret } or set REALTIMEX_WEBHOOK_SECRET.'
+      );
+    }
+    this.fetch = options.fetch || globalThis.fetch;
+    if (typeof this.fetch !== 'function') {
+      throw new Error('A fetch implementation is required. Use Node 18+ or pass { fetch }.');
+    }
+    this.signatureHeader =
+      options.signatureHeader ||
+      env.REALTIMEX_WEBHOOK_SIGNATURE_HEADER ||
+      'X-Webhook-Signature-256';
+    this.signaturePrefix =
+      options.signaturePrefix ?? env.REALTIMEX_WEBHOOK_SIGNATURE_PREFIX ?? 'sha256=';
+    this.timestampHeader =
+      options.timestampHeader ||
+      env.REALTIMEX_WEBHOOK_TIMESTAMP_HEADER ||
+      'X-Webhook-Timestamp';
+    this.deliveryIdHeader =
+      options.deliveryIdHeader ||
+      env.REALTIMEX_WEBHOOK_DELIVERY_ID_HEADER ||
+      'X-Webhook-Id';
+    this.eventTypeHeader =
+      options.eventTypeHeader ||
+      env.REALTIMEX_WEBHOOK_EVENT_TYPE_HEADER ||
+      'X-Webhook-Event';
+    this.sourceHeader =
+      options.sourceHeader ||
+      env.REALTIMEX_WEBHOOK_SOURCE_HEADER ||
+      'X-Webhook-Source';
+    this.defaultEventType =
+      options.eventType || env.REALTIMEX_WEBHOOK_EVENT_TYPE || 'realtimex.task';
+    this.defaultSource =
+      options.source || env.REALTIMEX_WEBHOOK_SOURCE || 'local-app';
+    this.defaultHeaders = { ...(options.headers || {}) };
+    this.maxRetries = normalizeRetryCount(options.maxRetries, 2);
+    const configuredRetryDelay = Number(options.retryDelayMs);
+    this.retryDelayMs = Number.isFinite(configuredRetryDelay) && configuredRetryDelay >= 0
+      ? configuredRetryDelay
+      : 250;
+    this.timeoutMs = normalizeTimeout(options.timeoutMs, 15000);
+  }
+
+  async trigger(payload, options = {}) {
+    if (payload === undefined) {
+      throw new Error('RealtimeX webhook payload is required.');
+    }
+    const serialized = typeof payload === 'string' ? payload : JSON.stringify(payload);
+    if (serialized === undefined) {
+      throw new Error('RealtimeX webhook payload is not JSON serializable.');
+    }
+    const body = Buffer.from(serialized, 'utf8');
+    const deliveryId = String(options.deliveryId || crypto.randomUUID());
+    const timestamp = String(
+      options.timestamp || Math.floor(Date.now() / 1000)
+    );
+    const signature = crypto
+      .createHmac('sha256', this.secret)
+      .update(body)
+      .digest('hex');
+    const headers = {
+      ...this.defaultHeaders,
+      ...(options.headers || {}),
+      'content-type': 'application/json',
+      [this.signatureHeader]: String(this.signaturePrefix || '') + signature,
+      [this.timestampHeader]: timestamp,
+      [this.deliveryIdHeader]: deliveryId,
+      [this.eventTypeHeader]: String(options.eventType || this.defaultEventType),
+      [this.sourceHeader]: String(options.source || this.defaultSource),
+    };
+    const maxRetries = normalizeRetryCount(options.maxRetries, this.maxRetries);
+    const retryDelayMs =
+      options.retryDelayMs === undefined
+        ? this.retryDelayMs
+        : Math.max(0, Number(options.retryDelayMs) || 0);
+    const timeoutMs = normalizeTimeout(options.timeoutMs, this.timeoutMs);
+
+    for (let attempt = 0; attempt <= maxRetries; attempt += 1) {
+      const attemptSignal = createAttemptSignal(options.signal, timeoutMs);
+      try {
+        const response = await this.fetch(this.endpointUrl, {
+          method: 'POST',
+          headers,
+          body,
+          signal: attemptSignal.signal,
+        });
+        const responseBody = await parseResponseBody(response);
+        if (response.status >= 500 && attempt < maxRetries) {
+          await waitForRetry(retryDelayMs * (attempt + 1), options.signal);
+          continue;
+        }
+        if (!response.ok) {
+          throw new RealtimeXWebhookError(
+            'RealtimeX webhook request failed: ' +
+              response.status +
+              ' ' +
+              response.statusText,
+            response,
+            responseBody
+          );
+        }
+        return responseBody;
+      } catch (error) {
+        if (error instanceof RealtimeXWebhookError) throw error;
+        if (options.signal && options.signal.aborted) {
+          throw new RealtimeXWebhookError(
+            'RealtimeX webhook request aborted.',
+            null,
+            null,
+            error
+          );
+        }
+        if (attempt >= maxRetries) {
+          const timedOut = attemptSignal.signal.aborted;
+          throw new RealtimeXWebhookError(
+            timedOut
+              ? 'RealtimeX webhook request timed out.'
+              : 'RealtimeX webhook request failed: ' + (error.message || String(error)),
+            null,
+            null,
+            error
+          );
+        }
+        await waitForRetry(retryDelayMs * (attempt + 1), options.signal);
+      } finally {
+        attemptSignal.cleanup();
+      }
+    }
+    throw new RealtimeXWebhookError('RealtimeX webhook request failed.');
+  }
+}
+
 function isPlainObject(value) {
   return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
 }
@@ -1217,6 +1452,13 @@ class RealtimeXClient {
     );
   }
 
+  goalKickoffComposer(...args) {
+    return this.request(
+      "goalKickoffComposer",
+      normalizeOperationOptions(operations["goalKickoffComposer"], args)
+    );
+  }
+
   installPlugin(...args) {
     return this.request(
       "installPlugin",
@@ -1593,11 +1835,18 @@ function createRealtimeXClient(options = {}) {
   return new RealtimeXClient(options);
 }
 
+function createRealtimeXWebhookClient(options = {}) {
+  return new RealtimeXWebhookClient(options);
+}
+
 module.exports = {
   RealtimeXApiError,
   RealtimeXClient,
+  RealtimeXWebhookClient,
+  RealtimeXWebhookError,
   createClient: createRealtimeXClient,
   createRealtimeXClient,
+  createRealtimeXWebhookClient,
   operations,
-  version: "2.0.29",
+  version: "2.0.31",
 };

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@realtimex/sdk",
-    "version": "2.0.29",
+    "version": "2.0.31",
     "description": "RealtimeX runtime SDK package and moderator agent skill assets.",
     "private": false,
     "main": "./index.js",

package/skills/realtimex-moderator-sdk/SKILL.md

@@ -20,15 +20,15 @@ This skill drives the `realtimex-pp-cli` binary. Verify the CLI is installed and
 
 1. Install or reinstall the pinned version via npm:
    ```bash
-   npm install -g @realtimex/pp-cli@2.0.29
+   npm install -g @realtimex/pp-cli@2.0.31
    ```
 2. Verify the exact version:
    ```bash
    realtimex-pp-cli --version
    ```
-   The output must be `realtimex-pp-cli 2.0.29`.
+   The output must be `realtimex-pp-cli 2.0.31`.
 
-If `--version` reports "command not found" after install, the npm global bin directory is not on `$PATH`. If it reports any version other than `2.0.29`, reinstall with the pinned npm command above. Do not proceed with skill commands until exact-version verification succeeds.
+If `--version` reports "command not found" after install, the npm global bin directory is not on `$PATH`. If it reports any version other than `2.0.31`, reinstall with the pinned npm command above. Do not proceed with skill commands until exact-version verification succeeds.
 
 * Always run first:
 
@@ -126,6 +126,10 @@ If `--version` reports "command not found" after install, the npm global bin dir
 
 - `realtimex-pp-cli get-workspace <workspaceSlug>` — Get one workspace by exact workspace slug.
 
+**goal-kickoff-composer** — Manage goal kickoff composer
+
+- `realtimex-pp-cli goal-kickoff-composer` — Verify the shared Project/global Goal kickoff composer, routing, attachment authorization, retry, preview
+
 **install-plugin** — Manage install plugin
 
 - `realtimex-pp-cli install-plugin` — Install a plugin from a local source directory on the same machine as the server.
@@ -460,9 +464,9 @@ Verify: `claude mcp list`
    ```bash
    realtimex-pp-cli --version
    ```
-   If the command is missing or the output is not exactly `realtimex-pp-cli 2.0.29`, reinstall the pinned version:
+   If the command is missing or the output is not exactly `realtimex-pp-cli 2.0.31`, reinstall the pinned version:
    ```bash
-   npm install -g @realtimex/pp-cli@2.0.29
+   npm install -g @realtimex/pp-cli@2.0.31
    ```
    Then run `realtimex-pp-cli --version` again and proceed only after exact-version verification succeeds.
 2. Match the user query to the best command from the Unique Capabilities and Command Reference above.