@narcisbodea/smstunnel-sdk 1.1.3 → 1.1.4

package/README.md

@@ -1,18 +1,74 @@
-# smstunnel-sdk
+# @narcisbodea/smstunnel-sdk
 
-SMSTunnel SDK - NestJS + React + Vue + framework-agnostic client for SMS pairing.
+SMSTunnel SDK - Node.js + NestJS + React + Vue + Angular + framework-agnostic client for SMS pairing & E2E encryption.
 
 | Import path | Scope |
 |---|---|
-| `smstunnel-sdk` | `SmsTunnelClient` class + types + labels (Angular, Svelte, Astro, Solid, Vanilla JS) |
-| `smstunnel-sdk/server` | NestJS module (backend) |
-| `smstunnel-sdk/react` | React components + hook (also Next.js, Remix, Gatsby) |
-| `smstunnel-sdk/vue` | Vue 3 components + composable (also Nuxt) |
+| `@narcisbodea/smstunnel-sdk` | `SmsTunnelClient` class + types + labels (Svelte, Astro, Solid, Vanilla JS) |
+| `@narcisbodea/smstunnel-sdk/server` | NestJS module (backend proxy) |
+| `@narcisbodea/smstunnel-sdk/react` | React components + hook (Next.js, Remix, Gatsby) |
+| `@narcisbodea/smstunnel-sdk/vue` | Vue 3 components + composable (Nuxt) |
+| `@narcisbodea/smstunnel-sdk/angular` | Angular 17+ injectable service |
+| `@narcisbodea/smstunnel-sdk/node` | Standalone Node.js client (no framework, API key auth) |
 
 ## Install
 
 ```bash
-npm install smstunnel-sdk
+npm install @narcisbodea/smstunnel-sdk
+```
+
+---
+
+## Node.js (Standalone)
+
+Works without NestJS or any framework. Uses native `fetch` (Node 18+), zero external dependencies.
+
+```typescript
+import { SmsTunnelNodeClient } from '@narcisbodea/smstunnel-sdk/node';
+
+const client = new SmsTunnelNodeClient({
+  apiKey: 'sk_live_xxx',
+  serverUrl: 'https://smstunnel.io',
+});
+
+// Send SMS
+const result = await client.sendSms('+40721123456', 'Hello!');
+
+// Send 2FA
+await client.send2FaSms('+40721123456', 'Your code is 123456');
+
+// Send bulk SMS
+await client.sendBulkSms(['+40721111111', '+40722222222'], 'Bulk message');
+
+// Get message status
+const status = await client.getMessageStatus('msg-id');
+
+// Get received SMS (inbox)
+const inbox = await client.getReceivedSms({ limit: 20, page: 1 });
+
+// List devices
+const devices = await client.getDevices();
+
+// E2E Encryption
+const e2eStatus = await client.getDeviceE2EStatus('device-id');
+const publicKey = await client.getDevicePublicKey('device-id');
+const verification = await client.verifyDeviceKey('device-id', 'stored-fingerprint');
+await client.sendEncryptedSms('encrypted-payload', 'device-id', {
+  is2FA: false,
+  expectedFingerprint: 'a1b2c3d4',
+});
+
+// Unified Pairing v2
+const pairing = await client.createPairingToken({
+  source: 'api',
+  displayName: 'My App',
+});
+const pairingStatus = await client.getPairingTokenStatus(pairing.data.token);
+
+// E2E Pairing (with public key exchange)
+const e2ePairing = await client.createE2EPairing({ siteName: 'My App' });
+const e2eResult = await client.pollE2EPairing(e2ePairing.data.token);
+// e2eResult.data.publicKey contains the device's RSA public key
 ```
 
 ---
@@ -26,7 +82,7 @@ The SDK is database-agnostic. You provide a simple adapter with 3 methods:
 #### MongoDB (Mongoose)
 
 ```typescript
-import { SmsTunnelStorageAdapter, SmsTunnelConfig } from 'smstunnel-sdk/server';
+import { SmsTunnelStorageAdapter, SmsTunnelConfig } from '@narcisbodea/smstunnel-sdk/server';
 import { Model } from 'mongoose';
 
 export class MongoSmsTunnelStorage implements SmsTunnelStorageAdapter {
@@ -62,7 +118,7 @@ export class MongoSmsTunnelStorage implements SmsTunnelStorageAdapter {
 #### Prisma (PostgreSQL)
 
 ```typescript
