@rivium/chat 0.1.1 → 0.1.3

package/README.md

@@ -79,6 +79,30 @@ const summary = await riviumChat.rooms.getUnreadSummary('user-1');
 
 ## API Reference
 
+### Users — verified identity (recommended)
+
+Your API key ships inside every app, so it cannot prove who a user is. Mint a
+short-lived token here and hand it to the client SDK's `tokenProvider`:
+
+```typescript
+// Express example — your own login protects the route
+app.get('/chat-token', requireLogin, async (req, res) => {
+  const { token } = await riviumChat.users.createToken({ userId: req.user.id });
+  res.json({ token });
+});
+```
+
+```typescript
+riviumChat.users.createToken({ userId, info?, ttl? })  // 1 h default, 24 h max
+riviumChat.users.revokeTokens(userId)                  // on logout, password change, ban
+riviumChat.users.getNotificationSettings(userId)                // App-wide push settings
+riviumChat.users.updateNotificationSettings(userId, options)    // Turn chat pushes off, mentions only, mute
+```
+
+`revokeTokens` invalidates every token issued to that user so far; it takes
+effect within about 15 seconds across servers. Client SDKs then ask your
+endpoint for a new token, so a signed-out user gets nothing.
+
 ### Rooms
 
 ```typescript
@@ -91,6 +115,8 @@ riviumChat.rooms.addParticipant(roomId, options)      // Add participant to room
 riviumChat.rooms.removeParticipant(roomId, userId)    // Remove participant (idempotent)
 riviumChat.rooms.delete(roomId)                       // Permanently delete a room
 riviumChat.rooms.getUnreadSummary(userId)             // Get unread counts
+riviumChat.rooms.getNotificationSettings(roomId, userId)             // A user's push settings for a room
+riviumChat.rooms.updateNotificationSettings(roomId, userId, options) // Mute a room or mentions only
 ```
 
 ### Messages
