@cosmoops/connect-sdk 0.16.1 → 0.18.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,107 @@
1
+ "use client";
2
+ import { useCallback, useMemo, useState } from "react";
3
+ import { useConnect, useConnectResource } from "./provider.js";
4
+ /**
5
+ * The bridge's scheduling surface, as hooks.
6
+ *
7
+ * Every path here is one of the six the bridge exposes, and every one of them
8
+ * is resolved *for the signed-in member* - Connect takes the workspace from
9
+ * their session and checks their own `calendar:read` / `calendar:manage`.
10
+ * Nothing in this file names a workspace, and nothing should: a browser that
11
+ * can name a tenant is a browser that can read someone else's diary.
12
+ */
13
+ /** What this workspace offers as bookable. Active types only. */
14
+ export function useBookableEventTypes() {
15
+ const { data, isLoading, error } = useConnectResource("/scheduling/event-types");
16
+ return { eventTypes: data?.eventTypes ?? [], isLoading, error };
17
+ }
18
+ /**
19
+ * Free times for one appointment type.
20
+ *
21
+ * **Deliberately re-read rather than cached across a session.** A slot list is
22
+ * a snapshot of contention: anyone else on that calendar - a colleague, a
23
+ * voice agent mid-call, someone on the public booking link - can take one
24
+ * between the read and the click. Showing a stale one is how two people are
25
+ * offered the same minute. The booking call re-checks inside a transaction
26
+ * anyway, so a stale list costs a refusal rather than a double booking; this
27
+ * just means the refusal is rare.
28
+ */
29
+ export function useAvailableSlots(query) {
30
+ const path = query
31
+ ? `/scheduling/slots?${new URLSearchParams({
32
+ eventTypeId: query.eventTypeId,
33
+ from: query.from.toISOString(),
34
+ to: query.to.toISOString(),
35
+ ...(query.excludeBookingId ? { excludeBookingId: query.excludeBookingId } : {}),
36
+ }).toString()}`
37
+ : null;
38
+ // `useConnectResource` needs a path; an empty one never resolves, so the
39
+ // hook is called unconditionally (rules of hooks) and simply idles.
40
+ const { data, isLoading, error, refetch } = useConnectResource(path ?? "");
41
+ return {
42
+ slots: path ? (data?.slots ?? []) : [],
43
+ timezone: data?.timezone ?? null,
44
+ durationMinutes: data?.durationMinutes ?? null,
45
+ isLoading: path ? isLoading : false,
46
+ error: path ? error : null,
47
+ refetch,
48
+ };
49
+ }
50
+ /** One page of the diary, ascending - a forward view, not a history. */
51
+ export function useBookings(query) {
52
+ const path = useMemo(() => `/scheduling/bookings?${new URLSearchParams({
53
+ from: query.from.toISOString(),
54
+ to: query.to.toISOString(),
55
+ order: "asc",
56
+ status: "confirmed",
57
+ limit: String(query.limit ?? 100),
58
+ ...(query.hostMemberId ? { hostMemberId: query.hostMemberId } : {}),
59
+ }).toString()}`, [query.from, query.to, query.hostMemberId, query.limit]);
60
+ const { data, isLoading, error, refetch } = useConnectResource(path);
61
+ return {
62
+ bookings: data?.bookings ?? [],
63
+ hasMore: data?.hasMore ?? false,
64
+ isLoading,
65
+ error,
66
+ path,
67
+ refetch,
68
+ };
69
+ }
70
+ /**
71
+ * Book, move and cancel.
72
+ *
73
+ * **None of these is optimistic**, and that is not an oversight. Whether a
74
+ * slot is still free is a question only the server can answer, inside the
75
+ * transaction that decides it - two people can be holding the same minute
76
+ * right now. Painting a booking as made and withdrawing it is exactly the lie
77
+ * the two-phase hold exists to prevent.
78
+ */
79
+ export function useBookingActions() {
80
+ const { mutateResource } = useConnect();
81
+ const [isPending, setPending] = useState(false);
82
+ const [error, setError] = useState(null);
83
+ const run = useCallback(async (path, body) => {
84
+ setPending(true);
85
+ setError(null);
86
+ try {
87
+ return await mutateResource(path, body);
88
+ }
89
+ catch (cause) {
90
+ // The server writes these as sentences - "that time was just taken" -
91
+ // precisely so they can be shown rather than mapped to a code.
92
+ setError(cause instanceof Error ? cause.message : "Something went wrong.");
93
+ return null;
94
+ }
95
+ finally {
96
+ setPending(false);
97
+ }
98
+ }, [mutateResource]);
99
+ return {
100
+ isPending,
101
+ error,
102
+ clearError: () => setError(null),
103
+ createBooking: (input) => run("/scheduling/bookings", input),
104
+ rescheduleBooking: (input) => run("/scheduling/bookings/reschedule", input).then((result) => result?.booking ?? null),
105
+ cancelBooking: (input) => run("/scheduling/bookings/cancel", input),
106
+ };
107
+ }
@@ -3,6 +3,7 @@ import { AppsResource } from "./resources/apps.js";
3
3
  import { AiResource } from "./resources/ai.js";