-import { SmsTunnelStorageAdapter, SmsTunnelConfig } from 'smstunnel-sdk/server';
+import { SmsTunnelStorageAdapter, SmsTunnelConfig } from '@narcisbodea/smstunnel-sdk/server';
 import { PrismaClient } from '@prisma/client';
 
 export class PrismaSmsTunnelStorage implements SmsTunnelStorageAdapter {
@@ -93,7 +149,7 @@ export class PrismaSmsTunnelStorage implements SmsTunnelStorageAdapter {
 #### JSON File
 
 ```typescript
-import { SmsTunnelStorageAdapter, SmsTunnelConfig } from 'smstunnel-sdk/server';
+import { SmsTunnelStorageAdapter, SmsTunnelConfig } from '@narcisbodea/smstunnel-sdk/server';
 import { readFile, writeFile } from 'fs/promises';
 
 export class JsonFileStorage implements SmsTunnelStorageAdapter {
@@ -118,7 +174,7 @@ export class JsonFileStorage implements SmsTunnelStorageAdapter {
 ### 2. Register the Module
 
 ```typescript
-import { SmsTunnelModule } from 'smstunnel-sdk/server';
+import { SmsTunnelModule } from '@narcisbodea/smstunnel-sdk/server';
 
 @Module({
   imports: [
@@ -147,7 +203,7 @@ SmsTunnelModule.forRootAsync({
 
 ### Multi-Tenant (Enterprise/SaaS) Mode
 
-For **multi-tenant applications** (SaaS platforms, CRMs, ERPs) where each tenant needs their own SMS device, configure the Enterprise API Key. The SDK will automatically provision sub-accounts for each tenant under your Enterprise umbrella:
+For **multi-tenant applications** (SaaS platforms, CRMs, ERPs) where each tenant needs their own SMS device:
 
 ```typescript
 SmsTunnelModule.forRootAsync({
@@ -155,7 +211,6 @@ SmsTunnelModule.forRootAsync({
     storage: new MongoSmsTunnelStorage(settingsModel),
     callbackBaseUrl: process.env.CALLBACK_URL,
     displayName: 'My SaaS App',
-    // Multi-tenant mode
     enterpriseApiKey: process.env.SMSTUNNEL_ENTERPRISE_API_KEY,
     externalId: tenantService.getCurrentTenantId(),
   }),
@@ -163,12 +218,10 @@ SmsTunnelModule.forRootAsync({
 })
 ```
 
-When `enterpriseApiKey` is set, `createPairingToken()` automatically uses `POST /api/v1/saas/activate` to create isolated sub-accounts per tenant. The callback flow and SMS sending remain the same — the SDK handles the routing transparently.
-
 ### 3. Auth Guard Integration
 
 ```typescript
-import { SMSTUNNEL_PUBLIC_PATHS } from 'smstunnel-sdk/server';
+import { SMSTUNNEL_PUBLIC_PATHS } from '@narcisbodea/smstunnel-sdk/server';
 
 // In your JwtAuthGuard:
 if (SMSTUNNEL_PUBLIC_PATHS.some(p => request.url.includes(p))) return true;
@@ -185,6 +238,11 @@ if (SMSTUNNEL_PUBLIC_PATHS.some(p => request.url.includes(p))) return true;
 | `POST /smstunnel/unpair` | unpair | Yes | Disconnect device |
 | `POST /smstunnel/send` | sendSms | Yes | Send SMS |
 | `POST /smstunnel/update-config` | updateConfig | Yes | Set server URL |
+| `GET /smstunnel/e2e-status/:deviceId` | getDeviceE2EStatus | Yes | E2E encryption status |
+| `GET /smstunnel/public-key/:deviceId` | getDevicePublicKey | Yes | Get device public key |
+| `POST /smstunnel/verify-key` | verifyDeviceKey | Yes | Verify key fingerprint |
+| `POST /smstunnel/send-encrypted` | sendEncryptedSms | Yes | Send encrypted SMS |
+| `GET /smstunnel/pairings` | getPairings | Yes | List active pairings |
 
 ---
 
@@ -195,7 +253,7 @@ Works with: **React, Next.js, Remix, Gatsby**
 ### Plug and Play Component
 
 ```tsx
-import { SmsTunnelPairing, RO_LABELS } from 'smstunnel-sdk/react';
+import { SmsTunnelPairing, RO_LABELS } from '@narcisbodea/smstunnel-sdk/react';
 
 function SettingsPage() {
   return (
@@ -220,7 +278,7 @@ Add `'use client'` in your page/component:
 
 ```tsx
 'use client';
-import { SmsTunnelPairing, RO_LABELS } from 'smstunnel-sdk/react';
+import { SmsTunnelPairing, RO_LABELS } from '@narcisbodea/smstunnel-sdk/react';
 
 export default function SmsSettings() {
   return <SmsTunnelPairing apiBaseUrl="/api" labels={RO_LABELS} />;
@@ -230,7 +288,7 @@ export default function SmsSettings() {
 ### Custom UI with Hook
 
 ```tsx
-import { useSmsTunnel, QrCodeCanvas } from 'smstunnel-sdk/react';
+import { useSmsTunnel, QrCodeCanvas } from '@narcisbodea/smstunnel-sdk/react';
 
 function MySmsSettings() {
   const tunnel = useSmsTunnel({
@@ -238,6 +296,12 @@ function MySmsSettings() {
     getAuthHeaders: () => ({ Authorization: `Bearer ${token}` }),
   });
 
+  // E2E Encryption
+  const e2eStatus = await tunnel.getDeviceE2EStatus('device-id');
+  const publicKey = await tunnel.getDevicePublicKey('device-id');
+  const keyValid = await tunnel.verifyDeviceKey('device-id', 'fingerprint');
+  await tunnel.sendEncryptedSms('payload', 'device-id');
+
   if (tunnel.status === 'paired') {
     return <div>Connected: {tunnel.deviceName}</div>;
   }
@@ -269,7 +333,7 @@ Works with: **Vue 3, Nuxt 3**
 
 ```vue
 <script setup>
-import { SmsTunnelPairing, RO_LABELS } from 'smstunnel-sdk/vue';
+import { SmsTunnelPairing, RO_LABELS } from '@narcisbodea/smstunnel-sdk/vue';
 
 function onPaired(device) {
   console.log('Paired:', device);
@@ -299,7 +363,7 @@ Wrap in `<ClientOnly>` since pairing uses browser APIs:
 </template>
 
 <script setup>
-import { SmsTunnelPairing, RO_LABELS } from 'smstunnel-sdk/vue';
+import { SmsTunnelPairing, RO_LABELS } from '@narcisbodea/smstunnel-sdk/vue';
 </script>
 ```
 
@@ -307,12 +371,17 @@ import { SmsTunnelPairing, RO_LABELS } from 'smstunnel-sdk/vue';
 
 ```vue
 <script setup>
-import { useSmsTunnel, QrCodeCanvas } from 'smstunnel-sdk/vue';
+import { useSmsTunnel, QrCodeCanvas } from '@narcisbodea/smstunnel-sdk/vue';
 
 const tunnel = useSmsTunnel({
   apiBaseUrl: '/api',
   getAuthHeaders: () => ({ Authorization: `Bearer ${token}` }),
 });
+
+// E2E Encryption
+const e2eStatus = await tunnel.getDeviceE2EStatus('device-id');
+const publicKey = await tunnel.getDevicePublicKey('device-id');
+await tunnel.sendEncryptedSms('payload', 'device-id');
 </script>
 
 <template>
@@ -336,46 +405,59 @@ const tunnel = useSmsTunnel({
 
 ## Angular
 
-Use the framework-agnostic `SmsTunnelClient` class:
+Works with: **Angular 17+** (standalone)
 
-```typescript
-import { Injectable, OnDestroy } from '@angular/core';
-import { SmsTunnelClient } from 'smstunnel-sdk';
+### Setup
 
-@Injectable({ providedIn: 'root' })
-export class SmsTunnelService implements OnDestroy {
-  private client = new SmsTunnelClient({
-    apiBaseUrl: '/api',
-    getAuthHeaders: () => ({
-      Authorization: `Bearer ${localStorage.getItem('token')}`,
+```typescript
+// app.config.ts
+import { provideSmsTunnel } from '@narcisbodea/smstunnel-sdk/angular';
+
+export const appConfig: ApplicationConfig = {
+  providers: [
+    provideSmsTunnel({
+      apiBaseUrl: 'https://your-backend.com',
+      getAuthHeaders: () => ({
+        Authorization: `Bearer ${localStorage.getItem('token')}`,
+      }),
     }),
-  });
-
-  getStatus() { return this.client.getStatus(); }
-  createToken() { return this.client.createToken(); }
-  startPolling(token: string, cb: any) { return this.client.startPolling(token, cb); }
-  sendSms(to: string, msg: string) { return this.client.sendSms(to, msg); }
-  unpair() { return this.client.unpair(); }
-  updateServerUrl(url: string) { return this.client.updateServerUrl(url); }
-
-  ngOnDestroy() { this.client.destroy(); }
-}
+  ],
+};
 ```
 
+### Usage
+
 ```typescript
-// Component
-@Component({ template: `...` })
+import { Component, inject } from '@angular/core';
+import { SmsTunnelService } from '@narcisbodea/smstunnel-sdk/angular';
+
+@Component({ /* ... */ })
 export class SmsPairingComponent {
-  constructor(private sms: SmsTunnelService) {}
+  private sms = inject(SmsTunnelService);
 
   async connect() {
-    const result = await this.sms.createToken();
-    if (result.success) {
-      this.qrData = result.qrData;
-      this.sms.startPolling(result.token!, (event) => {
-        if (event === 'completed') this.loadStatus();
-      });
-    }
+    // Pairing
+    const status = await this.sms.getStatus();
+    const token = await this.sms.createToken();
+    const pairings = await this.sms.getPairings();
+    await this.sms.unpair();
+
+    // SMS
+    await this.sms.sendSms('+40721123456', 'Hello!');
+    await this.sms.send2fa('+40721123456', '123456');
+    await this.sms.sendBulk([{ to: '+40721111111', message: 'Hi' }]);
+    const msgStatus = await this.sms.getSmsStatus('msg-id');
+    const inbox = await this.sms.getReceivedSms();
+
+    // Devices
+    const devices = await this.sms.getDevices();
+    const usage = await this.sms.getUsage();
+
+    // E2E Encryption
+    const e2eStatus = await this.sms.getDeviceE2EStatus('device-id');
+    const publicKey = await this.sms.getDevicePublicKey('device-id');
+    const verification = await this.sms.verifyDeviceKey('device-id', 'fingerprint');
+    await this.sms.sendEncryptedSms('payload', 'device-id');
   }
 }
 ```
@@ -386,7 +468,7 @@ export class SmsPairingComponent {
 
 ```svelte
 <script>
-  import { SmsTunnelClient } from 'smstunnel-sdk';
+  import { SmsTunnelClient } from '@narcisbodea/smstunnel-sdk';
   import { onMount, onDestroy } from 'svelte';
 
   let status = 'loading';
@@ -442,7 +524,7 @@ Astro supports React, Vue, and Svelte islands. Use any of the above:
 // pages/settings.astro
 ---
 <script>
-  import { SmsTunnelPairing, RO_LABELS } from 'smstunnel-sdk/react';
+  import { SmsTunnelPairing, RO_LABELS } from '@narcisbodea/smstunnel-sdk/react';
 </script>
 
 <SmsTunnelPairing client:only="react" apiBaseUrl="/api" labels={RO_LABELS} />
@@ -456,10 +538,35 @@ Or with Vue:
 
 ---
 
+## E2E Encryption
+
+All SDKs support end-to-end encryption using RSA-2048. The device holds the private key, the server stores the public key.
+
+### Flow
+
+1. Check if device has E2E enabled: `getDeviceE2EStatus(deviceId)`
+2. Get the device's public key: `getDevicePublicKey(deviceId)`
+3. Encrypt your message with the RSA public key (client-side)
+4. Send encrypted: `sendEncryptedSms(encryptedPayload, deviceId)`
+5. Device decrypts with its private key
+
+### Key Verification
+
+Store the `publicKeyFingerprint` locally after first pairing. Before sending, verify it hasn't changed:
+
+```typescript
+const result = await client.verifyDeviceKey('device-id', 'stored-fingerprint');
+if (result.needsRePairing) {
+  // Device was reinstalled, key changed - need to re-pair
+}
+```
+
+---
+
 ## SmsTunnelClient API (framework-agnostic)
 
 ```typescript
-import { SmsTunnelClient } from 'smstunnel-sdk';
+import { SmsTunnelClient } from '@narcisbodea/smstunnel-sdk';
 
 const client = new SmsTunnelClient({
   apiBaseUrl: '/api',
@@ -468,14 +575,24 @@ const client = new SmsTunnelClient({
   pollInterval: 3000,       // default
 });
 
+// Pairing
 await client.getStatus();                    // { paired, serverUrl, deviceName }
 await client.createToken();                  // { success, token, qrData, ... }
 await client.getPairingStatus(token);        // { status, displayName }
 client.startPolling(token, (event) => ...);  // returns cleanup fn
 client.stopPolling();
 await client.unpair();
+
+// SMS
 await client.sendSms('+40741234567', 'Hi');
 await client.updateServerUrl('https://...');
+
+// E2E Encryption
+await client.getDeviceE2EStatus('device-id');
+await client.getDevicePublicKey('device-id');
+await client.verifyDeviceKey('device-id', 'fingerprint');
+await client.sendEncryptedSms('payload', 'device-id');
+
 client.destroy();                            // cleanup
 ```
 
@@ -487,9 +604,9 @@ Built-in presets: `EN_LABELS` (default), `RO_LABELS`.
 
 Available from any import path:
 ```typescript
-import { EN_LABELS, RO_LABELS } from 'smstunnel-sdk';
-import { EN_LABELS, RO_LABELS } from 'smstunnel-sdk/react';
-import { EN_LABELS, RO_LABELS } from 'smstunnel-sdk/vue';
+import { EN_LABELS, RO_LABELS } from '@narcisbodea/smstunnel-sdk';
+import { EN_LABELS, RO_LABELS } from '@narcisbodea/smstunnel-sdk/react';
+import { EN_LABELS, RO_LABELS } from '@narcisbodea/smstunnel-sdk/vue';
 ```
 
 Custom labels: implement the `SmsTunnelLabels` interface.
@@ -500,10 +617,12 @@ Custom labels: implement the `SmsTunnelLabels` interface.
 
 | Path | Exports |
 |------|---------|
-| `smstunnel-sdk` | `SmsTunnelClient`, `EN_LABELS`, `RO_LABELS`, types |
-| `smstunnel-sdk/server` | `SmsTunnelModule`, `SmsTunnelService`, `SMSTUNNEL_PUBLIC_PATHS` |
-| `smstunnel-sdk/react` | `SmsTunnelPairing`, `QrCodeCanvas`, `useSmsTunnel` |
-| `smstunnel-sdk/vue` | `SmsTunnelPairing`, `QrCodeCanvas`, `useSmsTunnel` |
+| `@narcisbodea/smstunnel-sdk` | `SmsTunnelClient`, `EN_LABELS`, `RO_LABELS`, types |
+| `@narcisbodea/smstunnel-sdk/server` | `SmsTunnelModule`, `SmsTunnelService`, `SMSTUNNEL_PUBLIC_PATHS` |
+| `@narcisbodea/smstunnel-sdk/react` | `SmsTunnelPairing`, `QrCodeCanvas`, `useSmsTunnel` |
+| `@narcisbodea/smstunnel-sdk/vue` | `SmsTunnelPairing`, `QrCodeCanvas`, `useSmsTunnel` |
+| `@narcisbodea/smstunnel-sdk/angular` | `SmsTunnelService`, `provideSmsTunnel`, `SMSTUNNEL_CONFIG` |
+| `@narcisbodea/smstunnel-sdk/node` | `SmsTunnelNodeClient` |
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@narcisbodea/smstunnel-sdk",
-  "version": "1.1.3",
+  "version": "1.1.4",
   "description": "SMSTunnel SDK - Node.js + NestJS + React + Vue + Angular + framework-agnostic client for SMS pairing & E2E encryption",
   "author": "NARBOWEB SRL",
   "license": "MIT",