@granular-software/sdk 0.4.52 → 0.4.53

package/dist/index.mjs

@@ -16425,6 +16425,55 @@ var Granular = class _Granular {
       throw error;
     }
   }
+  /**
+   * Resolve one exact environment only when Granular confirms that it belongs
+   * to the given external user in the requested sandbox (and, optionally,
+   * tag). This is deliberately read-only: callers use it to keep an already
+   * opened delegated workspace stable while a newer active environment is
+   * being prepared in the background.
+   */
+  async getEnvironmentForUser(options) {
+    const sandboxId = options.sandboxId.trim();
+    const userId = options.userId.trim();
+    const environmentId = options.environmentId.trim();
+    const tagName = options.tag?.trim();
+    if (!sandboxId || !userId || !environmentId) {
+      throw new Error(
+        "getEnvironmentForUser() requires sandboxId, userId, and environmentId."
+      );
+    }
+    const subjects = await this.request(
+      `/control/subjects?identityId=${encodeURIComponent(userId)}`
+    );
+    const subject = (subjects.items || []).find(
+      (item) => item.identityId === userId || item.userId === userId
+    );
+    const subjectId = subject?.subjectId || subject?.granularId;
+    if (!subjectId) return null;
+    let environment;
+    try {
+      environment = await this.environments.get(environmentId);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      if (message.includes("404") || message.includes("not found")) {
+        return null;
+      }
+      throw error;
+    }
+    if (environment.sandboxId !== sandboxId || environment.subjectId !== subjectId) {
+      return null;
+    }
+    if (tagName) {
+      const tags = await this.request(`/control/sandboxes/${encodeURIComponent(sandboxId)}/tags`);
+      const tag = (tags.items || []).find(
+        (candidate) => candidate?.name === tagName
+      );
+      if (!tag || environment.tagId !== tag.tagId) {
+        return null;
+      }
+    }
+    return this.bindEnvironmentHandle(environment);
+  }
   /**
    * Register one reviewed, pre-existing environment as the active workspace
    * for an external user. This is for a controlled migration only: it does