API reference

/** Pass `clientSecret` to Stripe.js `confirmCardSetup` in the browser. */
export interface SetupIntent {
  id: ID;
  clientSecret: string;
  /** Gateway publishable key for initializing Stripe.js. */
  publishableKey: string | null;
}

export type ID = string;

export interface SignupRequest {
  businessName: string;
  timeZone: string;
  adminName: string;
  adminEmail: string;
  password: string;
  /** Billing product code of the base plan, e.g. "plan_standard". */
  planId: string;
  /** A SetupIntent from POST /api/v1/signup/setup-intents that the browser confirmed with Stripe.js. */
  setupIntentId: ID;
}

/** Pass `clientSecret` to Stripe.js `confirmCardSetup` in the browser. */
export interface SetupIntent {
  id: ID;
  clientSecret: string;
  /** Gateway publishable key for initializing Stripe.js. */
  publishableKey: string | null;
}

export type ID = string;

export interface AuthResponse {
  user: User;
  account: Account;
  /** RS256 JWT. Send as `Authorization: Bearer <accessToken>` to Accounts and Billing. */
  accessToken: string;
  expiresIn: number;
  /** Single use: POST /api/v1/auth/refresh returns a new one. */
  refreshToken: string;
  refreshExpiresIn: number;
  tokenType: "Bearer";
  /** Only on registration: `pending_payment` if the plan charge couldn't be confirmed yet. */
  planStatus?: "active" | "pending_payment" | null;
}

export interface User {
  id: ID;
  accountId: ID;
  email: string;
  name: string;
  role: UserRole;
  createdAt: ISODate;
}

export type UserRole = "admin" | "user";

/** ISO-8601 timestamp, e.g. "2026-10-28T14:03:00Z" */
export type ISODate = string;

/**
 * The business account. Identity fields come from Accounts; the rest come live
 * from Billing and are all null when Billing can't be reached (`billingAvailable: false`).
 */
export interface Account {
  id: ID;
  businessName: string;
  /** IANA zone, fixed after signup. Governs billing periods and business hours. */
  timeZone: string;
  /** SIP domain phones register at. */
  sipDomain: string;
  createdAt: ISODate;
  billingAvailable: boolean;
  status: AccountStatus | null;
  /** `pending` until the base plan is paid; no calling until `active`. */
  activationState: "pending" | "active" | null;
  /** `blocked` when outgoing calls are blocked. */
  restriction: "active" | "blocked" | null;
  canCallOutgoing: boolean | null;
  /** Calls outside the US, including other +1 countries. Needs the international calling add-on. */
  canCallInternational: boolean | null;
  /** Needs the call recording add-on. */
  canRecord: boolean | null;
  /** Billing product code of the active base plan, e.g. "plan_standard". */
  planId: string | null;
  includedExtensions: number | null;
  currentPeriodStart: ISODate | null;
  currentPeriodEnd: ISODate | null;
  /** Shared included US minutes this period. */
  includedMinutesGranted: number | null;
  includedMinutesUsed: number | null;
  addons: Addon[] | null;
}

export type AccountStatus = "active" | "past_due";

/**
 * An add-on's state, as reported by Billing. Buy one with POST /v1/quotes and
 * POST /v1/purchases; remove or keep it with the /v1/subscriptions/items routes.
 */
export interface Addon {
  key: AddonKey;
  name: string;
  /** The add-on works right now. */
  enabled: boolean;
  /** Removed: keeps working until `worksUntil`, then is not renewed. */
  removing: boolean;
  worksUntil: ISODate | null;
  /** Price per 7-day period; null when Billing has no approved price. */
  priceCents: Cents | null;
  /** False when the add-on can't be bought right now. */
  priceAvailable: boolean;
}

export type AddonKey = "international_calling" | "call_recording";

/** Amount in US cents. Per-call amounts and per-minute rates may be fractional. */
export type Cents = number;

export interface LoginRequest {
  email: string;
  password: string;
}

export interface AuthResponse {
  user: User;
  account: Account;
  /** RS256 JWT. Send as `Authorization: Bearer <accessToken>` to Accounts and Billing. */
  accessToken: string;
  expiresIn: number;
  /** Single use: POST /api/v1/auth/refresh returns a new one. */
  refreshToken: string;
  refreshExpiresIn: number;
  tokenType: "Bearer";
  /** Only on registration: `pending_payment` if the plan charge couldn't be confirmed yet. */
  planStatus?: "active" | "pending_payment" | null;
}

export interface User {
  id: ID;
  accountId: ID;
  email: string;
  name: string;
  role: UserRole;
  createdAt: ISODate;
}

export type ID = string;

export type UserRole = "admin" | "user";

/** ISO-8601 timestamp, e.g. "2026-10-28T14:03:00Z" */
export type ISODate = string;

/**
 * The business account. Identity fields come from Accounts; the rest come live
 * from Billing and are all null when Billing can't be reached (`billingAvailable: false`).
 */
export interface Account {
  id: ID;
  businessName: string;
  /** IANA zone, fixed after signup. Governs billing periods and business hours. */
  timeZone: string;
  /** SIP domain phones register at. */
  sipDomain: string;
  createdAt: ISODate;
  billingAvailable: boolean;
  status: AccountStatus | null;
  /** `pending` until the base plan is paid; no calling until `active`. */
  activationState: "pending" | "active" | null;
  /** `blocked` when outgoing calls are blocked. */
  restriction: "active" | "blocked" | null;
  canCallOutgoing: boolean | null;
  /** Calls outside the US, including other +1 countries. Needs the international calling add-on. */
  canCallInternational: boolean | null;
  /** Needs the call recording add-on. */
  canRecord: boolean | null;
  /** Billing product code of the active base plan, e.g. "plan_standard". */
  planId: string | null;
  includedExtensions: number | null;
  currentPeriodStart: ISODate | null;
  currentPeriodEnd: ISODate | null;
  /** Shared included US minutes this period. */
  includedMinutesGranted: number | null;
  includedMinutesUsed: number | null;
  addons: Addon[] | null;
}

export type AccountStatus = "active" | "past_due";

/**
 * An add-on's state, as reported by Billing. Buy one with POST /v1/quotes and
 * POST /v1/purchases; remove or keep it with the /v1/subscriptions/items routes.
 */
export interface Addon {
  key: AddonKey;
  name: string;
  /** The add-on works right now. */
  enabled: boolean;
  /** Removed: keeps working until `worksUntil`, then is not renewed. */
  removing: boolean;
  worksUntil: ISODate | null;
  /** Price per 7-day period; null when Billing has no approved price. */
  priceCents: Cents | null;
  /** False when the add-on can't be bought right now. */
  priceAvailable: boolean;
}

export type AddonKey = "international_calling" | "call_recording";

/** Amount in US cents. Per-call amounts and per-minute rates may be fractional. */
export type Cents = number;

export interface RefreshRequest {
  refreshToken: string;
}

export interface AuthResponse {
  user: User;
  account: Account;
  /** RS256 JWT. Send as `Authorization: Bearer <accessToken>` to Accounts and Billing. */
  accessToken: string;
  expiresIn: number;
  /** Single use: POST /api/v1/auth/refresh returns a new one. */
  refreshToken: string;
  refreshExpiresIn: number;
  tokenType: "Bearer";
  /** Only on registration: `pending_payment` if the plan charge couldn't be confirmed yet. */
  planStatus?: "active" | "pending_payment" | null;
}

export interface User {
  id: ID;
  accountId: ID;
  email: string;
  name: string;
  role: UserRole;
  createdAt: ISODate;
}

export type ID = string;

export type UserRole = "admin" | "user";

/** ISO-8601 timestamp, e.g. "2026-10-28T14:03:00Z" */
export type ISODate = string;

/**
 * The business account. Identity fields come from Accounts; the rest come live
 * from Billing and are all null when Billing can't be reached (`billingAvailable: false`).
 */
export interface Account {
  id: ID;
  businessName: string;
  /** IANA zone, fixed after signup. Governs billing periods and business hours. */
  timeZone: string;
  /** SIP domain phones register at. */
  sipDomain: string;
  createdAt: ISODate;
  billingAvailable: boolean;
  status: AccountStatus | null;
  /** `pending` until the base plan is paid; no calling until `active`. */
  activationState: "pending" | "active" | null;
  /** `blocked` when outgoing calls are blocked. */
  restriction: "active" | "blocked" | null;
  canCallOutgoing: boolean | null;
  /** Calls outside the US, including other +1 countries. Needs the international calling add-on. */
  canCallInternational: boolean | null;
  /** Needs the call recording add-on. */
  canRecord: boolean | null;
  /** Billing product code of the active base plan, e.g. "plan_standard". */
  planId: string | null;
  includedExtensions: number | null;
  currentPeriodStart: ISODate | null;
  currentPeriodEnd: ISODate | null;
  /** Shared included US minutes this period. */
  includedMinutesGranted: number | null;
  includedMinutesUsed: number | null;
  addons: Addon[] | null;
}

export type AccountStatus = "active" | "past_due";

/**
 * An add-on's state, as reported by Billing. Buy one with POST /v1/quotes and
 * POST /v1/purchases; remove or keep it with the /v1/subscriptions/items routes.
 */
export interface Addon {
  key: AddonKey;
  name: string;
  /** The add-on works right now. */
  enabled: boolean;
  /** Removed: keeps working until `worksUntil`, then is not renewed. */
  removing: boolean;
  worksUntil: ISODate | null;
  /** Price per 7-day period; null when Billing has no approved price. */
  priceCents: Cents | null;
  /** False when the add-on can't be bought right now. */
  priceAvailable: boolean;
}

export type AddonKey = "international_calling" | "call_recording";

/** Amount in US cents. Per-call amounts and per-minute rates may be fractional. */
export type Cents = number;

export interface LogoutRequest {
  /** Revoke just this session. Omit to sign out everywhere. */
  refreshToken?: string;
}

export interface Ok {
  ok: true;
}

export interface User {
  id: ID;
  accountId: ID;
  email: string;
  name: string;
  role: UserRole;
  createdAt: ISODate;
}

export type ID = string;

export type UserRole = "admin" | "user";

/** ISO-8601 timestamp, e.g. "2026-10-28T14:03:00Z" */
export type ISODate = string;

