@narcisbodea/smstunnel-sdk 1.0.0

package/README.md

@@ -0,0 +1,490 @@
+# smstunnel-sdk
+
+SMSTunnel SDK - NestJS + React + Vue + framework-agnostic client for SMS pairing.
+
+| 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) |
+
+## Install
+
+```bash
+npm install smstunnel-sdk
+```
+
+---
+
+## Server (NestJS)
+
+### 1. Implement a Storage Adapter
+
+The SDK is database-agnostic. You provide a simple adapter with 3 methods:
+
+#### MongoDB (Mongoose)
+
+```typescript
+import { SmsTunnelStorageAdapter, SmsTunnelConfig } from 'smstunnel-sdk/server';
+import { Model } from 'mongoose';
+
+export class MongoSmsTunnelStorage implements SmsTunnelStorageAdapter {
+  constructor(private model: Model<any>) {}
+
+  async getConfig(): Promise<Partial<SmsTunnelConfig>> {
+    const doc = await this.model.findOne().lean().exec();
+    return {
+      serverUrl: doc?.smstunnelServerUrl || '',
+      apiKey: doc?.smstunnelApiKey || '',
+      siteToken: doc?.smstunnelSiteToken || '',
+      deviceName: doc?.smstunnelDeviceName || '',
+    };
+  }
+
+  async updateConfig(partial: Partial<SmsTunnelConfig>): Promise<void> {
+    const $set: Record<string, string> = {};
+    if (partial.serverUrl !== undefined) $set.smstunnelServerUrl = partial.serverUrl;
+    if (partial.apiKey !== undefined) $set.smstunnelApiKey = partial.apiKey;
+    if (partial.siteToken !== undefined) $set.smstunnelSiteToken = partial.siteToken;
+    if (partial.deviceName !== undefined) $set.smstunnelDeviceName = partial.deviceName;
+    await this.model.updateOne({}, { $set });
+  }
+
+  async clearConfig(): Promise<void> {
+    await this.model.updateOne({}, {
+      $set: { smstunnelApiKey: '', smstunnelDeviceName: '', smstunnelSiteToken: '' },
+    });
+  }
+}
+```
+
+#### Prisma (PostgreSQL)
+
+```typescript
+import { SmsTunnelStorageAdapter, SmsTunnelConfig } from 'smstunnel-sdk/server';
+import { PrismaClient } from '@prisma/client';
+
+export class PrismaSmsTunnelStorage implements SmsTunnelStorageAdapter {
+  constructor(private prisma: PrismaClient) {}
+
+  async getConfig(): Promise<Partial<SmsTunnelConfig>> {
+    const row = await this.prisma.appSettings.findFirst();
+    return {
+      serverUrl: row?.smstunnelServerUrl || '',
+      apiKey: row?.smstunnelApiKey || '',
+      siteToken: row?.smstunnelSiteToken || '',
+      deviceName: row?.smstunnelDeviceName || '',
+    };
+  }
+
+  async updateConfig(partial: Partial<SmsTunnelConfig>): Promise<void> {
+    await this.prisma.appSettings.updateMany({ data: partial });
+  }
+
+  async clearConfig(): Promise<void> {
+    await this.prisma.appSettings.updateMany({
+      data: { apiKey: '', deviceName: '', siteToken: '' },
+    });
+  }
+}
+```
+
+#### JSON File
+
+```typescript
+import { SmsTunnelStorageAdapter, SmsTunnelConfig } from 'smstunnel-sdk/server';
+import { readFile, writeFile } from 'fs/promises';
+
+export class JsonFileStorage implements SmsTunnelStorageAdapter {
+  constructor(private filePath: string) {}
+
+  async getConfig(): Promise<Partial<SmsTunnelConfig>> {
+    try { return JSON.parse(await readFile(this.filePath, 'utf-8')); }
+    catch { return {}; }
+  }
+
+  async updateConfig(partial: Partial<SmsTunnelConfig>): Promise<void> {
+    const config = { ...(await this.getConfig()), ...partial };
+    await writeFile(this.filePath, JSON.stringify(config, null, 2));
+  }
+
+  async clearConfig(): Promise<void> {
+    await this.updateConfig({ apiKey: '', deviceName: '', siteToken: '' });
+  }
+}
+```
+
+### 2. Register the Module
+
+```typescript
+import { SmsTunnelModule } from 'smstunnel-sdk/server';
+
+@Module({
+  imports: [
+    SmsTunnelModule.forRoot({
+      storage: new MongoSmsTunnelStorage(settingsModel),
+      callbackBaseUrl: 'https://myapp.com/api',
+      displayName: 'My App',
+    }),
+  ],
+})
+export class AppModule {}
+```
+
+Or async:
+
+```typescript
+SmsTunnelModule.forRootAsync({
+  useFactory: (settingsModel) => ({
+    storage: new MongoSmsTunnelStorage(settingsModel),
+    callbackBaseUrl: process.env.CALLBACK_URL,
+    displayName: 'My App',
+  }),
+  inject: [getModelToken('Settings')],
+})
+```
+
+### 3. Auth Guard Integration
+
+```typescript
+import { SMSTUNNEL_PUBLIC_PATHS } from 'smstunnel-sdk/server';
+
+// In your JwtAuthGuard:
+if (SMSTUNNEL_PUBLIC_PATHS.some(p => request.url.includes(p))) return true;
+```
+
+### REST Endpoints
+
+| Route | Method | Auth | Purpose |
+|-------|--------|------|---------|
+| `GET /smstunnel/status` | getStatus | Yes | Show pairing status |
+| `POST /smstunnel/create-token` | createToken | Yes | Generate QR |
+| `GET /smstunnel/pairing-status/:token` | pairingStatus | No | Polling proxy |
+| `POST /smstunnel/callback` | callback | No | Receive API key |
+| `POST /smstunnel/unpair` | unpair | Yes | Disconnect device |
+| `POST /smstunnel/send` | sendSms | Yes | Send SMS |
+| `POST /smstunnel/update-config` | updateConfig | Yes | Set server URL |
+
+---
+
+## React
+
+Works with: **React, Next.js, Remix, Gatsby**
+
+### Plug and Play Component
+
+```tsx
+import { SmsTunnelPairing, RO_LABELS } from 'smstunnel-sdk/react';
+
+function SettingsPage() {
+  return (
+    <SmsTunnelPairing
+      apiBaseUrl="/api"
+      getAuthHeaders={() => ({
+        Authorization: `Bearer ${localStorage.getItem('token')}`,
+      })}
+      labels={RO_LABELS}
+      onPaired={(device) => console.log('Paired:', device)}
+      showTestSms={true}
+      showServerUrlInput={true}
+      qrSize={220}
+    />
+  );
+}
+```
+
+### Next.js
+
+Add `'use client'` in your page/component:
+
+```tsx
+'use client';
+import { SmsTunnelPairing, RO_LABELS } from 'smstunnel-sdk/react';
+
+export default function SmsSettings() {
+  return <SmsTunnelPairing apiBaseUrl="/api" labels={RO_LABELS} />;
+}
+```
+
+### Custom UI with Hook
+
+```tsx
+import { useSmsTunnel, QrCodeCanvas } from 'smstunnel-sdk/react';
+
+function MySmsSettings() {
+  const tunnel = useSmsTunnel({
+    apiBaseUrl: '/api',
+    getAuthHeaders: () => ({ Authorization: `Bearer ${token}` }),
+  });
+
+  if (tunnel.status === 'paired') {
+    return <div>Connected: {tunnel.deviceName}</div>;
+  }
+
+  return (
+    <div>
+      {tunnel.showQr ? (
+        <>
+          <QrCodeCanvas value={tunnel.qrData} size={200} />
+          <button onClick={tunnel.cancelPairing}>Cancel</button>
+        </>
+      ) : (
+        <button onClick={tunnel.generateQr} disabled={tunnel.generating}>
+          Connect Phone
+        </button>
+      )}
+    </div>
+  );
+}
+```
+
+---
+
+## Vue
+
+Works with: **Vue 3, Nuxt 3**
+
+### Plug and Play Component
+
+```vue
+<script setup>
+import { SmsTunnelPairing, RO_LABELS } from 'smstunnel-sdk/vue';
+
+function onPaired(device) {
+  console.log('Paired:', device);
+}
+</script>
+
+<template>
+  <SmsTunnelPairing
+    api-base-url="/api"
+    :labels="RO_LABELS"
+    :show-test-sms="true"
+    :show-server-url-input="true"
+    @paired="onPaired"
+  />
+</template>
+```
+
+### Nuxt 3
+
+Wrap in `<ClientOnly>` since pairing uses browser APIs:
+
+```vue
+<template>
+  <ClientOnly>
+    <SmsTunnelPairing api-base-url="/api" :labels="RO_LABELS" />
+  </ClientOnly>
+</template>
+
+<script setup>
+import { SmsTunnelPairing, RO_LABELS } from 'smstunnel-sdk/vue';
+</script>
+```
+
+### Custom UI with Composable
+
+```vue
+<script setup>
+import { useSmsTunnel, QrCodeCanvas } from 'smstunnel-sdk/vue';
+
+const tunnel = useSmsTunnel({
+  apiBaseUrl: '/api',
+  getAuthHeaders: () => ({ Authorization: `Bearer ${token}` }),
+});
+</script>
+
+<template>
+  <div v-if="tunnel.status.value === 'paired'">
+    Connected: {{ tunnel.deviceName.value }}
+    <button @click="tunnel.unpair()">Disconnect</button>
+  </div>
+  <div v-else>
+    <div v-if="tunnel.showQr.value">
+      <QrCodeCanvas :value="tunnel.qrData.value" :size="200" />
+      <button @click="tunnel.cancelPairing()">Cancel</button>
+    </div>
+    <button v-else @click="tunnel.generateQr()" :disabled="tunnel.generating.value">
+      Connect Phone
+    </button>
+  </div>
+</template>
+```
+
+---
+
+## Angular
+
+Use the framework-agnostic `SmsTunnelClient` class:
+
+```typescript
+import { Injectable, OnDestroy } from '@angular/core';
+import { SmsTunnelClient } from 'smstunnel-sdk';
+
+@Injectable({ providedIn: 'root' })
+export class SmsTunnelService implements OnDestroy {
+  private client = new SmsTunnelClient({
+    apiBaseUrl: '/api',
+    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(); }
+}
+```
+
+```typescript
+// Component
+@Component({ template: `...` })
+export class SmsPairingComponent {
+  constructor(private sms: 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();
+      });
+    }
+  }
+}
+```
+
+---
+
+## Svelte
+
+```svelte
+<script>
+  import { SmsTunnelClient } from 'smstunnel-sdk';
+  import { onMount, onDestroy } from 'svelte';
+
+  let status = 'loading';
+  let qrData = '';
+  let deviceName = '';
+
+  const client = new SmsTunnelClient({
+    apiBaseUrl: '/api',
+    getAuthHeaders: () => ({
+      Authorization: `Bearer ${localStorage.getItem('token')}`,
+    }),
+  });
+
+  onMount(async () => {
+    const s = await client.getStatus();
+    status = s.paired ? 'paired' : 'unpaired';
+    deviceName = s.deviceName || '';
+  });
+
+  onDestroy(() => client.destroy());
+
+  async function connect() {
+    const result = await client.createToken();
+    if (result.success) {
+      qrData = result.qrData;
+      client.startPolling(result.token, async (event) => {
+        if (event === 'completed') {
+          const s = await client.getStatus();
+          status = 'paired';
+          deviceName = s.deviceName || '';
+        }
+      });
+    }
+  }
+</script>
+
+{#if status === 'paired'}
+  <p>Connected: {deviceName}</p>
+  <button on:click={() => client.unpair()}>Disconnect</button>
+{:else}
+  <button on:click={connect}>Connect Phone</button>
+{/if}
+```
+
+---
+
+## Astro
+
+Astro supports React, Vue, and Svelte islands. Use any of the above:
+
+```astro
+---
+// pages/settings.astro
+---
+<script>
+  import { SmsTunnelPairing, RO_LABELS } from 'smstunnel-sdk/react';
+</script>
+
+<SmsTunnelPairing client:only="react" apiBaseUrl="/api" labels={RO_LABELS} />
+```
+
+Or with Vue:
+
+```astro
+<SmsTunnelPairing client:only="vue" api-base-url="/api" />
+```
+
+---
+
+## SmsTunnelClient API (framework-agnostic)
+
+```typescript
+import { SmsTunnelClient } from 'smstunnel-sdk';
+
+const client = new SmsTunnelClient({
+  apiBaseUrl: '/api',
+  getAuthHeaders: () => ({ Authorization: 'Bearer ...' }),
+  routePrefix: 'smstunnel', // default
+  pollInterval: 3000,       // default
+});
+
+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();
+await client.sendSms('+40741234567', 'Hi');
+await client.updateServerUrl('https://...');
+client.destroy();                            // cleanup
+```
+
+---
+
+## Labels (i18n)
+
+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';
+```
+
+Custom labels: implement the `SmsTunnelLabels` interface.
+
+---
+
+## Exports Summary
+
+| 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` |
+
+## License
+
+MIT