@realtimex/sdk 1.0.5 → 1.0.7

package/dist/index.d.mts

@@ -7,6 +7,7 @@ interface SDKConfig {
         appId?: string;
         appName?: string;
     };
+    defaultPort?: number;
 }
 interface Activity {
     id: string;
@@ -173,6 +174,49 @@ declare class TaskModule {
     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 on a specific host
+     */
+    private isPortAvailableOn;
+    /**
+     * Check if a port is available (checks both IPv4 and IPv6)
+     * @param port - Port number to check
+     * @returns Promise resolving to true if port is available on ALL interfaces
+     */
+    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
  *
@@ -185,6 +229,7 @@ declare class RealtimeXSDK {
     webhook: WebhookModule;
     api: ApiModule;
     task: TaskModule;
+    port: PortModule;
     readonly appId: string;
     readonly appName: string | undefined;
     private static DEFAULT_REALTIMEX_URL;
@@ -195,4 +240,4 @@ declare class RealtimeXSDK {
     private getEnvVar;
 }
 
-export { ActivitiesModule, type Activity, type Agent, ApiModule, RealtimeXSDK, type SDKConfig, type Task, TaskModule, 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;
@@ -173,6 +174,49 @@ declare class TaskModule {
     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 on a specific host
+     */
+    private isPortAvailableOn;
+    /**
+     * Check if a port is available (checks both IPv4 and IPv6)
+     * @param port - Port number to check
+     * @returns Promise resolving to true if port is available on ALL interfaces
+     */
+    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
  *
@@ -185,6 +229,7 @@ declare class RealtimeXSDK {
     webhook: WebhookModule;
     api: ApiModule;
     task: TaskModule;
+    port: PortModule;
     readonly appId: string;
     readonly appName: string | undefined;
     private static DEFAULT_REALTIMEX_URL;
@@ -195,4 +240,4 @@ declare class RealtimeXSDK {
     private getEnvVar;
 }
 
-export { ActivitiesModule, type Activity, type Agent, ApiModule, RealtimeXSDK, type SDKConfig, type Task, TaskModule, 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,6 +32,7 @@ var index_exports = {};
 __export(index_exports, {
   ActivitiesModule: () => ActivitiesModule,
   ApiModule: () => ApiModule,
+  PortModule: () => PortModule,
   RealtimeXSDK: () => RealtimeXSDK,
   TaskModule: () => TaskModule,
   WebhookModule: () => WebhookModule
@@ -233,6 +244,83 @@ var TaskModule = class {
   }
 };
 
+// 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 on a specific host
+   */
+  async isPortAvailableOn(port, host) {
+    return new Promise((resolve) => {
+      const server = net.createServer();
+      server.once("error", () => resolve(false));
+      server.once("listening", () => {
+        server.close();
+        resolve(true);
+      });
+      server.listen(port, host);
+    });
+  }
+  /**
+   * Check if a port is available (checks both IPv4 and IPv6)
+   * @param port - Port number to check
+   * @returns Promise resolving to true if port is available on ALL interfaces
+   */
+  async isPortAvailable(port) {
+    const ipv4Available = await this.isPortAvailableOn(port, "127.0.0.1");
+    if (!ipv4Available) return false;
+    const ipv6Available = await this.isPortAvailableOn(port, "::1");
+    if (!ipv6Available) return false;
+    const allInterfacesAvailable = await this.isPortAvailableOn(port, "0.0.0.0");
+    return allInterfacesAvailable;
+  }
+  /**
+   * 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 = {}) {
@@ -245,6 +333,7 @@ var _RealtimeXSDK = class _RealtimeXSDK {
     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)
@@ -265,6 +354,7 @@ var RealtimeXSDK = _RealtimeXSDK;
 0 && (module.exports = {
   ActivitiesModule,
   ApiModule,
+  PortModule,
   RealtimeXSDK,
   TaskModule,
   WebhookModule

package/dist/index.mjs

@@ -203,6 +203,83 @@ var TaskModule = class {
   }
 };
 
+// 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 on a specific host
+   */
+  async isPortAvailableOn(port, host) {
+    return new Promise((resolve) => {
+      const server = net.createServer();
+      server.once("error", () => resolve(false));
+      server.once("listening", () => {
+        server.close();
+        resolve(true);
+      });
+      server.listen(port, host);
+    });
+  }
+  /**
+   * Check if a port is available (checks both IPv4 and IPv6)
+   * @param port - Port number to check
+   * @returns Promise resolving to true if port is available on ALL interfaces
+   */
+  async isPortAvailable(port) {
+    const ipv4Available = await this.isPortAvailableOn(port, "127.0.0.1");
+    if (!ipv4Available) return false;
+    const ipv6Available = await this.isPortAvailableOn(port, "::1");
+    if (!ipv6Available) return false;
+    const allInterfacesAvailable = await this.isPortAvailableOn(port, "0.0.0.0");
+    return allInterfacesAvailable;
+  }
+  /**
+   * 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 = {}) {
@@ -215,6 +292,7 @@ var _RealtimeXSDK = class _RealtimeXSDK {
     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)
@@ -234,6 +312,7 @@ var RealtimeXSDK = _RealtimeXSDK;
 export {
   ActivitiesModule,
   ApiModule,
+  PortModule,
   RealtimeXSDK,
   TaskModule,
   WebhookModule

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@realtimex/sdk",
-    "version": "1.0.5",
+    "version": "1.0.7",
     "description": "SDK for building Local Apps that integrate with RealtimeX",
     "main": "dist/index.js",
     "module": "dist/index.mjs",
@@ -40,4 +40,4 @@
     "engines": {
         "node": ">=18.0.0"
     }
-}
+}