@graph8/sdk 0.251.0 → 0.260.0

package/docs/api/research.md

@@ -0,0 +1,534 @@
+<!-- Generated by sdk/js/scripts/generate-agent-docs.ts from developer-contract/openapi.json. Regenerated on every build. -->
+
+# `g8.api.research`: Research
+
+13 operations (3 read, 4 write, 2 destructive, 4 billable).
+
+No hand-written client covers this area. Call it through `g8.api.research.*` 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: [research.d.ts](research.d.ts).
+
+## Operations
+
+| Call | HTTP | Tier | Scope | Summary |
+|---|---|---|---|---|
+| [`approveResearchReport`](#op-approveresearchreport) | `POST /api/v1/research-reports/{report_id}/approve` | write | `campaigns:write` | Approve Research Report |
+| [`deleteResearchReport`](#op-deleteresearchreport) | `DELETE /api/v1/research-reports/{report_id}` | destructive | `campaigns:delete` | Delete Research Report |
+| [`generateAllResearchReports`](#op-generateallresearchreports) | `POST /api/v1/research-reports/generate-all` | billable | `campaigns:run` | Generate All Research Reports |
+| [`generateResearchReport`](#op-generateresearchreport) | `POST /api/v1/research-reports/generate` | billable | `campaigns:run` | Generate Research Report |
+| [`getResearchReport`](#op-getresearchreport) | `GET /api/v1/research-reports/{report_id}` | read | `campaigns:read` | Get Research Report |
+| [`getResearchReportByNumber`](#op-getresearchreportbynumber) | `GET /api/v1/research-reports/by-number/{report_number}` | read | `campaigns:read` | Get Research Report By Number |
+| [`getResearchWorkflowStatus`](#op-getresearchworkflowstatus) | `GET /api/v1/research-reports/workflow` | read | `campaigns:read` | Get Research Workflow Status |
+| [`resetResearchWorkflow`](#op-resetresearchworkflow) | `POST /api/v1/research-reports/workflow/reset` | destructive | `campaigns:delete` | Reset Research Workflow |
+| [`resumeResearchWorkflow`](#op-resumeresearchworkflow) | `POST /api/v1/research-reports/workflow/resume` | billable | `campaigns:run` | Resume Research Workflow |
+| [`retryResearchReport`](#op-retryresearchreport) | `POST /api/v1/research-reports/retry` | billable | `campaigns:run` | Retry Research Report |
+| [`scaffoldResearchReports`](#op-scaffoldresearchreports) | `POST /api/v1/research-reports/scaffold` | write | `campaigns:write` | Scaffold Research Reports |
+| [`stopAllResearch`](#op-stopallresearch) | `POST /api/v1/research-reports/stop-all` | write | `campaigns:write` | Stop All Research |
+| [`unapproveResearchReport`](#op-unapproveresearchreport) | `POST /api/v1/research-reports/{report_id}/unapprove` | write | `campaigns:write` | Unapprove Research Report |
+
+---
+
+<a id="op-approveresearchreport"></a>
+
+### `g8.api.research.approveResearchReport(input)`
+
+**Approve Research Report**
+
+- HTTP: `POST /api/v1/research-reports/{report_id}/approve`
+- operationId: `approve_research_report_research_reports__report_id__approve_post` (also callable as `g8.api.call("approve_research_report_research_reports__report_id__approve_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `campaigns:write`
+
+Approve a report and INDEX IT INTO THE KNOWLEDGE BASE. FREE.
+
+Approving is what makes the report reachable from retrieval - every
+campaign, sequence and copilot answer grounded on knowledge can quote it
+afterwards. That is a wider blast radius than "set a status", which is why
+it has its own route rather than being a field on the PATCH.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.report_id` | `string` | yes | Research report id. |
+
+**Returns** `ApiResponse_StudioContentPayload_`: the envelope `{ data: StudioContentPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.research.approveResearchReport({ path: { report_id: "id" } });
+```
+
+---
+
+<a id="op-deleteresearchreport"></a>
+
+### `g8.api.research.deleteResearchReport(input)`
+
+**Delete Research Report**
+
+- HTTP: `DELETE /api/v1/research-reports/{report_id}`
+- operationId: `delete_research_report_research_reports__report_id__delete` (also callable as `g8.api.call("delete_research_report_research_reports__report_id__delete", input)`)
+- Tier: `destructive`: deletes or archives data; confirm with a human before calling
+- API-key scope: `campaigns:delete`
+
+Delete a report. Regenerating it costs a full run, so this is expensive
+to undo even though the deletion itself is free.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.report_id` | `string` | yes | Research report id. |
+
+**Returns** `ApiResponse_StudioContentPayload_`: the envelope `{ data: StudioContentPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+// destructive: deletes or archives data; confirm with a human before calling.
+const result = await g8.api.research.deleteResearchReport({ path: { report_id: "id" } });
+```
+
+---
+
+<a id="op-generateallresearchreports"></a>
+
+### `g8.api.research.generateAllResearchReports(input)`
+
+**Generate All Research Reports**
+
+- HTTP: `POST /api/v1/research-reports/generate-all`
+- operationId: `generate_all_research_reports_research_reports_generate_all_post` (also callable as `g8.api.call("generate_all_research_reports_research_reports_generate_all_post", input)`)
+- Tier: `billable`: spends credits; the SDK never blindly retries it; confirm cost before bulk use
+- API-key scope: `campaigns:run`
+
+Generate all SIX reports for a website. SPENDS CREDIT, six times over.
+
+The single largest spend this API can trigger. `/stop-all` cancels a run
+in flight, but whatever has already been generated has already been paid
+for.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `GenerateAllReportsRequest` | yes | Request body; fields below. |
+
+Body fields (`GenerateAllReportsRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.website_url` | `string` | yes |  |
+
+**Returns** `ApiResponse_StudioContentPayload_`: the envelope `{ data: StudioContentPayload, ... }`. `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.research.generateAllResearchReports({ body: { website_url: "https://example.com" } });
+```
+
+---
+
+<a id="op-generateresearchreport"></a>
+
+### `g8.api.research.generateResearchReport(input)`
+
+**Generate Research Report**
+
+- HTTP: `POST /api/v1/research-reports/generate`
+- operationId: `generate_research_report_research_reports_generate_post` (also callable as `g8.api.call("generate_research_report_research_reports_generate_post", input)`)
+- Tier: `billable`: spends credits; the SDK never blindly retries it; confirm cost before bulk use
+- API-key scope: `campaigns:run`
+
+Generate ONE of the six reports. SPENDS CREDIT - heavily.
+
+A long multi-pass run against the market, the customer's own site and its
+competitors. This is the most expensive single operation in Studio.
+
+Asynchronous: it returns once the run is dispatched. Poll
+`GET /research-reports/workflow?website_url=...` for progress.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `GenerateReportRequest` | yes | Request body; fields below. |
+
+Body fields (`GenerateReportRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.report_number` | `integer` | yes |  |
+| `body.website_url` | `string` | yes |  |
+| `body.report_type` | `string \| null` | no |  |
+
+**Returns** `ApiResponse_StudioContentPayload_`: the envelope `{ data: StudioContentPayload, ... }`. `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.research.generateResearchReport({ body: { report_number: 1, website_url: "https://example.com" } });
+```
+
+---
+
+<a id="op-getresearchreport"></a>
+
+### `g8.api.research.getResearchReport(input)`
+
+**Get Research Report**
+
+- HTTP: `GET /api/v1/research-reports/{report_id}`
+- operationId: `get_research_report_research_reports__report_id__get` (also callable as `g8.api.call("get_research_report_research_reports__report_id__get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `campaigns:read`
+
+One research report with its full markdown. FREE.
+
+Declared AFTER every literal on this router (`/workflow`, `/by-number/...`)
+so it cannot swallow them.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.report_id` | `string` | yes | Research report id. |
+
+**Returns** `ApiResponse_StudioContentPayload_`: the envelope `{ data: StudioContentPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.research.getResearchReport({ path: { report_id: "id" } });
+```
+
+---
+
+<a id="op-getresearchreportbynumber"></a>
+
+### `g8.api.research.getResearchReportByNumber(input)`
+
+**Get Research Report By Number**
+
+- HTTP: `GET /api/v1/research-reports/by-number/{report_number}`
+- operationId: `get_research_report_by_number_research_reports_by_number__report_number__get` (also callable as `g8.api.call("get_research_report_by_number_research_reports_by_number__report_number__get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `campaigns:read`
+
+One report by its POSITION in the six, for a website. FREE.
+
+`/by-number/` rather than the app's singular `/report/{n}`: a path that
+differs from `/research-reports/{id}` only by a letter is the trap this
+programme has already paid for once.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.report_number` | `integer` | yes | Report number, 1-6. |
+| `query.website_url` | `string` | yes | The website the workflow is scoped to. |
+
+**Returns** `ApiResponse_StudioContentPayload_`: the envelope `{ data: StudioContentPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.research.getResearchReportByNumber({
+  path: { report_number: 1 },
+  query: { website_url: "https://example.com" },
+});
+```
+
+---
+
+<a id="op-getresearchworkflowstatus"></a>
+
+### `g8.api.research.getResearchWorkflowStatus(input)`
+
+**Get Research Workflow Status**
+
+- HTTP: `GET /api/v1/research-reports/workflow`
+- operationId: `get_research_workflow_status_research_reports_workflow_get` (also callable as `g8.api.call("get_research_workflow_status_research_reports_workflow_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `campaigns:read`
+
+How the six-report workflow is going for one website. FREE.
+
+The poll target for `/generate` and `/generate-all`, and the read to make
+before `/workflow/resume` - it says which reports are actually incomplete,
+and therefore what resuming would cost.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `query.website_url` | `string` | yes | The website the workflow is scoped to. |
+
+**Returns** `ApiResponse_StudioContentPayload_`: the envelope `{ data: StudioContentPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.research.getResearchWorkflowStatus({ query: { website_url: "https://example.com" } });
+```
+
+---
+
+<a id="op-resetresearchworkflow"></a>
+
+### `g8.api.research.resetResearchWorkflow(input)`
+
+**Reset Research Workflow**
+
+- HTTP: `POST /api/v1/research-reports/workflow/reset`
+- operationId: `reset_research_workflow_research_reports_workflow_reset_post` (also callable as `g8.api.call("reset_research_workflow_research_reports_workflow_reset_post", input)`)
+- Tier: `destructive`: deletes or archives data; confirm with a human before calling
+- API-key scope: `campaigns:delete`
+
+Reset the workflow to start fresh. NOT REVERSIBLE.
+
+It discards the workflow's progress. Nothing is spent by resetting - but
+everything that was generated has to be generated again, so the real cost
+of this call is the run that follows it.
+
+Spends nothing.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `GenerateAllReportsRequest` | yes | Request body; fields below. |
+
+Body fields (`GenerateAllReportsRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.website_url` | `string` | yes |  |
+
+**Returns** `ApiResponse_StudioContentPayload_`: the envelope `{ data: StudioContentPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+// destructive: deletes or archives data; confirm with a human before calling.
+const result = await g8.api.research.resetResearchWorkflow({ body: { website_url: "https://example.com" } });
+```
+
+---
+
+<a id="op-resumeresearchworkflow"></a>
+
+### `g8.api.research.resumeResearchWorkflow(input?)`
+
+**Resume Research Workflow**
+
+- HTTP: `POST /api/v1/research-reports/workflow/resume`
+- operationId: `resume_research_workflow_research_reports_workflow_resume_post` (also callable as `g8.api.call("resume_research_workflow_research_reports_workflow_resume_post", input)`)
+- Tier: `billable`: spends credits; the SDK never blindly retries it; confirm cost before bulk use
+- API-key scope: `campaigns:run`
+
+Restart a stuck workflow. SPENDS CREDIT - it generates what is missing.
+
+"Resume" understates it: every incomplete report is generated, which can
+be all six. Read `GET /research-reports/workflow` first to see how many
+that is. Its path carries no `/generate`, so the tier heuristic called
+this an ordinary write; it is corrected with an explicit rule.
+
+**Input**: none.
+
+**Returns** `ApiResponse_StudioContentPayload_`: the envelope `{ data: StudioContentPayload, ... }`. `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.research.resumeResearchWorkflow();
+```
+
+---
+
+<a id="op-retryresearchreport"></a>
+
+### `g8.api.research.retryResearchReport(input)`
+
+**Retry Research Report**
+
+- HTTP: `POST /api/v1/research-reports/retry`
+- operationId: `retry_research_report_research_reports_retry_post` (also callable as `g8.api.call("retry_research_report_research_reports_retry_post", input)`)
+- Tier: `billable`: spends credits; the SDK never blindly retries it; confirm cost before bulk use
+- API-key scope: `campaigns:run`
+
+Re-run ONE failed report. SPENDS CREDIT - it is a full generation of that report.
+
+The existing report row is reused, so a worker still writing to it does not
+lose its target. Poll `GET /research-reports/workflow?website_url=...`.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `RetryResearchReportRequest` | yes | Request body; fields below. |
+
+Body fields (`RetryResearchReportRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.report_type` | `"review_sentiment" \| "competitive_teardown" \| "voice_of_customer" \| "gtm_channel" \| "analyst_media" \| "buyer_psychology"` | yes |  |
+| `body.website_url` | `string` | yes |  |
+
+**Returns** `ApiResponse_StudioContentPayload_`: the envelope `{ data: StudioContentPayload, ... }`. `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.research.retryResearchReport({
+  body: {
+    report_type: "review_sentiment",
+    website_url: "https://example.com",
+  },
+});
+```
+
+---
+
+<a id="op-scaffoldresearchreports"></a>
+
+### `g8.api.research.scaffoldResearchReports(input?)`
+
+**Scaffold Research Reports**
+
+- HTTP: `POST /api/v1/research-reports/scaffold`
+- operationId: `scaffold_research_reports_research_reports_scaffold_post` (also callable as `g8.api.call("scaffold_research_reports_research_reports_scaffold_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `campaigns:write`
+
+Create the six report PLACEHOLDERS. FREE - nothing is generated.
+
+Empty rows you can then fill by editing, or by generating into them one at
+a time. The cheap way to see the six report types before committing to a
+run.
+
+**Input**: none.
+
+**Returns** `ApiResponse_StudioContentListPayload_`: the envelope `{ data: StudioContentListPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`StudioContentListPayload` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `items` | `Array<unknown>` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.research.scaffoldResearchReports();
+```
+
+---
+
+<a id="op-stopallresearch"></a>
+
+### `g8.api.research.stopAllResearch(input)`
+
+**Stop All Research**
+
+- HTTP: `POST /api/v1/research-reports/stop-all`
+- operationId: `stop_all_research_research_reports_stop_all_post` (also callable as `g8.api.call("stop_all_research_research_reports_stop_all_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `campaigns:write`
+
+Stop every running report for a website. FREE.
+
+It cancels what has not started. Anything already generated stays, and
+anything already generated has already been charged for.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `GenerateAllReportsRequest` | yes | Request body; fields below. |
+
+Body fields (`GenerateAllReportsRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.website_url` | `string` | yes |  |
+
+**Returns** `ApiResponse_StudioContentPayload_`: the envelope `{ data: StudioContentPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.research.stopAllResearch({ body: { website_url: "https://example.com" } });
+```
+
+---
+
+<a id="op-unapproveresearchreport"></a>
+
+### `g8.api.research.unapproveResearchReport(input)`
+
+**Unapprove Research Report**
+
+- HTTP: `POST /api/v1/research-reports/{report_id}/unapprove`
+- operationId: `unapprove_research_report_research_reports__report_id__unapprove_post` (also callable as `g8.api.call("unapprove_research_report_research_reports__report_id__unapprove_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `campaigns:write`
+
+Remove a report from the knowledge index. FREE. The report survives.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.report_id` | `string` | yes | Research report id. |
+
+**Returns** `ApiResponse_StudioContentPayload_`: the envelope `{ data: StudioContentPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.research.unapproveResearchReport({ path: { report_id: "id" } });
+```