@graph8/sdk 0.245.0 → 0.260.0

package/docs/api/scans.md

@@ -0,0 +1,136 @@
+<!-- Generated by sdk/js/scripts/generate-agent-docs.ts from developer-contract/openapi.json. Regenerated on every build. -->
+
+# `g8.api.scans`: Scans
+
+2 operations (2 billable).
+
+No hand-written client covers this area. Call it through `g8.api.scans.*` as shown below, or by operationId with `g8.api.call(operationId, input)`.
+
+Every example below assumes this setup (server-side, API key):
+
+```ts
+import { g8 } from "@graph8/sdk";
+
+g8.init({ apiKey: process.env.G8_API_KEY! });
+```
+
+Example values are placeholders that match each field's type. Only required fields are shown. Every example is type-checked against the SDK in CI.
+
+Exact TypeScript types for every operation on this page, and every schema they use: [scans.d.ts](scans.d.ts).
+
+## Operations
+
+| Call | HTTP | Tier | Scope | Summary |
+|---|---|---|---|---|
+| [`createScan`](#op-createscan) | `POST /api/v1/repos/{repo_id}/scan` | billable | `search:run` | Create Scan |
+| [`getScan`](#op-getscan) | `GET /api/v1/repos/{repo_id}/scan` | billable | `search:run` | Get Scan |
+
+---
+
+<a id="op-createscan"></a>
+
+### `g8.api.scans.createScan(input)`
+
+**Create Scan**
+
+- HTTP: `POST /api/v1/repos/{repo_id}/scan`
+- operationId: `create_scan_repos__repo_id__scan_post` (also callable as `g8.api.call("create_scan_repos__repo_id__scan_post", input)`)
+- Tier: `billable`: spends credits; the SDK never blindly retries it; confirm cost before bulk use
+- API-key scope: `search:run`
+
+Record pre-computed repository scan results.
+
+This endpoint does **not** scan a repository server-side — it persists a
+scan produced by the `g8` CLI (or any MCP client that walks the filesystem
+itself). Required fields in the body: ``tech_stack``, ``api_routes``,
+``gtm_readiness``. The server stores the results and links them to the
+repo so subsequent ``/install`` calls can derive a patch set.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.repo_id` | `string` | yes | Repository ID |
+| `body` | `ScanResultsRequest` | yes | Request body; fields below. |
+
+Body fields (`ScanResultsRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.tech_stack` | `Record<string, unknown>` | yes | Detected tech stack (framework, language, etc.) |
+| `body.api_routes` | `Array<Record<string, unknown>>` | no | Detected API routes default `[]` |
+| `body.gtm_readiness` | `Record<string, unknown>` | no | GTM readiness flags default `{}` |
+| `body.product_type` | `string \| null` | no | Detected product type (b2b_saas, api, etc.) |
+| `body.readme_summary` | `string \| null` | no | Extracted README summary |
+| `body.scan_duration_ms` | `integer \| null` | no | Scan duration in milliseconds |
+
+**Returns** `ApiResponse_ScanResponse_`: the envelope `{ data: ScanResponse, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`ScanResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `api_routes` | `Array<Record<string, unknown>>` | yes |  |
+| `id` | `string (uuid)` | yes |  |
+| `repo_id` | `string (uuid)` | yes |  |
+| `tech_stack` | `Record<string, unknown>` | yes |  |
+| `created_at` | `string (date-time) \| null` | no |  |
+| `gtm_readiness` | `Record<string, unknown>` | no | default `{}` |
+| `product_type` | `string \| null` | no |  |
+| `readme_summary` | `string \| null` | no |  |
+| `scan_duration_ms` | `integer \| null` | no |  |
+
+**Example**
+
+```ts
+// billable: spends credits; the SDK never blindly retries it; confirm cost before bulk use.
+const result = await g8.api.scans.createScan({ path: { repo_id: "id" }, body: { tech_stack: {} } });
+```
+
+---
+
+<a id="op-getscan"></a>
+
+### `g8.api.scans.getScan(input)`
+
+**Get Scan**
+
+- HTTP: `GET /api/v1/repos/{repo_id}/scan`
+- operationId: `get_scan_repos__repo_id__scan_get` (also callable as `g8.api.call("get_scan_repos__repo_id__scan_get", input)`)
+- Tier: `billable`: spends credits; the SDK never blindly retries it; confirm cost before bulk use
+- API-key scope: `search:run`
+
+Get the latest scan results for a repository.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.repo_id` | `string` | yes | Repository ID |
+
+**Returns** `ApiResponse_ScanResponse_`: the envelope `{ data: ScanResponse, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`ScanResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `api_routes` | `Array<Record<string, unknown>>` | yes |  |
+| `id` | `string (uuid)` | yes |  |
+| `repo_id` | `string (uuid)` | yes |  |
+| `tech_stack` | `Record<string, unknown>` | yes |  |
+| `created_at` | `string (date-time) \| null` | no |  |
+| `gtm_readiness` | `Record<string, unknown>` | no | default `{}` |
+| `product_type` | `string \| null` | no |  |
+| `readme_summary` | `string \| null` | no |  |
+| `scan_duration_ms` | `integer \| null` | no |  |
+
+**Example**
+
+```ts
+// billable: spends credits; the SDK never blindly retries it; confirm cost before bulk use.
+const result = await g8.api.scans.getScan({ path: { repo_id: "id" } });
+```

package/docs/api/scheduleBuy.d.ts

@@ -0,0 +1,293 @@
+/* Generated by sdk/js/scripts/generate-agent-docs.ts from developer-contract/openapi.json. Regenerated on every build. */
+
+/**
+ * Types for `g8.api.scheduleBuy` (Schedule Buy): 9 operations.
+ *
+ * For reading. In code, import from the package instead:
+ *   import type { ApiInput, ApiOutput, G8Contract } from "@graph8/sdk";
+ *   type In = ApiInput<"cancel_plan_mailboxes_schedule_buy_plans__plan_id__delete">;
+ *
+ * Reference with examples: scheduleBuy.md
+ */
+/* eslint-disable */
+
+/** `g8.api.scheduleBuy.<member>` -> the operationId it calls. */
+export interface ScheduleBuyMembers {
+  cancelPlan: "cancel_plan_mailboxes_schedule_buy_plans__plan_id__delete";
+  checkPlanDomains: "check_plan_domains_mailboxes_schedule_buy_check_domains_post";
+  createPlan: "create_plan_mailboxes_schedule_buy_plans_post";
+  getPlan: "get_plan_mailboxes_schedule_buy_plans__plan_id__get";
+  listPlans: "list_plans_mailboxes_schedule_buy_plans_get";
+  pausePlan: "pause_plan_mailboxes_schedule_buy_plans__plan_id__pause_post";
+  resumePlan: "resume_plan_mailboxes_schedule_buy_plans__plan_id__resume_post";
+  suggestPlan: "suggest_plan_mailboxes_schedule_buy_suggest_post";
+  suggestPlanDomains: "suggest_plan_domains_mailboxes_schedule_buy_suggest_domains_post";
+}
+
+/** Input and output of every `g8.api.scheduleBuy` operation, keyed by operationId. */
+export interface ScheduleBuyOperations {
+  /**
+   * DELETE /mailboxes/schedule-buy/plans/{plan_id}
+   * Cancel Plan
+   * tier: destructive · scope: campaigns:delete
+   */
+  cancel_plan_mailboxes_schedule_buy_plans__plan_id__delete: {
+    input: {
+    path: {
+      /** Schedule Buy plan id - from GET /mailboxes/schedule-buy/plans */
+      plan_id: number;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_MailboxDomainPayload_;
+  };
+  /**
+   * POST /mailboxes/schedule-buy/check-domains
+   * Check Plan Domains
+   * tier: read · scope: campaigns:read
+   */
+  check_plan_domains_mailboxes_schedule_buy_check_domains_post: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: ScheduleBuyDomainCheckRequest;
+  };
+    output: ApiResponse_MailboxDomainListPayload_;
+  };
+  /**
+   * POST /mailboxes/schedule-buy/plans
+   * Create Plan
+   * tier: billable · scope: campaigns:run
+   */
+  create_plan_mailboxes_schedule_buy_plans_post: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: ScheduleBuyPlanRequest;
+  };
+    output: ApiResponse_MailboxDomainPayload_;
+  };
+  /**
+   * GET /mailboxes/schedule-buy/plans/{plan_id}
+   * Get Plan
+   * tier: read · scope: campaigns:read
+   */
+  get_plan_mailboxes_schedule_buy_plans__plan_id__get: {
+    input: {
+    path: {
+      /** Schedule Buy plan id - from GET /mailboxes/schedule-buy/plans */
+      plan_id: number;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_MailboxDomainPayload_;
+  };
+  /**
+   * GET /mailboxes/schedule-buy/plans
+   * List Plans
+   * tier: read · scope: campaigns:read
+   */
+  list_plans_mailboxes_schedule_buy_plans_get: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_MailboxDomainListPayload_;
+  };
+  /**
+   * POST /mailboxes/schedule-buy/plans/{plan_id}/pause
+   * Pause Plan
+   * tier: write · scope: campaigns:write
+   */
+  pause_plan_mailboxes_schedule_buy_plans__plan_id__pause_post: {
+    input: {
+    path: {
+      /** Schedule Buy plan id - from GET /mailboxes/schedule-buy/plans */
+      plan_id: number;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_MailboxDomainPayload_;
+  };
+  /**
+   * POST /mailboxes/schedule-buy/plans/{plan_id}/resume
+   * Resume Plan
+   * tier: billable · scope: campaigns:run
+   */
+  resume_plan_mailboxes_schedule_buy_plans__plan_id__resume_post: {
+    input: {
+    path: {
+      /** Schedule Buy plan id - from GET /mailboxes/schedule-buy/plans */
+      plan_id: number;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_MailboxDomainPayload_;
+  };
+  /**
+   * POST /mailboxes/schedule-buy/suggest
+   * Suggest Plan
+   * tier: read · scope: campaigns:read
+   */
+  suggest_plan_mailboxes_schedule_buy_suggest_post: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: ScheduleBuySuggestRequest;
+  };
+    output: ApiResponse_MailboxDomainPayload_;
+  };
+  /**
+   * POST /mailboxes/schedule-buy/suggest-domains
+   * Suggest Plan Domains
+   * tier: read · scope: campaigns:read
+   */
+  suggest_plan_domains_mailboxes_schedule_buy_suggest_domains_post: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: ScheduleBuyDomainSuggestRequest;
+  };
+    output: ApiResponse_MailboxDomainPayload_;
+  };
+}
+
+// 9 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;
+}
+
+/**
+ * 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>;
+
+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;
+}
+
+/** Validate edited candidate names: owned-by-you, and available. SPENDS NOTHING. */
+export interface ScheduleBuyDomainCheckRequest {
+  /** Domain names to validate */
+  names: Array<string>;
+}
+
+/** Preview the domain names a plan WOULD buy. SPENDS NOTHING. */
+export interface ScheduleBuyDomainSuggestRequest {
+  /** Names to exclude */
+  avoid?: Array<string> | null;
+  /** How many candidate names to return */
+  count: number;
+  /** Extension to generate against, e.g. '.com' */
+  domain_tld?: string;
+  /** Rotate the generator to get fresh candidates */
+  offset?: number;
+  /** Where to attach the root */
+  pattern?: ("prefix" | "suffix" | "both") | null;
+  /** Word roots to build names from */
+  roots?: Array<string> | null;
+  /** Restrict to these extensions */
+  tlds?: Array<string> | null;
+}
+
+/**
+ * Create and LOCK a staggered buying plan. PLACES REAL CREDIT HOLDS.
+ *
+ * Mirrors the app's ``CreatePlanRequest`` field for field, including its
+ * mutual-exclusion rule between ``persona_ids`` and the manual
+ * ``registrants``/``mailbox_aliases`` pair - the app raises that in a
+ * validator, and it must fire as a 422 here rather than inside the proxy.
+ */
+export interface ScheduleBuyPlanRequest {
+  /** Sends per mailbox per day */
+  daily_send_cap?: number;
+  /** Approved names to buy, in order */
+  domain_names?: Array<string> | null;
+  /** Extension to buy, e.g. '.com' */
+  domain_tld?: string;
+  /** Domains bought per daily batch */
+  domains_per_batch?: number;
+  /** Idle mailboxes you already hold, from /suggest */
+  idle_mailboxes_snapshot: number;
+  /** One alias per mailbox_per_domain. Required unless persona_ids is set. */
+  mailbox_aliases?: Array<Record<string, unknown>>;
+  /** Mailboxes bought on each domain */
+  mailboxes_per_domain?: number;
+  /** Sender personas to buy for. Excludes the two above. */
+  persona_ids?: Array<number> | null;
+  /** Registrant identities. Required unless persona_ids is set. */
+  registrants?: Array<Record<string, unknown>>;
+  /** Adopt these owned EMPTY domains instead of buying */
+  reuse_domains?: Array<string> | null;
+  /** Sending days assumed per month */
+  sending_days_per_month?: number;
+  /** Contacts you intend to reach per month */
+  target_monthly_volume: number;
+  /** Warmup engine the bought mailboxes are enrolled with */
+  warmup_provider?: "warmy" | "instantly" | "smartlead";
+  /** Existing provisioning workspace to reuse */
+  workspace_uid?: string | null;
+}
+
+/**
+ * Size a plan for a target volume: idle capacity, net-new domains and mailboxes, credit cost.
+ * SPENDS NOTHING. Mirrors the app's `SuggestRequest` field for field.
+ */
+export interface ScheduleBuySuggestRequest {
+  /** Sends per mailbox per day */
+  daily_send_cap?: number;
+  /** Domains bought per daily batch */
+  domains_per_batch?: number;
+  /** Mailboxes bought on each domain */
+  mailboxes_per_domain?: number;
+  /** Sending days assumed per month */
+  sending_days_per_month?: number;
+  /** Contacts you intend to reach per month */
+  target_monthly_volume: number;
+}