@graph8/sdk 0.251.0 → 0.260.0

package/docs/api/clickHouse.md

@@ -0,0 +1,138 @@
+<!-- Generated by sdk/js/scripts/generate-agent-docs.ts from developer-contract/openapi.json. Regenerated on every build. -->
+
+# `g8.api.clickHouse`: ClickHouse
+
+2 operations (2 write).
+
+No hand-written client covers this area. Call it through `g8.api.clickHouse.*` 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: [clickHouse.d.ts](clickHouse.d.ts).
+
+## Operations
+
+| Call | HTTP | Tier | Scope | Summary |
+|---|---|---|---|---|
+| [`clickhouseMashup`](#op-clickhousemashup) | `POST /api/v1/clickhouse/mashup` | write | `search:write` | Clickhouse Mashup |
+| [`clickhouseOrgAnalytics`](#op-clickhouseorganalytics) | `POST /api/v1/clickhouse/org-analytics` | write | `search:write` | Clickhouse Org Analytics |
+
+---
+
+<a id="op-clickhousemashup"></a>
+
+### `g8.api.clickHouse.clickhouseMashup(input)`
+
+**Clickhouse Mashup**
+
+- HTTP: `POST /api/v1/clickhouse/mashup`
+- operationId: `clickhouse_mashup_clickhouse_mashup_post` (also callable as `g8.api.call("clickhouse_mashup_clickhouse_mashup_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `search:write`
+
+Enrich UP_IDs / HEMs / domains against the ClickHouse Cloud mashup tables.
+
+Use this for bulk enrichment workflows where the agent already has a
+primary key (UP_ID from ``g8_opensearch_resolve_ids``, a HEM from a
+visitor row, or a company domain from CRM). For free-form attribute
+search prefer ``g8_opensearch_search`` against ``mashup_contacts``.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `ClickhouseMashupRequest` | yes | Request body; fields below. |
+
+Body fields (`ClickhouseMashupRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.mode` | `"by_upid" \| "by_hem" \| "by_domain"` | yes | Which mashup PK to filter by. |
+| `body.values` | `Array<string>` | yes | Up to 100 key values (UP_IDs, HEMs, or domains). min items 1, max items 100 |
+| `body.limit` | `integer` | no | default `1000`, min 1, max 1000 |
+| `body.profile` | `"b2b" \| "b2c" \| "joined"` | no | Which mashup table to read. 'joined' returns the lighter denormalized mashup_new with both profiles partially populated. default `"b2b"` |
+
+**Returns** `ApiResponse_ClickhouseMashupResponse_`: the envelope `{ data: ClickhouseMashupResponse, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`ClickhouseMashupResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `mode` | `string` | yes |  |
+| `profile` | `string` | yes |  |
+| `matched` | `integer` | no | default `0` |
+| `records` | `Array<Record<string, unknown>>` | no | default `[]` |
+| `requested` | `integer` | no | default `0` |
+
+**Example**
+
+```ts
+const result = await g8.api.clickHouse.clickhouseMashup({ body: { mode: "by_upid", values: ["example"] } });
+```
+
+---
+
+<a id="op-clickhouseorganalytics"></a>
+
+### `g8.api.clickHouse.clickhouseOrgAnalytics(input)`
+
+**Clickhouse Org Analytics**
+
+- HTTP: `POST /api/v1/clickhouse/org-analytics`
+- operationId: `clickhouse_org_analytics_clickhouse_org_analytics_post` (also callable as `g8.api.call("clickhouse_org_analytics_clickhouse_org_analytics_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `search:write`
+
+Per-org visitor + intent analytics from ch3.
+
+The database name is always derived from the authenticated user's
+``organization.id`` (lower-cased) — the request body never carries
+an org_id. The agent cannot reach another org's data even if it
+tries.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `ClickhouseOrgAnalyticsRequest` | yes | Request body; fields below. |
+
+Body fields (`ClickhouseOrgAnalyticsRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.dataset` | `"people_visitors" \| "company_visitors" \| "5x5_visitors" \| "intent_resolved"` | yes | Which per-org table to read. |
+| `body.since` | `string` | yes | ISO date or datetime (inclusive lower bound). |
+| `body.aggregation` | `"raw" \| "daily_counts" \| "top_n"` | no | 'raw' returns the matching rows (capped). 'daily_counts' returns {day, count}. 'top_n' returns {value, count} grouped by the dataset's primary group key (contact_id, company_id, keyword_id). default `"raw"` |
+| `body.filters` | `Record<string, unknown>` | no | Optional equality filters. Keys must match dataset columns; unknown columns are silently dropped so an LLM guess can't produce a SQL error. |
+| `body.limit` | `integer` | no | default `1000`, min 1, max 1000 |
+| `body.until` | `string \| null` | no | ISO date or datetime (exclusive upper bound). Defaults to now. |
+
+**Returns** `ApiResponse_ClickhouseOrgAnalyticsResponse_`: the envelope `{ data: ClickhouseOrgAnalyticsResponse, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`ClickhouseOrgAnalyticsResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `aggregation` | `string` | yes |  |
+| `dataset` | `string` | yes |  |
+| `rows` | `Array<Record<string, unknown>>` | no | default `[]` |
+| `total` | `integer` | no | default `0` |
+| `window` | `Record<string, string>` | no | default `{}` |
+
+**Example**
+
+```ts
+const result = await g8.api.clickHouse.clickhouseOrgAnalytics({ body: { dataset: "people_visitors", since: "example" } });
+```