@graph8/sdk 0.251.0 → 0.260.0

package/docs/api/publicSignals.md

@@ -0,0 +1,71 @@
+<!-- Generated by sdk/js/scripts/generate-agent-docs.ts from developer-contract/openapi.json. Regenerated on every build. -->
+
+# `g8.api.publicSignals`: Public - Signals
+
+1 operation (1 read).
+
+1 of these also have a hand-written method (`g8.signals`), 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: [publicSignals.d.ts](publicSignals.d.ts).
+
+## Operations
+
+| Call | HTTP | Tier | Scope | Summary |
+|---|---|---|---|---|
+| [`publicSignalsCompany`](#op-publicsignalscompany) ★ | `GET /api/v1/public/signals/company` | read | `intent:read` | Public Signals Company |
+
+---
+
+<a id="op-publicsignalscompany"></a>
+
+### `g8.api.publicSignals.publicSignalsCompany(input)`
+
+**Public Signals Company**
+
+- HTTP: `GET /api/v1/public/signals/company`
+- operationId: `public_signals_company_public_signals_company_get` (also callable as `g8.api.call("public_signals_company_public_signals_company_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `intent:read`
+- ★ Hand-written: [`g8.signals.company()`](../sdk-clients.md#g8-signals-company)
+
+Get intent signals for a company domain.
+
+Analyzes visitor behavior from the org's ClickHouse events to determine
+buying intent. Used by g8.signals.company().
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `query.domain` | `string` | yes |  |
+| `headers.X-Write-Key` | `string \| null` | no |  |
+
+**Returns** `ApiResponse_IntentSignalsResponse_`: the envelope `{ data: IntentSignalsResponse, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`IntentSignalsResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `domain` | `string` | yes |  |
+| `intent` | `string` | no | default `"low"` |
+| `last_seen` | `string \| null` | no |  |
+| `score` | `integer` | no | default `0` |
+| `signals` | `Array<string>` | no | default `[]` |
+
+**Example**
+
+```ts
+const result = await g8.api.publicSignals.publicSignalsCompany({ query: { domain: "acme.com" } });
+```

package/docs/api/publicVisitors.d.ts

@@ -0,0 +1,97 @@
+/* Generated by sdk/js/scripts/generate-agent-docs.ts from developer-contract/openapi.json. Regenerated on every build. */
+
+/**
+ * Types for `g8.api.publicVisitors` (Public - Visitors): 2 operations.
+ *
+ * For reading. In code, import from the package instead:
+ *   import type { ApiInput, ApiOutput, G8Contract } from "@graph8/sdk";
+ *   type In = ApiInput<"public_visitor_company_public_visitors_company_get">;
+ *
+ * Reference with examples: publicVisitors.md
+ */
+/* eslint-disable */
+
+/** `g8.api.publicVisitors.<member>` -> the operationId it calls. */
+export interface PublicVisitorsMembers {
+  publicVisitorCompany: "public_visitor_company_public_visitors_company_get";
+  publicVisitorScore: "public_visitor_score_public_visitors_score_get";
+}
+
+/** Input and output of every `g8.api.publicVisitors` operation, keyed by operationId. */
+export interface PublicVisitorsOperations {
+  /**
+   * GET /public/visitors/company
+   * Public Visitor Company
+   * tier: read · scope: intent:read
+   */
+  public_visitor_company_public_visitors_company_get: {
+    input: {
+    query?: {
+      visitor_ip?: string | null;
+    };
+    headers?: {
+      "X-Write-Key"?: string | null;
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_VisitorCompanyResponse_;
+  };
+  /**
+   * GET /public/visitors/score
+   * Public Visitor Score
+   * tier: read · scope: intent:read
+   */
+  public_visitor_score_public_visitors_score_get: {
+    input: {
+    query?: {
+      visitor_ip?: string | null;
+    };
+    headers?: {
+      "X-Write-Key"?: string | null;
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_VisitorScoreResponse_;
+  };
+}
+
+// 5 schemas referenced above (the same as G8Contract.<Name>).
+
+export interface ApiResponse_VisitorCompanyResponse_ {
+  data: VisitorCompanyResponse;
+  pagination?: PaginationMeta | null;
+}
+
+export interface ApiResponse_VisitorScoreResponse_ {
+  data: VisitorScoreResponse;
+  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 VisitorCompanyResponse {
+  city?: string | null;
+  company_domain?: string | null;
+  company_name?: string | null;
+  confidence?: number;
+  country?: string | null;
+  employee_count?: string | null;
+  industry?: string | null;
+}
+
+export interface VisitorScoreResponse {
+  engagement?: number;
+  intent?: string;
+  signals?: Array<string>;
+}

package/docs/api/publicVisitors.md

@@ -0,0 +1,118 @@
+<!-- Generated by sdk/js/scripts/generate-agent-docs.ts from developer-contract/openapi.json. Regenerated on every build. -->
+
+# `g8.api.publicVisitors`: Public - Visitors
+
+2 operations (2 read).
+
+2 of these also have a hand-written method (`g8.visitors`), 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: [publicVisitors.d.ts](publicVisitors.d.ts).
+
+## Operations
+
+| Call | HTTP | Tier | Scope | Summary |
+|---|---|---|---|---|
+| [`publicVisitorCompany`](#op-publicvisitorcompany) ★ | `GET /api/v1/public/visitors/company` | read | `intent:read` | Public Visitor Company |
+| [`publicVisitorScore`](#op-publicvisitorscore) ★ | `GET /api/v1/public/visitors/score` | read | `intent:read` | Public Visitor Score |
+
+---
+
+<a id="op-publicvisitorcompany"></a>
+
+### `g8.api.publicVisitors.publicVisitorCompany(input?)`
+
+**Public Visitor Company**
+
+- HTTP: `GET /api/v1/public/visitors/company`
+- operationId: `public_visitor_company_public_visitors_company_get` (also callable as `g8.api.call("public_visitor_company_public_visitors_company_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `intent:read`
+- ★ Hand-written: [`g8.visitors.identify()`](../sdk-clients.md#g8-visitors-identify)
+
+Resolve the current visitor's IP address to a company.
+
+Uses the ip_2_company ClickHouse table to identify which company
+the visitor belongs to based on their IP address. Used by g8.visitors.identify().
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `query.visitor_ip` | `string (ipvanyaddress) \| null` | no |  |
+| `headers.X-Write-Key` | `string \| null` | no |  |
+
+**Returns** `ApiResponse_VisitorCompanyResponse_`: the envelope `{ data: VisitorCompanyResponse, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`VisitorCompanyResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `city` | `string \| null` | no |  |
+| `company_domain` | `string \| null` | no |  |
+| `company_name` | `string \| null` | no |  |
+| `confidence` | `number` | no | default `0` |
+| `country` | `string \| null` | no |  |
+| `employee_count` | `string \| null` | no |  |
+| `industry` | `string \| null` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.publicVisitors.publicVisitorCompany();
+```
+
+---
+
+<a id="op-publicvisitorscore"></a>
+
+### `g8.api.publicVisitors.publicVisitorScore(input?)`
+
+**Public Visitor Score**
+
+- HTTP: `GET /api/v1/public/visitors/score`
+- operationId: `public_visitor_score_public_visitors_score_get` (also callable as `g8.api.call("public_visitor_score_public_visitors_score_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `intent:read`
+- ★ Hand-written: [`g8.visitors.score()`](../sdk-clients.md#g8-visitors-score)
+
+Get engagement score for the current visitor.
+
+Scores are based on page views, time on site, and actions taken.
+Used by g8.visitors.score().
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `query.visitor_ip` | `string (ipvanyaddress) \| null` | no |  |
+| `headers.X-Write-Key` | `string \| null` | no |  |
+
+**Returns** `ApiResponse_VisitorScoreResponse_`: the envelope `{ data: VisitorScoreResponse, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`VisitorScoreResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `engagement` | `integer` | no | default `0` |
+| `intent` | `string` | no | default `"low"` |
+| `signals` | `Array<string>` | no | default `[]` |
+
+**Example**
+
+```ts
+const result = await g8.api.publicVisitors.publicVisitorScore();
+```