@realtimex/sdk 1.0.8 → 1.0.9

package/README.md

@@ -24,8 +24,9 @@ Before using this SDK, ensure your Supabase database is set up:
 ```typescript
 import { RealtimeXSDK } from '@realtimex/sdk';
 
-// No config needed - RTX_APP_ID is auto-detected from environment
-const sdk = new RealtimeXSDK();
+const sdk = new RealtimeXSDK({
+  permissions: ['activities.read', 'activities.write', 'webhook.trigger']
+});
 
 // Insert activity
 const activity = await sdk.activities.insert({

package/dist/index.d.mts

@@ -8,6 +8,7 @@ interface SDKConfig {
         appName?: string;
     };
     defaultPort?: number;
+    permissions?: string[];
 }
 interface Activity {
     id: string;
@@ -86,7 +87,12 @@ interface Task {
 declare class ActivitiesModule {
     private baseUrl;
     private appId;
-    constructor(realtimexUrl: string, appId: string);
+    private appName;
+    constructor(realtimexUrl: string, appId: string, appName?: string);
+    /**
+     * Request a single permission from Electron via internal API
+     */
+    private requestPermission;
     private request;
     /**
      * Insert a new activity
@@ -114,15 +120,16 @@ declare class ActivitiesModule {
     }): Promise<Activity[]>;
 }
 
-/**
- * Webhook Module - Call RealtimeX webhook
- */
-
 declare class WebhookModule {
     private realtimexUrl;
     private appName?;
     private appId?;
     constructor(realtimexUrl: string, appName?: string, appId?: string);
+    /**
+     * Request a single permission from Electron via internal API
+     */
+    private requestPermission;
+    private request;
     triggerAgent(payload: TriggerAgentPayload): Promise<TriggerAgentResponse>;
     ping(): Promise<{
         success: boolean;
@@ -135,11 +142,34 @@ declare class WebhookModule {
  * API Module - Call RealtimeX public APIs
  */
 
+/**
+ * Error thrown when a permission is permanently denied
+ */
+declare class PermissionDeniedError extends Error {
+    readonly permission: string;
+    constructor(permission: string, message?: string);
+}
+/**
+ * Error thrown when a permission needs to be granted
+ */
+declare class PermissionRequiredError extends Error {
+    readonly permission: string;
+    constructor(permission: string, message?: string);
+}
 declare class ApiModule {
     private realtimexUrl;
     private appId;
-    constructor(realtimexUrl: string, appId: string);
+    private appName;
+    constructor(realtimexUrl: string, appId: string, appName?: string);
     private getHeaders;
+    /**
+     * Request a single permission from Electron via internal API
+     */
+    private requestPermission;
+    /**
+     * Make an API call with automatic permission handling
+     */
+    private apiCall;
     getAgents(): Promise<Agent[]>;
     getWorkspaces(): Promise<Workspace[]>;
     getThreads(workspaceSlug: string): Promise<Thread[]>;
@@ -234,12 +264,19 @@ declare class RealtimeXSDK {
     port: PortModule;
     readonly appId: string;
     readonly appName: string | undefined;
+    private readonly realtimexUrl;
+    private readonly permissions;
     private static DEFAULT_REALTIMEX_URL;
     constructor(config?: SDKConfig);
+    /**
+     * Register app with RealtimeX hub and request declared permissions upfront.
+     * This is called automatically if permissions are provided in constructor.
+     */
+    register(permissions?: string[]): Promise<void>;
     /**
      * Get environment variable (works in Node.js and browser)
      */
     private getEnvVar;
 }
 
-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 };
+export { ActivitiesModule, type Activity, type Agent, ApiModule, PermissionDeniedError, PermissionRequiredError, PortModule, RealtimeXSDK, type SDKConfig, type Task, TaskModule, type TaskRun, type Thread, type TriggerAgentPayload, type TriggerAgentResponse, WebhookModule, type Workspace };

package/dist/index.d.ts

@@ -8,6 +8,7 @@ interface SDKConfig {
         appName?: string;
     };
     defaultPort?: number;
+    permissions?: string[];
 }
 interface Activity {
     id: string;
@@ -86,7 +87,12 @@ interface Task {
 declare class ActivitiesModule {
     private baseUrl;
     private appId;
-    constructor(realtimexUrl: string, appId: string);
+    private appName;
+    constructor(realtimexUrl: string, appId: string, appName?: string);
+    /**
+     * Request a single permission from Electron via internal API
+     */
+    private requestPermission;
     private request;
     /**
      * Insert a new activity
@@ -114,15 +120,16 @@ declare class ActivitiesModule {
     }): Promise<Activity[]>;
 }
 
-/**
- * Webhook Module - Call RealtimeX webhook
- */
-
 declare class WebhookModule {
     private realtimexUrl;
     private appName?;
     private appId?;
     constructor(realtimexUrl: string, appName?: string, appId?: string);
+    /**
+     * Request a single permission from Electron via internal API
+     */
+    private requestPermission;
+    private request;
     triggerAgent(payload: TriggerAgentPayload): Promise<TriggerAgentResponse>;
     ping(): Promise<{
         success: boolean;
@@ -135,11 +142,34 @@ declare class WebhookModule {
  * API Module - Call RealtimeX public APIs
  */
 
+/**
+ * Error thrown when a permission is permanently denied
+ */
+declare class PermissionDeniedError extends Error {
+    readonly permission: string;
+    constructor(permission: string, message?: string);
+}
+/**
+ * Error thrown when a permission needs to be granted
+ */
+declare class PermissionRequiredError extends Error {
+    readonly permission: string;
+    constructor(permission: string, message?: string);
+}
 declare class ApiModule {
     private realtimexUrl;
     private appId;
-    constructor(realtimexUrl: string, appId: string);
+    private appName;
+    constructor(realtimexUrl: string, appId: string, appName?: string);
     private getHeaders;
+    /**
+     * Request a single permission from Electron via internal API
+     */
+    private requestPermission;
+    /**
+     * Make an API call with automatic permission handling
+     */
+    private apiCall;
     getAgents(): Promise<Agent[]>;
     getWorkspaces(): Promise<Workspace[]>;
     getThreads(workspaceSlug: string): Promise<Thread[]>;
@@ -234,12 +264,19 @@ declare class RealtimeXSDK {
     port: PortModule;
     readonly appId: string;
     readonly appName: string | undefined;
+    private readonly realtimexUrl;
+    private readonly permissions;
     private static DEFAULT_REALTIMEX_URL;
     constructor(config?: SDKConfig);
+    /**
+     * Register app with RealtimeX hub and request declared permissions upfront.
+     * This is called automatically if permissions are provided in constructor.
+     */
+    register(permissions?: string[]): Promise<void>;
     /**
      * Get environment variable (works in Node.js and browser)
      */
     private getEnvVar;
 }
 
-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 };
+export { ActivitiesModule, type Activity, type Agent, ApiModule, PermissionDeniedError, PermissionRequiredError, PortModule, RealtimeXSDK, type SDKConfig, type Task, TaskModule, type TaskRun, type Thread, type TriggerAgentPayload, type TriggerAgentResponse, WebhookModule, type Workspace };

package/dist/index.js

@@ -32,6 +32,8 @@ var index_exports = {};
 __export(index_exports, {
   ActivitiesModule: () => ActivitiesModule,
   ApiModule: () => ApiModule,
+  PermissionDeniedError: () => PermissionDeniedError,
+  PermissionRequiredError: () => PermissionRequiredError,
   PortModule: () => PortModule,
   RealtimeXSDK: () => RealtimeXSDK,
   TaskModule: () => TaskModule,
@@ -39,11 +41,131 @@ __export(index_exports, {
 });
 module.exports = __toCommonJS(index_exports);
 
+// src/modules/api.ts
+var PermissionDeniedError = class extends Error {
+  constructor(permission, message) {
+    super(message || `Permission '${permission}' was denied`);
+    this.name = "PermissionDeniedError";
+    this.permission = permission;
+  }
+};
+var PermissionRequiredError = class extends Error {
+  constructor(permission, message) {
+    super(message || `Permission '${permission}' is required`);
+    this.name = "PermissionRequiredError";
+    this.permission = permission;
+  }
+};
+var ApiModule = class {
+  constructor(realtimexUrl, appId, appName) {
+    this.realtimexUrl = realtimexUrl.replace(/\/$/, "");
+    this.appId = appId;
+    this.appName = appName || process.env.RTX_APP_NAME || "Local App";
+  }
+  getHeaders() {
+    return {
+      "Content-Type": "application/json",
+      "x-app-id": this.appId
+    };
+  }
+  /**
+   * Request a single permission from Electron via internal API
+   */
+  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 (error) {
+      return false;
+    }
+  }
+  /**
+   * Make an API call with automatic permission handling
+   */
+  async apiCall(method, endpoint, options) {
+    const url = `${this.realtimexUrl}${endpoint}`;
+    const response = await fetch(url, {
+      method,
+      headers: this.getHeaders(),
+      ...options
+    });
+    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.apiCall(method, endpoint, options);
+        } else {
+          throw new PermissionDeniedError(permission, message);
+        }
+      }
+      if (errorCode === "PERMISSION_DENIED") {
+        throw new PermissionDeniedError(permission, message);
+      }
+      throw new Error(data.error || "Permission denied");
+    }
+    if (!response.ok) {
+      throw new Error(data.error || `API call failed: ${response.status}`);
+    }
+    return data;
+  }
+  async getAgents() {
+    const data = await this.apiCall("GET", "/agents");
+    return data.agents;
+  }
+  async getWorkspaces() {
+    const data = await this.apiCall("GET", "/workspaces");
+    return data.workspaces;
+  }
+  async getThreads(workspaceSlug) {
+    const data = await this.apiCall("GET", `/workspaces/${encodeURIComponent(workspaceSlug)}/threads`);
+    return data.threads;
+  }
+  async getTask(taskUuid) {
+    const data = await this.apiCall("GET", `/task/${encodeURIComponent(taskUuid)}`);
+    return { ...data.task, runs: data.runs };
+  }
+};
+
 // src/modules/activities.ts
 var ActivitiesModule = class {
-  constructor(realtimexUrl, appId) {
+  constructor(realtimexUrl, appId, appName) {
     this.baseUrl = realtimexUrl.replace(/\/$/, "");
     this.appId = appId;
+    this.appName = appName || process.env.RTX_APP_NAME || "Local App";
+  }
+  /**
+   * Request a single permission from Electron via internal API
+   */
+  async requestPermission(permission) {
+    try {
+      const response = await fetch(`${this.baseUrl}/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 (error) {
+      console.error("[SDK] Permission request failed:", error);
+      return false;
+    }
   }
   async request(path, options = {}) {
     const url = `${this.baseUrl}${path}`;
@@ -61,6 +183,22 @@ var ActivitiesModule = class {
       }
     });
     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, options);
