@tiquo/dom-package 1.0.0

package/README.md

@@ -0,0 +1,498 @@
+# @tiquo/dom-package
+
+Tiquo SDK for third-party websites. Integrate authentication, customer profiles, orders, bookings, and enquiries into your website with a simple JavaScript API.
+
+## Features
+
+- **Email OTP Authentication** - Secure passwordless login using email verification codes
+- **Session Management** - Automatic session persistence and refresh
+- **Multi-Tab Sync** - Auth state automatically syncs across all browser tabs
+- **Customer Flow Integration** - Embed authenticated customer flows with one line of code
+- **Framework Agnostic** - Works with React, Vue, Svelte, or vanilla JavaScript
+- **TypeScript Support** - Full type definitions included
+
+## Installation
+
+```bash
+npm install @tiquo/dom-package
+# or
+yarn add @tiquo/dom-package
+# or
+pnpm add @tiquo/dom-package
+```
+
+## Quick Start
+
+### 1. Get Your Public Key
+
+Go to your Tiquo dashboard → Settings → Auth DOM to get your public key.
+
+### 2. Initialize the SDK
+
+```typescript
+import { TiquoAuth } from '@tiquo/dom-package';
+
+const auth = new TiquoAuth({
+  publicKey: 'pk_dom_your_public_key'
+});
+```
+
+### 3. Authenticate Users
+
+```typescript
+// Step 1: Send OTP to user's email
+await auth.sendOTP('user@example.com');
+
+// Step 2: Verify the OTP code
+const result = await auth.verifyOTP('user@example.com', '123456');
+
+// Step 3: Get user data
+const session = await auth.getUser();
+console.log(session?.user.email); // user@example.com
+console.log(session?.customer?.firstName); // John
+```
+
+## API Reference
+
+### Constructor
+
+```typescript
+const auth = new TiquoAuth({
+  publicKey: string;       // Required: Your public key from Tiquo dashboard
+  apiEndpoint?: string;    // Optional: API endpoint (defaults to production)
+  storagePrefix?: string;  // Optional: localStorage key prefix
+  debug?: boolean;         // Optional: Enable debug logging
+  enableTabSync?: boolean; // Optional: Multi-tab session sync (default: true)
+});
+```
+
+### Methods
+
+#### `sendOTP(email: string): Promise<SendOTPResult>`
+
+Send a verification code to the user's email.
+
+```typescript
+const result = await auth.sendOTP('user@example.com');
+// { success: true, message: 'OTP sent' }
+```
+
+#### `verifyOTP(email: string, otp: string): Promise<VerifyOTPResult>`
+
+Verify the OTP code and authenticate the user.
+
+```typescript
+const result = await auth.verifyOTP('user@example.com', '123456');
+// {
+//   success: true,
+//   sessionToken: 'xxx',
+//   expiresAt: 1234567890,
+//   isNewUser: false,
+//   hasCustomer: true
+// }
+```
+
+#### `getUser(): Promise<TiquoSession | null>`
+
+Get the current authenticated user and customer data.
+
+```typescript
+const session = await auth.getUser();
+if (session) {
+  console.log(session.user.id);
+  console.log(session.user.email);
+  console.log(session.customer?.firstName);
+  console.log(session.customer?.customerNumber);
+}
+```
+
+#### `isAuthenticated(): boolean`
+
+Check if the user is currently authenticated.
+
+```typescript
+if (auth.isAuthenticated()) {
+  // User is logged in
+}
+```
+
+#### `updateProfile(updates): Promise<ProfileUpdateResult>`
+
+Update the authenticated customer's profile. Only allows updating the logged-in customer's own data.
+
+```typescript
+const result = await auth.updateProfile({
+  firstName: 'John',
+  lastName: 'Doe',
+  displayName: 'Johnny',
+  phone: '+1234567890',
+});
+
+console.log(result.customer.firstName); // 'John'
+```
+
+**Available fields:**
+- `firstName` - Customer's first name
+- `lastName` - Customer's last name
+- `displayName` - Display name (nickname)
+- `phone` - Primary phone number
+- `profilePhoto` - URL to profile photo
+
+#### `logout(): Promise<void>`
+
+Log out the current user.
+
+```typescript
+await auth.logout();
+```
+
+#### `getOrders(options?): Promise<GetOrdersResult>`
+
+Get the authenticated customer's order history. Only returns orders for the logged-in customer.
+
+```typescript
+// Get all orders (default limit 50)
+const { orders, hasMore, nextCursor } = await auth.getOrders();
+
+// With pagination
+const page1 = await auth.getOrders({ limit: 10 });
+const page2 = await auth.getOrders({ limit: 10, cursor: page1.nextCursor });
+
+// Filter by status
+const completedOrders = await auth.getOrders({ status: 'completed' });
+```
+
+**Options:**
+- `limit` - Number of orders to return (max 100, default 50)
+- `cursor` - Order ID to start after (for pagination)
+- `status` - Filter by status: `draft`, `pending`, `confirmed`, `processing`, `completed`, `cancelled`, `refunded`, `open_tab`
+
+**Returns:**
+- `orders` - Array of order objects with items, totals, and status
+- `hasMore` - Whether there are more orders to fetch
+- `nextCursor` - Cursor for the next page (if `hasMore` is true)
+
+#### `getBookings(options?): Promise<GetBookingsResult>`
+
+Get the authenticated customer's booking history. Only returns bookings for the logged-in customer.
+
+```typescript
+// Get all bookings (default limit 50)
+const { bookings, hasMore, nextCursor } = await auth.getBookings();
+
+// Get upcoming bookings only (sorted soonest first)
+const upcomingBookings = await auth.getBookings({ upcoming: true });
+
+// Filter by status
+const confirmedBookings = await auth.getBookings({ status: 'confirmed' });
+
+// With pagination
+const page1 = await auth.getBookings({ limit: 10 });
+const page2 = await auth.getBookings({ limit: 10, cursor: page1.nextCursor });
+```
+
+**Options:**
+- `limit` - Number of bookings to return (max 100, default 50)
+- `cursor` - Booking ID to start after (for pagination)
+- `status` - Filter by status: `draft`, `scheduled`, `confirmed`, `reminder_sent`, `waiting_room`, `waiting_list`, `checked_in`, `active`, `in_progress`, `completed`, `cancelled`, `no_show`, `rescheduled`
+- `upcoming` - If true, only return future bookings (sorted soonest first)
+
+**Returns:**
+- `bookings` - Array of booking objects with service details, date/time, and status
+- `hasMore` - Whether there are more bookings to fetch
+- `nextCursor` - Cursor for the next page (if `hasMore` is true)
+
+#### `getEnquiries(options?): Promise<GetEnquiriesResult>`
+
+Get the authenticated customer's enquiry history. Only returns enquiries for the logged-in customer.
+
+```typescript
+// Get all enquiries (default limit 50)
+const { enquiries, hasMore, nextCursor } = await auth.getEnquiries();
+
+// Filter by status
+const openEnquiries = await auth.getEnquiries({ status: 'in_progress' });
+
+// With pagination
+const page1 = await auth.getEnquiries({ limit: 10 });
+const page2 = await auth.getEnquiries({ limit: 10, cursor: page1.nextCursor });
+```
+
+**Options:**
+- `limit` - Number of enquiries to return (max 100, default 50)
+- `cursor` - Enquiry ID to start after (for pagination)
+- `status` - Filter by status: `new`, `in_progress`, `waiting_customer`, `waiting_internal`, `won`, `lost`, `closed`, `resolved`, `archived`
+
+**Returns:**
+- `enquiries` - Array of enquiry objects with subject, message, status, and priority
+- `hasMore` - Whether there are more enquiries to fetch
+- `nextCursor` - Cursor for the next page (if `hasMore` is true)
+
+#### `destroy(): void`
+
+Clean up resources when destroying the auth instance. Call this when your component unmounts or when you no longer need the auth instance.
+
+```typescript
+// In React
+useEffect(() => {
+  const auth = new TiquoAuth({ publicKey: 'pk_dom_xxx' });
+  
+  return () => {
+    auth.destroy(); // Cleanup on unmount
+  };
+}, []);
+
+// Or when done with auth
+auth.destroy();
+```
+
+#### `onAuthStateChange(callback): () => void`
+
+Subscribe to authentication state changes. Returns an unsubscribe function.
+
+```typescript
+const unsubscribe = auth.onAuthStateChange((session) => {
+  if (session) {
+    console.log('User logged in:', session.user.email);
+  } else {
+    console.log('User logged out');
+  }
+});
+
+// Later: unsubscribe()
+```
+
+#### `embedCustomerFlow(flowUrl, container, options?): Promise<HTMLIFrameElement>`
+
+Embed a Tiquo customer flow with automatic authentication.
+
+```typescript
+await auth.embedCustomerFlow(
+  'https://book.tiquo.app/your-flow',
+  '#container',
+  {
+    width: '100%',
+    height: '600px',
+    onLoad: () => console.log('Flow loaded'),
+    onError: (err) => console.error('Flow error:', err)
+  }
+);
+```
+
+#### `getIframeToken(customerFlowId?): Promise<IframeTokenResult>`
+
+Generate a short-lived token for manual iframe authentication.
+
+```typescript
+const { token, expiresAt } = await auth.getIframeToken();
+// Use token in iframe URL: ?_auth_token=xxx
+```
+
+## React Integration
+
+```tsx
+import { TiquoAuth } from '@tiquo/dom-package';
+import { useState, useEffect } from 'react';
+
+const auth = new TiquoAuth({ publicKey: 'pk_dom_xxx' });
+
+function App() {
+  const [session, setSession] = useState(null);
+  const [loading, setLoading] = useState(true);
+
+  useEffect(() => {
+    // Subscribe to auth changes
+    const unsubscribe = auth.onAuthStateChange((s) => {
+      setSession(s);
+      setLoading(false);
+    });
+
+    return unsubscribe;
+  }, []);
+
+  if (loading) return <div>Loading...</div>;
+
+  if (!session) {
+    return <LoginForm />;
+  }
+
+  return (
+    <div>
+      <p>Welcome, {session.user.email}!</p>
+      <button onClick={() => auth.logout()}>Logout</button>
+    </div>
+  );
+}
+
+function LoginForm() {
+  const [email, setEmail] = useState('');
+  const [otp, setOtp] = useState('');
+  const [step, setStep] = useState<'email' | 'otp'>('email');
+  const [error, setError] = useState('');
+
+  const handleSendOTP = async (e) => {
+    e.preventDefault();
+    try {
+      await auth.sendOTP(email);
+      setStep('otp');
+    } catch (err) {
+      setError(err.message);
+    }
+  };
+
+  const handleVerifyOTP = async (e) => {
+    e.preventDefault();
+    try {
+      await auth.verifyOTP(email, otp);
+      // Auth state change will update the UI
+    } catch (err) {
+      setError(err.message);
+    }
+  };
+
+  if (step === 'email') {
+    return (
+      <form onSubmit={handleSendOTP}>
+        <input
+          type="email"
+          value={email}
+          onChange={(e) => setEmail(e.target.value)}
+          placeholder="Email"
+          required
+        />
+        <button type="submit">Send Code</button>
+        {error && <p>{error}</p>}
+      </form>
+    );
+  }
+
+  return (
+    <form onSubmit={handleVerifyOTP}>
+      <p>Enter the code sent to {email}</p>
+      <input
+        type="text"
+        value={otp}
+        onChange={(e) => setOtp(e.target.value)}
+        placeholder="000000"
+        maxLength={6}
+        required
+      />
+      <button type="submit">Verify</button>
+      {error && <p>{error}</p>}
+    </form>
+  );
+}
+```
+
+## Vue Integration
+
+```vue
+<script setup>
+import { TiquoAuth } from '@tiquo/dom-package';
+import { ref, onMounted, onUnmounted } from 'vue';
+
+const auth = new TiquoAuth({ publicKey: 'pk_dom_xxx' });
+
+const session = ref(null);
+const loading = ref(true);
+let unsubscribe;
+
+onMounted(() => {
+  unsubscribe = auth.onAuthStateChange((s) => {
+    session.value = s;
+    loading.value = false;
+  });
+});
+
+onUnmounted(() => {
+  unsubscribe?.();
+  auth.destroy(); // Clean up resources including tab sync
+});
+
+async function logout() {
+  await auth.logout();
+}
+</script>
+
+<template>
+  <div v-if="loading">Loading...</div>
+  <div v-else-if="session">
+    <p>Welcome, {{ session.user.email }}!</p>
+    <button @click="logout">Logout</button>
+  </div>
+  <LoginForm v-else />
+</template>
+```
+
+## Multi-Tab Session Sync
+
+The SDK automatically synchronizes authentication state across all browser tabs using the [BroadcastChannel API](https://developer.mozilla.org/en-US/docs/Web/API/BroadcastChannel). This means:
+
+- **Login in one tab → All tabs are authenticated**
+- **Logout in one tab → All tabs are logged out**
+- **Profile updates sync across tabs**
+
+This feature is enabled by default and works automatically. No additional code is required.
+
+### Disabling Tab Sync
+
+If you need to disable multi-tab sync (e.g., for isolated sessions):
+
+```typescript
+const auth = new TiquoAuth({
+  publicKey: 'pk_dom_xxx',
+  enableTabSync: false, // Disable multi-tab sync
+});
+```
+
+### Browser Support
+
+Multi-tab sync requires `BroadcastChannel` support. It's available in all modern browsers:
+- Chrome 54+
+- Firefox 38+
+- Safari 15.4+
+- Edge 79+
+
+For older browsers, the feature gracefully degrades - auth still works normally, just without cross-tab sync.
+
+## Error Handling
+
+All SDK methods can throw `TiquoAuthError` with helpful error codes:
+
+```typescript
+import { TiquoAuth, TiquoAuthError } from '@tiquo/dom-package';
+
+try {
+  await auth.verifyOTP(email, otp);
+} catch (error) {
+  if (error instanceof TiquoAuthError) {
+    switch (error.code) {
+      case 'OTP_VERIFY_FAILED':
+        console.log('Invalid or expired code');
+        break;
+      case 'NOT_AUTHENTICATED':
+        console.log('Please log in first');
+        break;
+      default:
+        console.log('Error:', error.message);
+    }
+  }
+}
+```
+
+## Security Considerations
+
+- The public key is safe to expose in client-side code
+- Sessions are stored in localStorage with automatic refresh
+- OTP codes expire after 10 minutes
+- Failed OTP attempts are rate limited (max 5 attempts per code)
+
+## Support
+
+- [Documentation](https://docs.tiquo.com/dom-package)
+- [GitHub Issues](https://github.com/tiquo/dom-package/issues)
+- [Support Email](mailto:support@tiquo.com)
+
+## License
+
+MIT