export interface UpdateMeRequest {
  name?: string;
  email?: string;
}

export interface User {
  id: ID;
  accountId: ID;
  email: string;
  name: string;
  role: UserRole;
  createdAt: ISODate;
}

export type ID = string;

export type UserRole = "admin" | "user";

/** ISO-8601 timestamp, e.g. "2026-10-28T14:03:00Z" */
export type ISODate = string;

export interface ChangePasswordRequest {
  currentPassword: string;
  newPassword: string;
}

export interface Ok {
  ok: true;
}

/**
 * The business account. Identity fields come from Accounts; the rest come live
 * from Billing and are all null when Billing can't be reached (`billingAvailable: false`).
 */
export interface Account {
  id: ID;
  businessName: string;
  /** IANA zone, fixed after signup. Governs billing periods and business hours. */
  timeZone: string;
  /** SIP domain phones register at. */
  sipDomain: string;
  createdAt: ISODate;
  billingAvailable: boolean;
  status: AccountStatus | null;
  /** `pending` until the base plan is paid; no calling until `active`. */
  activationState: "pending" | "active" | null;
  /** `blocked` when outgoing calls are blocked. */
  restriction: "active" | "blocked" | null;
  canCallOutgoing: boolean | null;
  /** Calls outside the US, including other +1 countries. Needs the international calling add-on. */
  canCallInternational: boolean | null;
  /** Needs the call recording add-on. */
  canRecord: boolean | null;
  /** Billing product code of the active base plan, e.g. "plan_standard". */
  planId: string | null;
  includedExtensions: number | null;
  currentPeriodStart: ISODate | null;
  currentPeriodEnd: ISODate | null;
  /** Shared included US minutes this period. */
  includedMinutesGranted: number | null;
  includedMinutesUsed: number | null;
  addons: Addon[] | null;
}

export type ID = string;

/** ISO-8601 timestamp, e.g. "2026-10-28T14:03:00Z" */
export type ISODate = string;

export type AccountStatus = "active" | "past_due";

/**
 * An add-on's state, as reported by Billing. Buy one with POST /v1/quotes and
 * POST /v1/purchases; remove or keep it with the /v1/subscriptions/items routes.
 */
export interface Addon {
  key: AddonKey;
  name: string;
  /** The add-on works right now. */
  enabled: boolean;
  /** Removed: keeps working until `worksUntil`, then is not renewed. */
  removing: boolean;
  worksUntil: ISODate | null;
  /** Price per 7-day period; null when Billing has no approved price. */
  priceCents: Cents | null;
  /** False when the add-on can't be bought right now. */
  priceAvailable: boolean;
}

export type AddonKey = "international_calling" | "call_recording";

/** Amount in US cents. Per-call amounts and per-minute rates may be fractional. */
export type Cents = number;

export interface UpdateAccountRequest {
  businessName?: string;
}

/**
 * The business account. Identity fields come from Accounts; the rest come live
 * from Billing and are all null when Billing can't be reached (`billingAvailable: false`).
 */
export interface Account {
  id: ID;
  businessName: string;
  /** IANA zone, fixed after signup. Governs billing periods and business hours. */
  timeZone: string;
  /** SIP domain phones register at. */
  sipDomain: string;
  createdAt: ISODate;
  billingAvailable: boolean;
  status: AccountStatus | null;
  /** `pending` until the base plan is paid; no calling until `active`. */
  activationState: "pending" | "active" | null;
  /** `blocked` when outgoing calls are blocked. */
  restriction: "active" | "blocked" | null;
  canCallOutgoing: boolean | null;
  /** Calls outside the US, including other +1 countries. Needs the international calling add-on. */
  canCallInternational: boolean | null;
  /** Needs the call recording add-on. */
  canRecord: boolean | null;
  /** Billing product code of the active base plan, e.g. "plan_standard". */
  planId: string | null;
  includedExtensions: number | null;
  currentPeriodStart: ISODate | null;
  currentPeriodEnd: ISODate | null;
  /** Shared included US minutes this period. */
  includedMinutesGranted: number | null;
  includedMinutesUsed: number | null;
  addons: Addon[] | null;
}

export type ID = string;

/** ISO-8601 timestamp, e.g. "2026-10-28T14:03:00Z" */
export type ISODate = string;

export type AccountStatus = "active" | "past_due";

/**
 * An add-on's state, as reported by Billing. Buy one with POST /v1/quotes and
 * POST /v1/purchases; remove or keep it with the /v1/subscriptions/items routes.
 */
export interface Addon {
  key: AddonKey;
  name: string;
  /** The add-on works right now. */
  enabled: boolean;
  /** Removed: keeps working until `worksUntil`, then is not renewed. */
  removing: boolean;
  worksUntil: ISODate | null;
  /** Price per 7-day period; null when Billing has no approved price. */
  priceCents: Cents | null;
  /** False when the add-on can't be bought right now. */
  priceAvailable: boolean;
}

export type AddonKey = "international_calling" | "call_recording";

/** Amount in US cents. Per-call amounts and per-minute rates may be fractional. */
export type Cents = number;

export interface User {
  id: ID;
  accountId: ID;
  email: string;
  name: string;
  role: UserRole;
  createdAt: ISODate;
}

export type ID = string;

export type UserRole = "admin" | "user";

/** ISO-8601 timestamp, e.g. "2026-10-28T14:03:00Z" */
export type ISODate = string;

export interface User {
  id: ID;
  accountId: ID;
  email: string;
  name: string;
  role: UserRole;
  createdAt: ISODate;
}

export type ID = string;

export type UserRole = "admin" | "user";

/** ISO-8601 timestamp, e.g. "2026-10-28T14:03:00Z" */
export type ISODate = string;

export interface CreateUserRequest {
  name: string;
  email: string;
  password: string;
  /** Defaults to `user`. */
  role?: UserRole;
}

export type UserRole = "admin" | "user";

export interface User {
  id: ID;
  accountId: ID;
  email: string;
  name: string;
  role: UserRole;
  createdAt: ISODate;
}

export type ID = string;

/** ISO-8601 timestamp, e.g. "2026-10-28T14:03:00Z" */
export type ISODate = string;

export interface UpdateUserRequest {
  name?: string;
  role?: UserRole;
}

export type UserRole = "admin" | "user";

export interface User {
  id: ID;
  accountId: ID;
  email: string;
  name: string;
  role: UserRole;
  createdAt: ISODate;
}

export type ID = string;

/** ISO-8601 timestamp, e.g. "2026-10-28T14:03:00Z" */
export type ISODate = string;

export interface Ok {
  ok: true;
}

export interface LoginRequest {
  email: string;
  password: string;
}

export interface ProviderLoginResponse {
  accessToken: string;
  email: string;
  expiresIn: number;
}

export interface ListNumbersQuery {
  /** 1 to 1000; default 100. */
  limit?: number;
  offset?: number;
}

/** A number the account owns. */
export interface PhoneNumber extends AvailableNumber {
  status: NumberStatus;
  /** Where its calls go; null while unrouted. */
  destination: NumberDestination | null;
  /** End of the paid period. Null while pending. */
  paid_until: ISODate | null;
}

/** A number the provider can sell. Not a reservation. */
export interface AvailableNumber {
  number: E164;
  type: NumberType;
  /** Only "US" for now. */
  country: string;
  /** Two-letter state code; null for toll-free. */
  region: string | null;
  /** Null for toll-free. */
  city: string | null;
  /** Area code, or the 8XX prefix for toll-free. */
  area_code: string;
}

/** E.164 phone number, e.g. "+16315550142" */
export type E164 = string;

export type NumberType = "local" | "toll_free";

/** `pending`: the provider is still processing the order. `releasing`: released, works until `paid_until`. */
export type NumberStatus = "pending" | "active" | "releasing";

/** Where Numbers sends a number's calls; Calling resolves `id` in the account's call handling. */
export interface NumberDestination {
  type: "extension" | "ring_group" | "ivr" | "schedule";
  id: ID;
}

export type ID = string;

/** ISO-8601 timestamp, e.g. "2026-10-28T14:03:00Z" */
export type ISODate = string;

export interface SearchNumbersQuery {
  type?: NumberType;
  /** Only "US" for now. */
  country?: string;
  /** Two-letter state code, e.g. "NY". Ignored for toll-free. */
  region?: string;
  /** Case-insensitive. Ignored for toll-free. */
  city?: string;
  /** Three digits, or the 8XX prefix for toll-free. */
  area_code?: string;
  /** 1 to 50; default 5. */
  limit?: number;
}

export type NumberType = "local" | "toll_free";

/** A number the provider can sell. Not a reservation. */
export interface AvailableNumber {
  number: E164;
  type: NumberType;
  /** Only "US" for now. */
  country: string;
  /** Two-letter state code; null for toll-free. */
  region: string | null;
  /** Null for toll-free. */
  city: string | null;
  /** Area code, or the 8XX prefix for toll-free. */
  area_code: string;
}

/** E.164 phone number, e.g. "+16315550142" */
export type E164 = string;

/** A number the account owns. */
export interface PhoneNumber extends AvailableNumber {
  status: NumberStatus;
  /** Where its calls go; null while unrouted. */
  destination: NumberDestination | null;
  /** End of the paid period. Null while pending. */
  paid_until: ISODate | null;
}

/** A number the provider can sell. Not a reservation. */
export interface AvailableNumber {
  number: E164;
  type: NumberType;
  /** Only "US" for now. */
  country: string;
  /** Two-letter state code; null for toll-free. */
  region: string | null;
  /** Null for toll-free. */
  city: string | null;
  /** Area code, or the 8XX prefix for toll-free. */
  area_code: string;
}

/** E.164 phone number, e.g. "+16315550142" */
export type E164 = string;

export type NumberType = "local" | "toll_free";

/** `pending`: the provider is still processing the order. `releasing`: released, works until `paid_until`. */
export type NumberStatus = "pending" | "active" | "releasing";

/** Where Numbers sends a number's calls; Calling resolves `id` in the account's call handling. */
export interface NumberDestination {
  type: "extension" | "ring_group" | "ivr" | "schedule";
  id: ID;
}

export type ID = string;

