@cosmoops/connect-sdk 0.17.0 → 0.19.0

package/dist/esm/server/handler.js

@@ -412,6 +412,142 @@ export function createConnectHandler(options) {
             await session.write?.(request, response, result.sessionToken);
             return response;
         },
+        /*
+         * Scheduling - the workspace's own calendar, in a browser.
+         *
+         * Every one of these forwards the caller's session token, which is what
+         * makes them safe to expose: Connect derives the workspace from that token
+         * and checks the member's own `calendar:read` / `calendar:manage`. The
+         * browser names no tenant and the partner's key does not, by itself,
+         * authorize a write - without that second half, shipping a booking
+         * component would let every end user of every partner app take slots on a
+         * real business calendar.
+         *
+         * `workspaceId` is still passed because the resource requires it, and is
+         * still ignored by Connect whenever a token is present. `requireWorkspace`
+         * supplies the session's own, so the two can never disagree.
+         */
+        "GET /scheduling/event-types": async (request) => {
+            const { workspaceId } = await requireWorkspace(request);
+            const asUser = await requireToken(request);
+            return json({ eventTypes: await client.scheduling.listEventTypes(workspaceId, { asUser }) });
+        },
+        "GET /scheduling/slots": async (request) => {
+            const { workspaceId } = await requireWorkspace(request);
+            const asUser = await requireToken(request);
+            const url = new URL(request.url);
+            const eventTypeId = url.searchParams.get("eventTypeId");
+            const from = url.searchParams.get("from");
+            const to = url.searchParams.get("to");
+            if (!eventTypeId || !from || !to) {
+                throw new ConnectError({
+                    status: 400,
+                    code: "validation_error",
+                    message: "eventTypeId, from and to are required",
+                    endpoint: "/scheduling/slots",
+                });
+            }
+            return json(await client.scheduling.findSlots({
+                workspaceId,
+                eventTypeId,
+                from,
+                to,
+                // Set when offering times to move an existing appointment to, or the
+                // booking blocks its own replacement and the list comes back empty.
+                excludeBookingId: url.searchParams.get("excludeBookingId") ?? undefined,
+                asUser,
+            }));
+        },
+        "GET /scheduling/bookings": async (request) => {
+            const { workspaceId } = await requireWorkspace(request);
+            const asUser = await requireToken(request);
+            const url = new URL(request.url);
+            const limit = Number(url.searchParams.get("limit") ?? 25);
+            return json(await client.scheduling.listBookings({
+                workspaceId,
+                status: url.searchParams.get("status") ?? undefined,
+                hostMemberId: url.searchParams.get("hostMemberId") ?? undefined,
+                from: url.searchParams.get("from") ?? undefined,
+                to: url.searchParams.get("to") ?? undefined,
+                order: url.searchParams.get("order") === "asc" ? "asc" : "desc",
+                cursor: url.searchParams.get("cursor") ?? undefined,
+                limit: Number.isInteger(limit) && limit >= 1 && limit <= 100 ? limit : 25,
+                asUser,
+            }));
+        },
+        "POST /scheduling/bookings": async (request) => {
+            const { workspaceId } = await requireWorkspace(request);
+            const asUser = await requireToken(request);
+            const body = (await request.json().catch(() => null));
+            if (typeof body?.eventTypeId !== "string" ||
+                typeof body.startAt !== "string" ||
+                typeof body.attendee?.name !== "string" ||
+                typeof body.attendee?.phone !== "string") {
+                throw new ConnectError({
+                    status: 400,
+                    code: "validation_error",
+                    message: "eventTypeId, startAt and an attendee name and phone are required",
+                    endpoint: "/scheduling/bookings",
+                });
+            }
+            return json(await client.scheduling.createBooking({
+                workspaceId,
+                eventTypeId: body.eventTypeId,
+                startAt: body.startAt,
+                attendee: {
+                    name: body.attendee.name,
+                    phone: body.attendee.phone,
+                    email: typeof body.attendee.email === "string" ? body.attendee.email : null,
+                },
+                notes: typeof body.notes === "string" ? body.notes : null,
+                asUser,
+            }));
+        },
+        /*
+         * Reschedule and cancel take the booking id in the body rather than the
+         * path, matching `POST /sessions/revoke`. The bridge's route table is
+         * exact-match on `METHOD /path`, so a path parameter would mean a second
+         * matching strategy for two routes.
+         */
+        "POST /scheduling/bookings/reschedule": async (request) => {
+            const { workspaceId } = await requireWorkspace(request);
+            const asUser = await requireToken(request);
+            const body = (await request.json().catch(() => null));
+            if (typeof body?.bookingId !== "string" || typeof body.startAt !== "string") {
+                throw new ConnectError({
+                    status: 400,
+                    code: "validation_error",
+                    message: "bookingId and startAt are required",
+                    endpoint: "/scheduling/bookings/reschedule",
+                });
+            }
+            return json(await client.scheduling.rescheduleBooking({
+                workspaceId,
+                bookingId: body.bookingId,
+                startAt: body.startAt,
+                notes: typeof body.notes === "string" ? body.notes : undefined,
+                asUser,
+            }));
+        },
+        "POST /scheduling/bookings/cancel": async (request) => {
+            const { workspaceId } = await requireWorkspace(request);
+            const asUser = await requireToken(request);
+            const body = (await request.json().catch(() => null));
+            if (typeof body?.bookingId !== "string") {
+                throw new ConnectError({
+                    status: 400,
+                    code: "validation_error",
+                    message: "bookingId is required",
+                    endpoint: "/scheduling/bookings/cancel",
+                });
+            }
+            return json(await client.scheduling.cancelBooking({
+                workspaceId,
+                bookingId: body.bookingId,
+                reason: typeof body.reason === "string" ? body.reason : null,
+                asUser,
+            }));
+        },
         "GET /integrations": async (request) => {
             const { workspaceId } = await requireWorkspace(request);
             return json({ toolkits: await client.integrations.list(workspaceId) });

package/dist/esm/server/resources/contacts.js

@@ -0,0 +1,62 @@
+import { request } from "../http.js";
+import { actingAs } from "./acting-as.js";
+/**
+ * Who a workspace already knows how to reach.
+ *
+ * **This is the telephony identity, not a CRM record.** A contact is keyed by
+ * `primaryPhone` - the one fact every inbound call carries - and it is written
+ * automatically: a voice agent creates one on the first call from a new number
+ * and fills fields in as it learns them. `source` says which kind you are
+ * holding, and it is worth rendering: `call` means an agent guessed and nobody
+ * has confirmed, `manual` means a person typed it.
+ *
+ * **Reference it, do not copy it.** If your application keeps its own customer
+ * records, store this contact's `id` on yours rather than duplicating the
+ * fields. Two writable copies of a person's name with no single owner drift,
+ * and Connect's is the one an agent keeps updating from calls. The id is also
+ * an exact join to anything else keyed by it - `Booking.contactId`, most
+ * usefully - so "which of my records is this appointment for" becomes a lookup
+ * instead of a phone match.
+ *
+ * Read-only for now. Writing into a store with a per-field provenance chain
+ * means declaring where your facts came from and how they merge with a
+ * human's, and nothing needs that yet.
+ */
+export class ContactsResource {
+    transport;
+    constructor(transport) {
+        this.transport = transport;
+    }
+    /**
+     * "Do we already know this number?" - one point read, cheap enough for a
+     * screen pop on every inbound call.
+     *
+     * Resolves to `null` for a number nobody has called from before. That is the
+     * ordinary case for a first-time caller, not an error, which is why it is a
+     * null rather than a thrown `ConnectError`.
+     */
+    async lookupByPhone(input) {
+        const result = await request(this.transport, {
+            method: "GET",
+            path: "/contacts",
+            query: { workspaceId: input.workspaceId, phone: input.phone },
+            headers: actingAs(input.asUser),
+        });
+        return result.contact ?? null;
+    }
+    /**
+     * The record behind an id you already hold.
+     *
+     * Throws `ConnectError` with `code: "not_found"` for an id that does not
+     * exist *or* belongs to another workspace - deliberately the same answer,
+     * since telling those apart would confirm a contact exists somewhere else.
+     */
+    get(contactId, options) {
+        return request(this.transport, {
+            method: "GET",
+            path: `/contacts/${encodeURIComponent(contactId)}`,
+            query: { workspaceId: options.workspaceId },
+            headers: actingAs(options.asUser),
+        });
+    }
+}

package/dist/esm/server/resources/scheduling.js

@@ -1,4 +1,5 @@
 import { request } from "../http.js";
+import { actingAs } from "./acting-as.js";
 /**
  * A subscribing workspace's own calendar.
  *
@@ -18,11 +19,12 @@ export class SchedulingResource {
         this.transport = transport;
     }
     /** What this workspace offers as bookable. Active appointment types only. */
-    async listEventTypes(workspaceId) {
+    async listEventTypes(workspaceId, options = {}) {
         const result = await request(this.transport, {
             method: "GET",
             path: "/scheduling/event-types",
             query: { workspaceId },
+            headers: actingAs(options.asUser),
         });
         // `?? []` for the same reason `apps.list` has it - a collection every
         // caller immediately maps, and a body without the key would hand them
@@ -51,7 +53,9 @@ export class SchedulingResource {
                 eventTypeId: input.eventTypeId,
                 from: toInstant(input.from),
                 to: toInstant(input.to),
+                excludeBookingId: input.excludeBookingId,
             },
+            headers: actingAs(input.asUser),
         });
     }
     /** One page of the workspace's diary. */
