@graph8/sdk 0.251.0 → 0.262.0

package/docs/api/snippet.d.ts

@@ -0,0 +1,85 @@
+/* Generated by sdk/js/scripts/generate-agent-docs.ts from developer-contract/openapi.json. Regenerated on every build. */
+
+/**
+ * Types for `g8.api.snippet` (Snippet): 2 operations.
+ *
+ * For reading. In code, import from the package instead:
+ *   import type { ApiInput, ApiOutput, G8Contract } from "@graph8/sdk";
+ *   type In = ApiInput<"get_form_template_snippet_form_get">;
+ *
+ * Reference with examples: snippet.md
+ */
+/* eslint-disable */
+
+/** `g8.api.snippet.<member>` -> the operationId it calls. */
+export interface SnippetMembers {
+  getFormTemplate: "get_form_template_snippet_form_get";
+  getOrgSnippet: "get_org_snippet_snippet_get";
+}
+
+/** Input and output of every `g8.api.snippet` operation, keyed by operationId. */
+export interface SnippetOperations {
+  /**
+   * GET /snippet/form
+   * Get Form Template
+   * tier: read · scope: integrations:read
+   */
+  get_form_template_snippet_form_get: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_dict_;
+  };
+  /**
+   * GET /snippet
+   * Get Org Snippet
+   * tier: read · scope: integrations:read
+   */
+  get_org_snippet_snippet_get: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_SnippetResponse_;
+  };
+}
+
+// 4 schemas referenced above (the same as G8Contract.<Name>).
+
+export interface ApiResponse_SnippetResponse_ {
+  data: SnippetResponse;
+  pagination?: PaginationMeta | null;
+}
+
+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;
+}
+
+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;
+}

package/docs/api/snippet.md

@@ -0,0 +1,106 @@
+<!-- Generated by sdk/js/scripts/generate-agent-docs.ts from developer-contract/openapi.json. Regenerated on every build. -->
+
+# `g8.api.snippet`: Snippet
+
+2 operations (2 read).
+
+1 of these also have a hand-written method (`g8.snippet`), marked **★** below. Prefer the hand-written method when one exists: it unwraps the `data` envelope and takes friendlier arguments. See [../sdk-clients.md](../sdk-clients.md).
+
+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: [snippet.d.ts](snippet.d.ts).
+
+## Operations
+
+| Call | HTTP | Tier | Scope | Summary |
+|---|---|---|---|---|
+| [`getFormTemplate`](#op-getformtemplate) | `GET /api/v1/snippet/form` | read | `integrations:read` | Get Form Template |
+| [`getOrgSnippet`](#op-getorgsnippet) ★ | `GET /api/v1/snippet` | read | `integrations:read` | Get Org Snippet |
+
+---
+
+<a id="op-getformtemplate"></a>
+
+### `g8.api.snippet.getFormTemplate(input?)`
+
+**Get Form Template**
+
+- HTTP: `GET /api/v1/snippet/form`
+- operationId: `get_form_template_snippet_form_get` (also callable as `g8.api.call("get_form_template_snippet_form_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `integrations:read`
+
+Generate a ready-to-embed lead-capture HTML form.
+
+Returns a self-contained HTML snippet with:
+- Name + work email + company fields
+- Client-side validation
+- Tracking hook that calls ``window.graph8.track('form_submitted', ...)``
+  so the submission is captured alongside page views and other events
+
+Drop the returned ``html`` into any page that already loads the tracking
+snippet (see ``GET /snippet``). The form POSTs to your tracking host by
+default, but you can override ``action`` to route submissions to your own
+backend.
+
+**Input**: none.
+
+**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.snippet.getFormTemplate();
+```
+
+---
+
+<a id="op-getorgsnippet"></a>
+
+### `g8.api.snippet.getOrgSnippet(input?)`
+
+**Get Org Snippet**
+
+- HTTP: `GET /api/v1/snippet`
+- operationId: `get_org_snippet_snippet_get` (also callable as `g8.api.call("get_org_snippet_snippet_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `integrations:read`
+- ★ Hand-written: [`g8.snippet.get()`](../sdk-clients.md#g8-snippet-get)
+
+Get the tracking snippet for the authenticated organization.
+
+Returns the write key and pre-built snippets without requiring a
+connected repository. Uses the org's first available tracking stream.
+
+**Input**: none.
+
+**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.snippet.getOrgSnippet();
+```