@graph8/sdk 0.251.0 → 0.260.0

package/docs/api/deliverability.d.ts

@@ -0,0 +1,418 @@
+/* Generated by sdk/js/scripts/generate-agent-docs.ts from developer-contract/openapi.json. Regenerated on every build. */
+
+/**
+ * Types for `g8.api.deliverability` (Deliverability): 17 operations.
+ *
+ * For reading. In code, import from the package instead:
+ *   import type { ApiInput, ApiOutput, G8Contract } from "@graph8/sdk";
+ *   type In = ApiInput<"check_domain_blocklist_deliverability_blocklist_check_post">;
+ *
+ * Reference with examples: deliverability.md
+ */
+/* eslint-disable */
+
+/** `g8.api.deliverability.<member>` -> the operationId it calls. */
+export interface DeliverabilityMembers {
+  checkDomainBlocklist: "check_domain_blocklist_deliverability_blocklist_check_post";
+  createBlocklistRemovalRequest: "create_blocklist_removal_request_deliverability_recovery_removal_requests_post";
+  decideMailboxRetirement: "decide_mailbox_retirement_deliverability_recovery_decide_post";
+  getAutopilotPreferences: "get_autopilot_preferences_deliverability_autopilot_preferences_get";
+  getCapacityPlan: "get_capacity_plan_deliverability_capacity_plan_get";
+  getDomainReport: "get_domain_report_deliverability_domain__domain__report_get";
+  getFleetSummary: "get_fleet_summary_deliverability_fleet_summary_get";
+  getMailboxRecoveryHistory: "get_mailbox_recovery_history_deliverability_recovery_mailboxes__mailbox_id__history_get";
+  getMailboxRecoveryOverview: "get_mailbox_recovery_overview_deliverability_recovery_get";
+  getSafeToSend: "get_safe_to_send_deliverability_safe_to_send_get";
+  getSequencesHealth: "get_sequences_health_deliverability_sequences_health_get";
+  listAutopilotApprovals: "list_autopilot_approvals_deliverability_autopilot_approvals_get";
+  listDegradedMailboxes: "list_degraded_mailboxes_deliverability_degraded_get";
+  listDeliverabilityFindings: "list_deliverability_findings_deliverability_findings_get";
+  setAutopilotPreferences: "set_autopilot_preferences_deliverability_autopilot_preferences_put";
+  undoMailboxRetirement: "undo_mailbox_retirement_deliverability_recovery_undo_post";
+  updateBlocklistRemovalRequest: "update_blocklist_removal_request_deliverability_recovery_removal_requests__request_id__patch";
+}
+
+/** Input and output of every `g8.api.deliverability` operation, keyed by operationId. */
+export interface DeliverabilityOperations {
+  /**
+   * POST /deliverability/blocklist/check
+   * Check Domain Blocklist
+   * tier: read · scope: campaigns:read
+   */
+  check_domain_blocklist_deliverability_blocklist_check_post: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: BlocklistCheckRequest;
+  };
+    output: ApiResponse_MailboxRecoveryPayload_;
+  };
+  /**
+   * POST /deliverability/recovery/removal-requests
+   * Create Blocklist Removal Request
+   * tier: write · scope: campaigns:write
+   */
+  create_blocklist_removal_request_deliverability_recovery_removal_requests_post: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: BlocklistRemovalCreateRequest;
+  };
+    output: ApiResponse_MailboxRecoveryPayload_;
+  };
+  /**
+   * POST /deliverability/recovery/decide
+   * Decide Mailbox Retirement
+   * tier: destructive · scope: campaigns:delete
+   */
+  decide_mailbox_retirement_deliverability_recovery_decide_post: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: RetirementDecisionRequest;
+  };
+    output: ApiResponse_MailboxRecoveryPayload_;
+  };
+  /**
+   * GET /deliverability/autopilot/preferences
+   * Get Autopilot Preferences
+   * tier: read · scope: campaigns:read
+   */
+  get_autopilot_preferences_deliverability_autopilot_preferences_get: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_MailboxDomainPayload_;
+  };
+  /**
+   * GET /deliverability/capacity-plan
+   * Get Capacity Plan
+   * tier: read · scope: campaigns:read
+   */
+  get_capacity_plan_deliverability_capacity_plan_get: {
+    input: {
+    query: {
+      /** Volume you intend to send per month. */
+      contacts_per_month: number;
+      /** Days you want to spread that volume over. */
+      delivery_days?: number;
+      /** Assume new mailboxes must warm up before they count as capacity. */
+      warmed?: boolean;
+      /** Extension to price against. */
+      domain_tld?: string;
+      /** Treat the target as ADDITIONAL volume: mailboxes already in live sequences are not capacity. */
+      exclude_committed?: boolean;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_MailboxDomainPayload_;
+  };
+  /**
+   * GET /deliverability/domain/{domain}/report
+   * Get Domain Report
+   * tier: read · scope: campaigns:read
+   */
+  get_domain_report_deliverability_domain__domain__report_get: {
+    input: {
+    path: {
+      /** Sending domain name, e.g. acme-outreach.com */
+      domain: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_MailboxDomainPayload_;
+  };
+  /**
+   * GET /deliverability/fleet-summary
+   * Get Fleet Summary
+   * tier: read · scope: campaigns:read
+   */
+  get_fleet_summary_deliverability_fleet_summary_get: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_MailboxDomainPayload_;
+  };
+  /**
+   * GET /deliverability/recovery/mailboxes/{mailbox_id}/history
+   * Get Mailbox Recovery History
+   * tier: read · scope: campaigns:read
+   */
+  get_mailbox_recovery_history_deliverability_recovery_mailboxes__mailbox_id__history_get: {
+    input: {
+    path: {
+      /** Mailbox id. */
+      mailbox_id: number;
+    };
+    query?: {
+      weeks?: number;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_MailboxRecoveryListPayload_;
+  };
+  /**
+   * GET /deliverability/recovery
+   * Get Mailbox Recovery Overview
+   * tier: read · scope: campaigns:read
+   */
+  get_mailbox_recovery_overview_deliverability_recovery_get: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_MailboxRecoveryPayload_;
+  };
+  /**
+   * GET /deliverability/safe-to-send
+   * Get Safe To Send
+   * tier: read · scope: campaigns:read
+   */
+  get_safe_to_send_deliverability_safe_to_send_get: {
+    input: {
+    query?: {
+      /** Limit the verdict to one domain. Omit for the whole fleet. */
+      domain?: string | null;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_MailboxDomainPayload_;
+  };
+  /**
+   * GET /deliverability/sequences-health
+   * Get Sequences Health
+   * tier: read · scope: campaigns:read
+   */
+  get_sequences_health_deliverability_sequences_health_get: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_MailboxDomainPayload_;
+  };
+  /**
+   * GET /deliverability/autopilot/approvals
+   * List Autopilot Approvals
+   * tier: read · scope: campaigns:read
+   */
+  list_autopilot_approvals_deliverability_autopilot_approvals_get: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_MailboxDomainListPayload_;
+  };
+  /**
+   * GET /deliverability/degraded
+   * List Degraded Mailboxes
+   * tier: read · scope: campaigns:read
+   */
+  list_degraded_mailboxes_deliverability_degraded_get: {
+    input: {
+    query?: {
+      /** 'watch' returns everything of concern; 'paused' only what has already stopped sending. */
+      min_severity?: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_MailboxDomainListPayload_;
+  };
+  /**
+   * GET /deliverability/findings
+   * List Deliverability Findings
+   * tier: read · scope: campaigns:read
+   */
+  list_deliverability_findings_deliverability_findings_get: {
+    input: {
+    query?: {
+      /** Filter by lifecycle state. */
+      status?: string | null;
+      /** Filter by severity. */
+      severity?: string | null;
+      /** Filter by signal name, e.g. dmarc, mailbox_health. */
+      signal?: string | null;
+      /** Newest first. The app's own ceiling. */
+      limit?: number;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_MailboxDomainListPayload_;
+  };
+  /**
+   * PUT /deliverability/autopilot/preferences
+   * Set Autopilot Preferences
+   * tier: billable · scope: campaigns:run
+   */
+  set_autopilot_preferences_deliverability_autopilot_preferences_put: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: AutopilotPreferencesRequest;
+  };
+    output: ApiResponse_MailboxDomainPayload_;
+  };
+  /**
+   * POST /deliverability/recovery/undo
+   * Undo Mailbox Retirement
+   * tier: write · scope: campaigns:write
+   */
+  undo_mailbox_retirement_deliverability_recovery_undo_post: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: RetirementUndoRequest;
+  };
+    output: ApiResponse_MailboxRecoveryPayload_;
+  };
+  /**
+   * PATCH /deliverability/recovery/removal-requests/{request_id}
+   * Update Blocklist Removal Request
+   * tier: write · scope: campaigns:write
+   */
+  update_blocklist_removal_request_deliverability_recovery_removal_requests__request_id__patch: {
+    input: {
+    path: {
+      /** Removal request id. */
+      request_id: number;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: BlocklistRemovalUpdateRequest;
+  };
+    output: ApiResponse_MailboxRecoveryPayload_;
+  };
+}
+
+// 15 schemas referenced above (the same as G8Contract.<Name>).
+
+export interface ApiResponse_MailboxDomainListPayload_ {
+  data: MailboxDomainListPayload;
+  pagination?: PaginationMeta | null;
+}
+
+export interface ApiResponse_MailboxDomainPayload_ {
+  data: MailboxDomainPayload;
+  pagination?: PaginationMeta | null;
+}
+
+export interface ApiResponse_MailboxRecoveryListPayload_ {
+  data: MailboxRecoveryListPayload;
+  pagination?: PaginationMeta | null;
+}
+
+export interface ApiResponse_MailboxRecoveryPayload_ {
+  data: MailboxRecoveryPayload;
+  pagination?: PaginationMeta | null;
+}
+
+/**
+ * Replace the org's deliverability-autopilot preferences.
+ *
+ * ``mode='auto'`` authorises the autopilot to retire and REPLACE failing
+ * mailboxes without asking, up to ``monthly_spend_ceiling_credits`` of the
+ * org's credits each month. That is why this is not an ordinary write.
+ */
+export interface AutopilotPreferencesRequest {
+  /** Ceiling on automatic retirements per calendar month */
+  max_auto_retirements_per_month: number;
+  /** 'approval' queues every retirement for a human; 'auto' lets the autopilot act and SPEND */
+  mode: "approval" | "auto";
+  /** Ceiling on credits the autopilot may spend per calendar month */
+  monthly_spend_ceiling_credits: number;
+}
+
+export interface BlocklistCheckRequest {
+  /** Up to 50 domains or hostnames. */
+  domains: Array<string>;
+}
+
+export interface BlocklistRemovalCreateRequest {
+  /** The listed sending domain. */
+  domain_id: number;
+  /** Your reference for the removal ticket. */
+  ticket_ref?: string | null;
+}
+
+export interface BlocklistRemovalUpdateRequest {
+  ticket_ref: string;
+}
+
+/**
+ * An open envelope for a LIST result, so a bare list keeps its shape.
+ *
+ * A named collection (``{"plans": [...]}``) keeps its own key AND gains
+ * ``items``, so a caller can page every list surface the same way without
+ * memorising which key each route chose.
+ */
+export interface MailboxDomainListPayload {
+  items?: Array<unknown>;
+  [key: string]: unknown;
+}
+
+/**
+ * An open envelope for one provider/deliverability result.
+ *
+ * Open on purpose. These payloads are provider state and advisory reads whose
+ * contents grow with the product, and a dropped field reads as "nothing to
+ * report" rather than "we did not tell you". Every value passes through
+ * ``scrub_vendor_names`` on the way in.
+ */
+export type MailboxDomainPayload = Record<string, unknown>;
+
+/** Weekly health points or blocklist verdicts under `items`. */
+export interface MailboxRecoveryListPayload {
+  items?: Array<unknown>;
+  [key: string]: unknown;
+}
+
+/** The recovery overview, a decision outcome, or a removal request. */
+export type MailboxRecoveryPayload = Record<string, unknown>;
+
+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;
+}
+
+export interface RetirementDecisionRequest {
+  decision: "approved" | "rejected";
+  /** The retirement's 4-character code. */
+  short_code: string;
+}
+
+export interface RetirementUndoRequest {
+  /** The retirement's 4-character code. */
+  short_code: string;
+}