@@ -69,6 +73,7 @@ export class SchedulingResource {
                 cursor: input.cursor,
                 limit: input.limit === undefined ? undefined : String(input.limit),
             },
+            headers: actingAs(input.asUser),
         });
     }
     /**
@@ -90,6 +95,31 @@ export class SchedulingResource {
                 attendee: input.attendee,
                 notes: input.notes ?? null,
             },
+            headers: actingAs(input.asUser),
+        });
+    }
+    /**
+     * Moves an appointment to a different time.
+     *
+     * **The original is retired, not edited.** It stays on the diary as
+     * `rescheduled` with `rescheduledToId` pointing at the replacement, and both
+     * come back here - so a booking id you cached still resolves, and still says
+     * where the appointment went.
+     *
+     * A refused move changes nothing: the new slot is claimed before the old one
+     * is released, so a `conflict` leaves the customer with the appointment they
+     * already had. Re-read the slots (with `excludeBookingId`) and offer another.
+     */
+    rescheduleBooking(input) {
+        return request(this.transport, {
+            method: "POST",
+            path: `/scheduling/bookings/${encodeURIComponent(input.bookingId)}/reschedule`,
+            json: {
+                workspaceId: input.workspaceId,
+                startAt: toInstant(input.startAt),
+                notes: input.notes ?? null,
+            },
+            headers: actingAs(input.asUser),
         });
     }
     /**
@@ -104,6 +134,7 @@ export class SchedulingResource {
             method: "POST",
             path: `/scheduling/bookings/${encodeURIComponent(input.bookingId)}/cancel`,
             json: { workspaceId: input.workspaceId, reason: input.reason ?? null },
+            headers: actingAs(input.asUser),
         });
     }
 }

package/dist/types/client/components/booking-calendar.d.ts

@@ -0,0 +1,38 @@
+import { type GridWindow } from "./booking-grid.js";
+export interface ConnectBookingCalendarProps {
+    /**
+     * The business's IANA timezone. **Every instant on the grid is read against
+     * it, never the viewer's** - a workspace's working day must not shift
+     * because a member is travelling.
+     *
+     * Defaults to the host's zone, which is right for the common case where
+     * staff and business share one. Pass it explicitly when they might not.
+     */
+    timeZone?: string;
+    /** Only appointments this member hosts. Omit for the whole workspace's diary. */
+    hostMemberId?: string;
+    /** Narrow the visible band - see `DEFAULT_WINDOW`. */
+    window?: GridWindow;
+    /** Hide the "New appointment" action for a read-only view. */
+    canBook?: boolean;
+    className?: string;
+}
+/**
+ * A week of the workspace's calendar, with booking, rescheduling and
+ * cancelling.
+ *
+ * **Two views, and which one you get is a viewport decision, not a
+ * preference.** A seven-column time grid needs roughly 640px before a column
+ * is wide enough to hold a name; below that it degrades into unreadable
+ * slivers. So the grid is `sm:` and up, and the same week renders as a grouped
+ * agenda underneath - not a cut-down grid, a different and better shape for a
+ * phone. Both read the same data and open the same dialogs.
+ *
+ * Everything it does goes through the bridge as the signed-in member, so
+ * Connect checks *their* `calendar:read` / `calendar:manage` rather than the
+ * host application's key. A member who may look but not book gets the grid and
+ * a refusal on the write, which is the correct shape - see `useBookingActions`.
+ */
+export declare function ConnectBookingCalendar({ timeZone, hostMemberId, window: visibleWindow, canBook, className, }: Readonly<ConnectBookingCalendarProps>): import("react").JSX.Element;
+declare function timeLabel(instant: Date, zone: string): string;
+export { timeLabel as connectBookingTimeLabel };

