@realtimex/sdk 1.3.4 → 1.3.5-rc.1

package/dist/index.mjs

@@ -228,6 +228,204 @@ var ActivitiesModule = class {
   }
 };
 
+// src/modules/contract.ts
+import { createHash, createHmac, randomUUID } from "crypto";
+var LOCAL_APP_CONTRACT_VERSION = "local-app-contract/v1";
+var CONTRACT_SIGNATURE_HEADER = "x-rtx-contract-signature";
+var CONTRACT_EVENT_ID_HEADER = "x-rtx-event-id";
+var CONTRACT_SIGNATURE_ALGORITHM = "sha256";
+var CONTRACT_ATTEMPT_PREFIX = "run-";
+var CONTRACT_EVENT_ALIASES = {
+  "trigger-agent": "task.trigger",
+  "task.trigger": "task.trigger",
+  ping: "system.ping",
+  "system.ping": "system.ping",
+  claim: "task.claimed",
+  claimed: "task.claimed",
+  "task.claimed": "task.claimed",
+  "task-start": "task.started",
+  start: "task.started",
+  "task.started": "task.started",
+  "task-progress": "task.progress",
+  progress: "task.progress",
+  processing: "task.progress",
+  "task.progress": "task.progress",
+  "task-complete": "task.completed",
+  complete: "task.completed",
+  completed: "task.completed",
+  "task.completed": "task.completed",
+  "task-fail": "task.failed",
+  fail: "task.failed",
+  failed: "task.failed",
+  "task.failed": "task.failed",
+  "task-cancel": "task.canceled",
+  "task-cancelled": "task.canceled",
+  "task-canceled": "task.canceled",
+  cancel: "task.canceled",
+  cancelled: "task.canceled",
+  canceled: "task.canceled",
+  "task.canceled": "task.canceled"
+};
+var CONTRACT_LEGACY_ACTIONS = {
+  "task.trigger": "trigger-agent",
+  "system.ping": "ping",
+  "task.claimed": "claim",
+  "task.started": "start",
+  "task.progress": "progress",
+  "task.completed": "complete",
+  "task.failed": "fail",
+  "task.canceled": "cancel"
+};
+function normalizeContractEvent(eventLike) {
+  if (!eventLike || typeof eventLike !== "string") return null;
+  const normalized = CONTRACT_EVENT_ALIASES[eventLike.trim().toLowerCase()];
+  return normalized || null;
+}
+function normalizeAttemptId(attemptLike) {
+  if (attemptLike === null || attemptLike === void 0) return void 0;
+  if (typeof attemptLike === "number" && Number.isInteger(attemptLike) && attemptLike > 0) {
+    return `${CONTRACT_ATTEMPT_PREFIX}${attemptLike}`;
+  }
+  if (typeof attemptLike !== "string") return void 0;
+  const trimmed = attemptLike.trim();
+  if (!trimmed) return void 0;
+  if (trimmed.startsWith(CONTRACT_ATTEMPT_PREFIX)) return trimmed;
+  if (/^\d+$/.test(trimmed)) return `${CONTRACT_ATTEMPT_PREFIX}${trimmed}`;
+  return trimmed;
+}
+function parseAttemptRunId(attemptLike) {
+  const attemptId = normalizeAttemptId(attemptLike);
+  if (!attemptId) return null;
+  const matched = attemptId.match(/^run[-_:]?(\d+)$/i);
+  if (!matched) return null;
+  const value = Number(matched[1]);
+  return Number.isInteger(value) && value > 0 ? value : null;
+}
+function hashContractPayload(payload) {
+  const normalized = payload && typeof payload === "object" ? payload : { value: payload ?? null };
+  return createHash("sha256").update(JSON.stringify(normalized)).digest("hex");
+}
+function createContractEventId() {
+  return randomUUID();
+}
+function buildContractSignatureMessage({
+  eventId,
+  eventType,
+  taskId,
+  attemptId,
+  timestamp,
+  payload
+}) {
+  return [
+    String(eventId || ""),
+    String(normalizeContractEvent(String(eventType || "")) || eventType || ""),
+    String(taskId || ""),
+    String(normalizeAttemptId(attemptId) || ""),
+    String(timestamp || ""),
+    hashContractPayload(payload ?? {})
+  ].join(".");
+}
+function signContractEvent(input) {
+  const signatureMessage = buildContractSignatureMessage(input);
+  const digest = createHmac(CONTRACT_SIGNATURE_ALGORITHM, input.secret).update(signatureMessage).digest("hex");
+  return `${CONTRACT_SIGNATURE_ALGORITHM}=${digest}`;
+}
+function canonicalEventToLegacyAction(eventLike) {
+  const normalized = normalizeContractEvent(eventLike);
+  if (!normalized) return null;
+  return CONTRACT_LEGACY_ACTIONS[normalized] || null;
+}
+function buildContractIdempotencyKey({
+  taskId,
+  eventType,
+  eventId,
+  attemptId,
+  machineId,
+  timestamp,
+  payload
+}) {
+  const canonicalEvent = normalizeContractEvent(eventType) || eventType;
+  if (eventId) {
+    const eventToken = createHash("sha256").update(String(eventId)).digest("hex");
+    return `${taskId}:${canonicalEvent}:event:${eventToken}`;
+  }
+  const hashInput = {
+    task_id: taskId,
+    event_type: canonicalEvent,
+    attempt_id: normalizeAttemptId(attemptId),
+    machine_id: machineId || null,
+    timestamp: timestamp || null,
+    payload_hash: hashContractPayload(payload ?? {})
+  };
+  const token = createHash("sha256").update(JSON.stringify(hashInput)).digest("hex");
+  return `${taskId}:${canonicalEvent}:hash:${token}`;
+}
+var ContractModule = class {
+  constructor(realtimexUrl, appName, appId, apiKey) {
+    this.cachedContract = null;
+    this.realtimexUrl = realtimexUrl.replace(/\/$/, "");
+    this.appName = appName;
+    this.appId = appId;
+    this.apiKey = apiKey;
+  }
+  async requestPermission(permission) {
+    try {
+      const response = await fetch(`${this.realtimexUrl}/api/local-apps/request-permission`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+          app_id: this.appId,
+          app_name: this.appName,
+          permission
+        })
+      });
+      const data = await response.json();
+      return data.granted === true;
+    } catch {
+      return false;
+    }
+  }
+  async request(path) {
+    const url = `${this.realtimexUrl}${path}`;
+    const headers = {
+      "Content-Type": "application/json"
+    };
+    if (this.apiKey) headers.Authorization = `Bearer ${this.apiKey}`;
+    if (this.appId) headers["x-app-id"] = this.appId;
+    const response = await fetch(url, {
+      method: "GET",
+      headers
+    });
+    const data = await response.json();
+    if (response.status === 403) {
+      const errorCode = data.error;
+      const permission = data.permission;
+      const message = data.message;
+      if (errorCode === "PERMISSION_REQUIRED" && permission) {
+        const granted = await this.requestPermission(permission);
+        if (granted) return this.request(path);
+        throw new PermissionDeniedError(permission, message);
+      }
+      if (errorCode === "PERMISSION_DENIED") {
+        throw new PermissionDeniedError(permission, message);
+      }
+    }
+    if (!response.ok) {
+      throw new Error(data.error || `Request failed: ${response.status}`);
+    }
+    return data;
+  }
+  async getLocalAppV1(forceRefresh = false) {
+    if (!forceRefresh && this.cachedContract) return this.cachedContract;
+    const data = await this.request("/contracts/local-app/v1");
+    this.cachedContract = data.contract;
+    return data.contract;
+  }
+  clearCache() {
+    this.cachedContract = null;
+  }
+};
+
 // src/modules/webhook.ts
 var WebhookModule = class {
   constructor(realtimexUrl, appName, appId, apiKey) {
@@ -304,7 +502,9 @@ var WebhookModule = class {
       body: JSON.stringify({
         app_name: this.appName,
         app_id: this.appId,
-        event: "trigger-agent",
+        event: "task.trigger",
+        event_id: payload.event_id || createContractEventId(),
+        attempt_id: normalizeAttemptId(payload.attempt_id),
         payload: {
           raw_data: payload.raw_data,
           auto_run: payload.auto_run ?? false,
@@ -322,7 +522,8 @@ var WebhookModule = class {
       body: JSON.stringify({
         app_name: this.appName,
         app_id: this.appId,
-        event: "ping"
+        event: "system.ping",
+        event_id: createContractEventId()
       })
     });
   }
@@ -335,49 +536,148 @@ var TaskModule = class {
     this.appName = appName;
     this.appId = appId;
     this.apiKey = apiKey;
+    this.callbackSecret = process.env.RTX_CONTRACT_CALLBACK_SECRET;
+    this.signCallbacksByDefault = process.env.RTX_CONTRACT_SIGN_CALLBACKS === "true";
   }
   /**
-   * Mark task as processing
+   * Configure callback signing behavior.
    */
-  async start(taskUuid, machineId) {
-    return this._sendEvent("task-start", taskUuid, { machine_id: machineId });
+  configureContract(config) {
+    if (typeof config.callbackSecret === "string") {
+      this.callbackSecret = config.callbackSecret;
+    }
+    if (typeof config.signCallbacksByDefault === "boolean") {
+      this.signCallbacksByDefault = config.signCallbacksByDefault;
+    }
   }
   /**
-   * Mark task as completed with result
+   * Claim a task before processing.
    */
-  async complete(taskUuid, result, machineId) {
-    return this._sendEvent("task-complete", taskUuid, { result, machine_id: machineId });
+  async claim(taskUuid, options = {}) {
+    return this._sendEvent("task.claimed", taskUuid, {}, options);
   }
   /**
-   * Mark task as failed with error
+   * Alias for claim()
    */
-  async fail(taskUuid, error, machineId) {
-    return this._sendEvent("task-fail", taskUuid, { error, machine_id: machineId });
+  async claimed(taskUuid, options = {}) {
+    return this.claim(taskUuid, options);
   }
-  async _sendEvent(event, taskUuid, extra) {
+  /**
+   * Mark task as processing.
+   * Backward compatible signature: start(taskUuid, machineId?)
+   */
+  async start(taskUuid, machineIdOrOptions) {
+    return this._sendEvent("task.started", taskUuid, {}, this._normalizeOptions(machineIdOrOptions));
+  }
+  /**
+   * Report incremental task progress.
+   */
+  async progress(taskUuid, progressData = {}, options = {}) {
+    return this._sendEvent("task.progress", taskUuid, progressData, options);
+  }
+  /**
+   * Mark task as completed with result.
+   * Backward compatible signature: complete(taskUuid, result?, machineId?)
+   */
+  async complete(taskUuid, result = {}, machineIdOrOptions) {
+    return this._sendEvent("task.completed", taskUuid, { result }, this._normalizeOptions(machineIdOrOptions));
+  }
+  /**
+   * Mark task as failed with error.
+   * Backward compatible signature: fail(taskUuid, error, machineId?)
+   */
+  async fail(taskUuid, error, machineIdOrOptions) {
+    return this._sendEvent("task.failed", taskUuid, { error }, this._normalizeOptions(machineIdOrOptions));
+  }
+  /**
+   * Mark task as canceled.
+   */
+  async cancel(taskUuid, reason, options = {}) {
+    const payload = reason ? { error: reason } : {};
+    return this._sendEvent("task.canceled", taskUuid, payload, options);
+  }
+  _normalizeOptions(machineIdOrOptions) {
+    if (!machineIdOrOptions) return {};
+    if (typeof machineIdOrOptions === "string") {
+      return { machineId: machineIdOrOptions };
+    }
+    return machineIdOrOptions;
+  }
+  async _sendEvent(event, taskUuid, eventData = {}, options = {}) {
+    if (!taskUuid || !taskUuid.trim()) {
+      throw new Error("taskUuid is required");
+    }
+    const attemptId = normalizeAttemptId(options.attemptId);
+    const timestamp = options.timestamp || (/* @__PURE__ */ new Date()).toISOString();
+    const eventId = options.eventId || createContractEventId();
+    const callbackUrl = options.callbackUrl;
+    const targetUrl = callbackUrl || `${this.realtimexUrl}/webhooks/realtimex`;
+    const sendingToMainWebhook = !callbackUrl;
+    const includeAppAuth = sendingToMainWebhook || targetUrl.startsWith(this.realtimexUrl);
+    const payloadData = eventData && typeof eventData === "object" ? eventData : {};
     const headers = { "Content-Type": "application/json" };
-    if (this.apiKey) {
-      headers["Authorization"] = `Bearer ${this.apiKey}`;
+    headers[CONTRACT_EVENT_ID_HEADER] = eventId;
+    if (includeAppAuth) {
+      if (this.apiKey) headers.Authorization = `Bearer ${this.apiKey}`;
+      if (this.appId) headers["x-app-id"] = this.appId;
     }
-    if (this.appId) {
-      headers["x-app-id"] = this.appId;
+    const callbackSecret = options.callbackSecret || this.callbackSecret;
+    const shouldSign = options.sign ?? this.signCallbacksByDefault;
+    if (shouldSign) {
+      if (!callbackSecret) {
+        throw new Error(
+          "Callback signing is enabled but no callbackSecret is configured. Use task.configureContract({ callbackSecret }) or pass options.callbackSecret."
+        );
+      }
+      headers[CONTRACT_SIGNATURE_HEADER] = signContractEvent({
+        secret: callbackSecret,
+        eventId,
+        eventType: event,
+        taskId: taskUuid,
+        attemptId,
+        timestamp,
+        payload: payloadData
+      });
     }
-    const response = await fetch(`${this.realtimexUrl}/webhooks/realtimex`, {
+    const requestBody = sendingToMainWebhook ? {
+      app_name: this.appName,
+      app_id: this.appId,
+      event,
+      event_id: eventId,
+      attempt_id: attemptId,
+      payload: {
+        task_uuid: taskUuid,
+        machine_id: options.machineId,
+        timestamp,
+        attempt_id: attemptId,
+        ...payloadData
+      }
+    } : {
+      event,
+      action: canonicalEventToLegacyAction(event),
+      event_id: eventId,
+      attempt_id: attemptId,
+      machine_id: options.machineId,
+      user_email: options.userEmail,
+      activity_id: options.activityId,
+      table_name: options.tableName,
+      timestamp,
+      data: payloadData
+    };
+    const response = await fetch(targetUrl, {
       method: "POST",
       headers,
-      body: JSON.stringify({
-        app_name: this.appName,
-        app_id: this.appId,
-        event,
-        payload: {
-          task_uuid: taskUuid,
-          ...extra
-        }
-      })
+      body: JSON.stringify(requestBody)
     });
-    const data = await response.json();
-    if (!response.ok) throw new Error(data.error || `Failed to ${event}`);
-    return data;
+    const responseData = await response.json();
+    if (!response.ok) throw new Error(responseData.error || `Failed to ${event}`);
+    return {
+      ...responseData,
+      task_uuid: responseData.task_uuid || responseData.task_id || taskUuid,
+      event_id: responseData.event_id || eventId,
+      attempt_id: responseData.attempt_id || attemptId,
+      event_type: responseData.event_type || event
+    };
   }
 };
 
@@ -1429,12 +1729,16 @@ var _RealtimeXSDK = class _RealtimeXSDK {
     this.webhook = new WebhookModule(this.realtimexUrl, this.appName, this.appId, this.apiKey);
     this.api = new ApiModule(this.realtimexUrl, this.appId, this.appName, this.apiKey);
     this.task = new TaskModule(this.realtimexUrl, this.appName, this.appId, this.apiKey);
+    if (config.contract) {
+      this.task.configureContract(config.contract);
+    }
     this.port = new PortModule(config.defaultPort);
     this.llm = new LLMModule(this.realtimexUrl, this.appId, this.appName, this.apiKey);
     this.tts = new TTSModule(this.realtimexUrl, this.appId, this.appName, this.apiKey);
     this.stt = new STTModule(this.realtimexUrl, this.appId, this.appName, this.apiKey);
     this.agent = new AgentModule(this.httpClient);
     this.mcp = new MCPModule(this.realtimexUrl, this.appId, this.appName, this.apiKey);
+    this.contract = new ContractModule(this.realtimexUrl, this.appName, this.appId, this.apiKey);
     if (this.permissions.length > 0 && this.appId && !this.apiKey) {
       this.register().catch((err) => {
         console.error("[RealtimeX SDK] Auto-registration failed:", err.message);
@@ -1538,9 +1842,15 @@ export {
   ActivitiesModule,
   AgentModule,
   ApiModule,
+  CONTRACT_ATTEMPT_PREFIX,
+  CONTRACT_EVENT_ID_HEADER,
+  CONTRACT_SIGNATURE_ALGORITHM,
+  CONTRACT_SIGNATURE_HEADER,
+  ContractModule,
   LLMModule,
   LLMPermissionError,
   LLMProviderError,
+  LOCAL_APP_CONTRACT_VERSION,
   MCPModule,
   PermissionDeniedError,
   PermissionRequiredError,
@@ -1550,5 +1860,14 @@ export {
   TTSModule,
   TaskModule,
   VectorStore,
-  WebhookModule
+  WebhookModule,
+  buildContractIdempotencyKey,
+  buildContractSignatureMessage,
+  canonicalEventToLegacyAction,
+  createContractEventId,
+  hashContractPayload,
+  normalizeAttemptId,
+  normalizeContractEvent,
+  parseAttemptRunId,
+  signContractEvent
 };

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@realtimex/sdk",
-    "version": "1.3.4",
+    "version": "1.3.5-rc.1",
     "description": "SDK for building Local Apps that integrate with RealtimeX",
     "main": "dist/index.js",
     "module": "dist/index.mjs",
@@ -16,6 +16,7 @@
         "build": "tsup src/index.ts --format cjs,esm --dts --clean",
         "dev": "tsup src/index.ts --format cjs,esm --dts --watch",
         "test": "vitest run",
+        "contract:verify": "node ../scripts/verify-contract-compat.mjs",
         "prepublishOnly": "npm run build"
     },
     "keywords": [