@ordinatio/scheduling-api 0.3.0 → 0.4.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.
- package/CHANGELOG.md +34 -0
- package/README.md +19 -0
- package/dist/agent/index.d.mts +55 -0
- package/dist/agent/index.d.ts +55 -0
- package/dist/agent/index.js +547 -0
- package/dist/agent/index.mjs +517 -0
- package/dist/{chunk-MQO3VRMU.mjs → chunk-WZ5KO7IW.mjs} +12 -10
- package/dist/index.d.mts +4 -385
- package/dist/index.d.ts +4 -385
- package/dist/index.js +81 -24
- package/dist/index.mjs +72 -17
- package/dist/routes-CM-ezlv2.d.mts +386 -0
- package/dist/routes-CM-ezlv2.d.ts +386 -0
- package/dist/schemas/index.js +12 -10
- package/dist/schemas/index.mjs +1 -1
- package/package.json +13 -3
package/dist/index.mjs
CHANGED
|
@@ -37,7 +37,7 @@ import {
|
|
|
37
37
|
UpdatePackagePurchaseSchema,
|
|
38
38
|
UpdateRoutingFormSchema,
|
|
39
39
|
UpdateServicePackageSchema
|
|
40
|
-
} from "./chunk-
|
|
40
|
+
} from "./chunk-WZ5KO7IW.mjs";
|
|
41
41
|
|
|
42
42
|
// src/create-api.ts
|
|
43
43
|
import * as engine from "@ordinatio/scheduling";
|
|
@@ -4165,7 +4165,43 @@ We look forward to seeing you!
|
|
|
4165
4165
|
}
|
|
4166
4166
|
|
|
4167
4167
|
// src/handlers/calendar-ownership.ts
|
|
4168
|
-
import { schedError as schedError23 } from "@ordinatio/scheduling";
|
|
4168
|
+
import { schedError as schedError23, updateCalendar } from "@ordinatio/scheduling";
|
|
4169
|
+
var SAFE_CALENDAR_FIELDS = [
|
|
4170
|
+
"id",
|
|
4171
|
+
"organizationId",
|
|
4172
|
+
"name",
|
|
4173
|
+
"slug",
|
|
4174
|
+
"type",
|
|
4175
|
+
"timezone",
|
|
4176
|
+
"isActive",
|
|
4177
|
+
"googleCalendarId",
|
|
4178
|
+
"outlookCalendarId",
|
|
4179
|
+
"syncDirection",
|
|
4180
|
+
"lastSyncAt",
|
|
4181
|
+
"staffName",
|
|
4182
|
+
"staffEmail",
|
|
4183
|
+
"staffAvatar",
|
|
4184
|
+
"userId",
|
|
4185
|
+
"theme",
|
|
4186
|
+
"bookingPageConfig",
|
|
4187
|
+
"location",
|
|
4188
|
+
"slotGranularityMinutes",
|
|
4189
|
+
"createdAt",
|
|
4190
|
+
"updatedAt"
|
|
4191
|
+
];
|
|
4192
|
+
function toCalendarAnswer(calendar) {
|
|
4193
|
+
const row = calendar;
|
|
4194
|
+
return Object.fromEntries(SAFE_CALENDAR_FIELDS.filter((key) => key in row).map((key) => [key, row[key]]));
|
|
4195
|
+
}
|
|
4196
|
+
function lastActiveCalendarResponse(error, route) {
|
|
4197
|
+
if (getErrorCode(error) !== "SCHED_103") return null;
|
|
4198
|
+
const ref = getErrorRef(error);
|
|
4199
|
+
console.error(route, ref, error);
|
|
4200
|
+
return Response.json(
|
|
4201
|
+
{ error: "Cannot archive the last active calendar. Create another calendar first.", ...ref && { ref } },
|
|
4202
|
+
{ status: 409 }
|
|
4203
|
+
);
|
|
4204
|
+
}
|
|
4169
4205
|
async function getOwnedCalendarForRoute(db, id, organizationId) {
|
|
4170
4206
|
const calendar = await db.schedulingCalendar.findUnique({
|
|
4171
4207
|
where: { id },
|
|
@@ -4241,6 +4277,19 @@ async function releaseCalendarSlugIfStillInactive(host, db, calendarId, organiza
|
|
|
4241
4277
|
}
|
|
4242
4278
|
return false;
|
|
4243
4279
|
}
|
|
4280
|
+
async function undoArchive(host, db, calendarId, organizationId, slug) {
|
|
4281
|
+
try {
|
|
4282
|
+
await updateCalendar(db, calendarId, organizationId, { isActive: true });
|
|
4283
|
+
} catch (restoreError) {
|
|
4284
|
+
console.error("[calendar update] could not switch the calendar back on after a failed update", calendarId, restoreError);
|
|
4285
|
+
try {
|
|
4286
|
+
await releaseCalendarSlugIfStillInactive(host, db, calendarId, organizationId, slug);
|
|
4287
|
+
} catch (releaseError) {
|
|
4288
|
+
console.error("[calendar update] could not free the address of an archived calendar", calendarId, releaseError);
|
|
4289
|
+
}
|
|
4290
|
+
await bustCalendarCachesOnArchive(host, organizationId, slug, calendarId);
|
|
4291
|
+
}
|
|
4292
|
+
}
|
|
4244
4293
|
|
|
4245
4294
|
// src/handlers/admin-calendars.ts
|
|
4246
4295
|
var CALENDARS_DEFAULT_LIMIT = 500;
|
|
@@ -4319,7 +4368,7 @@ async function createCalendar(request, { host }) {
|
|
|
4319
4368
|
metadata: { calendarId: calendar.id, calendarName: input.name, type: input.type }
|
|
4320
4369
|
});
|
|
4321
4370
|
const claim = await host.slugDirectory.claim(calendar.slug, "CALENDAR", organizationId);
|
|
4322
|
-
return Response.json({ calendar, directoryClaimed: claim.claimed }, { status: 201 });
|
|
4371
|
+
return Response.json({ calendar: toCalendarAnswer(calendar), directoryClaimed: claim.claimed }, { status: 201 });
|
|
4323
4372
|
} catch (error) {
|
|
4324
4373
|
if (getErrorCode(error) === "P2002") {
|
|
4325
4374
|
return Response.json({ error: "A calendar with this name already exists" }, { status: 409 });
|
|
@@ -4329,7 +4378,7 @@ async function createCalendar(request, { host }) {
|
|
|
4329
4378
|
}
|
|
4330
4379
|
|
|
4331
4380
|
// src/handlers/admin-calendar-update.ts
|
|
4332
|
-
import { archiveCalendar, updateCalendar } from "@ordinatio/scheduling";
|
|
4381
|
+
import { archiveCalendar, updateCalendar as updateCalendar2 } from "@ordinatio/scheduling";
|
|
4333
4382
|
var NOT_FOUND5 = () => Response.json({ error: "Calendar not found" }, { status: 404 });
|
|
4334
4383
|
async function getCalendar(request, { host, params }) {
|
|
4335
4384
|
try {
|
|
@@ -4359,19 +4408,31 @@ async function putCalendar(request, { host, params }) {
|
|
|
4359
4408
|
const input = validation.data;
|
|
4360
4409
|
const linkError = input.userId === void 0 ? null : await validateStaffLink(host, input.userId, organizationId);
|
|
4361
4410
|
if (linkError) return linkError;
|
|
4362
|
-
const
|
|
4363
|
-
|
|
4364
|
-
|
|
4365
|
-
|
|
4411
|
+
const archiving = input.isActive === false && existing.isActive;
|
|
4412
|
+
let archived = false;
|
|
4413
|
+
let updated;
|
|
4414
|
+
try {
|
|
4415
|
+
if (archiving) {
|
|
4416
|
+
await archiveCalendar(db, id, organizationId);
|
|
4417
|
+
archived = true;
|
|
4418
|
+
}
|
|
4419
|
+
({ calendar: updated } = await updateCalendar2(db, id, organizationId, buildCalendarUpdateData(input)));
|
|
4420
|
+
} catch (error) {
|
|
4421
|
+
if (archived) await undoArchive(host, db, id, organizationId, existing.slug);
|
|
4422
|
+
throw error;
|
|
4366
4423
|
}
|
|
4424
|
+
if (input.slotGranularityMinutes !== void 0) await host.availabilityCache.invalidate(id);
|
|
4425
|
+
if (archiving) await releaseCalendarSlugIfStillInactive(host, db, id, organizationId, existing.slug);
|
|
4367
4426
|
await bustCalendarCachesOnUpdate(host, organizationId, existing.slug, input, id);
|
|
4368
4427
|
await host.activity.log(db, {
|
|
4369
4428
|
action: "scheduling.calendar_updated",
|
|
4370
4429
|
description: `updated calendar "${existing.name}"`,
|
|
4371
4430
|
metadata: { calendarId: id, changes: input }
|
|
4372
4431
|
});
|
|
4373
|
-
return Response.json({ calendar: updated });
|
|
4432
|
+
return Response.json({ calendar: toCalendarAnswer(updated) });
|
|
4374
4433
|
} catch (error) {
|
|
4434
|
+
const lastActive = lastActiveCalendarResponse(error, "[PUT /admin/calendars]");
|
|
4435
|
+
if (lastActive) return lastActive;
|
|
4375
4436
|
return Response.json({ error: getErrorMessage(error, "Failed to update calendar") }, { status: 500 });
|
|
4376
4437
|
}
|
|
4377
4438
|
}
|
|
@@ -4394,14 +4455,8 @@ async function deleteCalendar(request, { host, params }) {
|
|
|
4394
4455
|
});
|
|
4395
4456
|
return Response.json({ success: true });
|
|
4396
4457
|
} catch (error) {
|
|
4397
|
-
|
|
4398
|
-
|
|
4399
|
-
console.error("[DELETE /admin/calendars]", ref, error);
|
|
4400
|
-
return Response.json(
|
|
4401
|
-
{ error: "Cannot archive the last active calendar. Create another calendar first.", ...ref && { ref } },
|
|
4402
|
-
{ status: 409 }
|
|
4403
|
-
);
|
|
4404
|
-
}
|
|
4458
|
+
const lastActive = lastActiveCalendarResponse(error, "[DELETE /admin/calendars]");
|
|
4459
|
+
if (lastActive) return lastActive;
|
|
4405
4460
|
return Response.json({ error: getErrorMessage(error, "Failed to delete calendar") }, { status: 500 });
|
|
4406
4461
|
}
|
|
4407
4462
|
}
|
|
@@ -0,0 +1,386 @@
|
|
|
1
|
+
import { SchedulingDb, CalendarSyncAdapter, WebhookTransport, PaymentAdapter } from '@ordinatio/scheduling';
|
|
2
|
+
|
|
3
|
+
/** Named limits. A host that counts requests maps each name to its own numbers. */
|
|
4
|
+
type RateLimitTier = 'PUBLIC_BOOKING' | 'AVAILABILITY' | 'GENERAL' | 'CREATE' | 'UPDATE' | 'DELETE' | 'PAYMENT_INTENT' | 'RESOLVE_REFUND' | 'INTERNAL' | 'SETTINGS';
|
|
5
|
+
/** What a public booking page is looked up by: a calendar slug or an appointment type slug. */
|
|
6
|
+
type PublicBookingKind = 'CALENDAR' | 'APPOINTMENT_TYPE';
|
|
7
|
+
/** The organization a public request belongs to, and the database that holds its data. */
|
|
8
|
+
interface PublicBookingContext {
|
|
9
|
+
db: SchedulingDb;
|
|
10
|
+
organizationId: string;
|
|
11
|
+
}
|
|
12
|
+
interface PublicBookingResolver {
|
|
13
|
+
/**
|
|
14
|
+
* Finds the organization and database for a public booking page. `orgSlug` is the organization named in
|
|
15
|
+
* the page address, or null for an older address that names only the calendar or type. Returns null when
|
|
16
|
+
* there is no such page. A host with several organizations supplies this; the default assumes one.
|
|
17
|
+
*/
|
|
18
|
+
resolve(input: {
|
|
19
|
+
orgSlug: string | null;
|
|
20
|
+
slug: string;
|
|
21
|
+
kind: PublicBookingKind;
|
|
22
|
+
logPrefix: string;
|
|
23
|
+
}): Promise<PublicBookingContext | null>;
|
|
24
|
+
}
|
|
25
|
+
/** The organization a request names by its slug, and the database that holds its data. */
|
|
26
|
+
interface PublicOrganization {
|
|
27
|
+
db: SchedulingDb;
|
|
28
|
+
/** The organization id every read must be scoped by, or null when the host has one organization and nothing to scope. */
|
|
29
|
+
organizationId: string | null;
|
|
30
|
+
}
|
|
31
|
+
interface PublicOrganizationResolver {
|
|
32
|
+
/**
|
|
33
|
+
* Finds the organization named by `orgSlug`, for routes that are keyed by an id and not by a slug. Returns null
|
|
34
|
+
* when there is no such active organization. A host with several organizations supplies this; the default
|
|
35
|
+
* assumes one, so it returns the public database with no organization id and the reads are not scoped.
|
|
36
|
+
*/
|
|
37
|
+
resolve(input: {
|
|
38
|
+
orgSlug: string;
|
|
39
|
+
logPrefix: string;
|
|
40
|
+
}): Promise<PublicOrganization | null>;
|
|
41
|
+
}
|
|
42
|
+
/** Stored free-slot answers, one per calendar, day and duration. */
|
|
43
|
+
interface AvailabilityCache {
|
|
44
|
+
/** The stored answer, or null when there is none or it has expired. A rejection is treated as a miss. */
|
|
45
|
+
get(calendarId: string, day: string, duration: number): Promise<unknown | null>;
|
|
46
|
+
set(calendarId: string, day: string, duration: number, value: unknown): Promise<void>;
|
|
47
|
+
/** Drops every stored answer of the calendar. Called when a booking changes its free slots. */
|
|
48
|
+
invalidate(calendarId: string): Promise<void>;
|
|
49
|
+
}
|
|
50
|
+
/**
|
|
51
|
+
* Tells the screens of an organization that an appointment changed, for example `appointment.cancelled`. It runs
|
|
52
|
+
* after the change is saved and must not throw: a rejection ends the request with a 500 although the change stands,
|
|
53
|
+
* and the steps after it are skipped.
|
|
54
|
+
*/
|
|
55
|
+
interface AppointmentEventSink {
|
|
56
|
+
emit(organizationId: string, type: string, data: Record<string, unknown>): Promise<void>;
|
|
57
|
+
}
|
|
58
|
+
interface ActivityEntry {
|
|
59
|
+
action: string;
|
|
60
|
+
description: string;
|
|
61
|
+
metadata?: Record<string, unknown>;
|
|
62
|
+
/** A key that lets a later step find this entry again. */
|
|
63
|
+
externalRef?: string;
|
|
64
|
+
}
|
|
65
|
+
/**
|
|
66
|
+
* Writes entries to the activity feed that staff read. A self-service cancellation of a paid appointment tells staff
|
|
67
|
+
* to review the refund only through the entry `scheduling.appointment_refund_pending`, so a host that supplies no log
|
|
68
|
+
* sends no alert. It runs after the change is saved and must not throw: a rejection ends the request with a 500
|
|
69
|
+
* although the change stands, and the steps after it are skipped.
|
|
70
|
+
*/
|
|
71
|
+
interface ActivityLog {
|
|
72
|
+
log(db: SchedulingDb, entry: ActivityEntry): Promise<void>;
|
|
73
|
+
/** Whether an entry with this `externalRef` exists and has not been resolved. */
|
|
74
|
+
isOpen(db: SchedulingDb, externalRef: string): Promise<boolean>;
|
|
75
|
+
/** Marks the entry with this `externalRef` resolved by the person. Does nothing when there is none. */
|
|
76
|
+
resolve(db: SchedulingDb, externalRef: string, resolvedBy: string): Promise<void>;
|
|
77
|
+
}
|
|
78
|
+
/** A filter on the calendar of an appointment, narrowing a list to the calendars a person may see. */
|
|
79
|
+
type CalendarVisibility = NonNullable<NonNullable<NonNullable<Parameters<SchedulingDb['appointment']['count']>[0]>['where']>['calendar']>;
|
|
80
|
+
/** What the balance flow needs from the payment provider beyond creating a payment. */
|
|
81
|
+
interface BalancePaymentControl {
|
|
82
|
+
/** Cancels an unpaid payment. Rejects when the provider refuses, for example because it is already paid or canceled. */
|
|
83
|
+
cancel(paymentId: string): Promise<void>;
|
|
84
|
+
/** The provider's own status word for the payment, such as "canceled" or "succeeded". Rejects when it cannot be read. */
|
|
85
|
+
statusOf(paymentId: string): Promise<string>;
|
|
86
|
+
}
|
|
87
|
+
/** A signed-in member of the organization, as the host knows them. */
|
|
88
|
+
interface StaffContext {
|
|
89
|
+
userId: string;
|
|
90
|
+
organizationId: string;
|
|
91
|
+
/** The person's role. It is only written into the error record of a refusal. */
|
|
92
|
+
role: string;
|
|
93
|
+
/** True when the role may manage scheduling for the whole organization (owner, admin, manager) and not only look up one client. */
|
|
94
|
+
isAdmin: boolean;
|
|
95
|
+
/** False when the organization has scheduling switched off; admin routes then answer 503. */
|
|
96
|
+
schedulingEnabled: boolean;
|
|
97
|
+
/** The database of the organization. */
|
|
98
|
+
db: SchedulingDb;
|
|
99
|
+
/** The calendars this person may see, or null when they may see them all. Asked only after the role check. */
|
|
100
|
+
visibleCalendars(): Promise<CalendarVisibility | null>;
|
|
101
|
+
/**
|
|
102
|
+
* The ids of the calendars this person may see, or undefined when they may see them all. Reports and group-session
|
|
103
|
+
* lists narrow to these ids, where `visibleCalendars` gives a filter for queries on appointments.
|
|
104
|
+
*/
|
|
105
|
+
visibleCalendarIds(): Promise<string[] | undefined>;
|
|
106
|
+
/** Whether this person may see one calendar. False also for a calendar that does not exist, so a hidden one looks missing. */
|
|
107
|
+
canSeeCalendar(calendarId: string): Promise<boolean>;
|
|
108
|
+
/** Whether this person may see one appointment, by the group visibility of its calendar. False also when it does not exist. */
|
|
109
|
+
canSeeAppointment(appointmentId: string): Promise<boolean>;
|
|
110
|
+
/**
|
|
111
|
+
* The place a client prefers to be seen at, or null when the client does not exist, has no preference, or is one
|
|
112
|
+
* this person may not see. A client outside the person's groups looks the same as a missing one.
|
|
113
|
+
*/
|
|
114
|
+
preferredLocationOf(clientId: string): Promise<string | null>;
|
|
115
|
+
}
|
|
116
|
+
interface StaffResolver {
|
|
117
|
+
/**
|
|
118
|
+
* The signed-in member who sent the request, or null when nobody is signed in (the route then answers 401).
|
|
119
|
+
* It may throw, for example when the person belongs to no organization; the route then answers 500.
|
|
120
|
+
*/
|
|
121
|
+
resolve(request: Request): Promise<StaffContext | null>;
|
|
122
|
+
}
|
|
123
|
+
/**
|
|
124
|
+
* Decides which client record a new booking belongs to. The booking endpoint is public, so `suppliedClientId` is
|
|
125
|
+
* untrusted: honor it only for a signed-in member of the organization who may see that client. It must not throw: a
|
|
126
|
+
* failure means the appointment is saved unlinked and can be linked later.
|
|
127
|
+
*/
|
|
128
|
+
interface BookingClientResolver {
|
|
129
|
+
resolve(request: Request, db: SchedulingDb, input: {
|
|
130
|
+
organizationId: string;
|
|
131
|
+
email: string;
|
|
132
|
+
suppliedClientId?: string;
|
|
133
|
+
}): Promise<string | null>;
|
|
134
|
+
/** Remembers the place a client prefers to be seen at. It may throw: the caller logs the failure and carries on. */
|
|
135
|
+
rememberLocation(db: SchedulingDb, clientId: string, location: string): Promise<void>;
|
|
136
|
+
}
|
|
137
|
+
/** What an organization does about a client who keeps missing appointments. */
|
|
138
|
+
interface NoShowPolicy {
|
|
139
|
+
enabled: boolean;
|
|
140
|
+
/** How many missed appointments trigger the action. */
|
|
141
|
+
threshold: number;
|
|
142
|
+
/** BLOCK_BOOKING refuses online booking; REQUIRE_APPROVAL books it as PENDING for staff to review. */
|
|
143
|
+
action: 'BLOCK_BOOKING' | 'REQUIRE_APPROVAL';
|
|
144
|
+
}
|
|
145
|
+
interface BookingPolicy {
|
|
146
|
+
/** The no-show policy of the organization, or null when it has none. */
|
|
147
|
+
noShowPrevention(organizationId: string): Promise<NoShowPolicy | null>;
|
|
148
|
+
}
|
|
149
|
+
/** Who works in the organization, for the staff picker on the calendar settings page. */
|
|
150
|
+
interface StaffDirectory {
|
|
151
|
+
/** Active members of the organization. Departed or deactivated accounts are left out so they cannot be newly linked. */
|
|
152
|
+
listActive(organizationId: string): Promise<Array<{
|
|
153
|
+
id: string;
|
|
154
|
+
name: string | null;
|
|
155
|
+
email: string;
|
|
156
|
+
}>>;
|
|
157
|
+
/** Whether the user is a member of the organization. Used before a calendar is linked to a staff member. */
|
|
158
|
+
isMember(organizationId: string, userId: string): Promise<boolean>;
|
|
159
|
+
}
|
|
160
|
+
/** A public booking page is reached by a bare slug. This index says which organization owns each slug. */
|
|
161
|
+
interface SlugDirectory {
|
|
162
|
+
/** Reserves `slug` for the organization. First claim wins. Never throws: a conflict or failure is `claimed: false` with a `ref`. */
|
|
163
|
+
claim(slug: string, kind: 'CALENDAR' | 'APPOINTMENT_TYPE', organizationId: string): Promise<{
|
|
164
|
+
claimed: boolean;
|
|
165
|
+
ref?: string;
|
|
166
|
+
}>;
|
|
167
|
+
/** Frees the slug if this organization holds it. Never throws. */
|
|
168
|
+
release(slug: string, kind: 'CALENDAR' | 'APPOINTMENT_TYPE', organizationId: string): Promise<void>;
|
|
169
|
+
}
|
|
170
|
+
interface CacheOptions {
|
|
171
|
+
/** Names the stored answer. It always contains the organization id, so two organizations never share one. */
|
|
172
|
+
key: string;
|
|
173
|
+
/** Names to drop the answer by when its data changes. */
|
|
174
|
+
tags: string[];
|
|
175
|
+
ttlSeconds: number;
|
|
176
|
+
}
|
|
177
|
+
interface SchedulingCache {
|
|
178
|
+
/** Returns the stored answer for `options.key`, or calls `load`, stores what it returns, and returns that. */
|
|
179
|
+
wrap<T>(options: CacheOptions, load: () => Promise<T>): Promise<T>;
|
|
180
|
+
/** Drops every stored answer that carries one of the tags. */
|
|
181
|
+
invalidate(tags: string[]): Promise<void>;
|
|
182
|
+
}
|
|
183
|
+
/** Decides whether a request comes from the host's own background worker and not from a person or the public. */
|
|
184
|
+
interface InternalAccess {
|
|
185
|
+
/** True only for a request that carries the worker's credential. Must be false when no credential is configured. */
|
|
186
|
+
isAuthorized(request: Request): boolean | Promise<boolean>;
|
|
187
|
+
}
|
|
188
|
+
/** Hands a command to the host's background worker, for example to remove an event from an outside calendar. */
|
|
189
|
+
interface WorkerCommands {
|
|
190
|
+
queue(action: string, data: Record<string, unknown>): Promise<void>;
|
|
191
|
+
}
|
|
192
|
+
/** What a provider's side of a calendar connection ended in. */
|
|
193
|
+
type CalendarConnectOutcome =
|
|
194
|
+
/** The connection failed; the person is sent back to the settings page with `?error=<failure>`. */
|
|
195
|
+
{
|
|
196
|
+
failure: string;
|
|
197
|
+
}
|
|
198
|
+
/** The fields to write on the connected calendar, or null when there is nothing to write. */
|
|
199
|
+
| {
|
|
200
|
+
link: Record<string, unknown> | null;
|
|
201
|
+
};
|
|
202
|
+
/** One outside calendar provider (Google, Outlook): where to send the person and what to do with the code they come back with. */
|
|
203
|
+
interface CalendarConnector {
|
|
204
|
+
/** The provider's sign-in address. `state` must be carried through unchanged. */
|
|
205
|
+
authorizationUrl(state: string): string;
|
|
206
|
+
/**
|
|
207
|
+
* Exchanges the code the provider sent back. It runs before the calendar being connected is known, so it may save
|
|
208
|
+
* account tokens of its own but must not touch the scheduling calendar. A rejection ends the connection with the
|
|
209
|
+
* provider's generic failure.
|
|
210
|
+
*/
|
|
211
|
+
exchange(code: string): Promise<CalendarConnectOutcome>;
|
|
212
|
+
}
|
|
213
|
+
interface CalendarConnectors {
|
|
214
|
+
google: CalendarConnector;
|
|
215
|
+
outlook: CalendarConnector;
|
|
216
|
+
}
|
|
217
|
+
/** Switches outbound webhooks on. A host that supplies none has them off: the routes answer 501 and nothing is queued. */
|
|
218
|
+
interface WebhookSettings {
|
|
219
|
+
/** Allows http addresses and addresses on a private network. For local development and tests only. Default: no. */
|
|
220
|
+
allowInsecureTargets?: boolean;
|
|
221
|
+
/** Sends one request. Default: Node's own http client, which refuses names that resolve to private addresses. */
|
|
222
|
+
transport?: WebhookTransport;
|
|
223
|
+
}
|
|
224
|
+
/** What the host does with a waitlist offer. Switching the waitlist on is what supplies this object. */
|
|
225
|
+
interface WaitlistSettings {
|
|
226
|
+
/** How long an offer lasts, in minutes, and never past the start of the slot. Default 30. */
|
|
227
|
+
offerMinutes?: number;
|
|
228
|
+
/**
|
|
229
|
+
* Tells the client that a slot is theirs to take: send `token` in a link to the page that calls
|
|
230
|
+
* `GET /waitlist/offer` and `POST /waitlist/offer/accept`. It runs inside the request that cancelled the booking, so it
|
|
231
|
+
* should only queue the message, not wait for it to be delivered. It must not throw; a rejection is logged and the offer
|
|
232
|
+
* stays open until it expires. Without it, only the `waitlist.offered` webhook announces the offer.
|
|
233
|
+
*/
|
|
234
|
+
notify?(offer: {
|
|
235
|
+
organizationId: string;
|
|
236
|
+
token: string;
|
|
237
|
+
clientName: string;
|
|
238
|
+
clientEmail: string;
|
|
239
|
+
clientPhone: string | null;
|
|
240
|
+
typeName: string;
|
|
241
|
+
calendarName: string;
|
|
242
|
+
startTime: Date;
|
|
243
|
+
timezone: string;
|
|
244
|
+
expiresAt: Date;
|
|
245
|
+
}): Promise<void>;
|
|
246
|
+
}
|
|
247
|
+
/** Switches routing forms on. A host that supplies none has them off: the routes answer 501. */
|
|
248
|
+
type RoutingFormSettings = Record<string, never>;
|
|
249
|
+
/**
|
|
250
|
+
* Switches organization branding on: a name, logo and colours for the booking page and messages, and a sender identity.
|
|
251
|
+
* A host that supplies none has it off: the routes answer 501 and no message carries a brand.
|
|
252
|
+
*/
|
|
253
|
+
interface BrandSettings {
|
|
254
|
+
/**
|
|
255
|
+
* Says whether the host may send mail from `domain` (lower case, such as "mail.acme.com"), usually because it has been
|
|
256
|
+
* verified with the mail provider. Without it no organization can set a sending address; it can still set a reply-to.
|
|
257
|
+
* A rejection counts as "no".
|
|
258
|
+
*/
|
|
259
|
+
isSendingDomainVerified?(domain: string, organizationId: string): boolean | Promise<boolean>;
|
|
260
|
+
}
|
|
261
|
+
/** Switches data export and erasure on. A host that supplies none has them off: the routes answer 501. */
|
|
262
|
+
type PrivacySettings = Record<string, never>;
|
|
263
|
+
interface SchedulingHost {
|
|
264
|
+
/**
|
|
265
|
+
* The database for routes that have no signed-in user. Such a route reads the system database before it knows
|
|
266
|
+
* which organization the request belongs to, for example to find the organization of a calendar by its id.
|
|
267
|
+
*/
|
|
268
|
+
publicDb(): Promise<SchedulingDb>;
|
|
269
|
+
/** Finds the organization and database of a public booking page. Default: one organization in `publicDb()`. */
|
|
270
|
+
publicBooking?: PublicBookingResolver;
|
|
271
|
+
/** The web address of the host, such as https://system.example.com, used in links inside files it hands out. Default: none. */
|
|
272
|
+
appUrl?(): string | null | undefined;
|
|
273
|
+
/** The business name used in messages when a calendar has no staff name. Default: none. */
|
|
274
|
+
appName?(): string | null | undefined;
|
|
275
|
+
/** Whether scheduling is switched on for an organization, asked by public routes that know only the organization id. Default: yes. */
|
|
276
|
+
schedulingEnabledFor?(organizationId: string): Promise<boolean>;
|
|
277
|
+
/** Whether booking analytics is switched on for this installation. Default: on. */
|
|
278
|
+
bookingAnalyticsEnabled?(): boolean;
|
|
279
|
+
/** Whether the payment provider can charge in this currency (lower case, such as "usd"). Default: any currency. */
|
|
280
|
+
canChargeCurrency?(currency: string): boolean;
|
|
281
|
+
/**
|
|
282
|
+
* The database of one organization, for routes that find the organization only after reading a row, such as a
|
|
283
|
+
* manage-link token. Returns null when it cannot be reached. Default: `publicDb()`, for one organization.
|
|
284
|
+
*/
|
|
285
|
+
tenantDb?(organizationId: string, logPrefix: string): Promise<SchedulingDb | null>;
|
|
286
|
+
/** Announces appointment changes to connected screens. Default: nothing is announced. */
|
|
287
|
+
events?: AppointmentEventSink;
|
|
288
|
+
/**
|
|
289
|
+
* Keeps an outside calendar in step with an appointment. Failures are caught and reported through the activity
|
|
290
|
+
* log, never thrown. Default: nothing is synced.
|
|
291
|
+
*/
|
|
292
|
+
calendarSync?: CalendarSyncAdapter;
|
|
293
|
+
/**
|
|
294
|
+
* Turns on outbound webhooks: booking changes are queued for the organization's endpoints, and the admin routes
|
|
295
|
+
* work. Queued deliveries are sent by `deliverDueWebhooks` (or `POST /internal/webhooks/deliver`), which the host
|
|
296
|
+
* runs on a timer. Needs the webhook tables. Default: off.
|
|
297
|
+
*/
|
|
298
|
+
webhooks?: WebhookSettings | null;
|
|
299
|
+
/**
|
|
300
|
+
* Turns on the waitlist: clients can wait for a full slot or day, and a cancelled or moved booking offers its slot
|
|
301
|
+
* to the first person in line. Needs the waitlist table. Default: off, so the routes answer 501.
|
|
302
|
+
*/
|
|
303
|
+
waitlist?: WaitlistSettings | null;
|
|
304
|
+
/**
|
|
305
|
+
* Turns on routing forms: an admin defines questions and rules, and a public route sends a client to the right
|
|
306
|
+
* appointment type or calendar. Needs the routing form table. Default: off, so the routes answer 501.
|
|
307
|
+
*/
|
|
308
|
+
routingForms?: RoutingFormSettings | null;
|
|
309
|
+
/**
|
|
310
|
+
* Turns on exporting and erasing one person's data (admin only, every request recorded). Needs the data request table.
|
|
311
|
+
* Default: off, so the routes answer 501.
|
|
312
|
+
*/
|
|
313
|
+
privacy?: PrivacySettings | null;
|
|
314
|
+
/**
|
|
315
|
+
* Turns on organization branding. Needs the brand table. Messages carry the brand only if the host's message sender
|
|
316
|
+
* also asks for it (see `processPendingNotifications`' `brand` option). Default: off, so the routes answer 501.
|
|
317
|
+
*/
|
|
318
|
+
brand?: BrandSettings | null;
|
|
319
|
+
/** The domain used after the "@" in calendar-file event ids. Keep it unchanged once calendars have subscribed. Default: ordinatio-scheduling. */
|
|
320
|
+
icalUidDomain?(): string | null | undefined;
|
|
321
|
+
/** Records what happened in the activity feed. Default: nothing is recorded. */
|
|
322
|
+
activity?: ActivityLog;
|
|
323
|
+
/** Finds the organization named by an `orgSlug` query value. Default: one organization, nothing scoped. */
|
|
324
|
+
organizations?: PublicOrganizationResolver;
|
|
325
|
+
/** Stores free-slot answers for a minute. Default: in this process's memory. */
|
|
326
|
+
availabilityCache?: AvailabilityCache;
|
|
327
|
+
/** Stores answers that rarely change. Default: in this process's memory. */
|
|
328
|
+
cache?: SchedulingCache;
|
|
329
|
+
/**
|
|
330
|
+
* Counts one request against `key`. Returns null to let the request through, or the response to send
|
|
331
|
+
* (normally a 429). Default: an in-memory counter, which counts per process only.
|
|
332
|
+
*/
|
|
333
|
+
rateLimit?(key: string, tier: RateLimitTier): Promise<Response | null>;
|
|
334
|
+
/** Finds the signed-in member of a request, for routes only staff may call. Default: nobody is signed in, so those routes answer 401. */
|
|
335
|
+
staff?: StaffResolver;
|
|
336
|
+
/** Lists the staff of an organization. Default: nobody, so the staff picker is empty. */
|
|
337
|
+
staffDirectory?: StaffDirectory;
|
|
338
|
+
/** Bare-slug booking links across organizations. Default: none, so every claim succeeds and nothing is recorded. */
|
|
339
|
+
slugDirectory?: SlugDirectory;
|
|
340
|
+
/** Finds the client record of a new booking. Default: none, so every booking is saved unlinked. */
|
|
341
|
+
clients?: BookingClientResolver;
|
|
342
|
+
/** Per-organization booking rules. Default: none, so nobody is ever held back for missed appointments. */
|
|
343
|
+
bookingPolicy?: BookingPolicy;
|
|
344
|
+
/**
|
|
345
|
+
* Charges, checks and refunds payments. Default: none. A booking for a type that requires payment is then
|
|
346
|
+
* refused, because no payment can be verified.
|
|
347
|
+
*/
|
|
348
|
+
payments?: PaymentAdapter;
|
|
349
|
+
/**
|
|
350
|
+
* Cancels a payment that was created and then lost a race, and reads its current state. Default: none, so a
|
|
351
|
+
* payment that must be cancelled is reported as still live and staff are told to cancel it by hand.
|
|
352
|
+
*/
|
|
353
|
+
balancePayments?: BalancePaymentControl;
|
|
354
|
+
/** Who counts as the background worker, for routes only it may call. Default: nobody, so those routes answer 401. */
|
|
355
|
+
internalAccess?: InternalAccess;
|
|
356
|
+
/** Commands for the background worker. Default: they are dropped. */
|
|
357
|
+
workerCommands?: WorkerCommands;
|
|
358
|
+
/** The Google and Outlook sign-in flows. Default: neither is configured, so starting a connection answers 500 and finishing one fails. */
|
|
359
|
+
calendarConnectors?: CalendarConnectors;
|
|
360
|
+
/** Whether the short-lived sign-in cookies may only travel over https. Default: yes. */
|
|
361
|
+
secureCookies?(): boolean;
|
|
362
|
+
/** The value that clears a JSON column. Default: null. A Prisma host returns `Prisma.DbNull`, because Prisma refuses a plain null there. */
|
|
363
|
+
jsonNull?(): unknown;
|
|
364
|
+
/** CORS headers for answers to the booking widget, which runs on other websites. Default: any origin, no cookies. */
|
|
365
|
+
cors?(request?: Request): Record<string, string>;
|
|
366
|
+
}
|
|
367
|
+
/** The host with every default filled in. Handlers receive this. */
|
|
368
|
+
type ResolvedHost = Required<SchedulingHost>;
|
|
369
|
+
|
|
370
|
+
type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
|
|
371
|
+
interface RouteContext {
|
|
372
|
+
host: ResolvedHost;
|
|
373
|
+
/** Values of the `[name]` segments in the route path. */
|
|
374
|
+
params: Record<string, string>;
|
|
375
|
+
}
|
|
376
|
+
type RouteHandler = (request: Request, context: RouteContext) => Promise<Response> | Response;
|
|
377
|
+
interface Route {
|
|
378
|
+
method: HttpMethod;
|
|
379
|
+
/** Relative to the base path. A `[name]` segment matches any one segment. */
|
|
380
|
+
path: string;
|
|
381
|
+
/** A public route is called from other websites, so it also answers a CORS preflight. */
|
|
382
|
+
public: boolean;
|
|
383
|
+
handler: RouteHandler;
|
|
384
|
+
}
|
|
385
|
+
|
|
386
|
+
export type { AvailabilityCache as A, BalancePaymentControl as B, CacheOptions as C, HttpMethod as H, InternalAccess as I, NoShowPolicy as N, PublicBookingResolver as P, Route as R, SchedulingHost as S, WaitlistSettings as W, RateLimitTier as a, SchedulingCache as b, PublicOrganizationResolver as c, StaffResolver as d, StaffContext as e, ActivityEntry as f, ActivityLog as g, AppointmentEventSink as h, BookingClientResolver as i, BookingPolicy as j, BrandSettings as k, CalendarConnectOutcome as l, CalendarConnector as m, CalendarConnectors as n, CalendarVisibility as o, PrivacySettings as p, PublicBookingContext as q, PublicBookingKind as r, PublicOrganization as s, ResolvedHost as t, RouteContext as u, RouteHandler as v, RoutingFormSettings as w, StaffDirectory as x, WebhookSettings as y, WorkerCommands as z };
|