@graph8/sdk 0.251.0 → 0.262.0

package/docs/api/scraping.md

@@ -0,0 +1,383 @@
+<!-- Generated by sdk/js/scripts/generate-agent-docs.ts from developer-contract/openapi.json. Regenerated on every build. -->
+
+# `g8.api.scraping`: Scraping
+
+10 operations (5 read, 3 write, 1 billable, 1 external).
+
+No hand-written client covers this area. Call it through `g8.api.scraping.*` 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: [scraping.d.ts](scraping.d.ts).
+
+## Operations
+
+| Call | HTTP | Tier | Scope | Summary |
+|---|---|---|---|---|
+| [`confirmScrapeJob`](#op-confirmscrapejob) | `POST /api/v1/scrape/jobs/{job_id}/confirm` | write | `enrichment:write` | Confirm Scrape Job |
+| [`exportScrapeJobCsv`](#op-exportscrapejobcsv) | `GET /api/v1/scrape/jobs/{job_id}/export.csv` | read | `enrichment:read` | Export Scrape Job Csv |
+| [`getCrawlStatus`](#op-getcrawlstatus) | `GET /api/v1/settings/scrape-config/crawl/status/{job_id}` | read | `enrichment:read` | Get Crawl Status |
+| [`getScrapeConfig`](#op-getscrapeconfig) | `GET /api/v1/settings/scrape-config` | read | `enrichment:read` | Get Scrape Config |
+| [`getScrapeJob`](#op-getscrapejob) | `GET /api/v1/scrape/jobs/{job_id}` | read | `enrichment:read` | Get Scrape Job |
+| [`listScrapeAdapters`](#op-listscrapeadapters) | `GET /api/v1/scrape/adapters` | read | `enrichment:read` | List Scrape Adapters |
+| [`rejectScrapeJob`](#op-rejectscrapejob) | `POST /api/v1/scrape/jobs/{job_id}/reject` | write | `enrichment:write` | Reject Scrape Job |
+| [`startFullSiteCrawl`](#op-startfullsitecrawl) | `POST /api/v1/settings/scrape-config/crawl` | external | `enrichment:run` | Start Full Site Crawl |
+| [`submitScrapeRequest`](#op-submitscraperequest) | `POST /api/v1/scrape/requests` | billable | `enrichment:run` | Submit Scrape Request |
+| [`updateScrapeConfig`](#op-updatescrapeconfig) | `PATCH /api/v1/settings/scrape-config` | write | `enrichment:write` | Update Scrape Config |
+
+---
+
+<a id="op-confirmscrapejob"></a>
+
+### `g8.api.scraping.confirmScrapeJob(input)`
+
+**Confirm Scrape Job**
+
+- HTTP: `POST /api/v1/scrape/jobs/{job_id}/confirm`
+- operationId: `confirm_scrape_job_scrape_jobs__job_id__confirm_post` (also callable as `g8.api.call("confirm_scrape_job_scrape_jobs__job_id__confirm_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `enrichment:write`
+
+Accept a scrape result, so what it found is kept.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.job_id` | `string` | yes | Scrape job id. |
+
+**Returns** `ApiResponse_SettingsPayload_`: the envelope `{ data: SettingsPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.scraping.confirmScrapeJob({ path: { job_id: "id" } });
+```
+
+---
+
+<a id="op-exportscrapejobcsv"></a>
+
+### `g8.api.scraping.exportScrapeJobCsv(input)`
+
+**Export Scrape Job Csv**
+
+- HTTP: `GET /api/v1/scrape/jobs/{job_id}/export.csv`
+- operationId: `export_scrape_job_csv_scrape_jobs__job_id__export_csv_get` (also callable as `g8.api.call("export_scrape_job_csv_scrape_jobs__job_id__export_csv_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `enrichment:read`
+
+Download one scrape run's results as a CSV file.
+
+A FILE, not the JSON envelope - the same bytes the app's download button
+serves. Results live for 7 days after a run finishes; after that this is a
+404 naming the reason, never an empty file that reads like a run that found
+nothing.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.job_id` | `string` | yes | Scrape job id. |
+
+**Returns**: no JSON body is declared for the success response.
+
+**Example**
+
+```ts
+const result = await g8.api.scraping.exportScrapeJobCsv({ path: { job_id: "id" } });
+```
+
+---
+
+<a id="op-getcrawlstatus"></a>
+
+### `g8.api.scraping.getCrawlStatus(input)`
+
+**Get Crawl Status**
+
+- HTTP: `GET /api/v1/settings/scrape-config/crawl/status/{job_id}`
+- operationId: `get_crawl_status_settings_scrape_config_crawl_status__job_id__get` (also callable as `g8.api.call("get_crawl_status_settings_scrape_config_crawl_status__job_id__get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `enrichment:read`
+
+How far a site crawl has got.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.job_id` | `string` | yes | Crawl job id. |
+
+**Returns** `ApiResponse_SettingsPayload_`: the envelope `{ data: SettingsPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.scraping.getCrawlStatus({ path: { job_id: "id" } });
+```
+
+---
+
+<a id="op-getscrapeconfig"></a>
+
+### `g8.api.scraping.getScrapeConfig(input?)`
+
+**Get Scrape Config**
+
+- HTTP: `GET /api/v1/settings/scrape-config`
+- operationId: `get_scrape_config_settings_scrape_config_get` (also callable as `g8.api.call("get_scrape_config_settings_scrape_config_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `enrichment:read`
+
+How the org scrapes: which pages, how deep, how often.
+
+**Input**: none.
+
+**Returns** `ApiResponse_SettingsPayload_`: the envelope `{ data: SettingsPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.scraping.getScrapeConfig();
+```
+
+---
+
+<a id="op-getscrapejob"></a>
+
+### `g8.api.scraping.getScrapeJob(input)`
+
+**Get Scrape Job**
+
+- HTTP: `GET /api/v1/scrape/jobs/{job_id}`
+- operationId: `get_scrape_job_scrape_jobs__job_id__get` (also callable as `g8.api.call("get_scrape_job_scrape_jobs__job_id__get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `enrichment:read`
+
+One scrape job and its result.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.job_id` | `string` | yes | Scrape job id. |
+
+**Returns** `ApiResponse_SettingsPayload_`: the envelope `{ data: SettingsPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.scraping.getScrapeJob({ path: { job_id: "id" } });
+```
+
+---
+
+<a id="op-listscrapeadapters"></a>
+
+### `g8.api.scraping.listScrapeAdapters(input?)`
+
+**List Scrape Adapters**
+
+- HTTP: `GET /api/v1/scrape/adapters`
+- operationId: `list_scrape_adapters_scrape_adapters_get` (also callable as `g8.api.call("list_scrape_adapters_scrape_adapters_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `enrichment:read`
+
+Which scrapers are available, and what each is good for.
+
+**Input**: none.
+
+**Returns** `ApiResponse_SettingsListPayload_`: the envelope `{ data: SettingsListPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`SettingsListPayload` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `items` | `Array<unknown>` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.scraping.listScrapeAdapters();
+```
+
+---
+
+<a id="op-rejectscrapejob"></a>
+
+### `g8.api.scraping.rejectScrapeJob(input)`
+
+**Reject Scrape Job**
+
+- HTTP: `POST /api/v1/scrape/jobs/{job_id}/reject`
+- operationId: `reject_scrape_job_scrape_jobs__job_id__reject_post` (also callable as `g8.api.call("reject_scrape_job_scrape_jobs__job_id__reject_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `enrichment:write`
+
+Discard a scrape result. What it found is not kept.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.job_id` | `string` | yes | Scrape job id. |
+
+**Returns** `ApiResponse_SettingsPayload_`: the envelope `{ data: SettingsPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.scraping.rejectScrapeJob({ path: { job_id: "id" } });
+```
+
+---
+
+<a id="op-startfullsitecrawl"></a>
+
+### `g8.api.scraping.startFullSiteCrawl(input)`
+
+**Start Full Site Crawl**
+
+- HTTP: `POST /api/v1/settings/scrape-config/crawl`
+- operationId: `start_full_site_crawl_settings_scrape_config_crawl_post` (also callable as `g8.api.call("start_full_site_crawl_settings_scrape_config_crawl_post", input)`)
+- Tier: `external`: reaches real people (sends email/SMS, places a call, launches a send); the SDK never blindly retries it; confirm with a human first
+- API-key scope: `enrichment:run`
+
+Crawl a whole site. RUNS IN THE BACKGROUND and can take a long time.
+
+Returns a job id immediately; poll
+`GET /settings/scrape-config/crawl/status/{job_id}` for progress. A full
+crawl fetches every reachable page, so point it at a site you own.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `StartCrawlRequest` | yes | Request body; fields below. |
+
+Body fields (`StartCrawlRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.max_pages` | `integer \| null` | no | min 10, max 5000 |
+| `body.source_url` | `string \| null` | no | Where to start. Omit to use the org's configured site. |
+
+**Returns** `ApiResponse_SettingsPayload_`: the envelope `{ data: SettingsPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+// external: reaches real people (sends email/SMS, places a call, launches a send); the SDK never blindly retries it; confirm with a human first.
+const result = await g8.api.scraping.startFullSiteCrawl({ body: {} });
+```
+
+---
+
+<a id="op-submitscraperequest"></a>
+
+### `g8.api.scraping.submitScrapeRequest(input)`
+
+**Submit Scrape Request**
+
+- HTTP: `POST /api/v1/scrape/requests`
+- operationId: `submit_scrape_request_scrape_requests_post` (also callable as `g8.api.call("submit_scrape_request_scrape_requests_post", input)`)
+- Tier: `billable`: spends credits; the SDK never blindly retries it; confirm cost before bulk use
+- API-key scope: `enrichment:run`
+
+Ask for a scrape. Returns a job to poll.
+
+Scraping fetches pages from a third party and can cost credits depending on
+the adapter - check `GET /scrape/adapters` before running this in a loop.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `SubmitScrapeRequest` | yes | Request body; fields below. |
+
+Body fields (`SubmitScrapeRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.requirement` | `string` | yes | What to scrape, in plain English. min length 3, max length 2000 |
+| `body.adapter` | `string \| null` | no | Skip the planner and use this capability directly. |
+| `body.params` | `Record<string, unknown>` | no |  |
+| `body.preview` | `boolean` | no | Hold the run behind a 5-row preview. Leave it on for a first run. default `true` |
+| `body.rescrape` | `boolean` | no | Re-run rows that already have a result. default `false` |
+| `body.row_ids` | `Array<integer> \| null` | no | Limit the run to these rows. |
+| `body.seed_targets` | `Array<string> \| null` | no | Cold start: add these as rows in `source_column` before scraping. |
+| `body.source_column` | `string \| null` | no | Column holding the values to scrape from. |
+| `body.staging_table_id` | `string \| null` | no | Staging table to read from and write into. |
+
+**Returns** `ApiResponse_SettingsPayload_`: the envelope `{ data: SettingsPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+// billable: spends credits; the SDK never blindly retries it; confirm cost before bulk use.
+const result = await g8.api.scraping.submitScrapeRequest({ body: { requirement: "example" } });
+```
+
+---
+
+<a id="op-updatescrapeconfig"></a>
+
+### `g8.api.scraping.updateScrapeConfig(input)`
+
+**Update Scrape Config**
+
+- HTTP: `PATCH /api/v1/settings/scrape-config`
+- operationId: `update_scrape_config_settings_scrape_config_patch` (also callable as `g8.api.call("update_scrape_config_settings_scrape_config_patch", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `enrichment:write`
+
+Change the scraping configuration. Only what you send is written.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `ScrapeConfigUpdateRequest` | yes | Request body; fields below. |
+
+Body fields (`ScrapeConfigUpdateRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.exclude_paths` | `Array<string> \| null` | no | URL path patterns to skip while crawling. |
+| `body.include_blog_pages` | `boolean \| null` | no |  |
+| `body.max_pages` | `integer \| null` | no | Pages per crawl. The app's own bounds. min 10, max 5000 |
+
+**Returns** `ApiResponse_SettingsPayload_`: the envelope `{ data: SettingsPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.scraping.updateScrapeConfig({ body: {} });
+```

package/docs/api/sdrAnalytics.d.ts

@@ -0,0 +1,138 @@
+/* Generated by sdk/js/scripts/generate-agent-docs.ts from developer-contract/openapi.json. Regenerated on every build. */
+
+/**
+ * Types for `g8.api.sdrAnalytics` (SDR Analytics): 5 operations.
+ *
+ * For reading. In code, import from the package instead:
+ *   import type { ApiInput, ApiOutput, G8Contract } from "@graph8/sdk";
+ *   type In = ApiInput<"get_ai_agents_summary_analytics_sdr_ai_agents_summary_get">;
+ *
+ * Reference with examples: sdrAnalytics.md
+ */
+/* eslint-disable */
+
+/** `g8.api.sdrAnalytics.<member>` -> the operationId it calls. */
+export interface SdrAnalyticsMembers {
+  getAiAgentsSummary: "get_ai_agents_summary_analytics_sdr_ai_agents_summary_get";
+  getSdrDetail: "get_sdr_detail_analytics_sdr__sdr_email__get";
+  getSdrLeaderboard: "get_sdr_leaderboard_analytics_sdr_leaderboard_get";
+  getSdrSummary: "get_sdr_summary_analytics_sdr_summary_get";
+  getSdrTrends: "get_sdr_trends_analytics_sdr_trends_get";
+}
+
+/** Input and output of every `g8.api.sdrAnalytics` operation, keyed by operationId. */
+export interface SdrAnalyticsOperations {
+  /**
+   * GET /analytics/sdr/ai-agents/summary
+   * Get Ai Agents Summary
+   * tier: read · scope: analytics:read
+   */
+  get_ai_agents_summary_analytics_sdr_ai_agents_summary_get: {
+    input: {
+    query?: {
+      /** Number of days to analyze */
+      days?: number;
+    };
+    headers?: {
+      "X-Org-Id"?: string | null;
+    };
+  };
+    output: SDRAnalyticsResponse;
+  };
+  /**
+   * GET /analytics/sdr/{sdr_email}
+   * Get Sdr Detail
+   * tier: read · scope: analytics:read
+   */
+  get_sdr_detail_analytics_sdr__sdr_email__get: {
+    input: {
+    path: {
+      /** SDR email address */
+      sdr_email: string;
+    };
+    query?: {
+      /** Number of days to analyze */
+      days?: number;
+    };
+    headers?: {
+      "X-Org-Id"?: string | null;
+    };
+  };
+    output: SDRAnalyticsResponse;
+  };
+  /**
+   * GET /analytics/sdr/leaderboard
+   * Get Sdr Leaderboard
+   * tier: read · scope: analytics:read
+   */
+  get_sdr_leaderboard_analytics_sdr_leaderboard_get: {
+    input: {
+    query?: {
+      /** Number of days to analyze */
+      days?: number;
+      /** Maximum SDRs to return */
+      limit?: number;
+    };
+    headers?: {
+      "X-Org-Id"?: string | null;
+    };
+  };
+    output: SDRAnalyticsResponse;
+  };
+  /**
+   * GET /analytics/sdr/summary
+   * Get Sdr Summary
+   * tier: read · scope: analytics:read
+   */
+  get_sdr_summary_analytics_sdr_summary_get: {
+    input: {
+    query?: {
+      /** Number of days to analyze */
+      days?: number;
+    };
+    headers?: {
+      "X-Org-Id"?: string | null;
+    };
+  };
+    output: SDRAnalyticsResponse;
+  };
+  /**
+   * GET /analytics/sdr/trends
+   * Get Sdr Trends
+   * tier: read · scope: analytics:read
+   */
+  get_sdr_trends_analytics_sdr_trends_get: {
+    input: {
+    query?: {
+      /** Number of days to analyze */
+      days?: number;
+      /** Aggregation period: 'day' or 'week' */
+      granularity?: "day" | "week";
+    };
+    headers?: {
+      "X-Org-Id"?: string | null;
+    };
+  };
+    output: SDRAnalyticsResponse;
+  };
+}
+
+// 2 schemas referenced above (the same as G8Contract.<Name>).
+
+/** Metadata for SDR analytics responses. */
+export interface SDRAnalyticsMeta {
+  cache_ttl?: number;
+  cached: boolean;
+  days: number;
+  org_id: string;
+  query_time_ms?: number | null;
+  stale?: boolean;
+  timestamp: string;
+}
+
+/** Standard SDR analytics response wrapper. */
+export interface SDRAnalyticsResponse {
+  data: Record<string, unknown> | Array<unknown>;
+  meta: SDRAnalyticsMeta;
+  success?: boolean;
+}