@graph8/sdk 0.251.0 → 0.262.0

package/docs/api/gtmDeliverability.d.ts

@@ -0,0 +1,60 @@
+/* Generated by sdk/js/scripts/generate-agent-docs.ts from developer-contract/openapi.json. Regenerated on every build. */
+
+/**
+ * Types for `g8.api.gtmDeliverability` (GTM Deliverability): 1 operation.
+ *
+ * For reading. In code, import from the package instead:
+ *   import type { ApiInput, ApiOutput, G8Contract } from "@graph8/sdk";
+ *   type In = ApiInput<"get_deliverability_metrics_deliverability_metrics_get">;
+ *
+ * Reference with examples: gtmDeliverability.md
+ */
+/* eslint-disable */
+
+/** `g8.api.gtmDeliverability.<member>` -> the operationId it calls. */
+export interface GtmDeliverabilityMembers {
+  getDeliverabilityMetrics: "get_deliverability_metrics_deliverability_metrics_get";
+}
+
+/** Input and output of every `g8.api.gtmDeliverability` operation, keyed by operationId. */
+export interface GtmDeliverabilityOperations {
+  /**
+   * GET /deliverability/metrics
+   * Get Deliverability Metrics
+   * tier: read · scope: campaigns:read
+   */
+  get_deliverability_metrics_deliverability_metrics_get: {
+    input: {
+    query?: {
+      /** Trailing window in days */
+      days?: number;
+      /** Drill into one mailbox's slice */
+      mailbox_id?: number | null;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_dict_;
+  };
+}
+
+// 2 schemas referenced above (the same as G8Contract.<Name>).
+
+export interface ApiResponse_dict_ {
+  data: Record<string, unknown>;
+  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;
+}

package/docs/api/gtmDeliverability.md

@@ -0,0 +1,63 @@
+<!-- Generated by sdk/js/scripts/generate-agent-docs.ts from developer-contract/openapi.json. Regenerated on every build. -->
+
+# `g8.api.gtmDeliverability`: GTM Deliverability
+
+1 operation (1 read).
+
+No hand-written client covers this area. Call it through `g8.api.gtmDeliverability.*` 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: [gtmDeliverability.d.ts](gtmDeliverability.d.ts).
+
+## Operations
+
+| Call | HTTP | Tier | Scope | Summary |
+|---|---|---|---|---|
+| [`getDeliverabilityMetrics`](#op-getdeliverabilitymetrics) | `GET /api/v1/deliverability/metrics` | read | `campaigns:read` | Get Deliverability Metrics |
+
+---
+
+<a id="op-getdeliverabilitymetrics"></a>
+
+### `g8.api.gtmDeliverability.getDeliverabilityMetrics(input?)`
+
+**Get Deliverability Metrics**
+
+- HTTP: `GET /api/v1/deliverability/metrics`
+- operationId: `get_deliverability_metrics_deliverability_metrics_get` (also callable as `g8.api.call("get_deliverability_metrics_deliverability_metrics_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `campaigns:read`
+
+Deliverability capacity / sends / placement / warmup for the caller's org.
+
+Read-only, org-scoped (schema = ``str(org_id).lower()``). Reuses the admin
+dashboard's capacity+sends helpers (issue #14279) and the aggregator's
+honest placement bucketing (issue #14278) so the numbers match the internal
+dashboard by construction. Every signal fails soft to ``null`` — a missing
+ClickHouse / placement source degrades the field, never the whole response.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `query.days` | `integer` | no | Trailing window in days default `7` |
+| `query.mailbox_id` | `integer \| null` | no | Drill into one mailbox's slice |
+
+**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
+const result = await g8.api.gtmDeliverability.getDeliverabilityMetrics();
+```

package/docs/api/gtmKnowledgeBase.d.ts

@@ -0,0 +1,76 @@
+/* Generated by sdk/js/scripts/generate-agent-docs.ts from developer-contract/openapi.json. Regenerated on every build. */
+
+/**
+ * Types for `g8.api.gtmKnowledgeBase` (GTM Knowledge Base): 2 operations.
+ *
+ * For reading. In code, import from the package instead:
+ *   import type { ApiInput, ApiOutput, G8Contract } from "@graph8/sdk";
+ *   type In = ApiInput<"list_kb_documents_kb_get">;
+ *
+ * Reference with examples: gtmKnowledgeBase.md
+ */
+/* eslint-disable */
+
+/** `g8.api.gtmKnowledgeBase.<member>` -> the operationId it calls. */
+export interface GtmKnowledgeBaseMembers {
+  listKbDocuments: "list_kb_documents_kb_get";
+  searchKb: "search_kb_kb_search_post";
+}
+
+/** Input and output of every `g8.api.gtmKnowledgeBase` operation, keyed by operationId. */
+export interface GtmKnowledgeBaseOperations {
+  /**
+   * GET /kb
+   * List Kb Documents
+   * tier: read · scope: campaigns:read
+   */
+  list_kb_documents_kb_get: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_list_dict__;
+  };
+  /**
+   * POST /kb/search
+   * Search Kb
+   * tier: write · scope: campaigns:write
+   */
+  search_kb_kb_search_post: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: KBSearchRequest;
+  };
+    output: ApiResponse_list_dict__;
+  };
+}
+
+// 3 schemas referenced above (the same as G8Contract.<Name>).
+
+export interface ApiResponse_list_dict__ {
+  data: Array<Record<string, unknown>>;
+  pagination?: PaginationMeta | null;
+}
+
+export interface KBSearchRequest {
+  /** Max results */
+  limit?: number;
+  /** Search query */
+  query: 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/gtmKnowledgeBase.md

@@ -0,0 +1,91 @@
+<!-- Generated by sdk/js/scripts/generate-agent-docs.ts from developer-contract/openapi.json. Regenerated on every build. -->
+
+# `g8.api.gtmKnowledgeBase`: GTM Knowledge Base
+
+2 operations (1 read, 1 write).
+
+No hand-written client covers this area. Call it through `g8.api.gtmKnowledgeBase.*` 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: [gtmKnowledgeBase.d.ts](gtmKnowledgeBase.d.ts).
+
+## Operations
+
+| Call | HTTP | Tier | Scope | Summary |
+|---|---|---|---|---|
+| [`listKbDocuments`](#op-listkbdocuments) | `GET /api/v1/kb` | read | `campaigns:read` | List Kb Documents |
+| [`searchKb`](#op-searchkb) | `POST /api/v1/kb/search` | write | `campaigns:write` | Search Kb |
+
+---
+
+<a id="op-listkbdocuments"></a>
+
+### `g8.api.gtmKnowledgeBase.listKbDocuments(input?)`
+
+**List Kb Documents**
+
+- HTTP: `GET /api/v1/kb`
+- operationId: `list_kb_documents_kb_get` (also callable as `g8.api.call("list_kb_documents_kb_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `campaigns:read`
+
+List all KB documents grouped by section.
+
+**Input**: none.
+
+**Returns** `ApiResponse_list_dict__`: 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.gtmKnowledgeBase.listKbDocuments();
+```
+
+---
+
+<a id="op-searchkb"></a>
+
+### `g8.api.gtmKnowledgeBase.searchKb(input)`
+
+**Search Kb**
+
+- HTTP: `POST /api/v1/kb/search`
+- operationId: `search_kb_kb_search_post` (also callable as `g8.api.call("search_kb_kb_search_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `campaigns:write`
+
+Search the GTM knowledge base using full-text search.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `KBSearchRequest` | yes | Request body; fields below. |
+
+Body fields (`KBSearchRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.query` | `string` | yes | Search query |
+| `body.limit` | `integer` | no | Max results default `10`, min 1, max 50 |
+
+**Returns** `ApiResponse_list_dict__`: 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.gtmKnowledgeBase.searchKb({ body: { query: "example" } });
+```

package/docs/api/gtmLaunchHelpers.d.ts

@@ -0,0 +1,123 @@
+/* Generated by sdk/js/scripts/generate-agent-docs.ts from developer-contract/openapi.json. Regenerated on every build. */
+
+/**
+ * Types for `g8.api.gtmLaunchHelpers` (GTM Launch Helpers): 2 operations.
+ *
+ * For reading. In code, import from the package instead:
+ *   import type { ApiInput, ApiOutput, G8Contract } from "@graph8/sdk";
+ *   type In = ApiInput<"list_event_types_event_types_get">;
+ *
+ * Reference with examples: gtmLaunchHelpers.md
+ */
+/* eslint-disable */
+
+/** `g8.api.gtmLaunchHelpers.<member>` -> the operationId it calls. */
+export interface GtmLaunchHelpersMembers {
+  listEventTypes: "list_event_types_event_types_get";
+  listSchedules: "list_schedules_schedules_get";
+}
+
+/** Input and output of every `g8.api.gtmLaunchHelpers` operation, keyed by operationId. */
+export interface GtmLaunchHelpersOperations {
+  /**
+   * GET /event-types
+   * List bookable calendar event types (Cal.com appointments)
+   * tier: read · scope: campaigns:read
+   */
+  list_event_types_event_types_get: {
+    input: {
+    query?: {
+      /** Include event types marked `hidden` (unbookable publicly). Default False. */
+      include_hidden?: boolean;
+      /** Filter by Cal.com scheduling type: managed | round_robin | collective. Omit to return all types including single-host (NULL). */
+      scheduling_type?: string | null;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: EventTypesListResponse;
+  };
+  /**
+   * GET /schedules
+   * List sending schedules (send windows + timezone)
+   * tier: read · scope: campaigns:read
+   */
+  list_schedules_schedules_get: {
+    input: {
+    query?: {
+      /** Include archived schedules in the response. Default False matches the sequencer schedule picker. */
+      include_archived?: boolean;
+      /** Substring filter on schedule name + description. Case-insensitive on the underlying SQL. */
+      search?: string | null;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: SchedulesListResponse;
+  };
+}
+
+// 5 schemas referenced above (the same as G8Contract.<Name>).
+
+/** One row in the booking-link picker. `id` feeds `appointment_id` on the launch body. */
+export interface EventTypeListItem {
+  description?: string | null;
+  /** When True the event type is not bookable publicly. Excluded by default. */
+  hidden?: boolean;
+  /** Event-type integer ID; pass back to launch / PATCH endpoints as `appointment_id`. */
+  id: number;
+  /** Slot duration in minutes. */
+  length: number;
+  /** ID of the availability schedule attached to this event type, if any. */
+  schedule_id?: number | null;
+  /** Cal.com scheduling type: managed | round_robin | collective | None (= single-host). */
+  scheduling_type?: string | null;
+  /** URL-safe slug (the path segment used in `appointments/team/...` links). */
+  slug: string;
+  /** Display title shown on the booking page. */
+  title: string;
+}
+
+/** Envelope for `GET /event-types`. */
+export interface EventTypesListResponse {
+  data: Array<EventTypeListItem>;
+}
+
+/**
+ * One day's send window — flattens `{start, end}` from the sequencer.
+ *
+ * Days that are absent from the underlying config (= no sending) are
+ * omitted from the response rather than serialized as nulls — keeps
+ * the response compact and matches the picker UI's behaviour.
+ */
+export interface ScheduleDayWindow {
+  /** Lowercase day name: monday | tuesday | wednesday | thursday | friday | saturday | sunday. */
+  day: string;
+  /** Window end, 24h HH:MM in `timezone`. */
+  end: string;
+  /** Window start, 24h HH:MM in `timezone`. */
+  start: string;
+}
+
+/** One row in the schedule picker. `id` feeds `schedule_id` on the launch body. */
+export interface ScheduleListItem {
+  /** Optional human description. */
+  description?: string | null;
+  /** Schedule UUID; pass back to launch / PATCH endpoints. */
+  id: string;
+  /** Archived schedules are excluded by default — pass `include_archived=true` to include them. */
+  is_archived?: boolean;
+  /** Display name as set in the Sequencer schedule UI. */
+  name: string;
+  /** IANA timezone name applied to every window (e.g. 'Europe/Madrid'). */
+  timezone: string;
+  /** Per-day send windows for the schedule. Days with no window are omitted. */
+  windows?: Array<ScheduleDayWindow>;
+}
+
+/** Envelope for `GET /schedules`. */
+export interface SchedulesListResponse {
+  data: Array<ScheduleListItem>;
+}

package/docs/api/gtmLaunchHelpers.md

@@ -0,0 +1,148 @@
+<!-- Generated by sdk/js/scripts/generate-agent-docs.ts from developer-contract/openapi.json. Regenerated on every build. -->
+
+# `g8.api.gtmLaunchHelpers`: GTM Launch Helpers
+
+2 operations (2 read).
+
+No hand-written client covers this area. Call it through `g8.api.gtmLaunchHelpers.*` 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: [gtmLaunchHelpers.d.ts](gtmLaunchHelpers.d.ts).
+
+## Operations
+
+| Call | HTTP | Tier | Scope | Summary |
+|---|---|---|---|---|
+| [`listEventTypes`](#op-listeventtypes) | `GET /api/v1/event-types` | read | `campaigns:read` | List bookable calendar event types (Cal.com appointments) |
+| [`listSchedules`](#op-listschedules) | `GET /api/v1/schedules` | read | `campaigns:read` | List sending schedules (send windows + timezone) |
+
+---
+
+<a id="op-listeventtypes"></a>
+
+### `g8.api.gtmLaunchHelpers.listEventTypes(input?)`
+
+**List bookable calendar event types (Cal.com appointments)**
+
+- HTTP: `GET /api/v1/event-types`
+- operationId: `list_event_types_event_types_get` (also callable as `g8.api.call("list_event_types_event_types_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `campaigns:read`
+
+Return the org's bookable event types (calendar links).
+
+Each row carries `id` (integer) and the booking-page metadata. Pass `id`
+back as `appointment_id` on `POST /campaigns/{id}/launch` or
+`PATCH /sequences/{id}` to wire the booking link onto a sequence so the
+Cal.com short-link rewrite kicks in during send.
+
+Backed by the appointments `EventTypesHandler.handle_list` (same handler
+powering the in-app /appointments/event-types picker). We pass the
+authenticated user through so per-user visibility rules apply identically
+to the in-app flow.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `query.include_hidden` | `boolean` | no | Include event types marked `hidden` (unbookable publicly). Default False. default `false` |
+| `query.scheduling_type` | `string \| null` | no | Filter by Cal.com scheduling type: managed \| round_robin \| collective. Omit to return all types including single-host (NULL). |
+
+**Returns** `EventTypesListResponse`: the envelope `{ data: Array<EventTypeListItem>, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+`EventTypeListItem` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `id` | `integer` | yes | Event-type integer ID; pass back to launch / PATCH endpoints as `appointment_id`. |
+| `length` | `integer` | yes | Slot duration in minutes. |
+| `slug` | `string` | yes | URL-safe slug (the path segment used in `appointments/team/...` links). |
+| `title` | `string` | yes | Display title shown on the booking page. |
+| `description` | `string \| null` | no |  |
+| `hidden` | `boolean` | no | When True the event type is not bookable publicly. Excluded by default. default `false` |
+| `schedule_id` | `integer \| null` | no | ID of the availability schedule attached to this event type, if any. |
+| `scheduling_type` | `string \| null` | no | Cal.com scheduling type: managed \| round_robin \| collective \| None (= single-host). |
+
+**Example**
+
+```ts
+const result = await g8.api.gtmLaunchHelpers.listEventTypes();
+```
+
+---
+
+<a id="op-listschedules"></a>
+
+### `g8.api.gtmLaunchHelpers.listSchedules(input?)`
+
+**List sending schedules (send windows + timezone)**
+
+- HTTP: `GET /api/v1/schedules`
+- operationId: `list_schedules_schedules_get` (also callable as `g8.api.call("list_schedules_schedules_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `campaigns:read`
+
+Return the org's send-window schedules.
+
+Each row carries `id`, `name`, `timezone`, and a flattened per-day
+`windows` list. Pass `id` back as `schedule_id` on
+`POST /campaigns/{id}/launch` or `PATCH /sequences/{id}` to attach the
+schedule before the scheduler starts queueing sends.
+
+The underlying sequencer route is `GET /schedules` (unprefixed inside the
+sequencer app); this dev-API route is a thin org-scoped proxy that
+rewraps the rows into the launch-helper DTO shape and returns a
+`{data: [...]}` envelope for consistency with the rest of the dev API.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `query.include_archived` | `boolean` | no | Include archived schedules in the response. Default False matches the sequencer schedule picker. default `false` |
+| `query.search` | `string \| null` | no | Substring filter on schedule name + description. Case-insensitive on the underlying SQL. |
+
+**Returns** `SchedulesListResponse`: the envelope `{ data: Array<ScheduleListItem>, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+`ScheduleListItem` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `id` | `string` | yes | Schedule UUID; pass back to launch / PATCH endpoints. |
+| `name` | `string` | yes | Display name as set in the Sequencer schedule UI. |
+| `timezone` | `string` | yes | IANA timezone name applied to every window (e.g. 'Europe/Madrid'). |
+| `description` | `string \| null` | no | Optional human description. |
+| `is_archived` | `boolean` | no | Archived schedules are excluded by default — pass `include_archived=true` to include them. default `false` |
+| `windows` | `Array<ScheduleDayWindow>` | no | Per-day send windows for the schedule. Days with no window are omitted. |
+
+**Example**
+
+```ts
+const result = await g8.api.gtmLaunchHelpers.listSchedules();
+```
+
+---
+
+## Referenced types
+
+Named types that appear in the tables above. Full TypeScript definitions: `G8Contract.<Name>` (`import type { G8Contract } from "@graph8/sdk"`).
+
+<a id="type-scheduledaywindow"></a>
+
+### `ScheduleDayWindow`
+
+One day's send window — flattens `{start, end}` from the sequencer. Days that are absent from the underlying config (= no sending) are omitted from the response rather than serialized as nulls — keeps the response compact and matches the picker UI's behaviour.
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `day` | `string` | yes | Lowercase day name: monday \| tuesday \| wednesday \| thursday \| friday \| saturday \| sunday. |
+| `end` | `string` | yes | Window end, 24h HH:MM in `timezone`. |
+| `start` | `string` | yes | Window start, 24h HH:MM in `timezone`. |