@smarthivelabs-devs/hive-socket-node 1.0.0 → 1.1.0

package/README.md

@@ -1,6 +1,8 @@
 # @smarthivelabs-devs/hive-socket-node
 
-Node.js SDK for Hive-Socket — push real-time notifications and events to connected clients from any backend service.
+Node.js SDK for Hive-Socket — push real-time notifications and broadcast typed messages to connected clients from any backend service.
+
+> **v1.1.0** adds `hive.broadcast.toRoom()` for sending structured typed messages received by `useMessages()` on the client. Use this for full-duplex features (live competitions, collaborative editing, presence) where clients need to act on the payload, not just display a notification.
 
 ## Install
 
@@ -31,10 +33,13 @@ Add to your backend `.env`:
 
 ```env
 HIVE_SOCKET_URL=https://socket.smarthivelabs.dev
-HIVE_SOCKET_API_KEY=shai_hivesocket_<your-key>
+HIVE_SOCKET_API_KEY=shai_<your-key>          # same value as INTERNAL_API_KEY on the Hive-Socket server
+SMARTHIVE_PROJECT_ID=<your-auth-project-id>  # project ID from SmartHive Auth dashboard
 ```
 
-Get the API key from the Hive-Socket server's `.env` (`INTERNAL_API_KEY`).
+`HIVE_SOCKET_API_KEY` — copy the value of `INTERNAL_API_KEY` set on the Hive-Socket server. This is a shared secret between your backends and Hive-Socket.
+
+`SMARTHIVE_PROJECT_ID` — the project ID issued by SmartHive Auth when you registered your product. Pass this as `projectId` in every notify call so Hive-Socket scopes messages and notifications to the correct project.
 
 ---
 
