@mrcharles/sdk 0.0.0-stage → 0.2.0

package/dist/types/rooms.d.ts

@@ -0,0 +1,76 @@
+import type { Http } from './http';
+import { MrCharlesError } from './errors';
+import type { Links } from './links';
+import { type Locale, type LocaleInput } from './i18n';
+import type { Channel, ConfirmRequest, Confirmation, Hold, PublicRoom, PublicSite, RoomAvailability } from './types';
+export type RoomStep = 'slot' | 'details' | 'verify' | 'pay' | 'done' | 'expired';
+export interface RoomBookingState {
+    step: RoomStep;
+    site: PublicSite | null;
+    room: PublicRoom | null;
+    availability: RoomAvailability | null;
+    hold: Hold | null;
+    confirmation: Confirmation | null;
+    /** Last error from any action; cleared on the next successful one */
+    error: MrCharlesError | null;
+    /** `error` as a sentence in the flow's language — show this one. */
+    errorMessage: string | null;
+    busy: boolean;
+    /** Language of the flow's strings and of the guest's messages. */
+    locale: Locale;
+}
+export interface GuestDetails {
+    date: string;
+    startTime: string;
+    durationMinutes: number;
+    guestName: string;
+    channel: Channel;
+    contact: string;
+    /** Language of the guest's code and confirmation; defaults to the flow's locale. */
+    locale?: LocaleInput;
+    captchaToken?: string;
+}
+export interface RoomBookingOptions {
+    slug: string;
+    roomId: string;
+    /** Called on every state change */
+    onChange?: (state: RoomBookingState) => void;
+    /** Language for strings, errors and the guest's messages. Defaults to the client's locale, then the site's default. */
+    locale?: LocaleInput;
+}
+export interface RoomBooking {
+    readonly state: RoomBookingState;
+    subscribe(fn: (state: RoomBookingState) => void): () => void;
+    /** Site payload (cached 60 s server-side). Resolves the room too. */
+    loadSite(): Promise<PublicSite>;
+    /** Free spans for a window; defaults to the next 14 days from today in the studio's zone. */
+    loadAvailability(window?: {
+        from?: string;
+        to?: string;
+        days?: number;
+    }): Promise<RoomAvailability>;
+    /** Start times for a date and duration, from the loaded availability. */
+    startTimesFor(date: string, durationMinutes: number): string[];
+    /** Durations that fit after a start time, from the loaded availability. */
+    durationsFor(date: string, startTime: string): number[];
+    /** Reserve the slot and send the code. One idempotency key per attempt is handled for you. */
+    hold(details: GuestDetails): Promise<Hold>;
+    verify(code: string): Promise<Hold>;
+    resend(): Promise<Hold>;
+    confirm(req: ConfirmRequest): Promise<Confirmation>;
+    /** Milliseconds until the hold expires; 0 when there is no live hold. */
+    remainingMs(): number;
+    /** Forget the hold and start over (new idempotency key). Keeps site and availability. */
+    reset(): void;
+    destroy(): void;
+    /** Translate a UI string in the flow's language: `flow.t('action.confirm')`. */
+    t(key: string, params?: Record<string, string | number>): string;
+    /** Switch language mid-flow (a language switcher on the page). */
+    setLocale(locale: LocaleInput): void;
+}
+/**
+ * The whole guest flow for one room as a small state machine: availability →
+ * hold → code → confirm, with the expiry timer, idempotency key and error
+ * classification handled. Render it with any UI.
+ */
+export declare function createRoomBooking(http: Http, links: Links, opts: RoomBookingOptions, clientLocale?: () => LocaleInput | undefined): RoomBooking;

package/dist/types/slots.d.ts

