@smarthivelabs-devs/hive-socket-node 1.0.0

package/README.md

@@ -0,0 +1,365 @@
+# @smarthivelabs-devs/hive-socket-node
+
+Node.js SDK for Hive-Socket — push real-time notifications and events to connected clients from any backend service.
+
+## Install
+
+```bash
+npm install @smarthivelabs-devs/hive-socket-node
+# or
+yarn add @smarthivelabs-devs/hive-socket-node
+# or
+pnpm add @smarthivelabs-devs/hive-socket-node
+```
+
+**Requirements:** Node 18+ (uses native `fetch`). No peer dependencies.
+
+Supports both ESM and CommonJS:
+```typescript
+// ESM
+import { createHiveSocketClient } from '@smarthivelabs-devs/hive-socket-node';
+
+// CommonJS
+const { createHiveSocketClient } = require('@smarthivelabs-devs/hive-socket-node');
+```
+
+---
+
+## Environment variables
+
+Add to your backend `.env`:
+
+```env
+HIVE_SOCKET_URL=https://socket.smarthivelabs.dev
+HIVE_SOCKET_API_KEY=shai_hivesocket_<your-key>
+```
+
+Get the API key from the Hive-Socket server's `.env` (`INTERNAL_API_KEY`).
+
+---
+
+## Quick start
+
+```typescript
+import { createHiveSocketClient } from '@smarthivelabs-devs/hive-socket-node';
+
+const hive = createHiveSocketClient({
+  baseUrl: process.env.HIVE_SOCKET_URL!,
+  apiKey: process.env.HIVE_SOCKET_API_KEY!,
+});
+
+// Push a notification to a user
+await hive.notify.user('user-id-123', {
+  projectId: 'your-project-id',
+  title: 'New message',
+  body: 'Alice sent you a message',
+  type: 'message',
+});
+```
+
+---
+
+## API
+
+### `createHiveSocketClient(config)`
+
+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
+});
+```
+
+---
+
+### `hive.notify.user(userId, payload)`
+
+Push a notification to a specific user. Delivered instantly to all their connected devices. If the user is offline, the notification is persisted and delivered on their next login.
+
+```typescript
+await hive.notify.user(userId, {
+  projectId: string,          // Your SmartHive project ID
+  title: string,              // Notification title
+  body: string,               // Notification body
+  type: NotificationType,     // 'info' | 'success' | 'warning' | 'error' | 'message'
+  metadata?: Record<string, unknown>, // Optional — any JSON data
+  sourceService?: string,     // Optional — identifies the sending service
+});
+```
+
+**Example — payment confirmed:**
+```typescript
+await hive.notify.user(userId, {
+  projectId: 'workspace-project-id',
+  title: 'Payment confirmed',
+  body: `₦${amount.toLocaleString()} received`,
+  type: 'success',
+  metadata: { paymentId, amount },
+  sourceService: 'payment-backend',
+});
+```
+
+**Example — new comment:**
+```typescript
+await hive.notify.user(comment.authorId, {
+  projectId: workspace.projectId,
+  title: 'New reply',
+  body: `${commenter.name} replied to your comment`,
+  type: 'message',
+  metadata: { commentId: comment.id, threadId: comment.threadId },
+  sourceService: 'workspace-backend',
+});
+```
+
+---
+
+### `hive.notify.room(roomId, payload)`
+
+Broadcast a notification to all users currently in a room. Room notifications are ephemeral — not persisted to the database.
+
+```typescript
+await hive.notify.room(roomId, {
+  projectId: string,
+  title: string,
+  body: string,
+  type: NotificationType,
+  metadata?: Record<string, unknown>,
+  sourceService?: string,
+});
+```
+
+**Example — quiz started:**
+```typescript
+await hive.notify.room(`course:${courseId}`, {
+  projectId: 'hivedemia-project-id',
+  title: 'Quiz started',
+  body: 'Chapter 3 quiz is now live',
+  type: 'info',
+  sourceService: 'hivedemia-backend',
+});
+```
+
+**Example — live vote update:**
+```typescript
+await hive.notify.room(`event:${eventId}`, {
+  projectId: 'votyhive-project-id',
+  title: 'Results updated',
+  body: 'New votes have been counted',
+  type: 'info',
+  metadata: { candidateId, totalVotes },
+  sourceService: 'votyhive-backend',
+});
+```
+
+---
+
+### `hive.health()`
+
+Check server health and current connection count.
+
+```typescript
+const { status, connections, uptime } = await hive.health();
+// { status: 'ok', connections: 42, uptime: 3600 }
+```
+
+---
+
+## Error handling
+
+```typescript
+import {
+  HiveSocketAuthError,
+  HiveSocketNetworkError,
+  HiveSocketError,
+} from '@smarthivelabs-devs/hive-socket-node';
+
+try {
+  await hive.notify.user(userId, payload);
+} catch (err) {
+  if (err instanceof HiveSocketAuthError) {
+    // HTTP 401 — wrong API key
+    // Check HIVE_SOCKET_API_KEY matches INTERNAL_API_KEY on the server
+  } else if (err instanceof HiveSocketNetworkError) {
+    // Network failure or request timed out
+    // Safe to retry with exponential backoff
+  } else if (err instanceof HiveSocketError) {
+    // Other server error
+    console.error(err.message, err.statusCode);
+  }
+}
+```
+
+---
+
+## NestJS integration
+
+### Create a shared module
+
+```typescript
+// hive-socket.module.ts
+import { Module, Global } from '@nestjs/common';
+import { ConfigService } from '@nestjs/config';
+import { createHiveSocketClient, HiveSocketClient } from '@smarthivelabs-devs/hive-socket-node';
+
+export const HIVE_SOCKET = Symbol('HIVE_SOCKET');
+
+@Global()
+@Module({
+  providers: [
+    {
+      provide: HIVE_SOCKET,
+      inject: [ConfigService],
+      useFactory: (config: ConfigService) =>
+        createHiveSocketClient({
+          baseUrl: config.getOrThrow('HIVE_SOCKET_URL'),
+          apiKey: config.getOrThrow('HIVE_SOCKET_API_KEY'),
+        }),
+    },
+  ],
+  exports: [HIVE_SOCKET],
+})
+export class HiveSocketModule {}
+```
+
+### Inject into any service
+
+```typescript
+// notifications.service.ts
+import { Injectable, Inject } from '@nestjs/common';
+import { HiveSocketClient } from '@smarthivelabs-devs/hive-socket-node';
+import { HIVE_SOCKET } from './hive-socket.module';
+
+@Injectable()
+export class NotificationsService {
+  constructor(
+    @Inject(HIVE_SOCKET) private readonly hive: HiveSocketClient,
+  ) {}
+
+  async sendPaymentNotification(userId: string, projectId: string, amount: number) {
+    await this.hive.notify.user(userId, {
+      projectId,
+      title: 'Payment received',
+      body: `Your payment of ₦${amount.toLocaleString()} was confirmed`,
+      type: 'success',
+      metadata: { amount },
+      sourceService: 'payment-service',
+    });
+  }
+
+  async announceToRoom(roomId: string, projectId: string, message: string) {
+    await this.hive.notify.room(roomId, {
+      projectId,
+      title: 'Announcement',
+      body: message,
+      type: 'info',
+      sourceService: 'admin-service',
+    });
+  }
+}
+```
+
+---
+
+## Express / Next.js API route
+
+### Express
+
+```typescript
+// routes/messages.ts
+import { Router } from 'express';
+import { hive } from '../lib/hive-socket'; // your singleton
+
+const router = Router();
+
+router.post('/messages', async (req, res) => {
+  const { userId, projectId, text } = req.body;
+
+  // ... save message to your DB ...
+
+  await hive.notify.user(userId, {
+    projectId,
+    title: 'New message',
+    body: text.slice(0, 100),
+    type: 'message',
+    sourceService: 'workspace-api',
+  });
+
+  res.json({ ok: true });
+});
+```
+
+### Next.js App Router
+
+```typescript
+// app/api/notify/route.ts
+import { createHiveSocketClient } from '@smarthivelabs-devs/hive-socket-node';
+
+const hive = createHiveSocketClient({
+  baseUrl: process.env.HIVE_SOCKET_URL!,
+  apiKey: process.env.HIVE_SOCKET_API_KEY!,
+});
+
+export async function POST(req: Request) {
+  const { userId, projectId, title, body } = await req.json();
+
+  await hive.notify.user(userId, {
+    projectId,
+    title,
+    body,
+    type: 'info',
+  });
+
+  return Response.json({ ok: true });
+}
+```
+
+---
+
+## Notification types
+
+| Type | When to use |
+|------|-------------|
+| `'message'` | New chat message or direct message |
+| `'info'` | General information (quiz started, event begins) |
+| `'success'` | Positive outcome (payment confirmed, grade posted) |
+| `'warning'` | Requires attention (deadline approaching, low balance) |
+| `'error'` | Something failed (payment declined, submission error) |
+
+---
+
+## Types
+
+```typescript
+import type {
+  HiveSocketConfig,
+  HiveNotifyPayload,
+  HiveHealthResponse,
+  NotificationType,
+} from '@smarthivelabs-devs/hive-socket-node';
+```
+
+```typescript
+interface HiveSocketConfig {
+  baseUrl: string;
+  apiKey: string;
+  timeout?: number; // ms, default 10000
+}
+
+interface HiveNotifyPayload {
+  projectId: string;
+  title: string;
+  body: string;
+  type: 'info' | 'success' | 'warning' | 'error' | 'message';
+  metadata?: Record<string, unknown>;
+  sourceService?: string;
+}
+
+interface HiveHealthResponse {
+  status: 'ok';
+  connections: number;
+  uptime: number;
+}
+```

package/dist/index.cjs

@@ -0,0 +1,147 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  HiveSocketAuthError: () => HiveSocketAuthError,
+  HiveSocketClient: () => HiveSocketClient,
+  HiveSocketError: () => HiveSocketError,
+  HiveSocketNetworkError: () => HiveSocketNetworkError,
+  NotifyResource: () => NotifyResource,
+  createHiveSocketClient: () => createHiveSocketClient
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/errors.ts
+var HiveSocketError = class extends Error {
+  statusCode;
+  constructor(message, statusCode) {
+    super(message);
+    this.name = "HiveSocketError";
+    this.statusCode = statusCode;
+  }
+};
+var HiveSocketAuthError = class extends HiveSocketError {
+  constructor(message = "Invalid API key") {
+    super(message, 401);
+    this.name = "HiveSocketAuthError";
+  }
+};
+var HiveSocketNetworkError = class extends HiveSocketError {
+  constructor(message) {
+    super(message, 0);
+    this.name = "HiveSocketNetworkError";
+  }
+};
+
+// src/resources/notify.ts
+var NotifyResource = class {
+  constructor(baseUrl, apiKey, timeout) {
+    this.baseUrl = baseUrl;
+    this.apiKey = apiKey;
+    this.timeout = timeout;
+  }
+  baseUrl;
+  apiKey;
+  timeout;
+  /** Push a notification to a specific user's connected sockets. */
+  async user(userId, payload) {
+    await this.post(`/internal/notify/user/${encodeURIComponent(userId)}`, payload);
+  }
+  /** Broadcast a notification to all sockets in a room. */
+  async room(roomId, payload) {
+    await this.post(`/internal/notify/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 request 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;
+  baseUrl;
+  apiKey;
+  timeout;
+  constructor(config) {
+    this.baseUrl = config.baseUrl.replace(/\/$/, "");
+    this.apiKey = config.apiKey;
+    this.timeout = config.timeout ?? 1e4;
+    this.notify = new NotifyResource(this.baseUrl, this.apiKey, this.timeout);
+  }
+  /** Check the Hive-Socket server health and current connection count. */
+  async health() {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), this.timeout);
+    try {
+      const res = await fetch(`${this.baseUrl}/health`, {
+        signal: controller.signal
+      });
+      if (!res.ok) throw new HiveSocketNetworkError(`Health check failed: ${res.statusText}`);
+      return res.json();
+    } catch (err) {
+      if (err instanceof HiveSocketNetworkError) throw err;
+      const msg = err instanceof Error ? err.message : String(err);
+      throw new HiveSocketNetworkError(
+        controller.signal.aborted ? `Health check timed out after ${this.timeout}ms` : msg
+      );
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+};
+function createHiveSocketClient(config) {
+  return new HiveSocketClient(config);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  HiveSocketAuthError,
+  HiveSocketClient,
+  HiveSocketError,
+  HiveSocketNetworkError,
+  NotifyResource,
+  createHiveSocketClient
+});
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +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":[]}

