Vygor Browser SDK

Table of Contents

- Getting Started
- Installation
- Basic Usage
- Initialization
- Mounting Elements
- Fetching Data
- Authentication
- Vygor Elements
- googleSignIn
- bookingCheckout
- membershipCheckout
- Methods
- init
- fetchSchedule
- fetchBookable
- fetchMembershipPlans
- fetchOrganization
- captureEmail
- createAccount
- login
- logout
- fetchCustomer
- on
- cleanup
- Element.create
- Properties
- organizationId
- endpoint
- debug
- defaultEndpoint
- Models
- Organization
- Organization.Schedule
- Customer
- Booking
- Bookable
- Bookable.Template
- Recurrence
- Staff
- Membership
- Membership.Plan
- PaymentMethod
- Theming
- Root Properties
- shape
- spacing
- card
- font
- colors
- Overrides
- Button Overrides
- Advanced Usage
- Multiple Vygor.Clients

Getting Started

$3

``
npm i @vygor/browser-sdk
`

or

`
yarn add @vygor/browser-sdk
`

or

`
pnpm i @vygor/browser-sdk
`

$3

#### Initialization

Initialization must run before calling any Vygor methods or referencing properties.

`ts
Vygor.init("");
// e.g.
Vygor.init("o_example");
// Sandbox
Vygor.init("o_example", { endpoint: "https://staging.vygorai.com" });
`

#### Mounting Elements

Vygor Elements are a set of prebuilt UI components that help you quickly integrate Vygor functionality into your studio website. They handle complex workflows like checkouts and authentication.

Elements are designed to be simple to use while providing a seamless experience for your customers. They automatically handle:

- Unified authentication with Vygor and other studios powered by Vygor
- Secure payment processing
- Form validation and error handling
- Responsive layouts that work on all devices
- Consistent styling that matches your brand
- State management and data synchronization

See Vygor Elements for more info

`ts
Vygor.Element.create("googleSignIn", {}).mount(element);

// With options
Vygor.Element.create("bookingCheckout", {
bookableId: "bo_example",
membershipPlanId: "mp_example", // Optional
onSuccess(data) {
// ...
},
}).mount(element);
`

#### Fetching Data

The Vygor Browser SDK makes it easy to fetch data from your Vygor organization. The SDK provides simple methods to access schedules, customer data, bookables, membership plans, and more.

`ts
Vygor.fetchSchedule().then((data) => {
/ ... /
});
`

$3

Vygor has multiple customer authentication methods, we recommend using the googleSignIn element as the primary option and while allowing traditional email/password login as a fallback. The same set of options will always be available in checkout elements.

`ts
// Mount googleSignIn element
Vygor.Element.create("googleSignIn", {}).mount(element);

