// Transport-agnostic calendar gateway contract. JMAP is the only implementation
// today (CalDAV fallback shelved after Phase 0), but callers depend on this
// interface so the transport stays an implementation detail.

// Decrypted, ready-to-use access to one host's Stalwart calendar. Built by the
// CredentialProvisioner from the Host + its encrypted StalwartCredential.
export interface HostCalendarAccess {
  email: string // host mailbox address (HTTP Basic user)
  secret: string // decrypted app password (HTTP Basic pass) — never logged
  jmapSessionUrl: string // .well-known/jmap on the internal Stalwart hostname
  defaultCalendarId?: string
  busyCalendarIds: string[]
}

export interface Interval {
  startUtc: Date
  endUtc: Date
}

export interface CalendarRef {
  id: string
  name: string
}

// The event we write when a booking is confirmed. Times are UTC; hostTimezone is
// the IANA zone the JSCalendar local start/end are expressed in.
export interface BookingEvent {
  uid: string // client-generated, idempotent across retries
  title: string
  description?: string
  startUtc: Date
  endUtc: Date
  hostTimezone: string
  location?: string
  hostEmail: string
  attendeeName: string
  attendeeEmail: string
}

// Per-call tuning for free/busy resolution.
export interface BusyOptions {
  // When true, all-day events are excluded from the returned busy intervals
  // (best-effort — see JmapCalendarGateway.getBusyIntervals). Default false:
  // every busy marker counts.
  ignoreAllDayEvents?: boolean
}

export interface CalendarGateway {
  listCalendars(access: HostCalendarAccess): Promise<CalendarRef[]>
  // Busy intervals within [fromUtc, toUtc), recurrence already expanded, in UTC.
  getBusyIntervals(access: HostCalendarAccess, fromUtc: Date, toUtc: Date, options?: BusyOptions): Promise<Interval[]>
  // Returns the server-assigned event id (distinct from the UID).
  createEvent(access: HostCalendarAccess, event: BookingEvent): Promise<{ uid: string; id: string }>
  deleteEvent(access: HostCalendarAccess, eventId: string): Promise<void>
  validateCredential(access: HostCalendarAccess): Promise<boolean>
}