@@ -0,0 +1,19 @@
+import type { FreeSpan } from './types';
+/** "17:30" → 1050 */
+export declare function toMinutes(hhmm: string): number;
+/** 1050 → "17:30" */
+export declare function toHHMM(minutes: number): string;
+export declare function addMinutes(hhmm: string, minutes: number): string;
+/**
+ * Every start time at which a booking of `durationMinutes` fits inside one
+ * of the free spans, on the `stepMinutes` grid. Sorted, de-duplicated.
+ */
+export declare function startTimes(free: FreeSpan[], durationMinutes: number, stepMinutes: number): string[];
+/** Durations between min and max, on the step grid, that still fit after `start`. */
+export declare function durationOptions(free: FreeSpan[], start: string, minMinutes: number, maxMinutes: number, stepMinutes: number): number[];
+/** 2500, "EUR" → "25,00 €" (locale-aware; minor units in, string out). */
+export declare function formatPrice(cents: number, currency: string, locale?: string): string;
+/** "2026-10-12" for a Date, in the given IANA zone (today in the studio's zone). */
+export declare function dateKey(date: Date, timeZone: string): string;
+/** YYYY-MM-DD plus n days, calendar arithmetic only (no zone involved). */
+export declare function addDays(key: string, days: number): string;

package/dist/types/types.d.ts