// Traditional login
Vygor.login(email, password);
`

Since there are several potential login entrypoints, we recommend you use events to manage this state to instead of handling each source individually.

`ts
Vygor.on("login", ({ customer, memberships, membershipPlans }) => {
// ...
});
Vygor.on("logout", () => {
// ...
});
`

NOTE: memberships and membershipPlans are not populated with all memberships a customer has, just memberships referenced in the customer payload.

Vygor Elements

$3

`ts
Vygor.Element.create("googleSignIn", {}).mount(element);
`

The googleSignIn element renders a Google Sign In button that uses the OpenID Connect flow (opens a popup window instead of redirecting).

Emits login event with authenticated customer data on successful sign-in.

$3

The bookingCheckout element renders a checkout form for booking a service. It provides a complete checkout experience including:

- Account information collection
- Guest booking management
- Optional membership purchase
- Cart and pricing resolution
- Alternative currency support (credits/guest passes)
- Secure payment processing
- Digital waiver signatures

Unauthenticated customers can log in or create an account during the checkout process. Logged-in customers will have their information pre-filled. Customers are required to have an account to make a purchase.

Emits login event with authenticated customer data when customer logs in.
Emits logout event when customer clicks log out button.

Example:

`ts
Vygor.Element.create("bookingCheckout", {
bookableId,
membershipPlanId, // Optional
onSuccess(data) {
// ...
},
}).mount(element);
`

#### Options

##### bookableId

`ts
bookableId: Bookable.Id;
`

The ID of the bookable to check out.

This can be obtained from the organization's schedule (Vygor.fetchSchedule())

##### membershipPlanId (optional)

`ts
membershipPlanId?: Membership.Plan.Id;
`

The ID of the membership plan to purchase during checkout.

If provided, the checkout will include the membership purchase in the total. The membership will be activated immediately after successful payment.

This can be obtained from the organization's membership plans (Vygor.fetchMembershipPlans())

##### cart

`ts
cart?: {
hideOriginalPrice?: boolean
}
`

Configuration options for the cart display and behavior during checkout.

Properties:

- hideOriginalPrice (optional): By default, when booking with an alternative resource (membership, credits, guest passes), the original price of the bookable is displayed in the cart with a strikethrough. Enable this option to hide it.
- _Default_: false

Example:

`ts
Vygor.Element.create("bookingCheckout", {
bookableId: "bo_example",
cart: {
hideOriginalPrice: true, // Only show final cost, hide original price
},
onSuccess(data) {
// ...
},
}).mount(element);
`

##### onSuccess

`ts
onSuccess(data: {
customer: Customer
booking: Booking;
guestBookings: Booking[];
membership?: Membership;
}): void;
`

Callback function that runs when the checkout completes successfully.

The callback receives an object containing:

- customer: The updated current customer post checkout.
- booking: The created booking for the logged-in customer
- guestBookings: Array of bookings created for any guests added during checkout
- membership: The created membership if a membership plan was purchased during checkout, otherwise undefined

$3

The membershipCheckout element renders a checkout form for purchasing a membership plan. This checkout experience includes:

- Account information collection
- Membership details and benefits display
- Pricing information
- Secure payment processing
- Digital agreement signing

Unauthenticated customers can log in or create an account during the checkout process. Logged-in customers will have their information pre-filled. Customers are required to have an account to make a purchase.

Emits login event with authenticated customer data when customer logs in.
Emits logout event when customer clicks log out button.

Example:

`ts
Vygor.Element.create("membershipCheckout", {
planId,
onSuccess(data) {
// ...
},
}).mount(element);
`

#### Options

##### planId

`ts
planId: Membership.Plan.Id;
`

The ID of the membership plan to purchase.

This can be obtained from the organization's membership plans (Vygor.fetchMembershipPlans())

##### onSuccess

`ts
onSuccess(data: { membership: Membership }): void;
`

Callback function that runs when the checkout completes successfully.

The callback receives an object containing:

- customer: The updated current customer post checkout.
- membership: The created membership that was purchased during checkout

Methods

$3

`ts
Vygor.init(organizationId: Organization.Id, options?: {
endpoint?: string;
theme?: Vygor.ThemeOptions;
})
`

Initializes the Vygor client with your organization ID. This must be called before using any other methods.

#### Parameters

- organizationId: Your organization ID (e.g., "o_example")
- options.endpoint (optional): Override the default API endpoint (e.g., "https://staging.vygorai.com")
- options.theme (optional): Customization options for Vygor Elements. See Theming for details.

$3

`ts
Vygor.fetchSchedule(params?: {
bookableTemplateId?: Bookable.Template.Id;
staffId?: Staff.Id;
endAtAfter?: Date;
cursor?: string;
}): Promise
`

Fetches the organization's schedule data. You can filter the results by bookable template, staff member, or date range, and paginate through large result sets. Each page contains 50 results.

#### Parameters

- params.bookableTemplateId (optional): Filter to show only bookables of a specific template
- params.staffId (optional): Filter to show only bookables with a specific staff member
- params.endAtAfter (optional): Filter to show only bookables ending on or after the specified date
- params.cursor (optional): Pagination cursor from a previous request's response

#### Returns

A promise that resolves to the organization's schedule with a pagination cursor (nextCursor) to get the next page of 50 results.

#### Pagination Example

`ts
const firstPage = await Vygor.fetchSchedule({
endAtAfter: new Date(), // Only show future bookables
});

// ...

