@graph8/sdk 0.251.0 → 0.260.0

package/docs/api/leads.d.ts

@@ -0,0 +1,133 @@
+/* Generated by sdk/js/scripts/generate-agent-docs.ts from developer-contract/openapi.json. Regenerated on every build. */
+
+/**
+ * Types for `g8.api.leads` (Leads): 4 operations.
+ *
+ * For reading. In code, import from the package instead:
+ *   import type { ApiInput, ApiOutput, G8Contract } from "@graph8/sdk";
+ *   type In = ApiInput<"generate_lead_content_leads__lead_id__generate_content_post">;
+ *
+ * Reference with examples: leads.md
+ */
+/* eslint-disable */
+
+/** `g8.api.leads.<member>` -> the operationId it calls. */
+export interface LeadsMembers {
+  generateLeadContent: "generate_lead_content_leads__lead_id__generate_content_post";
+  getLeadContentBatch: "get_lead_content_batch_leads_generate_content_batches__batch_id__get";
+  removeLeads: "remove_leads_leads_bulk_delete_post";
+  startLeadContentBatch: "start_lead_content_batch_leads_generate_content_batches_post";
+}
+
+/** Input and output of every `g8.api.leads` operation, keyed by operationId. */
+export interface LeadsOperations {
+  /**
+   * POST /leads/{lead_id}/generate-content
+   * Generate Lead Content
+   * tier: billable · scope: lists:run
+   */
+  generate_lead_content_leads__lead_id__generate_content_post: {
+    input: {
+    path: {
+      /** Lead id. */
+      lead_id: number;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: LeadContentRequest;
+  };
+    output: ApiResponse_LeadContentPayload_;
+  };
+  /**
+   * GET /leads/generate-content/batches/{batch_id}
+   * Get Lead Content Batch
+   * tier: read · scope: lists:read
+   */
+  get_lead_content_batch_leads_generate_content_batches__batch_id__get: {
+    input: {
+    path: {
+      /** Batch id returned when the batch started. */
+      batch_id: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_LeadContentPayload_;
+  };
+  /**
+   * POST /leads/bulk-delete
+   * Remove Leads
+   * tier: destructive · scope: lists:delete
+   */
+  remove_leads_leads_bulk_delete_post: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: LeadRemoveRequest;
+  };
+    output: ApiResponse_LeadContentPayload_;
+  };
+  /**
+   * POST /leads/generate-content/batches
+   * Start Lead Content Batch
+   * tier: billable · scope: lists:run
+   */
+  start_lead_content_batch_leads_generate_content_batches_post: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: LeadContentBatchRequest;
+  };
+    output: ApiResponse_LeadContentPayload_;
+  };
+}
+
+// 6 schemas referenced above (the same as G8Contract.<Name>).
+
+export interface ApiResponse_LeadContentPayload_ {
+  data: LeadContentPayload;
+  pagination?: PaginationMeta | null;
+}
+
+export interface LeadContentBatchRequest {
+  agent_name?: string;
+  instructions?: string | null;
+  lead_ids: Array<number>;
+  studio_campaign_id?: string | null;
+}
+
+/** Generated content, a batch's progress, or a removal count. */
+export type LeadContentPayload = Record<string, unknown>;
+
+export interface LeadContentRequest {
+  /** The writing agent to use. */
+  agent_name?: string;
+  /** Write for this contact instead; the lead id in the path is then ignored. */
+  contact_id?: number | null;
+  /** Custom instructions. Omit to derive them from the lead. */
+  instructions?: string | null;
+  /** A campaign to draw extra context from. */
+  studio_campaign_id?: string | null;
+}
+
+export interface LeadRemoveRequest {
+  /** Leads to remove from their lists. */
+  lead_ids: Array<number>;
+}
+
+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/leads.md