@@ -0,0 +1,340 @@
+/**
+ * Public types of the Mr Charles booking API.
+ * Mirrors apps/backend-api/internal/sites/dto.go and the lesson DTOs; the
+ * API adds fields without notice but never removes or renames one within v1.
+ */
+import type { HostedLocale, Locale } from './i18n';
+export type { HostedLocale, Locale, LocaleInput } from './i18n';
+/** Per-language strings from the site payload: `{ es, ca, en }`. Use `pick()` to read one. */
+export type Localized = Partial<Record<HostedLocale, string>>;
+export type PaymentMode = 'card' | 'on_site';
+export type Channel = 'phone' | 'email';
+export interface OperatingHours {
+    /** 0–6, Sunday–Saturday */
+    dayOfWeek: number;
+    openTime: string;
+    closeTime: string;
+    isClosed: boolean;
+}
+export interface PublicStudio {
+    name: string;
+    slug: string;
+    description: string;
+    shortDescription: string | null;
+    studioType: string | null;
+    logoUrl: string | null;
+    coverImageUrl: string | null;
+    addressLine1: string;
+    addressLine2: string | null;
+    city: string;
+    postalCode: string;
+    country: string;
+    latitude: number | null;
+    longitude: number | null;
+    phone: string | null;
+    email: string;
+    website: string | null;
+    /** IANA zone. Every date and time of this studio belongs to it. */
+    timezone: string;
+    isVerified: boolean;
+    averageRating: number | null;
+    totalReviews: number;
+    operatingHours: OperatingHours[];
+    socialLinks: {
+        platform: string;
+        url: string;
+    }[];
+    amenities: {
+        name: string;
+        category: string;
+    }[];
+}
+export interface Equipment {
+    name: string;
+    category: string;
+    brand: string | null;
+    model: string | null;
+    quantity: number;
+}
+export interface PublicRoom {
+    id: string;
+    name: string;
+    description: string | null;
+    capacity: number;
+    roomType: string | null;
+    /** Minor units: 2500 = €25.00 per hour */
+    hourlyCents: number;
+    currency: string;
+    /** Only these rooms accept online bookings */
+    bookable: boolean;
+    minMinutes: number;
+    maxMinutes: number;
+    stepMinutes: number;
+    paymentModes: PaymentMode[];
+    depositPercent: number;
+    cancelNoticeHours: number;
+    instructions: Localized;
+    photos: string[];
+    equipment: Equipment[];
+    facilities: string[];
+}
+export interface PublicSiteConfig {
+    template: string;
+    theme: {
+        primary: string;
+        accent: string;
+        font: string;
+        radius: string;
+        mode?: string;
+        logoUrl: string | null;
+    };
+    sections: Record<string, boolean>;
+    content: {
+        tagline: Localized;
+        about: Localized;
+        bookingNote: Localized;
+        whatsapp: string;
+        instagram: string;
+        gallery: string[];
+    };
+    legal: {
+        legalName: string;
+        taxId: string;
+        address: string;
+        email: string;
+        phone: string;
+    };
+    seo: {
+        title: string;
+        description: string;
+    };
+    defaultLocale: HostedLocale;
+    locales: HostedLocale[];
+    status: string;
+    customDomain: string | null;
+    canonicalHost: string;
+    /**
+     * Sandbox: this site exists for testing. Codes come back as `hold.devCode`,
+     * nothing is sent to anyone, card payments are off and bookings are purged
+     * after seven days. Tell the guest.
+     */
+    sandbox: boolean;
+}
+export interface PublicSite {
+    studio: PublicStudio;
+    rooms: PublicRoom[];
+    site: PublicSiteConfig;
+    /** At least one room is bookable online */
+    bookingOnline: boolean;
+    cardPayments: boolean;
+    /** Present when holds require a Turnstile token */
+    captchaSiteKey?: string;
+    /** Present when card deposits are possible — use it to mount Stripe */
+    stripePublishableKey?: string;
+}
+/** A continuous free span, "HH:MM" in the studio's zone. "24:00" is a valid end. */
+export interface FreeSpan {
+    start: string;
+    end: string;
+}
+export interface DayAvailability {
+    /** YYYY-MM-DD */
+    date: string;
+    free: FreeSpan[];
+}
+export interface RoomAvailability {
+    roomId: string;
+    timezone: string;
+    hourlyCents: number;
+    currency: string;
+    minMinutes: number;
+    maxMinutes: number;
+    stepMinutes: number;
+    minNoticeMin: number;
+    maxAdvanceDays: number;
+    days: DayAvailability[];
+}
+export interface HoldRequest {
+    roomId: string;
+    /** YYYY-MM-DD in the studio's zone */
+    date: string;
+    /** HH:MM in the studio's zone */
+    startTime: string;
+    durationMinutes: number;
+    guestName: string;
+    channel: Channel;
+    /** E.164 phone (+34…) when channel is phone; an address when email */
+    contact: string;
+    /** Language of the code, confirmation and reminders. Hosted locales only; the SDK maps others for you. */
+    locale?: HostedLocale | Locale;
+    /** One per attempt; reuse it when retrying the same request */
+    idempotencyKey: string;
+    /** Required when the site payload has captchaSiteKey */
+    captchaToken?: string;
+}
+export interface Price {
+    priceCents: number;
+    /** What a card payment charges now */
+    depositCents: number;
+    currency: string;
+    minutes: number;
+}
+export interface Hold {
+    holdId: string;
+    status: string;
+    roomId: string;
+    roomName: string;
+    date: string;
+    startTime: string;
+    endTime: string;
+    timezone: string;
+    price: Price;
+    channel: Channel;
+    contactMasked: string;
+    /** ISO instant; the slot is yours until then (12 minutes) */
+    expiresAt: string;
+    resendsLeft: number;
+    paymentModes: PaymentMode[];
+    /** Only on sandbox sites: the code that would have been sent. */
+    devCode?: string;
+}
+export interface ConfirmRequest {
+    /** Must be one of hold.paymentModes */
+    paymentMode: PaymentMode;
+    /** Shown to the studio */
+    notes?: string;
+    /** Optional second contact for the receipt */
+    email?: string;
+}
+export interface Booking {
+    id: string;
+    reference: string;
+    status: 'confirmed' | 'pending_payment' | 'cancelled' | 'completed' | 'no_show' | string;
+    paymentMode: PaymentMode;
+    paymentStatus: string;
+    studioName: string;
+    roomName: string;
+    guestName: string;
+    date: string;
+    startTime: string;
+    endTime: string;
+    timezone: string;
+    startsAt: string;
+    endsAt: string;
+    minutes: number;
+    priceCents: number;
+    depositCents: number;
+    currency: string;
+    cancelNoticeHours: number;
+    mayCancel: boolean;
+    notes: string | null;
+    paymentDueAt: string | null;
+    createdAt: string;
+}
+export interface Confirmation {
+    booking: Booking;
+    /** Keep it if you build your own manage screen */
+    manageToken: string;
+    /** Hand it to the guest — the only way back to the booking */
+    manageUrl: string;
+    /** Stripe PaymentIntent secret, when paymentMode is card */
+    clientSecret?: string;
+}
+export interface Money {
+    /** Minor units */
+    amount: number;
+    currency: string;
+}
+export interface TeacherProfile {
+    /** Instructor *profile* id — not what the booking endpoints want */
+    id: string;
+    /** user.id is the id for availability, slots and the booking link */
+    user: {
+        id: string;
+        displayName: string;
+        username: string;
+        avatarUrl: string | null;
+    };
+    headline: string | null;
+    bio: string;
+    teachingPhilosophy: string | null;
+    hourlyRate: Money;
+    experienceYears: number;
+    teachesOnline: boolean;
+    teachesInPerson: boolean;
+    instruments: {
+        instrument: string;
+        skillLevel?: string;
+        [k: string]: unknown;
+    }[];
+    genres: string[];
+    teachingSpecialties: string[];
+    audienceLevels: string[];
+    languages: string[];
+    locationDisplay: string | null;
+    teachingSinceYear: number | null;
+    averageRating: number | null;
+    totalReviews: number;
+    totalStudents: number;
+    totalLessons: number;
+    isVerified: boolean;
+    createdAt: string;
+}
+export interface LessonOffer {
+    id: string;
+    /** Instructor *profile* id (see TeacherProfile.id) */
+    instructorId: string;
+    title: string;
+    description: string;
+    instrument: string;
+    audienceLevels: string[];
+    price: Money;
+    durationMinutes: number;
+    format: 'online' | 'in_person' | 'both' | string;
+    maxParticipants: number;
+    publishedAt: string | null;
+}
+export interface LessonPolicy {
+    minNoticeMin: number;
+    maxAdvanceDays: number;
+    slotGranularityMin: number;
+    rescheduleMinNoticeMin: number;
+    rescheduleMaxPerBooking: number;
+}
+export interface LessonSlot {
+    date: string;
+    /** HH:MM in the teacher's zone */
+    startTime: string;
+    endTime: string;
+}
+export interface LessonSlots {
+    instructorId: string;
+    offerId: string;
+    timezone: string;
+    durationMinutes: number;
+    days: {
+        date: string;
+        slots: LessonSlot[];
+    }[];
+    policy?: LessonPolicy;
+}
+export interface TeacherWindows {
+    timezone: string;
+    windows: {
+        date: string;
+        startTime: string;
+        endTime: string;
+    }[];
+}
+export interface EmbedBookedEvent {
+    type: 'mrcharles:booked';
+    reference: string;
+    bookingId: string;
+    manageUrl: string;
+    status: string;
+}
+export interface EmbedResizeEvent {
+    type: 'mrcharles:resize';
+    height: number;
+}
+export type EmbedEvent = EmbedBookedEvent | EmbedResizeEvent;