const secondPage = await Vygor.fetchSchedule({
cursor: firstPage.nextCursor,
});
`

$3

`ts
Vygor.fetchBookable(bookableId: Bookable.Id): Promise<{
bookable: Bookable;
bookableTemplate: Bookable.Template;
staff: Staff;
classTags: Bookable.Tag[];
}>
`

Fetches a single bookable by its ID. This is useful for when a bookable is not available from the schedule endpoint (such as when it's unlisted).

#### Parameters

- bookableId: The ID of the bookable to fetch (e.g. "bo_example")

#### Returns

A promise that resolves to an object containing the bookable and its dependencies.

$3

`ts
Vygor.fetchOrganization(): Promise
`

Fetches the current organization's details from organizationId.

#### Returns

A promise that resolves to an object containing the current organization.

$3

`ts
Vygor.fetchMembershipPlans(): Promise<{ membershipPlans: Membership.Plan[] }>
`

Fetches all available membership plans for the organization.

#### Returns

A promise that resolves to an object containing an array of membership plans.

$3

`ts
Vygor.captureEmail(email: string): Promise<{}>
`

Captures a potential customer's email address for marketing or lead generation. These will be targetable in campaigns in your organization's Vygor admin dashboard.

#### Parameters

- email: The email address to capture

#### Returns

A promise that resolves when the operation completes.

$3

`ts
Vygor.createAccount(email: string, password: string): Promise<{
customer: Customer;
}>
`

Creates a new customer account.

#### Parameters

- email: Email address for the new account
- password: Password for the new account

#### Returns

A promise that resolves with an object containing the newly created customer.

#### Events

Emits the login event on successful account creation.

$3

`ts
Vygor.login(email: string, password: string): Promise<{
customer: Customer;
memberships: Membership[];
membershipPlans: Membership.Plan[];
}>
`

Authenticates a customer using email and password. Includes the customer's memberships.

#### Parameters

- email: Customer's email address
- password: Customer's password

#### Returns

A promise that resolves with an object containing:

- customer: The authenticated customer data
- memberships: Array of the customer's memberships
- membershipPlans: Array of membership plans associated with the customer's memberships

#### Events

Emits the login event on successful authentication.

$3

`ts
Vygor.logout(): Promise
`

Logs out the currently authenticated customer.

#### Returns

A promise that resolves when the logout is complete.

#### Events

Emits the logout event when logout is complete.

$3

`ts
Vygor.fetchCustomer(): Promise<{
customer: Customer;
memberships: Membership[];
membershipPlans: Membership.Plan[];
}>
`

Fetches the currently authenticated customer's data.

#### Returns

A promise that resolves with an object containing:

- customer: The current customer data
- memberships: Array of the customer's memberships
- membershipPlans: Array of membership plans associated with the customer's memberships

$3

`ts
Vygor.on(event: 'login', handler: (data: {
customer: Customer;
memberships: Membership[];
membershipPlans: Membership.Plan[];
}) => void): { off: () => void }

Vygor.on(event: 'logout', handler: () => void): { off: () => void }
`

Registers an event handler for Vygor events.

#### Parameters

- event: The event to listen for ('login' or 'logout')
- handler: The function to call when the event occurs

#### Returns

An object with an off method that can be called to remove the event handler.

$3

`ts
Vygor.cleanup(): void
`

Cleans up all resources used by the Vygor client. Call this method when you're done using the SDK to free up memory.

$3

`ts
Vygor.Element.create(elementKey: Element.Key, options: Element.Options): Element
`

Creates a Vygor Element that can be mounted in the DOM.

#### Parameters

- elementKey: The type of element to create ('googleSignIn', 'bookingCheckout', or 'membershipCheckout')
- options: Configuration options specific to the element type

#### Returns

An Element object with a mount method that accepts an HTML element to mount into.

The mount method returns a handle to the mounted element with a cleanup function to remove the element and free resources.

#### Example

`ts
const element = Vygor.Element.create("googleSignIn", {});
const { cleanup } = element.mount(document.getElementById("container"));
// Later when done with the element:
cleanup();
`

Properties

$3

The organization ID the current client was initialized with.

$3

The endpoint the current client was initialized with.

$3

`ts
Vygor.debug = true;
`

When set to true, enables debug logging to the console for SDK operations. This can be helpful for troubleshooting SDK interactions.

Default: false

$3

`ts
Vygor.defaultEndpoint = "https://staging.vygorai.com";
`

Sets the default API endpoint for all Vygor clients. This can be used to globally configure the SDK to use a sandbox environment.

Default: "https://vygorai.com"

Models

The Vygor Browser SDK uses several data models to represent entities in your organization. Below are the core models referenced throughout the SDK.

$3

The organization represents your studio in the Vygor system.

`ts
type Organization = {
id: Organization.Id; // e.g. "o_example"
name: string;
imgUrl: string;
email: string;
phoneNumber?: string;
websiteUrl?: string;
address: Address;
descriptionMd?: string;
};