package/dist/types/client/components/booking-dialogs.d.ts

@@ -0,0 +1,33 @@
+import type { BookableEventType, Booking } from "../../types.js";
+/**
+ * Picking a time, and then who it is for.
+ *
+ * The slot list is read fresh every time this opens and is **never cached
+ * across an open**: it is a snapshot of contention, and offering a time
+ * somebody took ninety seconds ago is how two people end up in the same slot.
+ * The server re-checks inside its transaction regardless, so a stale list
+ * costs a refusal rather than a double booking - this only makes the refusal
+ * rare enough to be surprising when it happens.
+ */
+export declare function ConnectBookingDialog({ isOpen, onOpenChange, eventTypes, initialStartAt, timeZone, onBooked, }: Readonly<{
+    isOpen: boolean;
+    onOpenChange(open: boolean): void;
+    eventTypes: BookableEventType[];
+    initialStartAt: Date;
+    timeZone: string;
+    onBooked(booking: Booking): void;
+}>): import("react").JSX.Element;
+/**
+ * One appointment, and the two things anyone opens it to do.
+ *
+ * Rescheduling re-reads the slots with `excludeBookingId` set to this booking.
+ * Without that the appointment blocks its own replacement, and moving it by
+ * half an hour - the only move most people ever make - offers nothing.
+ */
+export declare function ConnectBookingDetail({ booking, eventType, timeZone, onOpenChange, onChanged, }: Readonly<{
+    booking: Booking;
+    eventType: BookableEventType | null;
+    timeZone: string;
+    onOpenChange(open: boolean): void;
+    onChanged(): void;
+}>): import("react").JSX.Element;