4
4
  import { DataResource, storePassthrough } from "./resources/data.js";
5
5
  import { WorkspacesResource } from "./resources/workspaces.js";
6
+ import { SchedulingResource } from "./resources/scheduling.js";
6
7
  import { KvResource } from "./resources/kv.js";
7
8
  import { BillingResource } from "./resources/billing.js";
8
9
  import { DriveResource } from "./resources/drive.js";
@@ -76,6 +77,8 @@ export class ConnectClient {
76
77
  billing;
77
78
  /** Files in a workspace's Drive. */
78
79
  drive;
80
+ /** A subscribing workspace's own calendar - what is bookable, free, and booked. */
81
+ scheduling;
79
82
  /** RAG chat and structured extraction. */
80
83
  ai;
81
84
  /** Your application's own document store - see `DataResource`. */
@@ -124,6 +127,7 @@ export class ConnectClient {
124
127
  this.entitlements = new EntitlementsResource(transport);
125
128
  this.billing = new BillingResource(transport);
126
129
  this.drive = new DriveResource(transport);
130
+ this.scheduling = new SchedulingResource(transport);
127
131
  this.ai = new AiResource(transport);
128
132
  this.data = new DataResource(transport);
129
133
  this.kv = new KvResource(transport);
@@ -138,4 +142,4 @@ export class ConnectClient {
138
142
  }
139
143
  }
140
144
  /** Kept in step with `package.json` by `sdk.test.ts`. */
141
- export const SDK_VERSION = "0.16.1";
145
+ export const SDK_VERSION = "0.18.0";
@@ -412,6 +412,142 @@ export function createConnectHandler(options) {
412
412
  await session.write?.(request, response, result.sessionToken);
413
413
  return response;
414
414
  },
415
+ /*
416
+ * Scheduling - the workspace's own calendar, in a browser.
417
+ *
418
+ * Every one of these forwards the caller's session token, which is what
419
+ * makes them safe to expose: Connect derives the workspace from that token
420
+ * and checks the member's own `calendar:read` / `calendar:manage`. The
421
+ * browser names no tenant and the partner's key does not, by itself,
422
+ * authorize a write - without that second half, shipping a booking
423
+ * component would let every end user of every partner app take slots on a
424
+ * real business calendar.
425
+ *
426
+ * `workspaceId` is still passed because the resource requires it, and is
427
+ * still ignored by Connect whenever a token is present. `requireWorkspace`
428
+ * supplies the session's own, so the two can never disagree.
429
+ */
430
+ "GET /scheduling/event-types": async (request) => {
431
+ const { workspaceId } = await requireWorkspace(request);
432
+ const asUser = await requireToken(request);
433
+ return json({ eventTypes: await client.scheduling.listEventTypes(workspaceId, { asUser }) });
434
+ },
435
+ "GET /scheduling/slots": async (request) => {
436
+ const { workspaceId } = await requireWorkspace(request);
437
+ const asUser = await requireToken(request);
438
+ const url = new URL(request.url);
439
+ const eventTypeId = url.searchParams.get("eventTypeId");
440
+ const from = url.searchParams.get("from");
441
+ const to = url.searchParams.get("to");
442
+ if (!eventTypeId || !from || !to) {
443
+ throw new ConnectError({
444
+ status: 400,
445
+ code: "validation_error",
446
+ message: "eventTypeId, from and to are required",
447
+ endpoint: "/scheduling/slots",
448
+ });
449
+ }
450
+ return json(await client.scheduling.findSlots({
451
+ workspaceId,
452
+ eventTypeId,
453
+ from,
454
+ to,
455
+ // Set when offering times to move an existing appointment to, or the
456
+ // booking blocks its own replacement and the list comes back empty.
457
+ excludeBookingId: url.searchParams.get("excludeBookingId") ?? undefined,
458
+ asUser,
459
+ }));
460
+ },
461
+ "GET /scheduling/bookings": async (request) => {
462
+ const { workspaceId } = await requireWorkspace(request);
463
+ const asUser = await requireToken(request);
464
+ const url = new URL(request.url);
465
+ const limit = Number(url.searchParams.get("limit") ?? 25);
466
+ return json(await client.scheduling.listBookings({
467
+ workspaceId,
468
+ status: url.searchParams.get("status") ?? undefined,
469
+ hostMemberId: url.searchParams.get("hostMemberId") ?? undefined,
470
+ from: url.searchParams.get("from") ?? undefined,
471
+ to: url.searchParams.get("to") ?? undefined,
472
+ order: url.searchParams.get("order") === "asc" ? "asc" : "desc",
473
+ cursor: url.searchParams.get("cursor") ?? undefined,
474
+ limit: Number.isInteger(limit) && limit >= 1 && limit <= 100 ? limit : 25,
475
+ asUser,
476
+ }));
477
+ },
478
+ "POST /scheduling/bookings": async (request) => {
479
+ const { workspaceId } = await requireWorkspace(request);
480
+ const asUser = await requireToken(request);
481
+ const body = (await request.json().catch(() => null));
482
+ if (typeof body?.eventTypeId !== "string" ||
483
+ typeof body.startAt !== "string" ||
484
+ typeof body.attendee?.name !== "string" ||
485
+ typeof body.attendee?.phone !== "string") {
486
+ throw new ConnectError({
487
+ status: 400,
488
+ code: "validation_error",
489
+ message: "eventTypeId, startAt and an attendee name and phone are required",
490
+ endpoint: "/scheduling/bookings",
491
+ });
492
+ }
493
+ return json(await client.scheduling.createBooking({
494
+ workspaceId,
495
+ eventTypeId: body.eventTypeId,
496
+ startAt: body.startAt,
497
+ attendee: {
498
+ name: body.attendee.name,
499
+ phone: body.attendee.phone,
500
+ email: typeof body.attendee.email === "string" ? body.attendee.email : null,
501
+ },
502
+ notes: typeof body.notes === "string" ? body.notes : null,
503
+ asUser,
504
+ }));
505
+ },
506
+ /*
507
+ * Reschedule and cancel take the booking id in the body rather than the
508
+ * path, matching `POST /sessions/revoke`. The bridge's route table is
509
+ * exact-match on `METHOD /path`, so a path parameter would mean a second
510
+ * matching strategy for two routes.
511
+ */
512
+ "POST /scheduling/bookings/reschedule": async (request) => {
513
+ const { workspaceId } = await requireWorkspace(request);
514
+ const asUser = await requireToken(request);
515
+ const body = (await request.json().catch(() => null));
516
+ if (typeof body?.bookingId !== "string" || typeof body.startAt !== "string") {
517
+ throw new ConnectError({
518
+ status: 400,
519
+ code: "validation_error",
520
+ message: "bookingId and startAt are required",
521
+ endpoint: "/scheduling/bookings/reschedule",
522
+ });
523
+ }
524
+ return json(await client.scheduling.rescheduleBooking({
525
+ workspaceId,
526
+ bookingId: body.bookingId,
527
+ startAt: body.startAt,
528
+ notes: typeof body.notes === "string" ? body.notes : undefined,
529
+ asUser,
530
+ }));
531
+ },
532
+ "POST /scheduling/bookings/cancel": async (request) => {
533
+ const { workspaceId } = await requireWorkspace(request);
534
+ const asUser = await requireToken(request);
535
+ const body = (await request.json().catch(() => null));
536
+ if (typeof body?.bookingId !== "string") {
537
+ throw new ConnectError({
538
+ status: 400,
539
+ code: "validation_error",
540
+ message: "bookingId is required",
541
+ endpoint: "/scheduling/bookings/cancel",
542
+ });
543
+ }
544
+ return json(await client.scheduling.cancelBooking({
545
+ workspaceId,
546
+ bookingId: body.bookingId,
547
+ reason: typeof body.reason === "string" ? body.reason : null,
548
+ asUser,
549
+ }));
550
+ },
415
551
  "GET /integrations": async (request) => {
416
552
  const { workspaceId } = await requireWorkspace(request);
417
553
  return json({ toolkits: await client.integrations.list(workspaceId) });
@@ -0,0 +1,149 @@
1
+ import { request } from "../http.js";
2
+ import { actingAs } from "./acting-as.js";
3
+ /**
4
+ * A subscribing workspace's own calendar.
5
+ *
6
+ * **There is one calendar, not one per application.** A booking made here
7
+ * appears on the workspace's own screen immediately, and a slot their
8
+ * receptionist just took is gone from your next `findSlots`. That is the
9
+ * reason to read it through Connect rather than keeping a copy: two calendars
10
+ * double-book, and nothing reconciles them afterwards.
11
+ *
12
+ * Every method needs a live subscription to your application in the workspace
13
+ * you name. The key says which application is calling; the subscription is
14
+ * what makes you welcome in a given tenant.
15
+ */
16
+ export class SchedulingResource {
17
+ transport;
18
+ constructor(transport) {
19
+ this.transport = transport;
20
+ }
21
+ /** What this workspace offers as bookable. Active appointment types only. */
22
+ async listEventTypes(workspaceId, options = {}) {
23
+ const result = await request(this.transport, {
24
+ method: "GET",
25
+ path: "/scheduling/event-types",
26
+ query: { workspaceId },
27
+ headers: actingAs(options.asUser),
28
+ });
29
+ // `?? []` for the same reason `apps.list` has it - a collection every
30
+ // caller immediately maps, and a body without the key would hand them
31
+ // `undefined` past every status check in between.
32
+ return result.eventTypes ?? [];
33
+ }
34
+ /**
35
+ * Free times for one appointment type over one window.
36
+ *
37
+ * **Advisory by construction.** Between this answer and `createBooking`,
38
+ * anyone else on that calendar can take any of these - a member, a voice
39
+ * agent mid-call, someone on the workspace's public booking link. That is
40
+ * why `createBooking` can answer `409`, and why that is an ordinary outcome
41
+ * rather than a fault.
42
+ *
43
+ * The window is clamped silently to now and to the appointment type's own
44
+ * booking horizon, so asking for a year of a sixty-day type returns sixty
45
+ * days rather than an error.
46
+ */
47
+ findSlots(input) {
48
+ return request(this.transport, {
49
+ method: "GET",
50
+ path: "/scheduling/slots",
51
+ query: {
52
+ workspaceId: input.workspaceId,
53
+ eventTypeId: input.eventTypeId,
54
+ from: toInstant(input.from),
55
+ to: toInstant(input.to),
56
+ excludeBookingId: input.excludeBookingId,
57
+ },
58
+ headers: actingAs(input.asUser),
59
+ });
60
+ }
61
+ /** One page of the workspace's diary. */
62
+ listBookings(input) {
63
+ return request(this.transport, {
64
+ method: "GET",
65
+ path: "/scheduling/bookings",
66
+ query: {
67
+ workspaceId: input.workspaceId,
68
+ status: input.status,
69
+ hostMemberId: input.hostMemberId,
70
+ from: input.from ? toInstant(input.from) : undefined,
71
+ to: input.to ? toInstant(input.to) : undefined,
72
+ order: input.order,
73
+ cursor: input.cursor,
74
+ limit: input.limit === undefined ? undefined : String(input.limit),
75
+ },
76
+ headers: actingAs(input.asUser),
77
+ });
78
+ }
79
+ /**
80
+ * Takes one of the times `findSlots` offered.
81
+ *
82
+ * Holds and confirms in one call - you already have the attendee, so there
83
+ * is no half-finished state for your integration to remember. The slot is
84
+ * re-checked inside a transaction, so a time taken since you read it throws
85
+ * a `ConnectError` with `code: "conflict"` rather than double-booking.
86
+ */
87
+ createBooking(input) {
88
+ return request(this.transport, {
89
+ method: "POST",
90
+ path: "/scheduling/bookings",
91
+ json: {
92
+ workspaceId: input.workspaceId,
93
+ eventTypeId: input.eventTypeId,
94
+ startAt: toInstant(input.startAt),
95
+ attendee: input.attendee,
96
+ notes: input.notes ?? null,
97
+ },
98
+ headers: actingAs(input.asUser),
99
+ });
100
+ }
101
+ /**
102
+ * Moves an appointment to a different time.
103
+ *
104
+ * **The original is retired, not edited.** It stays on the diary as
105
+ * `rescheduled` with `rescheduledToId` pointing at the replacement, and both
106
+ * come back here - so a booking id you cached still resolves, and still says
107
+ * where the appointment went.
108
+ *
109
+ * A refused move changes nothing: the new slot is claimed before the old one
110
+ * is released, so a `conflict` leaves the customer with the appointment they
111
+ * already had. Re-read the slots (with `excludeBookingId`) and offer another.
112
+ */
113
+ rescheduleBooking(input) {
114
+ return request(this.transport, {
115
+ method: "POST",
116
+ path: `/scheduling/bookings/${encodeURIComponent(input.bookingId)}/reschedule`,
117
+ json: {
118
+ workspaceId: input.workspaceId,
119
+ startAt: toInstant(input.startAt),
120
+ notes: input.notes ?? null,
121
+ },
122
+ headers: actingAs(input.asUser),
123
+ });
124
+ }
125
+ /**
126
+ * Frees the slot and records why.
127
+ *
128
+ * Not a deletion: the booking stays on the diary as `cancelled` with the
129
+ * reason, which is what makes a late cancellation something anyone can look
130
+ * up afterwards.
131
+ */
132
+ cancelBooking(input) {
133
+ return request(this.transport, {
134
+ method: "POST",
135
+ path: `/scheduling/bookings/${encodeURIComponent(input.bookingId)}/cancel`,
136
+ json: { workspaceId: input.workspaceId, reason: input.reason ?? null },
137
+ headers: actingAs(input.asUser),
138
+ });
139
+ }
140
+ }
141
+ /**
142
+ * A `Date` or an already-ISO string, as the ISO-8601 instant the API takes.
143
+ *
144
+ * `toISOString()` rather than any local formatting: these are instants, and a
145
+ * wall time without a zone is the one input this API cannot interpret.
146
+ */
147
+ function toInstant(value) {
148
+ return typeof value === "string" ? value : value.toISOString();
149
+ }
@@ -0,0 +1,38 @@
1
+ import { type GridWindow } from "./booking-grid.js";
2
+ export interface ConnectBookingCalendarProps {
3
+ /**
4
+ * The business's IANA timezone. **Every instant on the grid is read against
5
+ * it, never the viewer's** - a workspace's working day must not shift
6
+ * because a member is travelling.
7
+ *
8
+ * Defaults to the host's zone, which is right for the common case where
9
+ * staff and business share one. Pass it explicitly when they might not.
10
+ */
11
+ timeZone?: string;
12
+ /** Only appointments this member hosts. Omit for the whole workspace's diary. */
13
+ hostMemberId?: string;
14
+ /** Narrow the visible band - see `DEFAULT_WINDOW`. */
15
+ window?: GridWindow;
16
+ /** Hide the "New appointment" action for a read-only view. */
17
+ canBook?: boolean;
18
+ className?: string;
19
+ }
20
+ /**
21
+ * A week of the workspace's calendar, with booking, rescheduling and
22
+ * cancelling.
23
+ *
24
+ * **Two views, and which one you get is a viewport decision, not a
25
+ * preference.** A seven-column time grid needs roughly 640px before a column
26
+ * is wide enough to hold a name; below that it degrades into unreadable
27
+ * slivers. So the grid is `sm:` and up, and the same week renders as a grouped
28
+ * agenda underneath - not a cut-down grid, a different and better shape for a
29
+ * phone. Both read the same data and open the same dialogs.
30
+ *
31
+ * Everything it does goes through the bridge as the signed-in member, so
32
+ * Connect checks *their* `calendar:read` / `calendar:manage` rather than the
33
+ * host application's key. A member who may look but not book gets the grid and
34
+ * a refusal on the write, which is the correct shape - see `useBookingActions`.
35
+ */
36
+ export declare function ConnectBookingCalendar({ timeZone, hostMemberId, window: visibleWindow, canBook, className, }: Readonly<ConnectBookingCalendarProps>): import("react").JSX.Element;
37
+ declare function timeLabel(instant: Date, zone: string): string;
38
+ export { timeLabel as connectBookingTimeLabel };
@@ -0,0 +1,33 @@
1
+ import type { BookableEventType, Booking } from "../../types.js";
2
+ /**
3
+ * Picking a time, and then who it is for.
4
+ *
5
+ * The slot list is read fresh every time this opens and is **never cached
6
+ * across an open**: it is a snapshot of contention, and offering a time
7
+ * somebody took ninety seconds ago is how two people end up in the same slot.
8
+ * The server re-checks inside its transaction regardless, so a stale list
9
+ * costs a refusal rather than a double booking - this only makes the refusal
10
+ * rare enough to be surprising when it happens.
11
+ */
12
+ export declare function ConnectBookingDialog({ isOpen, onOpenChange, eventTypes, initialStartAt, timeZone, onBooked, }: Readonly<{
13
+ isOpen: boolean;
14
+ onOpenChange(open: boolean): void;
15
+ eventTypes: BookableEventType[];
16
+ initialStartAt: Date;
17
+ timeZone: string;
18
+ onBooked(booking: Booking): void;
19
+ }>): import("react").JSX.Element;
20
+ /**
21
+ * One appointment, and the two things anyone opens it to do.
22
+ *
23
+ * Rescheduling re-reads the slots with `excludeBookingId` set to this booking.
24
+ * Without that the appointment blocks its own replacement, and moving it by
25
+ * half an hour - the only move most people ever make - offers nothing.
26
+ */
27
+ export declare function ConnectBookingDetail({ booking, eventType, timeZone, onOpenChange, onChanged, }: Readonly<{
28
+ booking: Booking;
29
+ eventType: BookableEventType | null;
30
+ timeZone: string;
31
+ onOpenChange(open: boolean): void;
32
+ onChanged(): void;
33
+ }>): import("react").JSX.Element;
@@ -0,0 +1,102 @@
1
+ import type { Booking } from "../../types.js";
2
+ /**
3
+ * The arithmetic behind the week grid, with no React and no fetching - the
4
+ * same split `slot-computation.ts` uses server-side, and for the same reason:
5
+ * every timezone and overlap rule is then testable without rendering
6
+ * anything, and a layout bug is a failing assertion rather than a screenshot
7
+ * somebody has to notice.
8
+ *
9
+ * **Every instant is read against the business's timezone**, never the
10
+ * viewer's. A workspace in Kolkata whose staff are travelling must not see
11
+ * their own working day shift; the grid is a picture of when *the business* is
12
+ * open. That is why every function here takes an explicit `timeZone` rather
13
+ * than falling back to the host's.
14
+ */
15
+ export interface ZonedInstant {
16
+ /** `YYYY-MM-DD` in `timeZone` - the local calendar day this instant falls on. */
17
+ dateKey: string;
18
+ /** Minutes since local midnight, `0`-`1439`. */
19
+ minutes: number;
20
+ }
21
+ /**
22
+ * An instant, as the local day and minute it lands on in `timeZone`.
23
+ *
24
+ * Built from `formatToParts` rather than by adding a fixed offset. An offset
25
+ * is only correct until a DST boundary, and "add 5.5 hours" is wrong the
26
+ * moment the same code is pointed at a zone that observes one - which is
27
+ * exactly the kind of bug that appears twice a year and never in a test.
28
+ */
29
+ export declare function zonedInstant(instant: Date, timeZone: string): ZonedInstant;
30
+ export interface DayColumn {
31
+ /** `YYYY-MM-DD` in the grid's timezone. */
32
+ dateKey: string;
33
+ /** "Mon 8" - the column heading. */
34
+ label: string;
35
+ /** "Sep" etc, for the first column and any month change. */
36
+ monthLabel: string;
37
+ /** Midnight of this day, as an instant. Used to build slot query windows. */
38
+ startsAt: Date;
39
+ isToday: boolean;
40
+ }
41
+ /**
42
+ * `count` consecutive days starting at the local day `anchor` falls on.
43
+ *
44
+ * Days are stepped by adding 24 hours and re-reading the zone rather than by
45
+ * incrementing a date field, so a day that is 23 or 25 hours long still
46
+ * produces the right sequence of `dateKey`s - the midday anchor is what keeps
47
+ * a DST shift from landing the step on the previous or next day.
48
+ */
49
+ export declare function dayColumns(anchor: Date, timeZone: string, count: number, now: Date): DayColumn[];
50
+ /**
51
+ * Local midnight of `dateKey` in `timeZone`, as an instant.
52
+ *
53
+ * Solved by probing rather than by arithmetic: guess UTC midnight, read what
54
+ * local time that actually is, and subtract the difference. One correction is
55
+ * always enough because a zone's offset cannot change within the few hours the
56
+ * correction spans - and unlike a fixed-offset formula it is right across DST
57
+ * and for the half-hour zones (`Asia/Kolkata`, `Australia/Adelaide`) that a
58
+ * naive implementation quietly breaks on.
59
+ */
60
+ export declare function dayStartInstant(dateKey: string, timeZone: string): Date;
61
+ export interface PositionedBooking {
62
+ booking: Booking;
63
+ dateKey: string;
64
+ /** Fraction of the visible day, `0`-`1`, from the top of the grid. */
65
+ top: number;
66
+ /** Fraction of the visible day. Never `0` - see `MIN_VISIBLE_FRACTION`. */
67
+ height: number;
68
+ /** Column index within its overlap cluster, and how many columns that cluster has. */
69
+ column: number;
70
+ columns: number;
71
+ /** True when the appointment extends past the grid's visible window. */
72
+ clipped: boolean;
73
+ }
74
+ export interface GridWindow {
75
+ /** Minutes since local midnight the grid starts at - `480` is 08:00. */
76
+ startMinute: number;
77
+ endMinute: number;
78
+ }
79
+ /**
80
+ * Places bookings on the grid, side by side where they collide.
81
+ *
82
+ * Overlap handling is the part worth stating. Two appointments at the same
83
+ * time are not an error - a workspace with two hosts has them constantly - and
84
+ * stacking them would hide one entirely. So overlapping bookings are grouped
85
+ * into *clusters* and each cluster is split into equal columns. The cluster is
86
+ * built transitively: A overlapping B and B overlapping C puts all three in one
87
+ * cluster even when A and C do not touch, because anything else lets two of
88
+ * them land on the same column.
89
+ */
90
+ export declare function layoutBookings(bookings: Booking[], timeZone: string, window: GridWindow): PositionedBooking[];
91
+ /**
92
+ * The hour labels down the left edge, inclusive of both ends.
93
+ *
94
+ * Takes no timezone, deliberately: these label *wall-clock hours on the grid*,
95
+ * not instants. The grid is already drawn in the business's zone, so "10 am"
96
+ * means the business's ten - running the label through a zone conversion would
97
+ * shift it away from the row it sits on.
98
+ */
99
+ export declare function hourMarks(window: GridWindow): {
100
+ minute: number;
101
+ label: string;
102
+ }[];
@@ -87,3 +87,8 @@ export type { PlanAction, PlanTier, ComparablePlan } from "./components/plan-pri
87
87
  export { ConnectWorkspaceSwitcher } from "./components/workspace-switcher.js";
88
88
  export type { ConnectWorkspaceSwitcherProps } from "./components/workspace-switcher.js";
89
89
  export { useConnectWorkspaces, useConnectWorkspaceMembers } from "./provider.js";
90
+ export { ConnectBookingCalendar } from "./components/booking-calendar.js";
91
+ export type { ConnectBookingCalendarProps } from "./components/booking-calendar.js";
92
+ export { ConnectBookingDialog, ConnectBookingDetail } from "./components/booking-dialogs.js";
93
+ export { useBookableEventTypes, useAvailableSlots, useBookings, useBookingActions, type SlotQuery, type BookingsQuery, } from "./use-scheduling.js";
94
+ export { layoutBookings, dayColumns, zonedInstant, type GridWindow, type PositionedBooking, } from "./components/booking-grid.js";