@graph8/sdk 0.251.0 → 0.260.0

package/docs/api/radarReports.d.ts

@@ -0,0 +1,208 @@
+/* Generated by sdk/js/scripts/generate-agent-docs.ts from developer-contract/openapi.json. Regenerated on every build. */
+
+/**
+ * Types for `g8.api.radarReports` (Radar Reports): 8 operations.
+ *
+ * For reading. In code, import from the package instead:
+ *   import type { ApiInput, ApiOutput, G8Contract } from "@graph8/sdk";
+ *   type In = ApiInput<"act_on_radar_case_file_radar_case_files__case_id__action_post">;
+ *
+ * Reference with examples: radarReports.md
+ */
+/* eslint-disable */
+
+/** `g8.api.radarReports.<member>` -> the operationId it calls. */
+export interface RadarReportsMembers {
+  actOnRadarCaseFile: "act_on_radar_case_file_radar_case_files__case_id__action_post";
+  createRadarReport: "create_radar_report_radar_reports_post";
+  getRadarAeoDossier: "get_radar_aeo_dossier_radar_aeo_dossier__probe_id__get";
+  getRadarAeoSources: "get_radar_aeo_sources_radar_aeo_sources_get";
+  getRadarReportHtml: "get_radar_report_html_radar_reports__report_id__html_get";
+  getRadarReportPdf: "get_radar_report_pdf_radar_reports__report_id__pdf_get";
+  listRadarCaseFiles: "list_radar_case_files_radar_case_files_get";
+  listRadarReports: "list_radar_reports_radar_reports_get";
+}
+
+/** Input and output of every `g8.api.radarReports` operation, keyed by operationId. */
+export interface RadarReportsOperations {
+  /**
+   * POST /radar/case-files/{case_id}/action
+   * Act On Radar Case File
+   * tier: write · scope: intent:write
+   */
+  act_on_radar_case_file_radar_case_files__case_id__action_post: {
+    input: {
+    path: {
+      /** Case file id. */
+      case_id: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: RadarCaseFileActionRequest;
+  };
+    output: ApiResponse_RadarReportPayload_;
+  };
+  /**
+   * POST /radar/reports
+   * Create Radar Report
+   * tier: billable · scope: intent:run
+   */
+  create_radar_report_radar_reports_post: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: RadarReportCreateRequest;
+  };
+    output: ApiResponse_RadarReportPayload_;
+  };
+  /**
+   * GET /radar/aeo/dossier/{probe_id}
+   * Get Radar Aeo Dossier
+   * tier: read · scope: intent:read
+   */
+  get_radar_aeo_dossier_radar_aeo_dossier__probe_id__get: {
+    input: {
+    path: {
+      /** AEO probe id. */
+      probe_id: string;
+    };
+    query?: {
+      /** Only this answer engine. */
+      engine?: string | null;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_RadarReportPayload_;
+  };
+  /**
+   * GET /radar/aeo/sources
+   * Get Radar Aeo Sources
+   * tier: read · scope: intent:read
+   */
+  get_radar_aeo_sources_radar_aeo_sources_get: {
+    input: {
+    query?: {
+      days?: number;
+      /** Only this answer engine. */
+      engine?: string | null;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_RadarReportPayload_;
+  };
+  /**
+   * GET /radar/reports/{report_id}/html
+   * Get Radar Report Html
+   * tier: read · scope: intent:read
+   */
+  get_radar_report_html_radar_reports__report_id__html_get: {
+    input: {
+    path: {
+      report_id: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: void;
+  };
+  /**
+   * GET /radar/reports/{report_id}/pdf
+   * Get Radar Report Pdf
+   * tier: read · scope: intent:read
+   */
+  get_radar_report_pdf_radar_reports__report_id__pdf_get: {
+    input: {
+    path: {
+      report_id: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: void;
+  };
+  /**
+   * GET /radar/case-files
+   * List Radar Case Files
+   * tier: read · scope: intent:read
+   */
+  list_radar_case_files_radar_case_files_get: {
+    input: {
+    query?: {
+      /** Only case files in this status. */
+      status?: string | null;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_RadarReportListPayload_;
+  };
+  /**
+   * GET /radar/reports
+   * List Radar Reports
+   * tier: read · scope: intent:read
+   */
+  list_radar_reports_radar_reports_get: {
+    input: {
+    query?: {
+      capability_id?: string | null;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_RadarReportListPayload_;
+  };
+}
+
+// 7 schemas referenced above (the same as G8Contract.<Name>).
+
+export interface ApiResponse_RadarReportListPayload_ {
+  data: RadarReportListPayload;
+  pagination?: PaginationMeta | null;
+}
+
+export interface ApiResponse_RadarReportPayload_ {
+  data: RadarReportPayload;
+  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;
+}
+
+export interface RadarCaseFileActionRequest {
+  action: "mark_played" | "dismiss";
+}
+
+export interface RadarReportCreateRequest {
+  audience: "executive" | "developer";
+  capability_id: string;
+  edge: "us" | "them";
+}
+
+/** A list of reports or case files under `items`. */
+export interface RadarReportListPayload {
+  items?: Array<unknown>;
+  [key: string]: unknown;
+}
+
+/** A deep-dive report, case file, dossier or leaderboard. */
+export type RadarReportPayload = Record<string, unknown>;

package/docs/api/radarReports.md

@@ -0,0 +1,306 @@
+<!-- Generated by sdk/js/scripts/generate-agent-docs.ts from developer-contract/openapi.json. Regenerated on every build. -->
+
+# `g8.api.radarReports`: Radar Reports
+
+8 operations (6 read, 1 write, 1 billable).
+
+No hand-written client covers this area. Call it through `g8.api.radarReports.*` 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: [radarReports.d.ts](radarReports.d.ts).
+
+## Operations
+
+| Call | HTTP | Tier | Scope | Summary |
+|---|---|---|---|---|
+| [`actOnRadarCaseFile`](#op-actonradarcasefile) | `POST /api/v1/radar/case-files/{case_id}/action` | write | `intent:write` | Act On Radar Case File |
+| [`createRadarReport`](#op-createradarreport) | `POST /api/v1/radar/reports` | billable | `intent:run` | Create Radar Report |
+| [`getRadarAeoDossier`](#op-getradaraeodossier) | `GET /api/v1/radar/aeo/dossier/{probe_id}` | read | `intent:read` | Get Radar Aeo Dossier |
+| [`getRadarAeoSources`](#op-getradaraeosources) | `GET /api/v1/radar/aeo/sources` | read | `intent:read` | Get Radar Aeo Sources |
+| [`getRadarReportHtml`](#op-getradarreporthtml) | `GET /api/v1/radar/reports/{report_id}/html` | read | `intent:read` | Get Radar Report Html |
+| [`getRadarReportPdf`](#op-getradarreportpdf) | `GET /api/v1/radar/reports/{report_id}/pdf` | read | `intent:read` | Get Radar Report Pdf |
+| [`listRadarCaseFiles`](#op-listradarcasefiles) | `GET /api/v1/radar/case-files` | read | `intent:read` | List Radar Case Files |
+| [`listRadarReports`](#op-listradarreports) | `GET /api/v1/radar/reports` | read | `intent:read` | List Radar Reports |
+
+---
+
+<a id="op-actonradarcasefile"></a>
+
+### `g8.api.radarReports.actOnRadarCaseFile(input)`
+
+**Act On Radar Case File**
+
+- HTTP: `POST /api/v1/radar/case-files/{case_id}/action`
+- operationId: `act_on_radar_case_file_radar_case_files__case_id__action_post` (also callable as `g8.api.call("act_on_radar_case_file_radar_case_files__case_id__action_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `intent:write`
+
+Record the decision on a case file. `mark_played` also opens a CRM task for it.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.case_id` | `string` | yes | Case file id. |
+| `body` | `RadarCaseFileActionRequest` | yes | Request body; fields below. |
+
+Body fields (`RadarCaseFileActionRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.action` | `"mark_played" \| "dismiss"` | yes |  |
+
+**Returns** `ApiResponse_RadarReportPayload_`: the envelope `{ data: RadarReportPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.radarReports.actOnRadarCaseFile({ path: { case_id: "id" }, body: { action: "mark_played" } });
+```
+
+---
+
+<a id="op-createradarreport"></a>
+
+### `g8.api.radarReports.createRadarReport(input)`
+
+**Create Radar Report**
+
+- HTTP: `POST /api/v1/radar/reports`
+- operationId: `create_radar_report_radar_reports_post` (also callable as `g8.api.call("create_radar_report_radar_reports_post", input)`)
+- Tier: `billable`: spends credits; the SDK never blindly retries it; confirm cost before bulk use
+- API-key scope: `intent:run`
+
+Start a deep-dive report on one capability for one audience (runs a model; billable).
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `RadarReportCreateRequest` | yes | Request body; fields below. |
+
+Body fields (`RadarReportCreateRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.audience` | `"executive" \| "developer"` | yes |  |
+| `body.capability_id` | `string` | yes |  |
+| `body.edge` | `"us" \| "them"` | yes |  |
+
+**Returns** `ApiResponse_RadarReportPayload_`: the envelope `{ data: RadarReportPayload, ... }`. `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.radarReports.createRadarReport({ body: { audience: "executive", capability_id: "id", edge: "us" } });
+```
+
+---
+
+<a id="op-getradaraeodossier"></a>
+
+### `g8.api.radarReports.getRadarAeoDossier(input)`
+
+**Get Radar Aeo Dossier**
+
+- HTTP: `GET /api/v1/radar/aeo/dossier/{probe_id}`
+- operationId: `get_radar_aeo_dossier_radar_aeo_dossier__probe_id__get` (also callable as `g8.api.call("get_radar_aeo_dossier_radar_aeo_dossier__probe_id__get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `intent:read`
+
+One probe's answer dossier: its recent runs, oldest first, with citations.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.probe_id` | `string` | yes | AEO probe id. |
+| `query.engine` | `string \| null` | no | Only this answer engine. |
+
+**Returns** `ApiResponse_RadarReportPayload_`: the envelope `{ data: RadarReportPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.radarReports.getRadarAeoDossier({ path: { probe_id: "id" } });
+```
+
+---
+
+<a id="op-getradaraeosources"></a>
+
+### `g8.api.radarReports.getRadarAeoSources(input?)`
+
+**Get Radar Aeo Sources**
+
+- HTTP: `GET /api/v1/radar/aeo/sources`
+- operationId: `get_radar_aeo_sources_radar_aeo_sources_get` (also callable as `g8.api.call("get_radar_aeo_sources_radar_aeo_sources_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `intent:read`
+
+The domains answer engines cite, classified as yours, a rival's or neutral.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `query.days` | `integer` | no | default `30` |
+| `query.engine` | `string \| null` | no | Only this answer engine. |
+
+**Returns** `ApiResponse_RadarReportPayload_`: the envelope `{ data: RadarReportPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.radarReports.getRadarAeoSources();
+```
+
+---
+
+<a id="op-getradarreporthtml"></a>
+
+### `g8.api.radarReports.getRadarReportHtml(input)`
+
+**Get Radar Report Html**
+
+- HTTP: `GET /api/v1/radar/reports/{report_id}/html`
+- operationId: `get_radar_report_html_radar_reports__report_id__html_get` (also callable as `g8.api.call("get_radar_report_html_radar_reports__report_id__html_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `intent:read`
+
+A completed report as a self-contained HTML document.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.report_id` | `string` | yes |  |
+
+**Returns**: no JSON body is declared for the success response.
+
+**Example**
+
+```ts
+const result = await g8.api.radarReports.getRadarReportHtml({ path: { report_id: "id" } });
+```
+
+---
+
+<a id="op-getradarreportpdf"></a>
+
+### `g8.api.radarReports.getRadarReportPdf(input)`
+
+**Get Radar Report Pdf**
+
+- HTTP: `GET /api/v1/radar/reports/{report_id}/pdf`
+- operationId: `get_radar_report_pdf_radar_reports__report_id__pdf_get` (also callable as `g8.api.call("get_radar_report_pdf_radar_reports__report_id__pdf_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `intent:read`
+
+A completed report as a PDF. 409 while it is still generating.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.report_id` | `string` | yes |  |
+
+**Returns**: no JSON body is declared for the success response.
+
+**Example**
+
+```ts
+const result = await g8.api.radarReports.getRadarReportPdf({ path: { report_id: "id" } });
+```
+
+---
+
+<a id="op-listradarcasefiles"></a>
+
+### `g8.api.radarReports.listRadarCaseFiles(input?)`
+
+**List Radar Case Files**
+
+- HTTP: `GET /api/v1/radar/case-files`
+- operationId: `list_radar_case_files_radar_case_files_get` (also callable as `g8.api.call("list_radar_case_files_radar_case_files_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `intent:read`
+
+The org's case files, newest first (at most 100).
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `query.status` | `string \| null` | no | Only case files in this status. |
+
+**Returns** `ApiResponse_RadarReportListPayload_`: the envelope `{ data: RadarReportListPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`RadarReportListPayload` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `items` | `Array<unknown>` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.radarReports.listRadarCaseFiles();
+```
+
+---
+
+<a id="op-listradarreports"></a>
+
+### `g8.api.radarReports.listRadarReports(input?)`
+
+**List Radar Reports**
+
+- HTTP: `GET /api/v1/radar/reports`
+- operationId: `list_radar_reports_radar_reports_get` (also callable as `g8.api.call("list_radar_reports_radar_reports_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `intent:read`
+
+Deep-dive reports and their status (no content).
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `query.capability_id` | `string \| null` | no |  |
+
+**Returns** `ApiResponse_RadarReportListPayload_`: the envelope `{ data: RadarReportListPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`RadarReportListPayload` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `items` | `Array<unknown>` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.radarReports.listRadarReports();
+```

package/docs/api/recordRoles.d.ts

@@ -0,0 +1,143 @@
+/* Generated by sdk/js/scripts/generate-agent-docs.ts from developer-contract/openapi.json. Regenerated on every build. */
+
+/**
+ * Types for `g8.api.recordRoles` (Record Roles): 4 operations.
+ *
+ * For reading. In code, import from the package instead:
+ *   import type { ApiInput, ApiOutput, G8Contract } from "@graph8/sdk";
+ *   type In = ApiInput<"assign_record_role_records__entity_type___entity_id__role_assignments_post">;
+ *
+ * Reference with examples: recordRoles.md
+ */
+/* eslint-disable */
+
+/** `g8.api.recordRoles.<member>` -> the operationId it calls. */
+export interface RecordRolesMembers {
+  assignRecordRole: "assign_record_role_records__entity_type___entity_id__role_assignments_post";
+  clearRecordRole: "clear_record_role_records__entity_type___entity_id__role_assignments__role_slot__delete";
+  getRecordRoleHistory: "get_record_role_history_records__entity_type___entity_id__role_history_get";
+  getRecordRoleSlots: "get_record_role_slots_records__entity_type___entity_id__role_slots_get";
+}
+
+/** Input and output of every `g8.api.recordRoles` operation, keyed by operationId. */
+export interface RecordRolesOperations {
+  /**
+   * POST /records/{entity_type}/{entity_id}/role-assignments
+   * Assign Record Role
+   * tier: write · scope: contacts:write
+   */
+  assign_record_role_records__entity_type___entity_id__role_assignments_post: {
+    input: {
+    path: {
+      /** `contact`, `company` or `deal`. */
+      entity_type: "contact" | "company" | "deal";
+      /** The record id. */
+      entity_id: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: RecordRoleAssignRequest;
+  };
+    output: ApiResponse_RecordRolePayload_;
+  };
+  /**
+   * DELETE /records/{entity_type}/{entity_id}/role-assignments/{role_slot}
+   * Clear Record Role
+   * tier: destructive · scope: contacts:delete
+   */
+  clear_record_role_records__entity_type___entity_id__role_assignments__role_slot__delete: {
+    input: {
+    path: {
+      /** `contact`, `company` or `deal`. */
+      entity_type: "contact" | "company" | "deal";
+      /** The record id. */
+      entity_id: string;
+      /** The slot to clear. */
+      role_slot: "sdr" | "ae" | "csm";
+    };
+    query?: {
+      /** Recorded on the history row. */
+      reason?: string | null;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_RecordRolePayload_;
+  };
+  /**
+   * GET /records/{entity_type}/{entity_id}/role-history
+   * Get Record Role History
+   * tier: read · scope: contacts:read
+   */
+  get_record_role_history_records__entity_type___entity_id__role_history_get: {
+    input: {
+    path: {
+      /** `contact`, `company` or `deal`. */
+      entity_type: "contact" | "company" | "deal";
+      /** The record id. */
+      entity_id: string;
+    };
+    query?: {
+      /** Only this slot. */
+      slot?: ("sdr" | "ae" | "csm") | null;
+      limit?: number;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_RecordRolePayload_;
+  };
+  /**
+   * GET /records/{entity_type}/{entity_id}/role-slots
+   * Get Record Role Slots
+   * tier: read · scope: contacts:read
+   */
+  get_record_role_slots_records__entity_type___entity_id__role_slots_get: {
+    input: {
+    path: {
+      /** `contact`, `company` or `deal`. */
+      entity_type: "contact" | "company" | "deal";
+      /** The record id. */
+      entity_id: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_RecordRolePayload_;
+  };
+}
+
+// 4 schemas referenced above (the same as G8Contract.<Name>).
+
+export interface ApiResponse_RecordRolePayload_ {
+  data: RecordRolePayload;
+  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;
+}
+
+export interface RecordRoleAssignRequest {
+  /** Why: manual_reassign | rule_based | account_owner_change | import | api. */
+  reason?: string | null;
+  role_slot: "sdr" | "ae" | "csm";
+  /** The org member to put in the slot. */
+  user_id: string;
+}
+
+/** Role slots, their history, or the result of a change. */
+export type RecordRolePayload = Record<string, unknown>;