@proteos/sdk 0.52.0 → 0.54.0

package/src/scheduling/types.ts

@@ -0,0 +1,790 @@
+import type { ContactRef, WindowDay } from '../conversation/types.js'
+import type { ResponseMeta, UserRef } from '../types/index.js'
+
+/* =========================================================================
+   scheduling-service wire types — a 1:1 mirror of
+   packages/go/model/scheduling (schedulingmodel) and scheduling/api
+   (schedulingapi). snake_case fields, string enums, ISO timestamps.
+   ========================================================================= */
+
+// ── Enums ────────────────────────────────────────────────────────────────────
+
+/** The calendar backend behind a connection. */
+export type CalendarProvider = 'google' | 'microsoft'
+
+/** The health of our binding to a connector-service grant. */
+export type CalendarConnectionStatus = 'active' | 'error' | 'revoked'
+
+/** What COLLEAGUES see of a calendar's events: nothing, busy blocks, everything. */
+export type CalendarVisibility = 'private' | 'busy_only' | 'full'
+
+/** The mirror state of one calendar. */
+export type CalendarSyncStatus = 'idle' | 'syncing' | 'error'
+
+/** An attendee's RSVP. */
+export type ParticipationStatus = 'needs_action' | 'accepted' | 'declined' | 'tentative'
+
+/** Whether an event blocks its owner's time. */
+export type EventTransparency = 'busy' | 'free'
+
+/** The provider lifecycle state of an event. */
+export type EventStatus = 'confirmed' | 'tentative' | 'cancelled'
+
+/** Provider-side visibility of one event (distinct from CalendarVisibility). */
+export type EventVisibility = 'default' | 'private' | 'public'
+
+/** Who created the row first: the provider (mirrored) or the platform. */
+export type EventSource = 'provider' | 'platform'
+
+/**
+ * Delivery state of a platform write to the provider. `pending_mirror` marks a
+ * host's copy of a meeting written to the ORGANIZER's calendar, merged onto by
+ * that host's own sync (by ical_uid).
+ */
+export type EventWriteStatus = 'synced' | 'pending' | 'pending_mirror' | 'failed'
+
+/** Integrated conferencing minted by the provider. */
+export type ConferencingProvider = 'google_meet' | 'teams'
+
+/** How many of a link's hosts end up in the meeting. */
+export type Assignment = 'single' | 'round_robin' | 'collective'
+
+/** Whom the provider emails about a platform write. */
+export type NotifyMode = 'all' | 'external_only' | 'none'
+
+/** What an edit of a recurring instance targets. */
+export type RecurrenceScope = 'instance' | 'series'
+
+/** How a calendar event type meets. */
+export type LocationKind = 'video' | 'phone' | 'in_person' | 'custom'
+
+/** What an availability constraint does to the window it covers. */
+export type AvailabilityKind = 'available' | 'unavailable'
+
+/** Why a host is not offered at a time (verbose slot reads). */
+export type SlotUnavailabilityReason =
+  | 'no_calendar'
+  | 'outside_hours'
+  | 'blocked'
+  | 'other_event_type'
+  | 'calendar_busy'
+  | 'exclusive_event'
+  | 'minimum_notice'
+  | 'scheduling_window'
+  | 'daily_limit'
+
+// ── Entities ─────────────────────────────────────────────────────────────────
+
+/**
+ * Our binding to one connector-service grant (a `google-calendar` /
+ * `microsoft-calendar` connection of scope user). A user may hold several;
+ * the same provider account cannot be bound twice. Calendars hang off it.
+ */
+export interface CalendarConnection {
+  id: string
+  org_id: string
+  /** The platform user who owns the grant. */
+  owner: UserRef
+  connection_id: string
+  provider: CalendarProvider
+  /** The provider account (e-mail address / UPN), copied from the grant. */
+  external_account_id: string
+  status: CalendarConnectionStatus
+  status_detail?: string
+  last_synced_at?: string
+  created_at: string
+  created_by: UserRef
+  updated_at: string
+  updated_by: UserRef
+}
+
+/** The mirror state of one calendar: change cursor, backfilled window, last outcome. */
+export interface CalendarSync {
+  cursor?: string
+  backfill_from?: string
+  backfill_to?: string
+  last_synced_at?: string
+  status: CalendarSyncStatus
+  error?: string
+}
+
+/**
+ * The open push subscription for one calendar. Google fills channel_id +
+ * resource_id, Microsoft fills subscription_id. Only the HASH of the secret
+ * the provider echoes is stored.
+ */
+export interface CalendarWatch {
+  channel_id?: string
+  resource_id?: string
+  subscription_id?: string
+  client_state_hash?: string
+  expires_at?: string
+}
+
+/**
+ * One provider calendar under a connection, plus the platform's roles for it:
+ * is_synced (mirrored + watched), is_availability_source (its busy time counts
+ * against the owner's slots), is_target (the ONE calendar per user the
+ * platform writes exclusive events to), visibility (what colleagues see).
+ */
+export interface Calendar {
+  id: string
+  org_id: string
+  calendar_connection_id: string
+  /** The calendar's owner (the connection's owner, denormalized). */
+  owner: UserRef
+  provider_calendar_id: string
+  name: string
+  color?: string
+  timezone?: string
+  is_primary: boolean
+  is_readonly: boolean
+  has_integrated_conferencing: boolean
+  is_synced: boolean
+  is_availability_source: boolean
+  is_target: boolean
+  visibility: CalendarVisibility
+  sync: CalendarSync
+  watch: CalendarWatch
+  created_at: string
+  created_by: UserRef
+  updated_at: string
+  updated_by: UserRef
+}
+
+/**
+ * A user's scheduling settings: the zone their hours are expressed in, the
+ * weekly hours themselves ({day, from, until} windows, the sending-rule
+ * shape; empty = bookable any time), what a scheduling page shows about
+ * them, and whether they can be booked at all. One per (org, user).
+ */
+export interface SchedulingProfile {
+  id: string
+  org_id: string
+  user_id: string
+  timezone: string
+  weekly_hours: WindowDay[]
+  display_name?: string
+  headline?: string
+  is_bookable: boolean
+  created_at: string
+  created_by: UserRef
+  updated_at: string
+  updated_by: UserRef
+}
+
+/**
+ * One person or resource on an event: the platform's person snapshot
+ * (ContactRef — the same shape a conversation participant carries) plus the
+ * calendar facts. Hosts of a platform-scheduled event are attendees too
+ * (is_host); the calendar owner's own row is is_self.
+ */
+export interface CalendarAttendee extends ContactRef {
+  response_status: ParticipationStatus
+  is_optional: boolean
+  is_organizer: boolean
+  is_self: boolean
+  /** A platform user whose time this event claims; always false on mirrored events. */
+  is_host: boolean
+  /** Rooms and equipment — never resolved to a contact. */
+  is_resource: boolean
+}
+
+/**
+ * The one seam between the platform's calendar and a module's business
+ * object: the record this event belongs to (an appointment, an interview…).
+ */
+export interface RecordRef {
+  entity_slug: string
+  record_id: string
+}
+
+/**
+ * ONE entry in ONE provider calendar, mirrored two-way. A platform-created row
+ * with is_exclusive claims its owner's time (DB exclusion constraint);
+ * mirrored provider rows never do. All copies of one meeting share ical_uid.
+ */
+export interface CalendarEvent {
+  id: string
+  org_id: string
+  calendar_id: string
+  /** The calendar's owner (denormalized for per-user window reads). */
+  owner: UserRef
+  /** The id in THIS calendar; absent while a platform write is pending. */
+  provider_event_id?: string
+  /** RFC 5545 UID shared by every copy of the meeting. */
+  ical_uid?: string
+  /** The recurring master's id on expanded instances. */
+  series_id?: string
+  is_recurring_instance: boolean
+  /** RRULE / EXDATE lines — series master only. */
+  recurrence?: string[]
+  title: string
+  description?: string
+  start_at: string
+  end_at: string
+  is_all_day: boolean
+  /** The provider's zone for the event — display and all-day boundaries only. */
+  timezone?: string
+  location?: string
+  join_url?: string
+  conferencing_provider?: ConferencingProvider
+  organizer: ContactRef
+  attendees: CalendarAttendee[]
+  owner_response_status: ParticipationStatus
+  transparency: EventTransparency
+  status: EventStatus
+  visibility: EventVisibility
+  etag?: string
+  provider_updated_at?: string
+  source: EventSource
+  is_exclusive: boolean
+  /** Set when the platform scheduled the event through a calendar_event_type / scheduling_link. */
+  type_key?: string
+  link_key?: string
+  record?: RecordRef
+  /** A read where the viewer only sees busy blocks of a colleague's calendar. */
+  is_projected?: boolean
+  write_status: EventWriteStatus
+  write_error?: string
+  /** The tombstone: the provider (or a platform delete) removed the event. */
+  deleted_at?: string
+  created_at: string
+  created_by: UserRef
+  updated_at: string
+  updated_by: UserRef
+}
+
+/** Where events of a type meet; is_integrated_conferencing asks the provider for a Meet / Teams link. */
+export interface EventLocation {
+  kind: LocationKind
+  is_integrated_conferencing: boolean
+  join_url?: string
+  phone?: string
+  address?: string
+  instructions?: string
+}
+
+/**
+ * The *what* of a scheduled event — the reusable preset of slot rules a link,
+ * an internal booking or a module books against. Config, keyed by (org, key).
+ */
+export interface CalendarEventType {
+  org_id: string
+  key: string
+  name: string
+  description?: string
+  color?: string
+  duration_minutes: number
+  /** The candidate grid: 5 | 10 | 15 | 20 | 30 | 60. */
+  slot_interval_minutes: number
+  buffer_before_minutes: number
+  buffer_after_minutes: number
+  minimum_notice_minutes: number
+  /** How far ahead a slot may be taken; 0 = no cap. */
+  scheduling_window_days: number
+  /** Exclusive events of this type per host per day; 0 = no cap. */
+  max_per_day: number
+  location: EventLocation
+  /** Soft reference to conversation-service's conversation_type. */
+  conversation_type_key?: string
+  is_cancel_allowed: boolean
+  is_reschedule_allowed: boolean
+  cancel_notice_minutes: number
+  is_enabled: boolean
+  created_at: string
+  created_by: UserRef
+  updated_at: string
+  updated_by: UserRef
+}
+
+/**
+ * One rule about a user's time on top of their weekly hours: a recurring
+ * window (recurrence_rule = "DTSTART;TZID=…\nRRULE:…", duration_minutes
+ * long, or is_all_day) that opens time (available, also outside the weekly
+ * hours) or blocks it (unavailable). calendar_event_type_keys scopes the rule
+ * to some types: an available window "for intro calls" opens it for them and
+ * keeps every other type out; an unavailable window "for demos" blocks demos
+ * only. Empty = every type.
+ */
+export interface AvailabilityConstraint {
+  id: string
+  org_id: string
+  user_id: string
+  kind: AvailabilityKind
+  recurrence_rule: string
+  duration_minutes: number
+  is_all_day: boolean
+  calendar_event_type_keys: string[]
+  label?: string
+  created_at: string
+  created_by: UserRef
+  updated_at: string
+  updated_by: UserRef
+}
+
+/** One bookable start; host_user_ids = the hosts free for it. */
+export interface Slot {
+  start_at: string
+  end_at: string
+  host_user_ids: string[]
+}
+
+/** Why a host is not offered at a time; calendar_event_id when a mirrored event is the cause. */
+export interface SlotUnavailability {
+  start_at: string
+  end_at: string
+  host_user_id: string
+  reason: SlotUnavailabilityReason
+  calendar_event_id?: string
+}
+
+// ── Requests / queries ───────────────────────────────────────────────────────
+
+/** Creates or replaces a calendar event type (PUT /calendar-event-types/:key). */
+export interface PutCalendarEventTypeRequest {
+  name: string
+  description?: string
+  color?: string
+  duration_minutes: number
+  slot_interval_minutes?: number
+  buffer_before_minutes?: number
+  buffer_after_minutes?: number
+  minimum_notice_minutes?: number
+  scheduling_window_days?: number
+  max_per_day?: number
+  location?: EventLocation
+  conversation_type_key?: string
+  /** Policy flags default to TRUE when absent; send false to switch one off. */
+  is_cancel_allowed?: boolean
+  is_reschedule_allowed?: boolean
+  cancel_notice_minutes?: number
+  is_enabled?: boolean
+}
+
+/** Partial update of a calendar event type; location replaces wholesale. */
+export interface UpdateCalendarEventTypeRequest {
+  name?: string
+  description?: string
+  color?: string
+  duration_minutes?: number
+  slot_interval_minutes?: number
+  buffer_before_minutes?: number
+  buffer_after_minutes?: number
+  minimum_notice_minutes?: number
+  scheduling_window_days?: number
+  max_per_day?: number
+  location?: EventLocation
+  conversation_type_key?: string
+  /** Policy flags default to TRUE when absent; send false to switch one off. */
+  is_cancel_allowed?: boolean
+  is_reschedule_allowed?: boolean
+  cancel_notice_minutes?: number
+  is_enabled?: boolean
+}
+
+export interface ListCalendarEventTypesQuery {
+  is_enabled?: boolean
+  search?: string
+  page?: number
+  page_size?: number
+  sort_by?: string
+  sort_direction?: 'asc' | 'desc'
+}
+
+/**
+ * Adds one rule about a user's time. recurrence_rule is
+ * "DTSTART;TZID=<zone>:<local time>\nRRULE:<rule>" with a quarter-hour DTSTART.
+ */
+export interface CreateAvailabilityConstraintRequest {
+  kind: AvailabilityKind
+  recurrence_rule: string
+  duration_minutes?: number
+  is_all_day?: boolean
+  calendar_event_type_keys?: string[]
+  label?: string
+}
+
+/** Partial update; calendar_event_type_keys present replaces the list. */
+export interface UpdateAvailabilityConstraintRequest {
+  kind?: AvailabilityKind
+  recurrence_rule?: string
+  duration_minutes?: number
+  is_all_day?: boolean
+  calendar_event_type_keys?: string[]
+  label?: string
+}
+
+export interface ListAvailabilityConstraintsQuery {
+  kind?: AvailabilityKind
+  page?: number
+  page_size?: number
+  sort_by?: string
+  sort_direction?: 'asc' | 'desc'
+}
+
+/** Explicit slot rules when no calendar_event_type governs the request. */
+export interface SlotParameters {
+  duration_minutes: number
+  slot_interval_minutes?: number
+  buffer_before_minutes?: number
+  buffer_after_minutes?: number
+  minimum_notice_minutes?: number
+  scheduling_window_days?: number
+  max_per_day?: number
+}
+
+/**
+ * Asks for the bookable starts of some hosts in [from, to) (≤ 31 days).
+ * Exactly one of type_key | link_key | parameters governs the rules;
+ * assignment picks union (single / round_robin) or intersection (collective).
+ * timezone is the requester's zone: slots are grouped by its local day.
+ */
+export interface GetSlotsRequest {
+  type_key?: string
+  link_key?: string
+  parameters?: SlotParameters
+  host_user_ids?: string[]
+  assignment?: Assignment
+  from: string
+  to: string
+  timezone: string
+  is_verbose?: boolean
+}
+
+/** Slots grouped by the requester's local day ("YYYY-MM-DD"); unavailability only when verbose. */
+export interface GetSlotsResponse {
+  slots: Record<string, Slot[]>
+  unavailability?: SlotUnavailability[]
+}
+
+/**
+ * Binds a connector-service grant (a `google-calendar` / `microsoft-calendar`
+ * connection of scope user owned by the caller) to the calendar mirror.
+ */
+export interface CreateCalendarConnectionRequest {
+  connection_id: string
+}
+
+/** Re-activates a repaired connection. Only `active` can be requested. */
+export interface UpdateCalendarConnectionRequest {
+  status?: 'active'
+}
+
+export interface ListCalendarConnectionsQuery {
+  provider?: CalendarProvider
+  status?: CalendarConnectionStatus
+  page?: number
+  page_size?: number
+  sort_by?: string
+  sort_direction?: 'asc' | 'desc'
+}
+
+/**
+ * Changes the platform roles of a calendar. Every field is tri-state;
+ * is_synced flips the mirror on/off, is_target=true demotes the user's
+ * current target calendar in the same transaction.
+ */
+export interface UpdateCalendarRequest {
+  is_synced?: boolean
+  is_availability_source?: boolean
+  is_target?: boolean
+  visibility?: CalendarVisibility
+  color?: string
+}
+
+export interface ListCalendarsQuery {
+  calendar_connection_id?: string
+  is_synced?: boolean
+  is_availability_source?: boolean
+  is_target?: boolean
+  page?: number
+  page_size?: number
+  sort_by?: string
+  sort_direction?: 'asc' | 'desc'
+}
+
+/** Replaces a user's scheduling profile (PUT semantics: every field is the new value). */
+export interface PutSchedulingProfileRequest {
+  timezone: string
+  weekly_hours: WindowDay[]
+  display_name?: string
+  headline?: string
+  is_bookable: boolean
+}
+
+/**
+ * Reads a window of events. user_ids / calendar_ids pick whose calendars
+ * (default: the caller's); colleagues' events come back projected by their
+ * calendar's visibility. from/to are required (≤ 93 days).
+ */
+export interface ListCalendarEventsQuery {
+  user_ids?: string[]
+  calendar_ids?: string[]
+  from: string
+  to: string
+  timezone?: string
+  type_key?: string
+  record_entity_slug?: string
+  record_id?: string
+  contact_id?: string
+  is_deleted_included?: boolean
+}
+
+/** One person to invite on a platform write. */
+export interface CalendarAttendeeRequest {
+  email: string
+  name?: string
+  is_optional?: boolean
+}
+
+/**
+ * Schedules the event for platform users instead of one explicit calendar:
+ * the service resolves each host's target calendar and writes one provider
+ * event owned by the organizer.
+ */
+export interface HostsRequest {
+  user_ids: string[]
+  assignment: Assignment
+  organizer_user_id?: string
+}
+
+/**
+ * Writes an event through to the provider. Exactly one of calendar_id (the
+ * caller's own calendar) or hosts is given. is_exclusive makes the row claim
+ * the owner's time (409 slot_unavailable on overlap).
+ */
+export interface CreateCalendarEventRequest {
+  calendar_id?: string
+  hosts?: HostsRequest
+  title: string
+  description?: string
+  location?: string
+  start_at: string
+  end_at: string
+  is_all_day?: boolean
+  timezone?: string
+  attendees?: CalendarAttendeeRequest[]
+  is_conferencing_requested?: boolean
+  transparency?: EventTransparency
+  visibility?: EventVisibility
+  notify?: NotifyMode
+  is_exclusive?: boolean
+  type_key?: string
+  link_key?: string
+  record?: RecordRef
+}
+
+/**
+ * Partial update; an absent field is left as is. attendees present replaces
+ * the whole list (an empty list clears it).
+ */
+export interface UpdateCalendarEventRequest {
+  title?: string
+  description?: string
+  location?: string
+  start_at?: string
+  end_at?: string
+  is_all_day?: boolean
+  timezone?: string
+  attendees?: CalendarAttendeeRequest[]
+  is_conferencing_requested?: boolean
+  transparency?: EventTransparency
+  visibility?: EventVisibility
+  notify?: NotifyMode
+  type_key?: string
+  record?: RecordRef
+  /** Removes the record back-link (an absent record cannot say so). */
+  is_record_cleared?: boolean
+}
+
+/** Records the caller's RSVP on an event they were invited to. */
+export interface RespondCalendarEventRequest {
+  status: Exclude<ParticipationStatus, 'needs_action'>
+  comment?: string
+}
+
+/** Body of POST /me/calendar-connections/:id/sync. */
+// ── Scheduling links + bookings (phase 6) ───────────────────────────────────
+
+/** Which host a rescheduled link booking lands on. */
+export type RescheduleHost = 'same' | 'any'
+
+/** The entry point for taking a slot: hosts, assignment, governing type. Keyed by (org, key). */
+export interface SchedulingLink {
+  org_id: string
+  key: string
+  name: string
+  /** Types offered: one = pre-defined, several = the booker picks (type_key then required). */
+  calendar_event_type_keys: string[]
+  host_user_ids: string[]
+  assignment: Assignment
+  is_public: boolean
+  is_enabled: boolean
+  /** The booker may pick one of the hosts on the page. */
+  is_host_selectable: boolean
+  reschedule_host: RescheduleHost
+  /** Computed: the public page address (absent without WEB_PUBLIC_URL). */
+  url?: string
+  created_at: string
+  created_by: UserRef
+  updated_at: string
+  updated_by: UserRef
+}
+
+export interface CreateSchedulingLinkRequest {
+  key: string
+  name: string
+  calendar_event_type_keys: string[]
+  host_user_ids: string[]
+  assignment: Assignment
+  is_public?: boolean
+  is_enabled?: boolean
+  is_host_selectable?: boolean
+  reschedule_host?: RescheduleHost
+}
+
+export interface UpdateSchedulingLinkRequest {
+  name?: string
+  calendar_event_type_keys?: string[]
+  host_user_ids?: string[]
+  assignment?: Assignment
+  is_public?: boolean
+  is_enabled?: boolean
+  is_host_selectable?: boolean
+  reschedule_host?: RescheduleHost
+}
+
+export interface ListSchedulingLinksQuery {
+  /** Links offering this type. */
+  type_key?: string
+  is_public?: boolean
+  is_enabled?: boolean
+  search?: string
+  page?: number
+  page_size?: number
+  sort_by?: string
+  sort_direction?: 'asc' | 'desc'
+}
+
+/** The person a link booking is for: by id (contact-bound page) or by email. */
+export interface BookingContact {
+  id?: string
+  name?: string
+  email?: string
+  phone?: string
+}
+
+export interface BookSchedulingLinkRequest {
+  /** Picks the type on a multi-type link (optional when the link offers one). */
+  type_key?: string
+  start_at: string
+  timezone: string
+  contact?: BookingContact
+  notes?: string
+  host_user_id?: string
+}
+
+/** Authenticated booking answer: the event plus the one-time manage token. */
+export interface BookSchedulingLinkResponse extends CalendarEvent {
+  manage_token: string
+  manage_url?: string
+}
+
+export interface PublicEventLocation {
+  kind: LocationKind
+  address?: string
+  instructions?: string
+}
+
+export interface PublicCalendarEventType {
+  key: string
+  name: string
+  description?: string
+  duration_minutes: number
+  location: PublicEventLocation
+  is_cancel_allowed: boolean
+  is_reschedule_allowed: boolean
+  cancel_notice_minutes: number
+}
+
+export interface PublicHost {
+  user_id: string
+  display_name: string
+  headline?: string
+}
+
+/** What the unauthenticated scheduling page sees of a link. */
+export interface PublicSchedulingLink {
+  org_id: string
+  key: string
+  name: string
+  /** Types offered in link order; one = pre-defined, several = show a picker. */
+  types: PublicCalendarEventType[]
+  hosts: PublicHost[]
+  assignment: Assignment
+  is_host_selectable: boolean
+  reschedule_host: RescheduleHost
+  /** Opened with a contact_id the org knows: no name / email asked. */
+  is_contact_bound: boolean
+}
+
+export interface GetPublicSlotsQuery {
+  type_key?: string
+  from: string
+  to: string
+  timezone: string
+  host_user_id?: string
+}
+
+/** A booked event as its contact sees it on the manage page. */
+export interface PublicCalendarEvent {
+  id: string
+  org_id: string
+  title: string
+  start_at: string
+  end_at: string
+  timezone?: string
+  status: EventStatus
+  location: EventLocation
+  join_url?: string
+  link: PublicSchedulingLink
+  host: PublicHost
+  contact: BookingContact
+  is_cancelled: boolean
+  deleted_at?: string
+}
+
+export interface PublicBookSchedulingLinkResponse extends PublicCalendarEvent {
+  manage_token: string
+  manage_url?: string
+}
+
+export interface CancelPublicCalendarEventRequest {
+  token: string
+  reason?: string
+}
+
+export interface ReschedulePublicCalendarEventRequest {
+  token: string
+  start_at: string
+  timezone: string
+  host_user_id?: string
+}
+
+/** Body of POST /me/calendar-connections/:id/sync (mirrors Go UpdateCalendarSyncRequest). */
+export interface UpdateCalendarSyncRequest {
+  /** Drop the change cursors so the worker re-reads the whole window. */
+  is_rebaseline?: boolean
+}
+
+/** Scheduling-local page envelope ({meta, data}) — same shape as the conversation module's. */
+export interface ListResponse<T> {
+  meta: ResponseMeta
+  data: T[]
+}
+
+/** Window reads carry no pagination — the window itself bounds the result. */
+export interface CalendarEventsResponse {
+  data: CalendarEvent[]
+}