/** ISO-8601 timestamp, e.g. "2026-10-28T14:03:00Z" */
export type ISODate = string;

/** A found number held for the account while it buys it through Billing (about 30 minutes). */
export interface NumberReservation {
  number: E164;
  expires_at: ISODate;
}

/** E.164 phone number, e.g. "+16315550142" */
export type E164 = string;

/** ISO-8601 timestamp, e.g. "2026-10-28T14:03:00Z" */
export type ISODate = string;

/** Where Numbers sends a number's calls; Calling resolves `id` in the account's call handling. */
export interface NumberDestination {
  type: "extension" | "ring_group" | "ivr" | "schedule";
  id: ID;
}

export type ID = string;

/** A number the account owns. */
export interface PhoneNumber extends AvailableNumber {
  status: NumberStatus;
  /** Where its calls go; null while unrouted. */
  destination: NumberDestination | null;
  /** End of the paid period. Null while pending. */
  paid_until: ISODate | null;
}

/** A number the provider can sell. Not a reservation. */
export interface AvailableNumber {
  number: E164;
  type: NumberType;
  /** Only "US" for now. */
  country: string;
  /** Two-letter state code; null for toll-free. */
  region: string | null;
  /** Null for toll-free. */
  city: string | null;
  /** Area code, or the 8XX prefix for toll-free. */
  area_code: string;
}

/** E.164 phone number, e.g. "+16315550142" */
export type E164 = string;

export type NumberType = "local" | "toll_free";

/** `pending`: the provider is still processing the order. `releasing`: released, works until `paid_until`. */
export type NumberStatus = "pending" | "active" | "releasing";

/** ISO-8601 timestamp, e.g. "2026-10-28T14:03:00Z" */
export type ISODate = string;

/** A number the account owns. */
export interface PhoneNumber extends AvailableNumber {
  status: NumberStatus;
  /** Where its calls go; null while unrouted. */
  destination: NumberDestination | null;
  /** End of the paid period. Null while pending. */
  paid_until: ISODate | null;
}

/** A number the provider can sell. Not a reservation. */
export interface AvailableNumber {
  number: E164;
  type: NumberType;
  /** Only "US" for now. */
  country: string;
  /** Two-letter state code; null for toll-free. */
  region: string | null;
  /** Null for toll-free. */
  city: string | null;
  /** Area code, or the 8XX prefix for toll-free. */
  area_code: string;
}

/** E.164 phone number, e.g. "+16315550142" */
export type E164 = string;

export type NumberType = "local" | "toll_free";

/** `pending`: the provider is still processing the order. `releasing`: released, works until `paid_until`. */
export type NumberStatus = "pending" | "active" | "releasing";

/** Where Numbers sends a number's calls; Calling resolves `id` in the account's call handling. */
export interface NumberDestination {
  type: "extension" | "ring_group" | "ivr" | "schedule";
  id: ID;
}

export type ID = string;

/** ISO-8601 timestamp, e.g. "2026-10-28T14:03:00Z" */
export type ISODate = string;

/** The number shown on the account's outgoing calls. */
export interface CallerId {
  number: E164;
  account_id: ID;
  /** False while the chosen number is still pending. */
  usable: boolean;
}

/** E.164 phone number, e.g. "+16315550142" */
export type E164 = string;

export type ID = string;

export interface SetCallerIdRequest {
  number: E164;
}

/** E.164 phone number, e.g. "+16315550142" */
export type E164 = string;

/** The number shown on the account's outgoing calls. */
export interface CallerId {
  number: E164;
  account_id: ID;
  /** False while the chosen number is still pending. */
  usable: boolean;
}

export type ID = string;

export interface Catalog {
  catalog_version: string | null;
  catalog_version_id: ID | null;
  products: CatalogProduct[];
  rates: CatalogRate[];
}

export type ID = string;

export interface CatalogProduct {
  product_id: ID;
  /** Stable code, e.g. "plan_standard" or "call_recording". */
  code: string;
  kind: ProductKind;
  catalog_version_id: ID;
  /** Price per `unit`, decimal USD. */
  amount: string;
  currency: string;
  /** Always "week": recurring prices are per 7-day period. */
  unit: string;
  /** Unavailable entries must not be bought. */
  available: boolean;
  unavailable_reason: string | null;
  /** Plans: `included_quantity` (extensions). Numbers: `number_type`. Add-ons: `addon_code`. */
  product_details: Record<string, unknown>;
  /** Plans: `included_us_seconds`. */
  price_details: Record<string, unknown>;
}

export type ProductKind = "plan" | "extension" | "number" | "addon";

export interface CatalogRate {
  kind: RateKind;
  /** Destination prefix with "+", e.g. "+44". The longest matching prefix wins. */
  prefix: string;
  /** Matched when rating: empty, or `US` for incoming toll-free. */
  region: string;
  /** Destination name, e.g. "United Kingdom". */
  destination: string;
  /** Decimal USD per minute. */
  amount_per_minute: string;
  available: boolean;
  unavailable_reason: string | null;
}

export type RateKind = "us_overage" | "international" | "toll_free";

export type Destination =
  | { type: "extension"; extensionId: ID }
  | { type: "ring_group"; ringGroupId: ID }
  | { type: "ivr"; ivrMenuId: ID }
  | { type: "voicemail"; extensionId: ID }
  | { type: "external"; number: E164 }
  | { type: "schedule"; businessHoursId: ID }
  | { type: "repeat" }
  | { type: "hangup" };

/** E.164 phone number, e.g. "+16315550142" */
export type E164 = string;

export interface QuoteRequest {
  product_id: ID;
  /** 1 to 100; default 1. Plans, numbers and add-ons must be 1. */
  quantity?: number;
  /** Numbers only: the E.164 number to buy. */
  did_e164?: E164 | null;
}

export type ID = string;

/** E.164 phone number, e.g. "+16315550142" */
export type E164 = string;

/** A point-in-time prorated price. Doesn't reserve or charge anything. */
export interface Quote {
  catalog_version: string;
  catalog_version_id: ID;
  product_id: ID;
  product_code: string;
  product_kind: ProductKind;
  product_details: Record<string, unknown>;
  price_details: Record<string, unknown>;
  quantity: number;
  did_e164: E164 | null;
  period_start: ISODate;
  period_end: ISODate;
  scheduled_start: ISODate;
  /** Share of the period left, as a decimal string. */
  fraction: string;
  weekly_price_id: ID;
  weekly_amount: string;
  weekly_cents: number;
  setup_price_id: ID | null;
  setup_amount: string | null;
  setup_cents: number;
  /** What the purchase will charge now, in cents. */
  total_cents: number;
  full_included_us_seconds: number;
  included_us_seconds: number;
  initial_included_us_seconds: number;
  per_unit_included_us_seconds: number;
}

export type ProductKind = "plan" | "extension" | "number" | "addon";

/** ISO-8601 timestamp, e.g. "2026-10-28T14:03:00Z" */
export type ISODate = string;

export interface PurchaseRequest extends QuoteRequest {
  /** From the quote. A stale version returns 409: quote again. */
  catalog_version_id: ID;
  /** The quote's `total_cents`. A changed amount returns 409. */
  expected_total_cents: number;
}

export interface QuoteRequest {
  product_id: ID;
  /** 1 to 100; default 1. Plans, numbers and add-ons must be 1. */
  quantity?: number;
  /** Numbers only: the E.164 number to buy. */
  did_e164?: E164 | null;
}

export type ID = string;

/** E.164 phone number, e.g. "+16315550142" */
export type E164 = string;

/** Order status: `pending_payment`, `active`, `canceled`, or a provisioning state for numbers. */
export interface Purchase {
  id: ID;
  invoice_id: ID;
  status: string;
}

export interface PurchaseListItem extends Purchase {
  price_snapshot: Record<string, unknown>;
}

/** Order status: `pending_payment`, `active`, `canceled`, or a provisioning state for numbers. */
export interface Purchase {
  id: ID;
  invoice_id: ID;
  status: string;
}

export type ID = string;

export interface PurchaseStatus extends PurchaseListItem {
  invoice_status: InvoiceStatus;
  /** Numbers only: provisioning state at the DID provider. */
  number_status: string | null;
}

export interface PurchaseListItem extends Purchase {
  price_snapshot: Record<string, unknown>;
}

/** Order status: `pending_payment`, `active`, `canceled`, or a provisioning state for numbers. */
export interface Purchase {
  id: ID;
  invoice_id: ID;
  status: string;
}

export type ID = string;

export type InvoiceStatus = "draft" | "open" | "paid" | "past_due" | "void";

export interface SubscriptionItem {
  item_id: ID;
  product_id: ID;
  quantity: number;
  /** `pending`, `active`, `removing`, or `removed`. */
  status: string;
  active_from: ISODate | null;
  paid_through: ISODate | null;
  /** Set once removed: the item stops at this time and isn't renewed. */
  removal_at: ISODate | null;
  entitlement: string | null;
  /** Numbers only: which number this item pays for. Remove the item to release the number. */
  did_e164: E164 | null;
}

export type ID = string;

/** ISO-8601 timestamp, e.g. "2026-10-28T14:03:00Z" */
export type ISODate = string;

/** E.164 phone number, e.g. "+16315550142" */
export type E164 = string;

export interface Removal {
  item_id: ID;
  status: string;
  removal_at: ISODate | null;
}

export type ID = string;

/** ISO-8601 timestamp, e.g. "2026-10-28T14:03:00Z" */
export type ISODate = string;

export interface Removal {
  item_id: ID;
  status: string;
  removal_at: ISODate | null;
}

export type ID = string;

/** ISO-8601 timestamp, e.g. "2026-10-28T14:03:00Z" */
export type ISODate = string;

/** Pass `client_secret` to Stripe.js `confirmCardSetup`, then send `setup_intent_id` to POST /v1/card/complete. */
export interface CardSetup {
  setup_intent_id: ID | null;
  client_secret: string | null;
  publishable_key: string | null;
}

export type ID = string;

export interface CompleteCardRequest {
  setup_intent_id: ID;
}

export type ID = string;

/** The account's card. Only safe metadata is ever available. */
export interface Card {
  id: ID;
  brand: string | null;
  last4: string | null;
  exp_month: number | null;
  exp_year: number | null;
}

