@wix/auto_sdk_containers_projects 1.0.3 → 1.0.5

package/build/es/index.typings.d.mts

@@ -70,6 +70,16 @@ interface Project {
      * @maxLength 2000
      */
     appIconUrl?: string | null;
+    /**
+     * The Himalaya release the editor is currently on — the "head" the client previews and the next
+     * edit (design save or AI edit) branches from. Server-managed: set to the new draft after each
+     * edit, and to the chosen release by RestoreRelease. Unset means "newest release by date" (the
+     * pre-head default), so existing projects keep working until their first edit/restore sets it.
+     * Not a GUID — a Himalaya release id (e.g. `rel-<hash>` / `<sha>-<hash>`).
+     * @maxLength 200
+     * @readonly
+     */
+    headReleaseId?: string | null;
 }
 declare enum ProjectStatus {
     /** Project created; client (via containers-plans) is doing most of the work. */
@@ -527,6 +537,17 @@ interface SaveProjectDesignRequest {
      * @maxLength 200
      */
     canonicalApp?: string;
+    /**
+     * Conversation this design is saved from. When set, a CHECKPOINT message marking the saved
+     * version is posted into it (best-effort). Optional — an older client that omits it still saves
+     * the design; it just produces no checkpoint. Verified to belong to this project server-side.
+     *
+     * Deliberately NOT (.wix.api.format) = GUID: posting the checkpoint is best-effort and must never
+     * fail the save. A malformed/unexpected id is handled downstream (the ownership lookup rejects it
+     * and the checkpoint is skipped) rather than hard-failing SaveProjectDesign at the request boundary.
+     * @maxLength 100
+     */
+    conversationId?: string;
 }
 interface SaveProjectDesignResponse {
     /**
@@ -543,6 +564,43 @@ interface SaveProjectDesignResponse {
     /** When preview_token expires. */
     previewTokenExpiresAt?: Date | null;
 }
+interface RestoreReleaseRequest {
+    /**
+     * Project whose head is being moved. The caller must own it.
+     * @format GUID
+     */
+    projectId: string;
+    /**
+     * The Himalaya release to make the project's editable head. Not a GUID — a Himalaya release id
+     * (e.g. `rel-<hash>` / `<sha>-<hash>`), taken from the project's own release ledger.
+     * @maxLength 200
+     */
+    releaseId: string;
+    /**
+     * Short-lived, app-scoped Himalaya control credential (the same the client obtains from Himalaya's
+     * owner embed-token endpoint and sends on SaveProjectDesign). When present, the server verifies
+     * release_id belongs to this project's Himalaya app before moving head. Optional for back-compat:
+     * an older client that omits it skips that check (the release still comes from the project's own
+     * ledger). Forwarded to Himalaya for the ledger read only — never logged, persisted, or echoed.
+     * @maxLength 4096
+     */
+    himalayaControlToken?: string;
+    /**
+     * Conversation this restore is made from. When set, a CHECKPOINT message marking the restored
+     * version is posted into it (best-effort). Optional — a client that omits it still restores; it
+     * just produces no checkpoint. Verified to belong to this project server-side.
+     *
+     * Deliberately NOT (.wix.api.format) = GUID: posting the checkpoint is best-effort and must never
+     * fail the restore. A malformed id is handled downstream (the ownership lookup rejects it and the
+     * checkpoint is skipped) rather than hard-failing RestoreRelease at the request boundary.
+     * @maxLength 100
+     */
+    conversationId?: string;
+}
+interface RestoreReleaseResponse {
+    /** The project after the restore, with head_release_id set to the restored release. */
+    project?: Project;
+}
 interface ListProjectsRequest {
     /** Cursor paging options. */
     paging?: CursorPaging;
@@ -590,6 +648,7 @@ interface GetHimalayaAuthorizationResponse {
  * @documentationMaturity preview
  * @requiredField projectId
  * @permissionId containers:projects:v1:project:get_project
+ * @applicableIdentity APP
  * @returns The requested Project.
  * @fqn wix.containers.projects.v1.ContainersProjects.GetProject
  */
@@ -664,6 +723,16 @@ interface UpdateProject {
      * @maxLength 2000
      */
     appIconUrl?: string | null;
+    /**
+     * The Himalaya release the editor is currently on — the "head" the client previews and the next
+     * edit (design save or AI edit) branches from. Server-managed: set to the new draft after each
+     * edit, and to the chosen release by RestoreRelease. Unset means "newest release by date" (the
+     * pre-head default), so existing projects keep working until their first edit/restore sets it.
+     * Not a GUID — a Himalaya release id (e.g. `rel-<hash>` / `<sha>-<hash>`).
+     * @maxLength 200
+     * @readonly
+     */
+    headReleaseId?: string | null;
 }
 /**
  * Requests Project resume by starting or reusing its configured remote machine asynchronously.
@@ -672,6 +741,7 @@ interface UpdateProject {
  * @documentationMaturity preview
  * @requiredField projectId
  * @permissionId containers:projects:v1:project:resume_project
+ * @applicableIdentity APP
  * @fqn wix.containers.projects.v1.ContainersProjects.ResumeProject
  */
 declare function resumeProject(projectId: string): Promise<NonNullablePaths<ResumeProjectResponse, `project.name` | `project.status` | `project.sandboxStatus` | `project.metaSiteIds` | `project.platform`, 1>>;
@@ -681,8 +751,9 @@ declare function resumeProject(projectId: string): Promise<NonNullablePaths<Resu
  *
  * Synchronous: the Himalaya write completes before this call returns. Never touches the project's
  * sandbox, runs a build, or activates the app — the saved release stays a draft, so what the live
- * app serves is unaffected. Persists nothing on our side: this creates no entity and posts no
- * chat checkpoint.
+ * app serves is unaffected. Persists no entity of its own. When `conversation_id` is supplied it
+ * posts a CHECKPOINT message for the saved release into that conversation (best-effort — a chat
+ * failure never fails the save); omit it to skip the checkpoint.
  * @param projectId - Project whose design is being saved. The caller must own it.
  * @param baseReleaseId - The Himalaya release ID currently displayed by the client. The saved draft branches from
  * exactly this release, even when a newer release exists for the app.
@@ -693,6 +764,7 @@ declare function resumeProject(projectId: string): Promise<NonNullablePaths<Resu
  * @requiredField options.tokensJson
  * @requiredField projectId
  * @permissionId containers:projects:v1:project:save_project_design
+ * @applicableIdentity APP
  * @fqn wix.containers.projects.v1.ContainersProjects.SaveProjectDesign
  */
 declare function saveProjectDesign(projectId: string, baseReleaseId: string, options?: NonNullablePaths<SaveProjectDesignOptions, `himalayaControlToken` | `tokensJson`, 0>): Promise<NonNullablePaths<SaveProjectDesignResponse, `himalayaReleaseId` | `previewToken`, 0>>;
@@ -720,6 +792,61 @@ interface SaveProjectDesignOptions {
      * @maxLength 200
      */
     canonicalApp?: string;
+    /**
+     * Conversation this design is saved from. When set, a CHECKPOINT message marking the saved
+     * version is posted into it (best-effort). Optional — an older client that omits it still saves
+     * the design; it just produces no checkpoint. Verified to belong to this project server-side.
+     *
+     * Deliberately NOT (.wix.api.format) = GUID: posting the checkpoint is best-effort and must never
+     * fail the save. A malformed/unexpected id is handled downstream (the ownership lookup rejects it
+     * and the checkpoint is skipped) rather than hard-failing SaveProjectDesign at the request boundary.
+     * @maxLength 100
+     */
+    conversationId?: string;
+}
+/**
+ * Restores an earlier version by pointing the project's editable head at `release_id`: the client
+ * then previews that release and the next edit (design save or AI edit) branches from it. Pure
+ * project state — sets `head_release_id` and nothing in Himalaya: it does NOT activate the release,
+ * so the live app end-users run is untouched (a later publish/build is what carries head live).
+ *
+ * `release_id` is a Himalaya release id the caller already holds from the project's own release
+ * ledger, scoped to this project's app; the server stores it as head without re-reading Himalaya.
+ * When `conversation_id` is supplied, a CHECKPOINT message for the restored release is posted into
+ * it (best-effort — a chat failure never fails the restore); omit it to skip the checkpoint.
+ * @param projectId - Project whose head is being moved. The caller must own it.
+ * @param releaseId - The Himalaya release to make the project's editable head. Not a GUID — a Himalaya release id
+ * (e.g. `rel-<hash>` / `<sha>-<hash>`), taken from the project's own release ledger.
+ * @public
+ * @documentationMaturity preview
+ * @requiredField projectId
+ * @requiredField releaseId
+ * @permissionId containers:projects:v1:project:restore_release
+ * @applicableIdentity APP
+ * @fqn wix.containers.projects.v1.ContainersProjects.RestoreRelease
+ */
+declare function restoreRelease(projectId: string, releaseId: string, options?: RestoreReleaseOptions): Promise<NonNullablePaths<RestoreReleaseResponse, `project.name` | `project.status` | `project.sandboxStatus` | `project.metaSiteIds` | `project.platform`, 1>>;
+interface RestoreReleaseOptions {
+    /**
+     * Short-lived, app-scoped Himalaya control credential (the same the client obtains from Himalaya's
+     * owner embed-token endpoint and sends on SaveProjectDesign). When present, the server verifies
+     * release_id belongs to this project's Himalaya app before moving head. Optional for back-compat:
+     * an older client that omits it skips that check (the release still comes from the project's own
+     * ledger). Forwarded to Himalaya for the ledger read only — never logged, persisted, or echoed.
+     * @maxLength 4096
+     */
+    himalayaControlToken?: string;
+    /**
+     * Conversation this restore is made from. When set, a CHECKPOINT message marking the restored
+     * version is posted into it (best-effort). Optional — a client that omits it still restores; it
+     * just produces no checkpoint. Verified to belong to this project server-side.
+     *
+     * Deliberately NOT (.wix.api.format) = GUID: posting the checkpoint is best-effort and must never
+     * fail the restore. A malformed id is handled downstream (the ownership lookup rejects it and the
+     * checkpoint is skipped) rather than hard-failing RestoreRelease at the request boundary.
+     * @maxLength 100
+     */
+    conversationId?: string;
 }
 interface ListProjectsOptions {
     /** Cursor paging options. */
@@ -733,8 +860,9 @@ interface ListProjectsOptions {
  * @documentationMaturity preview
  * @requiredField projectId
  * @permissionId containers:projects:v1:project:get_himalaya_authorization
+ * @applicableIdentity APP
  * @fqn wix.containers.projects.v1.ContainersProjects.GetHimalayaAuthorization
  */
 declare function getHimalayaAuthorization(projectId: string): Promise<NonNullablePaths<GetHimalayaAuthorizationResponse, `authorizationVersion` | `metaSiteId` | `projectId` | `canonicalApp` | `workerLaunch` | `saveDesign`, 0>>;
 
-export { type AccountInfo, type ActionEvent, type CreateAgentSessionRequest, type CreateAgentSessionResponse, type CreateProjectRequest, type CreateProjectResponse, type CursorPaging, type CursorPagingMetadata, type Cursors, type DeleteProjectRequest, type DeleteProjectResponse, type DomainEvent, type DomainEventBodyOneOf, type EntityCreatedEvent, type EntityDeletedEvent, type EntityUpdatedEvent, type GetHimalayaAuthorizationRequest, type GetHimalayaAuthorizationResponse, type GetProjectRequest, type GetProjectResponse, type IdentificationData, type IdentificationDataIdOneOf, type ListProjectsForCurrentUserRequest, type ListProjectsForCurrentUserResponse, type ListProjectsOptions, type ListProjectsRequest, type ListProjectsResponse, type MessageEnvelope, Platform, type PlatformWithLiterals, type Project, type ProjectPlanReady, type ProjectResumeRequested, type ProjectStartRequested, ProjectStatus, type ProjectStatusWithLiterals, type RefreshAgentSiteTokenRequest, type RefreshAgentSiteTokenResponse, type RegenerateProjectIconRequest, type RegenerateProjectIconResponse, type RegenerateProjectNameRequest, type RegenerateProjectNameResponse, type RestoreInfo, type ResumeProjectRequest, type ResumeProjectResponse, SandboxStatus, type SandboxStatusWithLiterals, type SaveProjectDesignOptions, type SaveProjectDesignRequest, type SaveProjectDesignResponse, type StartProjectRequest, type StartProjectResponse, type UpdateProject, type UpdateProjectRequest, type UpdateProjectResponse, WebhookIdentityType, type WebhookIdentityTypeWithLiterals, getHimalayaAuthorization, getProject, resumeProject, saveProjectDesign };
+export { type AccountInfo, type ActionEvent, type CreateAgentSessionRequest, type CreateAgentSessionResponse, type CreateProjectRequest, type CreateProjectResponse, type CursorPaging, type CursorPagingMetadata, type Cursors, type DeleteProjectRequest, type DeleteProjectResponse, type DomainEvent, type DomainEventBodyOneOf, type EntityCreatedEvent, type EntityDeletedEvent, type EntityUpdatedEvent, type GetHimalayaAuthorizationRequest, type GetHimalayaAuthorizationResponse, type GetProjectRequest, type GetProjectResponse, type IdentificationData, type IdentificationDataIdOneOf, type ListProjectsForCurrentUserRequest, type ListProjectsForCurrentUserResponse, type ListProjectsOptions, type ListProjectsRequest, type ListProjectsResponse, type MessageEnvelope, Platform, type PlatformWithLiterals, type Project, type ProjectPlanReady, type ProjectResumeRequested, type ProjectStartRequested, ProjectStatus, type ProjectStatusWithLiterals, type RefreshAgentSiteTokenRequest, type RefreshAgentSiteTokenResponse, type RegenerateProjectIconRequest, type RegenerateProjectIconResponse, type RegenerateProjectNameRequest, type RegenerateProjectNameResponse, type RestoreInfo, type RestoreReleaseOptions, type RestoreReleaseRequest, type RestoreReleaseResponse, type ResumeProjectRequest, type ResumeProjectResponse, SandboxStatus, type SandboxStatusWithLiterals, type SaveProjectDesignOptions, type SaveProjectDesignRequest, type SaveProjectDesignResponse, type StartProjectRequest, type StartProjectResponse, type UpdateProject, type UpdateProjectRequest, type UpdateProjectResponse, WebhookIdentityType, type WebhookIdentityTypeWithLiterals, getHimalayaAuthorization, getProject, restoreRelease, resumeProject, saveProjectDesign };

package/build/es/index.typings.mjs

@@ -248,6 +248,33 @@ function saveProjectDesign(payload) {
   }
   return __saveProjectDesign;
 }
+function restoreRelease(payload) {
+  function __restoreRelease({ host }) {
+    const metadata = {
+      entityFqdn: "wix.containers.projects.v1.project",
+      method: "POST",
+      methodFqn: "wix.containers.projects.v1.ContainersProjects.RestoreRelease",
+      packageName: PACKAGE_NAME,
+      migrationOptions: {
+        optInTransformResponse: true
+      },
+      url: resolveWixContainersProjectsV1ContainersProjectsUrl({
+        protoPath: "/v1/projects/{projectId}/restore-release",
+        data: payload,
+        host
+      }),
+      data: payload,
+      transformResponse: (payload2) => transformPaths(payload2, [
+        {
+          transformFn: transformRESTTimestampToSDKTimestamp,
+          paths: TRANSFORM_PATHS_0
+        }
+      ])
+    };
+    return metadata;
+  }
+  return __restoreRelease;
+}
 function listProjects(payload) {
   function __listProjects({ host }) {
     const metadata = {
@@ -504,7 +531,8 @@ async function saveProjectDesign2(projectId, baseReleaseId, options) {
     baseReleaseId,
     tokensJson: options?.tokensJson,
     himalayaControlToken: options?.himalayaControlToken,
-    canonicalApp: options?.canonicalApp
+    canonicalApp: options?.canonicalApp,
+    conversationId: options?.conversationId
   });
   const reqOpts = saveProjectDesign(payload);
   sideEffects?.onSiteCall?.();
@@ -522,7 +550,8 @@ async function saveProjectDesign2(projectId, baseReleaseId, options) {
           baseReleaseId: "$[1]",
           tokensJson: "$[2].tokensJson",
           himalayaControlToken: "$[2].himalayaControlToken",
-          canonicalApp: "$[2].canonicalApp"
+          canonicalApp: "$[2].canonicalApp",
+          conversationId: "$[2].conversationId"
         },
         singleArgumentUnchanged: false
       },
@@ -532,6 +561,39 @@ async function saveProjectDesign2(projectId, baseReleaseId, options) {
     throw transformedError;
   }
 }
+async function restoreRelease2(projectId, releaseId, options) {
+  const { httpClient, sideEffects } = arguments[3];
+  const payload = renameKeysFromSDKRequestToRESTRequest({
+    projectId,
+    releaseId,
+    himalayaControlToken: options?.himalayaControlToken,
+    conversationId: options?.conversationId
+  });
+  const reqOpts = restoreRelease(payload);
+  sideEffects?.onSiteCall?.();
+  try {
+    const result = await httpClient.request(reqOpts);
+    sideEffects?.onSuccess?.(result);
+    return renameKeysFromRESTResponseToSDKResponse(result.data);
+  } catch (err) {
+    const transformedError = sdkTransformError(
+      err,
+      {
+        spreadPathsToArguments: {},
+        explicitPathsToArguments: {
+          projectId: "$[0]",
+          releaseId: "$[1]",
+          himalayaControlToken: "$[2].himalayaControlToken",
+          conversationId: "$[2].conversationId"
+        },
+        singleArgumentUnchanged: false
+      },
+      ["projectId", "releaseId", "options"]
+    );
+    sideEffects?.onError?.(err);
+    throw transformedError;
+  }
+}
 async function listProjects2(options) {
   const { httpClient, sideEffects } = arguments[1];
   const payload = renameKeysFromSDKRequestToRESTRequest({
@@ -594,6 +656,7 @@ export {
   listProjects2 as listProjects,
   regenerateProjectIcon2 as regenerateProjectIcon,
   regenerateProjectName2 as regenerateProjectName,
+  restoreRelease2 as restoreRelease,
   resumeProject2 as resumeProject,
   saveProjectDesign2 as saveProjectDesign,
   updateProject2 as updateProject