@graph8/sdk 0.251.0 → 0.260.0

package/docs/api/installedApps.md

@@ -0,0 +1,241 @@
+<!-- Generated by sdk/js/scripts/generate-agent-docs.ts from developer-contract/openapi.json. Regenerated on every build. -->
+
+# `g8.api.installedApps`: Installed Apps
+
+4 operations (2 read, 1 write, 1 destructive).
+
+No hand-written client covers this area. Call it through `g8.api.installedApps.*` 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: [installedApps.d.ts](installedApps.d.ts).
+
+## Operations
+
+| Call | HTTP | Tier | Scope | Summary |
+|---|---|---|---|---|
+| [`getInstalledApp`](#op-getinstalledapp) | `GET /api/v1/installed-apps/{app_id}` | read | `apps:read` | Get Installed App |
+| [`installApp`](#op-installapp) | `POST /api/v1/installed-apps` | write | `apps:write` | Install App |
+| [`listInstalledApps`](#op-listinstalledapps) | `GET /api/v1/installed-apps` | read | `apps:read` | List Installed Apps |
+| [`uninstallApp`](#op-uninstallapp) | `DELETE /api/v1/installed-apps/{app_id}` | destructive | `apps:delete` | Uninstall App |
+
+---
+
+<a id="op-getinstalledapp"></a>
+
+### `g8.api.installedApps.getInstalledApp(input)`
+
+**Get Installed App**
+
+- HTTP: `GET /api/v1/installed-apps/{app_id}`
+- operationId: `get_installed_app_installed_apps__app_id__get` (also callable as `g8.api.call("get_installed_app_installed_apps__app_id__get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `apps:read`
+- Lifecycle: `preview` (may not be enabled for every org yet)
+
+PREVIEW. This endpoint is deployed but gated: it returns 404 unless the hosted app platform is enabled for your organization. It is published here so the contract describes the whole surface, not so it can be called today.
+
+One app's installation in your workspace, and the scopes you granted it.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.app_id` | `string` | yes |  |
+
+**Returns** `ApiResponse_InstalledAppResponse_`: the envelope `{ data: InstalledAppResponse, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`InstalledAppResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `app_id` | `string` | yes |  |
+| `client_org_id` | `string` | yes |  |
+| `install_id` | `string` | yes |  |
+| `status` | `string` | yes | `pending`, `consented`, `revoked`, `suspended` or `expired`. |
+| `app_name` | `string \| null` | no | The app's display name, when it is still resolvable. |
+| `app_slug` | `string \| null` | no |  |
+| `consented_scopes` | `Array<string>` | no |  |
+| `created_at` | `string (date-time) \| null` | no |  |
+| `revoked_at` | `string (date-time) \| null` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.installedApps.getInstalledApp({ path: { app_id: "id" } });
+```
+
+---
+
+<a id="op-installapp"></a>
+
+### `g8.api.installedApps.installApp(input)`
+
+**Install App**
+
+- HTTP: `POST /api/v1/installed-apps`
+- operationId: `install_app_installed_apps_post` (also callable as `g8.api.call("install_app_installed_apps_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `apps:write`
+- Lifecycle: `preview` (may not be enabled for every org yet)
+
+PREVIEW. This endpoint is deployed but gated: it returns 404 unless the hosted app platform is enabled for your organization. It is published here so the contract describes the whole surface, not so it can be called today.
+
+Install an app into your workspace and grant it scopes.
+
+Consent is recorded immediately — there is no pending step in the beta, and a
+`pending` status that nothing ever advanced would be a trap. Re-installing an
+app you already have UPDATES the grant in place, which is how you change
+scopes; there is exactly one install row per (app, workspace).
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `InstallAppRequest` | yes | Request body; fields below. |
+
+Body fields (`InstallAppRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.app_id` | `string` | yes | The app to install, e.g. `dapp_a1b2c3d4e5f6`. |
+| `body.scopes` | `Array<string>` | no | Scopes you grant the app, e.g. `objects:read`. Only scopes the platform enables for apps are accepted; anything else is rejected rather than silently dropped, so a granted scope always means what it says. max items 32 |
+
+**Returns** `ApiResponse_InstalledAppResponse_`: the envelope `{ data: InstalledAppResponse, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`InstalledAppResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `app_id` | `string` | yes |  |
+| `client_org_id` | `string` | yes |  |
+| `install_id` | `string` | yes |  |
+| `status` | `string` | yes | `pending`, `consented`, `revoked`, `suspended` or `expired`. |
+| `app_name` | `string \| null` | no | The app's display name, when it is still resolvable. |
+| `app_slug` | `string \| null` | no |  |
+| `consented_scopes` | `Array<string>` | no |  |
+| `created_at` | `string (date-time) \| null` | no |  |
+| `revoked_at` | `string (date-time) \| null` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.installedApps.installApp({ body: { app_id: "id" } });
+```
+
+---
+
+<a id="op-listinstalledapps"></a>
+
+### `g8.api.installedApps.listInstalledApps(input?)`
+
+**List Installed Apps**
+
+- HTTP: `GET /api/v1/installed-apps`
+- operationId: `list_installed_apps_installed_apps_get` (also callable as `g8.api.call("list_installed_apps_installed_apps_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `apps:read`
+- Lifecycle: `preview` (may not be enabled for every org yet)
+
+PREVIEW. This endpoint is deployed but gated: it returns 404 unless the hosted app platform is enabled for your organization. It is published here so the contract describes the whole surface, not so it can be called today.
+
+List the apps installed in your workspace, including revoked ones.
+
+Revoked installs are included on purpose: "we used to have this app and
+turned it off" is a different answer from "we never had it", and only one of
+them explains why the app's data is still here.
+
+**Input**: none.
+
+**Returns** `ApiResponse_list_InstalledAppResponse__`: the envelope `{ data: Array<InstalledAppResponse>, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`InstalledAppResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `app_id` | `string` | yes |  |
+| `client_org_id` | `string` | yes |  |
+| `install_id` | `string` | yes |  |
+| `status` | `string` | yes | `pending`, `consented`, `revoked`, `suspended` or `expired`. |
+| `app_name` | `string \| null` | no | The app's display name, when it is still resolvable. |
+| `app_slug` | `string \| null` | no |  |
+| `consented_scopes` | `Array<string>` | no |  |
+| `created_at` | `string (date-time) \| null` | no |  |
+| `revoked_at` | `string (date-time) \| null` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.installedApps.listInstalledApps();
+```
+
+---
+
+<a id="op-uninstallapp"></a>
+
+### `g8.api.installedApps.uninstallApp(input)`
+
+**Uninstall App**
+
+- HTTP: `DELETE /api/v1/installed-apps/{app_id}`
+- operationId: `uninstall_app_installed_apps__app_id__delete` (also callable as `g8.api.call("uninstall_app_installed_apps__app_id__delete", input)`)
+- Tier: `destructive`: deletes or archives data; confirm with a human before calling
+- API-key scope: `apps:delete`
+- Lifecycle: `preview` (may not be enabled for every org yet)
+
+PREVIEW. This endpoint is deployed but gated: it returns 404 unless the hosted app platform is enabled for your organization. It is published here so the contract describes the whole surface, not so it can be called today.
+
+Revoke an app's access to your workspace.
+
+Takes effect on the app's NEXT request, not when its tokens expire: the
+verifier re-resolves consent live, and the M6-1d clamp reads only `consented`
+rows.
+
+Your data is NOT deleted. D13 requires a workspace to keep records an app
+authored after it is uninstalled — they are yours, and you can still read
+them through your own API key.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.app_id` | `string` | yes |  |
+
+**Returns** `ApiResponse_InstalledAppResponse_`: the envelope `{ data: InstalledAppResponse, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`InstalledAppResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `app_id` | `string` | yes |  |
+| `client_org_id` | `string` | yes |  |
+| `install_id` | `string` | yes |  |
+| `status` | `string` | yes | `pending`, `consented`, `revoked`, `suspended` or `expired`. |
+| `app_name` | `string \| null` | no | The app's display name, when it is still resolvable. |
+| `app_slug` | `string \| null` | no |  |
+| `consented_scopes` | `Array<string>` | no |  |
+| `created_at` | `string (date-time) \| null` | no |  |
+| `revoked_at` | `string (date-time) \| null` | no |  |
+
+**Example**
+
+```ts
+// destructive: deletes or archives data; confirm with a human before calling.
+const result = await g8.api.installedApps.uninstallApp({ path: { app_id: "id" } });
+```

package/docs/api/integrationStatus.d.ts

@@ -0,0 +1,142 @@
+/* Generated by sdk/js/scripts/generate-agent-docs.ts from developer-contract/openapi.json. Regenerated on every build. */
+
+/**
+ * Types for `g8.api.integrationStatus` (Integration Status): 6 operations.
+ *
+ * For reading. In code, import from the package instead:
+ *   import type { ApiInput, ApiOutput, G8Contract } from "@graph8/sdk";
+ *   type In = ApiInput<"get_google_workspace_status_integrations_google_workspace_get">;
+ *
+ * Reference with examples: integrationStatus.md
+ */
+/* eslint-disable */
+
+/** `g8.api.integrationStatus.<member>` -> the operationId it calls. */
+export interface IntegrationStatusMembers {
+  getGoogleWorkspaceStatus: "get_google_workspace_status_integrations_google_workspace_get";
+  getRoamStatus: "get_roam_status_integrations_roam_status_get";
+  getSlackStatus: "get_slack_status_integrations_slack_status_get";
+  listGoogleDriveFolderFiles: "list_google_drive_folder_files_integrations_google_workspace_folders__folder_id__files_get";
+  listGoogleDriveFolders: "list_google_drive_folders_integrations_google_workspace_folders_get";
+  testGoogleWorkspaceConnection: "test_google_workspace_connection_integrations_google_workspace_test_post";
+}
+
+/** Input and output of every `g8.api.integrationStatus` operation, keyed by operationId. */
+export interface IntegrationStatusOperations {
+  /**
+   * GET /integrations/google-workspace
+   * Get Google Workspace Status
+   * tier: read · scope: integrations:read
+   */
+  get_google_workspace_status_integrations_google_workspace_get: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_IntegrationStatusPayload_;
+  };
+  /**
+   * GET /integrations/roam/status
+   * Get Roam Status
+   * tier: read · scope: integrations:read
+   */
+  get_roam_status_integrations_roam_status_get: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_IntegrationStatusPayload_;
+  };
+  /**
+   * GET /integrations/slack/status
+   * Get Slack Status
+   * tier: read · scope: integrations:read
+   */
+  get_slack_status_integrations_slack_status_get: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_IntegrationStatusPayload_;
+  };
+  /**
+   * GET /integrations/google-workspace/folders/{folder_id}/files
+   * List Google Drive Folder Files
+   * tier: read · scope: integrations:read
+   */
+  list_google_drive_folder_files_integrations_google_workspace_folders__folder_id__files_get: {
+    input: {
+    path: {
+      /** Drive folder id. */
+      folder_id: string;
+    };
+    query?: {
+      page_size?: number;
+      page_token?: string | null;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_IntegrationStatusPayload_;
+  };
+  /**
+   * GET /integrations/google-workspace/folders
+   * List Google Drive Folders
+   * tier: read · scope: integrations:read
+   */
+  list_google_drive_folders_integrations_google_workspace_folders_get: {
+    input: {
+    query?: {
+      /** Parent folder id; `root` for the top level. */
+      parent_id?: string;
+      view?: "my_drive" | "shared_drives" | "shared_with_me";
+      page_size?: number;
+      page_token?: string | null;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_IntegrationStatusPayload_;
+  };
+  /**
+   * POST /integrations/google-workspace/test
+   * Test Google Workspace Connection
+   * tier: read · scope: integrations:read
+   */
+  test_google_workspace_connection_integrations_google_workspace_test_post: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_IntegrationStatusPayload_;
+  };
+}
+
+// 3 schemas referenced above (the same as G8Contract.<Name>).
+
+export interface ApiResponse_IntegrationStatusPayload_ {
+  data: IntegrationStatusPayload;
+  pagination?: PaginationMeta | null;
+}
+
+/** An integration's connection state, a test result, or a folder listing. */
+export type IntegrationStatusPayload = Record<string, unknown>;
+
+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/integrationStatus.md

@@ -0,0 +1,205 @@
+<!-- Generated by sdk/js/scripts/generate-agent-docs.ts from developer-contract/openapi.json. Regenerated on every build. -->
+
+# `g8.api.integrationStatus`: Integration Status
+
+6 operations (6 read).
+
+No hand-written client covers this area. Call it through `g8.api.integrationStatus.*` 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: [integrationStatus.d.ts](integrationStatus.d.ts).
+
+## Operations
+
+| Call | HTTP | Tier | Scope | Summary |
+|---|---|---|---|---|
+| [`getGoogleWorkspaceStatus`](#op-getgoogleworkspacestatus) | `GET /api/v1/integrations/google-workspace` | read | `integrations:read` | Get Google Workspace Status |
+| [`getRoamStatus`](#op-getroamstatus) | `GET /api/v1/integrations/roam/status` | read | `integrations:read` | Get Roam Status |
+| [`getSlackStatus`](#op-getslackstatus) | `GET /api/v1/integrations/slack/status` | read | `integrations:read` | Get Slack Status |
+| [`listGoogleDriveFolderFiles`](#op-listgoogledrivefolderfiles) | `GET /api/v1/integrations/google-workspace/folders/{folder_id}/files` | read | `integrations:read` | List Google Drive Folder Files |
+| [`listGoogleDriveFolders`](#op-listgoogledrivefolders) | `GET /api/v1/integrations/google-workspace/folders` | read | `integrations:read` | List Google Drive Folders |
+| [`testGoogleWorkspaceConnection`](#op-testgoogleworkspaceconnection) | `POST /api/v1/integrations/google-workspace/test` | read | `integrations:read` | Test Google Workspace Connection |
+
+---
+
+<a id="op-getgoogleworkspacestatus"></a>
+
+### `g8.api.integrationStatus.getGoogleWorkspaceStatus(input?)`
+
+**Get Google Workspace Status**
+
+- HTTP: `GET /api/v1/integrations/google-workspace`
+- operationId: `get_google_workspace_status_integrations_google_workspace_get` (also callable as `g8.api.call("get_google_workspace_status_integrations_google_workspace_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `integrations:read`
+
+Whether Google Workspace is connected, and what it is configured to do.
+
+**Input**: none.
+
+**Returns** `ApiResponse_IntegrationStatusPayload_`: the envelope `{ data: IntegrationStatusPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.integrationStatus.getGoogleWorkspaceStatus();
+```
+
+---
+
+<a id="op-getroamstatus"></a>
+
+### `g8.api.integrationStatus.getRoamStatus(input?)`
+
+**Get Roam Status**
+
+- HTTP: `GET /api/v1/integrations/roam/status`
+- operationId: `get_roam_status_integrations_roam_status_get` (also callable as `g8.api.call("get_roam_status_integrations_roam_status_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `integrations:read`
+
+Whether Roam is connected for notifications and the copilot bridge.
+
+**Input**: none.
+
+**Returns** `ApiResponse_IntegrationStatusPayload_`: the envelope `{ data: IntegrationStatusPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.integrationStatus.getRoamStatus();
+```
+
+---
+
+<a id="op-getslackstatus"></a>
+
+### `g8.api.integrationStatus.getSlackStatus(input?)`
+
+**Get Slack Status**
+
+- HTTP: `GET /api/v1/integrations/slack/status`
+- operationId: `get_slack_status_integrations_slack_status_get` (also callable as `g8.api.call("get_slack_status_integrations_slack_status_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `integrations:read`
+
+Whether Slack is connected, and to which workspace.
+
+**Input**: none.
+
+**Returns** `ApiResponse_IntegrationStatusPayload_`: the envelope `{ data: IntegrationStatusPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.integrationStatus.getSlackStatus();
+```
+
+---
+
+<a id="op-listgoogledrivefolderfiles"></a>
+
+### `g8.api.integrationStatus.listGoogleDriveFolderFiles(input)`
+
+**List Google Drive Folder Files**
+
+- HTTP: `GET /api/v1/integrations/google-workspace/folders/{folder_id}/files`
+- operationId: `list_google_drive_folder_files_integrations_google_workspace_folders__folder_id__files_get` (also callable as `g8.api.call("list_google_drive_folder_files_integrations_google_workspace_folders__folder_id__files_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `integrations:read`
+
+The files in one Drive folder.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.folder_id` | `string` | yes | Drive folder id. |
+| `query.page_size` | `integer` | no | default `50` |
+| `query.page_token` | `string \| null` | no |  |
+
+**Returns** `ApiResponse_IntegrationStatusPayload_`: the envelope `{ data: IntegrationStatusPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.integrationStatus.listGoogleDriveFolderFiles({ path: { folder_id: "id" } });
+```
+
+---
+
+<a id="op-listgoogledrivefolders"></a>
+
+### `g8.api.integrationStatus.listGoogleDriveFolders(input?)`
+
+**List Google Drive Folders**
+
+- HTTP: `GET /api/v1/integrations/google-workspace/folders`
+- operationId: `list_google_drive_folders_integrations_google_workspace_folders_get` (also callable as `g8.api.call("list_google_drive_folders_integrations_google_workspace_folders_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `integrations:read`
+
+Drive folders the connected Workspace can see, one level at a time.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `query.parent_id` | `string` | no | Parent folder id; `root` for the top level. default `"root"` |
+| `query.view` | `"my_drive" \| "shared_drives" \| "shared_with_me"` | no | default `"my_drive"` |
+| `query.page_size` | `integer` | no | default `50` |
+| `query.page_token` | `string \| null` | no |  |
+
+**Returns** `ApiResponse_IntegrationStatusPayload_`: the envelope `{ data: IntegrationStatusPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.integrationStatus.listGoogleDriveFolders();
+```
+
+---
+
+<a id="op-testgoogleworkspaceconnection"></a>
+
+### `g8.api.integrationStatus.testGoogleWorkspaceConnection(input?)`
+
+**Test Google Workspace Connection**
+
+- HTTP: `POST /api/v1/integrations/google-workspace/test`
+- operationId: `test_google_workspace_connection_integrations_google_workspace_test_post` (also callable as `g8.api.call("test_google_workspace_connection_integrations_google_workspace_test_post", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `integrations:read`
+
+Check the stored Workspace connection still authenticates. Changes nothing.
+
+**Input**: none.
+
+**Returns** `ApiResponse_IntegrationStatusPayload_`: the envelope `{ data: IntegrationStatusPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.integrationStatus.testGoogleWorkspaceConnection();
+```