@graph8/sdk 0.251.0 → 0.262.0

package/docs/api/appPlatformTokens.d.ts

@@ -0,0 +1,123 @@
+/* Generated by sdk/js/scripts/generate-agent-docs.ts from developer-contract/openapi.json. Regenerated on every build. */
+
+/**
+ * Types for `g8.api.appPlatformTokens` (App Platform - Tokens): 3 operations.
+ *
+ * For reading. In code, import from the package instead:
+ *   import type { ApiInput, ApiOutput, G8Contract } from "@graph8/sdk";
+ *   type In = ApiInput<"app_token_jwks_app_platform__well_known_jwks_json_get">;
+ *
+ * Reference with examples: appPlatformTokens.md
+ */
+/* eslint-disable */
+
+/** `g8.api.appPlatformTokens.<member>` -> the operationId it calls. */
+export interface AppPlatformTokensMembers {
+  appTokenJwks: "app_token_jwks_app_platform__well_known_jwks_json_get";
+  exchangeAppSession: "exchange_app_session_app_sessions_exchange_post";
+  issueServiceToken: "issue_service_token_service_token_post";
+}
+
+/** Input and output of every `g8.api.appPlatformTokens` operation, keyed by operationId. */
+export interface AppPlatformTokensOperations {
+  /**
+   * GET /app-platform/.well-known/jwks.json
+   * App Token Jwks
+   * tier: read · scope: n/a
+   */
+  app_token_jwks_app_platform__well_known_jwks_json_get: {
+    input: Record<string, never>;
+    output: Record<string, unknown>;
+  };
+  /**
+   * POST /app-sessions/exchange
+   * Exchange App Session
+   * tier: write · scope: n/a
+   */
+  exchange_app_session_app_sessions_exchange_post: {
+    input: {
+    headers?: {
+      /** The organization ID to use for the request */
+      "X-Org-Id"?: string | null;
+    };
+    body: BrowserExchangeRequest;
+  };
+    output: ApiResponse_TokenResponse_;
+  };
+  /**
+   * POST /service-token
+   * Issue Service Token
+   * tier: write · scope: n/a
+   */
+  issue_service_token_service_token_post: {
+    input: {
+    body: ServiceTokenRequest;
+  };
+    output: ApiResponse_TokenResponse_;
+  };
+}
+
+// 5 schemas referenced above (the same as G8Contract.<Name>).
+
+export interface ApiResponse_TokenResponse_ {
+  data: TokenResponse;
+  pagination?: PaginationMeta | null;
+}
+
+/**
+ * Body for the browser exchange — target app + non-identity params ONLY.
+ *
+ * Identity is DERIVED SERVER-SIDE from the authenticated PropelAuth principal
+ * (locked decision §5: "browser auth = PropelAuth login -> short-lived graph8
+ * app token"): ``subject`` / ``client_org_id`` / ``role`` come from the
+ * validated principal, never from this body, so a client cannot self-assert who
+ * it is or escalate its role. Any ``subject`` / ``client_org_id`` / ``role``
+ * keys a caller forges into the body are ignored (pydantic drops unknown fields).
+ */
+export interface BrowserExchangeRequest {
+  /** Target app id (dapp_-prefixed) */
+  app_id: string;
+  /** Scopes to embed in the token */
+  scopes?: Array<string>;
+}
+
+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;
+}
+
+/** Client-credentials exchange for a service (server-to-server) app token. */
+export interface ServiceTokenRequest {
+  /** Service credential client id */
+  client_id: string;
+  /** Service credential client secret (checked against stored hash) */
+  client_secret: string;
+  /** Scopes to embed in the token */
+  scopes?: Array<string>;
+  /** Requested TTL; clamped into the 30-60m service band */
+  ttl_seconds?: number | null;
+}
+
+/** The minted token + the non-secret metadata a client needs. */
+export interface TokenResponse {
+  /** The signed app JWT */
+  access_token: string;
+  /** App the token is bound to */
+  app_id: string;
+  /** The distinct-per-app, per-environment audience */
+  audience: string;
+  /** Lifetime in seconds */
+  expires_in: number;
+  /** Signing key id (matches a JWKS entry) */
+  kid: string;
+  /** Always 'Bearer' */
+  token_type?: string;
+}

package/docs/api/appPlatformTokens.md

