@realtimex/sdk 1.0.4 → 1.0.6

package/dist/index.d.mts

@@ -7,6 +7,7 @@ interface SDKConfig {
         appId?: string;
         appName?: string;
     };
+    defaultPort?: number;
 }
 interface Activity {
     id: string;
@@ -143,6 +144,75 @@ declare class ApiModule {
     getTask(taskUuid: string): Promise<Task>;
 }
 
+/**
+ * Task Module - Report task status to RealtimeX
+ * Used by external agents/processors to update task status
+ */
+interface TaskStatusResponse {
+    success: boolean;
+    task_uuid: string;
+    status: string;
+    message?: string;
+}
+declare class TaskModule {
+    private realtimexUrl;
+    private appName?;
+    private appId?;
+    constructor(realtimexUrl: string, appName?: string, appId?: string);
+    /**
+     * Mark task as processing
+     */
+    start(taskUuid: string, machineId?: string): Promise<TaskStatusResponse>;
+    /**
+     * Mark task as completed with result
+     */
+    complete(taskUuid: string, result?: object, machineId?: string): Promise<TaskStatusResponse>;
+    /**
+     * Mark task as failed with error
+     */
+    fail(taskUuid: string, error: string, machineId?: string): Promise<TaskStatusResponse>;
+    private _sendEvent;
+}
+
+/**
+ * Port utilities for Local Apps
+ * Helps find available ports to avoid conflicts when multiple apps run simultaneously
+ */
+declare class PortModule {
+    private defaultPort;
+    constructor(defaultPort?: number);
+    /**
+     * Get suggested port from environment (RTX_PORT) or default
+     */
+    getSuggestedPort(): number;
+    /**
+     * Check if a port is available
+     * @param port - Port number to check
+     * @returns Promise resolving to true if port is available
+     */
+    isPortAvailable(port: number): Promise<boolean>;
+    /**
+     * Find an available port starting from the suggested port
+     * @param startPort - Starting port number (default: RTX_PORT or defaultPort)
+     * @param maxAttempts - Maximum ports to try (default: 100)
+     * @returns Promise resolving to an available port number
+     * @throws Error if no available port found in range
+     */
+    findAvailablePort(startPort?: number, maxAttempts?: number): Promise<number>;
+    /**
+     * Get a ready-to-use port
+     * Returns the suggested port if available, otherwise finds the next available port
+     *
+     * @example
+     * ```typescript
+     * const sdk = new RealtimeXSDK();
+     * const port = await sdk.port.getPort();
+     * app.listen(port);
+     * ```
+     */
+    getPort(): Promise<number>;
+}
+
 /**
  * RealtimeX Local App SDK
  *
@@ -154,6 +224,8 @@ declare class RealtimeXSDK {
     activities: ActivitiesModule;
     webhook: WebhookModule;
     api: ApiModule;
+    task: TaskModule;
+    port: PortModule;
     readonly appId: string;
     readonly appName: string | undefined;
     private static DEFAULT_REALTIMEX_URL;
@@ -164,4 +236,4 @@ declare class RealtimeXSDK {
     private getEnvVar;
 }
 
-export { ActivitiesModule, type Activity, type Agent, ApiModule, RealtimeXSDK, type SDKConfig, type Task, type TaskRun, type Thread, type TriggerAgentPayload, type TriggerAgentResponse, WebhookModule, type Workspace };
+export { ActivitiesModule, type Activity, type Agent, ApiModule, PortModule, RealtimeXSDK, type SDKConfig, type Task, TaskModule, type TaskRun, type Thread, type TriggerAgentPayload, type TriggerAgentResponse, WebhookModule, type Workspace };

package/dist/index.d.ts

@@ -7,6 +7,7 @@ interface SDKConfig {
         appId?: string;
         appName?: string;
     };
+    defaultPort?: number;
 }
 interface Activity {
     id: string;
@@ -143,6 +144,75 @@ declare class ApiModule {
     getTask(taskUuid: string): Promise<Task>;
 }
 
+/**
+ * Task Module - Report task status to RealtimeX
+ * Used by external agents/processors to update task status
+ */
+interface TaskStatusResponse {
+    success: boolean;
+    task_uuid: string;
+    status: string;
+    message?: string;
+}
+declare class TaskModule {
+    private realtimexUrl;
+    private appName?;
+    private appId?;
+    constructor(realtimexUrl: string, appName?: string, appId?: string);
+    /**
+     * Mark task as processing
+     */
+    start(taskUuid: string, machineId?: string): Promise<TaskStatusResponse>;
+    /**
+     * Mark task as completed with result
+     */
+    complete(taskUuid: string, result?: object, machineId?: string): Promise<TaskStatusResponse>;
+    /**
+     * Mark task as failed with error
+     */
+    fail(taskUuid: string, error: string, machineId?: string): Promise<TaskStatusResponse>;
+    private _sendEvent;
+}
+
+/**
+ * Port utilities for Local Apps
+ * Helps find available ports to avoid conflicts when multiple apps run simultaneously
+ */
+declare class PortModule {
+    private defaultPort;
+    constructor(defaultPort?: number);
+    /**
+     * Get suggested port from environment (RTX_PORT) or default
+     */
+    getSuggestedPort(): number;
+    /**
+     * Check if a port is available
+     * @param port - Port number to check
+     * @returns Promise resolving to true if port is available
+     */
+    isPortAvailable(port: number): Promise<boolean>;
+    /**
+     * Find an available port starting from the suggested port
+     * @param startPort - Starting port number (default: RTX_PORT or defaultPort)
+     * @param maxAttempts - Maximum ports to try (default: 100)
+     * @returns Promise resolving to an available port number
+     * @throws Error if no available port found in range
+     */
+    findAvailablePort(startPort?: number, maxAttempts?: number): Promise<number>;
+    /**
+     * Get a ready-to-use port
+     * Returns the suggested port if available, otherwise finds the next available port
+     *
+     * @example
+     * ```typescript
+     * const sdk = new RealtimeXSDK();
+     * const port = await sdk.port.getPort();
+     * app.listen(port);
+     * ```
+     */
+    getPort(): Promise<number>;
+}
+
 /**
  * RealtimeX Local App SDK
  *
@@ -154,6 +224,8 @@ declare class RealtimeXSDK {
     activities: ActivitiesModule;
     webhook: WebhookModule;
     api: ApiModule;
+    task: TaskModule;
+    port: PortModule;
     readonly appId: string;
     readonly appName: string | undefined;
     private static DEFAULT_REALTIMEX_URL;
@@ -164,4 +236,4 @@ declare class RealtimeXSDK {
     private getEnvVar;
 }
 
-export { ActivitiesModule, type Activity, type Agent, ApiModule, RealtimeXSDK, type SDKConfig, type Task, type TaskRun, type Thread, type TriggerAgentPayload, type TriggerAgentResponse, WebhookModule, type Workspace };
+export { ActivitiesModule, type Activity, type Agent, ApiModule, PortModule, RealtimeXSDK, type SDKConfig, type Task, TaskModule, type TaskRun, type Thread, type TriggerAgentPayload, type TriggerAgentResponse, WebhookModule, type Workspace };

package/dist/index.js

@@ -1,7 +1,9 @@
 "use strict";
+var __create = Object.create;
 var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
 var __export = (target, all) => {
   for (var name in all)
@@ -15,6 +17,14 @@ var __copyProps = (to, from, except, desc) => {
   }
   return to;
 };
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 
 // src/index.ts
@@ -22,7 +32,9 @@ var index_exports = {};
 __export(index_exports, {
   ActivitiesModule: () => ActivitiesModule,
   ApiModule: () => ApiModule,
+  PortModule: () => PortModule,
   RealtimeXSDK: () => RealtimeXSDK,
+  TaskModule: () => TaskModule,
   WebhookModule: () => WebhookModule
 });
 module.exports = __toCommonJS(index_exports);
@@ -187,6 +199,117 @@ var ApiModule = class {
   }
 };
 
+// src/modules/task.ts
+var TaskModule = class {
+  constructor(realtimexUrl, appName, appId) {
+    this.realtimexUrl = realtimexUrl.replace(/\/$/, "");
+    this.appName = appName;
+    this.appId = appId;
+  }
+  /**
+   * Mark task as processing
+   */
+  async start(taskUuid, machineId) {
+    return this._sendEvent("task-start", taskUuid, { machine_id: machineId });
+  }
+  /**
+   * Mark task as completed with result
+   */
+  async complete(taskUuid, result, machineId) {
+    return this._sendEvent("task-complete", taskUuid, { result, machine_id: machineId });
+  }
+  /**
+   * Mark task as failed with error
+   */
+  async fail(taskUuid, error, machineId) {
+    return this._sendEvent("task-fail", taskUuid, { error, machine_id: machineId });
+  }
+  async _sendEvent(event, taskUuid, extra) {
+    const response = await fetch(`${this.realtimexUrl}/webhooks/realtimex`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        app_name: this.appName,
+        app_id: this.appId,
+        event,
+        payload: {
+          task_uuid: taskUuid,
+          ...extra
+        }
+      })
+    });
+    const data = await response.json();
+    if (!response.ok) throw new Error(data.error || `Failed to ${event}`);
+    return data;
+  }
+};
+
+// src/modules/port.ts
+var net = __toESM(require("net"));
+var PortModule = class {
+  constructor(defaultPort = 8080) {
+    this.defaultPort = defaultPort;
+  }
+  /**
+   * Get suggested port from environment (RTX_PORT) or default
+   */
+  getSuggestedPort() {
+    const envPort = process.env.RTX_PORT;
+    return envPort ? parseInt(envPort, 10) : this.defaultPort;
+  }
+  /**
+   * Check if a port is available
+   * @param port - Port number to check
+   * @returns Promise resolving to true if port is available
+   */
+  async isPortAvailable(port) {
+    return new Promise((resolve) => {
+      const server = net.createServer();
+      server.once("error", () => resolve(false));
+      server.once("listening", () => {
+        server.close();
+        resolve(true);
+      });
+      server.listen(port, "127.0.0.1");
+    });
+  }
+  /**
+   * Find an available port starting from the suggested port
+   * @param startPort - Starting port number (default: RTX_PORT or defaultPort)
+   * @param maxAttempts - Maximum ports to try (default: 100)
+   * @returns Promise resolving to an available port number
+   * @throws Error if no available port found in range
+   */
+  async findAvailablePort(startPort, maxAttempts = 100) {
+    const port = startPort ?? this.getSuggestedPort();
+    for (let i = 0; i < maxAttempts; i++) {
+      const currentPort = port + i;
+      if (await this.isPortAvailable(currentPort)) {
+        return currentPort;
+      }
+    }
+    throw new Error(`No available port found in range ${port}-${port + maxAttempts - 1}`);
+  }
+  /**
+   * Get a ready-to-use port
+   * Returns the suggested port if available, otherwise finds the next available port
+   * 
+   * @example
+   * ```typescript
+   * const sdk = new RealtimeXSDK();
+   * const port = await sdk.port.getPort();
+   * app.listen(port);
+   * ```
+   */
+  async getPort() {
+    const suggested = this.getSuggestedPort();
+    if (await this.isPortAvailable(suggested)) {
+      return suggested;
+    }
+    return this.findAvailablePort(suggested + 1);
+  }
+};
+
 // src/index.ts
 var _RealtimeXSDK = class _RealtimeXSDK {
   constructor(config = {}) {
@@ -198,6 +321,8 @@ var _RealtimeXSDK = class _RealtimeXSDK {
     this.activities = new ActivitiesModule(realtimexUrl, this.appId);
     this.webhook = new WebhookModule(realtimexUrl, this.appName, this.appId);
     this.api = new ApiModule(realtimexUrl);
+    this.task = new TaskModule(realtimexUrl, this.appName, this.appId);
+    this.port = new PortModule(config.defaultPort);
   }
   /**
    * Get environment variable (works in Node.js and browser)
@@ -218,6 +343,8 @@ var RealtimeXSDK = _RealtimeXSDK;
 0 && (module.exports = {
   ActivitiesModule,
   ApiModule,
+  PortModule,
   RealtimeXSDK,
+  TaskModule,
   WebhookModule
 });

package/dist/index.mjs

@@ -158,6 +158,117 @@ var ApiModule = class {
   }
 };
 
+// src/modules/task.ts
+var TaskModule = class {
+  constructor(realtimexUrl, appName, appId) {
+    this.realtimexUrl = realtimexUrl.replace(/\/$/, "");
+    this.appName = appName;
+    this.appId = appId;
+  }
+  /**
+   * Mark task as processing
+   */
+  async start(taskUuid, machineId) {
+    return this._sendEvent("task-start", taskUuid, { machine_id: machineId });
+  }
+  /**
+   * Mark task as completed with result
+   */
+  async complete(taskUuid, result, machineId) {
+    return this._sendEvent("task-complete", taskUuid, { result, machine_id: machineId });
+  }
+  /**
+   * Mark task as failed with error
+   */
+  async fail(taskUuid, error, machineId) {
+    return this._sendEvent("task-fail", taskUuid, { error, machine_id: machineId });
+  }
+  async _sendEvent(event, taskUuid, extra) {
+    const response = await fetch(`${this.realtimexUrl}/webhooks/realtimex`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        app_name: this.appName,
+        app_id: this.appId,
+        event,
+        payload: {
+          task_uuid: taskUuid,
+          ...extra
+        }
+      })
+    });
+    const data = await response.json();
+    if (!response.ok) throw new Error(data.error || `Failed to ${event}`);
+    return data;
+  }
+};
+
+// src/modules/port.ts
+import * as net from "net";
+var PortModule = class {
+  constructor(defaultPort = 8080) {
+    this.defaultPort = defaultPort;
+  }
+  /**
+   * Get suggested port from environment (RTX_PORT) or default
+   */
+  getSuggestedPort() {
+    const envPort = process.env.RTX_PORT;
+    return envPort ? parseInt(envPort, 10) : this.defaultPort;
+  }
+  /**
+   * Check if a port is available
+   * @param port - Port number to check
+   * @returns Promise resolving to true if port is available
+   */
+  async isPortAvailable(port) {
+    return new Promise((resolve) => {
+      const server = net.createServer();
+      server.once("error", () => resolve(false));
+      server.once("listening", () => {
+        server.close();
+        resolve(true);
+      });
+      server.listen(port, "127.0.0.1");
+    });
+  }
+  /**
+   * Find an available port starting from the suggested port
+   * @param startPort - Starting port number (default: RTX_PORT or defaultPort)
+   * @param maxAttempts - Maximum ports to try (default: 100)
+   * @returns Promise resolving to an available port number
+   * @throws Error if no available port found in range
+   */
+  async findAvailablePort(startPort, maxAttempts = 100) {
+    const port = startPort ?? this.getSuggestedPort();
+    for (let i = 0; i < maxAttempts; i++) {
+      const currentPort = port + i;
+      if (await this.isPortAvailable(currentPort)) {
+        return currentPort;
+      }
+    }
+    throw new Error(`No available port found in range ${port}-${port + maxAttempts - 1}`);
+  }
+  /**
+   * Get a ready-to-use port
+   * Returns the suggested port if available, otherwise finds the next available port
+   * 
+   * @example
+   * ```typescript
+   * const sdk = new RealtimeXSDK();
+   * const port = await sdk.port.getPort();
+   * app.listen(port);
+   * ```
+   */
+  async getPort() {
+    const suggested = this.getSuggestedPort();
+    if (await this.isPortAvailable(suggested)) {
+      return suggested;
+    }
+    return this.findAvailablePort(suggested + 1);
+  }
+};
+
 // src/index.ts
 var _RealtimeXSDK = class _RealtimeXSDK {
   constructor(config = {}) {
@@ -169,6 +280,8 @@ var _RealtimeXSDK = class _RealtimeXSDK {
     this.activities = new ActivitiesModule(realtimexUrl, this.appId);
     this.webhook = new WebhookModule(realtimexUrl, this.appName, this.appId);
     this.api = new ApiModule(realtimexUrl);
+    this.task = new TaskModule(realtimexUrl, this.appName, this.appId);
+    this.port = new PortModule(config.defaultPort);
   }
   /**
    * Get environment variable (works in Node.js and browser)
@@ -188,6 +301,8 @@ var RealtimeXSDK = _RealtimeXSDK;
 export {
   ActivitiesModule,
   ApiModule,
+  PortModule,
   RealtimeXSDK,
+  TaskModule,
   WebhookModule
 };

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@realtimex/sdk",
-    "version": "1.0.4",
+    "version": "1.0.6",
     "description": "SDK for building Local Apps that integrate with RealtimeX",
     "main": "dist/index.js",
     "module": "dist/index.mjs",