@granular-software/sdk 0.4.52 → 0.4.54

package/dist/index.mjs

@@ -14431,6 +14431,7 @@ var Environment = class _Environment {
       import: async (records, options) => this.enqueueRecordImport(records, options),
       listImports: async (status) => this.listRecordImports(status),
       getImport: async (importId) => this.getRecordImport(importId),
+      listImportItems: async (importId, status) => this.listRecordImportItems(importId, status),
       getImportSummary: async () => this.getRecordImportSummary(),
       cancelImport: async (importId) => this.cancelRecordImport(importId),
       getAwaitingCount: async () => this.getAwaitingRecordCount()
@@ -15609,6 +15610,15 @@ var Environment = class _Environment {
       `/control/record-imports/${importId}`
     );
   }
+  /**
+   * List the individual records persisted for one asynchronous import. This
+   * makes terminal import failures diagnosable without database access.
+   */
+  async listRecordImportItems(importId, status) {
+    const suffix = status ? `?status=${encodeURIComponent(status)}` : "";
+    const response = await this.controlPlaneRequest(`/control/record-imports/${importId}/items${suffix}`);
+    return Array.isArray(response.items) ? response.items : [];
+  }
   /**
    * Cancel a queued/background record import.
    */
@@ -16425,6 +16435,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