@voxket-ai/events-sdk 1.0.0 → 1.0.2

package/README.md

@@ -1,16 +1,23 @@
 # @voxket-ai/events-sdk
 
-> Embeddable event registration and ticketing widget SDK for Voxket.
+> Enterprise embeddable event registration, ticketing, and attendee self-service portal SDK for Voxket.
+
+[![npm version](https://img.shields.io/npm/v/@voxket-ai/events-sdk.svg)](https://www.npmjs.com/package/@voxket-ai/events-sdk)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+---
 
 ## Features
 
-- **Multiple Display Modes**: Popup modal, inline embedded widget, or fullscreen mode.
-- **Shadow DOM Isolation**: Zero CSS conflicts with the host website styles.
-- **Draft Auto-save & Recovery**: Automatically saves user progress and restores previous form entries via `xref_id` or email.
-- **Attendee Portal**: Built-in login, verification code generation/reset, profile editing, and add-on purchasing.
-- **Payment Handling**: External checkout in a dedicated tab with instant status updates.
-- **Framework Agnostic**: Usable via vanilla JavaScript or directly as a React component.
-- **TypeScript Support**: Full type definitions included out of the box.
+- **Multiple Display Formats**: Seamlessly embed as an inline `widget`, a floating corner `popup`, or a `fullscreen` modal.
+- **Interactive Corner Snapping**: In popup mode, attendees can slide/drag the collapsed widget to any screen corner (`bottom-right`, `bottom-left`, `top-right`, `top-left`).
+- **Shadow DOM Isolation**: Runs inside an isolated Shadow Root so host CSS styles and framework resets never bleed in or break the widget layout.
+- **Configurable Dark & Light Themes**: Full host-configured dark mode (`bg-black text-white`) and light mode with custom brand primary colors and typography.
+- **Event Callbacks (`onError`, `onRegister`)**: Native typed callbacks to easily display host toast notifications, trigger analytics, or redirect users.
+- **Attendee Self-Service Portal**: Attendees can log in, request OTP/verification codes, update registration fields, upload documents, and purchase add-ons.
+- **Draft Auto-save & Instant Recovery**: Automatically tracks in-progress form inputs and seamlessly recovers drafts via `xref_id` or email.
+- **Configurable Network Timeout**: Built-in 2-minute (`120,000 ms`) timeout across all API operations to handle slow mobile networks cleanly.
+- **Framework Agnostic & React Support**: Usable via vanilla JavaScript (`EventWidgetClient`) or directly as a declarative React component (`EventWidget`).
 
 ---
 
@@ -32,77 +39,250 @@ pnpm add @voxket-ai/events-sdk
 
 ## Quick Start
 
-### 1. Vanilla JavaScript / HTML
+### 1. React Applications
 
-```html
-<div id="voxket-widget"></div>
+Import `EventWidget` and pass your `WidgetConfig`:
 
-<script type="module">
-  import { EventWidgetClient } from '@voxket-ai/events-sdk';
+```tsx
+import React from 'react';
+import { EventWidget, type WidgetConfig } from '@voxket-ai/events-sdk';
 
-  const widget = new EventWidgetClient({
-    eventSlug: 'your-event-slug',
+export function RegistrationSection() {
+  const config: WidgetConfig = {
+    eventSlug: 'fogsi-yuva_2026',
     baseUrl: 'https://api.voxket.com',
     displayMode: 'popup', // 'popup' | 'widget' | 'fullscreen'
+    position: 'bottom-right',
+    themeMode: 'light', // 'light' | 'dark'
     theme: {
-      mode: 'custom',
-      primaryColor: '#6366f1'
+      primaryColor: '#8b5cf6',
+      fontFamily: 'Inter, system-ui, sans-serif'
+    },
+    // Fired when registration is completed
+    onRegister: (data) => {
+      console.log('Registered successfully:', data);
+      alert(`Registration confirmed! Reference: ${data.payload.xref_id || 'N/A'}`);
+    },
+    // Fired on validation, submission, or network failure
+    onError: (err) => {
+      console.error('Widget error:', err);
+      alert(`Error [${err.type}]: ${err.message}`);
     }
-  });
+  };
+
+  return <EventWidget config={config} />;
+}
+```
+
+---
+
+### 2. Vanilla JavaScript / HTML
+
+Use `EventWidgetClient` to mount and manage the widget programmatically:
+
+```html
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8" />
+  <title>Event Registration</title>
+</head>
+<body>
+  <!-- Mount target for inline widget or popup anchor -->
+  <div id="voxket-widget-container"></div>
+
+  <script type="module">
+    import { EventWidgetClient } from '@voxket-ai/events-sdk';
+
+    const client = new EventWidgetClient({
+      eventSlug: 'fogsi-yuva_2026',
+      baseUrl: 'https://api.voxket.com',
+      displayMode: 'popup',
+      position: 'bottom-right',
+      themeMode: 'dark', // Enable dark mode
+      theme: {
+        primaryColor: '#6366f1'
+      },
+      onRegister: (data) => {
+        console.log('Registration complete:', data);
+      },
+      onError: (error) => {
+        console.error('Error occurred:', error.message);
+      }
+    });
+
+    // Mount to the DOM
+    client.mount('voxket-widget-container');
+
+    // Dynamically update configuration without unmounting
+    // client.updateConfig({ position: 'bottom-left' });
+
+    // Clean up when leaving the page
+    // client.unmount();
+  </script>
+</body>
+</html>
+```
+
+---
+
+## Configuration Reference (`WidgetConfig`)
+
+All available options for the `WidgetConfig` object:
+
+| Parameter | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `eventSlug` | `string` | *(Required)* | The unique identifier/slug of the event in Voxket. |
+| `baseUrl` | `string` | *(Required)* | API base URL for Voxket backend endpoints. |
+| `displayMode` | `'popup' \| 'widget' \| 'fullscreen'` | `'widget'` | Layout style: floating popup badge, inline embedded container, or full viewport modal. |
+| `position` | `WidgetPosition` | `'bottom-right'` | Starting corner for popup mode. Options: `'bottom-right'`, `'bottom-left'`, `'top-right'`, `'top-left'`, `'right-bottom'`, `'left-bottom'`, `'right-top'`, `'left-top'`. |
+| `themeMode` | `'light' \| 'dark'` | `'light'` | Controls the base color scheme (clean white/gray or deep black `#000` with high-contrast text). |
+| `theme` | `object` | `{}` | Detailed appearance customization (see below). |
+| `theme.primaryColor` | `string` | `'#2563eb'` | Brand color used for primary buttons, tabs, highlights, and headers. |
+| `theme.fontFamily` | `string` | System font | Custom font family CSS string (e.g. `'Inter, sans-serif'`). |
+| `theme.mode` | `'light' \| 'dark' \| 'blue' \| 'white' \| 'custom'` | `'light'` | Preset theme mode alias. |
+| `width` | `string` | `undefined` | Custom width override (e.g. `'500px'`, `'100%'`). |
+| `height` | `string` | `undefined` | Custom height override (e.g. `'700px'`, `'650px'`). |
+| `timeoutMs` | `number` | `120000` *(2 min)* | Network request timeout in milliseconds before triggering `onError`. |
+| `debug` | `boolean` | `false` | Enables verbose debug logging in the browser console. |
+| `onRegister` | `(data: RegistrationSuccessPayload) => void` | `undefined` | Callback fired when an attendee completes registration successfully. |
+| `onRegistered` | `(data: RegistrationSuccessPayload) => void` | `undefined` | Alias for `onRegister`. |
+| `onError` | `(error: WidgetErrorPayload) => void` | `undefined` | Callback fired on validation, submission, network, or schema load errors. |
+| `onEvent` | `(eventName: string, payload: any) => void` | `undefined` | Optional generic event bus for internal widget lifecycle events. |
+
+---
+
+## Event Callbacks & Toast Notifications
+
+The SDK exposes dedicated callback functions so host applications can handle state transitions and show native toast notifications.
+
+### 1. `onError`
 
-  widget.mount('voxket-widget');
-</script>
+Fires whenever an operation fails (form validation failure, network disconnect, timeout, attendee login error, or profile update issue):
+
+```typescript
+onError: (err: WidgetErrorPayload) => void;
 ```
 
-### 2. React Applications
+**Payload Schema:**
+```typescript
+interface WidgetErrorPayload {
+  type: 'submit_error' | 'schema_load' | 'login_error' | 'profile_update_error' | 'file_upload_error' | 'network_error' | string;
+  message: string;
+  error?: any;
+}
+```
 
+**Toast Example (React Toastify / Sonner / AntD):**
 ```tsx
-import React from 'react';
-import { EventWidget } from '@voxket-ai/events-sdk';
-
-export function EventPage() {
-  return (
-    <EventWidget
-      config={{
-        eventSlug: 'your-event-slug',
-        baseUrl: 'https://api.voxket.com',
-        displayMode: 'widget',
-        theme: {
-          primaryColor: '#2563eb'
-        }
-      }}
-    />
-  );
+const config: WidgetConfig = {
+  // ...
+  onError: (err) => {
+    // Show toast in your host application
+    toast.error(err.message, {
+      description: `Error code: ${err.type}`
+    });
+  }
+};
+```
+
+---
+
+### 2. `onRegister` (or `onRegistered`)
+
+Fires when an attendee successfully submits their registration form:
+
+```typescript
+onRegister: (data: RegistrationSuccessPayload) => void;
+```
+
+**Payload Schema:**
+```typescript
+interface RegistrationSuccessPayload {
+  registrationType: string | number; // Selected ticket type
+  payload: Record<string, any>;      // Form field responses submitted
+  response?: any;                    // Raw backend API response
+  paymentUrl?: string | null;        // Gateway URL if payment is required
 }
 ```
 
+**Toast & Redirect Example:**
+```tsx
+const config: WidgetConfig = {
+  // ...
+  onRegister: (data) => {
+    toast.success(`Registration received for ${data.registrationType}!`);
+
+    if (data.paymentUrl) {
+      console.log('Payment gateway URL ready:', data.paymentUrl);
+    }
+  }
+};
+```
+
 ---
 
-## Configuration Options
+## Draggable Corner Positioning (Popup Mode)
 
-| Option | Type | Default | Description |
-| :--- | :--- | :--- | :--- |
-| `eventSlug` | `string` | *(required)* | The unique identifier/slug of your Voxket event. |
-| `baseUrl` | `string` | *(required)* | API base URL for Voxket backend endpoints. |
-| `displayMode` | `'popup' \| 'widget' \| 'fullscreen'` | `'widget'` | Layout display mode for the widget. |
-| `width` | `string` | `undefined` | Custom width (e.g. `'480px'`, `'100%'`). |
-| `height` | `string` | `undefined` | Custom height (e.g. `'600px'`). |
-| `theme.mode` | `'blue' \| 'white' \| 'custom'` | `'blue'` | Preset or custom theme mode. |
-| `theme.primaryColor` | `string` | `undefined` | Custom hex or HSL brand color. |
-| `debug` | `boolean` | `false` | Enable console logging for development. |
-| `onEvent` | `(eventName: string, payload: any) => void` | `undefined` | Callback for widget lifecycle and telemetry events. |
+When `displayMode: 'popup'` is active:
+1. The widget renders as a compact floating badge at the configured `position` (e.g. `bottom-right`).
+2. **Move Handle**: Hovering over the badge reveals a corner drag handle (`Move` icon at the top-left of the badge).
+3. **Corner Snapping**: Clicking and dragging the badge moves it across the screen; releasing snaps it to the nearest corner (`bottom-right`, `bottom-left`, `top-right`, or `top-left`).
+4. Once the popup is opened into full view, positioning is locked to prevent accidental movement during form completion.
+
+---
+
+## Dark Mode Support
+
+Theme mode is configured by the host application via `themeMode`:
+
+```typescript
+const config: WidgetConfig = {
+  eventSlug: 'fogsi-yuva_2026',
+  baseUrl: 'https://api.voxket.com',
+  themeMode: 'dark', // 'dark' | 'light'
+  theme: {
+    primaryColor: '#8b5cf6'
+  }
+};
+```
+
+- When set to `'dark'`, all views—Ticket Selector, Attendee Portal, Dynamic Form Inputs, Payment Screens, and Error Modals—render in high-contrast deep black (`#000000`) and dark zinc tones with crisp borders.
+- Attendees cannot override the theme from within the widget headers; theme configuration is strictly controlled by your application config.
+
+---
+
+## Client API Methods (`EventWidgetClient`)
+
+When using the vanilla JavaScript / non-React API:
+
+| Method | Description |
+| :--- | :--- |
+| `mount(container: HTMLElement \| string)` | Mounts the widget into a DOM container element or element ID. |
+| `updateConfig(newConfig: Partial<WidgetConfig>)` | Merges new configuration values into the running widget without remounting. |
+| `setConfig(newConfig: WidgetConfig)` | Replaces the entire widget configuration. |
+| `unmount()` | Cleanly destroys the React root, removes DOM nodes, and releases event listeners. |
 
 ---
 
-## Client Methods (`EventWidgetClient`)
+## TypeScript Exports
 
-- **`mount(container: HTMLElement | string)`**: Mounts the widget into a DOM container element or ID.
-- **`updateConfig(newConfig: Partial<WidgetConfig>)`**: Updates specific configuration values dynamically without remounting.
-- **`setConfig(newConfig: WidgetConfig)`**: Replaces the full widget configuration.
-- **`unmount()`**: Cleanly destroys the widget and cleans up event listeners and DOM roots.
+All primary types are exported directly from the package:
+
+```typescript
+import {
+  EventWidget,
+  EventWidgetClient,
+  type WidgetConfig,
+  type WidgetPosition,
+  type ThemeMode,
+  type RegistrationSuccessPayload,
+  type WidgetErrorPayload
+} from '@voxket-ai/events-sdk';
+```
 
 ---
 
 ## License
 
-[MIT](LICENSE) © 2025 Shashank Sanket
+MIT © Voxket

package/dist/api/ApiClient.d.ts

@@ -3,7 +3,8 @@ export declare class ApiClient {
     private baseUrl;
     private slug;
     private logger;
-    constructor(baseUrl: string, slug: string, logger: Logger);
+    private timeoutMs;
+    constructor(baseUrl: string, slug: string, logger: Logger, timeoutMs?: number);
     private fetchApi;
     getFormSchema(): Promise<any>;
     submitRegistration(payload: any): Promise<any>;
@@ -21,6 +22,9 @@ export declare class ApiClient {
         new_password: string;
     }): Promise<any>;
     portalGetProfile(token: string): Promise<any>;
+    uploadFile(file: File, token?: string | null): Promise<any>;
+    deleteFile(assetId: string | number, token?: string | null): Promise<any>;
     portalUploadFile(token: string, file: File): Promise<any>;
+    portalDeleteFile(token: string, assetId: string | number): Promise<any>;
     portalUpdateProfile(token: string, payload: any): Promise<any>;
 }

package/dist/components/AttendeePortal.d.ts

@@ -7,7 +7,9 @@ interface AttendeePortalProps {
     storage: StorageHelper;
     logger: Logger;
     primaryColor: string;
+    isDark?: boolean;
     onEvent?: (eventName: string, payload: any) => void;
+    onError?: (error: any) => void;
 }
 export declare const AttendeePortal: React.FC<AttendeePortalProps>;
 export {};

package/dist/components/DynamicForm.d.ts

@@ -1,2 +1,2 @@
 import React from 'react';
-export declare const DynamicForm: ({ schema, onSubmit, onBack, theme, displayMode, isExpanded, onToggleExpand, onClose, onChange, initialValues }: any) => React.JSX.Element;
+export declare const DynamicForm: ({ schema, onSubmit, onBack, theme, displayMode, isExpanded, onToggleExpand, onClose, onChange, initialValues, isDark, apiClient, storage, onError, onEvent, }: any) => React.JSX.Element;

package/dist/components/EventWidgetReact.d.ts

@@ -1,5 +1,9 @@
 import React from 'react';
-import { type WidgetConfig } from '../types';
+import { type WidgetConfig, type WidgetPosition } from '../types';
+export type Corner = 'bottom-right' | 'bottom-left' | 'top-right' | 'top-left';
+export declare function normalizePosition(pos?: WidgetPosition): Corner;
+export declare const getCornerStyle: (corner: Corner) => React.CSSProperties;
+export declare const getCornerClasses: (corner: Corner) => string;
 interface Props {
     config: WidgetConfig;
 }