@graph8/sdk 0.251.0 → 0.262.0

package/docs/api/seo.d.ts

@@ -0,0 +1,447 @@
+/* Generated by sdk/js/scripts/generate-agent-docs.ts from developer-contract/openapi.json. Regenerated on every build. */
+
+/**
+ * Types for `g8.api.seo` (SEO): 11 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">;
+ *
+ * Reference with examples: seo.md
+ */
+/* eslint-disable */
+
+/** `g8.api.seo.<member>` -> the operationId it calls. */
+export interface SeoMembers {
+  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";
+  getSeoRankHistory: "get_seo_rank_history_seo_rank_tracking__keyword_id__history_get";
+  listSeoAudits: "list_seo_audits_seo_audits_get";
+  listSeoTrackedKeywords: "list_seo_tracked_keywords_seo_rank_tracking_get";
+  removeSeoTrackedKeywords: "remove_seo_tracked_keywords_seo_rank_tracking_keywords_remove_post";
+  researchSeoKeywords: "research_seo_keywords_seo_keywords_research_post";
+  saveSeoTrackedKeywords: "save_seo_tracked_keywords_seo_rank_tracking_keywords_post";
+  startSeoAudit: "start_seo_audit_seo_audits_post";
+}
+
+/** Input and output of every `g8.api.seo` operation, keyed by operationId. */
+export interface SeoOperations {
+  /**
+   * GET /seo/audits/{audit_id}
+   * Get Seo Audit
+   * tier: read · scope: intent:read
+   */
+  get_seo_audit_seo_audits__audit_id__get: {
+    input: {
+    path: {
+      audit_id: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_SeoAudit_;
+  };
+  /**
+   * GET /seo/audits/{audit_id}/issues
+   * Get Seo Audit Issues
+   * tier: read · scope: intent:read
+   */
+  get_seo_audit_issues_seo_audits__audit_id__issues_get: {
+    input: {
+    path: {
+      audit_id: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_SeoAuditIssues_;
+  };
+  /**
+   * GET /seo/domains/{domain}/backlinks
+   * Get Seo Domain Backlinks
+   * tier: billable · scope: intent:run
+   */
+  get_seo_domain_backlinks_seo_domains__domain__backlinks_get: {
+    input: {
+    path: {
+      /** A bare domain - no scheme, no path. `www.` is stripped. */
+      domain: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_SeoBacklinksOverview_;
+  };
+  /**
+   * GET /seo/domains/{domain}/overview
+   * Get Seo Domain Overview
+   * tier: billable · scope: intent:run
+   */
+  get_seo_domain_overview_seo_domains__domain__overview_get: {
+    input: {
+    path: {
+      /** A bare domain - no scheme, no path. `www.` is stripped. */
+      domain: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_SeoDomainOverviewResponse_;
+  };
+  /**
+   * GET /seo/rank-tracking/{keyword_id}/history
+   * Get Seo Rank History
+   * tier: read · scope: intent:read
+   */
+  get_seo_rank_history_seo_rank_tracking__keyword_id__history_get: {
+    input: {
+    path: {
+      /** A tracked keyword id from `GET /seo/rank-tracking`. */
+      keyword_id: string;
+    };
+    query?: {
+      /** How far back to read snapshots. */
+      days?: number;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_SeoRankHistory_;
+  };
+  /**
+   * GET /seo/audits
+   * List Seo Audits
+   * tier: read · scope: intent:read
+   */
+  list_seo_audits_seo_audits_get: {
+    input: {
+    query?: {
+      limit?: number;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_List_SeoAudit__;
+  };
+  /**
+   * GET /seo/rank-tracking
+   * List Seo Tracked Keywords
+   * tier: read · scope: intent:read
+   */
+  list_seo_tracked_keywords_seo_rank_tracking_get: {
+    input: {
+    query?: {
+      /** Only keywords tracked for this domain. */
+      domain?: string | null;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_List_SeoTrackedKeyword__;
+  };
+  /**
+   * POST /seo/rank-tracking/keywords/remove
+   * Remove Seo Tracked Keywords
+   * tier: write · scope: intent:write
+   */
+  remove_seo_tracked_keywords_seo_rank_tracking_keywords_remove_post: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: SeoRemoveTrackedKeywordsRequest;
+  };
+    output: ApiResponse_SeoRemovedKeywords_;
+  };
+  /**
+   * POST /seo/keywords/research
+   * Research Seo Keywords
+   * tier: billable · scope: intent:run
+   */
+  research_seo_keywords_seo_keywords_research_post: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: SeoResearchKeywordsRequest;
+  };
+    output: ApiResponse_SeoResearchKeywordsResponse_;
+  };
+  /**
+   * POST /seo/rank-tracking/keywords
+   * Save Seo Tracked Keywords
+   * tier: write · scope: intent:write
+   */
+  save_seo_tracked_keywords_seo_rank_tracking_keywords_post: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: SeoSaveTrackedKeywordsRequest;
+  };
+    output: ApiResponse_List_SeoTrackedKeyword__;
+  };
+  /**
+   * POST /seo/audits
+   * Start Seo Audit
+   * tier: billable · scope: intent:run
+   */
+  start_seo_audit_seo_audits_post: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: SeoStartAuditRequest;
+  };
+    output: ApiResponse_SeoAudit_;
+  };
+}
+
+// 27 schemas referenced above (the same as G8Contract.<Name>).
+
+export interface ApiResponse_List_SeoAudit__ {
+  data: Array<SeoAudit>;
+  pagination?: PaginationMeta | null;
+}
+
+export interface ApiResponse_List_SeoTrackedKeyword__ {
+  data: Array<SeoTrackedKeyword>;
+  pagination?: PaginationMeta | null;
+}
+
+export interface ApiResponse_SeoAuditIssues_ {
+  data: SeoAuditIssues;
+  pagination?: PaginationMeta | null;
+}
+
+export interface ApiResponse_SeoAudit_ {
+  data: SeoAudit;
+  pagination?: PaginationMeta | null;
+}
+
+export interface ApiResponse_SeoBacklinksOverview_ {
+  data: SeoBacklinksOverview;
+  pagination?: PaginationMeta | null;
+}
+
+export interface ApiResponse_SeoDomainOverviewResponse_ {
+  data: SeoDomainOverviewResponse;
+  pagination?: PaginationMeta | null;
+}
+
+export interface ApiResponse_SeoRankHistory_ {
+  data: SeoRankHistory;
+  pagination?: PaginationMeta | null;
+}
+
+export interface ApiResponse_SeoRemovedKeywords_ {
+  data: SeoRemovedKeywords;
+  pagination?: PaginationMeta | null;
+}
+
+export interface ApiResponse_SeoResearchKeywordsResponse_ {
+  data: SeoResearchKeywordsResponse;
+  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;
+}
+
+/** Mirrors `AuditDTO`. */
+export interface SeoAudit {
+  completed_at?: string | null;
+  created_at?: string | null;
+  credits_charged?: number | null;
+  domain: string;
+  failure_reason?: string | null;
+  id: string;
+  max_pages: number;
+  onpage_score?: number | null;
+  pages_crawled?: number | null;
+  state: SeoAuditState;
+  status: string;
+  summary_checks?: Record<string, unknown>;
+}
+
+/** Mirrors `AuditIssueDTO`. */
+export interface SeoAuditIssue {
+  affected_count: number;
+  affected_urls?: Array<Record<string, unknown>>;
+  issue_type: string;
+  severity: string;
+}
+
+/** Mirrors `AuditIssuesResponse`. */
+export interface SeoAuditIssues {
+  audit_id: string;
+  issues: Array<SeoAuditIssue>;
+}
+
+/**
+ * Mirrors `AuditStateDTO` - the plain-language, recovery-oriented view of
+ * where an audit is, so a caller can explain the state rather than parse
+ * raw provider text.
+ */
+export interface SeoAuditState {
+  /** Whether to offer a manual 'Run a new audit' action */
+  can_run_again: boolean;
+  /** Lifecycle state category driving the plain-language status + recovery UX */
+  category: "queued" | "running" | "complete" | "timeout" | "provider_error" | "credit_issue" | "start_error" | "failed";
+  /** Plain-language explanation of what happened */
+  detail: string;
+  /** Secondary technical detail (raw provider text) */
+  diagnostic?: string | null;
+  /** One-line human status */
+  headline: string;
+  /** No further automatic progress will happen */
+  is_terminal: boolean;
+  /** Short status chip label */
+  label: string;
+  /** Plain-language, safe next step (may be empty) */
+  recovery: string;
+}
+
+/** Mirrors `BacklinksOverviewResponse`. */
+export interface SeoBacklinksOverview {
+  authority_score?: number | null;
+  dofollow?: number | null;
+  nofollow?: number | null;
+  referring_domains?: number | null;
+  total_backlinks?: number | null;
+}
+
+/**
+ * Mirrors `DomainOverviewResponse`. `data_freshness` labels how old the
+ * provider's view of the domain is - research surfaces must say.
+ */
+export interface SeoDomainOverviewResponse {
+  data_freshness?: string;
+  overview: Record<string, unknown>;
+  top_keywords: Array<Record<string, unknown>>;
+  top_pages: Array<Record<string, unknown>>;
+}
+
+/** Mirrors `KeywordRow`. */
+export interface SeoKeywordRow {
+  competition?: number;
+  cpc?: number;
+  intent?: string | null;
+  keyword: string;
+  keyword_difficulty?: number | null;
+  search_volume?: number;
+}
+
+/** Mirrors `RankHistoryResponse`. */
+export interface SeoRankHistory {
+  keyword_id: string;
+  snapshots: Array<SeoRankSnapshot>;
+}
+
+/** Mirrors `RankSnapshotDTO`. */
+export interface SeoRankSnapshot {
+  rank?: number | null;
+  serp_url?: string | null;
+  snapshot_date: string;
+}
+
+/** Mirrors `RemoveTrackedKeywordsRequest`. */
+export interface SeoRemoveTrackedKeywordsRequest {
+  keyword_ids: Array<string>;
+}
+
+/**
+ * How many tracked keywords the remove call deleted. The app answers a
+ * bare `{"removed": n}`; this names the shape so the SDK can type it.
+ */
+export interface SeoRemovedKeywords {
+  removed: number;
+}
+
+/**
+ * Mirrors `ResearchKeywordsRequest`.
+ *
+ * `limit` is capped at 150 - the same ceiling the app, the agent tool and the
+ * UI share - so a larger ask is a 422 here rather than a silent truncation.
+ */
+export interface SeoResearchKeywordsRequest {
+  language_code?: string;
+  limit?: number;
+  location_code?: number;
+  mode?: "auto" | "ideas" | "related" | "suggestions";
+  seed_keyword: string;
+}
+
+/**
+ * Mirrors `ResearchKeywordsResponse`.
+ *
+ * `keywords` rows are the provider's row shape for the chosen `mode`, passed
+ * through rather than flattened, because the four modes return different
+ * columns and flattening would drop the ones a caller asked for.
+ */
+export interface SeoResearchKeywordsResponse {
+  keywords?: Array<Record<string, unknown>>;
+  seed?: SeoKeywordRow | null;
+}
+
+/**
+ * Mirrors `SaveTrackedKeywordsRequest`.
+ *
+ * `domain` is normalised by the app (lower-cased, `www.` stripped) and
+ * refused with a 422 if it carries a scheme or a path.
+ */
+export interface SeoSaveTrackedKeywordsRequest {
+  cadence?: "daily" | "weekly";
+  domain: string;
+  keywords: Array<SeoTrackKeywordItem>;
+  language_code?: string;
+  location_code?: number;
+}
+
+/**
+ * Mirrors `StartAuditRequest`. `max_pages` is the crawl ceiling and the
+ * thing the credit reservation is sized from.
+ */
+export interface SeoStartAuditRequest {
+  domain: string;
+  max_pages?: number;
+}
+
+/** Mirrors `TrackKeywordItem`. */
+export interface SeoTrackKeywordItem {
+  keyword: string;
+  search_volume?: number | null;
+}
+
+/** Mirrors `TrackedKeywordDTO`. */
+export interface SeoTrackedKeyword {
+  cadence: string;
+  created_at?: string | null;
+  domain: string;
+  id: string;
+  keyword: string;
+  language_code: string;
+  latest_checked_at?: string | null;
+  latest_rank?: number | null;
+  latest_serp_url?: string | null;
+  location_code: number;
+  search_volume?: number | null;
+}