@graph8/sdk 0.245.0 → 0.260.0

package/docs/api/linkedIn.md

@@ -0,0 +1,289 @@
+<!-- Generated by sdk/js/scripts/generate-agent-docs.ts from developer-contract/openapi.json. Regenerated on every build. -->
+
+# `g8.api.linkedIn`: LinkedIn
+
+5 operations (3 read, 2 external).
+
+No hand-written client covers this area. Call it through `g8.api.linkedIn.*` 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: [linkedIn.d.ts](linkedIn.d.ts).
+
+## Operations
+
+| Call | HTTP | Tier | Scope | Summary |
+|---|---|---|---|---|
+| [`getLinkedinAccountSchedule`](#op-getlinkedinaccountschedule) | `GET /api/v1/linkedin/accounts/{account_id}/schedule` | read | `integrations:read` | Get Linkedin Account Schedule |
+| [`getLinkedinConnectionStatus`](#op-getlinkedinconnectionstatus) | `GET /api/v1/linkedin/connection` | read | `integrations:read` | Get Linkedin Connection Status |
+| [`listLinkedinSenderAccounts`](#op-listlinkedinsenderaccounts) | `GET /api/v1/linkedin/accounts` | read | `integrations:read` | List Linkedin Sender Accounts |
+| [`setLinkedinAccountSchedule`](#op-setlinkedinaccountschedule) | `PUT /api/v1/linkedin/accounts/{account_id}/schedule` | external | `integrations:run` | Set Linkedin Account Schedule |
+| [`syncLinkedinSenderAccounts`](#op-synclinkedinsenderaccounts) | `POST /api/v1/linkedin/accounts/sync` | external | `integrations:run` | Sync Linkedin Sender Accounts |
+
+---
+
+<a id="op-getlinkedinaccountschedule"></a>
+
+### `g8.api.linkedIn.getLinkedinAccountSchedule(input)`
+
+**Get Linkedin Account Schedule**
+
+- HTTP: `GET /api/v1/linkedin/accounts/{account_id}/schedule`
+- operationId: `get_linkedin_account_schedule_linkedin_accounts__account_id__schedule_get` (also callable as `g8.api.call("get_linkedin_account_schedule_linkedin_accounts__account_id__schedule_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `integrations:read`
+
+The account's send window. `schedule: null` means none is set and the default window applies.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.account_id` | `string` | yes | `account_id` from `GET /linkedin/accounts`. |
+
+**Returns** `ApiResponse_LinkedInScheduleState_`: the envelope `{ data: LinkedInScheduleState, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`LinkedInScheduleState` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `configured` | `boolean` | yes |  |
+| `schedule` | `LinkedInSchedule \| null` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.linkedIn.getLinkedinAccountSchedule({ path: { account_id: "id" } });
+```
+
+---
+
+<a id="op-getlinkedinconnectionstatus"></a>
+
+### `g8.api.linkedIn.getLinkedinConnectionStatus(input?)`
+
+**Get Linkedin Connection Status**
+
+- HTTP: `GET /api/v1/linkedin/connection`
+- operationId: `get_linkedin_connection_status_linkedin_connection_get` (also callable as `g8.api.call("get_linkedin_connection_status_linkedin_connection_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `integrations:read`
+
+Whether LinkedIn sending is connected, how many accounts are synced, and whether any needs attention.
+
+Reports that a credential exists - never the credential.
+
+**Input**: none.
+
+**Returns** `ApiResponse_LinkedInConnectionStatus_`: the envelope `{ data: LinkedInConnectionStatus, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`LinkedInConnectionStatus` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `connected` | `boolean` | yes |  |
+| `accounts_count` | `integer` | no | default `0` |
+| `accounts_need_attention` | `boolean` | no | default `false` |
+| `api_key_hint` | `string \| null` | no | Masked prefix only; the secret is never returned. |
+| `last_synced_at` | `string \| null` | no |  |
+| `webhook_registered` | `boolean` | no | default `false` |
+
+**Example**
+
+```ts
+const result = await g8.api.linkedIn.getLinkedinConnectionStatus();
+```
+
+---
+
+<a id="op-listlinkedinsenderaccounts"></a>
+
+### `g8.api.linkedIn.listLinkedinSenderAccounts(input?)`
+
+**List Linkedin Sender Accounts**
+
+- HTTP: `GET /api/v1/linkedin/accounts`
+- operationId: `list_linkedin_sender_accounts_linkedin_accounts_get` (also callable as `g8.api.call("list_linkedin_sender_accounts_linkedin_accounts_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `integrations:read`
+
+Sender accounts with today's invite and message usage against their caps, and the queue waiting.
+
+Empty (not an error) when LinkedIn sending is not enabled for the org or no account has been synced.
+
+**Input**: none.
+
+**Returns** `ApiResponse_LinkedInAccountPlans_`: the envelope `{ data: LinkedInAccountPlans, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`LinkedInAccountPlans` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `accounts` | `Array<LinkedInAccountPlan>` | yes |  |
+| `total_count` | `integer` | yes |  |
+
+**Example**
+
+```ts
+const result = await g8.api.linkedIn.listLinkedinSenderAccounts();
+```
+
+---
+
+<a id="op-setlinkedinaccountschedule"></a>
+
+### `g8.api.linkedIn.setLinkedinAccountSchedule(input)`
+
+**Set Linkedin Account Schedule**
+
+- HTTP: `PUT /api/v1/linkedin/accounts/{account_id}/schedule`
+- operationId: `set_linkedin_account_schedule_linkedin_accounts__account_id__schedule_put` (also callable as `g8.api.call("set_linkedin_account_schedule_linkedin_accounts__account_id__schedule_put", input)`)
+- Tier: `external`: reaches real people (sends email/SMS, places a call, launches a send); the SDK never blindly retries it; confirm with a human first
+- API-key scope: `integrations:run`
+
+Set or replace the account's send window.
+
+Written to the sending provider first, then stored; a provider failure is a
+502 and nothing changes. A timezone change takes effect at the account's
+next local midnight - `effective_from` says exactly when.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.account_id` | `string` | yes | `account_id` from `GET /linkedin/accounts`. |
+| `body` | `LinkedInScheduleRequest` | yes | Request body; fields below. |
+
+Body fields (`LinkedInScheduleRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.days` | `Array<integer>` | yes | ISO weekdays, 1 = Monday ... 7 = Sunday. min items 1 |
+| `body.end_time` | `string` | yes | HH:MM, local to `timezone`. Must be after `start_time`. pattern `^([01]\\d\|2[0-3]):[0-5]\\d$` |
+| `body.start_time` | `string` | yes | HH:MM, local to `timezone`. pattern `^([01]\\d\|2[0-3]):[0-5]\\d$` |
+| `body.timezone` | `string` | yes | IANA timezone, e.g. `Europe/London`. min length 1 |
+
+**Returns** `ApiResponse_LinkedInSchedule_`: the envelope `{ data: LinkedInSchedule, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`LinkedInSchedule` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `account_id` | `string` | yes |  |
+| `days` | `Array<integer>` | yes |  |
+| `end_time` | `string` | yes |  |
+| `start_time` | `string` | yes |  |
+| `timezone` | `string` | yes |  |
+| `effective_from` | `string (date-time) \| null` | no | When this window starts governing sends. Changes are deferred to the account's next local midnight; today keeps the window it started with. |
+
+**Example**
+
+```ts
+// external: reaches real people (sends email/SMS, places a call, launches a send); the SDK never blindly retries it; confirm with a human first.
+const result = await g8.api.linkedIn.setLinkedinAccountSchedule({
+  path: { account_id: "id" },
+  body: {
+    days: [1],
+    end_time: "example",
+    start_time: "example",
+    timezone: "example",
+  },
+});
+```
+
+---
+
+<a id="op-synclinkedinsenderaccounts"></a>
+
+### `g8.api.linkedIn.syncLinkedinSenderAccounts(input?)`
+
+**Sync Linkedin Sender Accounts**
+
+- HTTP: `POST /api/v1/linkedin/accounts/sync`
+- operationId: `sync_linkedin_sender_accounts_linkedin_accounts_sync_post` (also callable as `g8.api.call("sync_linkedin_sender_accounts_linkedin_accounts_sync_post", input)`)
+- Tier: `external`: reaches real people (sends email/SMS, places a call, launches a send); the SDK never blindly retries it; confirm with a human first
+- API-key scope: `integrations:run`
+
+Re-read the org's LinkedIn accounts from the sending provider.
+
+Accounts the provider no longer returns are marked removed and stop sending.
+
+**Input**: none.
+
+**Returns** `ApiResponse_LinkedInAccountSyncResult_`: the envelope `{ data: LinkedInAccountSyncResult, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`LinkedInAccountSyncResult` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `created` | `integer` | yes |  |
+| `synced` | `integer` | yes |  |
+| `updated` | `integer` | yes |  |
+| `removed` | `integer` | no | default `0` |
+| `webhook_registered` | `boolean` | no | default `false` |
+
+**Example**
+
+```ts
+// external: reaches real people (sends email/SMS, places a call, launches a send); the SDK never blindly retries it; confirm with a human first.
+const result = await g8.api.linkedIn.syncLinkedinSenderAccounts();
+```
+
+---
+
+## Referenced types
+
+Named types that appear in the tables above. Full TypeScript definitions: `G8Contract.<Name>` (`import type { G8Contract } from "@graph8/sdk"`).
+
+<a id="type-linkedinaccountplan"></a>
+
+### `LinkedInAccountPlan`
+
+One sender account: identity, pacing, today's usage against its caps, and the live queue.
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `account_id` | `string` | yes | The account id `/linkedin/accounts/{account_id}/schedule` takes. |
+| `day` | `string` | yes | ISO date the usage counts belong to. |
+| `id` | `integer` | yes | Internal id; the sender id a sequence's LinkedIn channel binds to. |
+| `invite_cap` | `integer` | yes |  |
+| `invite_cap_next` | `integer` | yes |  |
+| `invite_cap_with_note` | `integer` | yes |  |
+| `invite_cap_without_note` | `integer` | yes |  |
+| `invites_pending` | `integer` | yes |  |
+| `invites_used` | `integer` | yes |  |
+| `message_cap` | `integer` | yes |  |
+| `message_cap_next` | `integer` | yes |  |
+| `messages_pending` | `integer` | yes |  |
+| `messages_used` | `integer` | yes |  |
+| `status` | `string` | yes |  |
+| `account_tier` | `string \| null` | no |  |
+| `account_timezone` | `string \| null` | no |  |
+| `account_timezone_next` | `string \| null` | no |  |
+| `avatar_url` | `string \| null` | no |  |
+| `cap_source` | `string` | no | default `"live"` |
+| `display_name` | `string \| null` | no |  |
+| `is_paid` | `boolean \| null` | no | null is NOT false: it means the subscription has not been determined. |
+| `plan_frozen_at` | `string \| null` | no |  |
+| `product_statuses` | `Record<string, Record<string, string>> \| null` | no |  |
+| `public_identifier` | `string \| null` | no |  |
+| `timezone_effective_at` | `string \| null` | no |  |
+| `work_window` | `Record<string, unknown> \| null` | no |  |