@graph8/sdk 0.245.0 → 0.260.0

package/docs/api/install.d.ts

@@ -0,0 +1,213 @@
+/* Generated by sdk/js/scripts/generate-agent-docs.ts from developer-contract/openapi.json. Regenerated on every build. */
+
+/**
+ * Types for `g8.api.install` (Install): 6 operations.
+ *
+ * For reading. In code, import from the package instead:
+ *   import type { ApiInput, ApiOutput, G8Contract } from "@graph8/sdk";
+ *   type In = ApiInput<"apply_install_repos__repo_id__install_apply_post">;
+ *
+ * Reference with examples: install.md
+ */
+/* eslint-disable */
+
+/** `g8.api.install.<member>` -> the operationId it calls. */
+export interface InstallMembers {
+  applyInstall: "apply_install_repos__repo_id__install_apply_post";
+  generateInstall: "generate_install_repos__repo_id__install_post";
+  getInstallStatus: "get_install_status_repos__repo_id__install_status_get";
+  getSnippet: "get_snippet_repos__repo_id__snippet_get";
+  listStreams: "list_streams_repos__repo_id__streams_get";
+  rollbackInstall: "rollback_install_repos__repo_id__rollback_post";
+}
+
+/** Input and output of every `g8.api.install` operation, keyed by operationId. */
+export interface InstallOperations {
+  /**
+   * POST /repos/{repo_id}/install/apply
+   * Apply Install
+   * tier: write · scope: integrations:write
+   */
+  apply_install_repos__repo_id__install_apply_post: {
+    input: {
+    path: {
+      /** Repository ID */
+      repo_id: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_ApplyResponse_;
+  };
+  /**
+   * POST /repos/{repo_id}/install
+   * Generate Install
+   * tier: write · scope: integrations:write
+   */
+  generate_install_repos__repo_id__install_post: {
+    input: {
+    path: {
+      /** Repository ID */
+      repo_id: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_PatchSetResponse_;
+  };
+  /**
+   * GET /repos/{repo_id}/install/status
+   * Get Install Status
+   * tier: read · scope: integrations:read
+   */
+  get_install_status_repos__repo_id__install_status_get: {
+    input: {
+    path: {
+      /** Repository ID */
+      repo_id: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_PatchSetResponse_;
+  };
+  /**
+   * GET /repos/{repo_id}/snippet
+   * Get Snippet
+   * tier: read · scope: integrations:read
+   */
+  get_snippet_repos__repo_id__snippet_get: {
+    input: {
+    path: {
+      /** Repository ID */
+      repo_id: string;
+    };
+    query?: {
+      /** Stream ID to use. List available via GET /streams. */
+      stream_id?: string | null;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_SnippetResponse_;
+  };
+  /**
+   * GET /repos/{repo_id}/streams
+   * List Streams
+   * tier: read · scope: integrations:read
+   */
+  list_streams_repos__repo_id__streams_get: {
+    input: {
+    path: {
+      /** Repository ID */
+      repo_id: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_list_StreamInfoResponse__;
+  };
+  /**
+   * POST /repos/{repo_id}/rollback
+   * Rollback Install
+   * tier: write · scope: integrations:write
+   */
+  rollback_install_repos__repo_id__rollback_post: {
+    input: {
+    path: {
+      /** Repository ID */
+      repo_id: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_PatchSetResponse_;
+  };
+}
+
+// 10 schemas referenced above (the same as G8Contract.<Name>).
+
+export interface ApiResponse_ApplyResponse_ {
+  data: ApplyResponse;
+  pagination?: PaginationMeta | null;
+}
+
+export interface ApiResponse_PatchSetResponse_ {
+  data: PatchSetResponse;
+  pagination?: PaginationMeta | null;
+}
+
+export interface ApiResponse_SnippetResponse_ {
+  data: SnippetResponse;
+  pagination?: PaginationMeta | null;
+}
+
+export interface ApiResponse_list_StreamInfoResponse__ {
+  data: Array<StreamInfoResponse>;
+  pagination?: PaginationMeta | null;
+}
+
+export interface ApplyResponse {
+  patch_count: number;
+  status: 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 PatchResponse {
+  action: string;
+  content?: string | null;
+  description: string;
+  diff?: string | null;
+  file_path: string;
+}
+
+export interface PatchSetResponse {
+  applied_at?: string | null;
+  created_at?: string | null;
+  id: string;
+  patches: Array<PatchResponse>;
+  repo_id: string;
+  rolled_back_at?: string | null;
+  status: string;
+}
+
+export interface SnippetResponse {
+  /** Full configuration object for gtm/config.json */
+  config?: Record<string, unknown>;
+  domains?: Array<string>;
+  /** Ready-to-use React component import for @graph8/nextjs */
+  react_snippet: string;
+  /** Vanilla JS script tag for non-React apps */
+  script_tag: string;
+  tracking_host?: string;
+  write_key: string;
+}
+
+export interface StreamInfoResponse {
+  /** Domains associated with this stream */
+  domains?: Array<string>;
+  /** Stream ID used to select this stream */
+  id: string;
+  /** User-friendly stream name (e.g. 'graph8.com', 'heyreach-graph8') */
+  name: string;
+  /** Public write key for this stream */
+  write_key?: string | null;
+}

package/docs/api/install.md

@@ -0,0 +1,317 @@
+<!-- Generated by sdk/js/scripts/generate-agent-docs.ts from developer-contract/openapi.json. Regenerated on every build. -->
+
+# `g8.api.install`: Install
+
+6 operations (3 read, 3 write).
+
+No hand-written client covers this area. Call it through `g8.api.install.*` 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: [install.d.ts](install.d.ts).
+
+## Operations
+
+| Call | HTTP | Tier | Scope | Summary |
+|---|---|---|---|---|
+| [`applyInstall`](#op-applyinstall) | `POST /api/v1/repos/{repo_id}/install/apply` | write | `integrations:write` | Apply Install |
+| [`generateInstall`](#op-generateinstall) | `POST /api/v1/repos/{repo_id}/install` | write | `integrations:write` | Generate Install |
+| [`getInstallStatus`](#op-getinstallstatus) | `GET /api/v1/repos/{repo_id}/install/status` | read | `integrations:read` | Get Install Status |
+| [`getSnippet`](#op-getsnippet) | `GET /api/v1/repos/{repo_id}/snippet` | read | `integrations:read` | Get Snippet |
+| [`listStreams`](#op-liststreams) | `GET /api/v1/repos/{repo_id}/streams` | read | `integrations:read` | List Streams |
+| [`rollbackInstall`](#op-rollbackinstall) | `POST /api/v1/repos/{repo_id}/rollback` | write | `integrations:write` | Rollback Install |
+
+---
+
+<a id="op-applyinstall"></a>
+
+### `g8.api.install.applyInstall(input)`
+
+**Apply Install**
+
+- HTTP: `POST /api/v1/repos/{repo_id}/install/apply`
+- operationId: `apply_install_repos__repo_id__install_apply_post` (also callable as `g8.api.call("apply_install_repos__repo_id__install_apply_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `integrations:write`
+
+Record that the latest patch set has been applied client-side.
+
+This is a bookkeeping call. The server flips ``patch_sets.status`` from
+``PREVIEW`` to ``APPLIED`` so follow-up scans know the install is live;
+no files are written by this endpoint. The actual filesystem write must
+be performed by the caller (typically the `g8` CLI) before calling this.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.repo_id` | `string` | yes | Repository ID |
+
+**Returns** `ApiResponse_ApplyResponse_`: the envelope `{ data: ApplyResponse, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`ApplyResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `patch_count` | `integer` | yes |  |
+| `status` | `string` | yes |  |
+
+**Example**
+
+```ts
+const result = await g8.api.install.applyInstall({ path: { repo_id: "id" } });
+```
+
+---
+
+<a id="op-generateinstall"></a>
+
+### `g8.api.install.generateInstall(input)`
+
+**Generate Install**
+
+- HTTP: `POST /api/v1/repos/{repo_id}/install`
+- operationId: `generate_install_repos__repo_id__install_post` (also callable as `g8.api.call("generate_install_repos__repo_id__install_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `integrations:write`
+
+Generate a patch set describing the changes needed to install the GTM spine.
+
+Server-side only: returns a ``PatchSetResponse`` whose ``patches`` array
+describes the file changes (new files, modifications, snippets to add).
+**The caller is responsible for applying them to the local filesystem** —
+typically the `g8` CLI, but any MCP client can consume the patch array
+directly. Follow up with ``POST /install/apply`` once patches are on disk.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.repo_id` | `string` | yes | Repository ID |
+
+**Returns** `ApiResponse_PatchSetResponse_`: the envelope `{ data: PatchSetResponse, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`PatchSetResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `id` | `string (uuid)` | yes |  |
+| `patches` | `Array<PatchResponse>` | yes |  |
+| `repo_id` | `string (uuid)` | yes |  |
+| `status` | `string` | yes |  |
+| `applied_at` | `string (date-time) \| null` | no |  |
+| `created_at` | `string (date-time) \| null` | no |  |
+| `rolled_back_at` | `string (date-time) \| null` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.install.generateInstall({ path: { repo_id: "id" } });
+```
+
+---
+
+<a id="op-getinstallstatus"></a>
+
+### `g8.api.install.getInstallStatus(input)`
+
+**Get Install Status**
+
+- HTTP: `GET /api/v1/repos/{repo_id}/install/status`
+- operationId: `get_install_status_repos__repo_id__install_status_get` (also callable as `g8.api.call("get_install_status_repos__repo_id__install_status_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `integrations:read`
+
+Get the latest patch set status for a repository.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.repo_id` | `string` | yes | Repository ID |
+
+**Returns** `ApiResponse_PatchSetResponse_`: the envelope `{ data: PatchSetResponse, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`PatchSetResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `id` | `string (uuid)` | yes |  |
+| `patches` | `Array<PatchResponse>` | yes |  |
+| `repo_id` | `string (uuid)` | yes |  |
+| `status` | `string` | yes |  |
+| `applied_at` | `string (date-time) \| null` | no |  |
+| `created_at` | `string (date-time) \| null` | no |  |
+| `rolled_back_at` | `string (date-time) \| null` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.install.getInstallStatus({ path: { repo_id: "id" } });
+```
+
+---
+
+<a id="op-getsnippet"></a>
+
+### `g8.api.install.getSnippet(input)`
+
+**Get Snippet**
+
+- HTTP: `GET /api/v1/repos/{repo_id}/snippet`
+- operationId: `get_snippet_repos__repo_id__snippet_get` (also callable as `g8.api.call("get_snippet_repos__repo_id__snippet_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `integrations:read`
+
+Get the JavaScript tracking snippet for a connected repository.
+
+If the repo already has a write key stored, returns the snippet immediately.
+Otherwise, pass `stream_id` (from GET /streams) to select which stream to use.
+The selected write key is stored on the repo for future lookups.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.repo_id` | `string` | yes | Repository ID |
+| `query.stream_id` | `string \| null` | no | Stream ID to use. List available via GET /streams. |
+
+**Returns** `ApiResponse_SnippetResponse_`: the envelope `{ data: SnippetResponse, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`SnippetResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `react_snippet` | `string` | yes | Ready-to-use React component import for @graph8/nextjs |
+| `script_tag` | `string` | yes | Vanilla JS script tag for non-React apps |
+| `write_key` | `string` | yes |  |
+| `config` | `Record<string, unknown>` | no | Full configuration object for gtm/config.json |
+| `domains` | `Array<string>` | no |  |
+| `tracking_host` | `string` | no | default `"https://t.graph8.com"` |
+
+**Example**
+
+```ts
+const result = await g8.api.install.getSnippet({ path: { repo_id: "id" } });
+```
+
+---
+
+<a id="op-liststreams"></a>
+
+### `g8.api.install.listStreams(input)`
+
+**List Streams**
+
+- HTTP: `GET /api/v1/repos/{repo_id}/streams`
+- operationId: `list_streams_repos__repo_id__streams_get` (also callable as `g8.api.call("list_streams_repos__repo_id__streams_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `integrations:read`
+
+List available tracking streams (sites) for this organization.
+
+Returns each stream's ID, user-friendly name (domain or label),
+associated domains, and write key. The caller should select one
+and pass its `id` to the snippet endpoint.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.repo_id` | `string` | yes | Repository ID |
+
+**Returns** `ApiResponse_list_StreamInfoResponse__`: the envelope `{ data: Array<StreamInfoResponse>, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`StreamInfoResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `id` | `string` | yes | Stream ID used to select this stream |
+| `name` | `string` | yes | User-friendly stream name (e.g. 'graph8.com', 'heyreach-graph8') |
+| `domains` | `Array<string>` | no | Domains associated with this stream |
+| `write_key` | `string \| null` | no | Public write key for this stream |
+
+**Example**
+
+```ts
+const result = await g8.api.install.listStreams({ path: { repo_id: "id" } });
+```
+
+---
+
+<a id="op-rollbackinstall"></a>
+
+### `g8.api.install.rollbackInstall(input)`
+
+**Rollback Install**
+
+- HTTP: `POST /api/v1/repos/{repo_id}/rollback`
+- operationId: `rollback_install_repos__repo_id__rollback_post` (also callable as `g8.api.call("rollback_install_repos__repo_id__rollback_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `integrations:write`
+
+Rollback the last applied patch set.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.repo_id` | `string` | yes | Repository ID |
+
+**Returns** `ApiResponse_PatchSetResponse_`: the envelope `{ data: PatchSetResponse, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`PatchSetResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `id` | `string (uuid)` | yes |  |
+| `patches` | `Array<PatchResponse>` | yes |  |
+| `repo_id` | `string (uuid)` | yes |  |
+| `status` | `string` | yes |  |
+| `applied_at` | `string (date-time) \| null` | no |  |
+| `created_at` | `string (date-time) \| null` | no |  |
+| `rolled_back_at` | `string (date-time) \| null` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.install.rollbackInstall({ path: { repo_id: "id" } });
+```
+
+---
+
+## Referenced types
+
+Named types that appear in the tables above. Full TypeScript definitions: `G8Contract.<Name>` (`import type { G8Contract } from "@graph8/sdk"`).
+
+<a id="type-patchresponse"></a>
+
+### `PatchResponse`
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `action` | `string` | yes |  |
+| `description` | `string` | yes |  |
+| `file_path` | `string` | yes |  |
+| `content` | `string \| null` | no |  |
+| `diff` | `string \| null` | no |  |

package/docs/api/installedApps.d.ts

@@ -0,0 +1,131 @@
+/* Generated by sdk/js/scripts/generate-agent-docs.ts from developer-contract/openapi.json. Regenerated on every build. */
+
+/**
+ * Types for `g8.api.installedApps` (Installed Apps): 4 operations.
+ *
+ * For reading. In code, import from the package instead:
+ *   import type { ApiInput, ApiOutput, G8Contract } from "@graph8/sdk";
+ *   type In = ApiInput<"get_installed_app_installed_apps__app_id__get">;
+ *
+ * Reference with examples: installedApps.md
+ */
+/* eslint-disable */
+
+/** `g8.api.installedApps.<member>` -> the operationId it calls. */
+export interface InstalledAppsMembers {
+  getInstalledApp: "get_installed_app_installed_apps__app_id__get";
+  installApp: "install_app_installed_apps_post";
+  listInstalledApps: "list_installed_apps_installed_apps_get";
+  uninstallApp: "uninstall_app_installed_apps__app_id__delete";
+}
+
+/** Input and output of every `g8.api.installedApps` operation, keyed by operationId. */
+export interface InstalledAppsOperations {
+  /**
+   * GET /installed-apps/{app_id}
+   * Get Installed App
+   * tier: read · scope: apps:read
+   */
+  get_installed_app_installed_apps__app_id__get: {
+    input: {
+    path: {
+      app_id: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_InstalledAppResponse_;
+  };
+  /**
+   * POST /installed-apps
+   * Install App
+   * tier: write · scope: apps:write
+   */
+  install_app_installed_apps_post: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: InstallAppRequest;
+  };
+    output: ApiResponse_InstalledAppResponse_;
+  };
+  /**
+   * GET /installed-apps
+   * List Installed Apps
+   * tier: read · scope: apps:read
+   */
+  list_installed_apps_installed_apps_get: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_list_InstalledAppResponse__;
+  };
+  /**
+   * DELETE /installed-apps/{app_id}
+   * Uninstall App
+   * tier: destructive · scope: apps:delete
+   */
+  uninstall_app_installed_apps__app_id__delete: {
+    input: {
+    path: {
+      app_id: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_InstalledAppResponse_;
+  };
+}
+
+// 5 schemas referenced above (the same as G8Contract.<Name>).
+
+export interface ApiResponse_InstalledAppResponse_ {
+  data: InstalledAppResponse;
+  pagination?: PaginationMeta | null;
+}
+
+export interface ApiResponse_list_InstalledAppResponse__ {
+  data: Array<InstalledAppResponse>;
+  pagination?: PaginationMeta | null;
+}
+
+/** A client workspace consenting to an app. */
+export interface InstallAppRequest {
+  /** The app to install, e.g. `dapp_a1b2c3d4e5f6`. */
+  app_id: string;
+  /** Scopes you grant the app, e.g. `objects:read`. Only scopes the platform enables for apps are accepted; anything else is rejected rather than silently dropped, so a granted scope always means what it says. */
+  scopes?: Array<string>;
+}
+
+/** An app installed in your workspace, and what you granted it. */
+export interface InstalledAppResponse {
+  app_id: string;
+  /** The app's display name, when it is still resolvable. */
+  app_name?: string | null;
+  app_slug?: string | null;
+  client_org_id: string;
+  consented_scopes?: Array<string>;
+  created_at?: string | null;
+  install_id: string;
+  revoked_at?: string | null;
+  /** `pending`, `consented`, `revoked`, `suspended` or `expired`. */
+  status: 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;
+}