@cosmoops/connect-sdk 0.16.1 → 0.17.0

package/CHANGELOG.md

@@ -3,6 +3,65 @@
 `@cosmoops/connect-sdk` follows semver, with the 0.x convention that **minor
 versions may carry breaking changes** and patch versions never do.
 
+## 0.17.0
+
+### Added
+
+- **`connect.scheduling.*` - a subscribing workspace's own calendar.**
+
+  ```ts
+  const eventTypes = await connect.scheduling.listEventTypes(workspaceId);
+  const { slots, timezone } = await connect.scheduling.findSlots({
+    workspaceId,
+    eventTypeId: eventTypes[0].id,
+    from: new Date(),
+    to: nextWeek,
+  });
+  const booking = await connect.scheduling.createBooking({
+    workspaceId,
+    eventTypeId: eventTypes[0].id,
+    startAt: slots[0].startAt,
+    attendee: { name: "Priya", phone: "+919000000001" },
+  });
+  ```
+
+  Five methods - `listEventTypes`, `findSlots`, `listBookings`,
+  `createBooking`, `cancelBooking` - against the same calendar the workspace's
+  own team configures and its voice agent books into. A booking you make shows
+  up on their 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.
+
+  Needs a key scoped to `calendar:read` (and `calendar:write` to book), **and**
+  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. A workspace that has not installed your application
+  answers `403` with the same message as an unknown workspace id.
+
+  Two things to hold onto when integrating:
+
+  - **`findSlots` is advisory.** Between reading it and booking, anyone else on
+    that calendar can take a slot - a member, a voice agent mid-call, someone on
+    the workspace's public booking link. `createBooking` re-checks inside a
+    transaction and throws a `ConnectError` with `code: "conflict"` rather than
+    double-booking. Handle that as an ordinary outcome and offer the next time;
+    it is not an error condition.
+  - **`timezone` is the business's, not the viewer's.** It is 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.
+
+- New exported types: `BookableEventType`, `BookingSlot`, `BookingSlots`,
+  `Booking`, `BookingAttendee`, `BookingStatus`, `BookingSource`,
+  `ListBookingsPage`, and the `SchedulingResource` input types from
+  `@cosmoops/connect-sdk/server`.
+
+- `ConnectError.code` can now be `"conflict"` - today only from
+  `createBooking`. Nothing that switched on the previous codes stops
+  compiling: `code` is `string`, deliberately, so a new one reaches a partner
+  as a case to handle rather than a type error on a published package they
+  cannot patch.
+
 ## 0.16.1
 
 ### Fixed

package/README.md