@@ -0,0 +1,172 @@
+<!-- Generated by sdk/js/scripts/generate-agent-docs.ts from developer-contract/openapi.json. Regenerated on every build. -->
+
+# `g8.api.appPlatformTokens`: App Platform - Tokens
+
+3 operations (1 read, 2 write).
+
+No hand-written client covers this area. Call it through `g8.api.appPlatformTokens.*` 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: [appPlatformTokens.d.ts](appPlatformTokens.d.ts).
+
+## Operations
+
+| Call | HTTP | Tier | Scope | Summary |
+|---|---|---|---|---|
+| [`appTokenJwks`](#op-apptokenjwks) | `GET /api/v1/app-platform/.well-known/jwks.json` | read |  | App Token Jwks |
+| [`exchangeAppSession`](#op-exchangeappsession) | `POST /api/v1/app-sessions/exchange` | write |  | Exchange App Session |
+| [`issueServiceToken`](#op-issueservicetoken) | `POST /api/v1/service-token` | write |  | Issue Service Token |
+
+---
+
+<a id="op-apptokenjwks"></a>
+
+### `g8.api.appPlatformTokens.appTokenJwks(input?)`
+
+**App Token Jwks**
+
+- HTTP: `GET /api/v1/app-platform/.well-known/jwks.json`
+- operationId: `app_token_jwks_app_platform__well_known_jwks_json_get` (also callable as `g8.api.call("app_token_jwks_app_platform__well_known_jwks_json_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: none published
+- Lifecycle: `preview`, enabled by `M6_APP_TOKENS_ENABLED` (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.
+
+Serve the public JWKS (all kids). Empty keyset when dormant.
+
+**Input**: none.
+
+**Returns** `Record<string, unknown>`.
+
+**Example**
+
+```ts
+const result = await g8.api.appPlatformTokens.appTokenJwks();
+```
+
+---
+
+<a id="op-exchangeappsession"></a>
+
+### `g8.api.appPlatformTokens.exchangeAppSession(input)`
+
+**Exchange App Session**
+
+- HTTP: `POST /api/v1/app-sessions/exchange`
+- operationId: `exchange_app_session_app_sessions_exchange_post` (also callable as `g8.api.call("exchange_app_session_app_sessions_exchange_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: none published
+- Lifecycle: `preview`, enabled by `M6_APP_TOKENS_ENABLED` (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.
+
+Mint a short-lived browser app token for the authenticated PropelAuth principal.
+
+Auth is the EXISTING ``get_current_user`` PropelAuth dependency — no valid
+principal -> 401. ``subject`` / ``client_org_id`` / ``role`` are derived
+SERVER-SIDE from that validated principal (``derive_browser_identity``), never
+from ``body`` — a forged identity/role in the body has no effect. Minting also
+requires a consented installation of the target app in the principal's org (403).
+A fail-closed per-principal / per-app limiter throttles the mint (429).
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `BrowserExchangeRequest` | yes | Request body; fields below. |
+| `headers.X-Org-Id` | `string \| null` | no | The organization ID to use for the request |
+
+Body fields (`BrowserExchangeRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.app_id` | `string` | yes | Target app id (dapp_-prefixed) |
+| `body.scopes` | `Array<string>` | no | Scopes to embed in the token |
+
+**Returns** `ApiResponse_TokenResponse_`: the envelope `{ data: TokenResponse, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`TokenResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `access_token` | `string` | yes | The signed app JWT |
+| `app_id` | `string` | yes | App the token is bound to |
+| `audience` | `string` | yes | The distinct-per-app, per-environment audience |
+| `expires_in` | `integer` | yes | Lifetime in seconds |
+| `kid` | `string` | yes | Signing key id (matches a JWKS entry) |
+| `token_type` | `string` | no | Always 'Bearer' default `"Bearer"` |
+
+**Example**
+
+```ts
+const result = await g8.api.appPlatformTokens.exchangeAppSession({ body: { app_id: "id" } });
+```
+
+---
+
+<a id="op-issueservicetoken"></a>
+
+### `g8.api.appPlatformTokens.issueServiceToken(input)`
+
+**Issue Service Token**
+
+- HTTP: `POST /api/v1/service-token`
+- operationId: `issue_service_token_service_token_post` (also callable as `g8.api.call("issue_service_token_service_token_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: none published
+- Lifecycle: `preview`, enabled by `M6_APP_TOKENS_ENABLED` (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.
+
+Mint a service (client-credentials) app token bound to the credential's org.
+
+A fail-closed per-credential limiter throttles the mint (429) before the
+credential is even checked, so brute-forcing a client secret is rate-bound.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `ServiceTokenRequest` | yes | Request body; fields below. |
+
+Body fields (`ServiceTokenRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.client_id` | `string` | yes | Service credential client id |
+| `body.client_secret` | `string` | yes | Service credential client secret (checked against stored hash) |
+| `body.scopes` | `Array<string>` | no | Scopes to embed in the token |
+| `body.ttl_seconds` | `integer \| null` | no | Requested TTL; clamped into the 30-60m service band |
+
+**Returns** `ApiResponse_TokenResponse_`: the envelope `{ data: TokenResponse, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`TokenResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `access_token` | `string` | yes | The signed app JWT |
+| `app_id` | `string` | yes | App the token is bound to |
+| `audience` | `string` | yes | The distinct-per-app, per-environment audience |
+| `expires_in` | `integer` | yes | Lifetime in seconds |
+| `kid` | `string` | yes | Signing key id (matches a JWKS entry) |
+| `token_type` | `string` | no | Always 'Bearer' default `"Bearer"` |
+
+**Example**
+
+```ts
+const result = await g8.api.appPlatformTokens.issueServiceToken({ body: { client_id: "id", client_secret: "example" } });
+```