@@ -0,0 +1,180 @@
+<!-- Generated by sdk/js/scripts/generate-agent-docs.ts from developer-contract/openapi.json. Regenerated on every build. -->
+
+# `g8.api.leads`: Leads
+
+4 operations (1 read, 1 destructive, 2 billable).
+
+No hand-written client covers this area. Call it through `g8.api.leads.*` 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: [leads.d.ts](leads.d.ts).
+
+## Operations
+
+| Call | HTTP | Tier | Scope | Summary |
+|---|---|---|---|---|
+| [`generateLeadContent`](#op-generateleadcontent) | `POST /api/v1/leads/{lead_id}/generate-content` | billable | `lists:run` | Generate Lead Content |
+| [`getLeadContentBatch`](#op-getleadcontentbatch) | `GET /api/v1/leads/generate-content/batches/{batch_id}` | read | `lists:read` | Get Lead Content Batch |
+| [`removeLeads`](#op-removeleads) | `POST /api/v1/leads/bulk-delete` | destructive | `lists:delete` | Remove Leads |
+| [`startLeadContentBatch`](#op-startleadcontentbatch) | `POST /api/v1/leads/generate-content/batches` | billable | `lists:run` | Start Lead Content Batch |
+
+---
+
+<a id="op-generateleadcontent"></a>
+
+### `g8.api.leads.generateLeadContent(input)`
+
+**Generate Lead Content**
+
+- HTTP: `POST /api/v1/leads/{lead_id}/generate-content`
+- operationId: `generate_lead_content_leads__lead_id__generate_content_post` (also callable as `g8.api.call("generate_lead_content_leads__lead_id__generate_content_post", input)`)
+- Tier: `billable`: spends credits; the SDK never blindly retries it; confirm cost before bulk use
+- API-key scope: `lists:run`
+
+Write a personalised outreach email for one lead (runs a model; billable). Sends nothing.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.lead_id` | `integer` | yes | Lead id. |
+| `body` | `LeadContentRequest` | yes | Request body; fields below. |
+
+Body fields (`LeadContentRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.agent_name` | `string` | no | The writing agent to use. default `"default-agent"` |
+| `body.contact_id` | `integer \| null` | no | Write for this contact instead; the lead id in the path is then ignored. |
+| `body.instructions` | `string \| null` | no | Custom instructions. Omit to derive them from the lead. |
+| `body.studio_campaign_id` | `string \| null` | no | A campaign to draw extra context from. |
+
+**Returns** `ApiResponse_LeadContentPayload_`: the envelope `{ data: LeadContentPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+// billable: spends credits; the SDK never blindly retries it; confirm cost before bulk use.
+const result = await g8.api.leads.generateLeadContent({ path: { lead_id: 123 }, body: {} });
+```
+
+---
+
+<a id="op-getleadcontentbatch"></a>
+
+### `g8.api.leads.getLeadContentBatch(input)`
+
+**Get Lead Content Batch**
+
+- HTTP: `GET /api/v1/leads/generate-content/batches/{batch_id}`
+- operationId: `get_lead_content_batch_leads_generate_content_batches__batch_id__get` (also callable as `g8.api.call("get_lead_content_batch_leads_generate_content_batches__batch_id__get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `lists:read`
+
+A batch's progress, with each finished lead's content.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.batch_id` | `string` | yes | Batch id returned when the batch started. |
+
+**Returns** `ApiResponse_LeadContentPayload_`: the envelope `{ data: LeadContentPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.leads.getLeadContentBatch({ path: { batch_id: "id" } });
+```
+
+---
+
+<a id="op-removeleads"></a>
+
+### `g8.api.leads.removeLeads(input)`
+
+**Remove Leads**
+
+- HTTP: `POST /api/v1/leads/bulk-delete`
+- operationId: `remove_leads_leads_bulk_delete_post` (also callable as `g8.api.call("remove_leads_leads_bulk_delete_post", input)`)
+- Tier: `destructive`: deletes or archives data; confirm with a human before calling
+- API-key scope: `lists:delete`
+
+Remove leads from their lists. Returns how many were removed.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `LeadRemoveRequest` | yes | Request body; fields below. |
+
+Body fields (`LeadRemoveRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.lead_ids` | `Array<integer>` | yes | Leads to remove from their lists. min items 1 |
+
+**Returns** `ApiResponse_LeadContentPayload_`: the envelope `{ data: LeadContentPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+// destructive: deletes or archives data; confirm with a human before calling.
+const result = await g8.api.leads.removeLeads({ body: { lead_ids: [123] } });
+```
+
+---
+
+<a id="op-startleadcontentbatch"></a>
+
+### `g8.api.leads.startLeadContentBatch(input)`
+
+**Start Lead Content Batch**
+
+- HTTP: `POST /api/v1/leads/generate-content/batches`
+- operationId: `start_lead_content_batch_leads_generate_content_batches_post` (also callable as `g8.api.call("start_lead_content_batch_leads_generate_content_batches_post", input)`)
+- Tier: `billable`: spends credits; the SDK never blindly retries it; confirm cost before bulk use
+- API-key scope: `lists:run`
+
+Write outreach for up to 100 leads in the background (one model call each; billable).
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `LeadContentBatchRequest` | yes | Request body; fields below. |
+
+Body fields (`LeadContentBatchRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.lead_ids` | `Array<integer>` | yes | min items 1, max items 100 |
+| `body.agent_name` | `string` | no | default `"default-agent"` |
+| `body.instructions` | `string \| null` | no |  |
+| `body.studio_campaign_id` | `string \| null` | no |  |
+
+**Returns** `ApiResponse_LeadContentPayload_`: the envelope `{ data: LeadContentPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+// billable: spends credits; the SDK never blindly retries it; confirm cost before bulk use.
+const result = await g8.api.leads.startLeadContentBatch({ body: { lead_ids: [123] } });
+```

package/docs/api/library.d.ts

@@ -0,0 +1,217 @@
+/* Generated by sdk/js/scripts/generate-agent-docs.ts from developer-contract/openapi.json. Regenerated on every build. */
+
+/**
+ * Types for `g8.api.library` (Library): 9 operations.
+ *
+ * For reading. In code, import from the package instead:
+ *   import type { ApiInput, ApiOutput, G8Contract } from "@graph8/sdk";
+ *   type In = ApiInput<"backfill_library_case_studies_library_case_studies_backfill_post">;
+ *
+ * Reference with examples: library.md
+ */
+/* eslint-disable */
+
+/** `g8.api.library.<member>` -> the operationId it calls. */
+export interface LibraryMembers {
+  backfillLibraryCaseStudies: "backfill_library_case_studies_library_case_studies_backfill_post";
+  deleteLibraryDocument: "delete_library_document_library_documents__doc_id__delete";
+  downloadLibraryDocument: "download_library_document_library_documents__doc_id__download_get";
+  getLibraryDocument: "get_library_document_library_documents__doc_id__get";
+  reextractAllLibraryDocuments: "reextract_all_library_documents_library_reextract_all_post";
+  reextractLibraryDocument: "reextract_library_document_library_documents__doc_id__reextract_post";
+  refreshLibraryDocument: "refresh_library_document_library_documents__doc_id__refresh_post";
+  restoreLibraryDocument: "restore_library_document_library_documents__doc_id__restore_post";
+  updateLibraryDocument: "update_library_document_library_documents__doc_id__put";
+}
+
+/** Input and output of every `g8.api.library` operation, keyed by operationId. */
+export interface LibraryOperations {
+  /**
+   * POST /library/case-studies/backfill
+   * Backfill Library Case Studies
+   * tier: billable · scope: knowledge:run
+   */
+  backfill_library_case_studies_library_case_studies_backfill_post: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body?: BackfillCaseStudiesRequest;
+  };
+    output: ApiResponse_StudioContentPayload_;
+  };
+  /**
+   * DELETE /library/documents/{doc_id}
+   * Delete Library Document
+   * tier: destructive · scope: knowledge:delete
+   */
+  delete_library_document_library_documents__doc_id__delete: {
+    input: {
+    path: {
+      /** Library document id. */
+      doc_id: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_StudioContentPayload_;
+  };
+  /**
+   * GET /library/documents/{doc_id}/download
+   * Download Library Document
+   * tier: read · scope: knowledge:read
+   */
+  download_library_document_library_documents__doc_id__download_get: {
+    input: {
+    path: {
+      /** Library document id. */
+      doc_id: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: void;
+  };
+  /**
+   * GET /library/documents/{doc_id}
+   * Get Library Document
+   * tier: read · scope: knowledge:read
+   */
+  get_library_document_library_documents__doc_id__get: {
+    input: {
+    path: {
+      /** Library document id. */
+      doc_id: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_StudioContentPayload_;
+  };
+  /**
+   * POST /library/reextract-all
+   * Reextract All Library Documents
+   * tier: write · scope: knowledge:write
+   */
+  reextract_all_library_documents_library_reextract_all_post: {
+    input: {
+    query?: {
+      /** Only this folder. Omit for every PDF/DOCX. */
+      folder_path?: string | null;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_StudioContentPayload_;
+  };
+  /**
+   * POST /library/documents/{doc_id}/reextract
+   * Reextract Library Document
+   * tier: write · scope: knowledge:write
+   */
+  reextract_library_document_library_documents__doc_id__reextract_post: {
+    input: {
+    path: {
+      /** Library document id. */
+      doc_id: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_StudioContentPayload_;
+  };
+  /**
+   * POST /library/documents/{doc_id}/refresh
+   * Refresh Library Document
+   * tier: write · scope: knowledge:write
+   */
+  refresh_library_document_library_documents__doc_id__refresh_post: {
+    input: {
+    path: {
+      /** Library document id. */
+      doc_id: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_StudioContentPayload_;
+  };
+  /**
+   * POST /library/documents/{doc_id}/restore
+   * Restore Library Document
+   * tier: write · scope: knowledge:write
+   */
+  restore_library_document_library_documents__doc_id__restore_post: {
+    input: {
+    path: {
+      /** Library document id. */
+      doc_id: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_StudioContentPayload_;
+  };
+  /**
+   * PUT /library/documents/{doc_id}
+   * Update Library Document
+   * tier: write · scope: knowledge:write
+   */
+  update_library_document_library_documents__doc_id__put: {
+    input: {
+    path: {
+      /** Library document id. */
+      doc_id: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: UpdateLibraryDocumentRequest;
+  };
+    output: ApiResponse_StudioContentPayload_;
+  };
+}
+
+// 5 schemas referenced above (the same as G8Contract.<Name>).
+
+export interface ApiResponse_StudioContentPayload_ {
+  data: StudioContentPayload;
+  pagination?: PaginationMeta | null;
+}
+
+/** Extract structured metadata from case-study documents. SPENDS CREDIT. */
+export interface BackfillCaseStudiesRequest {
+  /** Re-extract documents already processed. */
+  force?: boolean;
+}
+
+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;
+}
+
+/** One Studio object, open-shaped. See the module docstring. */
+export type StudioContentPayload = Record<string, unknown>;
+
+/** Partial update. New `content` is re-embedded. */
+export interface UpdateLibraryDocumentRequest {
+  content?: string | null;
+  display_name?: string | null;
+  folder_path?: string | null;
+  meta_data?: Record<string, unknown> | null;
+}