@@ -342,6 +342,7 @@ try {
 | `entitlements` | `getReadiness` · `getSubscription` · `hasFeature` |
 | `billing` | `listPlans` · `getAddonUsage` · `consumeAddon` |
 | `drive` | `upload` · `getFileUrl` · `getPreviewUrl` |
+| `scheduling` | `listEventTypes` · `findSlots` · `listBookings` · `createBooking` · `cancelBooking` |
 | `ai` | `chat` · `extract` |
 | `otp` | `send` · `verify` |
 | `logs` | `write` |
@@ -349,6 +350,39 @@ try {
 | `sessions` | `list` · `revoke` · `revokeOthers` |
 | `integrations` | `list` · `initiateConnect` · `disconnect` · `execute` |
 
+### Booking on a workspace's calendar
+
+One calendar per workspace - the same one their team configures, and the same
+one a voice agent books into. Needs `calendar:read` (plus `calendar:write` to
+book) and a live subscription to your application in that workspace.
+
+```ts
+const eventTypes = await client.scheduling.listEventTypes(workspaceId);
+const { slots, timezone } = await client.scheduling.findSlots({
+  workspaceId,
+  eventTypeId: eventTypes[0].id,
+  from: new Date(),
+  to: nextWeek,
+});
+
+try {
+  await client.scheduling.createBooking({
+    workspaceId,
+    eventTypeId: eventTypes[0].id,
+    startAt: slots[0].startAt,   // exactly as findSlots gave it
+    attendee: { name, phone },
+  });
+} catch (error) {
+  if (error instanceof ConnectError && error.code === "conflict") {
+    // Someone took it between the two calls. Re-read and offer the next one -
+    // this is an ordinary outcome on a shared calendar, not a failure.
+  }
+}
+```
+
+`timezone` is the **business's** zone, not your user's - render the wall time in
+it, or you will offer an hour they are not open.
+
 ### Attributing a log to a user
 
 ```ts

package/dist/cjs/server/client.js

@@ -6,6 +6,7 @@ const apps_js_1 = require("./resources/apps.js");
 const ai_js_1 = require("./resources/ai.js");
 const data_js_1 = require("./resources/data.js");
 const workspaces_js_1 = require("./resources/workspaces.js");
+const scheduling_js_1 = require("./resources/scheduling.js");
 const kv_js_1 = require("./resources/kv.js");
 const billing_js_1 = require("./resources/billing.js");
 const drive_js_1 = require("./resources/drive.js");
@@ -79,6 +80,8 @@ class ConnectClient {
     billing;
     /** Files in a workspace's Drive. */
     drive;
+    /** A subscribing workspace's own calendar - what is bookable, free, and booked. */
+    scheduling;
     /** RAG chat and structured extraction. */
     ai;
     /** Your application's own document store - see `DataResource`. */
@@ -127,6 +130,7 @@ class ConnectClient {
         this.entitlements = new entitlements_js_1.EntitlementsResource(transport);
         this.billing = new billing_js_1.BillingResource(transport);
         this.drive = new drive_js_1.DriveResource(transport);
+        this.scheduling = new scheduling_js_1.SchedulingResource(transport);
         this.ai = new ai_js_1.AiResource(transport);
         this.data = new data_js_1.DataResource(transport);
         this.kv = new kv_js_1.KvResource(transport);
@@ -142,4 +146,4 @@ class ConnectClient {
 }
 exports.ConnectClient = ConnectClient;
 /** Kept in step with `package.json` by `sdk.test.ts`. */
-exports.SDK_VERSION = "0.16.1";
+exports.SDK_VERSION = "0.17.0";

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

@@ -0,0 +1,122 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SchedulingResource = void 0;
+const http_js_1 = require("../http.js");
+/**
+ * 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.
+ */
+class SchedulingResource {
+    transport;
+    constructor(transport) {
+        this.transport = transport;
+    }
+    /** What this workspace offers as bookable. Active appointment types only. */
+    async listEventTypes(workspaceId) {
+        const result = await (0, http_js_1.request)(this.transport, {
+            method: "GET",
+            path: "/scheduling/event-types",
+            query: { workspaceId },
+        });
+        // `?? []` for the same reason `apps.list` has it - a collection every
+        // caller immediately maps, and a body without the key would hand them
+        // `undefined` past every status check in between.
+        return result.eventTypes ?? [];
+    }
+    /**
+     * 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) {
+        return (0, http_js_1.request)(this.transport, {
+            method: "GET",
+            path: "/scheduling/slots",
+            query: {
+                workspaceId: input.workspaceId,
+                eventTypeId: input.eventTypeId,
+                from: toInstant(input.from),
+                to: toInstant(input.to),
+            },
+        });
+    }
+    /** One page of the workspace's diary. */
+    listBookings(input) {
+        return (0, http_js_1.request)(this.transport, {
+            method: "GET",
+            path: "/scheduling/bookings",
+            query: {
+                workspaceId: input.workspaceId,
+                status: input.status,
+                hostMemberId: input.hostMemberId,
+                from: input.from ? toInstant(input.from) : undefined,
+                to: input.to ? toInstant(input.to) : undefined,
+                order: input.order,
+                cursor: input.cursor,
+                limit: input.limit === undefined ? undefined : String(input.limit),
+            },
+        });
+    }
+    /**
+     * 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) {
+        return (0, http_js_1.request)(this.transport, {
+            method: "POST",
+            path: "/scheduling/bookings",
+            json: {
+                workspaceId: input.workspaceId,
+                eventTypeId: input.eventTypeId,
+                startAt: toInstant(input.startAt),
+                attendee: input.attendee,
+                notes: input.notes ?? null,
+            },
+        });
+    }
+    /**
+     * 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) {
+        return (0, http_js_1.request)(this.transport, {
+            method: "POST",
+            path: `/scheduling/bookings/${encodeURIComponent(input.bookingId)}/cancel`,
+            json: { workspaceId: input.workspaceId, reason: input.reason ?? null },
+        });
+    }
+}
+exports.SchedulingResource = SchedulingResource;
+/**
+ * A `Date` or an already-ISO string, as the ISO-8601 instant the API takes.
+ *
+ * `toISOString()` rather than any local formatting: these are instants, and a
+ * wall time without a zone is the one input this API cannot interpret.
+ */
+function toInstant(value) {
+    return typeof value === "string" ? value : value.toISOString();
+}

package/dist/esm/server/client.js

@@ -3,6 +3,7 @@ import { AppsResource } from "./resources/apps.js";
 import { AiResource } from "./resources/ai.js";
 import { DataResource, storePassthrough } 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";
@@ -76,6 +77,8 @@ export class ConnectClient {
     billing;
     /** Files in a workspace's Drive. */
     drive;
+    /** A subscribing workspace's own calendar - what is bookable, free, and booked. */
+    scheduling;
     /** RAG chat and structured extraction. */
     ai;
     /** Your application's own document store - see `DataResource`. */
@@ -124,6 +127,7 @@ export class ConnectClient {
         this.entitlements = new EntitlementsResource(transport);
         this.billing = new BillingResource(transport);
         this.drive = new DriveResource(transport);
+        this.scheduling = new SchedulingResource(transport);
         this.ai = new AiResource(transport);
         this.data = new DataResource(transport);
         this.kv = new KvResource(transport);
@@ -138,4 +142,4 @@ export class ConnectClient {
     }
 }
 /** Kept in step with `package.json` by `sdk.test.ts`. */
-export const SDK_VERSION = "0.16.1";
+export const SDK_VERSION = "0.17.0";

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

@@ -0,0 +1,118 @@
+import { request } from "../http.js";
+/**
+ * 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 class SchedulingResource {
+    transport;
+    constructor(transport) {
+        this.transport = transport;
+    }
+    /** What this workspace offers as bookable. Active appointment types only. */
+    async listEventTypes(workspaceId) {
+        const result = await request(this.transport, {
+            method: "GET",
+            path: "/scheduling/event-types",
+            query: { workspaceId },
+        });
+        // `?? []` for the same reason `apps.list` has it - a collection every
+        // caller immediately maps, and a body without the key would hand them
+        // `undefined` past every status check in between.
+        return result.eventTypes ?? [];
+    }
+    /**
+     * 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) {
+        return request(this.transport, {
+            method: "GET",
+            path: "/scheduling/slots",
+            query: {
+                workspaceId: input.workspaceId,
+                eventTypeId: input.eventTypeId,
+                from: toInstant(input.from),
+                to: toInstant(input.to),
+            },
+        });
+    }
+    /** One page of the workspace's diary. */
+    listBookings(input) {
+        return request(this.transport, {
+            method: "GET",
+            path: "/scheduling/bookings",
+            query: {
+                workspaceId: input.workspaceId,
+                status: input.status,
+                hostMemberId: input.hostMemberId,
+                from: input.from ? toInstant(input.from) : undefined,
+                to: input.to ? toInstant(input.to) : undefined,
+                order: input.order,
+                cursor: input.cursor,
+                limit: input.limit === undefined ? undefined : String(input.limit),
+            },
+        });
+    }
+    /**
+     * 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) {
+        return request(this.transport, {
+            method: "POST",
+            path: "/scheduling/bookings",
+            json: {
+                workspaceId: input.workspaceId,
+                eventTypeId: input.eventTypeId,
+                startAt: toInstant(input.startAt),
+                attendee: input.attendee,
+                notes: input.notes ?? null,
+            },
+        });
+    }
+    /**
+     * 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) {
+        return request(this.transport, {
+            method: "POST",
+            path: `/scheduling/bookings/${encodeURIComponent(input.bookingId)}/cancel`,
+            json: { workspaceId: input.workspaceId, reason: input.reason ?? null },
+        });
+    }
+}
+/**
+ * A `Date` or an already-ISO string, as the ISO-8601 instant the API takes.
+ *
+ * `toISOString()` rather than any local formatting: these are instants, and a
+ * wall time without a zone is the one input this API cannot interpret.
+ */
+function toInstant(value) {
+    return typeof value === "string" ? value : value.toISOString();
+}

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.17.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, } 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,91 @@
+import { type TransportOptions } from "../http.js";
+import type { BookableEventType, Booking, BookingAttendee, BookingSlots, BookingStatus, ListBookingsPage } from "../../types.js";
+export interface FindSlotsInput {
+    workspaceId: string;
+    eventTypeId: string;
+    /** ISO-8601 instant, or a `Date`. */
+    from: string | Date;
+    to: string | Date;
+}
+export interface ListBookingsInput {
+    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 {
+    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): 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>;
+    /**
+     * 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: {
+        workspaceId: string;
+        bookingId: string;
+        reason?: string | null;
+    }): Promise<Booking>;
+}

package/dist/types/types.d.ts

@@ -1140,3 +1140,74 @@ 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;
+    createdAt: string;
+}
+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.17.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",