@cosmoops/connect-sdk 0.16.1 → 0.18.0

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

@@ -4,6 +4,7 @@ import { AppsResource } from "./resources/apps.js";
 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 { KvResource } from "./resources/kv.js";
 import { BillingResource } from "./resources/billing.js";
 import { DriveResource } from "./resources/drive.js";
@@ -75,6 +76,8 @@ export declare class ConnectClient {
     readonly billing: BillingResource;
     /** Files in a workspace's Drive. */
     readonly drive: DriveResource;
+    /** A subscribing workspace's own calendar - what is bookable, free, and booked. */
+    readonly scheduling: SchedulingResource;
     /** RAG chat and structured extraction. */
     readonly ai: AiResource;
     /** Your application's own document store - see `DataResource`. */
@@ -109,4 +112,4 @@ export declare class ConnectClient {
     constructor(options: ConnectClientOptions);
 }
 /** Kept in step with `package.json` by `sdk.test.ts`. */
-export declare const SDK_VERSION = "0.16.1";
+export declare const SDK_VERSION = "0.18.0";

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

@@ -27,6 +27,7 @@ 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, RescheduleBookingInput, } from "./resources/scheduling.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/scheduling.d.ts

@@ -0,0 +1,136 @@
+import { type TransportOptions } from "../http.js";
+import type { BookableEventType, Booking, RescheduledBooking, BookingAttendee, BookingSlots, BookingStatus, ListBookingsPage } from "../../types.js";
+/**
+ * Present on every method here.
+ *
+ * With `asUser`, Connect derives the workspace from **that member's session**
+ * and ignores `workspaceId`, then checks their own `calendar:read` /
+ * `calendar:manage`. Without it the call is your server acting for a workspace
+ * you name, gated only on your application being installed there. The bridge
+ * always sends it - a browser must never be trusted to name a tenant, and an
+ * end user of your app is not automatically allowed to book on their
+ * employer's calendar.
+ */
+export interface ActingAsOption {
+    /** The signed-in member's opaque Connect session token. */
+    asUser?: string;
+}
+export interface FindSlotsInput extends ActingAsOption {
+    workspaceId: string;
+    eventTypeId: string;
+    /** ISO-8601 instant, or a `Date`. */
+    from: string | Date;
+    to: string | Date;
+    /**
+     * A booking to treat as if it were not there - **set this when offering
+     * times to move an existing appointment to.**
+     *
+     * Without it the appointment counts as blocking its own replacement, so the
+     * adjustment people actually make - same day, half an hour later - comes
+     * back with nothing available.
+     */
+    excludeBookingId?: string;
+}
+export interface RescheduleBookingInput extends ActingAsOption {
+    workspaceId: string;
+    bookingId: string;
+    /** The new time, from a `findSlots` result, passed back unchanged. */
+    startAt: string | Date;
+    /** Replaces the original note when given; it carries over otherwise. */
+    notes?: string | null;
+}
+export interface ListBookingsInput extends ActingAsOption {
+    workspaceId: string;
+    status?: BookingStatus;
+    /** A Connect workspace member id - only bookings that committed them. */
+    hostMemberId?: string;
+    from?: string | Date;
+    to?: string | Date;
+    /** `asc` for a forward diary, `desc` (the default) for a history. */
+    order?: "asc" | "desc";
+    cursor?: string;
+    limit?: number;
+}
+export interface CreateBookingInput extends ActingAsOption {
+    workspaceId: string;
+    eventTypeId: string;
+    /**
+     * The `startAt` from a `findSlots` result, passed back unchanged.
+     *
+     * Re-deriving it from a local wall time is how an integration books an hour
+     * that was never offered - the slot list is computed in the *business's*
+     * timezone, which is rarely the one your process is running in.
+     */
+    startAt: string | Date;
+    attendee: BookingAttendee;
+    notes?: string | null;
+}
+/**
+ * A subscribing workspace's own calendar.
+ *
+ * **There is one calendar, not one per application.** A booking made here
+ * appears on the workspace's own screen immediately, and a slot their
+ * receptionist just took is gone from your next `findSlots`. That is the
+ * reason to read it through Connect rather than keeping a copy: two calendars
+ * double-book, and nothing reconciles them afterwards.
+ *
+ * Every method needs a live subscription to your application in the workspace
+ * you name. The key says which application is calling; the subscription is
+ * what makes you welcome in a given tenant.
+ */
+export declare class SchedulingResource {
+    private readonly transport;
+    constructor(transport: TransportOptions);
+    /** What this workspace offers as bookable. Active appointment types only. */
+    listEventTypes(workspaceId: string, options?: ActingAsOption): Promise<BookableEventType[]>;
+    /**
+     * Free times for one appointment type over one window.
+     *
+     * **Advisory by construction.** Between this answer and `createBooking`,
+     * anyone else on that calendar can take any of these - a member, a voice
+     * agent mid-call, someone on the workspace's public booking link. That is
+     * why `createBooking` can answer `409`, and why that is an ordinary outcome
+     * rather than a fault.
+     *
+     * The window is clamped silently to now and to the appointment type's own
+     * booking horizon, so asking for a year of a sixty-day type returns sixty
+     * days rather than an error.
+     */
+    findSlots(input: FindSlotsInput): Promise<BookingSlots>;
+    /** One page of the workspace's diary. */
+    listBookings(input: ListBookingsInput): Promise<ListBookingsPage>;
+    /**
+     * Takes one of the times `findSlots` offered.
+     *
+     * Holds and confirms in one call - you already have the attendee, so there
+     * is no half-finished state for your integration to remember. The slot is
+     * re-checked inside a transaction, so a time taken since you read it throws
+     * a `ConnectError` with `code: "conflict"` rather than double-booking.
+     */
+    createBooking(input: CreateBookingInput): Promise<Booking>;
+    /**
+     * 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: RescheduleBookingInput): Promise<RescheduledBooking>;
+    /**
+     * Frees the slot and records why.
+     *
+     * Not a deletion: the booking stays on the diary as `cancelled` with the
+     * reason, which is what makes a late cancellation something anyone can look
+     * up afterwards.
+     */
+    cancelBooking(input: ActingAsOption & {
+        workspaceId: string;
+        bookingId: string;
+        reason?: string | null;
+    }): Promise<Booking>;
+}

