@graph8/sdk 0.245.0 → 0.260.0

package/docs/api/library.md

@@ -0,0 +1,338 @@
+<!-- Generated by sdk/js/scripts/generate-agent-docs.ts from developer-contract/openapi.json. Regenerated on every build. -->
+
+# `g8.api.library`: Library
+
+9 operations (2 read, 5 write, 1 destructive, 1 billable).
+
+No hand-written client covers this area. Call it through `g8.api.library.*` 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: [library.d.ts](library.d.ts).
+
+## Operations
+
+| Call | HTTP | Tier | Scope | Summary |
+|---|---|---|---|---|
+| [`backfillLibraryCaseStudies`](#op-backfilllibrarycasestudies) | `POST /api/v1/library/case-studies/backfill` | billable | `knowledge:run` | Backfill Library Case Studies |
+| [`deleteLibraryDocument`](#op-deletelibrarydocument) | `DELETE /api/v1/library/documents/{doc_id}` | destructive | `knowledge:delete` | Delete Library Document |
+| [`downloadLibraryDocument`](#op-downloadlibrarydocument) | `GET /api/v1/library/documents/{doc_id}/download` | read | `knowledge:read` | Download Library Document |
+| [`getLibraryDocument`](#op-getlibrarydocument) | `GET /api/v1/library/documents/{doc_id}` | read | `knowledge:read` | Get Library Document |
+| [`reextractAllLibraryDocuments`](#op-reextractalllibrarydocuments) | `POST /api/v1/library/reextract-all` | write | `knowledge:write` | Reextract All Library Documents |
+| [`reextractLibraryDocument`](#op-reextractlibrarydocument) | `POST /api/v1/library/documents/{doc_id}/reextract` | write | `knowledge:write` | Reextract Library Document |
+| [`refreshLibraryDocument`](#op-refreshlibrarydocument) | `POST /api/v1/library/documents/{doc_id}/refresh` | write | `knowledge:write` | Refresh Library Document |
+| [`restoreLibraryDocument`](#op-restorelibrarydocument) | `POST /api/v1/library/documents/{doc_id}/restore` | write | `knowledge:write` | Restore Library Document |
+| [`updateLibraryDocument`](#op-updatelibrarydocument) | `PUT /api/v1/library/documents/{doc_id}` | write | `knowledge:write` | Update Library Document |
+
+---
+
+<a id="op-backfilllibrarycasestudies"></a>
+
+### `g8.api.library.backfillLibraryCaseStudies(input?)`
+
+**Backfill Library Case Studies**
+
+- HTTP: `POST /api/v1/library/case-studies/backfill`
+- operationId: `backfill_library_case_studies_library_case_studies_backfill_post` (also callable as `g8.api.call("backfill_library_case_studies_library_case_studies_backfill_post", input)`)
+- Tier: `billable`: spends credits; the SDK never blindly retries it; confirm cost before bulk use
+- API-key scope: `knowledge:run`
+
+Extract company, industry and results from every case study. SPENDS CREDIT.
+
+A model reads each document in the case-study folders, in the background.
+Without `force`, documents already processed are skipped.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `BackfillCaseStudiesRequest` | no | Request body; fields below. |
+
+Body fields (`BackfillCaseStudiesRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.force` | `boolean` | no | Re-extract documents already processed. default `false` |
+
+**Returns** `ApiResponse_StudioContentPayload_`: the envelope `{ data: StudioContentPayload, ... }`. `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.library.backfillLibraryCaseStudies();
+```
+
+---
+
+<a id="op-deletelibrarydocument"></a>
+
+### `g8.api.library.deleteLibraryDocument(input)`
+
+**Delete Library Document**
+
+- HTTP: `DELETE /api/v1/library/documents/{doc_id}`
+- operationId: `delete_library_document_library_documents__doc_id__delete` (also callable as `g8.api.call("delete_library_document_library_documents__doc_id__delete", input)`)
+- Tier: `destructive`: deletes or archives data; confirm with a human before calling
+- API-key scope: `knowledge:delete`
+
+Soft-delete a document. It leaves retrieval; `POST .../restore` brings it back.
+
+Spends nothing.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.doc_id` | `string` | yes | Library document id. |
+
+**Returns** `ApiResponse_StudioContentPayload_`: the envelope `{ data: StudioContentPayload, ... }`. `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.library.deleteLibraryDocument({ path: { doc_id: "id" } });
+```
+
+---
+
+<a id="op-downloadlibrarydocument"></a>
+
+### `g8.api.library.downloadLibraryDocument(input)`
+
+**Download Library Document**
+
+- HTTP: `GET /api/v1/library/documents/{doc_id}/download`
+- operationId: `download_library_document_library_documents__doc_id__download_get` (also callable as `g8.api.call("download_library_document_library_documents__doc_id__download_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `knowledge:read`
+
+The document's original file, as uploaded. FREE.
+
+NOT wrapped in the JSON envelope: the body is the file itself, with its own
+`Content-Type` and a `Content-Disposition: attachment` filename.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.doc_id` | `string` | yes | Library document id. |
+
+**Returns**: no JSON body is declared for the success response.
+
+**Example**
+
+```ts
+const result = await g8.api.library.downloadLibraryDocument({ path: { doc_id: "id" } });
+```
+
+---
+
+<a id="op-getlibrarydocument"></a>
+
+### `g8.api.library.getLibraryDocument(input)`
+
+**Get Library Document**
+
+- HTTP: `GET /api/v1/library/documents/{doc_id}`
+- operationId: `get_library_document_library_documents__doc_id__get` (also callable as `g8.api.call("get_library_document_library_documents__doc_id__get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `knowledge:read`
+
+One document with its extracted text. FREE.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.doc_id` | `string` | yes | Library document id. |
+
+**Returns** `ApiResponse_StudioContentPayload_`: the envelope `{ data: StudioContentPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.library.getLibraryDocument({ path: { doc_id: "id" } });
+```
+
+---
+
+<a id="op-reextractalllibrarydocuments"></a>
+
+### `g8.api.library.reextractAllLibraryDocuments(input?)`
+
+**Reextract All Library Documents**
+
+- HTTP: `POST /api/v1/library/reextract-all`
+- operationId: `reextract_all_library_documents_library_reextract_all_post` (also callable as `g8.api.call("reextract_all_library_documents_library_reextract_all_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `knowledge:write`
+
+Re-read and re-embed every stored PDF/DOCX. FREE - no model runs.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `query.folder_path` | `string \| null` | no | Only this folder. Omit for every PDF/DOCX. |
+
+**Returns** `ApiResponse_StudioContentPayload_`: the envelope `{ data: StudioContentPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.library.reextractAllLibraryDocuments();
+```
+
+---
+
+<a id="op-reextractlibrarydocument"></a>
+
+### `g8.api.library.reextractLibraryDocument(input)`
+
+**Reextract Library Document**
+
+- HTTP: `POST /api/v1/library/documents/{doc_id}/reextract`
+- operationId: `reextract_library_document_library_documents__doc_id__reextract_post` (also callable as `g8.api.call("reextract_library_document_library_documents__doc_id__reextract_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `knowledge:write`
+
+Re-read the text out of a stored PDF/DOCX and re-embed it. FREE - no model runs.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.doc_id` | `string` | yes | Library document id. |
+
+**Returns** `ApiResponse_StudioContentPayload_`: the envelope `{ data: StudioContentPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.library.reextractLibraryDocument({ path: { doc_id: "id" } });
+```
+
+---
+
+<a id="op-refreshlibrarydocument"></a>
+
+### `g8.api.library.refreshLibraryDocument(input)`
+
+**Refresh Library Document**
+
+- HTTP: `POST /api/v1/library/documents/{doc_id}/refresh`
+- operationId: `refresh_library_document_library_documents__doc_id__refresh_post` (also callable as `g8.api.call("refresh_library_document_library_documents__doc_id__refresh_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `knowledge:write`
+
+Re-scrape a document that came from a web page, and re-embed it. FREE.
+
+Only for documents whose `source` is `scrape` (400 otherwise).
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.doc_id` | `string` | yes | Library document id. |
+
+**Returns** `ApiResponse_StudioContentPayload_`: the envelope `{ data: StudioContentPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.library.refreshLibraryDocument({ path: { doc_id: "id" } });
+```
+
+---
+
+<a id="op-restorelibrarydocument"></a>
+
+### `g8.api.library.restoreLibraryDocument(input)`
+
+**Restore Library Document**
+
+- HTTP: `POST /api/v1/library/documents/{doc_id}/restore`
+- operationId: `restore_library_document_library_documents__doc_id__restore_post` (also callable as `g8.api.call("restore_library_document_library_documents__doc_id__restore_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `knowledge:write`
+
+Undo a delete. FREE.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.doc_id` | `string` | yes | Library document id. |
+
+**Returns** `ApiResponse_StudioContentPayload_`: the envelope `{ data: StudioContentPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.library.restoreLibraryDocument({ path: { doc_id: "id" } });
+```
+
+---
+
+<a id="op-updatelibrarydocument"></a>
+
+### `g8.api.library.updateLibraryDocument(input)`
+
+**Update Library Document**
+
+- HTTP: `PUT /api/v1/library/documents/{doc_id}`
+- operationId: `update_library_document_library_documents__doc_id__put` (also callable as `g8.api.call("update_library_document_library_documents__doc_id__put", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `knowledge:write`
+
+Update a document's name, folder, metadata or text. FREE. New text is re-embedded.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.doc_id` | `string` | yes | Library document id. |
+| `body` | `UpdateLibraryDocumentRequest` | yes | Request body; fields below. |
+
+Body fields (`UpdateLibraryDocumentRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.content` | `string \| null` | no |  |
+| `body.display_name` | `string \| null` | no |  |
+| `body.folder_path` | `string \| null` | no |  |
+| `body.meta_data` | `Record<string, unknown> \| null` | no |  |
+
+**Returns** `ApiResponse_StudioContentPayload_`: the envelope `{ data: StudioContentPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.library.updateLibraryDocument({ path: { doc_id: "id" }, body: {} });
+```

package/docs/api/linkedIn.d.ts

@@ -0,0 +1,227 @@
+/* Generated by sdk/js/scripts/generate-agent-docs.ts from developer-contract/openapi.json. Regenerated on every build. */
+
+/**
+ * Types for `g8.api.linkedIn` (LinkedIn): 5 operations.
+ *
+ * For reading. In code, import from the package instead:
+ *   import type { ApiInput, ApiOutput, G8Contract } from "@graph8/sdk";
+ *   type In = ApiInput<"get_linkedin_account_schedule_linkedin_accounts__account_id__schedule_get">;
+ *
+ * Reference with examples: linkedIn.md
+ */
+/* eslint-disable */
+
+/** `g8.api.linkedIn.<member>` -> the operationId it calls. */
+export interface LinkedInMembers {
+  getLinkedinAccountSchedule: "get_linkedin_account_schedule_linkedin_accounts__account_id__schedule_get";
+  getLinkedinConnectionStatus: "get_linkedin_connection_status_linkedin_connection_get";
+  listLinkedinSenderAccounts: "list_linkedin_sender_accounts_linkedin_accounts_get";
+  setLinkedinAccountSchedule: "set_linkedin_account_schedule_linkedin_accounts__account_id__schedule_put";
+  syncLinkedinSenderAccounts: "sync_linkedin_sender_accounts_linkedin_accounts_sync_post";
+}
+
+/** Input and output of every `g8.api.linkedIn` operation, keyed by operationId. */
+export interface LinkedInOperations {
+  /**
+   * GET /linkedin/accounts/{account_id}/schedule
+   * Get Linkedin Account Schedule
+   * tier: read · scope: integrations:read
+   */
+  get_linkedin_account_schedule_linkedin_accounts__account_id__schedule_get: {
+    input: {
+    path: {
+      /** `account_id` from `GET /linkedin/accounts`. */
+      account_id: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_LinkedInScheduleState_;
+  };
+  /**
+   * GET /linkedin/connection
+   * Get Linkedin Connection Status
+   * tier: read · scope: integrations:read
+   */
+  get_linkedin_connection_status_linkedin_connection_get: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_LinkedInConnectionStatus_;
+  };
+  /**
+   * GET /linkedin/accounts
+   * List Linkedin Sender Accounts
+   * tier: read · scope: integrations:read
+   */
+  list_linkedin_sender_accounts_linkedin_accounts_get: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_LinkedInAccountPlans_;
+  };
+  /**
+   * PUT /linkedin/accounts/{account_id}/schedule
+   * Set Linkedin Account Schedule
+   * tier: external · scope: integrations:run
+   */
+  set_linkedin_account_schedule_linkedin_accounts__account_id__schedule_put: {
+    input: {
+    path: {
+      /** `account_id` from `GET /linkedin/accounts`. */
+      account_id: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: LinkedInScheduleRequest;
+  };
+    output: ApiResponse_LinkedInSchedule_;
+  };
+  /**
+   * POST /linkedin/accounts/sync
+   * Sync Linkedin Sender Accounts
+   * tier: external · scope: integrations:run
+   */
+  sync_linkedin_sender_accounts_linkedin_accounts_sync_post: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_LinkedInAccountSyncResult_;
+  };
+}
+
+// 13 schemas referenced above (the same as G8Contract.<Name>).
+
+export interface ApiResponse_LinkedInAccountPlans_ {
+  data: LinkedInAccountPlans;
+  pagination?: PaginationMeta | null;
+}
+
+export interface ApiResponse_LinkedInAccountSyncResult_ {
+  data: LinkedInAccountSyncResult;
+  pagination?: PaginationMeta | null;
+}
+
+export interface ApiResponse_LinkedInConnectionStatus_ {
+  data: LinkedInConnectionStatus;
+  pagination?: PaginationMeta | null;
+}
+
+export interface ApiResponse_LinkedInScheduleState_ {
+  data: LinkedInScheduleState;
+  pagination?: PaginationMeta | null;
+}
+
+export interface ApiResponse_LinkedInSchedule_ {
+  data: LinkedInSchedule;
+  pagination?: PaginationMeta | null;
+}
+
+/** One sender account: identity, pacing, today's usage against its caps, and the live queue. */
+export interface LinkedInAccountPlan {
+  /** The account id `/linkedin/accounts/{account_id}/schedule` takes. */
+  account_id: string;
+  account_tier?: string | null;
+  account_timezone?: string | null;
+  account_timezone_next?: string | null;
+  avatar_url?: string | null;
+  cap_source?: string;
+  /** ISO date the usage counts belong to. */
+  day: string;
+  display_name?: string | null;
+  /** Internal id; the sender id a sequence's LinkedIn channel binds to. */
+  id: number;
+  invite_cap: number;
+  invite_cap_next: number;
+  invite_cap_with_note: number;
+  invite_cap_without_note: number;
+  invites_pending: number;
+  invites_used: number;
+  /** null is NOT false: it means the subscription has not been determined. */
+  is_paid?: boolean | null;
+  message_cap: number;
+  message_cap_next: number;
+  messages_pending: number;
+  messages_used: number;
+  plan_frozen_at?: string | null;
+  product_statuses?: Record<string, Record<string, string>> | null;
+  public_identifier?: string | null;
+  status: string;
+  timezone_effective_at?: string | null;
+  work_window?: Record<string, unknown> | null;
+}
+
+export interface LinkedInAccountPlans {
+  accounts: Array<LinkedInAccountPlan>;
+  total_count: number;
+}
+
+/** What an account sync changed. */
+export interface LinkedInAccountSyncResult {
+  created: number;
+  removed?: number;
+  synced: number;
+  updated: number;
+  webhook_registered?: boolean;
+}
+
+/** Whether the org's LinkedIn sending connection exists and is healthy. Never the credential itself. */
+export interface LinkedInConnectionStatus {
+  accounts_count?: number;
+  accounts_need_attention?: boolean;
+  /** Masked prefix only; the secret is never returned. */
+  api_key_hint?: string | null;
+  connected: boolean;
+  last_synced_at?: string | null;
+  webhook_registered?: boolean;
+}
+
+/** An account's send window. */
+export interface LinkedInSchedule {
+  account_id: string;
+  days: Array<number>;
+  /** When this window starts governing sends. Changes are deferred to the account's next local midnight; today keeps the window it started with. */
+  effective_from?: string | null;
+  end_time: string;
+  start_time: string;
+  timezone: string;
+}
+
+/** When an account may send: days, a daily window and its timezone. */
+export interface LinkedInScheduleRequest {
+  /** ISO weekdays, 1 = Monday ... 7 = Sunday. */
+  days: Array<number>;
+  /** HH:MM, local to `timezone`. Must be after `start_time`. */
+  end_time: string;
+  /** HH:MM, local to `timezone`. */
+  start_time: string;
+  /** IANA timezone, e.g. `Europe/London`. */
+  timezone: string;
+}
+
+/** The account's send window, or `schedule: null` when none is set (the default window applies). */
+export interface LinkedInScheduleState {
+  configured: boolean;
+  schedule?: LinkedInSchedule | 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;
+}