DOM Package

The Tiquo DOM Package (@tiquo/dom-package) is a JavaScript SDK that provides customer authentication directly in the browser. It uses an email OTP flow: the customer enters their email address, receives a 6-digit verification code, and signs in. No passwords, no redirects, no OAuth configuration.

Once authenticated, the SDK issues JWT access and refresh tokens that work with the Client API. It also handles token storage, automatic token refresh, and multi-tab session synchronization out of the box.

Installation

npm install @tiquo/dom-package

Getting Your Public Key

Before using the SDK, you need to get your public key from the Tiquo dashboard:

1. Open your Tiquo dashboard
2. Go to Settings > Auth DOM
3. Enable the Auth DOM feature
4. Copy your public key (it starts with pk_dom_)

You will also need to add the domains where you plan to use the SDK to the Allowed Domains list in the same settings page. Requests from unlisted domains will be rejected.

Quick Start

import { TiquoAuth } from '@tiquo/dom-package';

// Initialize with your public key
const auth = new TiquoAuth({
  publicKey: 'pk_dom_your_key_here',
});

// Step 1: Send an OTP to the customer's email
await auth.sendOTP('customer@example.com');

// Step 2: Verify the OTP code the customer received
const result = await auth.verifyOTP('customer@example.com', '123456');

// The customer is now authenticated
const user = await auth.getUser();
console.log(user.email);

Configuration Options

const auth = new TiquoAuth({
  publicKey: 'pk_dom_your_key_here',
  debug: true,
  enableTabSync: true,
});

Authentication Flow

Sending an OTP

Call sendOTP with the customer's email address. Tiquo will send a 6-digit verification code to that address.

try {
  await auth.sendOTP('customer@example.com');
  // Show the OTP input field in your UI
} catch (error) {
  console.error('Failed to send OTP:', error.message);
}

The email is sent from a branded sender that you can customize per domain in Settings > Auth DOM > Allowed Domains. Each domain can have its own sender name and email theme.

Verifying an OTP

Call verifyOTP with the same email and the code the customer entered. On success, the SDK stores the JWT tokens and the customer is signed in.

try {
  const result = await auth.verifyOTP('customer@example.com', '123456');
  // Customer is now authenticated
  console.log('Signed in as:', result.email);
} catch (error) {
  console.error('Verification failed:', error.message);
}

After successful verification, the SDK:

• Stores the access token and refresh token in localStorage
• Sets a cross-subdomain cookie (tiquo_customer_user_ids) for tracking pixel integration
• Broadcasts the login event to other open tabs

Checking Authentication State

// Check if the customer is currently authenticated
const isLoggedIn = auth.isAuthenticated();

// Get the current user's profile (fetches from Client API if needed)
const user = await auth.getUser();
if (user) {
  console.log(user.email);
  console.log(user.customer?.displayName);
}

isAuthenticated() checks whether a valid (non-expired) access token exists. getUser() returns the cached session data, or fetches it from the Get Profile endpoint if no cache is available.

Updating the Customer Profile

await auth.updateProfile({
  firstName: 'John',
  lastName: 'Smith',
  phone: '+1234567890',
});

This calls the Update Profile endpoint under the hood.

Fetching Customer Data

The SDK provides convenience methods for the Client API list endpoints:

// Get order history
const orders = await auth.getOrders();

// Get booking history
const bookings = await auth.getBookings();

// Get enquiry history
const enquiries = await auth.getEnquiries();

These methods handle authentication headers and token refresh automatically.

Listening for Auth State Changes

Register a callback to be notified when the authentication state changes. This fires on login, logout, token refresh, and session updates from other tabs.

const unsubscribe = auth.onAuthStateChange((event) => {
  if (event.type === 'LOGIN') {
    console.log('Customer signed in');
  } else if (event.type === 'LOGOUT') {
    console.log('Customer signed out');
  }
});

// Later, to stop listening:
unsubscribe();

Logging Out

await auth.logout();

This revokes the session on the server, clears stored tokens from localStorage, and broadcasts the logout event to other tabs so they can update their UI.

Token Management

The SDK manages tokens automatically:

• Storage: Access and refresh tokens are stored in localStorage
• Automatic refresh: The SDK refreshes the access token 5 minutes before it expires, using the Refresh Token endpoint
• Token rotation: Each refresh rotates both the access and refresh tokens
• Multi-tab sync: Login, logout, and token refresh events are broadcast to all open tabs via the BroadcastChannel API

You generally do not need to manage tokens yourself. If you need direct access to the current access token (for example, to pass it to a custom API call), the SDK provides it through the internal state.

Multi-Tab Synchronization

When enableTabSync is set to true (the default), the SDK uses the BroadcastChannel API to keep all tabs in sync. The following events are broadcast:

This means if a customer signs in on one tab, all other tabs will automatically pick up the session without the customer needing to refresh the page.

WebView Integration

If you are embedding a web page inside a native mobile app (iOS or Android), you can pass tokens into the SDK to avoid requiring the customer to sign in again. There are three ways to do this:

Option 1: Constructor Parameters

const auth = new TiquoAuth({
  publicKey: 'pk_dom_your_key_here',
  accessToken: 'eyJhbGciOiJSUzI1NiJ9...',
  refreshToken: 'rt_xxx...',
});

Option 2: Global Variable

Set the tokens before the SDK loads:

window.__TIQUO_INIT_TOKEN__ = {
  accessToken: 'eyJhbGciOiJSUzI1NiJ9...',
  refreshToken: 'rt_xxx...',
};

Option 3: URL Fragment

Append tokens to the URL when loading the WebView:

https://yoursite.com/page#tiquo_access_token=eyJ...&tiquo_refresh_token=rt_xxx

The SDK checks for injected tokens on initialization and uses them if found.

Dashboard Configuration

In the Tiquo dashboard under Settings > Auth DOM, you can configure:

How It Works with the Client API

The DOM Package is essentially a thin authentication layer on top of the Client API. Here is the full flow:

1. Your website loads the SDK and initializes it with your public key
2. The customer enters their email and receives a verification code
3. After verifying the code, Tiquo issues a JWT access token and refresh token
4. The SDK stores these tokens in the browser and uses them for all Client API requests
5. When the access token expires, the SDK automatically calls the refresh endpoint to get a new pair
6. All Client API data (profile, orders, bookings, enquiries) is scoped to the authenticated customer

The SDK sends OTP requests to https://edge.tiquo.app/api/auth-dom/otp/send and https://edge.tiquo.app/api/auth-dom/otp/verify. After successful verification, it uses the standard Client API endpoints at https://edge.tiquo.app/api/client/v1/.

Cleanup

When you are done with the SDK instance (for example, on a single-page app route change), call destroy() to clean up event listeners and the BroadcastChannel:

auth.destroy();