namespace Organization {
export type Id = o_${string};
}
`

#### Organization.Schedule

Represents the organization's schedule, including bookable services and their availability.

`ts
namespace Organization {
export type Schedule = {
bookables: Bookable[];
recurrences: Recurrence[];
staffs: Staff[];
bookableTemplates: Bookable.Template[];
};
}
`

$3

Represents a customer in your organization.

`ts
type Customer = {
id: Customer.Id; // e.g. "cu_example"
email: string;
name?: {
first: string;
middle?: string;
last: string;
};
pfpUrl?: string;
phone?: string;
classVoucherWallet: Customer.ClassVoucherWallet;
guestPassWallet: Customer.GuestPassWallet;
createdAt: Date;
organizationId: Organization.Id;
};

namespace Customer {
export type Id = cu_${string};

export type ClassVoucherWallet = {
id: ClassVoucherWallet.Id; // e.g. "cvw_example"
count: number;
unlimitedMembershipId?: Membership.Id;
};

export type GuestPassWallet = {
id: GuestPassWallet.Id; // e.g. "gpw_example"
count: number;
unlimitedMembershipId?: Membership.Id;
};
}
`

$3

Represents a service that can be booked, e.g. "Morning Yoga Class"

`ts
type Bookable = {
id: Bookable.Id; // e.g. "bo_example"
organizationId: Organization.Id;
templateId: Bookable.Template.Id;
recurrenceId?: Recurrence.Id;
startAt: Date;
endAt: Date;
capacity?: number;
availability?: number;
staffId?: Staff.Id;
unlisted: boolean;
currentCustomerBooking?: Booking;
};

namespace Bookable {
export type Id = bo_${string};
}
`

#### Bookable.Template

Represents a template for bookable services with shared properties.

`ts
namespace Bookable {
export type Template = {
id: Template.Id; // e.g. "bt_example"
name: string;
description?: string;
imgUrl: string;
priceCents: number;
};

export namespace Template {
export type Id = bt_${string};
}
}
`

$3

Represents a customer booking for a bookable.

`ts
type Booking = {
id: Booking.Id; // e.g. "bg_example"
bookableId: Bookable.Id;
customerId: Customer.Id;
status: "confirmed" | "cancelled";
resourceId: Booking.Resource.Id;
checkedInAt: Date;
};

namespace Booking {
export type Id = bg_${string};

export type Resource =
| Membership
| PaymentMethod
| Customer.ClassVoucherWallet
| Customer.GuestPassWallet;
}
`

#### Booking.Resource

Represents the resource used to make a booking. This can be a membership, payment method, class voucher wallet, or guest pass wallet.

$3

Represents a recurring schedule for bookable services.

For rrule, see: iCalendar Recurrence Rule (RFC 5545)

Example rrule values:

- FREQ=WEEKLY;BYDAY=MO,WE,FR - Every Monday, Wednesday, and Friday
- FREQ=WEEKLY;INTERVAL=2;BYDAY=TU - Every other Tuesday
- FREQ=MONTHLY;BYMONTHDAY=15 - 15th day of every month

`ts
type Recurrence = {
id: Recurrence.Id; // e.g. "r_example"
rrule: string; // iCalendar Recurrence Rule (RFC 5545)
duration: number; // Duration in minutes
startAt: Date;
capacity?: number;
availability?: number;
staffId?: Staff.Id;
organizationId: Organization.Id;
templateId: Bookable.Template.Id;
};