package/dist/types/client/components/booking-grid.d.ts

@@ -0,0 +1,102 @@
+import type { Booking } from "../../types.js";
+/**
+ * The arithmetic behind the week grid, with no React and no fetching - the
+ * same split `slot-computation.ts` uses server-side, and for the same reason:
+ * every timezone and overlap rule is then testable without rendering
+ * anything, and a layout bug is a failing assertion rather than a screenshot
+ * somebody has to notice.
+ *
+ * **Every instant is read against the business's timezone**, never the
+ * viewer's. A workspace in Kolkata whose staff are travelling must not see
+ * their own working day shift; the grid is a picture of when *the business* is
+ * open. That is why every function here takes an explicit `timeZone` rather
+ * than falling back to the host's.
+ */
+export interface ZonedInstant {
+    /** `YYYY-MM-DD` in `timeZone` - the local calendar day this instant falls on. */
+    dateKey: string;
+    /** Minutes since local midnight, `0`-`1439`. */
+    minutes: number;
+}
+/**
+ * An instant, as the local day and minute it lands on in `timeZone`.
+ *
+ * Built from `formatToParts` rather than by adding a fixed offset. An offset
+ * is only correct until a DST boundary, and "add 5.5 hours" is wrong the
+ * moment the same code is pointed at a zone that observes one - which is
+ * exactly the kind of bug that appears twice a year and never in a test.
+ */
+export declare function zonedInstant(instant: Date, timeZone: string): ZonedInstant;
+export interface DayColumn {
+    /** `YYYY-MM-DD` in the grid's timezone. */
+    dateKey: string;
+    /** "Mon 8" - the column heading. */
+    label: string;
+    /** "Sep" etc, for the first column and any month change. */
+    monthLabel: string;
+    /** Midnight of this day, as an instant. Used to build slot query windows. */
+    startsAt: Date;
+    isToday: boolean;
+}
+/**
+ * `count` consecutive days starting at the local day `anchor` falls on.
+ *
+ * Days are stepped by adding 24 hours and re-reading the zone rather than by
+ * incrementing a date field, so a day that is 23 or 25 hours long still
+ * produces the right sequence of `dateKey`s - the midday anchor is what keeps
+ * a DST shift from landing the step on the previous or next day.
+ */
+export declare function dayColumns(anchor: Date, timeZone: string, count: number, now: Date): DayColumn[];
+/**
+ * Local midnight of `dateKey` in `timeZone`, as an instant.
+ *
+ * Solved by probing rather than by arithmetic: guess UTC midnight, read what
+ * local time that actually is, and subtract the difference. One correction is
+ * always enough because a zone's offset cannot change within the few hours the
+ * correction spans - and unlike a fixed-offset formula it is right across DST
+ * and for the half-hour zones (`Asia/Kolkata`, `Australia/Adelaide`) that a
+ * naive implementation quietly breaks on.
+ */
+export declare function dayStartInstant(dateKey: string, timeZone: string): Date;
+export interface PositionedBooking {
+    booking: Booking;
+    dateKey: string;
+    /** Fraction of the visible day, `0`-`1`, from the top of the grid. */
+    top: number;
+    /** Fraction of the visible day. Never `0` - see `MIN_VISIBLE_FRACTION`. */
+    height: number;
+    /** Column index within its overlap cluster, and how many columns that cluster has. */
+    column: number;
+    columns: number;
+    /** True when the appointment extends past the grid's visible window. */
+    clipped: boolean;
+}
+export interface GridWindow {
+    /** Minutes since local midnight the grid starts at - `480` is 08:00. */
+    startMinute: number;
+    endMinute: number;
+}
+/**
+ * Places bookings on the grid, side by side where they collide.
+ *
+ * Overlap handling is the part worth stating. Two appointments at the same
+ * time are not an error - a workspace with two hosts has them constantly - and
+ * stacking them would hide one entirely. So overlapping bookings are grouped
+ * into *clusters* and each cluster is split into equal columns. The cluster is
+ * built transitively: A overlapping B and B overlapping C puts all three in one
+ * cluster even when A and C do not touch, because anything else lets two of
+ * them land on the same column.
+ */
+export declare function layoutBookings(bookings: Booking[], timeZone: string, window: GridWindow): PositionedBooking[];
+/**
+ * The hour labels down the left edge, inclusive of both ends.
+ *
+ * Takes no timezone, deliberately: these label *wall-clock hours on the grid*,
+ * not instants. The grid is already drawn in the business's zone, so "10 am"
+ * means the business's ten - running the label through a zone conversion would
+ * shift it away from the row it sits on.
+ */
+export declare function hourMarks(window: GridWindow): {
+    minute: number;
+    label: string;
+}[];

