@rivium/sync-node 0.1.0 → 0.2.0

package/README.md

@@ -4,7 +4,7 @@ Official Node.js SDK for RiviumSync Realtime Database. Designed for server-side
 
 ## Features
 
-- **Admin-level access** - Bypasses security rules by default
+- **Server-side access** - Authenticates with your server secret, not an app key
 - **Full CRUD operations** - Create, read, update, delete documents
 - **Query support** - Filters, sorting, pagination
 - **Batch operations** - Atomic writes across multiple documents
@@ -31,8 +31,8 @@ import { RiviumSyncAdmin } from '@rivium/sync-node';
 
 // Initialize with your Project API Key and Server Secret
 const riviumSync = new RiviumSyncAdmin({
-  apiKey: process.env.RIVIUM_SYNC_API_KEY,           // nl_live_xxx or nl_test_xxx
-  serverSecret: process.env.RIVIUM_SYNC_SERVER_SECRET, // nl_srv_xxx - Required for server-side operations
+  apiKey: process.env.RIVIUM_SYNC_API_KEY,           // rv_live_xxx
+  serverSecret: process.env.RIVIUM_SYNC_SERVER_SECRET, // rv_srv_xxx - Required for server-side operations
 });
 
 // Get a database reference (database must be created via dashboard first)
@@ -42,7 +42,7 @@ const db = riviumSync.database('your-database-id');
 const users = db.collection('users');
 ```
 
-> **Note:** Both `apiKey` and `serverSecret` are required for all server-side SDK operations. You can find these credentials in your [AuthLeap Dashboard](https://console.authleap.com) when you create a project. Database creation and deletion is managed via the dashboard, not via SDK.
+> **Note:** Both `apiKey` and `serverSecret` are required for all server-side SDK operations. You can find these credentials in [Rivium Console](https://console.rivium.co) when you create a project. Database creation and deletion is managed via the dashboard, not via SDK.
 
 ## CRUD Operations
 
@@ -201,13 +201,34 @@ unsubscribeAll();
 unsubscribeQuery();
 ```
 