package/dist/index.d.cts

@@ -0,0 +1,72 @@
+type NotificationType = 'info' | 'success' | 'warning' | 'error' | 'message';
+/** Payload sent to POST /internal/notify/user/:userId or /internal/notify/room/:roomId */
+interface HiveNotifyPayload {
+    projectId: string;
+    title: string;
+    body: string;
+    type: NotificationType;
+    metadata?: Record<string, unknown>;
+    sourceService?: string;
+}
+/** Response from GET /health */
+interface HiveHealthResponse {
+    status: 'ok';
+    connections: number;
+    uptime: number;
+}
+interface HiveSocketConfig {
+    /** Base URL of the Hive-Socket server, e.g. https://socket.smarthivelabs.dev */
+    baseUrl: string;
+    /** Internal API key (shai_* format) */
+    apiKey: string;
+    /** Request timeout in ms. Default: 10000 */
+    timeout?: number;
+}
+
+declare class NotifyResource {
+    private readonly baseUrl;
+    private readonly apiKey;
+    private readonly timeout;
+    constructor(baseUrl: string, apiKey: string, timeout: number);
+    /** Push a notification to a specific user's connected sockets. */
+    user(userId: string, payload: HiveNotifyPayload): Promise<void>;
+    /** Broadcast a notification to all sockets in a room. */
+    room(roomId: string, payload: HiveNotifyPayload): Promise<void>;
+    private post;
+}
+
+declare class HiveSocketClient {
+    readonly notify: NotifyResource;
+    private readonly baseUrl;
+    private readonly apiKey;
+    private readonly timeout;
+    constructor(config: HiveSocketConfig);
+    /** Check the Hive-Socket server health and current connection count. */
+    health(): Promise<HiveHealthResponse>;
+}
+/**
+ * Create a Hive-Socket server-side client.
+ *
+ * @example
+ * const hive = createHiveSocketClient({
+ *   baseUrl: process.env.HIVE_SOCKET_URL!,
+ *   apiKey: process.env.HIVE_SOCKET_API_KEY!,
+ * });
+ * await hive.notify.user(userId, { projectId, title: 'Hey', body: 'Msg', type: 'message' });
+ */
+declare function createHiveSocketClient(config: HiveSocketConfig): HiveSocketClient;
+
+declare class HiveSocketError extends Error {
+    readonly statusCode: number;
+    constructor(message: string, statusCode: number);
+}
+/** Thrown when the API key is wrong (HTTP 401) */
+declare class HiveSocketAuthError extends HiveSocketError {
+    constructor(message?: string);
+}
+/** Thrown when the fetch fails entirely (network down, timeout) */
+declare class HiveSocketNetworkError extends HiveSocketError {
+    constructor(message: string);
+}
+
+export { type HiveHealthResponse, type HiveNotifyPayload, HiveSocketAuthError, HiveSocketClient, type HiveSocketConfig, HiveSocketError, HiveSocketNetworkError, type NotificationType, NotifyResource, createHiveSocketClient };