/** The account's card. Only safe metadata is ever available. */
export interface Card {
  id: ID;
  brand: string | null;
  last4: string | null;
  exp_month: number | null;
  exp_year: number | null;
}

export type ID = string;

/** Name and address shown on invoices. */
export interface BillingDetails {
  name: string;
  email: string;
  company?: string | null;
  address_line1: string;
  address_line2?: string | null;
  city: string;
  region?: string | null;
  postal_code: string;
  country: string;
}

/** Name and address shown on invoices. */
export interface BillingDetails {
  name: string;
  email: string;
  company?: string | null;
  address_line1: string;
  address_line2?: string | null;
  city: string;
  region?: string | null;
  postal_code: string;
  country: string;
}

export interface InvoicesQuery {
  /** 1 to 100; default 25. */
  limit?: number;
  offset?: number;
}

export interface InvoiceSummary {
  id: ID;
  kind: InvoiceKind;
  status: InvoiceStatus;
  currency: string;
  total_cents: number;
  period_id: ID | null;
  /** The billing period the invoice is for. */
  period_start: ISODate | null;
  period_end: ISODate | null;
  issued_at: ISODate | null;
  due_at: ISODate | null;
  paid_at: ISODate | null;
}

export type ID = string;

/** `purchase` is a mid-period charge; `renewal` is the 7-day invoice. */
export type InvoiceKind = "purchase" | "renewal";

export type InvoiceStatus = "draft" | "open" | "paid" | "past_due" | "void";

/** ISO-8601 timestamp, e.g. "2026-10-28T14:03:00Z" */
export type ISODate = string;

export interface InvoiceDetail extends InvoiceSummary {
  lines: InvoiceLine[];
  allowance: InvoiceAllowance;
}

export interface InvoiceSummary {
  id: ID;
  kind: InvoiceKind;
  status: InvoiceStatus;
  currency: string;
  total_cents: number;
  period_id: ID | null;
  /** The billing period the invoice is for. */
  period_start: ISODate | null;
  period_end: ISODate | null;
  issued_at: ISODate | null;
  due_at: ISODate | null;
  paid_at: ISODate | null;
}

export type ID = string;

/** `purchase` is a mid-period charge; `renewal` is the 7-day invoice. */
export type InvoiceKind = "purchase" | "renewal";

export type InvoiceStatus = "draft" | "open" | "paid" | "past_due" | "void";

/** ISO-8601 timestamp, e.g. "2026-10-28T14:03:00Z" */
export type ISODate = string;

export interface InvoiceLine {
  id: ID;
  /** `recurring`, `setup`, or `usage`. */
  kind: string;
  description: string;
  /** Decimal string. */
  quantity: string;
  unit_amount: string;
  amount_cents: number;
  source_type: string | null;
  source_id: ID | null;
  price_snapshot: Record<string, unknown>;
}

/** Included US allowance for the period an invoice's usage belongs to. */
export interface InvoiceAllowance {
  period_id?: ID;
  granted_seconds?: number;
  used_seconds?: number;
}

export interface InvoicesQuery {
  /** 1 to 100; default 25. */
  limit?: number;
  offset?: number;
}

/** A settled payment. */
export interface Transaction {
  id: ID;
  invoice_id: ID;
  kind: string;
  amount_cents: number;
  currency: string;
  settled_at: ISODate;
  gateway_object_id: string | null;
}

export type ID = string;

/** ISO-8601 timestamp, e.g. "2026-10-28T14:03:00Z" */
export type ISODate = string;

export interface Extension {
  id: ID;
  accountId: ID;
  /** Unique in the account, e.g. "101". */
  number: string;
  name: string;
  sipUsername: string;
  /** Null until the extension is active, and for non-admins. */
  sipPassword: string | null;
  status: ExtensionStatus;
  /** Billing purchase state, or null when included capacity was used. */
  purchaseState: string | null;
  purchaseId: string | null;
  /** Not reported yet: null. */
  voicemailBox: string | null;
  forwarding: Forwarding;
  /** External numbers that ring together with this extension. */
  simultaneousRing: E164[];
  userId: ID | null;
  /** Not reported yet: null. */
  devices: RegisteredDevice[] | null;
  /** Not reported yet: "unknown". */
  presence: Presence | "unknown";
  /** Beyond the plan's included extensions, so it has a recurring price. */
  billable: boolean;
  removing: boolean;
  worksUntil: ISODate | null;
  createdAt: ISODate;
}

export type ID = string;

/** `purchase_pending`: an extra extension waiting for payment; `pending`: its SIP login is being set up. */
export type ExtensionStatus = "purchase_pending" | "pending" | "active" | "removing" | "removed";

export interface Forwarding {
  always: ForwardTarget | null;
  busy: ForwardTarget | null;
  noAnswer: ForwardTarget | null;
  noAnswerSeconds: number;
}

export type ForwardTarget =
  | { type: "extension"; extensionId: ID }
  | { type: "external"; number: E164 };

/** E.164 phone number, e.g. "+16315550142" */
export type E164 = string;

export interface RegisteredDevice {
  id: ID;
  userAgent: string;
  transport: "udp" | "tls";
  codec: Codec;
  /** TLS phones use SRTP with SDES. */
  srtp: boolean;
  contact: string;
  registeredAt: ISODate;
  expiresAt: ISODate;
}

export type Codec = "PCMU" | "PCMA" | "G729" | "G723" | "OPUS";

/** ISO-8601 timestamp, e.g. "2026-10-28T14:03:00Z" */
export type ISODate = string;

export type Presence = "online" | "offline" | "busy";

export interface CreateExtensionRequest {
  number: string;
  name: string;
  forwarding?: Forwarding;
  simultaneousRing?: E164[];
  /** Only when included extensions are used up (409 `extension_capacity_exhausted`). */
  purchase?: AcceptedExtensionPurchase;
}

export interface Forwarding {
  always: ForwardTarget | null;
  busy: ForwardTarget | null;
  noAnswer: ForwardTarget | null;
  noAnswerSeconds: number;
}

export type ForwardTarget =
  | { type: "extension"; extensionId: ID }
  | { type: "external"; number: E164 };

export type ID = string;

/** E.164 phone number, e.g. "+16315550142" */
export type E164 = string;

/** A quote the admin accepted, to buy one extra extension when the plan's are used up. */
export interface AcceptedExtensionPurchase {
  productId: ID;
  catalogVersionId: ID;
  expectedTotalCents: number;
}

export interface Extension {
  id: ID;
  accountId: ID;
  /** Unique in the account, e.g. "101". */
  number: string;
  name: string;
  sipUsername: string;
  /** Null until the extension is active, and for non-admins. */
  sipPassword: string | null;
  status: ExtensionStatus;
  /** Billing purchase state, or null when included capacity was used. */
  purchaseState: string | null;
  purchaseId: string | null;
  /** Not reported yet: null. */
  voicemailBox: string | null;
  forwarding: Forwarding;
  /** External numbers that ring together with this extension. */
  simultaneousRing: E164[];
  userId: ID | null;
  /** Not reported yet: null. */
  devices: RegisteredDevice[] | null;
  /** Not reported yet: "unknown". */
  presence: Presence | "unknown";
  /** Beyond the plan's included extensions, so it has a recurring price. */
  billable: boolean;
  removing: boolean;
  worksUntil: ISODate | null;
  createdAt: ISODate;
}

/** `purchase_pending`: an extra extension waiting for payment; `pending`: its SIP login is being set up. */
export type ExtensionStatus = "purchase_pending" | "pending" | "active" | "removing" | "removed";

export interface RegisteredDevice {
  id: ID;
  userAgent: string;
  transport: "udp" | "tls";
  codec: Codec;
  /** TLS phones use SRTP with SDES. */
  srtp: boolean;
  contact: string;
  registeredAt: ISODate;
  expiresAt: ISODate;
}

export type Codec = "PCMU" | "PCMA" | "G729" | "G723" | "OPUS";

/** ISO-8601 timestamp, e.g. "2026-10-28T14:03:00Z" */
export type ISODate = string;

export type Presence = "online" | "offline" | "busy";

export interface ExtensionQuoteRequest {
  productId: ID;
}

export type ID = string;

export interface ExtensionQuote {
  productId: ID;
  productCode: string;
  catalogVersionId: ID;
  /** Charged now, prorated to the end of the period. */
  expectedTotalCents: number;
  weeklyCents: number;
  setupCents: number;
  periodEnd: ISODate;
}

/** ISO-8601 timestamp, e.g. "2026-10-28T14:03:00Z" */
export type ISODate = string;

export interface UpdateExtensionRequest {
  number?: string;
  name?: string;
  forwarding?: Forwarding;
  simultaneousRing?: E164[];
  /** True generates a new SIP password. */
  regeneratePassword?: boolean;
}

export interface Forwarding {
  always: ForwardTarget | null;
  busy: ForwardTarget | null;
  noAnswer: ForwardTarget | null;
  noAnswerSeconds: number;
}

export type ForwardTarget =
  | { type: "extension"; extensionId: ID }
  | { type: "external"; number: E164 };

export type ID = string;

/** E.164 phone number, e.g. "+16315550142" */
export type E164 = string;

export interface Extension {
  id: ID;
  accountId: ID;
  /** Unique in the account, e.g. "101". */
  number: string;
  name: string;
  sipUsername: string;
  /** Null until the extension is active, and for non-admins. */
  sipPassword: string | null;
  status: ExtensionStatus;
  /** Billing purchase state, or null when included capacity was used. */
  purchaseState: string | null;
  purchaseId: string | null;
  /** Not reported yet: null. */
  voicemailBox: string | null;
  forwarding: Forwarding;
  /** External numbers that ring together with this extension. */
  simultaneousRing: E164[];
  userId: ID | null;
  /** Not reported yet: null. */
  devices: RegisteredDevice[] | null;
  /** Not reported yet: "unknown". */
  presence: Presence | "unknown";
  /** Beyond the plan's included extensions, so it has a recurring price. */
  billable: boolean;
  removing: boolean;
  worksUntil: ISODate | null;
  createdAt: ISODate;
}

