@graph8/sdk 0.251.0 → 0.262.0

package/docs/api/crmSyncs.d.ts

@@ -0,0 +1,215 @@
+/* Generated by sdk/js/scripts/generate-agent-docs.ts from developer-contract/openapi.json. Regenerated on every build. */
+
+/**
+ * Types for `g8.api.crmSyncs` (CRM Syncs): 6 operations.
+ *
+ * For reading. In code, import from the package instead:
+ *   import type { ApiInput, ApiOutput, G8Contract } from "@graph8/sdk";
+ *   type In = ApiInput<"get_crm_fields_crm_syncs__provider__fields_get">;
+ *
+ * Reference with examples: crmSyncs.md
+ */
+/* eslint-disable */
+
+/** `g8.api.crmSyncs.<member>` -> the operationId it calls. */
+export interface CrmSyncsMembers {
+  getCrmFields: "get_crm_fields_crm_syncs__provider__fields_get";
+  getCrmStatus: "get_crm_status_crm_syncs__provider__status_get";
+  listCrmSyncs: "list_crm_syncs_crm_syncs_get";
+  pushCompaniesToCrm: "push_companies_to_crm_crm_syncs__provider__companies_push_post";
+  pushContactsToCrm: "push_contacts_to_crm_crm_syncs__provider__contacts_push_post";
+  pushListMemberships: "push_list_memberships_crm_syncs__provider__lists_push_post";
+}
+
+/** Input and output of every `g8.api.crmSyncs` operation, keyed by operationId. */
+export interface CrmSyncsOperations {
+  /**
+   * GET /crm-syncs/{provider}/fields
+   * Get Crm Fields
+   * tier: read · scope: integrations:read
+   */
+  get_crm_fields_crm_syncs__provider__fields_get: {
+    input: {
+    path: {
+      /** CRM provider */
+      provider: CrmProvider;
+    };
+    query?: {
+      /** Entity type: contacts, companies, leads, deals */
+      entity_type?: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_CrmFieldsResponse_;
+  };
+  /**
+   * GET /crm-syncs/{provider}/status
+   * Get Crm Status
+   * tier: read · scope: integrations:read
+   */
+  get_crm_status_crm_syncs__provider__status_get: {
+    input: {
+    path: {
+      /** CRM provider */
+      provider: CrmProvider;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_CrmStatusResponse_;
+  };
+  /**
+   * GET /crm-syncs
+   * List Crm Syncs
+   * tier: read · scope: integrations:read
+   */
+  list_crm_syncs_crm_syncs_get: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_list_CrmIntegrationResponse__;
+  };
+  /**
+   * POST /crm-syncs/{provider}/companies/push
+   * Push Companies To Crm
+   * tier: external · scope: integrations:run
+   */
+  push_companies_to_crm_crm_syncs__provider__companies_push_post: {
+    input: {
+    path: {
+      /** CRM provider */
+      provider: CrmProvider;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: CrmPushRequest;
+  };
+    output: ApiResponse_CrmPushResponse_;
+  };
+  /**
+   * POST /crm-syncs/{provider}/contacts/push
+   * Push Contacts To Crm
+   * tier: external · scope: integrations:run
+   */
+  push_contacts_to_crm_crm_syncs__provider__contacts_push_post: {
+    input: {
+    path: {
+      /** CRM provider */
+      provider: CrmProvider;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: CrmPushRequest;
+  };
+    output: ApiResponse_CrmPushResponse_;
+  };
+  /**
+   * POST /crm-syncs/{provider}/lists/push
+   * Push List Memberships
+   * tier: external · scope: integrations:run
+   */
+  push_list_memberships_crm_syncs__provider__lists_push_post: {
+    input: {
+    path: {
+      /** CRM provider */
+      provider: CrmProvider;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: CrmPushRequest;
+  };
+    output: ApiResponse_dict_;
+  };
+}
+
+// 13 schemas referenced above (the same as G8Contract.<Name>).
+
+export interface ApiResponse_CrmFieldsResponse_ {
+  data: CrmFieldsResponse;
+  pagination?: PaginationMeta | null;
+}
+
+export interface ApiResponse_CrmPushResponse_ {
+  data: CrmPushResponse;
+  pagination?: PaginationMeta | null;
+}
+
+export interface ApiResponse_CrmStatusResponse_ {
+  data: CrmStatusResponse;
+  pagination?: PaginationMeta | null;
+}
+
+export interface ApiResponse_dict_ {
+  data: Record<string, unknown>;
+  pagination?: PaginationMeta | null;
+}
+
+export interface ApiResponse_list_CrmIntegrationResponse__ {
+  data: Array<CrmIntegrationResponse>;
+  pagination?: PaginationMeta | null;
+}
+
+export interface CrmFieldItem {
+  label?: string | null;
+  name: string;
+  required?: boolean | null;
+  slug: string;
+  type?: string | null;
+}
+
+export interface CrmFieldsResponse {
+  fields?: Array<CrmFieldItem>;
+}
+
+export interface CrmIntegrationResponse {
+  connected_at?: string | null;
+  connection_id?: string | null;
+  last_sync_at?: string | null;
+  provider: string;
+  status: string;
+}
+
+export type CrmProvider = "hubspot" | "salesforce" | "pipedrive" | "zoho" | "sugarcrm";
+
+export interface CrmPushRequest {
+  /** Field mapping overrides */
+  provider_fields?: Record<string, unknown> | null;
+  /** Records to push to the CRM provider */
+  records: Array<Record<string, unknown>>;
+}
+
+export interface CrmPushResponse {
+  errors?: Array<Record<string, unknown>>;
+  failed_count?: number;
+  pushed_count?: number;
+}
+
+export interface CrmStatusResponse {
+  connected: boolean;
+  connection_id?: string | null;
+  crm_type?: string | null;
+  last_sync_at?: string | null;
+  message?: string | null;
+  provider: 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;
+}

package/docs/api/crmSyncs.md

@@ -0,0 +1,301 @@
+<!-- Generated by sdk/js/scripts/generate-agent-docs.ts from developer-contract/openapi.json. Regenerated on every build. -->
+
+# `g8.api.crmSyncs`: CRM Syncs
+
+6 operations (3 read, 3 external).
+
+No hand-written client covers this area. Call it through `g8.api.crmSyncs.*` 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: [crmSyncs.d.ts](crmSyncs.d.ts).
+
+## Operations
+
+| Call | HTTP | Tier | Scope | Summary |
+|---|---|---|---|---|
+| [`getCrmFields`](#op-getcrmfields) | `GET /api/v1/crm-syncs/{provider}/fields` | read | `integrations:read` | Get Crm Fields |
+| [`getCrmStatus`](#op-getcrmstatus) | `GET /api/v1/crm-syncs/{provider}/status` | read | `integrations:read` | Get Crm Status |
+| [`listCrmSyncs`](#op-listcrmsyncs) | `GET /api/v1/crm-syncs` | read | `integrations:read` | List Crm Syncs |
+| [`pushCompaniesToCrm`](#op-pushcompaniestocrm) | `POST /api/v1/crm-syncs/{provider}/companies/push` | external | `integrations:run` | Push Companies To Crm |
+| [`pushContactsToCrm`](#op-pushcontactstocrm) | `POST /api/v1/crm-syncs/{provider}/contacts/push` | external | `integrations:run` | Push Contacts To Crm |
+| [`pushListMemberships`](#op-pushlistmemberships) | `POST /api/v1/crm-syncs/{provider}/lists/push` | external | `integrations:run` | Push List Memberships |
+
+---
+
+<a id="op-getcrmfields"></a>
+
+### `g8.api.crmSyncs.getCrmFields(input)`
+
+**Get Crm Fields**
+
+- HTTP: `GET /api/v1/crm-syncs/{provider}/fields`
+- operationId: `get_crm_fields_crm_syncs__provider__fields_get` (also callable as `g8.api.call("get_crm_fields_crm_syncs__provider__fields_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `integrations:read`
+
+Discover available fields for an entity type on a CRM provider.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.provider` | `CrmProvider` | yes | CRM provider |
+| `query.entity_type` | `string` | no | Entity type: contacts, companies, leads, deals default `"contacts"` |
+
+**Returns** `ApiResponse_CrmFieldsResponse_`: the envelope `{ data: CrmFieldsResponse, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`CrmFieldsResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `fields` | `Array<CrmFieldItem>` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.crmSyncs.getCrmFields({ path: { provider: "hubspot" } });
+```
+
+---
+
+<a id="op-getcrmstatus"></a>
+
+### `g8.api.crmSyncs.getCrmStatus(input)`
+
+**Get Crm Status**
+
+- HTTP: `GET /api/v1/crm-syncs/{provider}/status`
+- operationId: `get_crm_status_crm_syncs__provider__status_get` (also callable as `g8.api.call("get_crm_status_crm_syncs__provider__status_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `integrations:read`
+
+Check connection health for a CRM provider.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.provider` | `CrmProvider` | yes | CRM provider |
+
+**Returns** `ApiResponse_CrmStatusResponse_`: the envelope `{ data: CrmStatusResponse, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`CrmStatusResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `connected` | `boolean` | yes |  |
+| `provider` | `string` | yes |  |
+| `connection_id` | `string \| null` | no |  |
+| `crm_type` | `string \| null` | no |  |
+| `last_sync_at` | `string \| null` | no |  |
+| `message` | `string \| null` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.crmSyncs.getCrmStatus({ path: { provider: "hubspot" } });
+```
+
+---
+
+<a id="op-listcrmsyncs"></a>
+
+### `g8.api.crmSyncs.listCrmSyncs(input?)`
+
+**List Crm Syncs**
+
+- HTTP: `GET /api/v1/crm-syncs`
+- operationId: `list_crm_syncs_crm_syncs_get` (also callable as `g8.api.call("list_crm_syncs_crm_syncs_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `integrations:read`
+
+List configured CRM integrations for the org.
+
+**Input**: none.
+
+**Returns** `ApiResponse_list_CrmIntegrationResponse__`: the envelope `{ data: Array<CrmIntegrationResponse>, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`CrmIntegrationResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `provider` | `string` | yes |  |
+| `status` | `string` | yes |  |
+| `connected_at` | `string \| null` | no |  |
+| `connection_id` | `string \| null` | no |  |
+| `last_sync_at` | `string \| null` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.crmSyncs.listCrmSyncs();
+```
+
+---
+
+<a id="op-pushcompaniestocrm"></a>
+
+### `g8.api.crmSyncs.pushCompaniesToCrm(input)`
+
+**Push Companies To Crm**
+
+- HTTP: `POST /api/v1/crm-syncs/{provider}/companies/push`
+- operationId: `push_companies_to_crm_crm_syncs__provider__companies_push_post` (also callable as `g8.api.call("push_companies_to_crm_crm_syncs__provider__companies_push_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: `integrations:run`
+
+Push companies to an external CRM provider.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.provider` | `CrmProvider` | yes | CRM provider |
+| `body` | `CrmPushRequest` | yes | Request body; fields below. |
+
+Body fields (`CrmPushRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.records` | `Array<Record<string, unknown>>` | yes | Records to push to the CRM provider |
+| `body.provider_fields` | `Record<string, unknown> \| null` | no | Field mapping overrides |
+
+**Returns** `ApiResponse_CrmPushResponse_`: the envelope `{ data: CrmPushResponse, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`CrmPushResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `errors` | `Array<Record<string, unknown>>` | no |  |
+| `failed_count` | `integer` | no | default `0` |
+| `pushed_count` | `integer` | no | default `0` |
+
+**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.crmSyncs.pushCompaniesToCrm({ path: { provider: "hubspot" }, body: { records: [{}] } });
+```
+
+---
+
+<a id="op-pushcontactstocrm"></a>
+
+### `g8.api.crmSyncs.pushContactsToCrm(input)`
+
+**Push Contacts To Crm**
+
+- HTTP: `POST /api/v1/crm-syncs/{provider}/contacts/push`
+- operationId: `push_contacts_to_crm_crm_syncs__provider__contacts_push_post` (also callable as `g8.api.call("push_contacts_to_crm_crm_syncs__provider__contacts_push_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: `integrations:run`
+
+Push contacts to an external CRM provider.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.provider` | `CrmProvider` | yes | CRM provider |
+| `body` | `CrmPushRequest` | yes | Request body; fields below. |
+
+Body fields (`CrmPushRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.records` | `Array<Record<string, unknown>>` | yes | Records to push to the CRM provider |
+| `body.provider_fields` | `Record<string, unknown> \| null` | no | Field mapping overrides |
+
+**Returns** `ApiResponse_CrmPushResponse_`: the envelope `{ data: CrmPushResponse, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`CrmPushResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `errors` | `Array<Record<string, unknown>>` | no |  |
+| `failed_count` | `integer` | no | default `0` |
+| `pushed_count` | `integer` | no | default `0` |
+
+**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.crmSyncs.pushContactsToCrm({ path: { provider: "hubspot" }, body: { records: [{}] } });
+```
+
+---
+
+<a id="op-pushlistmemberships"></a>
+
+### `g8.api.crmSyncs.pushListMemberships(input)`
+
+**Push List Memberships**
+
+- HTTP: `POST /api/v1/crm-syncs/{provider}/lists/push`
+- operationId: `push_list_memberships_crm_syncs__provider__lists_push_post` (also callable as `g8.api.call("push_list_memberships_crm_syncs__provider__lists_push_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: `integrations:run`
+
+Modify CRM list memberships (add/remove contacts).
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.provider` | `CrmProvider` | yes | CRM provider |
+| `body` | `CrmPushRequest` | yes | Request body; fields below. |
+
+Body fields (`CrmPushRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.records` | `Array<Record<string, unknown>>` | yes | Records to push to the CRM provider |
+| `body.provider_fields` | `Record<string, unknown> \| null` | no | Field mapping overrides |
+
+**Returns** `ApiResponse_dict_`: the envelope `{ data: Record<string, unknown>, ... }`. `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.crmSyncs.pushListMemberships({ path: { provider: "hubspot" }, body: { records: [{}] } });
+```
+
+---
+
+## Referenced types
+
+Named types that appear in the tables above. Full TypeScript definitions: `G8Contract.<Name>` (`import type { G8Contract } from "@graph8/sdk"`).
+
+<a id="type-crmfielditem"></a>
+
+### `CrmFieldItem`
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `name` | `string` | yes |  |
+| `slug` | `string` | yes |  |
+| `label` | `string \| null` | no |  |
+| `required` | `boolean \| null` | no |  |
+| `type` | `string \| null` | no |  |