package/dist/types/client/index.d.ts

@@ -87,3 +87,8 @@ export type { PlanAction, PlanTier, ComparablePlan } from "./components/plan-pri
 export { ConnectWorkspaceSwitcher } from "./components/workspace-switcher.js";
 export type { ConnectWorkspaceSwitcherProps } from "./components/workspace-switcher.js";
 export { useConnectWorkspaces, useConnectWorkspaceMembers } from "./provider.js";
+export { ConnectBookingCalendar } from "./components/booking-calendar.js";
+export type { ConnectBookingCalendarProps } from "./components/booking-calendar.js";
+export { ConnectBookingDialog, ConnectBookingDetail } from "./components/booking-dialogs.js";
+export { useBookableEventTypes, useAvailableSlots, useBookings, useBookingActions, type SlotQuery, type BookingsQuery, } from "./use-scheduling.js";
+export { layoutBookings, dayColumns, zonedInstant, type GridWindow, type PositionedBooking, } from "./components/booking-grid.js";

package/dist/types/client/use-scheduling.d.ts

@@ -0,0 +1,93 @@
+import type { BookableEventType, Booking, BookingAttendee } from "../types.js";
+/**
+ * The bridge's scheduling surface, as hooks.
+ *
+ * Every path here is one of the six the bridge exposes, and every one of them
+ * is resolved *for the signed-in member* - Connect takes the workspace from
+ * their session and checks their own `calendar:read` / `calendar:manage`.
+ * Nothing in this file names a workspace, and nothing should: a browser that
+ * can name a tenant is a browser that can read someone else's diary.
+ */
+/** What this workspace offers as bookable. Active types only. */
+export declare function useBookableEventTypes(): {
+    eventTypes: BookableEventType[];
+    isLoading: boolean;
+    error: string | null;
+};
+export interface SlotQuery {
+    eventTypeId: string;
+    from: Date;
+    to: Date;
+    /**
+     * Set to the booking being moved. Without it the appointment counts as
+     * blocking its own replacement and a reschedule picker comes back empty for
+     * the one adjustment people actually make.
+     */
+    excludeBookingId?: string;
+}
+/**
+ * Free times for one appointment type.
+ *
+ * **Deliberately re-read rather than cached across a session.** A slot list is
+ * a snapshot of contention: anyone else on that calendar - a colleague, a
+ * voice agent mid-call, someone on the public booking link - can take one
+ * between the read and the click. Showing a stale one is how two people are
+ * offered the same minute. The booking call re-checks inside a transaction
+ * anyway, so a stale list costs a refusal rather than a double booking; this
+ * just means the refusal is rare.
+ */
+export declare function useAvailableSlots(query: SlotQuery | null): {
+    slots: import("./index.js").BookingSlot[];
+    timezone: string | null;
+    durationMinutes: number | null;
+    isLoading: boolean;
+    error: string | null;
+    refetch: () => void;
+};
+export interface BookingsQuery {
+    from: Date;
+    to: Date;
+    /** Only appointments this member is hosting. Omit for the whole workspace. */
+    hostMemberId?: string;
+    limit?: number;
+}
+/** One page of the diary, ascending - a forward view, not a history. */
+export declare function useBookings(query: BookingsQuery): {
+    bookings: Booking[];
+    hasMore: boolean;
+    isLoading: boolean;
+    error: string | null;
+    path: string;
+    refetch: () => void;
+};
+export interface BookingActionsState {
+    isPending: boolean;
+    /** The last refusal, written to be shown to the person who clicked. */
+    error: string | null;
+    clearError(): void;
+}
+/**
+ * Book, move and cancel.
+ *
+ * **None of these is optimistic**, and that is not an oversight. Whether a
+ * slot is still free is a question only the server can answer, inside the
+ * transaction that decides it - two people can be holding the same minute
+ * right now. Painting a booking as made and withdrawing it is exactly the lie
+ * the two-phase hold exists to prevent.
+ */
+export declare function useBookingActions(): BookingActionsState & {
+    createBooking(input: {
+        eventTypeId: string;
+        startAt: string;
+        attendee: BookingAttendee;
+        notes?: string | null;
+    }): Promise<Booking | null>;
+    rescheduleBooking(input: {
+        bookingId: string;
+        startAt: string;
+    }): Promise<Booking | null>;
+    cancelBooking(input: {
+        bookingId: string;
+        reason?: string | null;
+    }): Promise<Booking | null>;
+};

