@graph8/sdk 0.251.0 → 0.260.0

package/docs/api/inbox.d.ts

@@ -0,0 +1,709 @@
+/* Generated by sdk/js/scripts/generate-agent-docs.ts from developer-contract/openapi.json. Regenerated on every build. */
+
+/**
+ * Types for `g8.api.inbox` (Inbox): 22 operations.
+ *
+ * For reading. In code, import from the package instead:
+ *   import type { ApiInput, ApiOutput, G8Contract } from "@graph8/sdk";
+ *   type In = ApiInput<"assign_reply_inbox__reply_id__assign_post">;
+ *
+ * Reference with examples: inbox.md
+ */
+/* eslint-disable */
+
+/** `g8.api.inbox.<member>` -> the operationId it calls. */
+export interface InboxMembers {
+  assignReply: "assign_reply_inbox__reply_id__assign_post";
+  autoTagInboxChat: "auto_tag_inbox_chat_inbox_chats_auto_tag_post";
+  createUniversalActivitySavedView: "create_universal_activity_saved_view_universal_activity_save_view_post";
+  discardInboxEmailDraft: "discard_inbox_email_draft_inbox_emails__email_id__draft_delete";
+  getDraft: "get_draft_inbox__reply_id__draft_get";
+  getInboxChat: "get_inbox_chat_inbox_chats__chat_id__get";
+  getInboxEmail: "get_inbox_email_inbox_emails__email_id__get";
+  getReply: "get_reply_inbox__reply_id__get";
+  getUniversalActivityMetrics: "get_universal_activity_metrics_universal_activity_metrics_get";
+  getUniversalActivityPreview: "get_universal_activity_preview_universal_activity_preview__event_id__get";
+  hotContacts: "hot_contacts_inbox_hot_contacts_get";
+  listInbox: "list_inbox_inbox_get";
+  listUniversalActivityQueues: "list_universal_activity_queues_universal_activity_queues_get";
+  listUniversalActivitySavedViews: "list_universal_activity_saved_views_universal_activity_saved_views_get";
+  markInboxChatViewed: "mark_inbox_chat_viewed_inbox_chats__chat_id__mark_viewed_post";
+  queryUniversalActivity: "query_universal_activity_universal_activity_post";
+  searchInboxChats: "search_inbox_chats_inbox_chats_search_post";
+  searchInboxEmails: "search_inbox_emails_inbox_emails_search_post";
+  sendInboxEmail: "send_inbox_email_inbox_emails__email_id__send_post";
+  sendReply: "send_reply_inbox__reply_id__send_post";
+  starInboxChat: "star_inbox_chat_inbox_chats__chat_id__star_put";
+  tagReply: "tag_reply_inbox__reply_id__tag_post";
+}
+
+/** Input and output of every `g8.api.inbox` operation, keyed by operationId. */
+export interface InboxOperations {
+  /**
+   * POST /inbox/{reply_id}/assign
+   * Assign Reply
+   * tier: external · scope: inbox:run
+   */
+  assign_reply_inbox__reply_id__assign_post: {
+    input: {
+    path: {
+      /** Thread/reply ID */
+      reply_id: string;
+    };
+    query?: {
+      /** Channel type */
+      channel?: InboxChannel;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: AssignRequest;
+  };
+    output: ApiResponse_dict_;
+  };
+  /**
+   * POST /inbox/chats/auto-tag
+   * Auto Tag Inbox Chat
+   * tier: write · scope: inbox:write
+   */
+  auto_tag_inbox_chat_inbox_chats_auto_tag_post: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: Record<string, unknown>;
+  };
+    output: ApiResponse_dict_;
+  };
+  /**
+   * POST /universal-activity/save-view
+   * Create Universal Activity Saved View
+   * tier: write · scope: inbox:write
+   */
+  create_universal_activity_saved_view_universal_activity_save_view_post: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: SavedViewCreateRequest;
+  };
+    output: ApiResponse_Any_;
+  };
+  /**
+   * DELETE /inbox/emails/{email_id}/draft
+   * Discard Inbox Email Draft
+   * tier: destructive · scope: inbox:delete
+   */
+  discard_inbox_email_draft_inbox_emails__email_id__draft_delete: {
+    input: {
+    path: {
+      /** Email thread id. */
+      email_id: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_dict_;
+  };
+  /**
+   * GET /inbox/{reply_id}/draft
+   * Get Draft
+   * tier: read · scope: inbox:read
+   */
+  get_draft_inbox__reply_id__draft_get: {
+    input: {
+    path: {
+      /** Thread/reply ID */
+      reply_id: string;
+    };
+    query?: {
+      /** Channel type */
+      channel?: InboxChannel;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_DraftResponse_;
+  };
+  /**
+   * GET /inbox/chats/{chat_id}
+   * Get Inbox Chat
+   * tier: read · scope: inbox:read
+   */
+  get_inbox_chat_inbox_chats__chat_id__get: {
+    input: {
+    path: {
+      /** Chat id. */
+      chat_id: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_InboxPage_;
+  };
+  /**
+   * GET /inbox/emails/{email_id}
+   * Get Inbox Email
+   * tier: read · scope: inbox:read
+   */
+  get_inbox_email_inbox_emails__email_id__get: {
+    input: {
+    path: {
+      /** Email thread id. */
+      email_id: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_InboxPage_;
+  };
+  /**
+   * GET /inbox/{reply_id}
+   * Get Reply
+   * tier: read · scope: inbox:read
+   */
+  get_reply_inbox__reply_id__get: {
+    input: {
+    path: {
+      /** Thread/reply ID */
+      reply_id: string;
+    };
+    query?: {
+      /** Channel type */
+      channel?: InboxChannel;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_InboxThreadResponse_;
+  };
+  /**
+   * GET /universal-activity/metrics
+   * Get Universal Activity Metrics
+   * tier: read · scope: inbox:read
+   */
+  get_universal_activity_metrics_universal_activity_metrics_get: {
+    input: {
+    query: {
+      /** IANA timezone name, e.g. `America/New_York`. */
+      tz: string;
+      range?: "today" | "yesterday" | "week" | "month" | "custom";
+      /** `team` is accepted for back-compat; the service aliases it to `mine`. */
+      scope?: "mine" | "all" | "team";
+      /** Custom range start, inclusive, in `tz`. */
+      start_date?: string | null;
+      /** Custom range end, inclusive, in `tz`. */
+      end_date?: string | null;
+      /** Workspace UUID; omit for org-wide. */
+      workspace_id?: string | null;
+      /** Restrict to one channel. */
+      channel?: string | null;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_Any_;
+  };
+  /**
+   * GET /universal-activity/preview/{event_id}
+   * Get Universal Activity Preview
+   * tier: read · scope: inbox:read
+   */
+  get_universal_activity_preview_universal_activity_preview__event_id__get: {
+    input: {
+    path: {
+      /** Activity event id. */
+      event_id: string;
+    };
+    query?: {
+      /** Comma-separated tabs to hydrate. */
+      tabs?: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_Any_;
+  };
+  /**
+   * GET /inbox/hot-contacts
+   * Hot Contacts
+   * tier: read · scope: inbox:read
+   */
+  hot_contacts_inbox_hot_contacts_get: {
+    input: {
+    query?: {
+      /** Lookback window in days */
+      days?: number;
+      /** Max contacts to return */
+      limit?: number;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_HotContactsResult_;
+  };
+  /**
+   * GET /inbox
+   * List Inbox
+   * tier: read · scope: inbox:read
+   */
+  list_inbox_inbox_get: {
+    input: {
+    query?: {
+      /** Filter by channel: email, sms, linkedin */
+      channel?: InboxChannel | null;
+      /** Filter by sequence (campaign) ID */
+      sequence_id?: string | null;
+      /** Filter by status */
+      status?: string | null;
+      /** Filter by assignee email */
+      assignee?: string | null;
+      /** Filter by tag ID */
+      tag?: string | null;
+      /** Page number */
+      page?: number;
+      /** Items per page */
+      page_size?: number;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_list_InboxThreadResponse__;
+  };
+  /**
+   * GET /universal-activity/queues
+   * List Universal Activity Queues
+   * tier: read · scope: inbox:read
+   */
+  list_universal_activity_queues_universal_activity_queues_get: {
+    input: {
+    query?: {
+      scope?: "mine" | "all" | "team";
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_Any_;
+  };
+  /**
+   * GET /universal-activity/saved-views
+   * List Universal Activity Saved Views
+   * tier: read · scope: inbox:read
+   */
+  list_universal_activity_saved_views_universal_activity_saved_views_get: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_Any_;
+  };
+  /**
+   * POST /inbox/chats/{chat_id}/mark-viewed
+   * Mark Inbox Chat Viewed
+   * tier: write · scope: inbox:write
+   */
+  mark_inbox_chat_viewed_inbox_chats__chat_id__mark_viewed_post: {
+    input: {
+    path: {
+      /** Chat id. */
+      chat_id: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_dict_;
+  };
+  /**
+   * POST /universal-activity
+   * Query Universal Activity
+   * tier: write · scope: inbox:write
+   */
+  query_universal_activity_universal_activity_post: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body?: UniversalActivityQuery;
+  };
+    output: ApiResponse_Any_;
+  };
+  /**
+   * POST /inbox/chats/search
+   * Search Inbox Chats
+   * tier: read · scope: inbox:read
+   */
+  search_inbox_chats_inbox_chats_search_post: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body?: ChatSearchRequest;
+  };
+    output: ApiResponse_InboxPage_;
+  };
+  /**
+   * POST /inbox/emails/search
+   * Search Inbox Emails
+   * tier: read · scope: inbox:read
+   */
+  search_inbox_emails_inbox_emails_search_post: {
+    input: {
+    query?: {
+      page?: number;
+      page_size?: number;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: EmailSearchRequest;
+  };
+    output: ApiResponse_InboxPage_;
+  };
+  /**
+   * POST /inbox/emails/{email_id}/send
+   * Send Inbox Email
+   * tier: external · scope: inbox:run
+   */
+  send_inbox_email_inbox_emails__email_id__send_post: {
+    input: {
+    path: {
+      /** Email thread id. */
+      email_id: string;
+    };
+    query: {
+      /** Mailbox address to send FROM. */
+      mailbox: string;
+      /** Required and not inferred: the same address can be connected either way, and guessing would send through the wrong transport. Declared as a Literal so an unknown value is a request-layer 422 - as a bare `str` it reached `Mailbox(provider)` inside the handler and raised a ValueError, which is a 500 on the single most consequential call on this surface. */
+      provider: "google_mailbox" | "smtp";
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: EmailSendRequest;
+  };
+    output: ApiResponse_dict_;
+  };
+  /**
+   * POST /inbox/{reply_id}/send
+   * Send Reply
+   * tier: external · scope: inbox:run
+   */
+  send_reply_inbox__reply_id__send_post: {
+    input: {
+    path: {
+      /** Thread/reply ID */
+      reply_id: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: SendRequest;
+  };
+    output: ApiResponse_SendResponse_;
+  };
+  /**
+   * PUT /inbox/chats/{chat_id}/star
+   * Star Inbox Chat
+   * tier: write · scope: inbox:write
+   */
+  star_inbox_chat_inbox_chats__chat_id__star_put: {
+    input: {
+    path: {
+      /** Chat id. */
+      chat_id: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: ChatStarRequest;
+  };
+    output: ApiResponse_dict_;
+  };
+  /**
+   * POST /inbox/{reply_id}/tag
+   * Tag Reply
+   * tier: external · scope: inbox:run
+   */
+  tag_reply_inbox__reply_id__tag_post: {
+    input: {
+    path: {
+      /** Thread/reply ID */
+      reply_id: string;
+    };
+    query?: {
+      /** Channel type */
+      channel?: InboxChannel;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: developer_api__interfaces__dtos__inbox__TagRequest;
+  };
+    output: ApiResponse_dict_;
+  };
+}
+
+// 26 schemas referenced above (the same as G8Contract.<Name>).
+
+export interface ApiResponse_Any_ {
+  data: unknown;
+  pagination?: PaginationMeta | null;
+}
+
+export interface ApiResponse_DraftResponse_ {
+  data: DraftResponse;
+  pagination?: PaginationMeta | null;
+}
+
+export interface ApiResponse_HotContactsResult_ {
+  data: HotContactsResult;
+  pagination?: PaginationMeta | null;
+}
+
+export interface ApiResponse_InboxPage_ {
+  data: InboxPage;
+  pagination?: PaginationMeta | null;
+}
+
+export interface ApiResponse_InboxThreadResponse_ {
+  data: InboxThreadResponse;
+  pagination?: PaginationMeta | null;
+}
+
+export interface ApiResponse_SendResponse_ {
+  data: SendResponse;
+  pagination?: PaginationMeta | null;
+}
+
+export interface ApiResponse_dict_ {
+  data: Record<string, unknown>;
+  pagination?: PaginationMeta | null;
+}
+
+export interface ApiResponse_list_InboxThreadResponse__ {
+  data: Array<InboxThreadResponse>;
+  pagination?: PaginationMeta | null;
+}
+
+export interface AssignRequest {
+  /** Email of the user to assign */
+  assignee_email: string;
+}
+
+/** Filter and page the chat inbox. */
+export interface ChatSearchRequest {
+  /** Drop chats carrying ANY of these tag ids. This is what makes a Focused view work - the app sends the archived/deleted/warmup/bounced tags here. Without it those threads come back. */
+  exclude_tag_ids?: Array<string> | null;
+  page?: number;
+  page_size?: number;
+  /** Field to sort by. See `SortByField` for the accepted values. */
+  sort_by?: "updated_at" | "created_at" | "last_message_at";
+  sort_order?: "asc" | "desc";
+  /** Keep chats carrying ANY of these tag ids. */
+  tags?: Array<string> | null;
+  updated_after?: string | null;
+  updated_before?: string | null;
+  /** Restrict to one user's chats. */
+  user_id?: string | null;
+}
+
+/**
+ * Set, rather than toggle, the starred state.
+ *
+ * Declared as a required bool for exactly that reason: a toggle is not
+ * idempotent, so a retried request would silently un-star the thread it just
+ * starred.
+ */
+export interface ChatStarRequest {
+  is_starred: boolean;
+}
+
+export interface DraftResponse {
+  /** Generated draft text (HTML) */
+  content: string;
+  credits_charged?: number;
+  /** Plain text version */
+  plain_content?: string | null;
+}
+
+/** Filter and page email threads across one or more mailboxes. */
+export interface EmailSearchRequest {
+  /** Only threads assigned to this user. */
+  assigned_to_user_email?: string | null;
+  campaign_ids?: Array<string> | null;
+  exclude_tag_ids?: Array<string> | null;
+  /** Mailbox addresses to search. REQUIRED: the inbox is per-mailbox, and an empty list is not 'all mailboxes', it is no result. */
+  mailboxes: Array<string>;
+  search?: string | null;
+  /** Return threads touching ANY of these addresses, in the thread owner or in a message's from/to. OR-matched - a scope filter, not a full-text search. */
+  search_emails?: Array<string> | null;
+  sort_by?: "updated_at" | "created_at" | "last_message_at";
+  sort_order?: "asc" | "desc";
+  /** Keep threads in one delivery state. Closed to the three the internal `EmailStatus` enum accepts - an open string here reaches a strict enum inside the handler and raises a bare `pydantic.ValidationError`, which no handler catches, so it escapes as a 500 instead of a 422. */
+  status?: ("SENT" | "AI_RESPONDED" | "DRAFT") | null;
+  tag_ids?: Array<string> | null;
+  updated_after?: string | null;
+  updated_before?: string | null;
+}
+
+/** The message to send. THIS REACHES A REAL RECIPIENT. */
+export interface EmailSendRequest {
+  bcc_email?: Array<string>;
+  cc_email?: Array<string>;
+  /** Body. */
+  content: string;
+  from_email: Array<string>;
+  /** Message being replied to, to keep the thread. */
+  message_id?: string | null;
+  /** Subject. */
+  subject: string;
+  /** Recipients. At least one. */
+  to: Array<string>;
+}
+
+/** One most-engaged contact (ranked by recent inbound activity). */
+export interface HotContact {
+  contact_id: string;
+  email?: string | null;
+  /** Inbound interaction events in the window */
+  events?: number;
+  /** Most recent inbound activity (ISO) */
+  last_at?: string | null;
+  /** Of those events, how many were meetings */
+  meetings?: number;
+  /** Display name, else email, else id */
+  who?: string | null;
+}
+
+export interface HotContactsResult {
+  contacts?: Array<HotContact>;
+  days: number;
+}
+
+export type InboxChannel = "email" | "sms" | "linkedin";
+
+export interface InboxMessageItem {
+  content?: string | null;
+  date?: string | null;
+  from_address?: string | null;
+  is_draft?: boolean;
+  message_id?: string | null;
+  /** USER, AI, or OTHER */
+  responder?: string | null;
+  to_addresses?: Array<string>;
+}
+
+/** A page of threads, or one thread, exactly as the inbox returns it. */
+export interface InboxPage {
+  items?: Array<Record<string, unknown>>;
+  total?: number;
+  [key: string]: unknown;
+}
+
+export interface InboxThreadResponse {
+  assignees?: Array<Record<string, unknown>>;
+  channel: string;
+  /** Contact snapshot: name, email, company */
+  contact?: Record<string, unknown> | null;
+  created_at?: string | null;
+  id: string;
+  messages?: Array<InboxMessageItem>;
+  status?: string | null;
+  subject?: string | null;
+  tags?: Array<Record<string, unknown>>;
+  updated_at?: string | 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;
+}
+
+/** A named queue + filter combination. */
+export interface SavedViewCreateRequest {
+  /** Filter set to restore. */
+  filters?: Record<string, unknown>;
+  icon?: string | null;
+  /** Display name. */
+  name: string;
+  queue?: string | null;
+  /** Visible to teammates when true. */
+  shared?: boolean;
+}
+
+export interface SendRequest {
+  /** Message body to send */
+  body: string;
+  /** Channel to send through: email, sms, or linkedin */
+  channel: InboxChannel;
+  /** Sender address (mailbox email, phone number, or LinkedIn account ID) */
+  from_address?: string | null;
+  /** Email subject (optional, for email channel) */
+  subject?: string | null;
+  /** Recipient override (email address, phone number, or LinkedIn ID) */
+  to?: string | null;
+}
+
+export interface SendResponse {
+  channel?: string;
+  message_id?: string | null;
+  status?: string;
+}
+
+/**
+ * Filter set for the unified activity timeline. Every field is optional.
+ *
+ * `org_id` is deliberately ABSENT: the org comes from the API key's own
+ * principal, never from the body, so a client cannot steer the query at
+ * another tenant.
+ */
+export interface UniversalActivityQuery {
+  assignee_emails?: Array<string> | null;
+  campaign_ids?: Array<string> | null;
+  /** Restrict to channels, e.g. `["email", "sms"]`. */
+  channels?: Array<string> | null;
+  company_id?: string | null;
+  contact_id?: string | null;
+  /** Opaque cursor from the previous page. */
+  cursor?: string | null;
+  /** `inbound` or `outbound`. */
+  direction?: string | null;
+  exclude_tag_ids?: Array<string> | null;
+  /** Rows per page (1-100). */
+  page_size?: number;
+  /** Named queue to read. */
+  queue?: ("hot_replies" | "follow_up" | "booked_meetings" | "everything") | null;
+  search?: string | null;
+  tag_ids?: Array<string> | null;
+  updated_after?: string | null;
+  updated_before?: string | null;
+  /** Only meaningful with `workspace_id`. A workspace normally auto-scopes the email leg to its own campaign and direct sequences; set true to show all mail through that workspace's mailboxes. */
+  workspace_all_mail?: boolean | null;
+  /** Workspace UUID; omit for org-wide. */
+  workspace_id?: string | null;
+}
+
+export interface developer_api__interfaces__dtos__inbox__TagRequest {
+  /** Tag IDs to associate with the thread */
+  tag_ids: Array<string>;
+}