/** `purchase_pending`: an extra extension waiting for payment; `pending`: its SIP login is being set up. */
export type ExtensionStatus = "purchase_pending" | "pending" | "active" | "removing" | "removed";

export interface RegisteredDevice {
  id: ID;
  userAgent: string;
  transport: "udp" | "tls";
  codec: Codec;
  /** TLS phones use SRTP with SDES. */
  srtp: boolean;
  contact: string;
  registeredAt: ISODate;
  expiresAt: ISODate;
}

export type Codec = "PCMU" | "PCMA" | "G729" | "G723" | "OPUS";

/** ISO-8601 timestamp, e.g. "2026-10-28T14:03:00Z" */
export type ISODate = string;

export type Presence = "online" | "offline" | "busy";

export interface Extension {
  id: ID;
  accountId: ID;
  /** Unique in the account, e.g. "101". */
  number: string;
  name: string;
  sipUsername: string;
  /** Null until the extension is active, and for non-admins. */
  sipPassword: string | null;
  status: ExtensionStatus;
  /** Billing purchase state, or null when included capacity was used. */
  purchaseState: string | null;
  purchaseId: string | null;
  /** Not reported yet: null. */
  voicemailBox: string | null;
  forwarding: Forwarding;
  /** External numbers that ring together with this extension. */
  simultaneousRing: E164[];
  userId: ID | null;
  /** Not reported yet: null. */
  devices: RegisteredDevice[] | null;
  /** Not reported yet: "unknown". */
  presence: Presence | "unknown";
  /** Beyond the plan's included extensions, so it has a recurring price. */
  billable: boolean;
  removing: boolean;
  worksUntil: ISODate | null;
  createdAt: ISODate;
}

export type ID = string;

/** `purchase_pending`: an extra extension waiting for payment; `pending`: its SIP login is being set up. */
export type ExtensionStatus = "purchase_pending" | "pending" | "active" | "removing" | "removed";

export interface Forwarding {
  always: ForwardTarget | null;
  busy: ForwardTarget | null;
  noAnswer: ForwardTarget | null;
  noAnswerSeconds: number;
}

export type ForwardTarget =
  | { type: "extension"; extensionId: ID }
  | { type: "external"; number: E164 };

/** E.164 phone number, e.g. "+16315550142" */
export type E164 = string;

export interface RegisteredDevice {
  id: ID;
  userAgent: string;
  transport: "udp" | "tls";
  codec: Codec;
  /** TLS phones use SRTP with SDES. */
  srtp: boolean;
  contact: string;
  registeredAt: ISODate;
  expiresAt: ISODate;
}

export type Codec = "PCMU" | "PCMA" | "G729" | "G723" | "OPUS";

/** ISO-8601 timestamp, e.g. "2026-10-28T14:03:00Z" */
export type ISODate = string;

export type Presence = "online" | "offline" | "busy";

export interface RingGroup {
  id: ID;
  accountId: ID;
  name: string;
  strategy: RingStrategy;
  members: RingGroupMember[];
  /** Simultaneous groups: how long everyone rings. */
  timeoutSeconds: number;
  noAnswerDestination: Destination;
  updatedAt: ISODate;
}

export type ID = string;

export type RingStrategy = "simultaneous" | "sequential";

export interface RingGroupMember {
  extensionId: ID;
  /** Sequential groups: how long this member rings before the next. */
  ringSeconds: number;
}

export type Destination =
  | { type: "extension"; extensionId: ID }
  | { type: "ring_group"; ringGroupId: ID }
  | { type: "ivr"; ivrMenuId: ID }
  | { type: "voicemail"; extensionId: ID }
  | { type: "external"; number: E164 }
  | { type: "schedule"; businessHoursId: ID }
  | { type: "repeat" }
  | { type: "hangup" };

/** E.164 phone number, e.g. "+16315550142" */
export type E164 = string;

/** ISO-8601 timestamp, e.g. "2026-10-28T14:03:00Z" */
export type ISODate = string;

export type UpsertRingGroupRequest = Pick<RingGroup, "name" | "strategy" | "members" | "timeoutSeconds" | "noAnswerDestination">;

export interface RingGroup {
  id: ID;
  accountId: ID;
  name: string;
  strategy: RingStrategy;
  members: RingGroupMember[];
  /** Simultaneous groups: how long everyone rings. */
  timeoutSeconds: number;
  noAnswerDestination: Destination;
  updatedAt: ISODate;
}

export type ID = string;

export type RingStrategy = "simultaneous" | "sequential";

export interface RingGroupMember {
  extensionId: ID;
  /** Sequential groups: how long this member rings before the next. */
  ringSeconds: number;
}

export type Destination =
  | { type: "extension"; extensionId: ID }
  | { type: "ring_group"; ringGroupId: ID }
  | { type: "ivr"; ivrMenuId: ID }
  | { type: "voicemail"; extensionId: ID }
  | { type: "external"; number: E164 }
  | { type: "schedule"; businessHoursId: ID }
  | { type: "repeat" }
  | { type: "hangup" };

/** E.164 phone number, e.g. "+16315550142" */
export type E164 = string;

/** ISO-8601 timestamp, e.g. "2026-10-28T14:03:00Z" */
export type ISODate = string;

export type UpsertRingGroupRequest = Pick<RingGroup, "name" | "strategy" | "members" | "timeoutSeconds" | "noAnswerDestination">;

export interface RingGroup {
  id: ID;
  accountId: ID;
  name: string;
  strategy: RingStrategy;
  members: RingGroupMember[];
  /** Simultaneous groups: how long everyone rings. */
  timeoutSeconds: number;
  noAnswerDestination: Destination;
  updatedAt: ISODate;
}

export type ID = string;

export type RingStrategy = "simultaneous" | "sequential";

export interface RingGroupMember {
  extensionId: ID;
  /** Sequential groups: how long this member rings before the next. */
  ringSeconds: number;
}

export type Destination =
  | { type: "extension"; extensionId: ID }
  | { type: "ring_group"; ringGroupId: ID }
  | { type: "ivr"; ivrMenuId: ID }
  | { type: "voicemail"; extensionId: ID }
  | { type: "external"; number: E164 }
  | { type: "schedule"; businessHoursId: ID }
  | { type: "repeat" }
  | { type: "hangup" };

/** E.164 phone number, e.g. "+16315550142" */
export type E164 = string;

/** ISO-8601 timestamp, e.g. "2026-10-28T14:03:00Z" */
export type ISODate = string;

export interface Ok {
  ok: true;
}

export interface BusinessHours {
  id: ID;
  accountId: ID;
  name: string;
  intervals: BusinessHoursInterval[];
  openDestination: Destination;
  closedDestination: Destination;
  updatedAt: ISODate;
}

export type ID = string;

export interface BusinessHoursInterval {
  /** 0 = Sunday. */
  day: number;
  /** "09:00" in the account's time zone. */
  open: string;
  close: string;
}

export type Destination =
  | { type: "extension"; extensionId: ID }
  | { type: "ring_group"; ringGroupId: ID }
  | { type: "ivr"; ivrMenuId: ID }
  | { type: "voicemail"; extensionId: ID }
  | { type: "external"; number: E164 }
  | { type: "schedule"; businessHoursId: ID }
  | { type: "repeat" }
  | { type: "hangup" };

/** E.164 phone number, e.g. "+16315550142" */
export type E164 = string;

/** ISO-8601 timestamp, e.g. "2026-10-28T14:03:00Z" */
export type ISODate = string;

export type UpsertBusinessHoursRequest = Pick<BusinessHours, "name" | "intervals" | "openDestination" | "closedDestination">;

export interface BusinessHours {
  id: ID;
  accountId: ID;
  name: string;
  intervals: BusinessHoursInterval[];
  openDestination: Destination;
  closedDestination: Destination;
  updatedAt: ISODate;
}

export type ID = string;

export interface BusinessHoursInterval {
  /** 0 = Sunday. */
  day: number;
  /** "09:00" in the account's time zone. */
  open: string;
  close: string;
}

export type Destination =
  | { type: "extension"; extensionId: ID }
  | { type: "ring_group"; ringGroupId: ID }
  | { type: "ivr"; ivrMenuId: ID }
  | { type: "voicemail"; extensionId: ID }
  | { type: "external"; number: E164 }
  | { type: "schedule"; businessHoursId: ID }
  | { type: "repeat" }
  | { type: "hangup" };

/** E.164 phone number, e.g. "+16315550142" */
export type E164 = string;

/** ISO-8601 timestamp, e.g. "2026-10-28T14:03:00Z" */
export type ISODate = string;

export type UpsertBusinessHoursRequest = Pick<BusinessHours, "name" | "intervals" | "openDestination" | "closedDestination">;

export interface BusinessHours {
  id: ID;
  accountId: ID;
  name: string;
  intervals: BusinessHoursInterval[];
  openDestination: Destination;
  closedDestination: Destination;
  updatedAt: ISODate;
}

export type ID = string;

export interface BusinessHoursInterval {
  /** 0 = Sunday. */
  day: number;
  /** "09:00" in the account's time zone. */
  open: string;
  close: string;
}

export type Destination =
  | { type: "extension"; extensionId: ID }
  | { type: "ring_group"; ringGroupId: ID }
  | { type: "ivr"; ivrMenuId: ID }
  | { type: "voicemail"; extensionId: ID }
  | { type: "external"; number: E164 }
  | { type: "schedule"; businessHoursId: ID }
  | { type: "repeat" }
  | { type: "hangup" };

/** E.164 phone number, e.g. "+16315550142" */
export type E164 = string;

/** ISO-8601 timestamp, e.g. "2026-10-28T14:03:00Z" */
export type ISODate = string;

export interface Ok {
  ok: true;
}

export interface IvrMenu {
  id: ID;
  accountId: ID;
  name: string;
  /** Uploaded WAV (16-bit PCM mono 8 kHz); null until one is uploaded. */
  greeting: IvrGreeting | null;
  /** Seconds to wait for a digit before `timeoutAction`. */
  timeoutSeconds: number;
  timeoutAction: Destination;
  invalidInputAction: Destination;
  /** How many times `repeat` replays the menu before hanging up. */
  maxRepeats: number;
  options: IvrOption[];
  updatedAt: ISODate;
}

export type ID = string;

