@graph8/sdk 0.308.1 → 0.358.0

package/docs/api/scheduleBuy.md

@@ -143,13 +143,14 @@ moment this returns. `total_credits_held` in the response is the figure.
 Org admins and owners only, and only for an org on a paid or pre-funded
 plan. 402 if the balance cannot cover the plan, 429 if the org has locked
 more than five plans this hour, 400 for an unsupported extension or an
-empty plan.
+empty plan. With `reuse_domains`, 409 when a domain's mailbox count changed
+(or it filled up) while the plan was locking: nothing stays held, re-read
+the domains and lock again.
 
-`persona_ids` and the manual `registrants`/`mailbox_aliases` pair are
-mutually exclusive: name the personas OR spell the identities out, never
-both. `idle_mailboxes_snapshot` is your own count, used to detect drift -
-the server recomputes it and returns its own as
-`server_idle_mailboxes`.
+At least one `persona_ids` entry is required. Manual `registrants` /
+`mailbox_aliases` are not accepted for new plans. `idle_mailboxes_snapshot`
+is your own count, used to detect drift - the server recomputes it and
+returns its own as `server_idle_mailboxes`.
 
 Send an `Idempotency-Key` header. A retried lock without one places a
 second full set of holds.
@@ -170,11 +171,11 @@ Body fields (`ScheduleBuyPlanRequest`):
 | `body.domain_names` | `Array<string> \| null` | no | Approved names to buy, in order min items 1, max items 500 |
 | `body.domain_tld` | `string` | no | Extension to buy, e.g. '.com' default `".com"` |
 | `body.domains_per_batch` | `integer` | no | Domains bought per daily batch default `10`, min 1, max 100 |
-| `body.mailbox_aliases` | `Array<Record<string, unknown>>` | no | One alias per mailbox_per_domain. Required unless persona_ids is set. |
+| `body.mailbox_aliases` | `Array<Record<string, unknown>>` | no | Not accepted for new plans. Use persona_ids. |
 | `body.mailboxes_per_domain` | `integer` | no | Mailboxes bought on each domain default `3`, min 1, max 5 |
-| `body.persona_ids` | `Array<integer> \| null` | no | Sender personas to buy for. Excludes the two above. min items 1, max items 20 |
-| `body.registrants` | `Array<Record<string, unknown>>` | no | Registrant identities. Required unless persona_ids is set. max items 20 |
-| `body.reuse_domains` | `Array<string> \| null` | no | Adopt these owned EMPTY domains instead of buying min items 1, max items 500 |
+| `body.persona_ids` | `Array<integer> \| null` | no | Sender identity IDs. At least one is required to start a schedule. max items 20 |
+| `body.registrants` | `Array<Record<string, unknown>>` | no | Not accepted for new plans. Use persona_ids. max items 20 |
+| `body.reuse_domains` | `Array<string> \| null` | no | Adopt these owned domains instead of buying. Each must have fewer live mailboxes than mailboxes_per_domain; the plan tops it up and holds credits for exactly the missing ones min items 1, max items 500 |
 | `body.sending_days_per_month` | `integer` | no | Sending days assumed per month default `22`, min 1, max 31 |
 | `body.warmup_provider` | `"warmy" \| "instantly" \| "smartlead"` | no | Warmup engine the bought mailboxes are enrolled with default `"warmy"` |
 | `body.workspace_uid` | `string \| null` | no | Existing provisioning workspace to reuse |
@@ -367,6 +368,8 @@ Body fields (`ScheduleBuySuggestRequest`):
 | `body.daily_send_cap` | `integer` | no | Sends per mailbox per day default `15`, min 1, max 100 |
 | `body.domains_per_batch` | `integer` | no | Domains bought per daily batch default `10`, min 1, max 100 |
 | `body.mailboxes_per_domain` | `integer` | no | Mailboxes bought on each domain default `3`, min 1, max 5 |