package/dist/index.d.ts

@@ -0,0 +1,72 @@
+type NotificationType = 'info' | 'success' | 'warning' | 'error' | 'message';
+/** Payload sent to POST /internal/notify/user/:userId or /internal/notify/room/:roomId */
+interface HiveNotifyPayload {
+    projectId: string;
+    title: string;
+    body: string;
+    type: NotificationType;
+    metadata?: Record<string, unknown>;
+    sourceService?: string;
+}
+/** Response from GET /health */
+interface HiveHealthResponse {
+    status: 'ok';
+    connections: number;
+    uptime: number;
+}
+interface HiveSocketConfig {
+    /** Base URL of the Hive-Socket server, e.g. https://socket.smarthivelabs.dev */
+    baseUrl: string;
+    /** Internal API key (shai_* format) */
+    apiKey: string;
+    /** Request timeout in ms. Default: 10000 */
+    timeout?: number;
+}
+
+declare class NotifyResource {
+    private readonly baseUrl;
+    private readonly apiKey;
+    private readonly timeout;
+    constructor(baseUrl: string, apiKey: string, timeout: number);
+    /** Push a notification to a specific user's connected sockets. */
+    user(userId: string, payload: HiveNotifyPayload): Promise<void>;
+    /** Broadcast a notification to all sockets in a room. */
+    room(roomId: string, payload: HiveNotifyPayload): Promise<void>;
+    private post;
+}
+
+declare class HiveSocketClient {
+    readonly notify: NotifyResource;
+    private readonly baseUrl;
+    private readonly apiKey;
+    private readonly timeout;
+    constructor(config: HiveSocketConfig);
+    /** Check the Hive-Socket server health and current connection count. */
+    health(): Promise<HiveHealthResponse>;
+}
+/**
+ * Create a Hive-Socket server-side client.
+ *
+ * @example
+ * const hive = createHiveSocketClient({
+ *   baseUrl: process.env.HIVE_SOCKET_URL!,
+ *   apiKey: process.env.HIVE_SOCKET_API_KEY!,
+ * });
+ * await hive.notify.user(userId, { projectId, title: 'Hey', body: 'Msg', type: 'message' });
+ */
+declare function createHiveSocketClient(config: HiveSocketConfig): HiveSocketClient;
+
+declare class HiveSocketError extends Error {
+    readonly statusCode: number;
+    constructor(message: string, statusCode: number);
+}
+/** Thrown when the API key is wrong (HTTP 401) */
+declare class HiveSocketAuthError extends HiveSocketError {
+    constructor(message?: string);
+}
+/** Thrown when the fetch fails entirely (network down, timeout) */
+declare class HiveSocketNetworkError extends HiveSocketError {
+    constructor(message: string);
+}
+
+export { type HiveHealthResponse, type HiveNotifyPayload, HiveSocketAuthError, HiveSocketClient, type HiveSocketConfig, HiveSocketError, HiveSocketNetworkError, type NotificationType, NotifyResource, createHiveSocketClient };

