@graph8/sdk 0.251.0 → 0.262.0

package/docs/api/apps.d.ts

@@ -0,0 +1,822 @@
+/* Generated by sdk/js/scripts/generate-agent-docs.ts from developer-contract/openapi.json. Regenerated on every build. */
+
+/**
+ * Types for `g8.api.apps` (Apps): 22 operations.
+ *
+ * For reading. In code, import from the package instead:
+ *   import type { ApiInput, ApiOutput, G8Contract } from "@graph8/sdk";
+ *   type In = ApiInput<"apply_app_manifest_apps__app_id__manifest_post">;
+ *
+ * Reference with examples: apps.md
+ */
+/* eslint-disable */
+
+/** `g8.api.apps.<member>` -> the operationId it calls. */
+export interface AppsMembers {
+  applyAppManifest: "apply_app_manifest_apps__app_id__manifest_post";
+  clearAppLimit: "clear_app_limit_apps__app_id__limit_delete";
+  clearAppSource: "clear_app_source_apps__app_id__source_delete";
+  createApp: "create_app_apps_post";
+  createAppCredential: "create_app_credential_apps__app_id__credentials_post";
+  deleteAppSecret: "delete_app_secret_apps__app_id__secrets__secret_key__delete";
+  getApp: "get_app_apps__app_id__get";
+  getAppLimit: "get_app_limit_apps__app_id__limit_get";
+  getAppRuntime: "get_app_runtime_apps__app_id__runtime_get";
+  getAppUsage: "get_app_usage_apps__app_id__usage_get";
+  listAppCredentials: "list_app_credentials_apps__app_id__credentials_get";
+  listAppInstalls: "list_app_installs_apps__app_id__installs_get";
+  listAppSchemaVersions: "list_app_schema_versions_apps__app_id__schema_versions_get";
+  listAppSecrets: "list_app_secrets_apps__app_id__secrets_get";
+  listApps: "list_apps_apps_get";
+  publishAppSchemaVersion: "publish_app_schema_version_apps__app_id__schema_versions_post";
+  putAppSecret: "put_app_secret_apps__app_id__secrets__secret_key__put";
+  revokeAppCredential: "revoke_app_credential_apps__app_id__credentials__client_id__delete";
+  setAppLimit: "set_app_limit_apps__app_id__limit_put";
+  setAppSource: "set_app_source_apps__app_id__source_put";
+  setAppStatus: "set_app_status_apps__app_id__status_post";
+  validateAppManifest: "validate_app_manifest_apps_manifest_validate_post";
+}
+
+/** Input and output of every `g8.api.apps` operation, keyed by operationId. */
+export interface AppsOperations {
+  /**
+   * POST /apps/{app_id}/manifest
+   * Apply App Manifest
+   * tier: write · scope: apps:write
+   */
+  apply_app_manifest_apps__app_id__manifest_post: {
+    input: {
+    path: {
+      app_id: string;
+    };
+    headers?: {
+      "X-Org-Id"?: string | null;
+    };
+    body: ManifestRequest;
+  };
+    output: ApiResponse_ApplyManifestResponse_;
+  };
+  /**
+   * DELETE /apps/{app_id}/limit
+   * Clear App Limit
+   * tier: destructive · scope: apps:delete
+   */
+  clear_app_limit_apps__app_id__limit_delete: {
+    input: {
+    path: {
+      app_id: string;
+    };
+    headers?: {
+      "X-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_NoneType_;
+  };
+  /**
+   * DELETE /apps/{app_id}/source
+   * Clear App Source
+   * tier: destructive · scope: apps:delete
+   */
+  clear_app_source_apps__app_id__source_delete: {
+    input: {
+    path: {
+      app_id: string;
+    };
+    headers?: {
+      "X-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_AppResponse_;
+  };
+  /**
+   * POST /apps
+   * Create App
+   * tier: write · scope: apps:write
+   */
+  create_app_apps_post: {
+    input: {
+    headers?: {
+      "X-Org-Id"?: string | null;
+    };
+    body: CreateAppRequest;
+  };
+    output: ApiResponse_AppResponse_;
+  };
+  /**
+   * POST /apps/{app_id}/credentials
+   * Create App Credential
+   * tier: write · scope: apps:write
+   */
+  create_app_credential_apps__app_id__credentials_post: {
+    input: {
+    path: {
+      app_id: string;
+    };
+    headers?: {
+      "X-Org-Id"?: string | null;
+    };
+    body: CreateCredentialRequest;
+  };
+    output: ApiResponse_CreatedCredentialResponse_;
+  };
+  /**
+   * DELETE /apps/{app_id}/secrets/{secret_key}
+   * Delete App Secret
+   * tier: destructive · scope: apps:delete
+   */
+  delete_app_secret_apps__app_id__secrets__secret_key__delete: {
+    input: {
+    path: {
+      app_id: string;
+      secret_key: string;
+    };
+    headers?: {
+      "X-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_dict_;
+  };
+  /**
+   * GET /apps/{app_id}
+   * Get App
+   * tier: read · scope: apps:read
+   */
+  get_app_apps__app_id__get: {
+    input: {
+    path: {
+      app_id: string;
+    };
+    headers?: {
+      "X-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_AppResponse_;
+  };
+  /**
+   * GET /apps/{app_id}/limit
+   * Get App Limit
+   * tier: read · scope: apps:read
+   */
+  get_app_limit_apps__app_id__limit_get: {
+    input: {
+    path: {
+      app_id: string;
+    };
+    headers?: {
+      "X-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_Union_AppLimitResponse__NoneType__;
+  };
+  /**
+   * GET /apps/{app_id}/runtime
+   * Get App Runtime
+   * tier: billable · scope: apps:run
+   */
+  get_app_runtime_apps__app_id__runtime_get: {
+    input: {
+    path: {
+      app_id: string;
+    };
+    headers?: {
+      "X-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_AppRuntimeResponse_;
+  };
+  /**
+   * GET /apps/{app_id}/usage
+   * Get App Usage
+   * tier: read · scope: apps:read
+   */
+  get_app_usage_apps__app_id__usage_get: {
+    input: {
+    path: {
+      app_id: string;
+    };
+    query?: {
+      /** Calendar month `YYYY-MM`. Defaults to the current month. */
+      period?: string | null;
+    };
+    headers?: {
+      "X-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_UsageSummaryResponse_;
+  };
+  /**
+   * GET /apps/{app_id}/credentials
+   * List App Credentials
+   * tier: read · scope: apps:read
+   */
+  list_app_credentials_apps__app_id__credentials_get: {
+    input: {
+    path: {
+      app_id: string;
+    };
+    headers?: {
+      "X-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_list_CredentialResponse__;
+  };
+  /**
+   * GET /apps/{app_id}/installs
+   * List App Installs
+   * tier: read · scope: apps:read
+   */
+  list_app_installs_apps__app_id__installs_get: {
+    input: {
+    path: {
+      app_id: string;
+    };
+    headers?: {
+      "X-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_list_InstallationResponse__;
+  };
+  /**
+   * GET /apps/{app_id}/schema-versions
+   * List App Schema Versions
+   * tier: read · scope: apps:read
+   */
+  list_app_schema_versions_apps__app_id__schema_versions_get: {
+    input: {
+    path: {
+      app_id: string;
+    };
+    headers?: {
+      "X-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_list_SchemaVersionResponse__;
+  };
+  /**
+   * GET /apps/{app_id}/secrets
+   * List App Secrets
+   * tier: read · scope: apps:read
+   */
+  list_app_secrets_apps__app_id__secrets_get: {
+    input: {
+    path: {
+      app_id: string;
+    };
+    headers?: {
+      "X-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_list_AppSecretResponse__;
+  };
+  /**
+   * GET /apps
+   * List Apps
+   * tier: read · scope: apps:read
+   */
+  list_apps_apps_get: {
+    input: {
+    headers?: {
+      "X-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_list_AppResponse__;
+  };
+  /**
+   * POST /apps/{app_id}/schema-versions
+   * Publish App Schema Version
+   * tier: write · scope: apps:write
+   */
+  publish_app_schema_version_apps__app_id__schema_versions_post: {
+    input: {
+    path: {
+      app_id: string;
+    };
+    headers?: {
+      "X-Org-Id"?: string | null;
+    };
+    body: PublishSchemaVersionRequest;
+  };
+    output: ApiResponse_PublishSchemaVersionResponse_;
+  };
+  /**
+   * PUT /apps/{app_id}/secrets/{secret_key}
+   * Put App Secret
+   * tier: write · scope: apps:write
+   */
+  put_app_secret_apps__app_id__secrets__secret_key__put: {
+    input: {
+    path: {
+      app_id: string;
+      secret_key: string;
+    };
+    headers?: {
+      "X-Org-Id"?: string | null;
+    };
+    body: PutAppSecretRequest;
+  };
+    output: ApiResponse_AppSecretResponse_;
+  };
+  /**
+   * DELETE /apps/{app_id}/credentials/{client_id}
+   * Revoke App Credential
+   * tier: destructive · scope: apps:delete
+   */
+  revoke_app_credential_apps__app_id__credentials__client_id__delete: {
+    input: {
+    path: {
+      app_id: string;
+      client_id: string;
+    };
+    headers?: {
+      "X-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_CredentialResponse_;
+  };
+  /**
+   * PUT /apps/{app_id}/limit
+   * Set App Limit
+   * tier: write · scope: apps:write
+   */
+  set_app_limit_apps__app_id__limit_put: {
+    input: {
+    path: {
+      app_id: string;
+    };
+    headers?: {
+      "X-Org-Id"?: string | null;
+    };
+    body: SetAppLimitRequest;
+  };
+    output: ApiResponse_AppLimitResponse_;
+  };
+  /**
+   * PUT /apps/{app_id}/source
+   * Set App Source
+   * tier: write · scope: apps:write
+   */
+  set_app_source_apps__app_id__source_put: {
+    input: {
+    path: {
+      app_id: string;
+    };
+    headers?: {
+      "X-Org-Id"?: string | null;
+    };
+    body: AppSourceRequest;
+  };
+    output: ApiResponse_AppResponse_;
+  };
+  /**
+   * POST /apps/{app_id}/status
+   * Set App Status
+   * tier: write · scope: apps:write
+   */
+  set_app_status_apps__app_id__status_post: {
+    input: {
+    path: {
+      app_id: string;
+    };
+    headers?: {
+      "X-Org-Id"?: string | null;
+    };
+    body: SetAppStatusRequest;
+  };
+    output: ApiResponse_AppResponse_;
+  };
+  /**
+   * POST /apps/manifest/validate
+   * Validate App Manifest
+   * tier: write · scope: apps:write
+   */
+  validate_app_manifest_apps_manifest_validate_post: {
+    input: {
+    headers?: {
+      "X-Org-Id"?: string | null;
+    };
+    body: ManifestRequest;
+  };
+    output: ApiResponse_ValidateManifestResponse_;
+  };
+}
+
+// 42 schemas referenced above (the same as G8Contract.<Name>).
+
+export interface ApiResponse_AppLimitResponse_ {
+  data: AppLimitResponse;
+  pagination?: PaginationMeta | null;
+}
+
+export interface ApiResponse_AppResponse_ {
+  data: AppResponse;
+  pagination?: PaginationMeta | null;
+}
+
+export interface ApiResponse_AppRuntimeResponse_ {
+  data: AppRuntimeResponse;
+  pagination?: PaginationMeta | null;
+}
+
+export interface ApiResponse_AppSecretResponse_ {
+  data: AppSecretResponse;
+  pagination?: PaginationMeta | null;
+}
+
+export interface ApiResponse_ApplyManifestResponse_ {
+  data: ApplyManifestResponse;
+  pagination?: PaginationMeta | null;
+}
+
+export interface ApiResponse_CreatedCredentialResponse_ {
+  data: CreatedCredentialResponse;
+  pagination?: PaginationMeta | null;
+}
+
+export interface ApiResponse_CredentialResponse_ {
+  data: CredentialResponse;
+  pagination?: PaginationMeta | null;
+}
+
+export interface ApiResponse_NoneType_ {
+  data: null;
+  pagination?: PaginationMeta | null;
+}
+
+export interface ApiResponse_PublishSchemaVersionResponse_ {
+  data: PublishSchemaVersionResponse;
+  pagination?: PaginationMeta | null;
+}
+
+export interface ApiResponse_Union_AppLimitResponse__NoneType__ {
+  data: AppLimitResponse | null;
+  pagination?: PaginationMeta | null;
+}
+
+export interface ApiResponse_UsageSummaryResponse_ {
+  data: UsageSummaryResponse;
+  pagination?: PaginationMeta | null;
+}
+
+export interface ApiResponse_ValidateManifestResponse_ {
+  data: ValidateManifestResponse;
+  pagination?: PaginationMeta | null;
+}
+
+export interface ApiResponse_dict_ {
+  data: Record<string, unknown>;
+  pagination?: PaginationMeta | null;
+}
+
+export interface ApiResponse_list_AppResponse__ {
+  data: Array<AppResponse>;
+  pagination?: PaginationMeta | null;
+}
+
+export interface ApiResponse_list_AppSecretResponse__ {
+  data: Array<AppSecretResponse>;
+  pagination?: PaginationMeta | null;
+}
+
+export interface ApiResponse_list_CredentialResponse__ {
+  data: Array<CredentialResponse>;
+  pagination?: PaginationMeta | null;
+}
+
+export interface ApiResponse_list_InstallationResponse__ {
+  data: Array<InstallationResponse>;
+  pagination?: PaginationMeta | null;
+}
+
+export interface ApiResponse_list_SchemaVersionResponse__ {
+  data: Array<SchemaVersionResponse>;
+  pagination?: PaginationMeta | null;
+}
+
+/**
+ * An app's hard credit cap. Mirrors `AppLimitDto`.
+ *
+ * The endpoint returns `null` for no cap. There is no "unlimited" sentinel, so
+ * an accidental zero can never read as no limit.
+ */
+export interface AppLimitResponse {
+  app_id: string;
+  created_at?: string | null;
+  credit_cap: number;
+  /** Cap window. `calendar_month` today. */
+  window: string;
+}
+
+/** One builder-owned app. Mirrors `AppDto`. */
+export interface AppResponse {
+  app_id: string;
+  archived_at?: string | null;
+  builder_org_id: string;
+  created_at?: string | null;
+  default_hostname?: string | null;
+  name: string;
+  /** https-only origins a browser app token may be presented from. */
+  registered_origins?: Array<string>;
+  slug: string;
+  /** A POINTER to the credential (a secret-manager path), never the credential itself. */
+  source_credential_ref?: string | null;
+  source_default_branch?: string | null;
+  source_provider?: string | null;
+  /** Where this app's code lives. Null until bound. */
+  source_repo_url?: string | null;
+  /** Lifecycle state: `draft`, `published`, `suspended` or `archived`. `active` is accepted on write as a legacy spelling of `published`. */
+  status: string;
+}
+
+/**
+ * Whether an app is ready to be built and run, and what is missing (J9).
+ *
+ * A READINESS REPORT, not a promise. It answers from what the control plane
+ * knows: is a source bound, is a hostname assigned, are secrets declared, what
+ * did the last deployment do. It does NOT claim the cluster side is ready,
+ * because the namespace provisioner, the image registry and the runtime objects
+ * are separate work and none of them exist yet.
+ *
+ * `blockers` is the useful field and it is deliberately explicit. An agent
+ * driving a build needs to know WHY it cannot proceed, and a bare
+ * `ready: false` sends it guessing.
+ */
+export interface AppRuntimeResponse {
+  app_id: string;
+  /** Each unmet prerequisite, named. Empty means ready. */
+  blockers?: Array<string>;
+  hostname_assigned: boolean;
+  latest_deployment_status?: string | null;
+  /** True only when nothing in `blockers` remains. False is the normal answer today. */
+  ready: boolean;
+  secrets_declared: number;
+  source_bound: boolean;
+}
+
+/**
+ * One declared secret. A POINTER and two timestamps, never a value.
+ *
+ * There is no `value` field and there must never be one. The control plane
+ * stores WHICH secrets an app declares and where they live, so a build can be
+ * rendered without the platform ever holding what the build will read.
+ */
+export interface AppSecretResponse {
+  created_at?: string | null;
+  /** Where the value lives, e.g. a secret-manager path. Never the value. */
+  provider_ref?: string | null;
+  /** Last time this declaration was rewritten. Moves on every write, including one that repeats the same pointer: the pointer is not the secret, so an unchanged path does not mean an unchanged value. */
+  rotated_at?: string | null;
+  secret_key: string;
+}
+
+/**
+ * Bind an app to the repository a build should fetch (J1).
+ *
+ * PROVIDER IS VALIDATED HERE, NOT BY A CHECK CONSTRAINT. `ensure_public_tables`
+ * emits `ADD COLUMN IF NOT EXISTS`, which cannot add a CHECK to an already
+ * created table, and editing the constraint tuple alone is a silent no-op. So
+ * the vocabulary lives in `SOURCE_PROVIDERS` and this DTO is what enforces it,
+ * the same way `repos_router` already validates its provider.
+ *
+ * `credential_ref` is a POINTER, and the description says so on the wire. A
+ * builder who pastes a token here has put it in the control-plane row, in every
+ * backup of it, and in the response body of `GET /apps/{app_id}`. There is no
+ * way to un-send that, so the field is named and documented to make the mistake
+ * hard rather than merely regrettable.
+ */
+export interface AppSourceRequest {
+  /** Secret-manager PATH for the fetch credential. Never the credential itself. */
+  credential_ref?: string | null;
+  /** Defaults to the repository's own default when omitted. */
+  default_branch?: string | null;
+  /** One of: github, gitlab, bitbucket. */
+  provider: string;
+  /** Clone URL. */
+  repo_url: string;
+}
+
+/**
+ * What an apply actually did, part by part.
+ *
+ * Each field answers "did this half happen", because a manifest declaring only
+ * `objects:` and one declaring only `backend:` are both legal and do different
+ * amounts of work. A caller should never have to infer that from a 200.
+ */
+export interface ApplyManifestResponse {
+  app_id: string;
+  deploy_config_stored?: boolean;
+  materialization?: MaterializationSummary | null;
+  /** False when an identical schema was already published. The version named above exists either way; this is what says nothing changed. */
+  schema_created?: boolean;
+  schema_version?: SchemaVersionResponse | null;
+  summary: ManifestSummary;
+}
+
+/** Mirrors `CreateAppInput`. */
+export interface CreateAppRequest {
+  name: string;
+  /** https-only origins a browser app token may be presented from. An http origin is rejected — a bearer token sent over http is a token disclosed to the network. */
+  registered_origins?: Array<string>;
+  /** Stable identifier, unique within your organization. Lowercased on write, so `CRM` and `crm` are the same app. */
+  slug: string;
+}
+
+/** A builder minting a service credential for one consented tenant. */
+export interface CreateCredentialRequest {
+  /** The client organization this credential acts for. It must already have a consented installation of the app — a credential is bound to one tenant and cannot be pointed at another later. */
+  client_org_id: string;
+}
+
+/**
+ * The create response, and the ONLY time the secret is ever returned.
+ *
+ * Only the SHA-256 is stored — `developer_app_credentials` has no column that
+ * could hold a plaintext secret — so this response cannot be reissued. That is
+ * the point: a secret the platform can re-read is a secret the platform can
+ * leak.
+ */
+export interface CreatedCredentialResponse {
+  app_id: string;
+  client_id: string;
+  client_org_id: string;
+  /** Shown ONCE. Store it now — only its hash is kept, so it cannot be retrieved again. Rotate by creating a new credential and revoking this one. */
+  client_secret: string;
+  created_at?: string | null;
+  revoked?: boolean;
+}
+
+/** A service credential. Carries NO secret. */
+export interface CredentialResponse {
+  app_id: string;
+  client_id: string;
+  client_org_id: string;
+  created_at?: string | null;
+  revoked?: boolean;
+}
+
+/** One client org's install of an app. Mirrors `InstallationDto`. */
+export interface InstallationResponse {
+  app_id: string;
+  client_org_id: string;
+  consented_scopes?: Array<string>;
+  created_at?: string | null;
+  install_id: string;
+  revoked_at?: string | null;
+  /** `pending`, `consented`, `revoked`, `suspended` or `expired`. */
+  status: string;
+}
+
+/** One validation problem, addressed to a line a builder can fix. */
+export interface ManifestIssueResponse {
+  /** Machine-readable cause. Stable; safe to branch on. */
+  code: string;
+  message: string;
+  /** Pointer into the document, e.g. objects[0].attributes[1].type */
+  path: string;
+}
+
+/** A `graph8.app.yaml` document, verbatim. */
+export interface ManifestRequest {
+  /** The full graph8.app.yaml document as text. Sent verbatim, including newlines. Rejected above 256 KiB by the parser. */
+  manifest: string;
+}
+
+/**
+ * What a valid manifest declares. The echo of a successful parse.
+ *
+ * Deliberately a summary and not the parsed document: a builder who wants the
+ * document already has it, and echoing it back would make this response the
+ * second place the shape is defined.
+ */
+export interface ManifestSummary {
+  app_name?: string | null;
+  app_slug?: string | null;
+  attribute_count?: number;
+  has_backend?: boolean;
+  has_frontend?: boolean;
+  object_slugs?: Array<string>;
+  version: number;
+}
+
+/** How the fan-out went, as counts. Never tenant ids -- see module docstring. */
+export interface MaterializationSummary {
+  failed?: number;
+  ready?: number;
+  /** Tenants already materialized on this exact digest. */
+  skipped?: number;
+  total?: number;
+}
+
+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;
+}
+
+/**
+ * A schema publish carries ONLY declared objects.
+ *
+ * Not a whole `graph8.app.yaml`: `frontend`/`backend` are deploy-time build
+ * config (M6-5) and have no bearing on what a tenant's `cb_*` tables receive.
+ * Accepting them here would let a Dockerfile edit re-materialize every tenant.
+ */
+export interface PublishSchemaVersionRequest {
+  /** Declared custom objects, in `graph8.app.yaml` `objects:` shape. */
+  objects: Array<unknown>;
+}
+
+/** The version, plus whether it was newly created and how the fan-out went. */
+export interface PublishSchemaVersionResponse {
+  /** False when an identical schema was already published -- the retry no-op. */
+  created: boolean;
+  materialization: MaterializationSummary;
+  version: SchemaVersionResponse;
+}
+
+/**
+ * Declare (or rotate) one secret.
+ *
+ * `provider_ref` is the ONLY writable field, and it is a pointer. A `value`
+ * field here would make every backup of the control plane a place credentials
+ * leak from, which is why the table has no column for one.
+ */
+export interface PutAppSecretRequest {
+  /** Secret-manager PATH for the value. Never the value itself. */
+  provider_ref?: string | null;
+}
+
+/** One published (or draft) object-schema version. */
+export interface SchemaVersionResponse {
+  app_id: string;
+  created_at?: string | null;
+  deprecated_at?: string | null;
+  /** SHA-256 of the canonical schema. Re-publishing the same schema resolves here. */
+  digest: string;
+  /** The stored canonical schema. Self-describing, so the version needs no other source. */
+  manifest?: Record<string, unknown>;
+  published_at?: string | null;
+  schema_version_id: string;
+  status: string;
+  /** Human-facing ordinal. Nothing keys on it; the digest is the identity. */
+  version: number;
+}
+
+/**
+ * Set an app's hard credit cap for a window.
+ *
+ * ``window`` is optional and defaults to the only value the enum has today
+ * (`calendar_month`, D5: fixed monthly allowance, monthly reset, no rollover).
+ * Accepting it explicitly now means adding a second window later does not
+ * change this DTO's shape.
+ */
+export interface SetAppLimitRequest {
+  /** Hard cap in credits for the window. `0` means 'cap at zero', NOT 'uncapped' -- to remove a cap, DELETE the limit instead. */
+  credit_cap: number;
+  /** Cap window. `calendar_month` is the only value today. */
+  window?: string;
+}
+
+/** Mirrors the portal's `setAppStatus(builderOrgId, appId, status)`. */
+export interface SetAppStatusRequest {
+  /** `draft`, `published`, `suspended` or `archived`. `active` is accepted as the legacy spelling of `published`. */
+  status: string;
+}
+
+/** Credits an app consumed in one calendar month. Mirrors `UsageSummaryDto`. */
+export interface UsageSummaryResponse {
+  app_id: string;
+  /** Everything deducted from list: the builder discount AND any hard-cap clamp. One compound number, not 'the 25%'. */
+  discount_credits?: number;
+  event_count: number;
+  /** Undiscounted list total for the period. `gross_credits - discount_credits == total_credits`. */
+  gross_credits?: number;
+  /** Credits per CLIENT org — whose data was touched, not who paid. The builder pays for all of them. */
+  per_client_credits?: Record<string, number>;
+  /** Net credits per operation id, so you can see which calls cost money. */
+  per_operation_credits?: Record<string, number>;
+  /** Net credits per BILLING org, who pays. The mirror of `per_client_credits`, which is whose data was touched. */
+  per_payer_credits?: Record<string, number>;
+  /** Calendar month, `YYYY-MM`. */
+  period: string;
+  total_credits: number;
+}
+
+/**
+ * A dry run. `valid` is the answer; `issues` is why not.
+ *
+ * 200 either way. A syntactically well-formed request that asks "is this
+ * manifest valid" and gets the answer "no" has been served correctly, and a
+ * 422 would make a builder's linter treat a working call as a transport
+ * failure.
+ */
+export interface ValidateManifestResponse {
+  issues?: Array<ManifestIssueResponse>;
+  summary?: ManifestSummary | null;
+  valid: boolean;
+}