@@ -160,6 +186,31 @@ await riviumChat.webhooks.setPushTemplates({
 });
 ```
 
+### Notification settings
+
+Let each user decide which chat pushes they get. Nothing changes until you set something.
+
+```typescript
+// Turn off chat pushes for a user across your app
+await riviumChat.users.updateNotificationSettings('user-1', { pushLevel: 'none' });
+
+// Only push when mentioned, and no reaction pushes
+await riviumChat.users.updateNotificationSettings('user-1', {
+  pushLevel: 'mentions',
+  disabledEvents: ['reaction'],
+});
+
+// Mute one room for 8 hours, then unmute
+await riviumChat.rooms.updateNotificationSettings(roomId, 'user-1', {
+  mutedUntil: new Date(Date.now() + 8 * 3600_000),
+});
+await riviumChat.rooms.updateNotificationSettings(roomId, 'user-1', { mutedUntil: null });
+
+await riviumChat.users.getNotificationSettings('user-1');
+```
+
+`pushLevel` is `all` (default), `mentions` or `none`. App-wide and room settings both apply: a push is sent only if neither blocks it.
+
 ## Links
 
 - [Rivium Chat](https://rivium.co/cloud/rivium-chat) - Learn more about Rivium Chat

package/dist/index.d.ts

@@ -4,6 +4,7 @@ import { Reactions } from './modules/reactions';
 import { Pins } from './modules/pins';
 import { Webhooks } from './modules/webhooks';
 import { Tokens } from './modules/tokens';
+import { Users } from './modules/users';
 import { RiviumChatConfig } from './types';
 export declare class RiviumChat {
     private client;
@@ -19,6 +20,8 @@ export declare class RiviumChat {
     webhooks: Webhooks;
     /** Centrifugo connection tokens */
     tokens: Tokens;
+    /** User tokens — verified identity for your client apps */
+    users: Users;
     constructor(config: RiviumChatConfig);
 }
 export { RiviumChatError } from './client';

package/dist/index.js

@@ -22,6 +22,7 @@ const reactions_1 = require("./modules/reactions");
 const pins_1 = require("./modules/pins");
 const webhooks_1 = require("./modules/webhooks");
 const tokens_1 = require("./modules/tokens");
+const users_1 = require("./modules/users");
 class RiviumChat {
     constructor(config) {
         this.client = new client_1.HttpClient(config);
@@ -31,6 +32,7 @@ class RiviumChat {
         this.pins = new pins_1.Pins(this.client);
         this.webhooks = new webhooks_1.Webhooks(this.client);
         this.tokens = new tokens_1.Tokens(this.client);
+        this.users = new users_1.Users(this.client);
     }
 }
 exports.RiviumChat = RiviumChat;

package/dist/modules/rooms.d.ts

@@ -1,5 +1,5 @@
 import { HttpClient } from '../client';
-import { Room, CreateRoomOptions, AddParticipantOptions, Participant, UnreadSummary } from '../types';
+import { Room, CreateRoomOptions, AddParticipantOptions, Participant, UnreadSummary, NotificationSettings, UpdateNotificationSettingsOptions } from '../types';
 export declare class Rooms {
     private client;
     constructor(client: HttpClient);
@@ -23,4 +23,15 @@ export declare class Rooms {
     delete(roomId: string): Promise<{
         success: boolean;
     }>;
+    /** A participant's push settings for one room. */
+    getNotificationSettings(roomId: string, userId: string): Promise<NotificationSettings>;
+    /**
+     * Changes a participant's push settings for one room: mute it, or only
+     * notify on mentions. The user must be in the room.
+     *
+     * ```ts
+     * await chat.rooms.updateNotificationSettings(roomId, 'user-1', { pushLevel: 'mentions' });
+     * ```
+     */
+    updateNotificationSettings(roomId: string, userId: string, settings: UpdateNotificationSettingsOptions): Promise<NotificationSettings>;
 }

package/dist/modules/rooms.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Rooms = void 0;
+const users_1 = require("./users");
 class Rooms {
     constructor(client) {
         this.client = client;
@@ -41,5 +42,20 @@ class Rooms {
     async delete(roomId) {
         return this.client.delete(`/api/v1/rooms/${roomId}`);
     }
+    /** A participant's push settings for one room. */
+    async getNotificationSettings(roomId, userId) {
+        return this.client.get(`/api/v1/rooms/${roomId}/notification-settings`, { userId });
+    }
+    /**
+     * Changes a participant's push settings for one room: mute it, or only
+     * notify on mentions. The user must be in the room.
+     *
+     * ```ts
+     * await chat.rooms.updateNotificationSettings(roomId, 'user-1', { pushLevel: 'mentions' });
+     * ```
+     */
+    async updateNotificationSettings(roomId, userId, settings) {
+        return this.client.put(`/api/v1/rooms/${roomId}/notification-settings`, (0, users_1.settingsBody)(userId, settings));
+    }
 }
 exports.Rooms = Rooms;

package/dist/modules/users.d.ts

@@ -0,0 +1,48 @@
+import { HttpClient } from '../client';
+import { CreateUserTokenOptions, UserToken, RevokeTokensResult, NotificationSettings, UpdateNotificationSettingsOptions } from '../types';
+export declare function settingsBody(userId: string, settings: UpdateNotificationSettingsOptions): {
+    mutedUntil?: string | null | undefined;
+    pushLevel?: import("../types").PushLevel;
+    disabledEvents?: string[];
+    userId: string;
+};
+/**
+ * User tokens — how your app proves **who** the user is.
+ *
+ * Your API key ships inside every app, so it cannot identify a user. Mint a
+ * short-lived token here (server-side, with your server secret) and hand it to
+ * the client SDK's `tokenProvider`. The client SDKs refresh it automatically.
+ */
+export declare class Users {
+    private client;
+    constructor(client: HttpClient);
+    /**
+     * Creates a token for one of your users. Expires in 1 hour by default
+     * (`ttl` seconds, max 24 hours).
+     *
+     * ```ts
+     * app.get('/chat-token', requireLogin, async (req, res) => {
+     *   const { token } = await chat.users.createToken({ userId: req.user.id });
+     *   res.json({ token });
+     * });
+     * ```
+     */
+    createToken(options: CreateUserTokenOptions): Promise<UserToken>;
+    /**
+     * Invalidates every token issued to this user so far — call it on logout,
+     * password change or ban. Tokens already in the user's hands stop working
+     * within seconds, for REST and realtime alike.
+     */
+    revokeTokens(userId: string): Promise<RevokeTokensResult>;
+    /** A user's chat push settings for your whole app. */
+    getNotificationSettings(userId: string): Promise<NotificationSettings>;
+    /**
+     * Changes a user's chat push settings for your whole app, e.g. to turn chat
+     * pushes off from your own settings screen.
+     *
+     * ```ts
+     * await chat.users.updateNotificationSettings('user-1', { pushLevel: 'none' });
+     * ```
+     */
+    updateNotificationSettings(userId: string, settings: UpdateNotificationSettingsOptions): Promise<NotificationSettings>;
+}

package/dist/modules/users.js

@@ -0,0 +1,64 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Users = void 0;
+exports.settingsBody = settingsBody;
+function settingsBody(userId, settings) {
+    const { mutedUntil, ...rest } = settings;
+    return {
+        userId,
+        ...rest,
+        ...(mutedUntil !== undefined && {
+            mutedUntil: mutedUntil instanceof Date ? mutedUntil.toISOString() : mutedUntil,
+        }),
+    };
+}
+/**
+ * User tokens — how your app proves **who** the user is.
+ *
+ * Your API key ships inside every app, so it cannot identify a user. Mint a
+ * short-lived token here (server-side, with your server secret) and hand it to
+ * the client SDK's `tokenProvider`. The client SDKs refresh it automatically.
+ */
+class Users {
+    constructor(client) {
+        this.client = client;
+    }
+    /**
+     * Creates a token for one of your users. Expires in 1 hour by default
+     * (`ttl` seconds, max 24 hours).
+     *
+     * ```ts
+     * app.get('/chat-token', requireLogin, async (req, res) => {
+     *   const { token } = await chat.users.createToken({ userId: req.user.id });
+     *   res.json({ token });
+     * });
+     * ```
+     */
+    async createToken(options) {
+        return this.client.post('/api/v1/users/token', options);
+    }
+    /**
+     * Invalidates every token issued to this user so far — call it on logout,
+     * password change or ban. Tokens already in the user's hands stop working
+     * within seconds, for REST and realtime alike.
+     */
+    async revokeTokens(userId) {
+        return this.client.post(`/api/v1/users/${encodeURIComponent(userId)}/revoke-tokens`);
+    }
+    /** A user's chat push settings for your whole app. */
+    async getNotificationSettings(userId) {
+        return this.client.get('/api/v1/users/notification-settings', { userId });
+    }
+    /**
+     * Changes a user's chat push settings for your whole app, e.g. to turn chat
+     * pushes off from your own settings screen.
+     *
+     * ```ts
+     * await chat.users.updateNotificationSettings('user-1', { pushLevel: 'none' });
+     * ```
+     */
+    async updateNotificationSettings(userId, settings) {
+        return this.client.put('/api/v1/users/notification-settings', settingsBody(userId, settings));
+    }
+}
+exports.Users = Users;

package/dist/types.d.ts

@@ -160,3 +160,47 @@ export interface GetTokenOptions {
     userId: string;
     info?: Record<string, any>;
 }
+export interface CreateUserTokenOptions {
+    /** Your own id for the user the token is for. */
+    userId: string;
+    /** Public connection info (e.g. displayName) visible to the realtime layer. */
+    info?: Record<string, any>;
+    /** Lifetime in seconds. Default 3600 (1 h), max 86400 (24 h). */
+    ttl?: number;
+}
+export interface UserToken {
+    /** Hand this to the client SDK's tokenProvider. */
+    token: string;
+    /** ISO timestamp; the client SDKs refresh shortly before it. */
+    expiresAt: string;
+    userId: string;
+}
+export interface RevokeTokensResult {
+    /** Tokens issued at or before this moment are no longer accepted. */
+    revokedBefore: string;
+}
+/** `all` (default), `mentions` (only when mentioned) or `none` (no chat pushes). */
+export type PushLevel = 'all' | 'mentions' | 'none';
+export interface NotificationSettings {
+    userId: string;
+    /** `app` for the user's app-wide settings, `room` for one room. */
+    scope: 'app' | 'room';
+    roomId?: string;
+    pushLevel: PushLevel;
+    /** ISO timestamp; no chat pushes until then. */
+    mutedUntil: string | null;
+    /** Push event types turned off, e.g. `reaction`. */
+    disabledEvents: string[];
+    updatedAt: string | null;
+}
+/** Only the fields you pass are changed. */
+export interface UpdateNotificationSettingsOptions {
+    pushLevel?: PushLevel;
+    /** A Date or ISO string to mute until; `null` unmutes. */
+    mutedUntil?: Date | string | null;
+    /**
+     * Event types to turn off: new_message, file_shared, mention, reaction,
+     * message_pinned, room_created, participant_joined, participant_removed.
+     */
+    disabledEvents?: string[];
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rivium/chat",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "RiviumChat Node.js SDK — server-side chat rooms, messages, reactions, pins, and webhooks",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",