+## User Tokens
+
+Your app's Security Rules check `auth.uid`. A browser or phone cannot be
+trusted to say who the user is - the API key it ships with is public - so your
+backend mints a short-lived token for the user it has already signed in, and
+the client SDK sends it:
+
+```typescript
+// In your backend, behind your own session check:
+app.post('/rivium-sync-token', async (req, res) => {
+  const { token, expiresIn } = await riviumSync.createUserToken(req.session.userId);
+  res.json({ token, expiresIn });
+});
+```
+
+The client passes that to its `tokenProvider` option. Tokens last an hour by
+default; pass a second argument in seconds to change it, up to 24 hours.
+
+This SDK holds the server secret, so it is already trusted and never needs a
+token of its own.
+
 ## Configuration Options
 
 ```typescript
 const riviumSync = new RiviumSyncAdmin({
   // Required
-  apiKey: 'nl_live_xxxxxxxxxxxxxxxxxxxxx',        // Required - from AuthLeap Dashboard
-  serverSecret: 'nl_srv_xxxxxxxxxxxxxxxxxxxxx',   // Required - from AuthLeap Dashboard
+  apiKey: 'rv_live_xxxxxxxxxxxxxxxxxxxxx',        // Required - from Rivium Console
+  serverSecret: 'rv_srv_xxxxxxxxxxxxxxxxxxxxx',   // Required - from Rivium Console
 
   // Optional
   enableRealtime: false, // Enable MQTT subscriptions
@@ -220,10 +241,10 @@ const riviumSync = new RiviumSyncAdmin({
 
 | Credential | Format | Description |
 |------------|--------|-------------|
-| **API Key** | `nl_live_xxx` or `nl_test_xxx` | Used for client-side SDKs and server-side SDKs |
-| **Server Secret** | `nl_srv_xxx` | **Required** for server-side operations. Never expose in client-side code. |
+| **API Key** | `rv_live_xxx` | Used for client-side SDKs and server-side SDKs |
+| **Server Secret** | `rv_srv_xxx` | **Required** for server-side operations. Never expose in client-side code. |
 
-Both credentials are generated when you create a project in the [AuthLeap Dashboard](https://console.authleap.com). Store them securely and never commit them to version control.
+Both credentials are generated when you create a project in [Rivium Console](https://console.rivium.co). Store them securely and never commit them to version control.
 
 ### Log Levels
 

package/dist/index.d.mts

@@ -55,7 +55,7 @@ declare enum RiviumSyncLogLevel {
 interface RiviumSyncAdminConfig {
     /** Your Project API Key (rv_live_xxx or rv_test_xxx) - REQUIRED */
     apiKey: string;
-    /** Server secret for server-side authentication (nl_srv_xxx) - REQUIRED for all server operations */
+    /** Server secret for server-side authentication (rv_srv_xxx) - REQUIRED for all server operations */
     serverSecret: string;
     /** Optional user identifier for Security Rules (used as auth.uid when acting on behalf of a user) */
     userId?: string;
@@ -303,6 +303,32 @@ declare class RiviumSyncAdmin {
     constructor(config: RiviumSyncAdminConfig);
     private log;
     setLogLevel(level: RiviumSyncLogLevel): void;
+    /**
+     * Mint a user token so your app can prove who the acting user is.
+     *
+     * Security Rules read `auth.uid`. A client cannot set that itself - the API
+     * key it ships with is public, so the server would have no reason to believe
+     * it. Your backend, which holds the server secret, calls this and hands the
+     * token to the app; the client SDKs take it through their `tokenProvider`
+     * option and send it on every request.
+     *
+     * Never ship the server secret (or this call) inside an app.
+     *
+     * @param userId  Your own id for the signed-in user - whatever your rules expect.
+     * @param expiresIn Lifetime in seconds. Default 1 hour, maximum 24 hours.
+     *
+     * @example
+     * // In your Express backend, behind your own session check:
+     * app.post('/rivium-sync-token', async (req, res) => {
+     *   const { token, expiresIn } = await sync.createUserToken(req.session.userId);
+     *   res.json({ token, expiresIn });
+     * });
+     */
+    createUserToken(userId: string, expiresIn?: number): Promise<{
+        token: string;
+        userId: string;
+        expiresIn: number;
+    }>;
     private request;
     /**
      * Get a database reference
@@ -319,6 +345,13 @@ declare class RiviumSyncAdmin {
     updateDocument<T>(databaseId: string, collectionId: string, documentId: string, data: Partial<T>): Promise<void>;
     deleteDocument(databaseId: string, collectionId: string, documentId: string): Promise<void>;
     executeBatch(operations: BatchOperation[]): Promise<void>;
+    /** Project the API key belongs to, from POST /connections/token. */
+    private projectId;
+    /**
+     * Topic for a collection or a single document.
+     * `rivium_sync/{projectId}/{databaseName}/{collectionName}[/{documentId}]`
+     */
+    private topicFor;
     private initRealtime;
     private connectMqtt;
     listenDocument<T>(databaseId: string, collectionId: string, documentId: string, callback: DocumentListener<T>): Unsubscribe;

package/dist/index.d.ts

@@ -55,7 +55,7 @@ declare enum RiviumSyncLogLevel {
 interface RiviumSyncAdminConfig {
     /** Your Project API Key (rv_live_xxx or rv_test_xxx) - REQUIRED */
     apiKey: string;
-    /** Server secret for server-side authentication (nl_srv_xxx) - REQUIRED for all server operations */
+    /** Server secret for server-side authentication (rv_srv_xxx) - REQUIRED for all server operations */
     serverSecret: string;
     /** Optional user identifier for Security Rules (used as auth.uid when acting on behalf of a user) */
     userId?: string;
@@ -303,6 +303,32 @@ declare class RiviumSyncAdmin {
     constructor(config: RiviumSyncAdminConfig);
     private log;
     setLogLevel(level: RiviumSyncLogLevel): void;
+    /**
+     * Mint a user token so your app can prove who the acting user is.
+     *
+     * Security Rules read `auth.uid`. A client cannot set that itself - the API
+     * key it ships with is public, so the server would have no reason to believe
+     * it. Your backend, which holds the server secret, calls this and hands the
+     * token to the app; the client SDKs take it through their `tokenProvider`
+     * option and send it on every request.
+     *
+     * Never ship the server secret (or this call) inside an app.
+     *
+     * @param userId  Your own id for the signed-in user - whatever your rules expect.
+     * @param expiresIn Lifetime in seconds. Default 1 hour, maximum 24 hours.
+     *
+     * @example
+     * // In your Express backend, behind your own session check:
+     * app.post('/rivium-sync-token', async (req, res) => {
+     *   const { token, expiresIn } = await sync.createUserToken(req.session.userId);
+     *   res.json({ token, expiresIn });
+     * });
+     */
+    createUserToken(userId: string, expiresIn?: number): Promise<{
+        token: string;
+        userId: string;
+        expiresIn: number;
+    }>;
     private request;
     /**
      * Get a database reference
@@ -319,6 +345,13 @@ declare class RiviumSyncAdmin {
     updateDocument<T>(databaseId: string, collectionId: string, documentId: string, data: Partial<T>): Promise<void>;
     deleteDocument(databaseId: string, collectionId: string, documentId: string): Promise<void>;
     executeBatch(operations: BatchOperation[]): Promise<void>;
+    /** Project the API key belongs to, from POST /connections/token. */
+    private projectId;
+    /**
+     * Topic for a collection or a single document.
+     * `rivium_sync/{projectId}/{databaseName}/{collectionName}[/{documentId}]`
+     */
+    private topicFor;
     private initRealtime;
     private connectMqtt;
     listenDocument<T>(databaseId: string, collectionId: string, documentId: string, callback: DocumentListener<T>): Unsubscribe;

package/dist/index.js

@@ -379,6 +379,11 @@ var _RiviumSyncAdmin = class _RiviumSyncAdmin {
     this.documentListeners = /* @__PURE__ */ new Map();
     this.collectionListeners = /* @__PURE__ */ new Map();
     this.cachedCollections = /* @__PURE__ */ new Map();
+    // ==========================================================================
+    // Realtime (Optional)
+    // ==========================================================================
+    /** Project the API key belongs to, from POST /connections/token. */
+    this.projectId = null;
     if (!config.apiKey) {
       throw new RiviumSyncError(1301 /* MISSING_API_KEY */);
     }
@@ -425,6 +430,40 @@ var _RiviumSyncAdmin = class _RiviumSyncAdmin {
   // ==========================================================================
   // HTTP Client
   // ==========================================================================
+  /**
+   * Mint a user token so your app can prove who the acting user is.
+   *
+   * Security Rules read `auth.uid`. A client cannot set that itself - the API
+   * key it ships with is public, so the server would have no reason to believe
+   * it. Your backend, which holds the server secret, calls this and hands the
+   * token to the app; the client SDKs take it through their `tokenProvider`
+   * option and send it on every request.
+   *
+   * Never ship the server secret (or this call) inside an app.
+   *
+   * @param userId  Your own id for the signed-in user - whatever your rules expect.
+   * @param expiresIn Lifetime in seconds. Default 1 hour, maximum 24 hours.
+   *
+   * @example
+   * // In your Express backend, behind your own session check:
+   * app.post('/rivium-sync-token', async (req, res) => {
+   *   const { token, expiresIn } = await sync.createUserToken(req.session.userId);
+   *   res.json({ token, expiresIn });
+   * });
+   */
+  async createUserToken(userId, expiresIn) {
+    if (!userId) {
+      throw new RiviumSyncError(
+        1300 /* INVALID_CONFIG */,
+        "createUserToken requires a userId"
+      );
+    }
+    return this.request(
+      "POST",
+      "/users/token",
+      expiresIn === void 0 ? { userId } : { userId, expiresIn }
+    );
+  }
   async request(method, path, body) {
     const url = `${this.config.baseUrl}${path}`;
     const headers = {
@@ -598,13 +637,19 @@ var _RiviumSyncAdmin = class _RiviumSyncAdmin {
       }
     }
   }
-  // ==========================================================================
-  // Realtime (Optional)
-  // ==========================================================================
+  /**
+   * Topic for a collection or a single document.
+   * `rivium_sync/{projectId}/{databaseName}/{collectionName}[/{documentId}]`
+   */
+  topicFor(databaseId, collectionId, documentId) {
+    const base = `rivium_sync/${this.projectId ?? "unknown"}/${databaseId}/${collectionId}`;
+    return documentId === void 0 ? base : `${base}/${documentId}`;
+  }
   async initRealtime() {
     try {
       this.log(4 /* DEBUG */, "Fetching MQTT token...");
       const tokenData = await this.request("POST", "/connections/token");
+      this.projectId = tokenData.projectId ?? null;
       this.mqttConfig = {
         host: tokenData.mqtt.host,
         port: tokenData.mqtt.port,
@@ -661,7 +706,7 @@ var _RiviumSyncAdmin = class _RiviumSyncAdmin {
       };
     }
     const path = `/${databaseId}/${collectionId}/${documentId}`;
-    const mqttTopic = `rivium_sync/${this.config.apiKey.substring(0, 16)}/db/${databaseId}/${collectionId}/${documentId}`;
+    const mqttTopic = this.topicFor(databaseId, collectionId, documentId);
     if (!this.documentListeners.has(path)) {
       this.documentListeners.set(path, /* @__PURE__ */ new Set());
     }
@@ -693,7 +738,7 @@ var _RiviumSyncAdmin = class _RiviumSyncAdmin {
       };
     }
     const path = `/${databaseId}/${collectionId}`;
-    const mqttTopic = `rivium_sync/${this.config.apiKey.substring(0, 16)}/db/${databaseId}/${collectionId}/+`;
+    const mqttTopic = this.topicFor(databaseId, collectionId, "changes");
     if (!this.collectionListeners.has(path)) {
       this.collectionListeners.set(path, /* @__PURE__ */ new Set());
     }
@@ -725,12 +770,11 @@ var _RiviumSyncAdmin = class _RiviumSyncAdmin {
   }
   resubscribeAll() {
     if (!this.mqttClient?.connected) return;
-    const appId = this.config.apiKey.substring(0, 16);
     this.documentListeners.forEach((_, path) => {
       const parts = path.split("/").filter((p) => p);
       if (parts.length === 3) {
         const [databaseId, collectionId, documentId] = parts;
-        const topic = `rivium_sync/${appId}/db/${databaseId}/${collectionId}/${documentId}`;
+        const topic = this.topicFor(databaseId, collectionId, documentId);
         this.mqttClient.subscribe(topic, { qos: 1 });
       }
     });
@@ -738,7 +782,7 @@ var _RiviumSyncAdmin = class _RiviumSyncAdmin {
       const parts = path.split("/").filter((p) => p);
       if (parts.length === 2) {
         const [databaseId, collectionId] = parts;
-        const topic = `rivium_sync/${appId}/db/${databaseId}/${collectionId}/+`;
+        const topic = this.topicFor(databaseId, collectionId, "changes");
         this.mqttClient.subscribe(topic, { qos: 1 });
       }
     });

package/dist/index.mjs

@@ -336,6 +336,11 @@ var _RiviumSyncAdmin = class _RiviumSyncAdmin {
     this.documentListeners = /* @__PURE__ */ new Map();
     this.collectionListeners = /* @__PURE__ */ new Map();
     this.cachedCollections = /* @__PURE__ */ new Map();
+    // ==========================================================================
+    // Realtime (Optional)
+    // ==========================================================================
+    /** Project the API key belongs to, from POST /connections/token. */
+    this.projectId = null;
     if (!config.apiKey) {
       throw new RiviumSyncError(1301 /* MISSING_API_KEY */);
     }
@@ -382,6 +387,40 @@ var _RiviumSyncAdmin = class _RiviumSyncAdmin {
   // ==========================================================================
   // HTTP Client
   // ==========================================================================
+  /**
+   * Mint a user token so your app can prove who the acting user is.
+   *
+   * Security Rules read `auth.uid`. A client cannot set that itself - the API
+   * key it ships with is public, so the server would have no reason to believe
+   * it. Your backend, which holds the server secret, calls this and hands the
+   * token to the app; the client SDKs take it through their `tokenProvider`
+   * option and send it on every request.
+   *
+   * Never ship the server secret (or this call) inside an app.
+   *
+   * @param userId  Your own id for the signed-in user - whatever your rules expect.
+   * @param expiresIn Lifetime in seconds. Default 1 hour, maximum 24 hours.
+   *
+   * @example
+   * // In your Express backend, behind your own session check:
+   * app.post('/rivium-sync-token', async (req, res) => {
+   *   const { token, expiresIn } = await sync.createUserToken(req.session.userId);
+   *   res.json({ token, expiresIn });
+   * });
+   */
+  async createUserToken(userId, expiresIn) {
+    if (!userId) {
+      throw new RiviumSyncError(
+        1300 /* INVALID_CONFIG */,
+        "createUserToken requires a userId"
+      );
+    }
+    return this.request(
+      "POST",
+      "/users/token",
+      expiresIn === void 0 ? { userId } : { userId, expiresIn }
+    );
+  }
   async request(method, path, body) {
     const url = `${this.config.baseUrl}${path}`;
     const headers = {
@@ -555,13 +594,19 @@ var _RiviumSyncAdmin = class _RiviumSyncAdmin {
       }
     }
   }
-  // ==========================================================================
-  // Realtime (Optional)
-  // ==========================================================================
+  /**
+   * Topic for a collection or a single document.
+   * `rivium_sync/{projectId}/{databaseName}/{collectionName}[/{documentId}]`
+   */
+  topicFor(databaseId, collectionId, documentId) {
+    const base = `rivium_sync/${this.projectId ?? "unknown"}/${databaseId}/${collectionId}`;
+    return documentId === void 0 ? base : `${base}/${documentId}`;
+  }
   async initRealtime() {
     try {
       this.log(4 /* DEBUG */, "Fetching MQTT token...");
       const tokenData = await this.request("POST", "/connections/token");
+      this.projectId = tokenData.projectId ?? null;
       this.mqttConfig = {
         host: tokenData.mqtt.host,
         port: tokenData.mqtt.port,
@@ -618,7 +663,7 @@ var _RiviumSyncAdmin = class _RiviumSyncAdmin {
       };
     }
     const path = `/${databaseId}/${collectionId}/${documentId}`;
-    const mqttTopic = `rivium_sync/${this.config.apiKey.substring(0, 16)}/db/${databaseId}/${collectionId}/${documentId}`;
+    const mqttTopic = this.topicFor(databaseId, collectionId, documentId);
     if (!this.documentListeners.has(path)) {
       this.documentListeners.set(path, /* @__PURE__ */ new Set());
     }
@@ -650,7 +695,7 @@ var _RiviumSyncAdmin = class _RiviumSyncAdmin {
       };
     }
     const path = `/${databaseId}/${collectionId}`;
-    const mqttTopic = `rivium_sync/${this.config.apiKey.substring(0, 16)}/db/${databaseId}/${collectionId}/+`;
+    const mqttTopic = this.topicFor(databaseId, collectionId, "changes");
     if (!this.collectionListeners.has(path)) {
       this.collectionListeners.set(path, /* @__PURE__ */ new Set());
     }
@@ -682,12 +727,11 @@ var _RiviumSyncAdmin = class _RiviumSyncAdmin {
   }
   resubscribeAll() {
     if (!this.mqttClient?.connected) return;
-    const appId = this.config.apiKey.substring(0, 16);
     this.documentListeners.forEach((_, path) => {
       const parts = path.split("/").filter((p) => p);
       if (parts.length === 3) {
         const [databaseId, collectionId, documentId] = parts;
-        const topic = `rivium_sync/${appId}/db/${databaseId}/${collectionId}/${documentId}`;
+        const topic = this.topicFor(databaseId, collectionId, documentId);
         this.mqttClient.subscribe(topic, { qos: 1 });
       }
     });
@@ -695,7 +739,7 @@ var _RiviumSyncAdmin = class _RiviumSyncAdmin {
       const parts = path.split("/").filter((p) => p);
       if (parts.length === 2) {
         const [databaseId, collectionId] = parts;
-        const topic = `rivium_sync/${appId}/db/${databaseId}/${collectionId}/+`;
+        const topic = this.topicFor(databaseId, collectionId, "changes");
         this.mqttClient.subscribe(topic, { qos: 1 });
       }
     });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rivium/sync-node",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "RiviumSync Node.js SDK - Server-side SDK for RiviumSync Realtime Database",
   "main": "dist/index.js",
   "module": "dist/index.mjs",