@graph8/sdk 0.245.0 → 0.260.0

package/docs/api/phoneNumbers.d.ts

@@ -0,0 +1,484 @@
+/* Generated by sdk/js/scripts/generate-agent-docs.ts from developer-contract/openapi.json. Regenerated on every build. */
+
+/**
+ * Types for `g8.api.phoneNumbers` (Phone Numbers): 16 operations.
+ *
+ * For reading. In code, import from the package instead:
+ *   import type { ApiInput, ApiOutput, G8Contract } from "@graph8/sdk";
+ *   type In = ApiInput<"delete_voice_number_voice_numbers_delete">;
+ *
+ * Reference with examples: phoneNumbers.md
+ */
+/* eslint-disable */
+
+/** `g8.api.phoneNumbers.<member>` -> the operationId it calls. */
+export interface PhoneNumbersMembers {
+  deleteVoiceNumber: "delete_voice_number_voice_numbers_delete";
+  getPhoneA2pStatus: "get_phone_a2p_status_phone_numbers_a2p_status_get";
+  getVoiceAnsweringAgent: "get_voice_answering_agent_voice_numbers_answering_agent_get";
+  provisionVoiceNumber: "provision_voice_number_voice_numbers_provision_post";
+  purchasePhoneNumber: "purchase_phone_number_phone_numbers_purchase_post";
+  reconcileA2pRegistration: "reconcile_a2p_registration_phone_numbers_a2p_reconcile_post";
+  releasePhoneNumber: "release_phone_number_phone_numbers_release_post";
+  resetVoiceDailyCounts: "reset_voice_daily_counts_voice_numbers_daily_counts_delete";
+  saveA2pInputs: "save_a2p_inputs_phone_numbers_a2p_inputs_post";
+  searchAvailablePhoneNumbers: "search_available_phone_numbers_phone_numbers_search_post";
+  startA2pRegistration: "start_a2p_registration_phone_numbers_a2p_register_post";
+  updatePhoneAssignee: "update_phone_assignee_phone_numbers_update_assignee_patch";
+  updatePhoneCapabilities: "update_phone_capabilities_phone_numbers_update_capabilities_patch";
+  updateVoiceAssignee: "update_voice_assignee_voice_numbers_assignee_patch";
+  updateVoiceInboundType: "update_voice_inbound_type_voice_numbers_inbound_type_patch";
+  verifyVoiceCallerId: "verify_voice_caller_id_voice_numbers_verify_caller_id__phone_number__post";
+}
+
+/** Input and output of every `g8.api.phoneNumbers` operation, keyed by operationId. */
+export interface PhoneNumbersOperations {
+  /**
+   * DELETE /voice/numbers
+   * Deregister a number from the voice platform
+   * tier: destructive · scope: voice:delete
+   */
+  delete_voice_number_voice_numbers_delete: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: VoiceNumberDeleteRequest;
+  };
+    output: ApiResponse_PhoneNumberPayload_;
+  };
+  /**
+   * GET /phone-numbers/a2p/status
+   * Get Phone A2P Status
+   * tier: read · scope: voice:read
+   */
+  get_phone_a2p_status_phone_numbers_a2p_status_get: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_PhoneA2pStatusPayload_;
+  };
+  /**
+   * GET /voice/numbers/answering-agent
+   * Which agent answers a number
+   * tier: read · scope: voice:read
+   */
+  get_voice_answering_agent_voice_numbers_answering_agent_get: {
+    input: {
+    query?: {
+      /** The number to resolve, E.164. OPTIONAL: with no main line set yet, omitting it returns the organisation's receptionists, which is exactly the list to choose one from. */
+      number?: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_PhoneNumberPayload_;
+  };
+  /**
+   * POST /voice/numbers/provision
+   * Register a number with the voice platform
+   * tier: write · scope: voice:write
+   */
+  provision_voice_number_voice_numbers_provision_post: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: VoiceNumberProvisionRequest;
+  };
+    output: ApiResponse_PhoneNumberPayload_;
+  };
+  /**
+   * POST /phone-numbers/purchase
+   * Buy a phone number
+   * tier: billable · scope: voice:run
+   */
+  purchase_phone_number_phone_numbers_purchase_post: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: PurchasePhoneRequest;
+  };
+    output: ApiResponse_PhoneNumberPayload_;
+  };
+  /**
+   * POST /phone-numbers/a2p/reconcile
+   * Re-run A2P registration for stuck numbers
+   * tier: write · scope: voice:write
+   */
+  reconcile_a2p_registration_phone_numbers_a2p_reconcile_post: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_PhoneNumberPayload_;
+  };
+  /**
+   * POST /phone-numbers/release
+   * Release a phone number
+   * tier: destructive · scope: voice:delete
+   */
+  release_phone_number_phone_numbers_release_post: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: ReleasePhoneRequest;
+  };
+    output: ApiResponse_PhoneNumberPayload_;
+  };
+  /**
+   * DELETE /voice/numbers/daily-counts
+   * Reset today's per-number dialing counters
+   * tier: destructive · scope: voice:delete
+   */
+  reset_voice_daily_counts_voice_numbers_daily_counts_delete: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_PhoneNumberPayload_;
+  };
+  /**
+   * POST /phone-numbers/a2p/inputs
+   * Save A2P brand and campaign details
+   * tier: write · scope: voice:write
+   */
+  save_a2p_inputs_phone_numbers_a2p_inputs_post: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: A2pRegisterRequest;
+  };
+    output: ApiResponse_PhoneNumberPayload_;
+  };
+  /**
+   * POST /phone-numbers/search
+   * Search Available Phone Numbers
+   * tier: read · scope: voice:read
+   */
+  search_available_phone_numbers_phone_numbers_search_post: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: PhoneNumberSearchRequest;
+  };
+    output: ApiResponse_PhoneNumberSearchPayload_;
+  };
+  /**
+   * POST /phone-numbers/a2p/register
+   * Submit A2P 10DLC registration
+   * tier: external · scope: voice:run
+   */
+  start_a2p_registration_phone_numbers_a2p_register_post: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: A2pRegisterRequest;
+  };
+    output: ApiResponse_PhoneNumberPayload_;
+  };
+  /**
+   * PATCH /phone-numbers/update-assignee
+   * Reassign a phone number
+   * tier: write · scope: voice:write
+   */
+  update_phone_assignee_phone_numbers_update_assignee_patch: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: UpdateAssigneeRequest;
+  };
+    output: ApiResponse_PhoneNumberPayload_;
+  };
+  /**
+   * PATCH /phone-numbers/update-capabilities
+   * Switch a number between dialer and voice AI
+   * tier: write · scope: voice:write
+   */
+  update_phone_capabilities_phone_numbers_update_capabilities_patch: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: UpdateCapabilitiesRequest;
+  };
+    output: ApiResponse_PhoneNumberPayload_;
+  };
+  /**
+   * PATCH /voice/numbers/assignee
+   * Set a number's voice-side assignee
+   * tier: write · scope: voice:write
+   */
+  update_voice_assignee_voice_numbers_assignee_patch: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: VoiceAssigneeRequest;
+  };
+    output: ApiResponse_PhoneNumberPayload_;
+  };
+  /**
+   * PATCH /voice/numbers/inbound-type
+   * Change what answers a number's inbound calls
+   * tier: write · scope: voice:write
+   */
+  update_voice_inbound_type_voice_numbers_inbound_type_patch: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: VoiceInboundTypeRequest;
+  };
+    output: ApiResponse_PhoneNumberPayload_;
+  };
+  /**
+   * POST /voice/numbers/verify-caller-id/{phone_number}
+   * Verify a Telnyx number as a caller ID
+   * tier: write · scope: voice:write
+   */
+  verify_voice_caller_id_voice_numbers_verify_caller_id__phone_number__post: {
+    input: {
+    path: {
+      /** The number to verify, E.164. */
+      phone_number: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_PhoneNumberPayload_;
+  };
+}
+
+// 17 schemas referenced above (the same as G8Contract.<Name>).
+
+/**
+ * Brand and campaign details for A2P 10DLC registration.
+ *
+ * Mirrors `phone_numbers.interfaces.fastapi.dtos.A2pRegisterRequest`.
+ *
+ * Both dicts are OPEN and forwarded as-is, matching the app, which types
+ * them as bare `Dict[str, Any]` and stores them in JSONB before handing them
+ * to the carrier registry by name. Closing them here would reject a field
+ * the registry added last week.
+ */
+export interface A2pRegisterRequest {
+  /** The legal business behind the messages: `legal_business_name` (required before registration can start), plus `ein`, `address`, `website`, `business_type`, `vertical` and whatever else the carrier registry asks for. */
+  brand_inputs?: Record<string, unknown>;
+  /** What the messages are: `use_case`, `message_samples` and `opt_in_method` are the three the platform checks for before it considers the inputs complete. */
+  campaign_inputs?: Record<string, unknown>;
+}
+
+export interface ApiResponse_PhoneA2pStatusPayload_ {
+  data: PhoneA2pStatusPayload;
+  pagination?: PaginationMeta | null;
+}
+
+export interface ApiResponse_PhoneNumberPayload_ {
+  data: PhoneNumberPayload;
+  pagination?: PaginationMeta | null;
+}
+
+export interface ApiResponse_PhoneNumberSearchPayload_ {
+  data: PhoneNumberSearchPayload;
+  pagination?: PaginationMeta | null;
+}
+
+export interface PaginationMeta {
+  /** Whether there are more pages */
+  has_next: boolean;
+  /** Items per page */
+  limit: number;
+  /** Opaque cursor for the next page; null when there are no more items. Pass it back as the `cursor` query param to fetch the following page without computing page numbers. */
+  next_cursor?: string | null;
+  /** Current page number (1-indexed) */
+  page: number;
+  /** Total number of items */
+  total: number;
+}
+
+/** The org's A2P brand and campaign registration state. */
+export type PhoneA2pStatusPayload = Record<string, unknown>;
+
+/**
+ * An open envelope for a purchase result, a release, or an A2P job.
+ *
+ * Open on purpose. A purchase returns the stored row (whose capability and
+ * provider-metadata keys differ per provider), a workflow start returns a
+ * `workflow_id`, and the A2P reconcile returns per-number outcomes that grow
+ * as carriers add statuses. Pinning it would silently drop whatever the
+ * provider reported that this contract had not caught up on.
+ */
+export type PhoneNumberPayload = Record<string, unknown>;
+
+/** Numbers available to buy, under `items`. */
+export interface PhoneNumberSearchPayload {
+  items?: Array<unknown>;
+  [key: string]: unknown;
+}
+
+export interface PhoneNumberSearchRequest {
+  area_code?: string | null;
+  /** ISO country code. */
+  country?: string;
+  /** City. Use this or `pattern`, not both. */
+  locality?: string | null;
+  /** Where `pattern` must appear: `first`, `anywhere` or `last`. */
+  match?: string;
+  /** `local` or `toll_free`. */
+  number_type?: string;
+  /** Digits or a phrase the number must contain. */
+  pattern?: string | null;
+  /** The carrier to search - the same values `POST /phone-numbers/purchase` takes. */
+  provider: string;
+}
+
+/**
+ * Buy ONE number from the provider. THIS SPENDS CREDITS AND REAL MONEY.
+ *
+ * Mirrors `phone_numbers.interfaces.fastapi.dtos.PurchasePhoneRequest`
+ * field-for-field. `capabilities` is deliberately absent from both: it was
+ * dropped in the app on 2026-06-02 because the handler never read it and
+ * sending it silently 422'd.
+ */
+export interface PurchasePhoneRequest {
+  /** Who the number belongs to. Defaults to the identity behind the API key, matching the app - it is never taken from the body's organisation, because there is no organisation in the body. */
+  assignee?: string | null;
+  /** True provisions a dialer number; false provisions a voice-AI number. */
+  dialer?: boolean;
+  /** The number to buy, E.164 (e.g. `+14155550123`). Search for one first. */
+  phone_number: string;
+  /** Which carrier to buy it from. */
+  provider: "twilio" | "telnyx";
+  /** True makes this someone's personal work phone - provisioned like a dialer number but tagged `work`, and never part of the outbound caller-ID rotation pool. */
+  work?: boolean;
+}
+
+/**
+ * Give a number back to the carrier. IRREVERSIBLE.
+ *
+ * Mirrors `phone_numbers.interfaces.fastapi.dtos.ReleasePhoneRequest`.
+ */
+export interface ReleasePhoneRequest {
+  /** The number to release, E.164. */
+  phone_number: string;
+  /** The carrier that holds it. It must match what the number was bought from - releasing a Telnyx number as `twilio` reaches the wrong provider. */
+  provider: "twilio" | "telnyx";
+}
+
+/**
+ * Move a number to a different person.
+ *
+ * Mirrors `phone_numbers.interfaces.fastapi.dtos.UpdateAssigneeRequest`.
+ */
+export interface UpdateAssigneeRequest {
+  /** Who owns it now. This drives inbound ring targeting, missed-call notification and the outbound caller-ID pool - it is not a label. */
+  assignee: string;
+  /** The number to reassign, E.164. */
+  phone_number: string;
+}
+
+/**
+ * Switch a number between dialer and voice-AI answering.
+ *
+ * Mirrors `phone_numbers.interfaces.fastapi.dtos.UpdateCapabilitiesRequest`.
+ *
+ * The two flags are not independent in effect: the app derives the voice
+ * service's `inbound_type` as `dialer` only when `dialer` is set and `voice`
+ * is not, and `ai` in every other combination.
+ */
+export interface UpdateCapabilitiesRequest {
+  /** Use the number for outbound dialing. */
+  dialer?: boolean;
+  /** The number to reconfigure, E.164. */
+  phone_number: string;
+  /** Answer inbound calls with a voice AI agent. */
+  voice?: boolean;
+}
+
+/**
+ * Point a number's voice-side assignment at someone else.
+ *
+ * Mirrors `graph8_livekit.schemas.numbers.UpdateAssignee` minus `org_id`.
+ *
+ * `assigned_to` is REQUIRED but may be the empty string, which is how voice
+ * spells "clear the assignment" - its own normalisation passes falsy input
+ * through untouched for exactly that reason.
+ */
+export interface VoiceAssigneeRequest {
+  /** Email of the new assignee, or `""` to clear it. Normalised by voice before storage so inbound ring targeting, the dialer assignee filter and per-rep stat redaction all compare equal. */
+  assigned_to: string;
+  /** The number to reassign, E.164. */
+  number: string;
+}
+
+/**
+ * Retype a number: which system answers its inbound calls.
+ *
+ * Mirrors `graph8_livekit.schemas.numbers.UpdateNumberInboundType` minus
+ * `org_id`, which is taken from the key.
+ *
+ * NOT a label change. `ai`/`sdr` -> `dialer` TEARS DOWN the LiveKit dispatch
+ * rule and both SIP trunks and repoints the carrier webhook; the reverse
+ * creates them again. A number mid-transition answers nothing.
+ */
+export interface VoiceInboundTypeRequest {
+  /** The answering mode to switch to. */
+  inbound_type: "ai" | "sdr" | "dialer" | "work";
+  /** The number to retype, E.164. */
+  number: string;
+}
+
+/**
+ * Tear a number's voice registration down.
+ *
+ * Mirrors the subset of `graph8_livekit.schemas.numbers.Number` that voice's
+ * delete handler actually reads (`number`, `provider`); `org_id` comes from
+ * the key. The remaining `Number` fields are accepted by voice but never
+ * read on this path, so publishing them would advertise knobs that do
+ * nothing.
+ */
+export interface VoiceNumberDeleteRequest {
+  /** The number to deregister, E.164. */
+  number: string;
+  /** The carrier to deregister from. Must match how the number was registered, or the provider-side cleanup silently does nothing while the local record still disappears. */
+  provider?: "twilio" | "telnyx";
+}
+
+/**
+ * Register an already-owned number with the voice platform.
+ *
+ * Mirrors `graph8_livekit.schemas.numbers.Number` field-for-field EXCEPT
+ * `org_id`, which is taken from the API key and can never be sent - see the
+ * router docstring.
+ *
+ * `number`, not `phone_number`: this is voice's field name, and the proxy
+ * sends voice's own wire shape rather than inventing a translation layer
+ * that would have to be kept in step with it.
+ */
+export interface VoiceNumberProvisionRequest {
+  /** Email of the person this number rings for. REQUIRED in practice for a `work` number: without it no phone-directory row is created, so the receptionist can never route to them by name. */
+  assigned_to?: string | null;
+  /** Provision as a dialer number (no LiveKit). */
+  dialer?: boolean;
+  /** How inbound calls are answered. Ignored when `dialer` or `work` is set - those paths provision no LiveKit trunks at all and the type is forced to `dialer` / `work` respectively. */
+  inbound_type?: ("ai" | "sdr" | "dialer" | "work") | null;
+  /** The number to register, E.164. You must already own it. */
+  number: string;
+  /** Which carrier holds the number. */
+  provider?: "twilio" | "telnyx";
+  /** Provision as someone's personal work phone. Implies `dialer`. */
+  work?: boolean;
+}