+        } else {
+          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}`);
     }
@@ -127,13 +265,64 @@ var WebhookModule = class {
     this.appName = appName;
     this.appId = appId;
   }
+  /**
+   * Request a single permission from Electron via internal API
+   */
+  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 (error) {
+      console.error("[SDK] Permission request failed:", error);
+      return false;
+    }
+  }
+  async request(path, options = {}) {
+    const url = `${this.realtimexUrl}${path}`;
+    const response = await fetch(url, {
+      ...options,
+      headers: {
+        "Content-Type": "application/json",
+        ...options.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, options);
+        } else {
+          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 triggerAgent(payload) {
     if (payload.auto_run && (!payload.agent_name || !payload.workspace_slug)) {
       throw new Error("auto_run requires agent_name and workspace_slug");
     }
-    const response = await fetch(`${this.realtimexUrl}/webhooks/realtimex`, {
+    return this.request("/webhooks/realtimex", {
       method: "POST",
-      headers: { "Content-Type": "application/json" },
       body: JSON.stringify({
         app_name: this.appName,
         app_id: this.appId,
@@ -148,69 +337,16 @@ var WebhookModule = class {
         }
       })
     });
-    const data = await response.json();
-    if (!response.ok) throw new Error(data.error || "Failed to trigger agent");
-    return data;
   }
   async ping() {
-    const response = await fetch(`${this.realtimexUrl}/webhooks/realtimex`, {
+    return this.request("/webhooks/realtimex", {
       method: "POST",
-      headers: { "Content-Type": "application/json" },
       body: JSON.stringify({
         app_name: this.appName,
         app_id: this.appId,
         event: "ping"
       })
     });
-    const data = await response.json();
-    if (!response.ok) throw new Error(data.error || "Ping failed");
-    return data;
-  }
-};
-
-// src/modules/api.ts
-var ApiModule = class {
-  constructor(realtimexUrl, appId) {
-    this.realtimexUrl = realtimexUrl.replace(/\/$/, "");
-    this.appId = appId;
-  }
-  getHeaders() {
-    return {
-      "Content-Type": "application/json",
-      "x-app-id": this.appId
-    };
-  }
-  async getAgents() {
-    const response = await fetch(`${this.realtimexUrl}/agents`, {
-      headers: this.getHeaders()
-    });
-    const data = await response.json();
-    if (!response.ok) throw new Error(data.error || "Failed to get agents");
-    return data.agents;
-  }
-  async getWorkspaces() {
-    const response = await fetch(`${this.realtimexUrl}/workspaces`, {
-      headers: this.getHeaders()
-    });
-    const data = await response.json();
-    if (!response.ok) throw new Error(data.error || "Failed to get workspaces");
-    return data.workspaces;
-  }
-  async getThreads(workspaceSlug) {
-    const response = await fetch(`${this.realtimexUrl}/workspaces/${encodeURIComponent(workspaceSlug)}/threads`, {
-      headers: this.getHeaders()
-    });
-    const data = await response.json();
-    if (!response.ok) throw new Error(data.error || "Failed to get threads");
-    return data.threads;
-  }
-  async getTask(taskUuid) {
-    const response = await fetch(`${this.realtimexUrl}/task/${encodeURIComponent(taskUuid)}`, {
-      headers: this.getHeaders()
-    });
-    const data = await response.json();
-    if (!response.ok) throw new Error(data.error || "Failed to get task");
-    return { ...data.task, runs: data.runs };
   }
 };
 
@@ -343,12 +479,44 @@ var _RealtimeXSDK = class _RealtimeXSDK {
     const envAppName = this.getEnvVar("RTX_APP_NAME");
     this.appId = config.realtimex?.appId || envAppId || "";
     this.appName = config.realtimex?.appName || envAppName;
-    const realtimexUrl = config.realtimex?.url || _RealtimeXSDK.DEFAULT_REALTIMEX_URL;
-    this.activities = new ActivitiesModule(realtimexUrl, this.appId);
-    this.webhook = new WebhookModule(realtimexUrl, this.appName, this.appId);
-    this.api = new ApiModule(realtimexUrl, this.appId);
-    this.task = new TaskModule(realtimexUrl, this.appName, this.appId);
+    this.permissions = config.permissions || [];
+    this.realtimexUrl = config.realtimex?.url || _RealtimeXSDK.DEFAULT_REALTIMEX_URL;
+    this.activities = new ActivitiesModule(this.realtimexUrl, this.appId, this.appName);
+    this.webhook = new WebhookModule(this.realtimexUrl, this.appName, this.appId);
+    this.api = new ApiModule(this.realtimexUrl, this.appId, this.appName);
+    this.task = new TaskModule(this.realtimexUrl, this.appName, this.appId);
     this.port = new PortModule(config.defaultPort);
+    if (this.permissions.length > 0) {
+      this.register().catch((err) => {
+        console.error("[RealtimeX SDK] Auto-registration failed:", err.message);
+      });
+    }
+  }
+  /**
+   * Register app with RealtimeX hub and request declared permissions upfront.
+   * This is called automatically if permissions are provided in constructor.
+   */
+  async register(permissions) {
+    const perms = permissions || this.permissions;
+    if (perms.length === 0) return;
+    try {
+      const response = await fetch(`${this.realtimexUrl.replace(/\/$/, "")}/sdk/register`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+          app_id: this.appId,
+          app_name: this.appName,
+          permissions: perms
+        })
+      });
+      const data = await response.json();
+      if (!response.ok) {
+        throw new Error(data.error || "Registration failed");
+      }
+      console.log(`[RealtimeX SDK] App registered successfully (${data.message})`);
+    } catch (error) {
+      throw new Error(`Failed to register app: ${error.message}`);
+    }
   }
   /**
    * Get environment variable (works in Node.js and browser)
@@ -369,6 +537,8 @@ var RealtimeXSDK = _RealtimeXSDK;
 0 && (module.exports = {
   ActivitiesModule,
   ApiModule,
+  PermissionDeniedError,
+  PermissionRequiredError,
   PortModule,
   RealtimeXSDK,
   TaskModule,

package/dist/index.mjs

@@ -1,8 +1,128 @@
+// src/modules/api.ts
+var PermissionDeniedError = class extends Error {
+  constructor(permission, message) {
+    super(message || `Permission '${permission}' was denied`);
+    this.name = "PermissionDeniedError";
+    this.permission = permission;
+  }
+};
+var PermissionRequiredError = class extends Error {
+  constructor(permission, message) {
+    super(message || `Permission '${permission}' is required`);
+    this.name = "PermissionRequiredError";
+    this.permission = permission;
+  }
+};
+var ApiModule = class {
+  constructor(realtimexUrl, appId, appName) {
+    this.realtimexUrl = realtimexUrl.replace(/\/$/, "");
+    this.appId = appId;
+    this.appName = appName || process.env.RTX_APP_NAME || "Local App";
+  }
+  getHeaders() {
+    return {
+      "Content-Type": "application/json",
+      "x-app-id": this.appId
+    };
+  }
+  /**
+   * Request a single permission from Electron via internal API
+   */
+  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 (error) {
+      return false;
+    }
+  }
+  /**
+   * Make an API call with automatic permission handling
+   */
+  async apiCall(method, endpoint, options) {
+    const url = `${this.realtimexUrl}${endpoint}`;
+    const response = await fetch(url, {
+      method,
+      headers: this.getHeaders(),
+      ...options
+    });
+    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.apiCall(method, endpoint, options);
+        } else {
+          throw new PermissionDeniedError(permission, message);
+        }
+      }
+      if (errorCode === "PERMISSION_DENIED") {
+        throw new PermissionDeniedError(permission, message);
+      }
+      throw new Error(data.error || "Permission denied");
+    }
+    if (!response.ok) {
+      throw new Error(data.error || `API call failed: ${response.status}`);
+    }
+    return data;
+  }
+  async getAgents() {
+    const data = await this.apiCall("GET", "/agents");
+    return data.agents;
+  }
+  async getWorkspaces() {
+    const data = await this.apiCall("GET", "/workspaces");
+    return data.workspaces;
+  }
+  async getThreads(workspaceSlug) {
+    const data = await this.apiCall("GET", `/workspaces/${encodeURIComponent(workspaceSlug)}/threads`);
+    return data.threads;
+  }
+  async getTask(taskUuid) {
+    const data = await this.apiCall("GET", `/task/${encodeURIComponent(taskUuid)}`);
+    return { ...data.task, runs: data.runs };
+  }
+};
+
 // src/modules/activities.ts
 var ActivitiesModule = class {
-  constructor(realtimexUrl, appId) {
+  constructor(realtimexUrl, appId, appName) {
     this.baseUrl = realtimexUrl.replace(/\/$/, "");
     this.appId = appId;
+    this.appName = appName || process.env.RTX_APP_NAME || "Local App";
+  }
+  /**
+   * Request a single permission from Electron via internal API
+   */
+  async requestPermission(permission) {
+    try {
+      const response = await fetch(`${this.baseUrl}/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 (error) {
+      console.error("[SDK] Permission request failed:", error);
+      return false;
+    }
   }
   async request(path, options = {}) {
     const url = `${this.baseUrl}${path}`;
@@ -20,6 +140,22 @@ var ActivitiesModule = class {
       }
     });
     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, options);
