@docgenlab.com/chat-widget 0.1.3 → 0.4.2

package/README.md

@@ -83,9 +83,46 @@ DocGenLab.destroy();
 | `enableImageUpload` | boolean | `true` | Allow end-users to attach screenshots |
 | `hideBranding` | boolean | `false` | Hide "Powered by DocGenLab" — paid tier |
 | `openOnLoad` | boolean | `false` | Auto-open the panel on first load |
+| `endUserId` | string | — | Customer's authenticated user id. Conversations follow this user across browsers + devices (vs the default anonymous-per-browser cookie). Without `endUserHash`, the id is unverified. |
+| `endUserHash` | string | — | HMAC-SHA256 of `endUserId` signed with your identity-verification secret. Required only when the agent enforces identity verification. |
 | `onReady` | `(agent) => void` | — | Fired when the agent resolves |
 | `onError` | `(err) => void` | — | Fired on unrecoverable errors |
 
+### Identity verification (optional)
+
+For unauthenticated visitors, the widget assigns an anonymous UUID per browser via `localStorage`. Conversations are scoped to that UUID.
+
+If your site has authenticated users and you want chat history to follow each user across devices:
+
+```tsx
+<DocGenLabChat
+    agentKey="pk_live_..."
+    endUserId={currentUser.id}
+    endUserHash={currentUser.docgenlabHash}
+/>
+```
+
+Generate `endUserHash` on YOUR backend (never on the client) using HMAC-SHA256:
+
+```ts
+import { createHmac } from 'crypto';
+const hash = createHmac('sha256', process.env.DOCGENLAB_IDENTITY_SECRET)
+    .update(user.id)
+    .digest('hex');
+```
+
+Without `endUserHash`, the user id is unverified (any browser can claim any id). Standard Intercom-style trust model.
+
+### Responsive behaviour
+
+The widget adapts automatically across breakpoints:
+
+- **Phone portrait (≤480 wide):** full-width bottom sheet, 90dvh tall (respects iOS Safari's collapsible bottom bar)
+- **Phone landscape / short screens (≤600 high):** side panel anchored to the launcher corner, doesn't fight the on-screen keyboard
+- **Tablet (481–768 wide):** slimmer 340px panel with reduced inset
+- **Tiny phones (≤360 wide):** smaller launcher (48px), tightened padding
+- **Touch devices:** larger tap-targets via `@media (hover: none) and (pointer: coarse)`
+
 ## Browser support
 
 ES2018+ targets. Edge, Chrome, Firefox, Safari (last 2 versions). IE11 not supported.

package/dist/api.d.ts

@@ -6,22 +6,72 @@
  *   X-DocGenLab-Key         — the publishable key (server resolves to agent)
  *   X-DocGenLab-Visitor-Id  — a stable UUID minted in localStorage
  */
-import type { AgentInfo, StreamEvent } from './types';
+import type { AgentInfo, StreamEvent, TicketRef } from './types';
 export interface ClientOptions {
     agentKey: string;
     apiBaseUrl: string;
+    /** Customer's stable user identifier. When provided, takes precedence
+     *  over the anonymous-per-browser UUID so conversations follow the user
+     *  across browsers + devices. Prefixed with 'user:' internally so an
+     *  attacker can't guess + collide with another user's anonymous UUID. */
+    endUserId?: string;
+    /** HMAC verification companion (currently passed to the server for
+     *  future enforcement). */
+    endUserHash?: string;
 }
 export declare class WidgetClient {
     private readonly agentKey;
     private readonly baseUrl;
     private readonly visitorId;
+    private readonly endUserHash?;
     constructor(opts: ClientOptions);
     private headers;
     getAgent(): Promise<AgentInfo>;
+    /** Load a previous conversation's messages so the widget can show
+     *  history after a refresh / re-open. The visitor-id header is the
+     *  authorization — the backend only returns conversations owned by
+     *  the requesting visitor on this agent. */
+    getConversation(conversationId: string): Promise<any>;
+    /** Reconstruct the ticket card that SHOULD currently be on the
+     *  conversation, based on persisted state. Lets the widget restore
+     *  raise-ticket / "already on it" / created cards after refresh.
+     *  Returns kind=null when nothing should show. */
+    getTicketCardState(conversationId: string): Promise<{
+        kind: 'offer' | 'existing' | 'created' | null;
+        conversation_id: string | null;
+        connector_type?: string | null;
+        connector_name?: string | null;
+        ticket_id?: string | null;
+        external_ticket_number?: string | null;
+        external_url?: string | null;
+        status?: string | null;
+    }>;
     uploadImage(file: File): Promise<string>;
     /** Fetch a previously-uploaded image as a blob URL. Caller must
      *  URL.revokeObjectURL() when done to avoid memory leaks. */
     fetchImage(imagePath: string): Promise<string>;
+    /** Raise a support ticket from a conversation. Requires explicit user
+     *  consent — the widget only calls this after the user clicks the
+     *  in-chat "Raise a ticket" chip. */
+    raiseTicket(conversationId: string, body: {
+        consent: boolean;
+        end_user_email?: string;
+        end_user_phone?: string;
+        priority?: 'low' | 'medium' | 'high' | 'urgent';
+        /** Escape hatch from the "We're already on it" card — bypasses
+         *  the duplicate guard so the user can raise a fresh ticket
+         *  for a different issue even when a recent one is still open. */
+        force_new?: boolean;
+    }): Promise<TicketRef>;
+    /** List all tickets for THIS visitor on THIS agent. Used by the widget
+     *  to hydrate ticket cards on conversation reload and to power the
+     *  "Manage tickets" modal. Optionally filtered by conversation. */
+    listTickets(conversationId?: string): Promise<TicketRef[]>;
+    /** Fetch the latest status of a ticket the user raised. */
+    getTicket(ticketId: string, refresh?: boolean): Promise<TicketRef>;
+    /** Fetch a video-source frame attached to a citation chunk.
+     *  Same auth pattern as fetchImage. */
+    fetchSourceFrame(sourceId: string, framePath: string): Promise<string>;
     /** Stream a chat response via SSE. Returns an abort fn the caller invokes
      *  to cancel the stream. */
     streamChat(body: {