@graph8/sdk 0.303.0 → 0.357.0

package/docs/api/dataPipelines.md

@@ -0,0 +1,232 @@
+<!-- Generated by sdk/js/scripts/generate-agent-docs.ts from developer-contract/openapi.json. Regenerated on every build. -->
+
+# `g8.api.dataPipelines`: Data pipelines
+
+5 operations (5 read).
+
+No hand-written client covers this area. Call it through `g8.api.dataPipelines.*` 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: [dataPipelines.d.ts](dataPipelines.d.ts).
+
+## Operations
+
+| Call | HTTP | Tier | Scope | Summary |
+|---|---|---|---|---|
+| [`listDestinations`](#op-listdestinations) | `GET /api/v1/data-pipelines/destinations` | read | `integrations:read` | List Destinations |
+| [`listFunctions`](#op-listfunctions) | `GET /api/v1/data-pipelines/functions` | read | `integrations:read` | List Functions |
+| [`listStreamEvents`](#op-liststreamevents) | `GET /api/v1/data-pipelines/streams/{stream_id}/events` | read | `integrations:read` | List Stream Events |
+| [`listSyncTasks`](#op-listsynctasks) | `GET /api/v1/data-pipelines/syncs/{sync_id}/tasks` | read | `integrations:read` | List Sync Tasks |
+| [`listSyncs`](#op-listsyncs) | `GET /api/v1/data-pipelines/syncs` | read | `integrations:read` | List Syncs |
+
+---
+
+<a id="op-listdestinations"></a>
+
+### `g8.api.dataPipelines.listDestinations(input?)`
+
+**List Destinations**
+
+- HTTP: `GET /api/v1/data-pipelines/destinations`
+- operationId: `list_destinations_data_pipelines_destinations_get` (also callable as `g8.api.call("list_destinations_data_pipelines_destinations_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `integrations:read`
+
+List the organization's data destinations (warehouses, webhooks, ad/CRM targets).
+
+Same list as Data > Connections > Destinations. Secrets (passwords, keys,
+service-account JSON, tokens) are never returned: each one reads `__SET__`.
+
+**Input**: none.
+
+**Returns** `ApiResponse_DataPipelineItems_`: the envelope `{ data: DataPipelineItems, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`DataPipelineItems` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `items` | `Array<Record<string, unknown>>` | no |  |
+| `total` | `integer` | no | default `0` |
+
+**Example**
+
+```ts
+const result = await g8.api.dataPipelines.listDestinations();
+```
+
+---
+
+<a id="op-listfunctions"></a>
+
+### `g8.api.dataPipelines.listFunctions(input?)`
+
+**List Functions**
+
+- HTTP: `GET /api/v1/data-pipelines/functions`
+- operationId: `list_functions_data_pipelines_functions_get` (also callable as `g8.api.call("list_functions_data_pipelines_functions_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `integrations:read`
+
+List the organization's event functions (transformations run on a sync).
+
+Same list as Data > Connections > Functions. Function environment secrets
+read `__SET__`.
+
+**Input**: none.
+
+**Returns** `ApiResponse_DataPipelineItems_`: the envelope `{ data: DataPipelineItems, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`DataPipelineItems` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `items` | `Array<Record<string, unknown>>` | no |  |
+| `total` | `integer` | no | default `0` |
+
+**Example**
+
+```ts
+const result = await g8.api.dataPipelines.listFunctions();
+```
+
+---
+
+<a id="op-liststreamevents"></a>
+
+### `g8.api.dataPipelines.listStreamEvents(input)`
+
+**List Stream Events**
+
+- HTTP: `GET /api/v1/data-pipelines/streams/{stream_id}/events`
+- operationId: `list_stream_events_data_pipelines_streams__stream_id__events_get` (also callable as `g8.api.call("list_stream_events_data_pipelines_streams__stream_id__events_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `integrations:read`
+
+Live events: the latest events a tracking stream received, newest first.
+
+Same feed as Data > Connections > Live events. Use it to check a snippet
+install (are page views arriving from the right site?) or to see rejected
+events (`levels=error`). The sender's IP address and HTTP headers are
+dropped from every entry. 404 when the stream is not in this organization.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.stream_id` | `string` | yes | Stream id (from GET /streams). |
+| `query.limit` | `integer` | no | Newest events to return, 1-200. default `50` |
+| `query.start` | `string \| null` | no | Only events at or after (ISO 8601). |
+| `query.end` | `string \| null` | no | Only events before (ISO 8601). |
+| `query.levels` | `"error" \| "warn" \| "info" \| "debug" \| null` | no | Only entries at this log level (e.g. error = rejected events). |
+
+**Returns** `ApiResponse_DataPipelineItems_`: the envelope `{ data: DataPipelineItems, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`DataPipelineItems` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `items` | `Array<Record<string, unknown>>` | no |  |
+| `total` | `integer` | no | default `0` |
+
+**Example**
+
+```ts
+const result = await g8.api.dataPipelines.listStreamEvents({ path: { stream_id: "id" } });
+```
+
+---
+
+<a id="op-listsynctasks"></a>
+
+### `g8.api.dataPipelines.listSyncTasks(input)`
+
+**List Sync Tasks**
+
+- HTTP: `GET /api/v1/data-pipelines/syncs/{sync_id}/tasks`
+- operationId: `list_sync_tasks_data_pipelines_syncs__sync_id__tasks_get` (also callable as `g8.api.call("list_sync_tasks_data_pipelines_syncs__sync_id__tasks_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `integrations:read`
+
+A sync's run history: when each run started, its status and any error.
+
+Connector (service) syncs only; a stream-to-destination sync streams events
+continuously and has no runs. 404 when the sync is not in this organization.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.sync_id` | `string` | yes | Sync id (from GET /data-pipelines/syncs). |
+| `query.status` | `string \| null` | no | Only runs in this status (e.g. SUCCESS, FAILED, RUNNING). |
+| `query.started_after` | `string \| null` | no | Only runs started at or after (ISO 8601). |
+| `query.started_before` | `string \| null` | no | Only runs started before (ISO 8601). |
+
+**Returns** `ApiResponse_DataPipelineItems_`: the envelope `{ data: DataPipelineItems, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`DataPipelineItems` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `items` | `Array<Record<string, unknown>>` | no |  |
+| `total` | `integer` | no | default `0` |
+
+**Example**
+
+```ts
+const result = await g8.api.dataPipelines.listSyncTasks({ path: { sync_id: "id" } });
+```
+
+---
+
+<a id="op-listsyncs"></a>
+
+### `g8.api.dataPipelines.listSyncs(input?)`
+
+**List Syncs**
+
+- HTTP: `GET /api/v1/data-pipelines/syncs`
+- operationId: `list_syncs_data_pipelines_syncs_get` (also callable as `g8.api.call("list_syncs_data_pipelines_syncs_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `integrations:read`
+
+List the organization's syncs: each one connects a stream or connector to a destination.
+
+Same list as Data > Connections > Syncs. Each item carries `fromId`
+(stream or connector id), `toId` (destination id) and its settings. Per-sync
+function secrets read `__SET__`. Run history: GET /data-pipelines/syncs/{sync_id}/tasks.
+
+**Input**: none.
+
+**Returns** `ApiResponse_DataPipelineItems_`: the envelope `{ data: DataPipelineItems, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`DataPipelineItems` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `items` | `Array<Record<string, unknown>>` | no |  |
+| `total` | `integer` | no | default `0` |
+
+**Example**
+
+```ts
+const result = await g8.api.dataPipelines.listSyncs();
+```

package/docs/api/forms.d.ts

@@ -837,14 +837,24 @@ export interface FormOverview {
   activation_health?: string | null;
   capture_health?: string | null;
   delivery_health?: string | null;
+  /** Where leads go: 'route' (tracked delivery route), 'legacy_mapping' (older list mapping; delivered, but processed/failed stay 0 because it writes no receipts) or null (nowhere). */
+  delivery_source?: string | null;
+  /** Plain-language delivery problem, e.g. captured leads with no destination. */
+  delivery_warning?: string | null;
+  /** The destination list: {list_id, route_version, source, list_name?}; null when none. */
+  destination?: Record<string, unknown> | null;
   display_name?: string | null;
   form_key: string;
   identity_state?: string | null;
   last_destination_verified_at?: string | null;
+  /** When a submission of this form was last processed for delivery. */
+  last_processed_at?: string | null;
   metrics?: Record<string, unknown>;
   owner_id?: string | null;
   placement_count?: number;
   recommended_action?: string | null;
+  /** What is missing for someone to own this form's leads: [{code, message}], e.g. owner_missing. */
+  setup_hints?: Array<Record<string, unknown>>;
   source_id: string;
   technical_form_id?: string | null;
 }
@@ -961,8 +971,14 @@ export interface FormSubmissionsSearchRequest {
 
 /** One lead-capture form as returned by the list/search endpoint. */
 export interface FormSummary {
+  /** 'failing' when at least one submission failed delivery; null otherwise. */
+  delivery_health?: string | null;
+  /** Where this form's leads are delivered: 'route' (a tracked delivery route), 'legacy_mapping' (an older list mapping, delivered but not tracked per submission) or 'none' (nowhere). Same value the overview reports. */
+  delivery_source?: string | null;
   /** Human-friendly name for the form. */
   display_name?: string | null;
+  /** Submissions whose delivery failed or was only partly delivered (same count as the overview). */
+  failed_submissions?: number | null;
   /** Alias for id; the addressable key for detail lookups. */
   form_key?: string | null;
   /** The form's HTML tag id (or the id-less group key). */

package/docs/api/forms.md

@@ -400,13 +400,18 @@ Other envelope fields: `pagination` (PaginationMeta).
 | `activation_health` | `string \| null` | no |  |
 | `capture_health` | `string \| null` | no |  |
 | `delivery_health` | `string \| null` | no |  |
+| `delivery_source` | `string \| null` | no | Where leads go: 'route' (tracked delivery route), 'legacy_mapping' (older list mapping; delivered, but processed/failed stay 0 because it writes no receipts) or null (nowhere). |
+| `delivery_warning` | `string \| null` | no | Plain-language delivery problem, e.g. captured leads with no destination. |
+| `destination` | `Record<string, unknown> \| null` | no | The destination list: {list_id, route_version, source, list_name?}; null when none. |
 | `display_name` | `string \| null` | no |  |
 | `identity_state` | `string \| null` | no |  |
 | `last_destination_verified_at` | `string (date-time) \| null` | no |  |
+| `last_processed_at` | `string (date-time) \| null` | no | When a submission of this form was last processed for delivery. |
 | `metrics` | `Record<string, unknown>` | no |  |
 | `owner_id` | `string \| null` | no |  |
 | `placement_count` | `integer` | no | default `0` |
 | `recommended_action` | `string \| null` | no |  |
+| `setup_hints` | `Array<Record<string, unknown>>` | no | What is missing for someone to own this form's leads: [{code, message}], e.g. owner_missing. |
 | `technical_form_id` | `string \| null` | no |  |
 
 **Example**
@@ -1532,7 +1537,10 @@ One lead-capture form as returned by the list/search endpoint.
 | Field | Type | Required | Description |
 |---|---|---|---|
 | `id` | `string` | yes | The form's HTML tag id (or the id-less group key). |
+| `delivery_health` | `string \| null` | no | 'failing' when at least one submission failed delivery; null otherwise. |
+| `delivery_source` | `string \| null` | no | Where this form's leads are delivered: 'route' (a tracked delivery route), 'legacy_mapping' (an older list mapping, delivered but not tracked per submission) or 'none' (nowhere). Same value the overview reports. |
 | `display_name` | `string \| null` | no | Human-friendly name for the form. |
+| `failed_submissions` | `integer \| null` | no | Submissions whose delivery failed or was only partly delivered (same count as the overview). |
 | `form_key` | `string \| null` | no | Alias for id; the addressable key for detail lookups. |
 | `latest_submitted_at` | `string (date-time) \| null` | no | Most recent submission timestamp. |
 | `page_url` | `string \| null` | no | URL of a page where the form was submitted. |