package/dist/types/types.d.ts

@@ -1140,3 +1140,87 @@ export interface ConnectWorkspaceMember {
     granted: string[];
     role: string | null;
 }
+/**
+ * One bookable thing a workspace offers - "15-minute intro call", "site
+ * survey".
+ *
+ * `locationKind` and never the location itself: the address or the meeting
+ * link belongs to whoever booked, and this is a catalogue.
+ */
+export interface BookableEventType {
+    id: string;
+    /** Stable and readable, unique within the workspace - branch on this, not `id`. */
+    slug: string;
+    name: string;
+    description: string | null;
+    durationMinutes: number;
+    locationKind: "phone" | "address" | "link";
+}
+export interface BookingSlot {
+    /** ISO-8601 instant. Pass this back to `createBooking` unchanged. */
+    startAt: string;
+    endAt: string;
+}
+export interface BookingSlots {
+    /**
+     * The **business's** IANA timezone, not yours and not your user's - what to
+     * render a slot's wall time in. A slot shown in the viewer's zone is an hour
+     * the business may not be open.
+     */
+    timezone: string;
+    durationMinutes: number;
+    slots: BookingSlot[];
+}
+export interface BookingAttendee {
+    name: string;
+    phone: string;
+    email?: string | null;
+}
+export type BookingStatus = "hold" | "confirmed" | "cancelled" | "rescheduled" | "no_show";
+/**
+ * Where a booking came from - usually the first question anyone asks about an
+ * appointment they did not expect.
+ *
+ * `api` is your integration; `portal` is the workspace's own screen or its
+ * public booking link; `agent-call` is a voice agent, mid-call.
+ */
+export type BookingSource = "agent-call" | "portal" | "api";
+export interface Booking {
+    id: string;
+    eventTypeId: string;
+    status: BookingStatus;
+    /** ISO-8601 instants. */
+    startAt: string;
+    endAt: string;
+    /** The zone the two parties agreed the time in, frozen at booking. */
+    timezone: string;
+    attendee: {
+        name: string;
+        phone: string;
+        email: string | null;
+    };
+    notes: string | null;
+    source: BookingSource;
+    cancelledReason: string | null;
+    /**
+     * Set when `status` is `rescheduled` - the booking that replaced this one.
+     *
+     * Rescheduling retires a booking rather than moving its `startAt`, so an id
+     * you cached still resolves and still tells you where the appointment went.
+     */
+    rescheduledToId: string | null;
+    createdAt: string;
+}
+export interface RescheduledBooking {
+    /** The new appointment. This is the live one. */
+    booking: Booking;
+    /** The retired original, now `rescheduled` and pointing at `booking`. */
+    previous: Booking;
+}
+export interface ListBookingsPage {
+    bookings: Booking[];
+    /** Pass back as `cursor`. A cursor belongs to one set of filters. */
+    nextCursor: string | null;
+    hasMore: boolean;
+    totalCount: number;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmoops/connect-sdk",
-  "version": "0.16.1",
+  "version": "0.18.0",
   "description": "Official server-side SDK for the CosmoOps Connect platform API - Login with Connect, entitlements, billing and metering.",
   "license": "SEE LICENSE IN LICENSE",
   "type": "commonjs",