package/dist/index.js

@@ -0,0 +1,115 @@
+// src/errors.ts
+var HiveSocketError = class extends Error {
+  statusCode;
+  constructor(message, statusCode) {
+    super(message);
+    this.name = "HiveSocketError";
+    this.statusCode = statusCode;
+  }
+};
+var HiveSocketAuthError = class extends HiveSocketError {
+  constructor(message = "Invalid API key") {
+    super(message, 401);
+    this.name = "HiveSocketAuthError";
+  }
+};
+var HiveSocketNetworkError = class extends HiveSocketError {
+  constructor(message) {
+    super(message, 0);
+    this.name = "HiveSocketNetworkError";
+  }
+};
+
+// src/resources/notify.ts
+var NotifyResource = class {
+  constructor(baseUrl, apiKey, timeout) {
+    this.baseUrl = baseUrl;
+    this.apiKey = apiKey;
+    this.timeout = timeout;
+  }
+  baseUrl;
+  apiKey;
+  timeout;
+  /** Push a notification to a specific user's connected sockets. */
+  async user(userId, payload) {
+    await this.post(`/internal/notify/user/${encodeURIComponent(userId)}`, payload);
+  }
+  /** Broadcast a notification to all sockets in a room. */
+  async room(roomId, payload) {
+    await this.post(`/internal/notify/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 request 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;
+  baseUrl;
+  apiKey;
+  timeout;
+  constructor(config) {
+    this.baseUrl = config.baseUrl.replace(/\/$/, "");
+    this.apiKey = config.apiKey;
+    this.timeout = config.timeout ?? 1e4;
+    this.notify = new NotifyResource(this.baseUrl, this.apiKey, this.timeout);
+  }
+  /** Check the Hive-Socket server health and current connection count. */
+  async health() {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), this.timeout);
+    try {
+      const res = await fetch(`${this.baseUrl}/health`, {
+        signal: controller.signal
+      });
+      if (!res.ok) throw new HiveSocketNetworkError(`Health check failed: ${res.statusText}`);
+      return res.json();
+    } catch (err) {
+      if (err instanceof HiveSocketNetworkError) throw err;
+      const msg = err instanceof Error ? err.message : String(err);
+      throw new HiveSocketNetworkError(
+        controller.signal.aborted ? `Health check timed out after ${this.timeout}ms` : msg
+      );
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+};
+function createHiveSocketClient(config) {
+  return new HiveSocketClient(config);
+}
+export {
+  HiveSocketAuthError,
+  HiveSocketClient,
+  HiveSocketError,
+  HiveSocketNetworkError,
+  NotifyResource,
+  createHiveSocketClient
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +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":[]}

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@smarthivelabs-devs/hive-socket-node",
+  "version": "1.0.0",
+  "description": "Node.js SDK for Hive-Socket — push notifications and events to connected clients",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "sideEffects": false,
+  "files": ["dist", "README.md"],
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "pnpm run build && pnpm run typecheck"
+  },
+  "devDependencies": {
+    "tsup": "^8.0.0",
+    "typescript": "^5.0.0"
+  },
+  "engines": { "node": ">=18.0.0" },
+  "publishConfig": { "access": "public" }
+}