@sayna-ai/node-sdk 0.0.12 → 0.0.14

package/README.md

@@ -138,7 +138,7 @@ Retrieves all configured SIP webhook hooks from the runtime cache.
 ```typescript
 const response = await client.getSipHooks();
 for (const hook of response.hooks) {
-  console.log(`Host: ${hook.host}, URL: ${hook.url}`);
+  console.log(`Host: ${hook.host}, URL: ${hook.url}, Auth ID: ${hook.auth_id}`);
 }
 ```
 
@@ -152,10 +152,11 @@ Sets or updates SIP webhook hooks in the runtime cache. Hooks with matching host
 
 Each `SipHook` object contains:
 
-| field  | type     | description                             |
-| ------ | -------- | --------------------------------------- |
-| `host` | `string` | SIP domain pattern (case-insensitive).  |
-| `url`  | `string` | HTTPS URL to forward webhook events to. |
+| field     | type     | description                                                                                                           |
+| --------- | -------- | --------------------------------------------------------------------------------------------------------------------- |
+| `host`    | `string` | SIP domain pattern (case-insensitive).                                                                                |
+| `url`     | `string` | HTTPS URL to forward webhook events to.                                                                               |
+| `auth_id` | `string` | Tenant identifier for this hook. Required but may be empty for unauthenticated mode. Treat as opaque; pass unchanged. |
 
 **Returns**: `Promise<SipHooksResponse>` - Object containing the merged list of all configured hooks.
 
@@ -163,14 +164,48 @@ Each `SipHook` object contains:
 
 ```typescript
 const response = await client.setSipHooks([
-  { host: "example.com", url: "https://webhook.example.com/events" },
-  { host: "another.com", url: "https://webhook.another.com/events" },
+  {
+    host: "example.com",
+    url: "https://webhook.example.com/events",
+    auth_id: "tenant-123",
+  },
+  {
+    host: "another.com",
+    url: "https://webhook.another.com/events",
+    auth_id: "",
+  }, // Empty for unauthenticated mode
 ]);
 console.log("Total hooks configured:", response.hooks.length);
 ```
 
 ---
 
+### Room Ownership and Access
+
+When authentication is enabled, the server enforces room-level access control:
+
+- **Room names are clean**: The SDK does not rewrite or prefix room names. Pass room names as-is.
+- **Room listings are scoped**: `getLiveKitRooms()` returns only rooms accessible to your authenticated context.
+- **403 on token requests**: `getLiveKitToken()` returns a 403 error if the room exists but is owned by another tenant. Do not retry with a modified room name.
+- **404 masks access denial**: For room-scoped operations (`getLiveKitRoom()`, `removeLiveKitParticipant()`, `muteLiveKitParticipantTrack()`, `sipTransferRest()`), a 404 response can mean "not found" or "not accessible."
+- **Inbound SIP rooms**: Rooms created by inbound SIP calls are owned by the routing configuration's `auth_id`. Access depends on your authentication context.
+- **WebSocket errors**: Ownership/access errors during WebSocket configuration are surfaced via the error callback. Retry with the correct room name if needed.
+
+Errors include HTTP status and endpoint information for easier debugging:
+
+```typescript
+try {
+  await client.getLiveKitToken("some-room", "user", "user-123");
+} catch (error) {
+  if (error instanceof SaynaServerError) {
+    console.log(`Status: ${error.status}, Endpoint: ${error.endpoint}`);
+    // Status: 403, Endpoint: livekit/token
+  }
+}
+```
+
+---
+
 ### WebSocket API Methods
 
 These methods require an active WebSocket connection:

package/dist/errors.d.ts

@@ -30,9 +30,25 @@ export declare class SaynaValidationError extends SaynaError {
     constructor(message: string);
 }
 /**
- * Error thrown when the server returns an error.
+ * Error thrown when the server returns an error response.
+ *
+ * For REST API calls, the `status` and `endpoint` fields provide context about
+ * which request failed and with what HTTP status code. Common status codes:
+ * - 403: Access denied (e.g., room owned by another tenant on /livekit/token)
+ * - 404: Not found or not accessible (masked access denial for room-scoped operations)
+ * - 500: Internal server error
  */
 export declare class SaynaServerError extends SaynaError {
-    constructor(message: string);
+    /**
+     * HTTP status code returned by the server, if available.
+     * Set for REST API errors; undefined for WebSocket errors.
+     */
+    readonly status?: number;
+    /**
+     * API endpoint that returned the error, if available.
+     * Set for REST API errors; undefined for WebSocket errors.
+     */
+    readonly endpoint?: string;
+    constructor(message: string, status?: number, endpoint?: string);
 }
 //# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,qBAAa,UAAW,SAAQ,KAAK;gBACvB,OAAO,EAAE,MAAM;CAK5B;AAED;;GAEG;AACH,qBAAa,sBAAuB,SAAQ,UAAU;gBACxC,OAAO,GAAE,MAA2C;CAKjE;AAED;;GAEG;AACH,qBAAa,kBAAmB,SAAQ,UAAU;gBAE9C,OAAO,GAAE,MAA0F;CAMtG;AAED;;GAEG;AACH,qBAAa,oBAAqB,SAAQ,UAAU;IAClD,SAAyB,KAAK,CAAC,EAAE,OAAO,CAAC;gBAE7B,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,OAAO;CAM7C;AAED;;GAEG;AACH,qBAAa,oBAAqB,SAAQ,UAAU;gBACtC,OAAO,EAAE,MAAM;CAK5B;AAED;;GAEG;AACH,qBAAa,gBAAiB,SAAQ,UAAU;gBAClC,OAAO,EAAE,MAAM;CAK5B"}
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,qBAAa,UAAW,SAAQ,KAAK;gBACvB,OAAO,EAAE,MAAM;CAK5B;AAED;;GAEG;AACH,qBAAa,sBAAuB,SAAQ,UAAU;gBACxC,OAAO,GAAE,MAA2C;CAKjE;AAED;;GAEG;AACH,qBAAa,kBAAmB,SAAQ,UAAU;gBAE9C,OAAO,GAAE,MAA0F;CAMtG;AAED;;GAEG;AACH,qBAAa,oBAAqB,SAAQ,UAAU;IAClD,SAAyB,KAAK,CAAC,EAAE,OAAO,CAAC;gBAE7B,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,OAAO;CAM7C;AAED;;GAEG;AACH,qBAAa,oBAAqB,SAAQ,UAAU;gBACtC,OAAO,EAAE,MAAM;CAK5B;AAED;;;;;;;;GAQG;AACH,qBAAa,gBAAiB,SAAQ,UAAU;IAC9C;;;OAGG;IACH,SAAgB,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhC;;;OAGG;IACH,SAAgB,QAAQ,CAAC,EAAE,MAAM,CAAC;gBAEtB,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM;CAOhE"}