+| `body.reuse_domain_count` | `integer \| null` | no | Price a REUSE plan over this many owned domains instead min 1, max 500 |
+| `body.reuse_missing_mailboxes` | `integer \| null` | no | With reuse_domain_count: the total mailboxes those domains are missing (each domain: mailboxes_per_domain minus its live mailboxes). Omitted, every domain is priced as empty min 1, max 2500 |
 | `body.sending_days_per_month` | `integer` | no | Sending days assumed per month default `22`, min 1, max 31 |
 
 **Returns** `ApiResponse_MailboxDomainPayload_`: the envelope `{ data: MailboxDomainPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.

package/docs/api/seo.d.ts

@@ -1,11 +1,11 @@
 /* Generated by sdk/js/scripts/generate-agent-docs.ts from developer-contract/openapi.json. Regenerated on every build. */
 
 /**
- * Types for `g8.api.seo` (SEO): 14 operations.
+ * Types for `g8.api.seo` (SEO): 22 operations.
  *
  * For reading. In code, import from the package instead:
  *   import type { ApiInput, ApiOutput, G8Contract } from "@graph8/sdk";
- *   type In = ApiInput<"get_seo_audit_seo_audits__audit_id__get">;
+ *   type In = ApiInput<"claim_seo_fix_seo_fixes__fix_id__claim_post">;
  *
  * Reference with examples: seo.md
  */
@@ -13,14 +13,22 @@
 
 /** `g8.api.seo.<member>` -> the operationId it calls. */
 export interface SeoMembers {
+  claimSeoFix: "claim_seo_fix_seo_fixes__fix_id__claim_post";
+  completeSeoFix: "complete_seo_fix_seo_fixes__fix_id__complete_post";
+  getSeoAgentHandoff: "get_seo_agent_handoff_seo_fixes_agent_handoff_get";
   getSeoAudit: "get_seo_audit_seo_audits__audit_id__get";
   getSeoAuditIssues: "get_seo_audit_issues_seo_audits__audit_id__issues_get";
   getSeoDomainBacklinks: "get_seo_domain_backlinks_seo_domains__domain__backlinks_get";
   getSeoDomainOverview: "get_seo_domain_overview_seo_domains__domain__overview_get";
+  getSeoFixPack: "get_seo_fix_pack_seo_fixes__fix_id__pack_get";
+  getSeoPage360: "get_seo_page_360_seo_pages_360_detail_get";
   getSeoRankHistory: "get_seo_rank_history_seo_rank_tracking__keyword_id__history_get";
+  getSeoToday: "get_seo_today_seo_today_get";
   getSeoTrackedDomain: "get_seo_tracked_domain_seo_domains_tracked__domain__get";
   listSeoAudits: "list_seo_audits_seo_audits_get";
   listSeoDomainPages: "list_seo_domain_pages_seo_domains_tracked__domain__pages_get";
+  listSeoFixes: "list_seo_fixes_seo_fixes_get";
+  listSeoPages360: "list_seo_pages_360_seo_pages_360_get";
   listSeoTrackedDomains: "list_seo_tracked_domains_seo_domains_tracked_get";
   listSeoTrackedKeywords: "list_seo_tracked_keywords_seo_rank_tracking_get";
   removeSeoTrackedKeywords: "remove_seo_tracked_keywords_seo_rank_tracking_keywords_remove_post";
@@ -31,6 +39,59 @@ export interface SeoMembers {
 
 /** Input and output of every `g8.api.seo` operation, keyed by operationId. */
 export interface SeoOperations {
+  /**
+   * POST /seo/fixes/{fix_id}/claim
+   * Claim Seo Fix
+   * tier: write · scope: intent:write
+   */
+  claim_seo_fix_seo_fixes__fix_id__claim_post: {
+    input: {
+    path: {
+      /** A fix id from `GET /seo/fixes`. */
+      fix_id: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body?: SeoClaimFixRequest;
+  };
+    output: ApiResponse_SeoClaimFixResponse_;
+  };
+  /**
+   * POST /seo/fixes/{fix_id}/complete
+   * Complete Seo Fix
+   * tier: write · scope: intent:write
+   */
+  complete_seo_fix_seo_fixes__fix_id__complete_post: {
+    input: {
+    path: {
+      /** A fix id from `GET /seo/fixes`. */
+      fix_id: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: SeoCompleteFixRequest;
+  };
+    output: ApiResponse_SeoCompleteFixResponse_;
+  };
+  /**
+   * GET /seo/fixes/agent-handoff
+   * Get Seo Agent Handoff
+   * tier: read · scope: intent:read
+   */
+  get_seo_agent_handoff_seo_fixes_agent_handoff_get: {
+    input: {
+    query?: {
+      /** Only fixes for this domain. */
+      domain?: string | null;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_SeoAgentHandoff_;
+  };
   /**
    * GET /seo/audits/{audit_id}
    * Get Seo Audit
@@ -97,6 +158,42 @@ export interface SeoOperations {
   };
     output: ApiResponse_SeoDomainOverviewResponse_;
   };
+  /**
+   * GET /seo/fixes/{fix_id}/pack
+   * Get Seo Fix Pack
+   * tier: read · scope: intent:read
+   */
+  get_seo_fix_pack_seo_fixes__fix_id__pack_get: {
+    input: {
+    path: {
+      /** A fix id from `GET /seo/fixes`. */
+      fix_id: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_SeoAgentFixPack_;
+  };
+  /**
+   * GET /seo/pages/360/detail
+   * Get Seo Page 360
+   * tier: read · scope: intent:read
+   */
+  get_seo_page_360_seo_pages_360_detail_get: {
+    input: {
+    query: {
+      /** A tracked domain. */
+      domain: string;
+      /** The page URL or path, e.g. /pricing. */
+      url: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_SeoPage360_;
+  };
   /**
    * GET /seo/rank-tracking/{keyword_id}/history
    * Get Seo Rank History
@@ -118,6 +215,23 @@ export interface SeoOperations {
   };
     output: ApiResponse_SeoRankHistory_;
   };
+  /**
+   * GET /seo/today
+   * Get Seo Today
+   * tier: read · scope: intent:read
+   */
+  get_seo_today_seo_today_get: {
+    input: {
+    query?: {
+      /** A tracked domain. Omit for the primary one. */
+      domain?: string | null;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_SeoToday_;
+  };
   /**
    * GET /seo/domains/tracked/{domain}
    * Get Seo Tracked Domain
@@ -179,6 +293,51 @@ export interface SeoOperations {
   };
     output: ApiResponse_SeoDomainPages_;
   };
+  /**
+   * GET /seo/fixes
+   * List Seo Fixes
+   * tier: read · scope: intent:read
+   */
+  list_seo_fixes_seo_fixes_get: {
+    input: {
+    query?: {
+      /** Only fixes for this domain. */
+      domain?: string | null;
+      /** Fixes to return, most severe first. */
+      limit?: number;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_SeoAgentFixQueue_;
+  };
+  /**
+   * GET /seo/pages/360
+   * List Seo Pages 360
+   * tier: read · scope: intent:read
+   */
+  list_seo_pages_360_seo_pages_360_get: {
+    input: {
+    query: {
+      /** A tracked domain. */
+      domain: string;
+      /** Only pages whose path contains this text. */
+      q?: string;
+      sort?: "pageviews" | "clicks" | "position" | "companies" | "pipeline" | "issues";
+      order?: "asc" | "desc";
+      filter?: "all" | "money" | "decay" | "fixes" | "companies" | "slow";
+      /** Rows to return. */
+      limit?: number;
+      /** Rows to skip. */
+      offset?: number;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_SeoPages360_;
+  };
   /**
    * GET /seo/domains/tracked
    * List Seo Tracked Domains
@@ -267,7 +426,7 @@ export interface SeoOperations {
   };
 }
 
-// 37 schemas referenced above (the same as G8Contract.<Name>).
+// 69 schemas referenced above (the same as G8Contract.<Name>).
 
 export interface ApiResponse_List_SeoAudit__ {
   data: Array<SeoAudit>;
@@ -279,6 +438,21 @@ export interface ApiResponse_List_SeoTrackedKeyword__ {
   pagination?: PaginationMeta | null;
 }
 
+export interface ApiResponse_SeoAgentFixPack_ {
+  data: SeoAgentFixPack;
+  pagination?: PaginationMeta | null;
+}
+
+export interface ApiResponse_SeoAgentFixQueue_ {
+  data: SeoAgentFixQueue;
+  pagination?: PaginationMeta | null;
+}
+
+export interface ApiResponse_SeoAgentHandoff_ {
+  data: SeoAgentHandoff;
+  pagination?: PaginationMeta | null;
+}
+
 export interface ApiResponse_SeoAuditIssues_ {
   data: SeoAuditIssues;
   pagination?: PaginationMeta | null;
@@ -294,6 +468,16 @@ export interface ApiResponse_SeoBacklinksOverview_ {
   pagination?: PaginationMeta | null;
 }
 
+export interface ApiResponse_SeoClaimFixResponse_ {
+  data: SeoClaimFixResponse;
+  pagination?: PaginationMeta | null;
+}
+
+export interface ApiResponse_SeoCompleteFixResponse_ {
+  data: SeoCompleteFixResponse;
+  pagination?: PaginationMeta | null;
+}
+
 export interface ApiResponse_SeoDomainOverviewResponse_ {
   data: SeoDomainOverviewResponse;
   pagination?: PaginationMeta | null;
@@ -304,6 +488,16 @@ export interface ApiResponse_SeoDomainPages_ {
   pagination?: PaginationMeta | null;
 }
 
+export interface ApiResponse_SeoPage360_ {
+  data: SeoPage360;
+  pagination?: PaginationMeta | null;
+}
+
+export interface ApiResponse_SeoPages360_ {
+  data: SeoPages360;
+  pagination?: PaginationMeta | null;
+}
+
 export interface ApiResponse_SeoRankHistory_ {
   data: SeoRankHistory;
   pagination?: PaginationMeta | null;
@@ -319,6 +513,11 @@ export interface ApiResponse_SeoResearchKeywordsResponse_ {
   pagination?: PaginationMeta | null;
 }
 
+export interface ApiResponse_SeoToday_ {
+  data: SeoToday;
+  pagination?: PaginationMeta | null;
+}
+
 export interface ApiResponse_SeoTrackedDomainDetail_ {
   data: SeoTrackedDomainDetail;
   pagination?: PaginationMeta | null;
@@ -348,6 +547,80 @@ export interface PaginationMeta {
   total_is_lower_bound?: boolean | null;
 }
 
+/** One fix with exact instructions: the page, the steps, the code to add and how success is checked. */
+export interface SeoAgentFix {
+  acceptance: Array<string>;
+  category: string;
+  domain: string;
+  files?: Record<string, string>;
+  fix_id: string;
+  severity: string;
+  snippets?: Array<SeoAgentSnippet>;
+  status: string;
+  steps: Array<string>;
+  target_url?: string | null;
+  title: string;
+  why?: string;
+}
+
+export interface SeoAgentFixPack {
+  agents_md: string;
+  claude_md: string;
+  files?: Record<string, string>;
+  fix: SeoAgentFix;
+}
+
+export interface SeoAgentFixQueue {
+  agents_md: string;
+  count: number;
+  domain?: string | null;
+  fixes: Array<SeoAgentFix>;
+}
+
+export interface SeoAgentHandoff {
+  domain?: string | null;
+  files: Record<string, string>;
+  fix_count: number;
+  setup: SeoAgentSetup;
+}
+
+export interface SeoAgentSetup {
+  claude_code: string;
+  cursor: SeoAgentSetupCursor;
+  mcp_url: string;
+  prompt: string;
+  tools: Array<string>;
+}
+
+export interface SeoAgentSetupCursor {
+  command: string;
+  file: string;
+  json: string;
+}
+
+export interface SeoAgentSnippet {
+  code: string;
+  file_hint?: string;
+  label: string;
+  language?: string;
+}
+
+export interface SeoApprovalItem {
+  category: string;
+  confidence?: "measured" | "estimated" | "partial";
+  delivery: string;
+  fix_id: string;
+  impact?: Record<string, unknown> | null;
+  severity: string;
+  target_url?: string | null;
+  title: string;
+}
+
+export interface SeoApprovalQueue {
+  count: number;
+  items: Array<SeoApprovalItem>;
+}
+
 /** Mirrors `AuditDTO`. */
 export interface SeoAudit {
   completed_at?: string | null;
@@ -411,6 +684,33 @@ export interface SeoBacklinksOverview {
   total_backlinks?: number | null;
 }
 
+export interface SeoClaimFixRequest {
+  /** A label for this agent, e.g. claude-code. */
+  agent?: string | null;
+}
+
+export interface SeoClaimFixResponse {
+  claim_note: string;
+  claimed: boolean;
+  claimed_by?: string | null;
+  fix: SeoAgentFix;
+}
+
+export interface SeoCompleteFixRequest {
+  agent?: string | null;
+  note?: string;
+  outcome?: "done" | "failed";
+  /** Commit SHA or commit/pull request URL. */
+  ref?: string | null;
+}
+
+export interface SeoCompleteFixResponse {
+  applied_ref?: string | null;
+  fix_id: string;
+  status: string;
+  verification?: string | null;
+}
+
 /**
  * Mirrors `DomainChangeDTO`: the current snapshot against the one nearest
  * 30 days back. `traffic_pct` is null when the baseline traffic was zero.
@@ -455,6 +755,13 @@ export interface SeoDomainPages {
   total: number;
 }
 
+export interface SeoEndOfDay {
+  ask: string;
+  risk: string;
+  win: string;
+  work_channel_id?: string | null;
+}
+
 /** Mirrors `KeywordRow`. */
 export interface SeoKeywordRow {
   competition?: number;
@@ -465,6 +772,34 @@ export interface SeoKeywordRow {
   search_volume?: number;
 }
 
+export interface SeoMover {
+  confidence?: "measured" | "estimated" | "partial";
+  delta?: number | null;
+  detail: string;
+  from_value?: number | null;
+  kind: "rank_up" | "rank_down" | "gsc_drop" | "gsc_gain" | "low_ctr";
+  title: string;
+  to_value?: number | null;
+  url?: string | null;
+}
+
+/** One page in full: its Page360 snapshot plus top queries and open fixes. Extra snapshot keys pass through. */
+export interface SeoPage360 {
+  fixes?: Array<Record<string, unknown>>;
+  queries?: Array<Record<string, unknown>>;
+  [key: string]: unknown;
+}
+
+/** The Page360 grid: one row per page with Search Console, vitals, visitors and fix counts. */
+export interface SeoPages360 {
+  gsc_connected: boolean;
+  last_sync_at?: string | null;
+  limit: number;
+  offset: number;
+  rows: Array<Record<string, unknown>>;
+  total: number;
+}
+
 /** Mirrors `RankHistoryResponse`. */
 export interface SeoRankHistory {
   keyword_id: string;
@@ -524,13 +859,27 @@ export interface SeoResearchKeywordsResponse {
  * refused with a 422 if it carries a scheme or a path.
  */
 export interface SeoSaveTrackedKeywordsRequest {
-  cadence?: "daily" | "weekly";
+  cadence?: "daily" | "weekly" | "manual";
   domain: string;
   keywords: Array<SeoTrackKeywordItem>;
   language_code?: string;
   location_code?: number;
 }
 
+export interface SeoSetupChecklist {
+  done_count: number;
+  items: Array<SeoSetupItem>;
+  total: number;
+}
+
+export interface SeoSetupItem {
+  action: SeoTodayAction;
+  done: boolean;
+  hint: string;
+  key: "gsc" | "domain" | "competitors" | "prompts" | "fix_delivery";
+  label: string;
+}
+
 /**
  * Mirrors `StartAuditRequest`. `max_pages` is the crawl ceiling and the
  * thing the credit reservation is sized from.
@@ -540,6 +889,60 @@ export interface SeoStartAuditRequest {
   max_pages?: number;
 }
 
+/** Today in Signals > SEO: KPIs, the briefing, the approval queue, movers, alerts and the setup checklist. */
+export interface SeoToday {
+  alerts: Array<SeoTodayAlert>;
+  approval_queue: SeoApprovalQueue;
+  briefing: Array<SeoTodayCard>;
+  domain?: string | null;
+  end_of_day: SeoEndOfDay;
+  generated_at: string;
+  health_score?: number | null;
+  kpis: Array<SeoTodayKpi>;
+  movers: Array<SeoMover>;
+  setup: SeoSetupChecklist;
+  sources?: Record<string, boolean>;
+}
+
+export interface SeoTodayAction {
+  fix_id?: string | null;
+  href?: string | null;
+  kind: "goto_tab" | "settings" | "approve_fix" | "link";
+  label: string;
+  tab?: string | null;
+}
+
+export interface SeoTodayAlert {
+  action?: SeoTodayAction | null;
+  body: string;
+  fired_at: string;
+  id: string;
+  kind: string;
+  payload?: Record<string, unknown>;
+  severity: "critical" | "high" | "medium" | "low";
+  title: string;
+}
+
+export interface SeoTodayCard {
+  action: SeoTodayAction;
+  category: string;
+  confidence?: "measured" | "estimated" | "partial";
+  detail: string;
+  id: string;
+  severity: "critical" | "high" | "medium" | "low";
+  stake?: string | null;
+  title: string;
+}
+
+export interface SeoTodayKpi {
+  confidence?: "measured" | "estimated" | "partial";
+  delta_pct?: number | null;
+  hint?: string | null;
+  key: string;
+  label: string;
+  value?: number | null;
+}
+
 /** Mirrors `TrackKeywordItem`. */
 export interface SeoTrackKeywordItem {
   keyword: string;