namespace Recurrence {
export type Id = r_${string};
}
`

$3

Represents staff members in your organization who can teach classes or provide services.

`ts
type Staff = {
id: Staff.Id; // e.g. "sp_example"
email: string;
name: {
first: string;
middle?: string;
last: string;
};
pfpUrl?: string;
phone?: string;
role: Staff.Role;
};

namespace Staff {
export type Id = sp_${string};
export type Role = "staff" | "owner" | "retired";
}
`

$3

Represents a customer's membership.

`ts
type Membership = {
id: Membership.Id; // e.g. "m_example"
expiresAt: Date;
activatedAt: Date;
planId: Membership.Plan.Id;
customerId: Customer.Id;
};

namespace Membership {
export type Id = m_${string};
}
`

#### Membership.Plan

Represents a membership plan that customers can purchase.

`ts
namespace Membership {
export type Plan = {
id: Plan.Id; // e.g. "mp_example"
organizationId: Organization.Id;
name: string;
description: string;
priceCents: number;
introOfferType?: Plan.IntroOfferType;
renewalPeriod?: Plan.Period;
classLimit?: number;
classRefreshPeriod?: Plan.Period;
guestPassLimit?: number;
guestPassRefreshPeriod?: Plan.Period;
};

export namespace Plan {
export type Id = mp_${string};
export type Period = ${number} ${Period.Unit}; // e.g. "1 month"
export namespace Period {
export type Unit = "day" | "week" | "month" | "year";
}
export type IntroOfferType = "pre-booking" | "pre-membership" | "pre-self";
}
}
`

$3

Represents a payment method attached to a customer used for purchases.

`ts
type PaymentMethod = {
id: PaymentMethod.Id; // e.g. "pm_example"
type: PaymentMethod.Type;
details: {
brand: PaymentMethod.Card.Brand;
lastFour: string;
exp: ${string}/${string};
};
};

