@webzaytsev/support-sdk 0.1.0 → 0.1.1

package/README.md

@@ -0,0 +1,230 @@
+# @webzaytsev/support-sdk
+
+TypeScript SDK for the **Support Bot Web API** — a Telegram-based customer support system with a REST/SSE web interface.
+
+> **Note:** The support bot itself is a private, commercial product. This SDK is published publicly so that frontend teams can integrate the support widget without needing access to the backend source code.
+
+---
+
+## Installation
+
+```bash
+npm install @webzaytsev/support-sdk
+# or
+pnpm add @webzaytsev/support-sdk
+```
+
+**Runtime requirements:** Node.js 18+ or any modern browser (Fetch API).
+
+---
+
+## Quick Start
+
+### 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';
+
+client.setConfig({ baseUrl: 'https://support.example.com' });
+
+// Called from YOUR backend, not from the browser
+const { data } = await webAuthControllerIssueToken({
+  headers: { 'X-Internal-Api-Key': process.env.WEB_API_KEY },
+  body: {
+    userId: 'user_42',
+    userProfile: {
+      name: 'Ivan Petrov',
+      email: 'ivan@example.com',
+      extra: { plan: 'pro', subscriptionId: 'sub_123' },
+    },
+  },
+});
+
+// data.token — pass this to the frontend widget
+// data.expiresAt — ISO timestamp
+```
+
+### 2. Configure the widget client (browser)
+
+```typescript
+import { client } from '@webzaytsev/support-sdk/client';
+
+client.setConfig({
+  baseUrl: 'https://support.example.com',
+  // Attach JWT from your auth store on every request
+  auth: () => localStorage.getItem('support_jwt') ?? '',
+});
+```
+
+### 3. Send a message
+
+```typescript
+import { webTicketsControllerSendMessage } from '@webzaytsev/support-sdk';
+
+const { data } = await webTicketsControllerSendMessage({
+  body: { text: 'My subscription is not working' },
+});
+
+console.log(data.ticketId, data.messageId);
+```
+
+### 4. Hydrate the widget on load
+
+```typescript
+import { webTicketsControllerGetCurrentTicket } from '@webzaytsev/support-sdk';
+
+const { data } = await webTicketsControllerGetCurrentTicket();
+
+if (data.ticket) {
+  renderMessages(data.messages); // oldest-first order
+}
+```
+
+### 5. Subscribe to real-time events (SSE)
+
+```typescript
+import { webTicketsControllerSseStream } from '@webzaytsev/support-sdk';
+
+const stream = webTicketsControllerSseStream({
+  path: { id: ticketId },
+  // ?access_token= is used automatically when auth is configured
+});
+
+for await (const event of stream) {
+  const e = event.data;
+  switch (e.type) {
+    case 'message':
+      appendMessage({ id: e.data?.messageId, text: e.data?.text });
+      break;
+    case 'resolved':
+      showResolvedBanner();
+      break;
+    case 'heartbeat':
+      // keep-alive, no action needed
+      break;
+  }
+}
+```
+
+### 6. Upload an image
+
+```typescript
+import { webUploadsControllerUpload, webTicketsControllerSendMessage } from '@webzaytsev/support-sdk';
+
+const formData = new FormData();
+formData.append('file', selectedFile);
+
+const { data: upload } = await webUploadsControllerUpload({ body: formData });
+
+// Attach the upload to the next message
+await webTicketsControllerSendMessage({
+  body: {
+    text: 'See the screenshot',
+    attachmentIds: [upload.uploadId],
+  },
+});
+```
+
+---
+
+## API Reference
+
+### SDK Functions
+
+All functions are imported from `@webzaytsev/support-sdk`.
+
+| Function | Method | Description |
+|---|---|---|
+| `webAuthControllerIssueToken` | `POST /web/auth/token` | Issue user JWT *(server-side, requires API key)* |
+| `webTicketsControllerSendMessage` | `POST /web/messages` | Send message (creates or reopens ticket) |
+| `webTicketsControllerGetCurrentTicket` | `GET /web/tickets/current` | Get open ticket + message history |
+| `webTicketsControllerGetMessages` | `GET /web/tickets/:id/messages` | Poll messages since cursor |
+| `webTicketsControllerSseStream` | `GET /web/tickets/:id/stream` | SSE real-time event stream |
+| `webTicketsControllerEscalate` | `POST /web/tickets/:id/escalate` | Mark ticket as unresolved (escalate) |
+| `webTicketsControllerResolveByUser` | `POST /web/tickets/:id/resolve` | Confirm issue is resolved |
+| `webUploadsControllerUpload` | `POST /web/uploads` | Upload an image (jpeg/png/webp, max 10 MB) |
+| `webUploadsControllerGetUpload` | `GET /web/uploads/:id` | Stream an uploaded image |
+
+### Client Configuration
+
+```typescript
+import { client } from '@webzaytsev/support-sdk/client';
+
+client.setConfig({
+  baseUrl: 'https://support.example.com',
+  // Called before every request — return the Bearer token
+  auth: () => getJwtFromStorage(),
+});
+```
+
+### Zod Schemas
+
+Runtime validation schemas are available for all request and response types:
+
+```typescript
+import { zSendMessageDto, zCurrentTicketResponseDto, zWebSseEventDto } from '@webzaytsev/support-sdk/zod';
+
+// Validate before sending
+const parsed = zSendMessageDto.parse({ text: 'Hello' });
+
+// Validate API response at runtime
+const ticket = zCurrentTicketResponseDto.parse(apiResponse);
+```
+
+---
+
+## SSE Event Types
+
+The `webTicketsControllerSseStream` endpoint emits the following events:
+
+| `type` | Description | `data` fields |
+|---|---|---|
+| `message` | New message from moderator or bot | `messageId`, `text`, `attachmentIds?`, `createdAt` |
+| `resolved` | Ticket marked as resolved | — |
+| `reopened` | Ticket reopened after resolution | — |
+| `escalation_ack` | Escalation acknowledged | `escalatableMessageId`, `source` |
+| `closed` | Ticket closed by moderator | — |
+| `heartbeat` | Keep-alive ping (~15 s interval) | — |
+
+---
+
+## Polling Fallback
+
+If SSE is unavailable (e.g. behind a proxy that buffers responses), use `webTicketsControllerGetMessages` with cursor-based polling:
+
+```typescript
+let cursor: string | null = null;
+
+setInterval(async () => {
+  const { data } = await webTicketsControllerGetMessages({
+    path: { id: ticketId },
+    query: { since: cursor ?? undefined, limit: 50 },
+  });
+
+  if (data.messages.length > 0) {
+    appendMessages(data.messages); // oldest-first
+    cursor = data.nextCursor;
+  }
+}, 5000);
+```
+
+---
+
+## Exports
+
+| Import path | Contents |
+|---|---|
+| `@webzaytsev/support-sdk` | SDK functions + TypeScript types |
+| `@webzaytsev/support-sdk/client` | `client` singleton, `createClient` |
+| `@webzaytsev/support-sdk/zod` | Zod schemas for all DTOs |
+
+Both CJS (`require`) and ESM (`import`) are supported.
+
+---
+
+## License
+
+MIT — the SDK is free to use. The support bot backend is a private commercial product.

package/dist/client.gen.d.mts

@@ -0,0 +1,14 @@
+import { b as ClientOptions, a as ClientOptions$1, c as Config, C as Client } from './types.gen-DHi9F3K-.mjs';
+
+/**
+ * The `createClientConfig()` function will be called on client initialization
+ * and the returned object will become the client's initial configuration.
+ *
+ * You may want to initialize your client this way instead of calling
+ * `setConfig()`. This is useful for example if you're using Next.js
+ * to ensure your client always has the correct values.
+ */
+type CreateClientConfig<T extends ClientOptions = ClientOptions$1> = (override?: Config<ClientOptions & T>) => Config<Required<ClientOptions> & T>;
+declare const client: Client;
+
+export { type CreateClientConfig, client };

package/dist/client.gen.d.ts

@@ -1,5 +1,5 @@
-import { type ClientOptions, type Config } from './client';
-import type { ClientOptions as ClientOptions2 } from './types.gen';
+import { b as ClientOptions, a as ClientOptions$1, c as Config, C as Client } from './types.gen-DHi9F3K-.js';
+
 /**
  * The `createClientConfig()` function will be called on client initialization
  * and the returned object will become the client's initial configuration.
@@ -8,6 +8,7 @@ import type { ClientOptions as ClientOptions2 } from './types.gen';
  * `setConfig()`. This is useful for example if you're using Next.js
  * to ensure your client always has the correct values.
  */
-export type CreateClientConfig<T extends ClientOptions = ClientOptions2> = (override?: Config<ClientOptions & T>) => Config<Required<ClientOptions> & T>;
-export declare const client: import("./client").Client;
-//# sourceMappingURL=client.gen.d.ts.map
+type CreateClientConfig<T extends ClientOptions = ClientOptions$1> = (override?: Config<ClientOptions & T>) => Config<Required<ClientOptions> & T>;
+declare const client: Client;
+
+export { type CreateClientConfig, client };