+        } else {
+          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}`);
     }
@@ -86,13 +222,64 @@ var WebhookModule = class {
     this.appName = appName;
     this.appId = appId;
   }
+  /**
+   * Request a single permission from Electron via internal API
+   */
+  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 (error) {
+      console.error("[SDK] Permission request failed:", error);
+      return false;
+    }
+  }
+  async request(path, options = {}) {
+    const url = `${this.realtimexUrl}${path}`;
+    const response = await fetch(url, {
+      ...options,
+      headers: {
+        "Content-Type": "application/json",
+        ...options.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, options);
+        } else {
+          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 triggerAgent(payload) {
     if (payload.auto_run && (!payload.agent_name || !payload.workspace_slug)) {
       throw new Error("auto_run requires agent_name and workspace_slug");
     }
-    const response = await fetch(`${this.realtimexUrl}/webhooks/realtimex`, {
+    return this.request("/webhooks/realtimex", {
       method: "POST",
-      headers: { "Content-Type": "application/json" },
       body: JSON.stringify({
         app_name: this.appName,
         app_id: this.appId,
@@ -107,69 +294,16 @@ var WebhookModule = class {
         }
       })
     });
-    const data = await response.json();
-    if (!response.ok) throw new Error(data.error || "Failed to trigger agent");
-    return data;
   }
   async ping() {
-    const response = await fetch(`${this.realtimexUrl}/webhooks/realtimex`, {
+    return this.request("/webhooks/realtimex", {
       method: "POST",
-      headers: { "Content-Type": "application/json" },
       body: JSON.stringify({
         app_name: this.appName,
         app_id: this.appId,
         event: "ping"
       })
     });
-    const data = await response.json();
-    if (!response.ok) throw new Error(data.error || "Ping failed");
-    return data;
-  }
-};
-
-// src/modules/api.ts
-var ApiModule = class {
-  constructor(realtimexUrl, appId) {
-    this.realtimexUrl = realtimexUrl.replace(/\/$/, "");
-    this.appId = appId;
-  }
-  getHeaders() {
-    return {
-      "Content-Type": "application/json",
-      "x-app-id": this.appId
-    };
-  }
-  async getAgents() {
-    const response = await fetch(`${this.realtimexUrl}/agents`, {
-      headers: this.getHeaders()
-    });
-    const data = await response.json();
-    if (!response.ok) throw new Error(data.error || "Failed to get agents");
-    return data.agents;
-  }
-  async getWorkspaces() {
-    const response = await fetch(`${this.realtimexUrl}/workspaces`, {
-      headers: this.getHeaders()
-    });
-    const data = await response.json();
-    if (!response.ok) throw new Error(data.error || "Failed to get workspaces");
-    return data.workspaces;
-  }
-  async getThreads(workspaceSlug) {
-    const response = await fetch(`${this.realtimexUrl}/workspaces/${encodeURIComponent(workspaceSlug)}/threads`, {
-      headers: this.getHeaders()
-    });
-    const data = await response.json();
-    if (!response.ok) throw new Error(data.error || "Failed to get threads");
-    return data.threads;
-  }
-  async getTask(taskUuid) {
-    const response = await fetch(`${this.realtimexUrl}/task/${encodeURIComponent(taskUuid)}`, {
-      headers: this.getHeaders()
-    });
-    const data = await response.json();
-    if (!response.ok) throw new Error(data.error || "Failed to get task");
-    return { ...data.task, runs: data.runs };
   }
 };
 
@@ -302,12 +436,44 @@ var _RealtimeXSDK = class _RealtimeXSDK {
     const envAppName = this.getEnvVar("RTX_APP_NAME");
     this.appId = config.realtimex?.appId || envAppId || "";
     this.appName = config.realtimex?.appName || envAppName;
-    const realtimexUrl = config.realtimex?.url || _RealtimeXSDK.DEFAULT_REALTIMEX_URL;
-    this.activities = new ActivitiesModule(realtimexUrl, this.appId);
-    this.webhook = new WebhookModule(realtimexUrl, this.appName, this.appId);
-    this.api = new ApiModule(realtimexUrl, this.appId);
-    this.task = new TaskModule(realtimexUrl, this.appName, this.appId);
+    this.permissions = config.permissions || [];
+    this.realtimexUrl = config.realtimex?.url || _RealtimeXSDK.DEFAULT_REALTIMEX_URL;
+    this.activities = new ActivitiesModule(this.realtimexUrl, this.appId, this.appName);
+    this.webhook = new WebhookModule(this.realtimexUrl, this.appName, this.appId);
+    this.api = new ApiModule(this.realtimexUrl, this.appId, this.appName);
+    this.task = new TaskModule(this.realtimexUrl, this.appName, this.appId);
     this.port = new PortModule(config.defaultPort);
+    if (this.permissions.length > 0) {
+      this.register().catch((err) => {
+        console.error("[RealtimeX SDK] Auto-registration failed:", err.message);
+      });
+    }
+  }
+  /**
+   * Register app with RealtimeX hub and request declared permissions upfront.
+   * This is called automatically if permissions are provided in constructor.
+   */
+  async register(permissions) {
+    const perms = permissions || this.permissions;
+    if (perms.length === 0) return;
+    try {
+      const response = await fetch(`${this.realtimexUrl.replace(/\/$/, "")}/sdk/register`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+          app_id: this.appId,
+          app_name: this.appName,
+          permissions: perms
+        })
+      });
+      const data = await response.json();
+      if (!response.ok) {
+        throw new Error(data.error || "Registration failed");
+      }
+      console.log(`[RealtimeX SDK] App registered successfully (${data.message})`);
+    } catch (error) {
+      throw new Error(`Failed to register app: ${error.message}`);
+    }
   }
   /**
    * Get environment variable (works in Node.js and browser)
@@ -327,6 +493,8 @@ var RealtimeXSDK = _RealtimeXSDK;
 export {
   ActivitiesModule,
   ApiModule,
+  PermissionDeniedError,
+  PermissionRequiredError,
   PortModule,
   RealtimeXSDK,
   TaskModule,

package/package.json

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