@graph8/sdk 0.251.0 → 0.260.0

package/docs/api/profile.md

@@ -0,0 +1,540 @@
+<!-- Generated by sdk/js/scripts/generate-agent-docs.ts from developer-contract/openapi.json. Regenerated on every build. -->
+
+# `g8.api.profile`: Profile
+
+14 operations (8 read, 4 write, 1 destructive, 1 external).
+
+No hand-written client covers this area. Call it through `g8.api.profile.*` 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: [profile.d.ts](profile.d.ts).
+
+## Operations
+
+| Call | HTTP | Tier | Scope | Summary |
+|---|---|---|---|---|
+| [`getAvailableMcpTools`](#op-getavailablemcptools) | `GET /api/v1/profile/mcp/tools` | read | `account:read` | Get Available Mcp Tools |
+| [`getDealAutomations`](#op-getdealautomations) | `GET /api/v1/profile/deal-automations` | read | `account:read` | Get Deal Automations |
+| [`getMcpConnectionStatus`](#op-getmcpconnectionstatus) | `GET /api/v1/profile/mcp/status` | read | `account:read` | Get Mcp Connection Status |
+| [`getMcpUsageStats`](#op-getmcpusagestats) | `GET /api/v1/profile/mcp/usage` | read | `account:read` | Get Mcp Usage Stats |
+| [`getNotificationPreferences`](#op-getnotificationpreferences) | `GET /api/v1/profile/notification-preferences` | read | `account:read` | Get Notification Preferences |
+| [`getPipelineDealHints`](#op-getpipelinedealhints) | `GET /api/v1/profile/deal-automations/pipeline-hints` | read | `account:read` | Get Pipeline Deal Hints |
+| [`getPreferences`](#op-getpreferences) | `GET /api/v1/profile/preferences` | read | `account:read` | Get Preferences |
+| [`listMcpSessions`](#op-listmcpsessions) | `GET /api/v1/profile/mcp/sessions` | read | `account:read` | List Mcp Sessions |
+| [`revokeMcpSession`](#op-revokemcpsession) | `DELETE /api/v1/profile/mcp/sessions/{session_id}` | destructive | `account:delete` | Revoke Mcp Session |
+| [`syncMyCalendarNow`](#op-syncmycalendarnow) | `POST /api/v1/profile/deal-automations/sync-now` | external | `integrations:run` | Sync My Calendar Now |
+| [`updateDealAutomations`](#op-updatedealautomations) | `PUT /api/v1/profile/deal-automations` | write | `account:write` | Update Deal Automations |
+| [`updateNotificationPreference`](#op-updatenotificationpreference) | `PUT /api/v1/profile/notification-preferences` | write | `account:write` | Update Notification Preference |
+| [`updatePreferences`](#op-updatepreferences) | `PUT /api/v1/profile/preferences` | write | `account:write` | Update Preferences |
+| [`uploadProfileAvatar`](#op-uploadprofileavatar) | `POST /api/v1/profile/avatar` | write | `account:write` | Upload Profile Avatar |
+
+---
+
+<a id="op-getavailablemcptools"></a>
+
+### `g8.api.profile.getAvailableMcpTools(input?)`
+
+**Get Available Mcp Tools**
+
+- HTTP: `GET /api/v1/profile/mcp/tools`
+- operationId: `get_available_mcp_tools_profile_mcp_tools_get` (also callable as `g8.api.call("get_available_mcp_tools_profile_mcp_tools_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `account:read`
+
+The MCP tool groups and toolboxes a person can choose between.
+
+`groups[].value` and `toolboxes[].id` are the ids `PUT /profile/preferences`
+accepts as `mcp_tool_group`. The catalog is the same for every caller, so
+any key may read it.
+
+**Input**: none.
+
+**Returns** `ApiResponse_OrgPayload_`: the envelope `{ data: OrgPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.profile.getAvailableMcpTools();
+```
+
+---
+
+<a id="op-getdealautomations"></a>
+
+### `g8.api.profile.getDealAutomations(input?)`
+
+**Get Deal Automations**
+
+- HTTP: `GET /api/v1/profile/deal-automations`
+- operationId: `get_deal_automations_profile_deal_automations_get` (also callable as `g8.api.call("get_deal_automations_profile_deal_automations_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `account:read`
+
+What this person's calendar is allowed to do to their pipeline.
+
+Per pipeline: which meeting titles count, whether a scope of work is
+written, whether a quote is drafted, and whether the deal advances or
+closes on its own.
+
+**Input**: none.
+
+**Returns** `ApiResponse_OrgPayload_`: the envelope `{ data: OrgPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.profile.getDealAutomations();
+```
+
+---
+
+<a id="op-getmcpconnectionstatus"></a>
+
+### `g8.api.profile.getMcpConnectionStatus(input?)`
+
+**Get Mcp Connection Status**
+
+- HTTP: `GET /api/v1/profile/mcp/status`
+- operationId: `get_mcp_connection_status_profile_mcp_status_get` (also callable as `g8.api.call("get_mcp_connection_status_profile_mcp_status_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `account:read`
+
+Whether the key-holder has a live MCP connection, and when it was last used.
+
+**Input**: none.
+
+**Returns** `ApiResponse_OrgPayload_`: the envelope `{ data: OrgPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.profile.getMcpConnectionStatus();
+```
+
+---
+
+<a id="op-getmcpusagestats"></a>
+
+### `g8.api.profile.getMcpUsageStats(input?)`
+
+**Get Mcp Usage Stats**
+
+- HTTP: `GET /api/v1/profile/mcp/usage`
+- operationId: `get_mcp_usage_stats_profile_mcp_usage_get` (also callable as `g8.api.call("get_mcp_usage_stats_profile_mcp_usage_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `account:read`
+
+How much the key-holder has used MCP: totals, this month, and the top tools.
+
+**Input**: none.
+
+**Returns** `ApiResponse_OrgPayload_`: the envelope `{ data: OrgPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.profile.getMcpUsageStats();
+```
+
+---
+
+<a id="op-getnotificationpreferences"></a>
+
+### `g8.api.profile.getNotificationPreferences(input?)`
+
+**Get Notification Preferences**
+
+- HTTP: `GET /api/v1/profile/notification-preferences`
+- operationId: `get_notification_preferences_profile_notification_preferences_get` (also callable as `g8.api.call("get_notification_preferences_profile_notification_preferences_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `account:read`
+
+Which events reach this person, and through which channel.
+
+Open-shaped: the event catalogue and the delivery channels both grow with
+the product, and a dropped entry would read as "you are not subscribed"
+rather than "we did not tell you".
+
+**Input**: none.
+
+**Returns** `ApiResponse_OrgPayload_`: the envelope `{ data: OrgPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.profile.getNotificationPreferences();
+```
+
+---
+
+<a id="op-getpipelinedealhints"></a>
+
+### `g8.api.profile.getPipelineDealHints(input?)`
+
+**Get Pipeline Deal Hints**
+
+- HTTP: `GET /api/v1/profile/deal-automations/pipeline-hints`
+- operationId: `get_pipeline_deal_hints_profile_deal_automations_pipeline_hints_get` (also callable as `g8.api.call("get_pipeline_deal_hints_profile_deal_automations_pipeline_hints_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `account:read`
+
+Suggested settings per pipeline, derived from how it is actually used.
+
+Advisory only - reading this changes nothing. It is what makes the
+configuration above a choice rather than a guess.
+
+**Input**: none.
+
+**Returns** `ApiResponse_OrgPayload_`: the envelope `{ data: OrgPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.profile.getPipelineDealHints();
+```
+
+---
+
+<a id="op-getpreferences"></a>
+
+### `g8.api.profile.getPreferences(input?)`
+
+**Get Preferences**
+
+- HTTP: `GET /api/v1/profile/preferences`
+- operationId: `get_preferences_profile_preferences_get` (also callable as `g8.api.call("get_preferences_profile_preferences_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `account:read`
+
+The key-holder's own preferences: theme, locale, timezone, defaults.
+
+Creates an empty preferences row on first read rather than 404ing, which
+is the app's behaviour - so the shape is stable from the very first call.
+
+**Input**: none.
+
+**Returns** `ApiResponse_OrgPayload_`: the envelope `{ data: OrgPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.profile.getPreferences();
+```
+
+---
+
+<a id="op-listmcpsessions"></a>
+
+### `g8.api.profile.listMcpSessions(input?)`
+
+**List Mcp Sessions**
+
+- HTTP: `GET /api/v1/profile/mcp/sessions`
+- operationId: `list_mcp_sessions_profile_mcp_sessions_get` (also callable as `g8.api.call("list_mcp_sessions_profile_mcp_sessions_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `account:read`
+
+The key-holder's active MCP sessions - one per connected client.
+
+**Input**: none.
+
+**Returns** `ApiResponse_OrgPayload_`: the envelope `{ data: OrgPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.profile.listMcpSessions();
+```
+
+---
+
+<a id="op-revokemcpsession"></a>
+
+### `g8.api.profile.revokeMcpSession(input)`
+
+**Revoke Mcp Session**
+
+- HTTP: `DELETE /api/v1/profile/mcp/sessions/{session_id}`
+- operationId: `revoke_mcp_session_profile_mcp_sessions__session_id__delete` (also callable as `g8.api.call("revoke_mcp_session_profile_mcp_sessions__session_id__delete", input)`)
+- Tier: `destructive`: deletes or archives data; confirm with a human before calling
+- API-key scope: `account:delete`
+
+Disconnect one MCP client. It must re-authorise to connect again.
+
+Only ever the key-holder's own session: the app matches the row on the
+caller's user id, so another person's session id is a 404.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.session_id` | `string` | yes | MCP session id, from `GET /profile/mcp/sessions`. |
+
+**Returns** `ApiResponse_OrgPayload_`: the envelope `{ data: OrgPayload, ... }`. `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.profile.revokeMcpSession({ path: { session_id: "id" } });
+```
+
+---
+
+<a id="op-syncmycalendarnow"></a>
+
+### `g8.api.profile.syncMyCalendarNow(input?)`
+
+**Sync My Calendar Now**
+
+- HTTP: `POST /api/v1/profile/deal-automations/sync-now`
+- operationId: `sync_my_calendar_now_profile_deal_automations_sync_now_post` (also callable as `g8.api.call("sync_my_calendar_now_profile_deal_automations_sync_now_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`
+
+Run the calendar sync immediately instead of waiting for the interval.
+
+Reaches the key-holder's connected CALENDAR PROVIDER, so it gates on
+`integrations:run` rather than plain write. It can create deals and draft
+quotes as a consequence - whatever the configuration above allows - so it
+is worth calling once with `dry_run` on before relying on it.
+
+**Input**: none.
+
+**Returns** `ApiResponse_OrgPayload_`: the envelope `{ data: OrgPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**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.profile.syncMyCalendarNow();
+```
+
+---
+
+<a id="op-updatedealautomations"></a>
+
+### `g8.api.profile.updateDealAutomations(input)`
+
+**Update Deal Automations**
+
+- HTTP: `PUT /api/v1/profile/deal-automations`
+- operationId: `update_deal_automations_profile_deal_automations_put` (also callable as `g8.api.call("update_deal_automations_profile_deal_automations_put", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `account:write`
+
+Configure the calendar-driven deal automations.
+
+Read `dry_run` before turning anything on: with it set, the automation
+reports what it WOULD do and creates nothing. `auto_close_deal_on_acceptance`
+is the one to be most careful with - it moves a deal to closed without a
+human in the loop.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `ProfileDealAutomationsUpdateRequest` | yes | Request body; fields below. |
+
+Body fields (`ProfileDealAutomationsUpdateRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.pipelines` | `Record<string, ProfilePipelineAutomationBlock> \| null` | no | Rules per pipeline id. Only the pipelines sent are changed; the others, and other people's rules, are never touched. |
+| `body.sync_interval_minutes` | `10 \| 30 \| 60 \| 180 \| 360 \| 1440 \| null` | no | How often the calendar is pulled, in minutes. |
+
+**Returns** `ApiResponse_OrgPayload_`: the envelope `{ data: OrgPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.profile.updateDealAutomations({ body: {} });
+```
+
+---
+
+<a id="op-updatenotificationpreference"></a>
+
+### `g8.api.profile.updateNotificationPreference(input)`
+
+**Update Notification Preference**
+
+- HTTP: `PUT /api/v1/profile/notification-preferences`
+- operationId: `update_notification_preference_profile_notification_preferences_put` (also callable as `g8.api.call("update_notification_preference_profile_notification_preferences_put", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `account:write`
+
+Update ONE event type, named by `event_type`.
+
+Singular on purpose, matching the app: a caller that sent the whole map
+would race with the person changing a different toggle in the browser and
+silently revert it.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `ProfileNotificationPreferenceUpdateRequest` | yes | Request body; fields below. |
+
+Body fields (`ProfileNotificationPreferenceUpdateRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.event_type` | `string` | yes | The event to configure, as listed by `GET /profile/notification-preferences`. An unknown one is refused with the valid list. |
+| `body.bridge_email` | `boolean \| null` | no |  |
+| `body.bridge_imessage` | `boolean \| null` | no |  |
+| `body.bridge_roam` | `boolean \| null` | no |  |
+| `body.bridge_slack` | `boolean \| null` | no |  |
+| `body.bridge_whatsapp` | `boolean \| null` | no |  |
+| `body.copilot_bridge` | `boolean \| null` | no |  |
+| `body.copilot_proactive` | `boolean \| null` | no |  |
+| `body.enabled` | `boolean \| null` | no |  |
+| `body.hot_override` | `boolean \| null` | no |  |
+| `body.routing` | `"conversation" \| "notify_only" \| "off" \| null` | no |  |
+| `body.urgency` | `"interrupt_now" \| "fold_into_brief" \| null` | no |  |
+
+**Returns** `ApiResponse_OrgPayload_`: the envelope `{ data: OrgPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.profile.updateNotificationPreference({ body: { event_type: "example" } });
+```
+
+---
+
+<a id="op-updatepreferences"></a>
+
+### `g8.api.profile.updatePreferences(input)`
+
+**Update Preferences**
+
+- HTTP: `PUT /api/v1/profile/preferences`
+- operationId: `update_preferences_profile_preferences_put` (also callable as `g8.api.call("update_preferences_profile_preferences_put", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `account:write`
+
+Update preferences. Omitted fields are LEFT ALONE, not cleared.
+
+`whatsapp_number` is validated against the messaging bridge before
+anything is written: claiming a number another person in the organisation
+already registered is refused rather than silently stealing their route.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `ProfilePreferencesUpdateRequest` | yes | Request body; fields below. |
+
+Body fields (`ProfilePreferencesUpdateRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.default_view` | `string \| null` | no |  |
+| `body.locale` | `string \| null` | no |  |
+| `body.mcp_default_client` | `string \| null` | no |  |
+| `body.mcp_tool_group` | `string \| null` | no | An id from `GET /profile/mcp/tools` (a `groups[].value` or a `toolboxes[].id`). Anything else is a 422 that lists the valid ids. |
+| `body.mcp_widgets_enabled` | `boolean \| null` | no |  |
+| `body.notifications_email` | `boolean \| null` | no |  |
+| `body.notifications_in_app` | `boolean \| null` | no |  |
+| `body.notifications_slack` | `boolean \| null` | no |  |
+| `body.theme` | `string \| null` | no |  |
+| `body.timezone` | `string \| null` | no |  |
+| `body.whatsapp_number` | `string \| null` | no |  |
+
+**Returns** `ApiResponse_OrgPayload_`: the envelope `{ data: OrgPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.profile.updatePreferences({ body: {} });
+```
+
+---
+
+<a id="op-uploadprofileavatar"></a>
+
+### `g8.api.profile.uploadProfileAvatar(input?)`
+
+**Upload Profile Avatar**
+
+- HTTP: `POST /api/v1/profile/avatar`
+- operationId: `upload_profile_avatar_profile_avatar_post` (also callable as `g8.api.call("upload_profile_avatar_profile_avatar_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `account:write`
+
+Set the key-holder's profile picture. Multipart, like the app.
+
+Stored, then written to the identity provider. `synced_to_propelauth` is
+false when that second write failed: the picture is saved and the next
+identity sync picks it up, so it is a soft warning rather than an error.
+A file of the wrong type or over 5 MB is a 400.
+
+**Input**: none.
+
+**Returns** `ApiResponse_OrgPayload_`: the envelope `{ data: OrgPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.profile.uploadProfileAvatar();
+```
+
+---
+
+## Referenced types
+
+Named types that appear in the tables above. Full TypeScript definitions: `G8Contract.<Name>` (`import type { G8Contract } from "@graph8/sdk"`).
+
+<a id="type-profilepipelineautomationblock"></a>
+
+### `ProfilePipelineAutomationBlock`
+
+Mirrors `user_profile.PipelineAutomationBlock`. `dry_run` is the safety switch: with it on, the automation reports what it WOULD do and creates nothing.
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `auto_advance_deal_on_quote_send` | `boolean` | no | default `false` |
+| `auto_close_deal_on_acceptance` | `boolean` | no | default `false` |
+| `auto_draft_quote` | `boolean` | no | default `false` |
+| `dry_run` | `boolean` | no | default `false` |
+| `enabled` | `boolean` | no | default `false` |
+| `generate_scope_of_work` | `boolean` | no | default `false` |
+| `title_keywords` | `Array<string>` | no | Meeting-title keywords that count. At most 10; each is trimmed to 100 characters and duplicates are dropped case-insensitively. max items 10 |