package/dist/types/uuid.d.ts

@@ -0,0 +1,2 @@
+/** RFC 4122 v4, with a fallback for runtimes without crypto.randomUUID. */
+export declare function uuid(): string;

package/package.json

@@ -1,6 +1,57 @@
 {
   "name": "@mrcharles/sdk",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "Mr Charles booking SDK \u2014 put studio room bookings and teacher lessons on any website.",
+  "license": "MIT",
+  "homepage": "https://developers.mrcharles.app/integrate/sdk/",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/oryontech-ou/mrcharles.git",
+    "directory": "packages/sdk"
+  },
+  "keywords": [
+    "mrcharles",
+    "booking",
+    "studio",
+    "music",
+    "lessons",
+    "sdk"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/mrcharles.esm.js",
+  "module": "./dist/mrcharles.esm.js",
+  "types": "./dist/types/index.d.ts",
+  "unpkg": "./dist/mrcharles.min.js",
+  "jsdelivr": "./dist/mrcharles.min.js",
+  "exports": {
+    ".": {
+      "types": "./dist/types/index.d.ts",
+      "import": "./dist/mrcharles.esm.js",
+      "default": "./dist/mrcharles.esm.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "rm -rf dist && bun build src/index.ts --target=browser --format=esm --outdir=dist --entry-naming='mrcharles.esm.[ext]' --sourcemap=linked && bun build src/global.ts --target=browser --format=iife --minify --outdir=dist --entry-naming='mrcharles.min.[ext]' --sourcemap=linked && tsc -p tsconfig.build.json",
+    "test": "bun test",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.0.0",
+    "typescript": "^5.9.3"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "nx": {
+    "tags": [
+      "scope:sdk"
+    ]
+  }
+}