@webzaytsev/support-sdk 0.1.2 → 0.1.4

package/README.md

@@ -20,15 +20,31 @@ pnpm add @webzaytsev/support-sdk
 
 ## Quick Start
 
+### 0. Configure the SDK
+
+Call `configure()` once at app startup before making any requests. Both `baseUrl` and `token` can be updated at any time (e.g. after receiving a JWT).
+
+```typescript
+import { configure } from '@webzaytsev/support-sdk/configure';
+
+// Set base URL once at startup
+configure({ baseUrl: 'https://sup.example.com' });
+
+// After receiving a JWT from your backend, set the token:
+configure({ baseUrl: 'https://sup.example.com', token: jwt });
+```
+
+> **Important:** All SDK functions share a single client instance. Calling `configure()` applies to every subsequent API call.
+
 ### 1. Issue a JWT (server-side)
 
 Your backend exchanges a server-to-server API key for a short-lived user JWT. This keeps your `WEB_API_KEY` secret out of the browser.
 
 ```typescript
 import { webAuthControllerIssueToken } from '@webzaytsev/support-sdk';
-import { client } from '@webzaytsev/support-sdk/client';
+import { configure } from '@webzaytsev/support-sdk/configure';
 
-client.setConfig({ baseUrl: 'https://support.example.com' });
+configure({ baseUrl: 'https://support.example.com' });
 
 // Called from YOUR backend, not from the browser
 const { data } = await webAuthControllerIssueToken({
@@ -50,12 +66,12 @@ const { data } = await webAuthControllerIssueToken({
 ### 2. Configure the widget client (browser)
 
 ```typescript
-import { client } from '@webzaytsev/support-sdk/client';
+import { configure } from '@webzaytsev/support-sdk/configure';
 
-client.setConfig({
+// Attach JWT from your auth store; can be called again whenever token changes
+configure({
   baseUrl: 'https://support.example.com',
-  // Attach JWT from your auth store on every request
-  auth: () => localStorage.getItem('support_jwt') ?? '',
+  token: localStorage.getItem('support_jwt') ?? '',
 });
 ```
 
@@ -151,15 +167,23 @@ All functions are imported from `@webzaytsev/support-sdk`.
 ### Client Configuration
 
 ```typescript
-import { client } from '@webzaytsev/support-sdk/client';
+import { configure } from '@webzaytsev/support-sdk/configure';
 
-client.setConfig({
+configure({
   baseUrl: 'https://support.example.com',
-  // Called before every request — return the Bearer token
-  auth: () => getJwtFromStorage(),
+  token: getJwtFromStorage(),
 });
 ```
 
+For advanced use cases (dynamic token refresh, interceptors) you can access the raw client directly:
+
+```typescript
+import { client } from '@webzaytsev/support-sdk/client';
+
+// Dynamic token — called before every request
+client.setConfig({ auth: () => getJwtFromStorage() });
+```
+
 ### Zod Schemas
 
 Runtime validation schemas are available for all request and response types:
@@ -213,13 +237,58 @@ setInterval(async () => {
 
 ---
 
+## Plugin Types
+
+The `extra` field in `WebProfileDto` is a general-purpose string key-value bag — you can put any data your backend needs to store alongside the user profile. The support bot plugins read specific keys from it.
+
+Import typed helpers from `@webzaytsev/support-sdk/plugins`:
+
+### Remnawave
+
+The Remnawave plugin (`/sub` command, ticket info card) looks for a user identifier in `extra` using this priority order: `userId` → `remnawave_user_id` → `user_id`.
+
+```typescript
+import type { RemnawaveWebProfile } from '@webzaytsev/support-sdk/plugins';
+
+// Typed profile — extra.userId is required, any other keys are allowed
+const profile: RemnawaveWebProfile = {
+  name: 'Ivan Petrov',
+  email: 'ivan@example.com',
+  extra: {
+    userId: 'ddc9c1c9-973c-46d9-acd7-8db629e7bc98', // Remnawave user UUID
+    plan: 'pro',       // arbitrary extra data — allowed
+    region: 'eu-west', // also fine
+  },
+};
+
+// Pass to POST /web/auth/token
+await webAuthControllerIssueToken({
+  headers: { 'X-Internal-Api-Key': process.env.WEB_API_KEY },
+  body: { userId: 'user_42', userProfile: profile },
+});
+```
+
+You can also use `RemnawaveExtra` if you only need the extra shape:
+
+```typescript
+import type { RemnawaveExtra } from '@webzaytsev/support-sdk/plugins';
+
+const extra: RemnawaveExtra & Record<string, string> = {
+  userId: 'ddc9c1c9-973c-46d9-acd7-8db629e7bc98',
+};
+```
+
+---
+
 ## Exports
 
 | Import path | Contents |
 |---|---|
 | `@webzaytsev/support-sdk` | SDK functions + TypeScript types |
-| `@webzaytsev/support-sdk/client` | `client` singleton, `createClient` |
+| `@webzaytsev/support-sdk/configure` | `configure({ baseUrl, token })` — recommended setup entrypoint |
+| `@webzaytsev/support-sdk/client` | `client` singleton, `createClient` — for advanced use |
 | `@webzaytsev/support-sdk/zod` | Zod schemas for all DTOs |
+| `@webzaytsev/support-sdk/plugins` | Plugin-specific `extra` types (`RemnawaveExtra`, `RemnawaveWebProfile`) |
 
 Both CJS (`require`) and ESM (`import`) are supported.