export interface IvrGreeting {
  fileName: string;
  durationSeconds: number;
  uploadedAt: ISODate;
}

/** ISO-8601 timestamp, e.g. "2026-10-28T14:03:00Z" */
export type ISODate = string;

export type Destination =
  | { type: "extension"; extensionId: ID }
  | { type: "ring_group"; ringGroupId: ID }
  | { type: "ivr"; ivrMenuId: ID }
  | { type: "voicemail"; extensionId: ID }
  | { type: "external"; number: E164 }
  | { type: "schedule"; businessHoursId: ID }
  | { type: "repeat" }
  | { type: "hangup" };

/** E.164 phone number, e.g. "+16315550142" */
export type E164 = string;

export interface IvrOption {
  digit: DtmfKey;
  label: string;
  destination: Destination;
}

export type DtmfKey = "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9" | "*" | "#";

export type UpsertIvrMenuRequest = Pick<IvrMenu, "name" | "timeoutSeconds" | "timeoutAction" | "invalidInputAction" | "maxRepeats" | "options">;

export interface IvrMenu {
  id: ID;
  accountId: ID;
  name: string;
  /** Uploaded WAV (16-bit PCM mono 8 kHz); null until one is uploaded. */
  greeting: IvrGreeting | null;
  /** Seconds to wait for a digit before `timeoutAction`. */
  timeoutSeconds: number;
  timeoutAction: Destination;
  invalidInputAction: Destination;
  /** How many times `repeat` replays the menu before hanging up. */
  maxRepeats: number;
  options: IvrOption[];
  updatedAt: ISODate;
}

export type ID = string;

export interface IvrGreeting {
  fileName: string;
  durationSeconds: number;
  uploadedAt: ISODate;
}

/** ISO-8601 timestamp, e.g. "2026-10-28T14:03:00Z" */
export type ISODate = string;

export type Destination =
  | { type: "extension"; extensionId: ID }
  | { type: "ring_group"; ringGroupId: ID }
  | { type: "ivr"; ivrMenuId: ID }
  | { type: "voicemail"; extensionId: ID }
  | { type: "external"; number: E164 }
  | { type: "schedule"; businessHoursId: ID }
  | { type: "repeat" }
  | { type: "hangup" };

/** E.164 phone number, e.g. "+16315550142" */
export type E164 = string;

export interface IvrOption {
  digit: DtmfKey;
  label: string;
  destination: Destination;
}

export type DtmfKey = "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9" | "*" | "#";

export type UpsertIvrMenuRequest = Pick<IvrMenu, "name" | "timeoutSeconds" | "timeoutAction" | "invalidInputAction" | "maxRepeats" | "options">;

export interface IvrMenu {
  id: ID;
  accountId: ID;
  name: string;
  /** Uploaded WAV (16-bit PCM mono 8 kHz); null until one is uploaded. */
  greeting: IvrGreeting | null;
  /** Seconds to wait for a digit before `timeoutAction`. */
  timeoutSeconds: number;
  timeoutAction: Destination;
  invalidInputAction: Destination;
  /** How many times `repeat` replays the menu before hanging up. */
  maxRepeats: number;
  options: IvrOption[];
  updatedAt: ISODate;
}

export type ID = string;

export interface IvrGreeting {
  fileName: string;
  durationSeconds: number;
  uploadedAt: ISODate;
}

/** ISO-8601 timestamp, e.g. "2026-10-28T14:03:00Z" */
export type ISODate = string;

export type Destination =
  | { type: "extension"; extensionId: ID }
  | { type: "ring_group"; ringGroupId: ID }
  | { type: "ivr"; ivrMenuId: ID }
  | { type: "voicemail"; extensionId: ID }
  | { type: "external"; number: E164 }
  | { type: "schedule"; businessHoursId: ID }
  | { type: "repeat" }
  | { type: "hangup" };

/** E.164 phone number, e.g. "+16315550142" */
export type E164 = string;

export interface IvrOption {
  digit: DtmfKey;
  label: string;
  destination: Destination;
}

export type DtmfKey = "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9" | "*" | "#";

export interface Ok {
  ok: true;
}

export interface UploadIvrGreetingRequest {
  fileName: string;
  /** Raw WAV bytes, sent as the `audio/wav` request body. */
  wav: ArrayBuffer;
}

export interface IvrMenu {
  id: ID;
  accountId: ID;
  name: string;
  /** Uploaded WAV (16-bit PCM mono 8 kHz); null until one is uploaded. */
  greeting: IvrGreeting | null;
  /** Seconds to wait for a digit before `timeoutAction`. */
  timeoutSeconds: number;
  timeoutAction: Destination;
  invalidInputAction: Destination;
  /** How many times `repeat` replays the menu before hanging up. */
  maxRepeats: number;
  options: IvrOption[];
  updatedAt: ISODate;
}

export type ID = string;

export interface IvrGreeting {
  fileName: string;
  durationSeconds: number;
  uploadedAt: ISODate;
}

/** ISO-8601 timestamp, e.g. "2026-10-28T14:03:00Z" */
export type ISODate = string;

export type Destination =
  | { type: "extension"; extensionId: ID }
  | { type: "ring_group"; ringGroupId: ID }
  | { type: "ivr"; ivrMenuId: ID }
  | { type: "voicemail"; extensionId: ID }
  | { type: "external"; number: E164 }
  | { type: "schedule"; businessHoursId: ID }
  | { type: "repeat" }
  | { type: "hangup" };

/** E.164 phone number, e.g. "+16315550142" */
export type E164 = string;

export interface IvrOption {
  digit: DtmfKey;
  label: string;
  destination: Destination;
}

export type DtmfKey = "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9" | "*" | "#";

export interface BlockedCaller {
  id: ID;
  accountId: ID;
  number: E164;
  note: string;
  createdAt: ISODate;
}

export type ID = string;

/** E.164 phone number, e.g. "+16315550142" */
export type E164 = string;

/** ISO-8601 timestamp, e.g. "2026-10-28T14:03:00Z" */
export type ISODate = string;

export interface CreateBlockedCallerRequest {
  number: string;
  note?: string;
}

export interface BlockedCaller {
  id: ID;
  accountId: ID;
  number: E164;
  note: string;
  createdAt: ISODate;
}

export type ID = string;

/** E.164 phone number, e.g. "+16315550142" */
export type E164 = string;

/** ISO-8601 timestamp, e.g. "2026-10-28T14:03:00Z" */
export type ISODate = string;

export interface Ok {
  ok: true;
}

export interface VoicemailQuery {
  extension_id?: ID;
  status?: VoicemailStatus;
}

export type ID = string;

export type VoicemailStatus = "new" | "saved";

export interface VoicemailMessage extends Recording {
  /** Whose box it was left in. */
  extension_id: ID;
  status: VoicemailStatus;
}

export interface Recording {
  id: ID;
  account_id: ID;
  call_id: ID;
  calling_number: string;
  called_number: string;
  started_at: ISODate;
  duration_ms: number;
  /** False while the call is still being recorded. */
  complete: boolean;
}

/** ISO-8601 timestamp, e.g. "2026-10-28T14:03:00Z" */
export type ISODate = string;

export interface UpdateVoicemailRequest {
  status: VoicemailStatus;
}

export type VoicemailStatus = "new" | "saved";

export interface VoicemailMessage extends Recording {
  /** Whose box it was left in. */
  extension_id: ID;
  status: VoicemailStatus;
}

export interface Recording {
  id: ID;
  account_id: ID;
  call_id: ID;
  calling_number: string;
  called_number: string;
  started_at: ISODate;
  duration_ms: number;
  /** False while the call is still being recorded. */
  complete: boolean;
}

export type ID = string;

/** ISO-8601 timestamp, e.g. "2026-10-28T14:03:00Z" */
export type ISODate = string;

export interface Ok {
  ok: true;
}

export interface Recording {
  id: ID;
  account_id: ID;
  call_id: ID;
  calling_number: string;
  called_number: string;
  started_at: ISODate;
  duration_ms: number;
  /** False while the call is still being recorded. */
  complete: boolean;
}

export type ID = string;

/** ISO-8601 timestamp, e.g. "2026-10-28T14:03:00Z" */
export type ISODate = string;

/** A ticket in a list. */
export interface TicketSummary {
  id: ID;
  title: string;
  status: TicketStatus;
  account_id: ID;
  created_at: ISODate;
}

export type ID = string;

export type TicketStatus = "open" | "closed";

/** ISO-8601 timestamp, e.g. "2026-10-28T14:03:00Z" */
export type ISODate = string;

export interface Ticket extends TicketSummary {
  /** The user who opened it. */
  user_id: ID;
  description: string;
  closed_at: ISODate | null;
  replies: TicketReply[];
}

/** A ticket in a list. */
export interface TicketSummary {
  id: ID;
  title: string;
  status: TicketStatus;
  account_id: ID;
  created_at: ISODate;
}

export type ID = string;

export type TicketStatus = "open" | "closed";

/** ISO-8601 timestamp, e.g. "2026-10-28T14:03:00Z" */
export type ISODate = string;

export interface TicketReply {
  /** Who wrote it: a user of the account, or provider staff. */
  user_id: string;
  text: string;
}

export interface CreateTicketRequest {
  title: string;
  description: string;
}

export interface Ticket extends TicketSummary {
  /** The user who opened it. */
  user_id: ID;
  description: string;
  closed_at: ISODate | null;
  replies: TicketReply[];
}

/** A ticket in a list. */
export interface TicketSummary {
  id: ID;
  title: string;
  status: TicketStatus;
  account_id: ID;
  created_at: ISODate;
}

export type ID = string;

export type TicketStatus = "open" | "closed";

/** ISO-8601 timestamp, e.g. "2026-10-28T14:03:00Z" */
export type ISODate = string;

export interface TicketReply {
  /** Who wrote it: a user of the account, or provider staff. */
  user_id: string;
  text: string;
}

export interface CreateTicketReplyRequest {
  text: string;
}

export interface TicketReply {
  /** Who wrote it: a user of the account, or provider staff. */
  user_id: string;
  text: string;
}

export interface Ticket extends TicketSummary {
  /** The user who opened it. */
  user_id: ID;
  description: string;
  closed_at: ISODate | null;
  replies: TicketReply[];
}