package/dist/types/server/client.d.ts

@@ -5,6 +5,7 @@ import { AiResource } from "./resources/ai.js";
 import { DataResource } from "./resources/data.js";
 import { WorkspacesResource } from "./resources/workspaces.js";
 import { SchedulingResource } from "./resources/scheduling.js";
+import { ContactsResource } from "./resources/contacts.js";
 import { KvResource } from "./resources/kv.js";
 import { BillingResource } from "./resources/billing.js";
 import { DriveResource } from "./resources/drive.js";
@@ -78,6 +79,8 @@ export declare class ConnectClient {
     readonly drive: DriveResource;
     /** A subscribing workspace's own calendar - what is bookable, free, and booked. */
     readonly scheduling: SchedulingResource;
+    /** Who a workspace already knows how to reach, by phone or by id. */
+    readonly contacts: ContactsResource;
     /** RAG chat and structured extraction. */
     readonly ai: AiResource;
     /** Your application's own document store - see `DataResource`. */
@@ -112,4 +115,4 @@ export declare class ConnectClient {
     constructor(options: ConnectClientOptions);
 }
 /** Kept in step with `package.json` by `sdk.test.ts`. */
-export declare const SDK_VERSION = "0.17.0";
+export declare const SDK_VERSION = "0.19.0";

package/dist/types/server/index.d.ts

@@ -27,7 +27,8 @@ export type { AnalyticsResource } from "./resources/analytics.js";
 export type { SessionsResource } from "./resources/sessions.js";
 export type { ExecuteIntegrationActionInput, IntegrationsResource } from "./resources/integrations.js";
 export type { PlatformResource } from "./resources/platform.js";
-export type { SchedulingResource, FindSlotsInput, ListBookingsInput, CreateBookingInput, } from "./resources/scheduling.js";
+export type { SchedulingResource, FindSlotsInput, ListBookingsInput, CreateBookingInput, RescheduleBookingInput, } from "./resources/scheduling.js";
+export type { ContactsResource, LookupContactInput } from "./resources/contacts.js";
 /**
  * Webhook verification and a ready-made POST route. Server-only for the
  * obvious reason: the signing secret must never reach a browser bundle.

package/dist/types/server/resources/contacts.d.ts

@@ -0,0 +1,60 @@
+import { type TransportOptions } from "../http.js";
+import type { ConnectContact } from "../../types.js";
+export interface LookupContactInput {
+    workspaceId: string;
+    /**
+     * Any reasonable spelling. `+919000000001`, `919000000001` and
+     * `+91 90000 00001` all resolve to the same contact - the number is
+     * normalized to E.164 before the lookup, because comparing unnormalized is
+     * how a contact that exists reads as absent.
+     */
+    phone: string;
+    /** See `ActingAsOption` on the scheduling resource - same contract. */
+    asUser?: string;
+}
+/**
+ * Who a workspace already knows how to reach.
+ *
+ * **This is the telephony identity, not a CRM record.** A contact is keyed by
+ * `primaryPhone` - the one fact every inbound call carries - and it is written
+ * automatically: a voice agent creates one on the first call from a new number
+ * and fills fields in as it learns them. `source` says which kind you are
+ * holding, and it is worth rendering: `call` means an agent guessed and nobody
+ * has confirmed, `manual` means a person typed it.
+ *
+ * **Reference it, do not copy it.** If your application keeps its own customer
+ * records, store this contact's `id` on yours rather than duplicating the
+ * fields. Two writable copies of a person's name with no single owner drift,
+ * and Connect's is the one an agent keeps updating from calls. The id is also
+ * an exact join to anything else keyed by it - `Booking.contactId`, most
+ * usefully - so "which of my records is this appointment for" becomes a lookup
+ * instead of a phone match.
+ *
+ * Read-only for now. Writing into a store with a per-field provenance chain
+ * means declaring where your facts came from and how they merge with a
+ * human's, and nothing needs that yet.
+ */
+export declare class ContactsResource {
+    private readonly transport;
+    constructor(transport: TransportOptions);
+    /**
+     * "Do we already know this number?" - one point read, cheap enough for a
+     * screen pop on every inbound call.
+     *
+     * Resolves to `null` for a number nobody has called from before. That is the
+     * ordinary case for a first-time caller, not an error, which is why it is a
+     * null rather than a thrown `ConnectError`.
+     */
+    lookupByPhone(input: LookupContactInput): Promise<ConnectContact | null>;
+    /**
+     * The record behind an id you already hold.
+     *
+     * Throws `ConnectError` with `code: "not_found"` for an id that does not
+     * exist *or* belongs to another workspace - deliberately the same answer,
+     * since telling those apart would confirm a contact exists somewhere else.
+     */
+    get(contactId: string, options: {
+        workspaceId: string;
+        asUser?: string;
+    }): Promise<ConnectContact>;
+}