@graph8/sdk 0.251.0 → 0.262.0

package/docs/api/companyIntelligence.md

@@ -0,0 +1,488 @@
+<!-- Generated by sdk/js/scripts/generate-agent-docs.ts from developer-contract/openapi.json. Regenerated on every build. -->
+
+# `g8.api.companyIntelligence`: Company Intelligence
+
+14 operations (10 read, 1 destructive, 3 billable).
+
+No hand-written client covers this area. Call it through `g8.api.companyIntelligence.*` 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: [companyIntelligence.d.ts](companyIntelligence.d.ts).
+
+## Operations
+
+| Call | HTTP | Tier | Scope | Summary |
+|---|---|---|---|---|
+| [`analyzeWebsite`](#op-analyzewebsite) | `POST /api/v1/intelligence/analyze` | billable | `knowledge:run` | Analyze Website |
+| [`generateGlobalContextDocument`](#op-generateglobalcontextdocument) | `POST /api/v1/global-context/generate/{doc_type}` | billable | `knowledge:run` | Generate Global Context Document |
+| [`getAllIntelligenceData`](#op-getallintelligencedata) | `GET /api/v1/intelligence/all/{website_url}` | read | `knowledge:read` | Get All Intelligence Data |
+| [`getGlobalContextTree`](#op-getglobalcontexttree) | `GET /api/v1/global-context/tree` | read | `knowledge:read` | Get Global Context Tree |
+| [`getGlobalContextTreeFlat`](#op-getglobalcontexttreeflat) | `GET /api/v1/global-context/tree/flat` | read | `knowledge:read` | Get Global Context Tree Flat |
+| [`getIntelligenceData`](#op-getintelligencedata) | `GET /api/v1/intelligence/data/{data_type}` | read | `knowledge:read` | Get Intelligence Data |
+| [`getIntelligenceOrgDomain`](#op-getintelligenceorgdomain) | `GET /api/v1/intelligence/org-domain` | read | `knowledge:read` | Get Intelligence Org Domain |
+| [`getIntelligencePrimaryWebsite`](#op-getintelligenceprimarywebsite) | `GET /api/v1/intelligence/primary-website` | read | `knowledge:read` | Get Intelligence Primary Website |
+| [`getIntelligenceStatus`](#op-getintelligencestatus) | `GET /api/v1/intelligence/status/{task_id}` | read | `knowledge:read` | Get Intelligence Status |
+| [`getLatestIntelligenceTask`](#op-getlatestintelligencetask) | `GET /api/v1/intelligence/latest-task` | read | `knowledge:read` | Get Latest Intelligence Task |
+| [`getResearchReportThinking`](#op-getresearchreportthinking) | `GET /api/v1/research-reports/{report_id}/thinking` | read | `knowledge:read` | Get Research Report Thinking |
+| [`listIntelligenceDocuments`](#op-listintelligencedocuments) | `GET /api/v1/intelligence/documents` | read | `knowledge:read` | List Intelligence Documents |
+| [`resetIntelligence`](#op-resetintelligence) | `DELETE /api/v1/intelligence` | destructive | `knowledge:delete` | Reset Intelligence |
+| [`retryIntelligenceSource`](#op-retryintelligencesource) | `POST /api/v1/intelligence/retry` | billable | `knowledge:run` | Retry Intelligence Source |
+
+---
+
+<a id="op-analyzewebsite"></a>
+
+### `g8.api.companyIntelligence.analyzeWebsite(input)`
+
+**Analyze Website**
+
+- HTTP: `POST /api/v1/intelligence/analyze`
+- operationId: `analyze_website_intelligence_analyze_post` (also callable as `g8.api.call("analyze_website_intelligence_analyze_post", input)`)
+- Tier: `billable`: spends credits; the SDK never blindly retries it; confirm cost before bulk use
+- API-key scope: `knowledge:run`
+
+Start researching a website (scrapes and runs models; billable). Poll the returned task.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `IntelligenceAnalyzeRequest` | yes | Request body; fields below. |
+
+Body fields (`IntelligenceAnalyzeRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.website_url` | `string` | yes | The company website to research. |
+| `body.force` | `boolean` | no | Re-run even when a recent analysis exists. default `false` |
+
+**Returns** `ApiResponse_IntelligencePayload_`: the envelope `{ data: IntelligencePayload, ... }`. `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.companyIntelligence.analyzeWebsite({ body: { website_url: "https://example.com" } });
+```
+
+---
+
+<a id="op-generateglobalcontextdocument"></a>
+
+### `g8.api.companyIntelligence.generateGlobalContextDocument(input)`
+
+**Generate Global Context Document**
+
+- HTTP: `POST /api/v1/global-context/generate/{doc_type}`
+- operationId: `generate_global_context_document_global_context_generate__doc_type__post` (also callable as `g8.api.call("generate_global_context_document_global_context_generate__doc_type__post", input)`)
+- Tier: `billable`: spends credits; the SDK never blindly retries it; confirm cost before bulk use
+- API-key scope: `knowledge:run`
+
+Generate ONE global-context document from the intelligence data (runs a model; billable).
+
+The document appears under `GET /global-context/documents` when done.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.doc_type` | `string` | yes | The document type to (re)generate. |
+| `body` | `GlobalContextGenerateRequest` | yes | Request body; fields below. |
+
+Body fields (`GlobalContextGenerateRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.doc_type` | `string` | yes | Must match the `doc_type` in the path. |
+| `body.website_url` | `string` | yes |  |
+
+**Returns** `ApiResponse_IntelligencePayload_`: the envelope `{ data: IntelligencePayload, ... }`. `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.companyIntelligence.generateGlobalContextDocument({
+  path: { doc_type: "example" },
+  body: { doc_type: "example", website_url: "https://example.com" },
+});
+```
+
+---
+
+<a id="op-getallintelligencedata"></a>
+
+### `g8.api.companyIntelligence.getAllIntelligenceData(input)`
+
+**Get All Intelligence Data**
+
+- HTTP: `GET /api/v1/intelligence/all/{website_url}`
+- operationId: `get_all_intelligence_data_intelligence_all__website_url__get` (also callable as `g8.api.call("get_all_intelligence_data_intelligence_all__website_url__get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `knowledge:read`
+
+Everything collected for one website.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.website_url` | `string` | yes | The researched website (host, no scheme). |
+
+**Returns** `ApiResponse_IntelligencePayload_`: the envelope `{ data: IntelligencePayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.companyIntelligence.getAllIntelligenceData({ path: { website_url: "https://example.com" } });
+```
+
+---
+
+<a id="op-getglobalcontexttree"></a>
+
+### `g8.api.companyIntelligence.getGlobalContextTree(input?)`
+
+**Get Global Context Tree**
+
+- HTTP: `GET /api/v1/global-context/tree`
+- operationId: `get_global_context_tree_global_context_tree_get` (also callable as `g8.api.call("get_global_context_tree_global_context_tree_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `knowledge:read`
+
+The global-context documents as a folder tree, with completion counts.
+
+**Input**: none.
+
+**Returns** `ApiResponse_IntelligencePayload_`: the envelope `{ data: IntelligencePayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.companyIntelligence.getGlobalContextTree();
+```
+
+---
+
+<a id="op-getglobalcontexttreeflat"></a>
+
+### `g8.api.companyIntelligence.getGlobalContextTreeFlat(input?)`
+
+**Get Global Context Tree Flat**
+
+- HTTP: `GET /api/v1/global-context/tree/flat`
+- operationId: `get_global_context_tree_flat_global_context_tree_flat_get` (also callable as `g8.api.call("get_global_context_tree_flat_global_context_tree_flat_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `knowledge:read`
+
+The global-context documents as a flat list.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `query.folder_path` | `string \| null` | no | Only documents under this folder. |
+
+**Returns** `ApiResponse_IntelligencePayload_`: the envelope `{ data: IntelligencePayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.companyIntelligence.getGlobalContextTreeFlat();
+```
+
+---
+
+<a id="op-getintelligencedata"></a>
+
+### `g8.api.companyIntelligence.getIntelligenceData(input)`
+
+**Get Intelligence Data**
+
+- HTTP: `GET /api/v1/intelligence/data/{data_type}`
+- operationId: `get_intelligence_data_intelligence_data__data_type__get` (also callable as `g8.api.call("get_intelligence_data_intelligence_data__data_type__get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `knowledge:read`
+
+What one data source collected.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.data_type` | `string` | yes | Which data source, e.g. `company_info`. |
+| `query.website_url` | `string \| null` | no |  |
+
+**Returns** `ApiResponse_IntelligencePayload_`: the envelope `{ data: IntelligencePayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.companyIntelligence.getIntelligenceData({ path: { data_type: "example" } });
+```
+
+---
+
+<a id="op-getintelligenceorgdomain"></a>
+
+### `g8.api.companyIntelligence.getIntelligenceOrgDomain(input?)`
+
+**Get Intelligence Org Domain**
+
+- HTTP: `GET /api/v1/intelligence/org-domain`
+- operationId: `get_intelligence_org_domain_intelligence_org_domain_get` (also callable as `g8.api.call("get_intelligence_org_domain_intelligence_org_domain_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `knowledge:read`
+
+The company domain recorded on the organisation.
+
+**Input**: none.
+
+**Returns** `ApiResponse_IntelligencePayload_`: the envelope `{ data: IntelligencePayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.companyIntelligence.getIntelligenceOrgDomain();
+```
+
+---
+
+<a id="op-getintelligenceprimarywebsite"></a>
+
+### `g8.api.companyIntelligence.getIntelligencePrimaryWebsite(input?)`
+
+**Get Intelligence Primary Website**
+
+- HTTP: `GET /api/v1/intelligence/primary-website`
+- operationId: `get_intelligence_primary_website_intelligence_primary_website_get` (also callable as `g8.api.call("get_intelligence_primary_website_intelligence_primary_website_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `knowledge:read`
+
+The website the org's intelligence was built from.
+
+**Input**: none.
+
+**Returns** `ApiResponse_IntelligencePayload_`: the envelope `{ data: IntelligencePayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.companyIntelligence.getIntelligencePrimaryWebsite();
+```
+
+---
+
+<a id="op-getintelligencestatus"></a>
+
+### `g8.api.companyIntelligence.getIntelligenceStatus(input)`
+
+**Get Intelligence Status**
+
+- HTTP: `GET /api/v1/intelligence/status/{task_id}`
+- operationId: `get_intelligence_status_intelligence_status__task_id__get` (also callable as `g8.api.call("get_intelligence_status_intelligence_status__task_id__get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `knowledge:read`
+
+Progress of an intelligence run, step by step.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.task_id` | `string` | yes | Task id returned by `POST /intelligence/analyze`. |
+
+**Returns** `ApiResponse_IntelligencePayload_`: the envelope `{ data: IntelligencePayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.companyIntelligence.getIntelligenceStatus({ path: { task_id: "id" } });
+```
+
+---
+
+<a id="op-getlatestintelligencetask"></a>
+
+### `g8.api.companyIntelligence.getLatestIntelligenceTask(input?)`
+
+**Get Latest Intelligence Task**
+
+- HTTP: `GET /api/v1/intelligence/latest-task`
+- operationId: `get_latest_intelligence_task_intelligence_latest_task_get` (also callable as `g8.api.call("get_latest_intelligence_task_intelligence_latest_task_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `knowledge:read`
+
+The org's most recent intelligence run.
+
+**Input**: none.
+
+**Returns** `ApiResponse_IntelligencePayload_`: the envelope `{ data: IntelligencePayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.companyIntelligence.getLatestIntelligenceTask();
+```
+
+---
+
+<a id="op-getresearchreportthinking"></a>
+
+### `g8.api.companyIntelligence.getResearchReportThinking(input)`
+
+**Get Research Report Thinking**
+
+- HTTP: `GET /api/v1/research-reports/{report_id}/thinking`
+- operationId: `get_research_report_thinking_research_reports__report_id__thinking_get` (also callable as `g8.api.call("get_research_report_thinking_research_reports__report_id__thinking_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `knowledge:read`
+
+The recorded reasoning events of a research report, in order.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.report_id` | `string` | yes | Research report id. |
+
+**Returns** `ApiResponse_IntelligencePayload_`: the envelope `{ data: IntelligencePayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.companyIntelligence.getResearchReportThinking({ path: { report_id: "id" } });
+```
+
+---
+
+<a id="op-listintelligencedocuments"></a>
+
+### `g8.api.companyIntelligence.listIntelligenceDocuments(input?)`
+
+**List Intelligence Documents**
+
+- HTTP: `GET /api/v1/intelligence/documents`
+- operationId: `list_intelligence_documents_intelligence_documents_get` (also callable as `g8.api.call("list_intelligence_documents_intelligence_documents_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `knowledge:read`
+
+Every intelligence document for the org.
+
+**Input**: none.
+
+**Returns** `ApiResponse_IntelligenceListPayload_`: the envelope `{ data: IntelligenceListPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`IntelligenceListPayload` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `items` | `Array<unknown>` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.companyIntelligence.listIntelligenceDocuments();
+```
+
+---
+
+<a id="op-resetintelligence"></a>
+
+### `g8.api.companyIntelligence.resetIntelligence(input?)`
+
+**Reset Intelligence**
+
+- HTTP: `DELETE /api/v1/intelligence`
+- operationId: `reset_intelligence_intelligence_delete` (also callable as `g8.api.call("reset_intelligence_intelligence_delete", input)`)
+- Tier: `destructive`: deletes or archives data; confirm with a human before calling
+- API-key scope: `knowledge:delete`
+
+Delete every intelligence record and run for the org and clear its primary website.
+
+Global-context documents are NOT touched.
+
+**Input**: none.
+
+**Returns** `ApiResponse_IntelligencePayload_`: the envelope `{ data: IntelligencePayload, ... }`. `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.companyIntelligence.resetIntelligence();
+```
+
+---
+
+<a id="op-retryintelligencesource"></a>
+
+### `g8.api.companyIntelligence.retryIntelligenceSource(input)`
+
+**Retry Intelligence Source**
+
+- HTTP: `POST /api/v1/intelligence/retry`
+- operationId: `retry_intelligence_source_intelligence_retry_post` (also callable as `g8.api.call("retry_intelligence_source_intelligence_retry_post", input)`)
+- Tier: `billable`: spends credits; the SDK never blindly retries it; confirm cost before bulk use
+- API-key scope: `knowledge:run`
+
+Re-collect one data source (scrapes and runs models; billable).
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `IntelligenceSourceRetryRequest` | yes | Request body; fields below. |
+
+Body fields (`IntelligenceSourceRetryRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.data_type` | `string` | yes | The one data source to re-collect. |
+| `body.website_url` | `string` | yes |  |
+
+**Returns** `ApiResponse_IntelligencePayload_`: the envelope `{ data: IntelligencePayload, ... }`. `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.companyIntelligence.retryIntelligenceSource({ body: { data_type: "example", website_url: "https://example.com" } });
+```