/** A ticket in a list. */
export interface TicketSummary {
  id: ID;
  title: string;
  status: TicketStatus;
  account_id: ID;
  created_at: ISODate;
}

export type ID = string;

export type TicketStatus = "open" | "closed";

/** ISO-8601 timestamp, e.g. "2026-10-28T14:03:00Z" */
export type ISODate = string;

export interface TicketReply {
  /** Who wrote it: a user of the account, or provider staff. */
  user_id: string;
  text: string;
}

export interface LiveCall {
  id: ID;
  accountId: ID;
  direction: CallDirection;
  from: string;
  to: string;
  /** The account's number the call came in on or presents as caller ID. */
  did: E164 | null;
  /** Extension placing the call (outgoing and internal). */
  fromExtensionId: ID | null;
  /** Extensions ringing right now. */
  ringingExtensionIds: ID[];
  /** External numbers ringing with them. */
  ringingExternalNumbers: E164[];
  /** Extension talking on the call. */
  answeredExtensionId: ID | null;
  state: LiveCallState;
  codec: Codec | null;
  /** Seconds since the call started. */
  elapsedSeconds: number;
  /** Path taken through routing so far. */
  path: string[];
  /** For a call to *98: what the voicemail system is saying now. */
  voicemailPrompt: string | null;
  /** For an attended transfer: the held call this one consults about. */
  consultForCallId: ID | null;
}

export type ID = string;

export type CallDirection = "incoming" | "outgoing" | "internal";

/** E.164 phone number, e.g. "+16315550142" */
export type E164 = string;

export interface Extension {
  id: ID;
  accountId: ID;
  /** Unique in the account, e.g. "101". */
  number: string;
  name: string;
  sipUsername: string;
  /** Null until the extension is active, and for non-admins. */
  sipPassword: string | null;
  status: ExtensionStatus;
  /** Billing purchase state, or null when included capacity was used. */
  purchaseState: string | null;
  purchaseId: string | null;
  /** Not reported yet: null. */
  voicemailBox: string | null;
  forwarding: Forwarding;
  /** External numbers that ring together with this extension. */
  simultaneousRing: E164[];
  userId: ID | null;
  /** Not reported yet: null. */
  devices: RegisteredDevice[] | null;
  /** Not reported yet: "unknown". */
  presence: Presence | "unknown";
  /** Beyond the plan's included extensions, so it has a recurring price. */
  billable: boolean;
  removing: boolean;
  worksUntil: ISODate | null;
  createdAt: ISODate;
}

/** `purchase_pending`: an extra extension waiting for payment; `pending`: its SIP login is being set up. */
export type ExtensionStatus = "purchase_pending" | "pending" | "active" | "removing" | "removed";

export interface Forwarding {
  always: ForwardTarget | null;
  busy: ForwardTarget | null;
  noAnswer: ForwardTarget | null;
  noAnswerSeconds: number;
}

export type ForwardTarget =
  | { type: "extension"; extensionId: ID }
  | { type: "external"; number: E164 };

export interface RegisteredDevice {
  id: ID;
  userAgent: string;
  transport: "udp" | "tls";
  codec: Codec;
  /** TLS phones use SRTP with SDES. */
  srtp: boolean;
  contact: string;
  registeredAt: ISODate;
  expiresAt: ISODate;
}

export type Codec = "PCMU" | "PCMA" | "G729" | "G723" | "OPUS";

/** ISO-8601 timestamp, e.g. "2026-10-28T14:03:00Z" */
export type ISODate = string;

export type Presence = "online" | "offline" | "busy";

export type LiveCallState = "ringing" | "active" | "on-hold";

export type CallAction =
  | { action: "answer"; extensionId: ID }
  | { action: "answer_external"; number: E164 }
  | { action: "reject"; extensionId?: ID }
  | { action: "hold" }
  | { action: "resume" }
  | { action: "hangup" }
  | { action: "forward"; to: string }
  | { action: "transfer"; to: string; type: "blind" | "attended" }
  | { action: "transfer_complete" }
  | { action: "dtmf"; digit: DtmfKey };

export type ID = string;

/** E.164 phone number, e.g. "+16315550142" */
export type E164 = string;

export type DtmfKey = "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9" | "*" | "#";

export interface CallActionResponse {
  /** The call after the action, or null if it ended. */
  call: LiveCall | null;
  /** Attended transfer: the new call to the transfer target. */
  consultCall: LiveCall | null;
}

export interface LiveCall {
  id: ID;
  accountId: ID;
  direction: CallDirection;
  from: string;
  to: string;
  /** The account's number the call came in on or presents as caller ID. */
  did: E164 | null;
  /** Extension placing the call (outgoing and internal). */
  fromExtensionId: ID | null;
  /** Extensions ringing right now. */
  ringingExtensionIds: ID[];
  /** External numbers ringing with them. */
  ringingExternalNumbers: E164[];
  /** Extension talking on the call. */
  answeredExtensionId: ID | null;
  state: LiveCallState;
  codec: Codec | null;
  /** Seconds since the call started. */
  elapsedSeconds: number;
  /** Path taken through routing so far. */
  path: string[];
  /** For a call to *98: what the voicemail system is saying now. */
  voicemailPrompt: string | null;
  /** For an attended transfer: the held call this one consults about. */
  consultForCallId: ID | null;
}

export type CallDirection = "incoming" | "outgoing" | "internal";

export interface Extension {
  id: ID;
  accountId: ID;
  /** Unique in the account, e.g. "101". */
  number: string;
  name: string;
  sipUsername: string;
  /** Null until the extension is active, and for non-admins. */
  sipPassword: string | null;
  status: ExtensionStatus;
  /** Billing purchase state, or null when included capacity was used. */
  purchaseState: string | null;
  purchaseId: string | null;
  /** Not reported yet: null. */
  voicemailBox: string | null;
  forwarding: Forwarding;
  /** External numbers that ring together with this extension. */
  simultaneousRing: E164[];
  userId: ID | null;
  /** Not reported yet: null. */
  devices: RegisteredDevice[] | null;
  /** Not reported yet: "unknown". */
  presence: Presence | "unknown";
  /** Beyond the plan's included extensions, so it has a recurring price. */
  billable: boolean;
  removing: boolean;
  worksUntil: ISODate | null;
  createdAt: ISODate;
}

/** `purchase_pending`: an extra extension waiting for payment; `pending`: its SIP login is being set up. */
export type ExtensionStatus = "purchase_pending" | "pending" | "active" | "removing" | "removed";

export interface Forwarding {
  always: ForwardTarget | null;
  busy: ForwardTarget | null;
  noAnswer: ForwardTarget | null;
  noAnswerSeconds: number;
}

export type ForwardTarget =
  | { type: "extension"; extensionId: ID }
  | { type: "external"; number: E164 };

export interface RegisteredDevice {
  id: ID;
  userAgent: string;
  transport: "udp" | "tls";
  codec: Codec;
  /** TLS phones use SRTP with SDES. */
  srtp: boolean;
  contact: string;
  registeredAt: ISODate;
  expiresAt: ISODate;
}

export type Codec = "PCMU" | "PCMA" | "G729" | "G723" | "OPUS";

/** ISO-8601 timestamp, e.g. "2026-10-28T14:03:00Z" */
export type ISODate = string;

export type Presence = "online" | "offline" | "busy";

export type LiveCallState = "ringing" | "active" | "on-hold";

export interface DialRequest {
  /** Extension placing the call. */
  extensionId: ID;
  /** 10 digits, 1 + 10 digits, E.164, 011 + number, an extension, or *98. */
  to: string;
}

export interface Extension {
  id: ID;
  accountId: ID;
  /** Unique in the account, e.g. "101". */
  number: string;
  name: string;
  sipUsername: string;
  /** Null until the extension is active, and for non-admins. */
  sipPassword: string | null;
  status: ExtensionStatus;
  /** Billing purchase state, or null when included capacity was used. */
  purchaseState: string | null;
  purchaseId: string | null;
  /** Not reported yet: null. */
  voicemailBox: string | null;
  forwarding: Forwarding;
  /** External numbers that ring together with this extension. */
  simultaneousRing: E164[];
  userId: ID | null;
  /** Not reported yet: null. */
  devices: RegisteredDevice[] | null;
  /** Not reported yet: "unknown". */
  presence: Presence | "unknown";
  /** Beyond the plan's included extensions, so it has a recurring price. */
  billable: boolean;
  removing: boolean;
  worksUntil: ISODate | null;
  createdAt: ISODate;
}

export type ID = string;

/** `purchase_pending`: an extra extension waiting for payment; `pending`: its SIP login is being set up. */
export type ExtensionStatus = "purchase_pending" | "pending" | "active" | "removing" | "removed";

export interface Forwarding {
  always: ForwardTarget | null;
  busy: ForwardTarget | null;
  noAnswer: ForwardTarget | null;
  noAnswerSeconds: number;
}

export type ForwardTarget =
  | { type: "extension"; extensionId: ID }
  | { type: "external"; number: E164 };

/** E.164 phone number, e.g. "+16315550142" */
export type E164 = string;

export interface RegisteredDevice {
  id: ID;
  userAgent: string;
  transport: "udp" | "tls";
  codec: Codec;
  /** TLS phones use SRTP with SDES. */
  srtp: boolean;
  contact: string;
  registeredAt: ISODate;
  expiresAt: ISODate;
}

export type Codec = "PCMU" | "PCMA" | "G729" | "G723" | "OPUS";

/** ISO-8601 timestamp, e.g. "2026-10-28T14:03:00Z" */
export type ISODate = string;

export type Presence = "online" | "offline" | "busy";

export interface LiveCall {
  id: ID;
  accountId: ID;
  direction: CallDirection;
  from: string;
  to: string;
  /** The account's number the call came in on or presents as caller ID. */
  did: E164 | null;
  /** Extension placing the call (outgoing and internal). */
  fromExtensionId: ID | null;
  /** Extensions ringing right now. */
  ringingExtensionIds: ID[];
  /** External numbers ringing with them. */
  ringingExternalNumbers: E164[];
  /** Extension talking on the call. */
  answeredExtensionId: ID | null;
  state: LiveCallState;
  codec: Codec | null;
  /** Seconds since the call started. */
  elapsedSeconds: number;
  /** Path taken through routing so far. */
  path: string[];
  /** For a call to *98: what the voicemail system is saying now. */
  voicemailPrompt: string | null;
  /** For an attended transfer: the held call this one consults about. */
  consultForCallId: ID | null;
}

