@graph8/sdk 0.251.0 → 0.262.0

package/docs/api/apiKeys.d.ts

@@ -0,0 +1,252 @@
+/* Generated by sdk/js/scripts/generate-agent-docs.ts from developer-contract/openapi.json. Regenerated on every build. */
+
+/**
+ * Types for `g8.api.apiKeys` (API Keys): 6 operations.
+ *
+ * For reading. In code, import from the package instead:
+ *   import type { ApiInput, ApiOutput, G8Contract } from "@graph8/sdk";
+ *   type In = ApiInput<"create_api_key_api_keys_post">;
+ *
+ * Reference with examples: apiKeys.md
+ */
+/* eslint-disable */
+
+/** `g8.api.apiKeys.<member>` -> the operationId it calls. */
+export interface ApiKeysMembers {
+  createApiKey: "create_api_key_api_keys_post";
+  deleteApiKey: "delete_api_key_api_keys__api_key_id__delete";
+  listApiKeys: "list_api_keys_api_keys_get";
+  listScopeCatalog: "list_scope_catalog_api_keys_scopes_get";
+  rotateApiKey: "rotate_api_key_api_keys__api_key_id__rotate_post";
+  updateIpAllowlist: "update_ip_allowlist_api_keys__api_key_id__ip_allowlist_put";
+}
+
+/** Input and output of every `g8.api.apiKeys` operation, keyed by operationId. */
+export interface ApiKeysOperations {
+  /**
+   * POST /api-keys
+   * Create Api Key
+   * tier: write · scope: account:write
+   */
+  create_api_key_api_keys_post: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: ApiKeyCreateRequest;
+  };
+    output: ApiResponse_ApiKeyCreateResponse_;
+  };
+  /**
+   * DELETE /api-keys/{api_key_id}
+   * Delete Api Key
+   * tier: destructive · scope: account:write
+   */
+  delete_api_key_api_keys__api_key_id__delete: {
+    input: {
+    path: {
+      api_key_id: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: void;
+  };
+  /**
+   * GET /api-keys
+   * List Api Keys
+   * tier: read · scope: account:read
+   */
+  list_api_keys_api_keys_get: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_ApiKeyListResponse_;
+  };
+  /**
+   * GET /api-keys/scopes
+   * List Scope Catalog
+   * tier: read · scope: account:read
+   */
+  list_scope_catalog_api_keys_scopes_get: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_ScopeCatalogResponse_;
+  };
+  /**
+   * POST /api-keys/{api_key_id}/rotate
+   * Rotate Api Key
+   * tier: write · scope: account:write
+   */
+  rotate_api_key_api_keys__api_key_id__rotate_post: {
+    input: {
+    path: {
+      api_key_id: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: ApiKeyRotateRequest;
+  };
+    output: ApiResponse_ApiKeyCreateResponse_;
+  };
+  /**
+   * PUT /api-keys/{api_key_id}/ip-allowlist
+   * Update Ip Allowlist
+   * tier: write · scope: account:write
+   */
+  update_ip_allowlist_api_keys__api_key_id__ip_allowlist_put: {
+    input: {
+    path: {
+      api_key_id: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: ApiKeyIpAllowlistRequest;
+  };
+    output: ApiResponse_ApiKeyResponse_;
+  };
+}
+
+// 14 schemas referenced above (the same as G8Contract.<Name>).
+
+/**
+ * Request to mint a new organization API key.
+ *
+ * ``extra="forbid"`` so a caller sending ``org_id``, ``is_agency`` or
+ * ``is_ops`` gets an explicit 422 instead of the field being silently
+ * dropped — it is a stronger, more debuggable signal that those fields do
+ * not exist on this door.
+ */
+export interface ApiKeyCreateRequest {
+  /** Days until key expires (optional) */
+  expires_in_days?: number | null;
+  /** Optional list of IPv4/IPv6 CIDR strings (e.g. ['10.0.0.0/8', '2001:db8::/32']). Bare IPs are accepted as /32 (IPv4) or /128 (IPv6). When non-empty, only requests from a matching IP are accepted — all others receive 403. Empty list (the default) means unrestricted: the key works from any IP address. Maximum 50 entries. */
+  ip_allowlist?: Array<string>;
+  /** Key mode. A 'test' key is returned with a g8_test_ prefix; a 'live' key carries g8_live_; a 'sandbox' key carries g8_sbx_ and only authenticates against the graph8 developer sandbox. A key minted by a 'test'-mode credential is always forced to 'test' regardless of this field — a test key may not mint itself a live successor. */
+  mode?: "live" | "test" | "sandbox";
+  /** Human-readable name for the key */
+  name: string;
+  /** Restrict the new key to specific resource:action scopes (e.g. ['contacts:read', 'deals:*']). '*' grants everything; 'resource:*' grants every action on a resource. Omitted or empty grants the full current scope vocabulary (today's status quo for an unscoped key), stored explicitly so the key stays narrowable and auditable rather than permanently unrestricted. */
+  scopes?: Array<string> | null;
+}
+
+/**
+ * Response after minting a key.
+ *
+ * ``api_key_token`` is returned exactly once, here, at creation. No other
+ * endpoint on this router — or the app's — ever returns it again.
+ */
+export interface ApiKeyCreateResponse {
+  api_key_id: string;
+  api_key_token: string;
+  mode?: string;
+  name: string;
+  scopes?: Array<string>;
+}
+
+/** Request body to replace an existing key's IP allowlist in-place. */
+export interface ApiKeyIpAllowlistRequest {
+  /** Replacement list of CIDR strings. Pass [] to remove all restrictions. Maximum 50 entries. */
+  ip_allowlist: Array<string>;
+}
+
+export interface ApiKeyListResponse {
+  keys: Array<ApiKeyResponse>;
+  total: number;
+}
+
+/** One API key's metadata (never the secret). */
+export interface ApiKeyResponse {
+  api_key_id: string;
+  created_at?: number | null;
+  created_by?: string | null;
+  expires_at?: number | null;
+  /** CIDRs this key is restricted to. Empty = unrestricted. */
+  ip_allowlist?: Array<string>;
+  /** Whether this key is agency-scoped. Informational — this door cannot mint one. */
+  is_agency?: boolean;
+  /** True for a key minted before scopes existed. An empty scope list means unrestricted, not 'no access'. */
+  is_legacy_unrestricted?: boolean;
+  last_used_at?: number | null;
+  mode?: string;
+  name: string;
+  scopes?: Array<string>;
+}
+
+/**
+ * Request to rotate a key. Mode, scopes and agency status are preserved
+ * from the key being rotated — none are settable here.
+ *
+ * ``ip_allowlist`` is settable on rotation: a rotation is the natural moment
+ * to update network restrictions alongside the new credential.
+ * When omitted the old key's allowlist is preserved.
+ */
+export interface ApiKeyRotateRequest {
+  expires_in_days?: number | null;
+  /** Update the IP allowlist on rotation. Omit to preserve the existing allowlist. Pass [] to remove all restrictions. */
+  ip_allowlist?: Array<string> | null;
+  name?: string | null;
+}
+
+export interface ApiResponse_ApiKeyCreateResponse_ {
+  data: ApiKeyCreateResponse;
+  pagination?: PaginationMeta | null;
+}
+
+export interface ApiResponse_ApiKeyListResponse_ {
+  data: ApiKeyListResponse;
+  pagination?: PaginationMeta | null;
+}
+
+export interface ApiResponse_ApiKeyResponse_ {
+  data: ApiKeyResponse;
+  pagination?: PaginationMeta | null;
+}
+
+export interface ApiResponse_ScopeCatalogResponse_ {
+  data: ScopeCatalogResponse;
+  pagination?: PaginationMeta | 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;
+}
+
+export interface ScopeCatalogEntry {
+  action: string;
+  default: boolean;
+  scope: string;
+  strict: boolean;
+}
+
+export interface ScopeCatalogResource {
+  resource: string;
+  scopes: Array<ScopeCatalogEntry>;
+}
+
+export interface ScopeCatalogResponse {
+  default_scopes: Array<string>;
+  /** The full-access preset: every grantable scope except the explicit-only strict ones. `default_scopes` is read-only, so this is what a creator picks to opt in to write/run/launch/delete. */
+  full_access_scopes?: Array<string>;
+  /** The read-only preset: every ':read' scope in the grantable vocabulary. Minting a key with exactly these produces a credential that can look but never write, run, launch or delete — the 'read-only key' standard option (issue #21188). */
+  read_only_scopes?: Array<string>;
+  resources: Array<ScopeCatalogResource>;
+  total: number;
+}

package/docs/api/apiKeys.md

@@ -0,0 +1,318 @@
+<!-- Generated by sdk/js/scripts/generate-agent-docs.ts from developer-contract/openapi.json. Regenerated on every build. -->
+
+# `g8.api.apiKeys`: API Keys
+
+6 operations (2 read, 3 write, 1 destructive).
+
+No hand-written client covers this area. Call it through `g8.api.apiKeys.*` 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: [apiKeys.d.ts](apiKeys.d.ts).
+
+## Operations
+
+| Call | HTTP | Tier | Scope | Summary |
+|---|---|---|---|---|
+| [`createApiKey`](#op-createapikey) | `POST /api/v1/api-keys` | write | `account:write` | Create Api Key |
+| [`deleteApiKey`](#op-deleteapikey) | `DELETE /api/v1/api-keys/{api_key_id}` | destructive | `account:write` | Delete Api Key |
+| [`listApiKeys`](#op-listapikeys) | `GET /api/v1/api-keys` | read | `account:read` | List Api Keys |
+| [`listScopeCatalog`](#op-listscopecatalog) | `GET /api/v1/api-keys/scopes` | read | `account:read` | List Scope Catalog |
+| [`rotateApiKey`](#op-rotateapikey) | `POST /api/v1/api-keys/{api_key_id}/rotate` | write | `account:write` | Rotate Api Key |
+| [`updateIpAllowlist`](#op-updateipallowlist) | `PUT /api/v1/api-keys/{api_key_id}/ip-allowlist` | write | `account:write` | Update Ip Allowlist |
+
+---
+
+<a id="op-createapikey"></a>
+
+### `g8.api.apiKeys.createApiKey(input)`
+
+**Create Api Key**
+
+- HTTP: `POST /api/v1/api-keys`
+- operationId: `create_api_key_api_keys_post` (also callable as `g8.api.call("create_api_key_api_keys_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `account:write`
+
+Mint a new API key for the caller's own org. The token is returned exactly once.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `ApiKeyCreateRequest` | yes | Request body; fields below. |
+
+Body fields (`ApiKeyCreateRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.name` | `string` | yes | Human-readable name for the key min length 1, max length 100 |
+| `body.expires_in_days` | `integer \| null` | no | Days until key expires (optional) min 1, max 365 |
+| `body.ip_allowlist` | `Array<string>` | no | Optional list of IPv4/IPv6 CIDR strings (e.g. ['10.0.0.0/8', '2001:db8::/32']). Bare IPs are accepted as /32 (IPv4) or /128 (IPv6). When non-empty, only requests from a matching IP are accepted — all others receive 403. Empty list (the default) means unrestricted: the key works from any IP address. Maximum 50 entries. |
+| `body.mode` | `"live" \| "test" \| "sandbox"` | no | Key mode. A 'test' key is returned with a g8_test_ prefix; a 'live' key carries g8_live_; a 'sandbox' key carries g8_sbx_ and only authenticates against the graph8 developer sandbox. A key minted by a 'test'-mode credential is always forced to 'test' regardless of this field — a test key may not mint itself a live successor. default `"live"` |
+| `body.scopes` | `Array<string> \| null` | no | Restrict the new key to specific resource:action scopes (e.g. ['contacts:read', 'deals:*']). '*' grants everything; 'resource:*' grants every action on a resource. Omitted or empty grants the full current scope vocabulary (today's status quo for an unscoped key), stored explicitly so the key stays narrowable and auditable rather than permanently unrestricted. |
+
+**Returns** `ApiResponse_ApiKeyCreateResponse_`: the envelope `{ data: ApiKeyCreateResponse, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`ApiKeyCreateResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `api_key_id` | `string` | yes |  |
+| `api_key_token` | `string` | yes |  |
+| `name` | `string` | yes |  |
+| `mode` | `string` | no | default `"live"` |
+| `scopes` | `Array<string>` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.apiKeys.createApiKey({ body: { name: "Example" } });
+```
+
+---
+
+<a id="op-deleteapikey"></a>
+
+### `g8.api.apiKeys.deleteApiKey(input)`
+
+**Delete Api Key**
+
+- HTTP: `DELETE /api/v1/api-keys/{api_key_id}`
+- operationId: `delete_api_key_api_keys__api_key_id__delete` (also callable as `g8.api.call("delete_api_key_api_keys__api_key_id__delete", input)`)
+- Tier: `destructive`: deletes or archives data; confirm with a human before calling
+- API-key scope: `account:write`
+
+Revoke an API key. Idempotent: revoking a key that no longer exists
+(already revoked, or never existed in this org) returns 404, never 500.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.api_key_id` | `string` | yes |  |
+
+**Returns**: no JSON body is declared for the success response.
+
+**Example**
+
+```ts
+// destructive: deletes or archives data; confirm with a human before calling.
+const result = await g8.api.apiKeys.deleteApiKey({ path: { api_key_id: "id" } });
+```
+
+---
+
+<a id="op-listapikeys"></a>
+
+### `g8.api.apiKeys.listApiKeys(input?)`
+
+**List Api Keys**
+
+- HTTP: `GET /api/v1/api-keys`
+- operationId: `list_api_keys_api_keys_get` (also callable as `g8.api.call("list_api_keys_api_keys_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `account:read`
+
+List every API key in the caller's own org (never the secret).
+
+**Input**: none.
+
+**Returns** `ApiResponse_ApiKeyListResponse_`: the envelope `{ data: ApiKeyListResponse, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`ApiKeyListResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `keys` | `Array<ApiKeyResponse>` | yes |  |
+| `total` | `integer` | yes |  |
+
+**Example**
+
+```ts
+const result = await g8.api.apiKeys.listApiKeys();
+```
+
+---
+
+<a id="op-listscopecatalog"></a>
+
+### `g8.api.apiKeys.listScopeCatalog(input?)`
+
+**List Scope Catalog**
+
+- HTTP: `GET /api/v1/api-keys/scopes`
+- operationId: `list_scope_catalog_api_keys_scopes_get` (also callable as `g8.api.call("list_scope_catalog_api_keys_scopes_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `account:read`
+
+The scope vocabulary a key may be granted, so an automation can decide
+what to ask for without reading source. Read-only, org-independent.
+
+**Input**: none.
+
+**Returns** `ApiResponse_ScopeCatalogResponse_`: the envelope `{ data: ScopeCatalogResponse, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`ScopeCatalogResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `default_scopes` | `Array<string>` | yes |  |
+| `resources` | `Array<ScopeCatalogResource>` | yes |  |
+| `total` | `integer` | yes |  |
+| `full_access_scopes` | `Array<string>` | no | The full-access preset: every grantable scope except the explicit-only strict ones. `default_scopes` is read-only, so this is what a creator picks to opt in to write/run/launch/delete. |
+| `read_only_scopes` | `Array<string>` | no | The read-only preset: every ':read' scope in the grantable vocabulary. Minting a key with exactly these produces a credential that can look but never write, run, launch or delete — the 'read-only key' standard option (issue #21188). |
+
+**Example**
+
+```ts
+const result = await g8.api.apiKeys.listScopeCatalog();
+```
+
+---
+
+<a id="op-rotateapikey"></a>
+
+### `g8.api.apiKeys.rotateApiKey(input)`
+
+**Rotate Api Key**
+
+- HTTP: `POST /api/v1/api-keys/{api_key_id}/rotate`
+- operationId: `rotate_api_key_api_keys__api_key_id__rotate_post` (also callable as `g8.api.call("rotate_api_key_api_keys__api_key_id__rotate_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `account:write`
+
+Rotate a key, preserving its mode, scopes and agency status.
+
+The old key is deleted and a policy-equivalent replacement is minted; the
+new token is returned exactly once. Ownership is enforced by the org-scoped
+lookup below (mirroring the delete route) plus `rotate_api_key`'s own
+org-scoped read-back (`campaign_builder/services/propelauth.py`).
+
+Guard 4 (mode non-escalation) applies here too — see module docstring point
+4. Rotation PRESERVES the target key's mode, so without this a `test`-mode
+caller could rotate a `live` key and receive a brand-new `live` token (while
+invalidating the working live key). That is the same escalation the create
+route coerces away, so refuse it here rather than coerce: a rotation cannot
+be silently downgraded to `test` without destroying a working live key.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.api_key_id` | `string` | yes |  |
+| `body` | `ApiKeyRotateRequest` | yes | Request body; fields below. |
+
+Body fields (`ApiKeyRotateRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.expires_in_days` | `integer \| null` | no | min 1, max 365 |
+| `body.ip_allowlist` | `Array<string> \| null` | no | Update the IP allowlist on rotation. Omit to preserve the existing allowlist. Pass [] to remove all restrictions. |
+| `body.name` | `string \| null` | no | min length 1, max length 100 |
+
+**Returns** `ApiResponse_ApiKeyCreateResponse_`: the envelope `{ data: ApiKeyCreateResponse, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`ApiKeyCreateResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `api_key_id` | `string` | yes |  |
+| `api_key_token` | `string` | yes |  |
+| `name` | `string` | yes |  |
+| `mode` | `string` | no | default `"live"` |
+| `scopes` | `Array<string>` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.apiKeys.rotateApiKey({ path: { api_key_id: "id" }, body: {} });
+```
+
+---
+
+<a id="op-updateipallowlist"></a>
+
+### `g8.api.apiKeys.updateIpAllowlist(input)`
+
+**Update Ip Allowlist**
+
+- HTTP: `PUT /api/v1/api-keys/{api_key_id}/ip-allowlist`
+- operationId: `update_ip_allowlist_api_keys__api_key_id__ip_allowlist_put` (also callable as `g8.api.call("update_ip_allowlist_api_keys__api_key_id__ip_allowlist_put", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `account:write`
+
+Replace the IP allowlist for a key in-place. The token is unchanged.
+
+Pass an empty list to remove all IP restrictions.
+Gated by account:write (same as create/rotate/delete).
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.api_key_id` | `string` | yes |  |
+| `body` | `ApiKeyIpAllowlistRequest` | yes | Request body; fields below. |
+
+Body fields (`ApiKeyIpAllowlistRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.ip_allowlist` | `Array<string>` | yes | Replacement list of CIDR strings. Pass [] to remove all restrictions. Maximum 50 entries. |
+
+**Returns** `ApiResponse_ApiKeyResponse_`: the envelope `{ data: ApiKeyResponse, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`ApiKeyResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `api_key_id` | `string` | yes |  |
+| `name` | `string` | yes |  |
+| `created_at` | `integer \| null` | no |  |
+| `created_by` | `string \| null` | no |  |
+| `expires_at` | `integer \| null` | no |  |
+| `ip_allowlist` | `Array<string>` | no | CIDRs this key is restricted to. Empty = unrestricted. |
+| `is_agency` | `boolean` | no | Whether this key is agency-scoped. Informational — this door cannot mint one. default `false` |
+| `is_legacy_unrestricted` | `boolean` | no | True for a key minted before scopes existed. An empty scope list means unrestricted, not 'no access'. default `false` |
+| `last_used_at` | `integer \| null` | no |  |
+| `mode` | `string` | no | default `"live"` |
+| `scopes` | `Array<string>` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.apiKeys.updateIpAllowlist({ path: { api_key_id: "id" }, body: { ip_allowlist: ["example"] } });
+```
+
+---
+
+## Referenced types
+
+Named types that appear in the tables above. Full TypeScript definitions: `G8Contract.<Name>` (`import type { G8Contract } from "@graph8/sdk"`).
+
+<a id="type-scopecatalogresource"></a>
+
+### `ScopeCatalogResource`
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `resource` | `string` | yes |  |
+| `scopes` | `Array<ScopeCatalogEntry>` | yes |  |