palbase 0.31.0 → 0.32.0

package/types/internal/src/modules/machines.d.ts

@@ -307,7 +307,7 @@ export type MachineCreate = {
      */
     always_on?: boolean;
     /**
-     * Whether a pull request opened against its branch is previewed: its head built into a machine of its own, <name>-pr<n>, in this environment, with this environment's settings and secrets, answering at <name>-pr<n>-<ref> until the pull request closes; the pull request is told where in a comment. Turn it on in an environment kept for previews, not production's: the pull request's code runs with the environment's secrets. A machine read with Palbase's GitHub App alone (source.access app).
+     * Whether a pull request opened against its branch is previewed: its head built into a machine of its own, <name>-pr<n>, in this environment, with this environment's settings and secrets, answering at <name>-pr<n>-<ref> until the pull request closes; the pull request is told where in a comment. Turn it on in an environment kept for previews, not production's: the pull request's code runs with the environment's secrets. A machine read with a platform's tokens (source.access token) previews what its platform puts (PUT /machines/{name}/previews/{pull_request}), no comment written.
      */
     previews?: boolean;
     /**
@@ -1857,6 +1857,23 @@ export type PreviewOpened = {
      */
     commit: string;
 };
+/**
+ * A platform's pull request: its branch — one of the machine's repository's own — the head its machine's preview builds, and the token it is read with.
+ */
+export type PreviewDeploy = {
+    /**
+     * The pull request's branch, of the machine's repository itself: a fork's pull request is not built with the environment's secrets.
+     */
+    branch: string;
+    /**
+     * The branch's head, its full SHA: a newer push answers 409 commit_not_head. Left out, the branch's head.
+     */
+    commit?: string;
+    /**
+     * A GitHub App installation's token (ghs_…) for the machine's repository alone, read-only: used once, never kept.
+     */
+    git_access_token: string;
+};
 /** Palbase Machines */
 export declare function client(t: Transport): {
     /**
@@ -2024,6 +2041,31 @@ export declare function client(t: Transport): {
         }; /** Stops the call: the request in flight, a wait before a retry, a proof-of-work being solved. */
         signal?: AbortSignal;
     }): Promise<Reply<200, PreviewList>>;
+    /**
+     * Open or update a platform's pull request preview
+     *
+     * For a machine read with a platform's tokens (source.access token: PalCore's, whose repositories have no Palbase App, so no pull request is heard here): opens the preview of the pull request at the head of its branch — one of the machine's repository's own: a fork's is not built — its own machine, <name>-pr<n>, and a database of its own when the machine runs its database's migrations — or builds the open one at it, and opens one that went idle again. The branch is read with git_access_token, a GitHub App installation's token for the machine's repository alone (ghs_…), once; a commit named must be the branch's head (409 commit_not_head). Its address and state are read with GET /machines/{name}/previews; the platform tells its pull request itself. Refused in a production environment (409 previews_in_production), for a machine read with Palbase's GitHub App (409 previews_from_github), with previews off (409 previews_off), and when the environment's limits refuse the preview (409 preview_refused, with why).
+     */
+    putMachinePreview(input: {
+        path: {
+            name: string; /** The pull request's number. */
+            pull_request: number;
+        };
+        body: PreviewDeploy; /** Stops the call: the request in flight, a wait before a retry, a proof-of-work being solved. */
+        signal?: AbortSignal;
+    }): Promise<Reply<202, PreviewOpened>>;
+    /**
+     * Close a platform's pull request preview
+     *
+     * For a machine read with a platform's tokens: closes the preview of the pull request, its pull request closed — its machine and its own database are deleted at once. A machine read with Palbase's GitHub App has its previews closed as GitHub tells (409 previews_from_github).
+     */
+    deleteMachinePreview(input: {
+        path: {
+            name: string; /** The pull request's number. */
+            pull_request: number;
+        }; /** Stops the call: the request in flight, a wait before a retry, a proof-of-work being solved. */
+        signal?: AbortSignal;
+    }): Promise<Reply<204, undefined>>;
     /**
      * List a machine's domains
      *
@@ -2721,7 +2763,7 @@ export declare function client(t: Transport): {
     /**
      * Open a machine's pull request preview again
      *
-     * Opens a machine's preview of an open pull request again, at the pull request's head: one closed for want of a push (state idle: no push for 3 days, its machine and its own database taken away) or refused at its last push (state refused) is made anew, with a new, empty database of its own when the machine runs its database's migrations. One open goes on as it is, and its 3 days start again. A fork's preview under fork protection opens only at a head an admin authorized (409 preview_waits_authorization); one the environment's limits refuse again answers 409 preview_refused, with why.
+     * Opens a machine's preview of an open pull request again, at the pull request's head: one closed for want of a push (state idle: no push for 3 days, its machine and its own database taken away) or refused at its last push (state refused) is made anew, with a new, empty database of its own when the machine runs its database's migrations. One open goes on as it is, and its 3 days start again. A fork's preview under fork protection opens only at a head an admin authorized (409 preview_waits_authorization); one the environment's limits refuse again answers 409 preview_refused, with why. A machine read with a platform's tokens has an idle or refused preview opened again by its platform, with a token (PUT /machines/{name}/previews/{pull_request}): 409 preview_needs_token.
      */
     openMachinePreview(input: {
         path: {