export type CallDirection = "incoming" | "outgoing" | "internal";

export type LiveCallState = "ringing" | "active" | "on-hold";

export interface CallHistoryQuery {
  /** Full or partial phone number, matched against calling and called. */
  phone?: string;
  /** Start time at or after this time. */
  from?: ISODate;
  /** Start time before this time. */
  to?: ISODate;
  direction?: CallDirection;
  /** Extension number. */
  extension?: string;
  outcome?: CallOutcome;
  cursor?: string;
  limit?: number;
}

/** ISO-8601 timestamp, e.g. "2026-10-28T14:03:00Z" */
export type ISODate = string;

export type CallDirection = "incoming" | "outgoing" | "internal";

export interface Extension {
  id: ID;
  accountId: ID;
  /** Unique in the account, e.g. "101". */
  number: string;
  name: string;
  sipUsername: string;
  /** Null until the extension is active, and for non-admins. */
  sipPassword: string | null;
  status: ExtensionStatus;
  /** Billing purchase state, or null when included capacity was used. */
  purchaseState: string | null;
  purchaseId: string | null;
  /** Not reported yet: null. */
  voicemailBox: string | null;
  forwarding: Forwarding;
  /** External numbers that ring together with this extension. */
  simultaneousRing: E164[];
  userId: ID | null;
  /** Not reported yet: null. */
  devices: RegisteredDevice[] | null;
  /** Not reported yet: "unknown". */
  presence: Presence | "unknown";
  /** Beyond the plan's included extensions, so it has a recurring price. */
  billable: boolean;
  removing: boolean;
  worksUntil: ISODate | null;
  createdAt: ISODate;
}

export type ID = string;

/** `purchase_pending`: an extra extension waiting for payment; `pending`: its SIP login is being set up. */
export type ExtensionStatus = "purchase_pending" | "pending" | "active" | "removing" | "removed";

export interface Forwarding {
  always: ForwardTarget | null;
  busy: ForwardTarget | null;
  noAnswer: ForwardTarget | null;
  noAnswerSeconds: number;
}

export type ForwardTarget =
  | { type: "extension"; extensionId: ID }
  | { type: "external"; number: E164 };

/** E.164 phone number, e.g. "+16315550142" */
export type E164 = string;

export interface RegisteredDevice {
  id: ID;
  userAgent: string;
  transport: "udp" | "tls";
  codec: Codec;
  /** TLS phones use SRTP with SDES. */
  srtp: boolean;
  contact: string;
  registeredAt: ISODate;
  expiresAt: ISODate;
}

export type Codec = "PCMU" | "PCMA" | "G729" | "G723" | "OPUS";

export type Presence = "online" | "offline" | "busy";

export type CallOutcome = "answered" | "busy" | "no_answer" | "failed" | "blocked";

export interface CursorPage<T> {
  items: T[];
  /** Pass as `cursor` to get the next page; null on the last page. */
  next_cursor: string | null;
  limit: number;
}

export interface CallRecord {
  id: ID;
  account_id: ID;
  direction: CallDirection;
  calling_number: string;
  called_number: string;
  did: E164 | null;
  /** Extension numbers on the call, e.g. ["101", "103"]. */
  extensions: string[];
  /** Path through routing, e.g. ["IVR: Main", "Pressed 2", "Ext 103"]. */
  path: string[];
  status: CallStatus;
  /** Null while active. */
  outcome: CallOutcome | null;
  codec: string | null;
  /** PSTN vendor that carried an outgoing call. */
  vendor: VendorName | null;
  start_time: ISODate;
  answer_time: ISODate | null;
  end_time: ISODate | null;
  recording_id: ID | null;
  /** Answered time after 30/6 rounding; null while active. */
  billable_seconds: number | null;
  /** What we bill, once Billing has rated it. */
  charge_cents: Cents | null;
  /** What the PSTN vendor charges us; null when unknown. */
  cost_cents: Cents | null;
  /** Billable seconds covered by the plan's included US minutes. */
  included_seconds: number | null;
  /** The rate used, e.g. "International (+44)". */
  rate_description: string | null;
}

/** `active` while it runs; `interrupted` if its media server stopped. */
export type CallStatus = "active" | "ended" | "interrupted";

export type VendorName = "us" | "international";

/** Amount in US cents. Per-call amounts and per-minute rates may be fractional. */
export type Cents = number;

export interface CallStats {
  calls_this_period: number | null;
  /** Answered ÷ finished calls, 0–1. */
  answered_rate: number | null;
  avg_duration_seconds: number | null;
  active_calls: number;
  period_start: ISODate | null;
  period_end: ISODate | null;
}

/** ISO-8601 timestamp, e.g. "2026-10-28T14:03:00Z" */
export type ISODate = string;

export interface PhoneSettings {
  /** Ordered by preference; first is offered first in SDP. */
  codecPriority: Codec[];
  enabledCodecs: Codec[];
  holdMusic: string;
  /** The account's number (E.164) shown as caller ID on outgoing calls. */
  callerIdNumberId: E164 | null;
}

export type Codec = "PCMU" | "PCMA" | "G729" | "G723" | "OPUS";

export type ID = string;

/** E.164 phone number, e.g. "+16315550142" */
export type E164 = string;

export type UpdatePhoneSettingsRequest = Partial<PhoneSettings>;

export interface PhoneSettings {
  /** Ordered by preference; first is offered first in SDP. */
  codecPriority: Codec[];
  enabledCodecs: Codec[];
  holdMusic: string;
  /** The account's number (E.164) shown as caller ID on outgoing calls. */
  callerIdNumberId: E164 | null;
}

export type Codec = "PCMU" | "PCMA" | "G729" | "G723" | "OPUS";

export type ID = string;

/** E.164 phone number, e.g. "+16315550142" */
export type E164 = string;

/** The provider's queue lists every account's open tickets. */
export type ProviderTicket = TicketSummary;

/** A ticket in a list. */
export interface TicketSummary {
  id: ID;
  title: string;
  status: TicketStatus;
  account_id: ID;
  created_at: ISODate;
}

export type ID = string;

export type TicketStatus = "open" | "closed";

/** ISO-8601 timestamp, e.g. "2026-10-28T14:03:00Z" */
export type ISODate = string;

export interface RegisterWebPhoneRequest {
  extensionId: ID;
  /** Keep the same web phone as an earlier registration. */
  deviceId?: ID | null;
}

export type ID = string;

export interface WebPhone {
  deviceId: ID;
  extensionId: ID;
  /** Poll its calls more often than this to stay registered. */
  expiresInSeconds: number;
  iceServers: IceServer[];
}

export interface IceServer {
  urls: string[];
  username?: string | null;
  credential?: string | null;
}

export interface Ok {
  ok: true;
}

export interface WebCall {
  /** The browser's leg (`web:…`). */
  id: string;
  /** The live call, for hold, transfer and keys. */
  callId: ID | null;
  direction: "incoming" | "outgoing";
  state: "ringing" | "answered" | "ended";
  /** The caller's number, or the number dialed. */
  peer: string;
  /** Incoming: the PBX's WebRTC offer. */
  offer: string | null;
  /** Outgoing: the PBX's WebRTC answer once answered. */
  answer: string | null;
  /** 180 while the far end rings; 486, 480, 403… when it failed. */
  status: number | null;
}

export type ID = string;

export interface WebDialRequest extends WebSdpRequest {
  to: string;
}

export interface WebSdpRequest {
  sdp: string;
}

export interface WebCall {
  /** The browser's leg (`web:…`). */
  id: string;
  /** The live call, for hold, transfer and keys. */
  callId: ID | null;
  direction: "incoming" | "outgoing";
  state: "ringing" | "answered" | "ended";
  /** The caller's number, or the number dialed. */
  peer: string;
  /** Incoming: the PBX's WebRTC offer. */
  offer: string | null;
  /** Outgoing: the PBX's WebRTC answer once answered. */
  answer: string | null;
  /** 180 while the far end rings; 486, 480, 403… when it failed. */
  status: number | null;
}

export type ID = string;

export interface WebSdpRequest {
  sdp: string;
}

export interface WebCall {
  /** The browser's leg (`web:…`). */
  id: string;
  /** The live call, for hold, transfer and keys. */
  callId: ID | null;
  direction: "incoming" | "outgoing";
  state: "ringing" | "answered" | "ended";
  /** The caller's number, or the number dialed. */
  peer: string;
  /** Incoming: the PBX's WebRTC offer. */
  offer: string | null;
  /** Outgoing: the PBX's WebRTC answer once answered. */
  answer: string | null;
  /** 180 while the far end rings; 486, 480, 403… when it failed. */
  status: number | null;
}

export type ID = string;

export interface WebCall {
  /** The browser's leg (`web:…`). */
  id: string;
  /** The live call, for hold, transfer and keys. */
  callId: ID | null;
  direction: "incoming" | "outgoing";
  state: "ringing" | "answered" | "ended";
  /** The caller's number, or the number dialed. */
  peer: string;
  /** Incoming: the PBX's WebRTC offer. */
  offer: string | null;
  /** Outgoing: the PBX's WebRTC answer once answered. */
  answer: string | null;
  /** 180 while the far end rings; 486, 480, 403… when it failed. */
  status: number | null;
}

export type ID = string;

export interface WebCall {
  /** The browser's leg (`web:…`). */
  id: string;
  /** The live call, for hold, transfer and keys. */
  callId: ID | null;
  direction: "incoming" | "outgoing";
  state: "ringing" | "answered" | "ended";
  /** The caller's number, or the number dialed. */
  peer: string;
  /** Incoming: the PBX's WebRTC offer. */
  offer: string | null;
  /** Outgoing: the PBX's WebRTC answer once answered. */
  answer: string | null;
  /** 180 while the far end rings; 486, 480, 403… when it failed. */
  status: number | null;
}

export type ID = string;