@graph8/sdk 0.251.0 → 0.260.0

package/docs/api/duplicates.d.ts

@@ -0,0 +1,195 @@
+/* Generated by sdk/js/scripts/generate-agent-docs.ts from developer-contract/openapi.json. Regenerated on every build. */
+
+/**
+ * Types for `g8.api.duplicates` (Duplicates): 7 operations.
+ *
+ * For reading. In code, import from the package instead:
+ *   import type { ApiInput, ApiOutput, G8Contract } from "@graph8/sdk";
+ *   type In = ApiInput<"duplicate_counts_duplicates_counts_get">;
+ *
+ * Reference with examples: duplicates.md
+ */
+/* eslint-disable */
+
+/** `g8.api.duplicates.<member>` -> the operationId it calls. */
+export interface DuplicatesMembers {
+  duplicateCounts: "duplicate_counts_duplicates_counts_get";
+  getBulkMergeStatus: "get_bulk_merge_status_duplicates_bulk_merge__run_id__get";
+  listDuplicates: "list_duplicates_duplicates_get";
+  listRecentMerges: "list_recent_merges_duplicates_recent_merges_get";
+  rejectSuggestion: "reject_suggestion_duplicates__suggestion_id__reject_post";
+  startBulkMerge: "start_bulk_merge_duplicates_bulk_merge_post";
+  undoMerge: "undo_merge_duplicates_undo_merge__merge_history_id__post";
+}
+
+/** Input and output of every `g8.api.duplicates` operation, keyed by operationId. */
+export interface DuplicatesOperations {
+  /**
+   * GET /duplicates/counts
+   * Duplicate Counts
+   * tier: read · scope: contacts:read
+   */
+  duplicate_counts_duplicates_counts_get: {
+    input: {
+    query: {
+      entity_type: "contact" | "company" | "deal";
+      lifecycle_stage?: string | null;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_dict_str__Any__;
+  };
+  /**
+   * GET /duplicates/bulk-merge/{run_id}
+   * Get Bulk Merge Status
+   * tier: read · scope: contacts:read
+   */
+  get_bulk_merge_status_duplicates_bulk_merge__run_id__get: {
+    input: {
+    path: {
+      run_id: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_dict_str__Any__;
+  };
+  /**
+   * GET /duplicates
+   * List Duplicates
+   * tier: read · scope: contacts:read
+   */
+  list_duplicates_duplicates_get: {
+    input: {
+    query: {
+      entity_type: "contact" | "company" | "deal";
+      status?: string;
+      owner_id?: string | null;
+      industry?: string | null;
+      confidence?: string | null;
+      /** Comma-separated list of lifecycle stages (e.g. 'lead') */
+      lifecycle_stage?: string | null;
+      created_after?: string | null;
+      created_before?: string | null;
+      last_activity_after?: string | null;
+      last_activity_before?: string | null;
+      discovered_after?: string | null;
+      discovered_before?: string | null;
+      search?: string | null;
+      cursor?: string | null;
+      limit?: number;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_dict_str__Any__;
+  };
+  /**
+   * GET /duplicates/recent-merges
+   * List Recent Merges
+   * tier: read · scope: contacts:read
+   */
+  list_recent_merges_duplicates_recent_merges_get: {
+    input: {
+    query?: {
+      entity_type?: ("contact" | "company" | "deal") | null;
+      include_shadow?: boolean;
+      limit?: number;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_list_dict_str__Any___;
+  };
+  /**
+   * POST /duplicates/{suggestion_id}/reject
+   * Reject Suggestion
+   * tier: write · scope: contacts:write
+   */
+  reject_suggestion_duplicates__suggestion_id__reject_post: {
+    input: {
+    path: {
+      /** cb_duplicate_suggestions.id */
+      suggestion_id: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body?: RejectDuplicateRequest;
+  };
+    output: ApiResponse_dict_str__Any__;
+  };
+  /**
+   * POST /duplicates/bulk-merge
+   * Start Bulk Merge
+   * tier: write · scope: contacts:delete
+   */
+  start_bulk_merge_duplicates_bulk_merge_post: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: MergeDuplicatesRequest;
+  };
+    output: ApiResponse_dict_str__Any__;
+  };
+  /**
+   * POST /duplicates/undo-merge/{merge_history_id}
+   * Undo Merge
+   * tier: write · scope: contacts:write
+   */
+  undo_merge_duplicates_undo_merge__merge_history_id__post: {
+    input: {
+    path: {
+      merge_history_id: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_dict_str__Any__;
+  };
+}
+
+// 5 schemas referenced above (the same as G8Contract.<Name>).
+
+export interface ApiResponse_dict_str__Any__ {
+  data: Record<string, unknown>;
+  pagination?: PaginationMeta | null;
+}
+
+export interface ApiResponse_list_dict_str__Any___ {
+  data: Array<Record<string, unknown>>;
+  pagination?: PaginationMeta | null;
+}
+
+/**
+ * Kick off a bulk merge run for up to ``BULK_MERGE_MAX_PAIRS`` suggestion
+ * pairs. Mirrors ``duplicates/interfaces/router.py::_BulkMergeRequest``.
+ */
+export interface MergeDuplicatesRequest {
+  criterion: "most_recent_engagement" | "oldest_engagement" | "created_first" | "created_last" | "most_recently_updated";
+  suggestion_ids: Array<string>;
+}
+
+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 RejectDuplicateRequest {
+  reason?: string | null;
+}

package/docs/api/duplicates.md

@@ -0,0 +1,315 @@
+<!-- Generated by sdk/js/scripts/generate-agent-docs.ts from developer-contract/openapi.json. Regenerated on every build. -->
+
+# `g8.api.duplicates`: Duplicates
+
+7 operations (4 read, 3 write).
+
+No hand-written client covers this area. Call it through `g8.api.duplicates.*` 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: [duplicates.d.ts](duplicates.d.ts).
+
+## Operations
+
+| Call | HTTP | Tier | Scope | Summary |
+|---|---|---|---|---|
+| [`duplicateCounts`](#op-duplicatecounts) | `GET /api/v1/duplicates/counts` | read | `contacts:read` | Duplicate Counts |
+| [`getBulkMergeStatus`](#op-getbulkmergestatus) | `GET /api/v1/duplicates/bulk-merge/{run_id}` | read | `contacts:read` | Get Bulk Merge Status |
+| [`listDuplicates`](#op-listduplicates) | `GET /api/v1/duplicates` | read | `contacts:read` | List Duplicates |
+| [`listRecentMerges`](#op-listrecentmerges) | `GET /api/v1/duplicates/recent-merges` | read | `contacts:read` | List Recent Merges |
+| [`rejectSuggestion`](#op-rejectsuggestion) | `POST /api/v1/duplicates/{suggestion_id}/reject` | write | `contacts:write` | Reject Suggestion |
+| [`startBulkMerge`](#op-startbulkmerge) | `POST /api/v1/duplicates/bulk-merge` | write | `contacts:delete` | Start Bulk Merge |
+| [`undoMerge`](#op-undomerge) | `POST /api/v1/duplicates/undo-merge/{merge_history_id}` | write | `contacts:write` | Undo Merge |
+
+---
+
+<a id="op-duplicatecounts"></a>
+
+### `g8.api.duplicates.duplicateCounts(input)`
+
+**Duplicate Counts**
+
+- HTTP: `GET /api/v1/duplicates/counts`
+- operationId: `duplicate_counts_duplicates_counts_get` (also callable as `g8.api.call("duplicate_counts_duplicates_counts_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `contacts:read`
+
+Badge count of pending duplicate suggestions. Proxies
+``GET /v1/duplicates/counts`` (``duplicates/interfaces/router.py:556``).
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `query.entity_type` | `"contact" \| "company" \| "deal"` | yes |  |
+| `query.lifecycle_stage` | `string \| null` | no |  |
+
+**Returns** `ApiResponse_dict_str__Any__`: the envelope `{ data: Record<string, unknown>, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.duplicates.duplicateCounts({ query: { entity_type: "contact" } });
+```
+
+---
+
+<a id="op-getbulkmergestatus"></a>
+
+### `g8.api.duplicates.getBulkMergeStatus(input)`
+
+**Get Bulk Merge Status**
+
+- HTTP: `GET /api/v1/duplicates/bulk-merge/{run_id}`
+- operationId: `get_bulk_merge_status_duplicates_bulk_merge__run_id__get` (also callable as `g8.api.call("get_bulk_merge_status_duplicates_bulk_merge__run_id__get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `contacts:read`
+
+Poll a bulk-merge run started via ``POST /duplicates/bulk-merge``
+(this router or the app UI -- same in-process run registry, see module
+docstring). Proxies ``GET /v1/duplicates/bulk-merge/{run_id}``.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.run_id` | `string` | yes |  |
+
+**Returns** `ApiResponse_dict_str__Any__`: the envelope `{ data: Record<string, unknown>, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.duplicates.getBulkMergeStatus({ path: { run_id: "id" } });
+```
+
+---
+
+<a id="op-listduplicates"></a>
+
+### `g8.api.duplicates.listDuplicates(input)`
+
+**List Duplicates**
+
+- HTTP: `GET /api/v1/duplicates`
+- operationId: `list_duplicates_duplicates_get` (also callable as `g8.api.call("list_duplicates_duplicates_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `contacts:read`
+
+List duplicate-suggestion pairs. Proxies the app's own
+``GET /v1/duplicates`` (``duplicates/interfaces/router.py:497``) --
+see module docstring for why this is a direct function call.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `query.entity_type` | `"contact" \| "company" \| "deal"` | yes |  |
+| `query.status` | `string` | no | default `"pending"` |
+| `query.owner_id` | `string \| null` | no |  |
+| `query.industry` | `string \| null` | no |  |
+| `query.confidence` | `string \| null` | no |  |
+| `query.lifecycle_stage` | `string \| null` | no | Comma-separated list of lifecycle stages (e.g. 'lead') |
+| `query.created_after` | `string (date-time) \| null` | no |  |
+| `query.created_before` | `string (date-time) \| null` | no |  |
+| `query.last_activity_after` | `string (date-time) \| null` | no |  |
+| `query.last_activity_before` | `string (date-time) \| null` | no |  |
+| `query.discovered_after` | `string (date-time) \| null` | no |  |
+| `query.discovered_before` | `string (date-time) \| null` | no |  |
+| `query.search` | `string \| null` | no |  |
+| `query.cursor` | `string \| null` | no |  |
+| `query.limit` | `integer` | no | default `25` |
+
+**Returns** `ApiResponse_dict_str__Any__`: the envelope `{ data: Record<string, unknown>, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.duplicates.listDuplicates({ query: { entity_type: "contact" } });
+```
+
+---
+
+<a id="op-listrecentmerges"></a>
+
+### `g8.api.duplicates.listRecentMerges(input?)`
+
+**List Recent Merges**
+
+- HTTP: `GET /api/v1/duplicates/recent-merges`
+- operationId: `list_recent_merges_duplicates_recent_merges_get` (also callable as `g8.api.call("list_recent_merges_duplicates_recent_merges_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `contacts:read`
+
+Recent merges with undo eligibility. Proxies
+``GET /v1/duplicates/recent-merges`` (``duplicates/interfaces/router.py:899``).
+Make undo discoverable: each row's ``can_undo`` flag tells you whether
+``POST /duplicates/undo-merge/{id}`` below will accept it.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `query.entity_type` | `"contact" \| "company" \| "deal" \| null` | no |  |
+| `query.include_shadow` | `boolean` | no | default `false` |
+| `query.limit` | `integer` | no | default `25` |
+
+**Returns** `ApiResponse_list_dict_str__Any___`: the envelope `{ data: Array<Record<string, unknown>>, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.duplicates.listRecentMerges();
+```
+
+---
+
+<a id="op-rejectsuggestion"></a>
+
+### `g8.api.duplicates.rejectSuggestion(input)`
+
+**Reject Suggestion**
+
+- HTTP: `POST /api/v1/duplicates/{suggestion_id}/reject`
+- operationId: `reject_suggestion_duplicates__suggestion_id__reject_post` (also callable as `g8.api.call("reject_suggestion_duplicates__suggestion_id__reject_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `contacts:write`
+
+Mark a pair as not-a-duplicate, permanently. Proxies
+``POST /v1/duplicates/{id}/reject`` (``duplicates/interfaces/router.py:585``).
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.suggestion_id` | `string (uuid)` | yes | cb_duplicate_suggestions.id |
+| `body` | `RejectDuplicateRequest` | no | Request body; fields below. |
+
+Body fields (`RejectDuplicateRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.reason` | `string \| null` | no |  |
+
+**Returns** `ApiResponse_dict_str__Any__`: the envelope `{ data: Record<string, unknown>, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.duplicates.rejectSuggestion({ path: { suggestion_id: "00000000-0000-0000-0000-000000000000" } });
+```
+
+---
+
+<a id="op-startbulkmerge"></a>
+
+### `g8.api.duplicates.startBulkMerge(input)`
+
+**Start Bulk Merge**
+
+- HTTP: `POST /api/v1/duplicates/bulk-merge`
+- operationId: `start_bulk_merge_duplicates_bulk_merge_post` (also callable as `g8.api.call("start_bulk_merge_duplicates_bulk_merge_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `contacts:delete`
+
+Merge a group: start a bulk merge run over up to 50 suggestion pairs.
+Proxies ``POST /v1/duplicates/bulk-merge``
+(``duplicates/interfaces/router.py:617``) -- same blocker checks, same
+per-pair transactions, same ``MergeContactBlockedError``/
+``MergeCompanyBlockedError`` handling. Returns immediately with a
+``run_id``; poll ``GET /duplicates/bulk-merge/{run_id}`` for progress.
+Merge is destructive: an already-applied pair is only reversible via
+``POST /duplicates/undo-merge/{merge_history_id}`` within its 30-day
+window, so check the response and the recent-merges feed rather than
+assuming success.
+
+Idempotency: this is a POST, so it already honours the standard
+``Idempotency-Key`` header via the platform-wide
+``IdempotencyMiddleware`` (``developer_api/dependencies
+/idempotency_middleware.py``) -- no per-route wiring needed. Retrying
+the same key returns the first run's response instead of starting a
+second run.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `MergeDuplicatesRequest` | yes | Request body; fields below. |
+
+Body fields (`MergeDuplicatesRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.criterion` | `"most_recent_engagement" \| "oldest_engagement" \| "created_first" \| "created_last" \| "most_recently_updated"` | yes |  |
+| `body.suggestion_ids` | `Array<string (uuid)>` | yes | min items 1, max items 50 |
+
+**Returns** `ApiResponse_dict_str__Any__`: the envelope `{ data: Record<string, unknown>, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.duplicates.startBulkMerge({
+  body: {
+    criterion: "most_recent_engagement",
+    suggestion_ids: ["00000000-0000-0000-0000-000000000000"],
+  },
+});
+```
+
+---
+
+<a id="op-undomerge"></a>
+
+### `g8.api.duplicates.undoMerge(input)`
+
+**Undo Merge**
+
+- HTTP: `POST /api/v1/duplicates/undo-merge/{merge_history_id}`
+- operationId: `undo_merge_duplicates_undo_merge__merge_history_id__post` (also callable as `g8.api.call("undo_merge_duplicates_undo_merge__merge_history_id__post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `contacts:write`
+
+Undo a merge within its 30-day recoverability window. Proxies
+``POST /v1/duplicates/undo-merge/{id}``
+(``duplicates/interfaces/router.py:1044``). Contact/company merges only --
+the app's own merge vocabulary excludes deals here too (see
+``shared/merge/entity_registry.py::SUPPORTED_ENTITY_TYPES``), so this
+route accepts no ``deal_scope`` either, matching the app function's own
+signature exactly.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.merge_history_id` | `string` | yes |  |
+
+**Returns** `ApiResponse_dict_str__Any__`: the envelope `{ data: Record<string, unknown>, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.duplicates.undoMerge({ path: { merge_history_id: "id" } });
+```

package/docs/api/eSign.d.ts

@@ -0,0 +1,38 @@
+/* Generated by sdk/js/scripts/generate-agent-docs.ts from developer-contract/openapi.json. Regenerated on every build. */
+
+/**
+ * Types for `g8.api.eSign` (E-Sign): 1 operation.
+ *
+ * For reading. In code, import from the package instead:
+ *   import type { ApiInput, ApiOutput, G8Contract } from "@graph8/sdk";
+ *   type In = ApiInput<"download_signed_envelope_envelopes__envelope_id__pdf_get">;
+ *
+ * Reference with examples: eSign.md
+ */
+/* eslint-disable */
+
+/** `g8.api.eSign.<member>` -> the operationId it calls. */
+export interface ESignMembers {
+  downloadSignedEnvelope: "download_signed_envelope_envelopes__envelope_id__pdf_get";
+}
+
+/** Input and output of every `g8.api.eSign` operation, keyed by operationId. */
+export interface ESignOperations {
+  /**
+   * GET /envelopes/{envelope_id}/pdf
+   * Download Signed Envelope
+   * tier: read · scope: quotes:read
+   */
+  download_signed_envelope_envelopes__envelope_id__pdf_get: {
+    input: {
+    path: {
+      /** Envelope id. */
+      envelope_id: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: void;
+  };
+}

package/docs/api/eSign.md

@@ -0,0 +1,54 @@
+<!-- Generated by sdk/js/scripts/generate-agent-docs.ts from developer-contract/openapi.json. Regenerated on every build. -->
+
+# `g8.api.eSign`: E-Sign
+
+1 operation (1 read).
+
+No hand-written client covers this area. Call it through `g8.api.eSign.*` 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: [eSign.d.ts](eSign.d.ts).
+
+## Operations
+
+| Call | HTTP | Tier | Scope | Summary |
+|---|---|---|---|---|
+| [`downloadSignedEnvelope`](#op-downloadsignedenvelope) | `GET /api/v1/envelopes/{envelope_id}/pdf` | read | `quotes:read` | Download Signed Envelope |
+
+---
+
+<a id="op-downloadsignedenvelope"></a>
+
+### `g8.api.eSign.downloadSignedEnvelope(input)`
+
+**Download Signed Envelope**
+
+- HTTP: `GET /api/v1/envelopes/{envelope_id}/pdf`
+- operationId: `download_signed_envelope_envelopes__envelope_id__pdf_get` (also callable as `g8.api.call("download_signed_envelope_envelopes__envelope_id__pdf_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `quotes:read`
+
+The signed PDF of a completed envelope.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.envelope_id` | `string (uuid)` | yes | Envelope id. |
+
+**Returns**: no JSON body is declared for the success response.
+
+**Example**
+
+```ts
+const result = await g8.api.eSign.downloadSignedEnvelope({ path: { envelope_id: "00000000-0000-0000-0000-000000000000" } });
+```