@graph8/sdk 0.251.0 → 0.260.0

package/docs/api/appDeployments.d.ts

@@ -0,0 +1,236 @@
+/* Generated by sdk/js/scripts/generate-agent-docs.ts from developer-contract/openapi.json. Regenerated on every build. */
+
+/**
+ * Types for `g8.api.appDeployments` (App Deployments): 7 operations.
+ *
+ * For reading. In code, import from the package instead:
+ *   import type { ApiInput, ApiOutput, G8Contract } from "@graph8/sdk";
+ *   type In = ApiInput<"create_app_deployment_apps__app_id__deployments_post">;
+ *
+ * Reference with examples: appDeployments.md
+ */
+/* eslint-disable */
+
+/** `g8.api.appDeployments.<member>` -> the operationId it calls. */
+export interface AppDeploymentsMembers {
+  createAppDeployment: "create_app_deployment_apps__app_id__deployments_post";
+  getActiveDeployment: "get_active_deployment_apps__app_id__deployments_active_get";
+  getDeployment: "get_deployment_apps__app_id__deployments__deployment_id__get";
+  listAppDeployments: "list_app_deployments_apps__app_id__deployments_get";
+  promoteDeployment: "promote_deployment_apps__app_id__deployments__deployment_id__promote_post";
+  reportDeploymentProgress: "report_deployment_progress_apps__app_id__deployments__deployment_id__status_post";
+  rollbackDeployment: "rollback_deployment_apps__app_id__deployments__deployment_id__rollback_post";
+}
+
+/** Input and output of every `g8.api.appDeployments` operation, keyed by operationId. */
+export interface AppDeploymentsOperations {
+  /**
+   * POST /apps/{app_id}/deployments
+   * Create App Deployment
+   * tier: write · scope: apps:write
+   */
+  create_app_deployment_apps__app_id__deployments_post: {
+    input: {
+    path: {
+      app_id: string;
+    };
+    headers?: {
+      "X-Org-Id"?: string | null;
+    };
+    body: CreateDeploymentRequest;
+  };
+    output: ApiResponse_DeploymentResponse_;
+  };
+  /**
+   * GET /apps/{app_id}/deployments/active
+   * Get Active Deployment
+   * tier: read · scope: apps:read
+   */
+  get_active_deployment_apps__app_id__deployments_active_get: {
+    input: {
+    path: {
+      app_id: string;
+    };
+    headers?: {
+      "X-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_Union_DeploymentResponse__NoneType__;
+  };
+  /**
+   * GET /apps/{app_id}/deployments/{deployment_id}
+   * Get Deployment
+   * tier: read · scope: apps:read
+   */
+  get_deployment_apps__app_id__deployments__deployment_id__get: {
+    input: {
+    path: {
+      app_id: string;
+      deployment_id: string;
+    };
+    headers?: {
+      "X-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_DeploymentResponse_;
+  };
+  /**
+   * GET /apps/{app_id}/deployments
+   * List App Deployments
+   * tier: read · scope: apps:read
+   */
+  list_app_deployments_apps__app_id__deployments_get: {
+    input: {
+    path: {
+      app_id: string;
+    };
+    headers?: {
+      "X-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_list_DeploymentResponse__;
+  };
+  /**
+   * POST /apps/{app_id}/deployments/{deployment_id}/promote
+   * Promote Deployment
+   * tier: write · scope: apps:write
+   */
+  promote_deployment_apps__app_id__deployments__deployment_id__promote_post: {
+    input: {
+    path: {
+      app_id: string;
+      deployment_id: string;
+    };
+    headers?: {
+      "X-Org-Id"?: string | null;
+    };
+    body: PromoteDeploymentRequest;
+  };
+    output: ApiResponse_DeploymentResponse_;
+  };
+  /**
+   * POST /apps/{app_id}/deployments/{deployment_id}/status
+   * Report Deployment Progress
+   * tier: write · scope: n/a
+   */
+  report_deployment_progress_apps__app_id__deployments__deployment_id__status_post: {
+    input: {
+    path: {
+      app_id: string;
+      deployment_id: string;
+    };
+    headers?: {
+      "x-build-controller-token"?: string | null;
+    };
+    body: DeploymentProgressRequest;
+  };
+    output: ApiResponse_DeploymentResponse_;
+  };
+  /**
+   * POST /apps/{app_id}/deployments/{deployment_id}/rollback
+   * Rollback Deployment
+   * tier: write · scope: apps:write
+   */
+  rollback_deployment_apps__app_id__deployments__deployment_id__rollback_post: {
+    input: {
+    path: {
+      app_id: string;
+      deployment_id: string;
+    };
+    headers?: {
+      "X-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_DeploymentResponse_;
+  };
+}
+
+// 8 schemas referenced above (the same as G8Contract.<Name>).
+
+export interface ApiResponse_DeploymentResponse_ {
+  data: DeploymentResponse;
+  pagination?: PaginationMeta | null;
+}
+
+export interface ApiResponse_Union_DeploymentResponse__NoneType__ {
+  data: DeploymentResponse | null;
+  pagination?: PaginationMeta | null;
+}
+
+export interface ApiResponse_list_DeploymentResponse__ {
+  data: Array<DeploymentResponse>;
+  pagination?: PaginationMeta | null;
+}
+
+/**
+ * Start a deployment from a pinned source ref.
+ *
+ * ``source_ref`` is a COMMIT-ish, not a branch name. A branch moves, so a
+ * deployment recorded against one cannot answer "what is running right now" a
+ * week later -- which is the question a rollback has to answer.
+ */
+export interface CreateDeploymentRequest {
+  /** Schema version this build expects. Pinned so a rollback restores the matching schema, not merely the matching image. */
+  schema_version_id?: string | null;
+  /** Immutable source reference (commit SHA). Branches move; deployments must not. */
+  source_ref: string;
+}
+
+/**
+ * What the in-cluster build controller reports as a build advances (J2).
+ *
+ * THE ALLOWED SET IS `building | promoting | failed`, AND `deployed` IS ABSENT
+ * ON PURPOSE. The controller knows when a build started and when an image is
+ * pushed and ready. It does not decide that the app should take traffic; that is
+ * `POST .../promote`, a separate act by the builder. Letting the callback write
+ * `deployed` would collapse "the build finished" and "send users at it" into one
+ * step performed by whichever pod happened to run the build.
+ *
+ * `rolled_back` is likewise absent: a rollback is a decision about a deployment
+ * that is already serving, which a builder makes.
+ */
+export interface DeploymentProgressRequest {
+  /** The pushed image digest, once there is one. Reported with `promoting`. */
+  image_digest?: string | null;
+  /** A short, ALREADY-SANITIZED failure reason, surfaced to the builder. Build logs carry secrets and other tenants' identifiers, so the controller sanitizes before sending and this field is truncated here. */
+  last_error_sanitized?: string | null;
+  /** Where the build has reached. `deployed` is not settable here -- taking traffic is a separate, builder-initiated promote. */
+  status: "building" | "promoting" | "failed";
+}
+
+export interface DeploymentResponse {
+  app_id: string;
+  /** When the build ended, at `promoting` or at `failed`. Not at `deployed`: that is reached after traffic is taken, so measuring to it would count promotion and rollout as build time. */
+  build_finished_at?: string | null;
+  /** Measured build duration. `null` means NOT MEASURED, never zero: a build whose transitions were not reported has no duration, and a metering pipeline reading 0 would bill nothing and look correct. */
+  build_seconds?: number | null;
+  /** When the build started. `null` means it was not measured. */
+  build_started_at?: string | null;
+  created_at?: string | null;
+  deployed_at?: string | null;
+  deployment_id: string;
+  image_digest?: string | null;
+  /** Sanitized at the write. Build logs carry secrets and other tenants' ids. */
+  last_error_sanitized?: string | null;
+  schema_version_id?: string | null;
+  source_ref?: string | null;
+  status: 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;
+}
+
+export interface PromoteDeploymentRequest {
+  /** The built image digest being promoted. Recorded so a rollback targets an artifact rather than a rebuild. */
+  image_digest: string;
+}