@graph8/sdk 0.251.0 → 0.260.0

package/docs/api/appPages.d.ts

@@ -0,0 +1,557 @@
+/* Generated by sdk/js/scripts/generate-agent-docs.ts from developer-contract/openapi.json. Regenerated on every build. */
+
+/**
+ * Types for `g8.api.appPages` (App Pages): 16 operations.
+ *
+ * For reading. In code, import from the package instead:
+ *   import type { ApiInput, ApiOutput, G8Contract } from "@graph8/sdk";
+ *   type In = ApiInput<"chat_edit_app_page_app_pages__page_id__chat_edit_post">;
+ *
+ * Reference with examples: appPages.md
+ */
+/* eslint-disable */
+
+/** `g8.api.appPages.<member>` -> the operationId it calls. */
+export interface AppPagesMembers {
+  chatEditAppPage: "chat_edit_app_page_app_pages__page_id__chat_edit_post";
+  createAppPage: "create_app_page_app_pages_post";
+  deleteAppPage: "delete_app_page_app_pages__page_id__delete";
+  generateAppPage: "generate_app_page_app_pages__page_id__generate_post";
+  getAppPage: "get_app_page_app_pages__page_id__get";
+  getAppPageArtifact: "get_app_page_artifact_app_pages__page_id__artifact_get";
+  getAppPageStatus: "get_app_page_status_app_pages__page_id__status_get";
+  invokeAppPageAction: "invoke_app_page_action_app_pages__page_id__actions__alias___action_name__post";
+  listAppPageActions: "list_app_page_actions_app_pages__page_id__actions_get";
+  listAppPageSourceInstances: "list_app_page_source_instances_app_page_sources__source_kind__instances_get";
+  listAppPageSourceKinds: "list_app_page_source_kinds_app_page_sources_get";
+  listAppPageVersions: "list_app_page_versions_app_pages__page_id__versions_get";
+  listAppPages: "list_app_pages_app_pages_get";
+  mintAppPageFrameSession: "mint_app_page_frame_session_app_pages__page_id__frame_session_post";
+  replaceAppPageSources: "replace_app_page_sources_app_pages__page_id__sources_put";
+  restoreAppPageVersion: "restore_app_page_version_app_pages__page_id__versions__version_num__restore_post";
+}
+
+/** Input and output of every `g8.api.appPages` operation, keyed by operationId. */
+export interface AppPagesOperations {
+  /**
+   * POST /app-pages/{page_id}/chat-edit
+   * Chat Edit App Page
+   * tier: write · scope: apps:write
+   */
+  chat_edit_app_page_app_pages__page_id__chat_edit_post: {
+    input: {
+    path: {
+      page_id: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: AppPageChatEditRequest;
+  };
+    output: ApiResponse_AppPageChatEditResponse_;
+  };
+  /**
+   * POST /app-pages
+   * Create App Page
+   * tier: write · scope: apps:write
+   */
+  create_app_page_app_pages_post: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: CreateAppPageRequest;
+  };
+    output: ApiResponse_CreatedAppPageResponse_;
+  };
+  /**
+   * DELETE /app-pages/{page_id}
+   * Delete App Page
+   * tier: destructive · scope: apps:delete
+   */
+  delete_app_page_app_pages__page_id__delete: {
+    input: {
+    path: {
+      page_id: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_dict_;
+  };
+  /**
+   * POST /app-pages/{page_id}/generate
+   * Generate App Page
+   * tier: billable · scope: apps:run
+   */
+  generate_app_page_app_pages__page_id__generate_post: {
+    input: {
+    path: {
+      page_id: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: GenerateAppPageRequest;
+  };
+    output: ApiResponse_GenerateAppPageResponse_;
+  };
+  /**
+   * GET /app-pages/{page_id}
+   * Get App Page
+   * tier: read · scope: apps:read
+   */
+  get_app_page_app_pages__page_id__get: {
+    input: {
+    path: {
+      page_id: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_AppPageResponse_;
+  };
+  /**
+   * GET /app-pages/{page_id}/artifact
+   * Get App Page Artifact
+   * tier: read · scope: apps:read
+   */
+  get_app_page_artifact_app_pages__page_id__artifact_get: {
+    input: {
+    path: {
+      page_id: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_AppPageArtifactResponse_;
+  };
+  /**
+   * GET /app-pages/{page_id}/status
+   * Get App Page Status
+   * tier: read · scope: apps:read
+   */
+  get_app_page_status_app_pages__page_id__status_get: {
+    input: {
+    path: {
+      page_id: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_AppPageStatusResponse_;
+  };
+  /**
+   * POST /app-pages/{page_id}/actions/{alias}/{action_name}
+   * Invoke App Page Action
+   * tier: write · scope: apps:write
+   */
+  invoke_app_page_action_app_pages__page_id__actions__alias___action_name__post: {
+    input: {
+    path: {
+      page_id: string;
+      alias: string;
+      action_name: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: InvokeActionRequest;
+  };
+    output: ApiResponse_InvokeActionResponse_;
+  };
+  /**
+   * GET /app-pages/{page_id}/actions
+   * List App Page Actions
+   * tier: read · scope: apps:read
+   */
+  list_app_page_actions_app_pages__page_id__actions_get: {
+    input: {
+    path: {
+      page_id: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_AppPageActionsResponse_;
+  };
+  /**
+   * GET /app-page-sources/{source_kind}/instances
+   * List App Page Source Instances
+   * tier: read · scope: apps:read
+   */
+  list_app_page_source_instances_app_page_sources__source_kind__instances_get: {
+    input: {
+    path: {
+      /** A family `kind` from `GET /app-page-sources`. */
+      source_kind: string;
+    };
+    query?: {
+      limit?: number;
+      /** Filter by name. */
+      query?: string | null;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_AppPageSourceCatalogPayload_;
+  };
+  /**
+   * GET /app-page-sources
+   * List App Page Source Kinds
+   * tier: read · scope: apps:read
+   */
+  list_app_page_source_kinds_app_page_sources_get: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_AppPageSourceCatalogPayload_;
+  };
+  /**
+   * GET /app-pages/{page_id}/versions
+   * List App Page Versions
+   * tier: read · scope: apps:read
+   */
+  list_app_page_versions_app_pages__page_id__versions_get: {
+    input: {
+    path: {
+      page_id: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_AppPageVersionListResponse_;
+  };
+  /**
+   * GET /app-pages
+   * List App Pages
+   * tier: read · scope: apps:read
+   */
+  list_app_pages_app_pages_get: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_list_AppPageResponse__;
+  };
+  /**
+   * POST /app-pages/{page_id}/frame-session
+   * Mint App Page Frame Session
+   * tier: write · scope: apps:write
+   */
+  mint_app_page_frame_session_app_pages__page_id__frame_session_post: {
+    input: {
+    path: {
+      page_id: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_AppPageFrameSessionResponse_;
+  };
+  /**
+   * PUT /app-pages/{page_id}/sources
+   * Replace App Page Sources
+   * tier: write · scope: apps:write
+   */
+  replace_app_page_sources_app_pages__page_id__sources_put: {
+    input: {
+    path: {
+      /** App page id. */
+      page_id: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: AppPageSourcesReplaceRequest;
+  };
+    output: ApiResponse_AppPageSourcesPayload_;
+  };
+  /**
+   * POST /app-pages/{page_id}/versions/{version_num}/restore
+   * Restore App Page Version
+   * tier: write · scope: apps:write
+   */
+  restore_app_page_version_app_pages__page_id__versions__version_num__restore_post: {
+    input: {
+    path: {
+      page_id: string;
+      version_num: number;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_AppPageRestoreResponse_;
+  };
+}
+
+// 38 schemas referenced above (the same as G8Contract.<Name>).
+
+/** One action a page may invoke on one of its bound sources. */
+export interface ActionDescriptorDto {
+  description?: string;
+  /** Cannot be undone. Surfaced so a host can confirm before invoking. */
+  irreversible?: boolean;
+  label: string;
+  name: string;
+  params?: Array<ActionParamDto>;
+}
+
+/** One argument an action accepts. */
+export interface ActionParamDto {
+  label: string;
+  name: string;
+  required?: boolean;
+  /** `pii` marks personal data, so a host can treat it accordingly */
+  sensitivity?: string;
+  /** string | number | date | bool | enum | json */
+  type: string;
+}
+
+export interface ApiResponse_AppPageActionsResponse_ {
+  data: AppPageActionsResponse;
+  pagination?: PaginationMeta | null;
+}
+
+export interface ApiResponse_AppPageArtifactResponse_ {
+  data: AppPageArtifactResponse;
+  pagination?: PaginationMeta | null;
+}
+
+export interface ApiResponse_AppPageChatEditResponse_ {
+  data: AppPageChatEditResponse;
+  pagination?: PaginationMeta | null;
+}
+
+export interface ApiResponse_AppPageFrameSessionResponse_ {
+  data: AppPageFrameSessionResponse;
+  pagination?: PaginationMeta | null;
+}
+
+export interface ApiResponse_AppPageResponse_ {
+  data: AppPageResponse;
+  pagination?: PaginationMeta | null;
+}
+
+export interface ApiResponse_AppPageRestoreResponse_ {
+  data: AppPageRestoreResponse;
+  pagination?: PaginationMeta | null;
+}
+
+export interface ApiResponse_AppPageSourceCatalogPayload_ {
+  data: AppPageSourceCatalogPayload;
+  pagination?: PaginationMeta | null;
+}
+
+export interface ApiResponse_AppPageSourcesPayload_ {
+  data: AppPageSourcesPayload;
+  pagination?: PaginationMeta | null;
+}
+
+export interface ApiResponse_AppPageStatusResponse_ {
+  data: AppPageStatusResponse;
+  pagination?: PaginationMeta | null;
+}
+
+export interface ApiResponse_AppPageVersionListResponse_ {
+  data: AppPageVersionListResponse;
+  pagination?: PaginationMeta | null;
+}
+
+export interface ApiResponse_CreatedAppPageResponse_ {
+  data: CreatedAppPageResponse;
+  pagination?: PaginationMeta | null;
+}
+
+export interface ApiResponse_GenerateAppPageResponse_ {
+  data: GenerateAppPageResponse;
+  pagination?: PaginationMeta | null;
+}
+
+export interface ApiResponse_InvokeActionResponse_ {
+  data: InvokeActionResponse;
+  pagination?: PaginationMeta | null;
+}
+
+export interface ApiResponse_dict_ {
+  data: Record<string, unknown>;
+  pagination?: PaginationMeta | null;
+}
+
+export interface ApiResponse_list_AppPageResponse__ {
+  data: Array<AppPageResponse>;
+  pagination?: PaginationMeta | null;
+}
+
+/**
+ * Everything this page can do, grouped by the alias it acts on.
+ *
+ * Only aliases the page actually binds appear. An action is addressed by
+ * (alias, name), never by a source id, which is what stops a page acting on
+ * something it does not bind.
+ */
+export interface AppPageActionsResponse {
+  actions_by_alias?: Record<string, Array<ActionDescriptorDto>>;
+  page_id: string;
+}
+
+/** The generated page itself, plus the manifest wiring it to its sources. */
+export interface AppPageArtifactResponse {
+  data_manifest?: Record<string, unknown>;
+  html_source?: string | null;
+  name: string;
+  page_id: string;
+  status: string;
+  updated_at?: string | null;
+}
+
+export interface AppPageChatEditRequest {
+  instruction: string;
+}
+
+export interface AppPageChatEditResponse {
+  edit_summary: string;
+  page_id: string;
+  status?: string;
+  version_num: number;
+}
+
+/**
+ * A one-shot token for loading the page's sandboxed frame.
+ *
+ * Single use and short lived. The frame is served from a cookieless origin
+ * under a `default-src 'none'` policy, so this token is the only thing that
+ * authorizes a load.
+ */
+export interface AppPageFrameSessionResponse {
+  expires_in: number;
+  /** Absolute URL to load, token included. Absent when no frame origin is configured. */
+  frame_url?: string | null;
+  token: string;
+  view_session_id: string;
+}
+
+export interface AppPageResponse {
+  created_at?: string | null;
+  description?: string | null;
+  name: string;
+  page_id: string;
+  sources?: Array<AppPageSourceDto>;
+  /** draft | generating | ready | failed */
+  status: string;
+  updated_at?: string | null;
+}
+
+export interface AppPageRestoreResponse {
+  page_id: string;
+  restored_from_version: number;
+  snapshot_version: number;
+}
+
+/** Source families or instances under `items`. */
+export interface AppPageSourceCatalogPayload {
+  items?: Array<unknown>;
+  [key: string]: unknown;
+}
+
+/**
+ * One data source bound into a page. `alias` is the handle the generated
+ * page's JavaScript addresses it by.
+ */
+export interface AppPageSourceDto {
+  /** Handle used inside the page. Auto-assigned from the kind when omitted. */
+  alias?: string | null;
+  position?: number;
+  role?: string;
+  /** Opaque to everything but the connector that owns it */
+  source_id: string;
+  /** Connector family, e.g. staging-table or custom-object */
+  source_kind: string;
+}
+
+/** The page after its sources changed. */
+export type AppPageSourcesPayload = Record<string, unknown>;
+
+export interface AppPageSourcesReplaceRequest {
+  /** The page's full source list. */
+  sources: Array<AppPageSourceDto>;
+}
+
+export interface AppPageStatusResponse {
+  /** True once generation has stored HTML. `status: ready` alone is not enough. */
+  has_page?: boolean;
+  page_id: string;
+  status: string;
+}
+
+export interface AppPageVersionDto {
+  created_at?: string | null;
+  edit_instruction?: string | null;
+  edit_summary?: string | null;
+  version_num: number;
+}
+
+export interface AppPageVersionListResponse {
+  page_id: string;
+  versions?: Array<AppPageVersionDto>;
+}
+
+export interface CreateAppPageRequest {
+  description?: string | null;
+  name: string;
+  /** At least one. A page with no data source can never be generated. */
+  sources: Array<AppPageSourceDto>;
+}
+
+export interface CreatedAppPageResponse {
+  page_id: string;
+}
+
+export interface GenerateAppPageRequest {
+  /** What the page should show. Free text; the generator composes every bound source. */
+  instruction?: string | null;
+}
+
+export interface GenerateAppPageResponse {
+  job_id?: string | null;
+  page_id: string;
+  status?: string;
+}
+
+export interface InvokeActionRequest {
+  /** Action arguments. Validated against the object's own schema; an undeclared field is refused, not dropped. */
+  args?: Record<string, unknown>;
+}
+
+export interface InvokeActionResponse {
+  /** Sources whose data is now stale, so a page can refresh only what changed. */
+  invalidates?: Array<string>;
+  message?: string | null;
+  ok: boolean;
+  record_id?: string | 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;
+}