namespace PaymentMethod {
export type Id = pm_${string};
export type Type = "unknown" | "card";

export namespace Card {
export type Brand = "visa" | "mastercard" | "amex" | "discover";
}
}
`

Theming

You can customize the appearance of Vygor Elements to match your brand's styling. Theme options are passed during the initialization of the SDK via the theme property in the options object.

`ts
// Example theme configuration
Vygor.init("o_example", {
theme: {
baseUnit: "8px", // Base unit for scaling
shape: {
borderRadius: 2, // Multiplier for border radius
},
spacing: {
baseUnit: 1, // Multiplier or absolute value for spacing
panelGap: 2.5, // Multiplier for gap between panels
},
card: {
padding: 2, // Multiplier for card padding
borderRadius: 2, // Multiplier for card border radius
},
font: {
family: "MyCustomFont" || "google:Inter", // Font family name (can use Google Fonts)
faces: [
{
family: "MyCustomFont",
src: "url(/path/to/MyCustomFont.woff2)",
weight: 400,
style: "normal",
},
],
weights: {
semibold: 600,
bold: 700,
},
},
colors: {
background: "#ffffff",
onBackground: "#111111",
primary: "#6200ea",
onPrimary: "#ffffff",
border: "#cccccc",
success: "#00c853",
onSuccess: "#000000",
warning: "#ffab00",
onWarning: "#000000",
error: "#d50000",
onError: "#ffffff",
},
},
});
`

Below is a breakdown of the available theme properties:

$3

- baseUnit: string
- The universal base unit for scalar values. Change this to scale all spacing and sizing globally.
- _Default_: "0.5rem" or "8px"

$3

- borderRadius: number
- Universal default border radius for all components, applied as a multiplier of the root baseUnit.
- _Default_: 2.5

$3

- baseUnit: number | string
- The base unit specifically for the spacing system. If a number, it acts as a multiplier of the root baseUnit. If a string, it's used as an absolute CSS unit (e.g., 10px).
- _Default_: 1
- panelGap: number
- The gap between panels (e.g., in checkout elements), applied as a multiplier of the spacing.baseUnit.
- _Default_: 2

$3

- padding: number
- The padding inside card components, applied as a multiplier of the spacing.baseUnit.
- _Default_: 2.5
- borderRadius: number
- The border radius for card components, applied as a multiplier of the root baseUnit.
- _Default_: 2.5

$3

- family: google:${string} | string
- The primary font-family name to use. Use the google: prefix to load fonts from Google Fonts (e.g., google:Inter). Otherwise, provide a standard CSS font-family string.
- _Default_: "Figtree"
- faces: Array<{ family: string; src: string; weight: number; style?: "normal" | "italic" | "oblique" }>
- Allows loading external font faces. Provide an array of objects, each defining a font face. The src URL must be accessible by the Vygor endpoint origin (production: "https://vygorai.com").
- weights: { semibold?: number; bold?: number }
- Override the default font weights used within elements.
- semibold: _Default_: 600
- bold: _Default_: 700

$3

Provide valid CSS color strings for the following properties:

- background: The main background color for elements. _Default_: "#1f1e1d"
- onBackground: Text/icon color on background. Will be derived from background if not set. _Default_: "#eeeeee"
- primary: Main accent color used for buttons, highlights, and interactive elements. _Default_: "#ccc395"
- onPrimary: Text/icon color on primary backgrounds. Will be derived from primary if not set. _Default_: "#1f1e1d"
- border: Default border color for separators and outlines. Will be derived from background if not set. _Default_: "#484848"
- success: Color for success states, confirmations, and positive feedback. _Default_: "#00900b"
- onSuccess: Text/icon color on success backgrounds. Will be derived from success if not set. _Default_: "#ffffff"
- warning: Color for warning states, cautions, and alerts. _Default_: "#ddd900"
- onWarning: Text/icon color on warning backgrounds. Will be derived from warning if not set. _Default_: "#1f1e1d"
- error: Color for error states, failures, and destructive actions. _Default_: "#ff3d00"
- onError: Text/icon color on error backgrounds. Will be derived from error if not set. _Default_: "#ffffff"

Overrides

For more granular control beyond theming, you can use overrides to customize specific components within Vygor Elements. Overrides are passed during initialization via the overrides property in the options object.

`ts
Vygor.init("o_example", {
theme: {
// ... theme options
},
overrides: {
button: {
"primary": {
style: {
color: "#000000",
background: "#ffffff",
},
},
"text-primary": {
style: {
color: "#6200ea",
},
},
},
},
});
`

$3

You can customize the appearance of buttons within Vygor Elements by overriding their default styles.

#### button.primary

Overrides styles for primary action buttons (e.g., "Complete Purchase", "Book Now").

- style.color: string
- Text color for primary buttons.
- _Default_: "var(--strong-on-primary)" (derived from theme)
- style.background: string
- Background color for primary buttons.
- _Default_: "var(--primary)" (derived from theme)

#### button.text-primary

Overrides styles for text-based primary action buttons (buttons without background fills).

- style.color: string
- Text color for text-based primary buttons.
- _Default_: "var(--primary)" (derived from theme)

$3

`ts
// Customize button styles to match a specific brand
Vygor.init("o_example", {
theme: {
colors: {
primary: "#6200ea",
onPrimary: "#ffffff",
},
},
overrides: {
button: {
"primary": {
style: {
color: "#ffffff",
background: "linear-gradient(135deg, #667eea 0%, #764ba2 100%)",
},
},
"text-primary": {
style: {
color: "#667eea",
},
},
},
},
});
`

Advanced Usage

$3

You can create multiple clients targetting different organization IDs and endpoints with the Vygor.Client class

Example:

`ts
const client = new Vygor.Client(o_example);
// or
const client = new Vygor.Client(o_example, {
endpoint: "https://otherendpoint.com",
});

client.fetchSchedule().then(() => {
// ...
});
`

#### deferInitialization

If you need a reference to a client outside of the scope it can be initialized, you can use Vygor.Client.deferInitialization.

Example:

`ts
const client = Vygor.Client.deferInitialization();
// ...
client.init("o_example", {
endpoint: "https://otherendpoint.com",
});
// ...
client.fetchSchedule().then(() => {
// ...
});
``