@@ -50,7 +55,7 @@ const hive = createHiveSocketClient({
 
 // Push a notification to a user
 await hive.notify.user('user-id-123', {
-  projectId: 'your-project-id',
+  projectId: process.env.SMARTHIVE_PROJECT_ID!,
   title: 'New message',
   body: 'Alice sent you a message',
   type: 'message',
@@ -67,9 +72,9 @@ Creates a client instance. Create once and reuse across your application.
 
 ```typescript
 const hive = createHiveSocketClient({
-  baseUrl: 'https://socket.smarthivelabs.dev', // Hive-Socket server URL
-  apiKey: 'shai_hivesocket_...',               // Internal API key
-  timeout: 10_000,                             // Optional. Request timeout in ms. Default: 10000
+  baseUrl: process.env.HIVE_SOCKET_URL!,    // e.g. https://socket.smarthivelabs.dev
+  apiKey: process.env.HIVE_SOCKET_API_KEY!, // shai_* internal API key
+  timeout: 10_000,                          // Optional. Request timeout in ms. Default: 10000
 });
 ```
 
@@ -81,7 +86,7 @@ Push a notification to a specific user. Delivered instantly to all their connect
 
 ```typescript
 await hive.notify.user(userId, {
-  projectId: string,          // Your SmartHive project ID
+  projectId: string,          // SmartHive Auth project ID (process.env.SMARTHIVE_PROJECT_ID)
   title: string,              // Notification title
   body: string,               // Notification body
   type: NotificationType,     // 'info' | 'success' | 'warning' | 'error' | 'message'
@@ -93,7 +98,7 @@ await hive.notify.user(userId, {
 **Example — payment confirmed:**
 ```typescript
 await hive.notify.user(userId, {
-  projectId: 'workspace-project-id',
+  projectId: process.env.SMARTHIVE_PROJECT_ID!,
   title: 'Payment confirmed',
   body: `₦${amount.toLocaleString()} received`,
   type: 'success',
@@ -122,7 +127,7 @@ Broadcast a notification to all users currently in a room. Room notifications ar
 
 ```typescript
 await hive.notify.room(roomId, {
-  projectId: string,
+  projectId: string,          // SmartHive Auth project ID (process.env.SMARTHIVE_PROJECT_ID)
   title: string,
   body: string,
   type: NotificationType,
@@ -134,7 +139,7 @@ await hive.notify.room(roomId, {
 **Example — quiz started:**
 ```typescript
 await hive.notify.room(`course:${courseId}`, {
-  projectId: 'hivedemia-project-id',
+  projectId: process.env.SMARTHIVE_PROJECT_ID!,
   title: 'Quiz started',
   body: 'Chapter 3 quiz is now live',
   type: 'info',
@@ -145,7 +150,7 @@ await hive.notify.room(`course:${courseId}`, {
 **Example — live vote update:**
 ```typescript
 await hive.notify.room(`event:${eventId}`, {
-  projectId: 'votyhive-project-id',
+  projectId: process.env.SMARTHIVE_PROJECT_ID!,
   title: 'Results updated',
   body: 'New votes have been counted',
   type: 'info',
@@ -156,6 +161,40 @@ await hive.notify.room(`event:${eventId}`, {
 
 ---
 
+### `hive.broadcast.toRoom(roomId, payload)` *(v1.1.0)*
+
+Broadcast a typed structured message to all sockets in a room. Messages are received by clients via `useMessages(roomId)` — they arrive as `message:new` events, distinct from `notification:new` produced by `notify.*`. Use this for real-time game state, collaborative state changes, or any payload where the client needs to react to the message type programmatically.
+
+```typescript
+await hive.broadcast.toRoom(roomId, {
+  projectId: string,            // SmartHive Auth project ID
+  type: string,                 // your event type, e.g. "competition.question-change"
+  payload: Record<string, unknown>, // arbitrary JSON
+  senderId?: string,            // optional — defaults to "system"
+});
+```
+
+**Example — competition state advance:**
+```typescript
+await hive.broadcast.toRoom(`competition:${competitionId}`, {
+  projectId: process.env.SMARTHIVE_PROJECT_ID!,
+  type: 'competition.question-change',
+  payload: { questionIndex: 2, questionEndsAt: '2026-05-24T12:00:30.000Z' },
+  senderId: 'hivedemia-api',
+});
+```
+
+**Difference between `notify.room` and `broadcast.toRoom`:**
+
+| | `notify.room` | `broadcast.toRoom` |
+|---|---|---|
+| Client hook | `useNotifications()` | `useMessages(roomId)` |
+| Wire event | `notification:new` | `message:new` |
+| Persisted | Yes (offline delivery) | No (ephemeral) |
+| Best for | In-app alerts, toasts | Game state, live sync |
+
+---
+
 ### `hive.health()`
 
 Check server health and current connection count.
@@ -330,12 +369,46 @@ export async function POST(req: Request) {
 
 ---
 
+## Security
+
+### How the API key is sent and validated
+
+Every request from this SDK includes an `x-internal-api-key` header:
+
+```
+POST /notify/user
+x-internal-api-key: shai_<your-key>
+```
+
+The Hive-Socket server compares this header against its `INTERNAL_API_KEY` env var using a constant-time comparison (no timing attacks). If the key doesn't match the request is rejected with HTTP 401.
+
+**This key is a shared secret between your backends and Hive-Socket.** It must never be used in browser or mobile code — it gives unrestricted ability to send notifications to any user.
+
+### What the server enforces
+
+| Guarantee | How |
+|-----------|-----|
+| Only trusted backends can push notifications | `x-internal-api-key` validated on every request |
+| Notifications are scoped to the correct project | `projectId` from your payload scopes DB storage and room routing |
+| `userId` comes from your backend, not the client | Clients never call notify endpoints — only your server-side code does |
+
+### What you must do
+
+- **Store the key in environment variables only.** Never commit it to source control or embed it in client-side code.
+- **Use the same key value** as `INTERNAL_API_KEY` on the Hive-Socket server. They must match exactly.
+- **Use a different key per environment** — generate a separate key for dev and prod, set them independently.
+- **Rotate by updating both env vars** — update `INTERNAL_API_KEY` on Hive-Socket and `HIVE_SOCKET_API_KEY` on your backends, then redeploy. There is no revocation endpoint; rotation is instant once both sides are updated.
+- **Always pass `projectId` from your own config** (`process.env.SMARTHIVE_PROJECT_ID`) — never accept it from user input. It is the SmartHive Auth project ID for your product.
+
+---
+
 ## Types
 
 ```typescript
 import type {
   HiveSocketConfig,
   HiveNotifyPayload,
+  HiveBroadcastPayload,
   HiveHealthResponse,
   NotificationType,
 } from '@smarthivelabs-devs/hive-socket-node';
@@ -357,6 +430,13 @@ interface HiveNotifyPayload {
   sourceService?: string;
 }
 
+interface HiveBroadcastPayload {
+  projectId: string;
+  type: string;
+  payload: Record<string, unknown>;
+  senderId?: string;
+}
+
 interface HiveHealthResponse {
   status: 'ok';
   connections: number;

package/dist/index.cjs

@@ -20,6 +20,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  BroadcastResource: () => BroadcastResource,
   HiveSocketAuthError: () => HiveSocketAuthError,
   HiveSocketClient: () => HiveSocketClient,
   HiveSocketError: () => HiveSocketError,
@@ -99,9 +100,54 @@ var NotifyResource = class {
   }
 };
 
+// src/resources/broadcast.ts
+var BroadcastResource = class {
+  constructor(baseUrl, apiKey, timeout) {
+    this.baseUrl = baseUrl;
+    this.apiKey = apiKey;
+    this.timeout = timeout;
+  }
+  baseUrl;
+  apiKey;
+  timeout;
+  /** Broadcast a real-time message to all sockets in a room (received via useMessages). */
+  async toRoom(roomId, payload) {
+    await this.post(`/internal/broadcast/room/${encodeURIComponent(roomId)}`, payload);
+  }
+  async post(path, body) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), this.timeout);
+    try {
+      const res = await fetch(`${this.baseUrl}${path}`, {
+        method: "POST",
+        headers: {
+          "content-type": "application/json",
+          "x-internal-api-key": this.apiKey
+        },
+        body: JSON.stringify(body),
+        signal: controller.signal
+      });
+      if (res.status === 401) throw new HiveSocketAuthError();
+      if (!res.ok) {
+        const text = await res.text().catch(() => res.statusText);
+        throw new HiveSocketError(`Hive-Socket broadcast failed: ${text}`, res.status);
+      }
+    } catch (err) {
+      if (err instanceof HiveSocketError) throw err;
+      const msg = err instanceof Error ? err.message : String(err);
+      throw new HiveSocketNetworkError(
+        controller.signal.aborted ? `Request timed out after ${this.timeout}ms` : msg
+      );
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+};
+
 // src/client.ts
 var HiveSocketClient = class {
   notify;
+  broadcast;
   baseUrl;
   apiKey;
   timeout;
@@ -110,6 +156,7 @@ var HiveSocketClient = class {
     this.apiKey = config.apiKey;
     this.timeout = config.timeout ?? 1e4;
     this.notify = new NotifyResource(this.baseUrl, this.apiKey, this.timeout);
+    this.broadcast = new BroadcastResource(this.baseUrl, this.apiKey, this.timeout);
   }
   /** Check the Hive-Socket server health and current connection count. */
   async health() {
@@ -137,6 +184,7 @@ function createHiveSocketClient(config) {
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  BroadcastResource,
   HiveSocketAuthError,
   HiveSocketClient,
   HiveSocketError,

package/dist/index.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/index.ts","../src/errors.ts","../src/resources/notify.ts","../src/client.ts"],"sourcesContent":["export { HiveSocketClient, createHiveSocketClient } from './client.js';\nexport { NotifyResource } from './resources/notify.js';\nexport { HiveSocketError, HiveSocketAuthError, HiveSocketNetworkError } from './errors.js';\nexport type {\n  HiveSocketConfig,\n  HiveNotifyPayload,\n  HiveHealthResponse,\n  NotificationType,\n} from './types.js';\n","export class HiveSocketError extends Error {\n  readonly statusCode: number;\n\n  constructor(message: string, statusCode: number) {\n    super(message);\n    this.name = 'HiveSocketError';\n    this.statusCode = statusCode;\n  }\n}\n\n/** Thrown when the API key is wrong (HTTP 401) */\nexport class HiveSocketAuthError extends HiveSocketError {\n  constructor(message = 'Invalid API key') {\n    super(message, 401);\n    this.name = 'HiveSocketAuthError';\n  }\n}\n\n/** Thrown when the fetch fails entirely (network down, timeout) */\nexport class HiveSocketNetworkError extends HiveSocketError {\n  constructor(message: string) {\n    super(message, 0);\n    this.name = 'HiveSocketNetworkError';\n  }\n}\n","import { HiveSocketAuthError, HiveSocketError, HiveSocketNetworkError } from '../errors.js';\nimport type { HiveNotifyPayload } from '../types.js';\n\nexport class NotifyResource {\n  constructor(\n    private readonly baseUrl: string,\n    private readonly apiKey: string,\n    private readonly timeout: number,\n  ) {}\n\n  /** Push a notification to a specific user's connected sockets. */\n  async user(userId: string, payload: HiveNotifyPayload): Promise<void> {\n    await this.post(`/internal/notify/user/${encodeURIComponent(userId)}`, payload);\n  }\n\n  /** Broadcast a notification to all sockets in a room. */\n  async room(roomId: string, payload: HiveNotifyPayload): Promise<void> {\n    await this.post(`/internal/notify/room/${encodeURIComponent(roomId)}`, payload);\n  }\n\n  private async post(path: string, body: unknown): Promise<void> {\n    const controller = new AbortController();\n    const timer = setTimeout(() => controller.abort(), this.timeout);\n\n    try {\n      const res = await fetch(`${this.baseUrl}${path}`, {\n        method: 'POST',\n        headers: {\n          'content-type': 'application/json',\n          'x-internal-api-key': this.apiKey,\n        },\n        body: JSON.stringify(body),\n        signal: controller.signal,\n      });\n\n      if (res.status === 401) throw new HiveSocketAuthError();\n      if (!res.ok) {\n        const text = await res.text().catch(() => res.statusText);\n        throw new HiveSocketError(`Hive-Socket request failed: ${text}`, res.status);\n      }\n    } catch (err) {\n      if (err instanceof HiveSocketError) throw err;\n      const msg = err instanceof Error ? err.message : String(err);\n      throw new HiveSocketNetworkError(\n        controller.signal.aborted ? `Request timed out after ${this.timeout}ms` : msg,\n      );\n    } finally {\n      clearTimeout(timer);\n    }\n  }\n}\n","import { NotifyResource } from './resources/notify.js';\nimport { HiveSocketNetworkError } from './errors.js';\nimport type { HiveSocketConfig, HiveHealthResponse } from './types.js';\n\nexport class HiveSocketClient {\n  readonly notify: NotifyResource;\n\n  private readonly baseUrl: string;\n  private readonly apiKey: string;\n  private readonly timeout: number;\n\n  constructor(config: HiveSocketConfig) {\n    this.baseUrl = config.baseUrl.replace(/\\/$/, '');\n    this.apiKey = config.apiKey;\n    this.timeout = config.timeout ?? 10_000;\n    this.notify = new NotifyResource(this.baseUrl, this.apiKey, this.timeout);\n  }\n\n  /** Check the Hive-Socket server health and current connection count. */\n  async health(): Promise<HiveHealthResponse> {\n    const controller = new AbortController();\n    const timer = setTimeout(() => controller.abort(), this.timeout);\n\n    try {\n      const res = await fetch(`${this.baseUrl}/health`, {\n        signal: controller.signal,\n      });\n      if (!res.ok) throw new HiveSocketNetworkError(`Health check failed: ${res.statusText}`);\n      return res.json() as Promise<HiveHealthResponse>;\n    } catch (err) {\n      if (err instanceof HiveSocketNetworkError) throw err;\n      const msg = err instanceof Error ? err.message : String(err);\n      throw new HiveSocketNetworkError(\n        controller.signal.aborted ? `Health check timed out after ${this.timeout}ms` : msg,\n      );\n    } finally {\n      clearTimeout(timer);\n    }\n  }\n}\n\n/**\n * Create a Hive-Socket server-side client.\n *\n * @example\n * const hive = createHiveSocketClient({\n *   baseUrl: process.env.HIVE_SOCKET_URL!,\n *   apiKey: process.env.HIVE_SOCKET_API_KEY!,\n * });\n * await hive.notify.user(userId, { projectId, title: 'Hey', body: 'Msg', type: 'message' });\n */\nexport function createHiveSocketClient(config: HiveSocketConfig): HiveSocketClient {\n  return new HiveSocketClient(config);\n}\n"],"mappings":"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","names":[]}
+{"version":3,"sources":["../src/index.ts","../src/errors.ts","../src/resources/notify.ts","../src/resources/broadcast.ts","../src/client.ts"],"sourcesContent":["export { HiveSocketClient, createHiveSocketClient } from './client.js';\nexport { NotifyResource } from './resources/notify.js';\nexport { BroadcastResource } from './resources/broadcast.js';\nexport { HiveSocketError, HiveSocketAuthError, HiveSocketNetworkError } from './errors.js';\nexport type {\n  HiveSocketConfig,\n  HiveNotifyPayload,\n  HiveBroadcastPayload,\n  HiveHealthResponse,\n  NotificationType,\n} from './types.js';\n","export class HiveSocketError extends Error {\n  readonly statusCode: number;\n\n  constructor(message: string, statusCode: number) {\n    super(message);\n    this.name = 'HiveSocketError';\n    this.statusCode = statusCode;\n  }\n}\n\n/** Thrown when the API key is wrong (HTTP 401) */\nexport class HiveSocketAuthError extends HiveSocketError {\n  constructor(message = 'Invalid API key') {\n    super(message, 401);\n    this.name = 'HiveSocketAuthError';\n  }\n}\n\n/** Thrown when the fetch fails entirely (network down, timeout) */\nexport class HiveSocketNetworkError extends HiveSocketError {\n  constructor(message: string) {\n    super(message, 0);\n    this.name = 'HiveSocketNetworkError';\n  }\n}\n","import { HiveSocketAuthError, HiveSocketError, HiveSocketNetworkError } from '../errors.js';\nimport type { HiveNotifyPayload } from '../types.js';\n\nexport class NotifyResource {\n  constructor(\n    private readonly baseUrl: string,\n    private readonly apiKey: string,\n    private readonly timeout: number,\n  ) {}\n\n  /** Push a notification to a specific user's connected sockets. */\n  async user(userId: string, payload: HiveNotifyPayload): Promise<void> {\n    await this.post(`/internal/notify/user/${encodeURIComponent(userId)}`, payload);\n  }\n\n  /** Broadcast a notification to all sockets in a room. */\n  async room(roomId: string, payload: HiveNotifyPayload): Promise<void> {\n    await this.post(`/internal/notify/room/${encodeURIComponent(roomId)}`, payload);\n  }\n\n  private async post(path: string, body: unknown): Promise<void> {\n    const controller = new AbortController();\n    const timer = setTimeout(() => controller.abort(), this.timeout);\n\n    try {\n      const res = await fetch(`${this.baseUrl}${path}`, {\n        method: 'POST',\n        headers: {\n          'content-type': 'application/json',\n          'x-internal-api-key': this.apiKey,\n        },\n        body: JSON.stringify(body),\n        signal: controller.signal,\n      });\n\n      if (res.status === 401) throw new HiveSocketAuthError();\n      if (!res.ok) {\n        const text = await res.text().catch(() => res.statusText);\n        throw new HiveSocketError(`Hive-Socket request failed: ${text}`, res.status);\n      }\n    } catch (err) {\n      if (err instanceof HiveSocketError) throw err;\n      const msg = err instanceof Error ? err.message : String(err);\n      throw new HiveSocketNetworkError(\n        controller.signal.aborted ? `Request timed out after ${this.timeout}ms` : msg,\n      );\n    } finally {\n      clearTimeout(timer);\n    }\n  }\n}\n","import { HiveSocketAuthError, HiveSocketError, HiveSocketNetworkError } from '../errors.js';\n\nexport class BroadcastResource {\n  constructor(\n    private readonly baseUrl: string,\n    private readonly apiKey: string,\n    private readonly timeout: number,\n  ) {}\n\n  /** Broadcast a real-time message to all sockets in a room (received via useMessages). */\n  async toRoom(\n    roomId: string,\n    payload: { projectId: string; senderId?: string; type: string; payload: Record<string, unknown> },\n  ): Promise<void> {\n    await this.post(`/internal/broadcast/room/${encodeURIComponent(roomId)}`, payload);\n  }\n\n  private async post(path: string, body: unknown): Promise<void> {\n    const controller = new AbortController();\n    const timer = setTimeout(() => controller.abort(), this.timeout);\n\n    try {\n      const res = await fetch(`${this.baseUrl}${path}`, {\n        method: 'POST',\n        headers: {\n          'content-type': 'application/json',\n          'x-internal-api-key': this.apiKey,\n        },\n        body: JSON.stringify(body),\n        signal: controller.signal,\n      });\n\n      if (res.status === 401) throw new HiveSocketAuthError();\n      if (!res.ok) {\n        const text = await res.text().catch(() => res.statusText);\n        throw new HiveSocketError(`Hive-Socket broadcast failed: ${text}`, res.status);\n      }\n    } catch (err) {\n      if (err instanceof HiveSocketError) throw err;\n      const msg = err instanceof Error ? err.message : String(err);\n      throw new HiveSocketNetworkError(\n        controller.signal.aborted ? `Request timed out after ${this.timeout}ms` : msg,\n      );\n    } finally {\n      clearTimeout(timer);\n    }\n  }\n}\n","import { NotifyResource } from './resources/notify.js';\nimport { BroadcastResource } from './resources/broadcast.js';\nimport { HiveSocketNetworkError } from './errors.js';\nimport type { HiveSocketConfig, HiveHealthResponse } from './types.js';\n\nexport class HiveSocketClient {\n  readonly notify: NotifyResource;\n  readonly broadcast: BroadcastResource;\n\n  private readonly baseUrl: string;\n  private readonly apiKey: string;\n  private readonly timeout: number;\n\n  constructor(config: HiveSocketConfig) {\n    this.baseUrl = config.baseUrl.replace(/\\/$/, '');\n    this.apiKey = config.apiKey;\n    this.timeout = config.timeout ?? 10_000;\n    this.notify = new NotifyResource(this.baseUrl, this.apiKey, this.timeout);\n    this.broadcast = new BroadcastResource(this.baseUrl, this.apiKey, this.timeout);\n  }\n\n  /** Check the Hive-Socket server health and current connection count. */\n  async health(): Promise<HiveHealthResponse> {\n    const controller = new AbortController();\n    const timer = setTimeout(() => controller.abort(), this.timeout);\n\n    try {\n      const res = await fetch(`${this.baseUrl}/health`, {\n        signal: controller.signal,\n      });\n      if (!res.ok) throw new HiveSocketNetworkError(`Health check failed: ${res.statusText}`);\n      return res.json() as Promise<HiveHealthResponse>;\n    } catch (err) {\n      if (err instanceof HiveSocketNetworkError) throw err;\n      const msg = err instanceof Error ? err.message : String(err);\n      throw new HiveSocketNetworkError(\n        controller.signal.aborted ? `Health check timed out after ${this.timeout}ms` : msg,\n      );\n    } finally {\n      clearTimeout(timer);\n    }\n  }\n}\n\n/**\n * Create a Hive-Socket server-side client.\n *\n * @example\n * const hive = createHiveSocketClient({\n *   baseUrl: process.env.HIVE_SOCKET_URL!,\n *   apiKey: process.env.HIVE_SOCKET_API_KEY!,\n * });\n * await hive.notify.user(userId, { projectId, title: 'Hey', body: 'Msg', type: 'message' });\n */\nexport function createHiveSocketClient(config: HiveSocketConfig): HiveSocketClient {\n  return new HiveSocketClient(config);\n}\n"],"mappings":"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","names":[]}

package/dist/index.d.cts

@@ -8,6 +8,13 @@ interface HiveNotifyPayload {
     metadata?: Record<string, unknown>;
     sourceService?: string;
 }
+/** Payload sent to POST /internal/broadcast/room/:roomId */
+interface HiveBroadcastPayload {
+    projectId: string;
+    type: string;
+    payload: Record<string, unknown>;
+    senderId?: string;
+}
 /** Response from GET /health */
 interface HiveHealthResponse {
     status: 'ok';
@@ -35,8 +42,24 @@ declare class NotifyResource {
     private post;
 }
 
+declare class BroadcastResource {
+    private readonly baseUrl;
+    private readonly apiKey;
+    private readonly timeout;
+    constructor(baseUrl: string, apiKey: string, timeout: number);
+    /** Broadcast a real-time message to all sockets in a room (received via useMessages). */
+    toRoom(roomId: string, payload: {
+        projectId: string;
+        senderId?: string;
+        type: string;
+        payload: Record<string, unknown>;
+    }): Promise<void>;
+    private post;
+}
+
 declare class HiveSocketClient {
     readonly notify: NotifyResource;
+    readonly broadcast: BroadcastResource;
     private readonly baseUrl;
     private readonly apiKey;
     private readonly timeout;
@@ -69,4 +92,4 @@ declare class HiveSocketNetworkError extends HiveSocketError {
     constructor(message: string);
 }
 
-export { type HiveHealthResponse, type HiveNotifyPayload, HiveSocketAuthError, HiveSocketClient, type HiveSocketConfig, HiveSocketError, HiveSocketNetworkError, type NotificationType, NotifyResource, createHiveSocketClient };
+export { BroadcastResource, type HiveBroadcastPayload, type HiveHealthResponse, type HiveNotifyPayload, HiveSocketAuthError, HiveSocketClient, type HiveSocketConfig, HiveSocketError, HiveSocketNetworkError, type NotificationType, NotifyResource, createHiveSocketClient };

package/dist/index.d.ts

@@ -8,6 +8,13 @@ interface HiveNotifyPayload {
     metadata?: Record<string, unknown>;
     sourceService?: string;
 }
+/** Payload sent to POST /internal/broadcast/room/:roomId */
+interface HiveBroadcastPayload {
+    projectId: string;
+    type: string;
+    payload: Record<string, unknown>;
+    senderId?: string;
+}
 /** Response from GET /health */
 interface HiveHealthResponse {
     status: 'ok';
@@ -35,8 +42,24 @@ declare class NotifyResource {
     private post;
 }
 
+declare class BroadcastResource {
+    private readonly baseUrl;
+    private readonly apiKey;
+    private readonly timeout;
+    constructor(baseUrl: string, apiKey: string, timeout: number);
+    /** Broadcast a real-time message to all sockets in a room (received via useMessages). */
+    toRoom(roomId: string, payload: {
+        projectId: string;
+        senderId?: string;
+        type: string;
+        payload: Record<string, unknown>;
+    }): Promise<void>;
+    private post;
+}
+
 declare class HiveSocketClient {
     readonly notify: NotifyResource;
+    readonly broadcast: BroadcastResource;
     private readonly baseUrl;
     private readonly apiKey;
     private readonly timeout;
@@ -69,4 +92,4 @@ declare class HiveSocketNetworkError extends HiveSocketError {
     constructor(message: string);
 }
 
-export { type HiveHealthResponse, type HiveNotifyPayload, HiveSocketAuthError, HiveSocketClient, type HiveSocketConfig, HiveSocketError, HiveSocketNetworkError, type NotificationType, NotifyResource, createHiveSocketClient };
+export { BroadcastResource, type HiveBroadcastPayload, type HiveHealthResponse, type HiveNotifyPayload, HiveSocketAuthError, HiveSocketClient, type HiveSocketConfig, HiveSocketError, HiveSocketNetworkError, type NotificationType, NotifyResource, createHiveSocketClient };

package/dist/index.js

@@ -68,9 +68,54 @@ var NotifyResource = class {
   }
 };
 
+// src/resources/broadcast.ts
+var BroadcastResource = class {
+  constructor(baseUrl, apiKey, timeout) {
+    this.baseUrl = baseUrl;
+    this.apiKey = apiKey;
+    this.timeout = timeout;
+  }
+  baseUrl;
+  apiKey;
+  timeout;
+  /** Broadcast a real-time message to all sockets in a room (received via useMessages). */
+  async toRoom(roomId, payload) {
+    await this.post(`/internal/broadcast/room/${encodeURIComponent(roomId)}`, payload);
+  }
+  async post(path, body) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), this.timeout);
+    try {
+      const res = await fetch(`${this.baseUrl}${path}`, {
+        method: "POST",
+        headers: {
+          "content-type": "application/json",
+          "x-internal-api-key": this.apiKey
+        },
+        body: JSON.stringify(body),
+        signal: controller.signal
+      });
+      if (res.status === 401) throw new HiveSocketAuthError();
+      if (!res.ok) {
+        const text = await res.text().catch(() => res.statusText);
+        throw new HiveSocketError(`Hive-Socket broadcast failed: ${text}`, res.status);
+      }
+    } catch (err) {
+      if (err instanceof HiveSocketError) throw err;
+      const msg = err instanceof Error ? err.message : String(err);
+      throw new HiveSocketNetworkError(
+        controller.signal.aborted ? `Request timed out after ${this.timeout}ms` : msg
+      );
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+};
+
 // src/client.ts
 var HiveSocketClient = class {
   notify;
+  broadcast;
   baseUrl;
   apiKey;
   timeout;
@@ -79,6 +124,7 @@ var HiveSocketClient = class {
     this.apiKey = config.apiKey;
     this.timeout = config.timeout ?? 1e4;
     this.notify = new NotifyResource(this.baseUrl, this.apiKey, this.timeout);
+    this.broadcast = new BroadcastResource(this.baseUrl, this.apiKey, this.timeout);
   }
   /** Check the Hive-Socket server health and current connection count. */
   async health() {
@@ -105,6 +151,7 @@ function createHiveSocketClient(config) {
   return new HiveSocketClient(config);
 }
 export {
+  BroadcastResource,
   HiveSocketAuthError,
   HiveSocketClient,
   HiveSocketError,

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/errors.ts","../src/resources/notify.ts","../src/client.ts"],"sourcesContent":["export class HiveSocketError extends Error {\n  readonly statusCode: number;\n\n  constructor(message: string, statusCode: number) {\n    super(message);\n    this.name = 'HiveSocketError';\n    this.statusCode = statusCode;\n  }\n}\n\n/** Thrown when the API key is wrong (HTTP 401) */\nexport class HiveSocketAuthError extends HiveSocketError {\n  constructor(message = 'Invalid API key') {\n    super(message, 401);\n    this.name = 'HiveSocketAuthError';\n  }\n}\n\n/** Thrown when the fetch fails entirely (network down, timeout) */\nexport class HiveSocketNetworkError extends HiveSocketError {\n  constructor(message: string) {\n    super(message, 0);\n    this.name = 'HiveSocketNetworkError';\n  }\n}\n","import { HiveSocketAuthError, HiveSocketError, HiveSocketNetworkError } from '../errors.js';\nimport type { HiveNotifyPayload } from '../types.js';\n\nexport class NotifyResource {\n  constructor(\n    private readonly baseUrl: string,\n    private readonly apiKey: string,\n    private readonly timeout: number,\n  ) {}\n\n  /** Push a notification to a specific user's connected sockets. */\n  async user(userId: string, payload: HiveNotifyPayload): Promise<void> {\n    await this.post(`/internal/notify/user/${encodeURIComponent(userId)}`, payload);\n  }\n\n  /** Broadcast a notification to all sockets in a room. */\n  async room(roomId: string, payload: HiveNotifyPayload): Promise<void> {\n    await this.post(`/internal/notify/room/${encodeURIComponent(roomId)}`, payload);\n  }\n\n  private async post(path: string, body: unknown): Promise<void> {\n    const controller = new AbortController();\n    const timer = setTimeout(() => controller.abort(), this.timeout);\n\n    try {\n      const res = await fetch(`${this.baseUrl}${path}`, {\n        method: 'POST',\n        headers: {\n          'content-type': 'application/json',\n          'x-internal-api-key': this.apiKey,\n        },\n        body: JSON.stringify(body),\n        signal: controller.signal,\n      });\n\n      if (res.status === 401) throw new HiveSocketAuthError();\n      if (!res.ok) {\n        const text = await res.text().catch(() => res.statusText);\n        throw new HiveSocketError(`Hive-Socket request failed: ${text}`, res.status);\n      }\n    } catch (err) {\n      if (err instanceof HiveSocketError) throw err;\n      const msg = err instanceof Error ? err.message : String(err);\n      throw new HiveSocketNetworkError(\n        controller.signal.aborted ? `Request timed out after ${this.timeout}ms` : msg,\n      );\n    } finally {\n      clearTimeout(timer);\n    }\n  }\n}\n","import { NotifyResource } from './resources/notify.js';\nimport { HiveSocketNetworkError } from './errors.js';\nimport type { HiveSocketConfig, HiveHealthResponse } from './types.js';\n\nexport class HiveSocketClient {\n  readonly notify: NotifyResource;\n\n  private readonly baseUrl: string;\n  private readonly apiKey: string;\n  private readonly timeout: number;\n\n  constructor(config: HiveSocketConfig) {\n    this.baseUrl = config.baseUrl.replace(/\\/$/, '');\n    this.apiKey = config.apiKey;\n    this.timeout = config.timeout ?? 10_000;\n    this.notify = new NotifyResource(this.baseUrl, this.apiKey, this.timeout);\n  }\n\n  /** Check the Hive-Socket server health and current connection count. */\n  async health(): Promise<HiveHealthResponse> {\n    const controller = new AbortController();\n    const timer = setTimeout(() => controller.abort(), this.timeout);\n\n    try {\n      const res = await fetch(`${this.baseUrl}/health`, {\n        signal: controller.signal,\n      });\n      if (!res.ok) throw new HiveSocketNetworkError(`Health check failed: ${res.statusText}`);\n      return res.json() as Promise<HiveHealthResponse>;\n    } catch (err) {\n      if (err instanceof HiveSocketNetworkError) throw err;\n      const msg = err instanceof Error ? err.message : String(err);\n      throw new HiveSocketNetworkError(\n        controller.signal.aborted ? `Health check timed out after ${this.timeout}ms` : msg,\n      );\n    } finally {\n      clearTimeout(timer);\n    }\n  }\n}\n\n/**\n * Create a Hive-Socket server-side client.\n *\n * @example\n * const hive = createHiveSocketClient({\n *   baseUrl: process.env.HIVE_SOCKET_URL!,\n *   apiKey: process.env.HIVE_SOCKET_API_KEY!,\n * });\n * await hive.notify.user(userId, { projectId, title: 'Hey', body: 'Msg', type: 'message' });\n */\nexport function createHiveSocketClient(config: HiveSocketConfig): HiveSocketClient {\n  return new HiveSocketClient(config);\n}\n"],"mappings":"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","names":[]}
+{"version":3,"sources":["../src/errors.ts","../src/resources/notify.ts","../src/resources/broadcast.ts","../src/client.ts"],"sourcesContent":["export class HiveSocketError extends Error {\n  readonly statusCode: number;\n\n  constructor(message: string, statusCode: number) {\n    super(message);\n    this.name = 'HiveSocketError';\n    this.statusCode = statusCode;\n  }\n}\n\n/** Thrown when the API key is wrong (HTTP 401) */\nexport class HiveSocketAuthError extends HiveSocketError {\n  constructor(message = 'Invalid API key') {\n    super(message, 401);\n    this.name = 'HiveSocketAuthError';\n  }\n}\n\n/** Thrown when the fetch fails entirely (network down, timeout) */\nexport class HiveSocketNetworkError extends HiveSocketError {\n  constructor(message: string) {\n    super(message, 0);\n    this.name = 'HiveSocketNetworkError';\n  }\n}\n","import { HiveSocketAuthError, HiveSocketError, HiveSocketNetworkError } from '../errors.js';\nimport type { HiveNotifyPayload } from '../types.js';\n\nexport class NotifyResource {\n  constructor(\n    private readonly baseUrl: string,\n    private readonly apiKey: string,\n    private readonly timeout: number,\n  ) {}\n\n  /** Push a notification to a specific user's connected sockets. */\n  async user(userId: string, payload: HiveNotifyPayload): Promise<void> {\n    await this.post(`/internal/notify/user/${encodeURIComponent(userId)}`, payload);\n  }\n\n  /** Broadcast a notification to all sockets in a room. */\n  async room(roomId: string, payload: HiveNotifyPayload): Promise<void> {\n    await this.post(`/internal/notify/room/${encodeURIComponent(roomId)}`, payload);\n  }\n\n  private async post(path: string, body: unknown): Promise<void> {\n    const controller = new AbortController();\n    const timer = setTimeout(() => controller.abort(), this.timeout);\n\n    try {\n      const res = await fetch(`${this.baseUrl}${path}`, {\n        method: 'POST',\n        headers: {\n          'content-type': 'application/json',\n          'x-internal-api-key': this.apiKey,\n        },\n        body: JSON.stringify(body),\n        signal: controller.signal,\n      });\n\n      if (res.status === 401) throw new HiveSocketAuthError();\n      if (!res.ok) {\n        const text = await res.text().catch(() => res.statusText);\n        throw new HiveSocketError(`Hive-Socket request failed: ${text}`, res.status);\n      }\n    } catch (err) {\n      if (err instanceof HiveSocketError) throw err;\n      const msg = err instanceof Error ? err.message : String(err);\n      throw new HiveSocketNetworkError(\n        controller.signal.aborted ? `Request timed out after ${this.timeout}ms` : msg,\n      );\n    } finally {\n      clearTimeout(timer);\n    }\n  }\n}\n","import { HiveSocketAuthError, HiveSocketError, HiveSocketNetworkError } from '../errors.js';\n\nexport class BroadcastResource {\n  constructor(\n    private readonly baseUrl: string,\n    private readonly apiKey: string,\n    private readonly timeout: number,\n  ) {}\n\n  /** Broadcast a real-time message to all sockets in a room (received via useMessages). */\n  async toRoom(\n    roomId: string,\n    payload: { projectId: string; senderId?: string; type: string; payload: Record<string, unknown> },\n  ): Promise<void> {\n    await this.post(`/internal/broadcast/room/${encodeURIComponent(roomId)}`, payload);\n  }\n\n  private async post(path: string, body: unknown): Promise<void> {\n    const controller = new AbortController();\n    const timer = setTimeout(() => controller.abort(), this.timeout);\n\n    try {\n      const res = await fetch(`${this.baseUrl}${path}`, {\n        method: 'POST',\n        headers: {\n          'content-type': 'application/json',\n          'x-internal-api-key': this.apiKey,\n        },\n        body: JSON.stringify(body),\n        signal: controller.signal,\n      });\n\n      if (res.status === 401) throw new HiveSocketAuthError();\n      if (!res.ok) {\n        const text = await res.text().catch(() => res.statusText);\n        throw new HiveSocketError(`Hive-Socket broadcast failed: ${text}`, res.status);\n      }\n    } catch (err) {\n      if (err instanceof HiveSocketError) throw err;\n      const msg = err instanceof Error ? err.message : String(err);\n      throw new HiveSocketNetworkError(\n        controller.signal.aborted ? `Request timed out after ${this.timeout}ms` : msg,\n      );\n    } finally {\n      clearTimeout(timer);\n    }\n  }\n}\n","import { NotifyResource } from './resources/notify.js';\nimport { BroadcastResource } from './resources/broadcast.js';\nimport { HiveSocketNetworkError } from './errors.js';\nimport type { HiveSocketConfig, HiveHealthResponse } from './types.js';\n\nexport class HiveSocketClient {\n  readonly notify: NotifyResource;\n  readonly broadcast: BroadcastResource;\n\n  private readonly baseUrl: string;\n  private readonly apiKey: string;\n  private readonly timeout: number;\n\n  constructor(config: HiveSocketConfig) {\n    this.baseUrl = config.baseUrl.replace(/\\/$/, '');\n    this.apiKey = config.apiKey;\n    this.timeout = config.timeout ?? 10_000;\n    this.notify = new NotifyResource(this.baseUrl, this.apiKey, this.timeout);\n    this.broadcast = new BroadcastResource(this.baseUrl, this.apiKey, this.timeout);\n  }\n\n  /** Check the Hive-Socket server health and current connection count. */\n  async health(): Promise<HiveHealthResponse> {\n    const controller = new AbortController();\n    const timer = setTimeout(() => controller.abort(), this.timeout);\n\n    try {\n      const res = await fetch(`${this.baseUrl}/health`, {\n        signal: controller.signal,\n      });\n      if (!res.ok) throw new HiveSocketNetworkError(`Health check failed: ${res.statusText}`);\n      return res.json() as Promise<HiveHealthResponse>;\n    } catch (err) {\n      if (err instanceof HiveSocketNetworkError) throw err;\n      const msg = err instanceof Error ? err.message : String(err);\n      throw new HiveSocketNetworkError(\n        controller.signal.aborted ? `Health check timed out after ${this.timeout}ms` : msg,\n      );\n    } finally {\n      clearTimeout(timer);\n    }\n  }\n}\n\n/**\n * Create a Hive-Socket server-side client.\n *\n * @example\n * const hive = createHiveSocketClient({\n *   baseUrl: process.env.HIVE_SOCKET_URL!,\n *   apiKey: process.env.HIVE_SOCKET_API_KEY!,\n * });\n * await hive.notify.user(userId, { projectId, title: 'Hey', body: 'Msg', type: 'message' });\n */\nexport function createHiveSocketClient(config: HiveSocketConfig): HiveSocketClient {\n  return new HiveSocketClient(config);\n}\n"],"mappings":"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","names":[]}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@smarthivelabs-devs/hive-socket-node",
-  "version": "1.0.0",
-  "description": "Node.js SDK for Hive-Socket — push notifications and events to connected clients",
+  "version": "1.1.0",
+  "description": "Node.js SDK for Hive-Socket — push notifications, events, and real-time messages to connected clients",
   "type": "module",
   "main": "./dist/index.cjs",
   "module": "./dist/index.js",