@granular-software/sdk 0.4.56 → 0.4.58

package/dist/index.mjs

@@ -16606,24 +16606,72 @@ var Granular = class _Granular {
     if (!tagName) {
       throw new Error(`${methodName}() requires \`tag\`.`);
     }
-    const user = await this.resolveConnectUser(options);
-    if (!Array.isArray(user.permissions) || user.permissions.length === 0) {
+    const assignmentMode = options.assignmentMode ?? "ensure";
+    if (assignmentMode !== "ensure" && assignmentMode !== "require-existing") {
       throw new Error(
-        `${methodName}() requires at least one permission so the SDK can ensure assignments for new users.`
+        `${methodName}() received an unsupported assignmentMode: ${String(options.assignmentMode)}.`
       );
     }
-    const sandbox = await this.findOrCreateSandbox(ontology);
-    for (const profileName of user.permissions) {
-      const profileId = await this.ensurePermissionProfile(
-        sandbox.sandboxId,
-        profileName
+    const requiredGranularId = options.granularId?.trim();
+    if (assignmentMode === "require-existing" && (!requiredGranularId || options.userId || options.user)) {
+      throw new Error(
+        `${methodName}() with assignmentMode "require-existing" requires granularId and does not accept userId or user.`
       );
-      await this.ensureAssignment(
-        user.granularId,
-        sandbox.sandboxId,
-        profileId
+    }
+    const user = await this.resolveConnectUser(
+      assignmentMode === "require-existing" ? { ...options, granularId: requiredGranularId } : options
+    );
+    let requiredPermissionProfileId = null;
+    const sandbox = assignmentMode === "require-existing" ? { sandboxId: await this._resolveSandboxId(ontology) } : await this.findOrCreateSandbox(ontology);
+    if (assignmentMode === "require-existing") {
+      const assignments = await this.subjects.listAssignments(user.granularId);
+      const assignment = assignments.items.find(
+        (item) => item.sandboxId === sandbox.sandboxId
       );
+      if (!assignment) {
+        throw new Error(
+          `${methodName}() requires an existing assignment for subject ${user.granularId} in ontology ${sandbox.sandboxId}.`
+        );
+      }
+      const assignedPermissionProfileId = assignment.permissionProfileId?.trim();
+      if (!assignedPermissionProfileId) {
+        throw new Error(
+          `${methodName}() found an invalid assignment without a permission profile for subject ${user.granularId} in ontology ${sandbox.sandboxId}.`
+        );
+      }
+      const expectedPermissionProfileId = options.expectedPermissionProfileId?.trim();
+      if (expectedPermissionProfileId && assignedPermissionProfileId !== expectedPermissionProfileId) {
+        throw new Error(
+          `${methodName}() assignment mismatch for subject ${user.granularId}: expected permission profile ${expectedPermissionProfileId}, received ${assignedPermissionProfileId}.`
+        );
+      }
+      requiredPermissionProfileId = assignedPermissionProfileId;
+    } else {
+      if (!Array.isArray(user.permissions) || user.permissions.length === 0) {
+        throw new Error(
+          `${methodName}() requires at least one permission so the SDK can ensure assignments for new users.`
+        );
+      }
+      for (const profileName of user.permissions) {
+        const profileId = await this.ensurePermissionProfile(
+          sandbox.sandboxId,
+          profileName
+        );
+        await this.ensureAssignment(
+          user.granularId,
+          sandbox.sandboxId,
+          profileId
+        );
+      }
     }
+    const requireMatchingEnvironmentProfile = (environment2) => {
+      if (requiredPermissionProfileId && environment2.permissionProfileId !== requiredPermissionProfileId) {
+        throw new Error(
+          `${methodName}() resolved environment ${environment2.environmentId} with permission profile ${environment2.permissionProfileId || "none"}; current assignment requires ${requiredPermissionProfileId}.`
+        );
+      }
+      return environment2;
+    };
     const tags = await this.request(
       `/control/sandboxes/${sandbox.sandboxId}/tags`
     );
@@ -16646,6 +16694,9 @@ var Granular = class _Granular {
     const resolveActive = async (operationKey) => {
       const query = new URLSearchParams({ tagId: tag.tagId, slot });
       if (operationKey) query.set("operationKey", operationKey);
+      if (requiredPermissionProfileId) {
+        query.set("expectedPermissionProfileId", requiredPermissionProfileId);
+      }
       try {
         const payload = await this.request(
           `/control/sandboxes/${encodeURIComponent(sandbox.sandboxId)}/subjects/${encodeURIComponent(user.granularId)}/active-environment?${query.toString()}`
@@ -16669,7 +16720,8 @@ var Granular = class _Granular {
             tagId: tag.tagId,
             slot,
             operationKey: resetKey,
-            operation: resetKey ? "explicit_reset" : void 0
+            operation: resetKey ? "explicit_reset" : void 0,
+            expectedPermissionProfileId: requiredPermissionProfileId || void 0
           })
         }
       );
@@ -16679,7 +16731,7 @@ var Granular = class _Granular {
       const resetEnvironment = await resolveActive(resetKey);
       if (resetEnvironment) {
         return {
-          environment: resetEnvironment,
+          environment: requireMatchingEnvironmentProfile(resetEnvironment),
           requestedOntology: ontology,
           sandboxId: sandbox.sandboxId,
           subjectId: user.granularId,
@@ -16695,7 +16747,7 @@ var Granular = class _Granular {
       const active = await resolveActive();
       if (active && (active.versionId === targetVersionId || options.createFreshIfOutdated !== true)) {
         return {
-          environment: active,
+          environment: requireMatchingEnvironmentProfile(active),
           requestedOntology: ontology,
           sandboxId: sandbox.sandboxId,
           subjectId: user.granularId,
@@ -16713,7 +16765,10 @@ var Granular = class _Granular {
       )
     );
     if (!resetKey && currentMatches.length > 0) {
-      const environment2 = await activate(currentMatches[0]);
+      requireMatchingEnvironmentProfile(currentMatches[0]);
+      const environment2 = requireMatchingEnvironmentProfile(
+        await activate(currentMatches[0])
+      );
       return {
         environment: environment2,
         requestedOntology: ontology,
@@ -16726,7 +16781,10 @@ var Granular = class _Granular {
       userEnvironments.filter((environment2) => environment2.tagId === tag.tagId)
     );
     if (outdatedMatches.length > 0 && options.createFreshIfOutdated !== true) {
-      const environment2 = await activate(outdatedMatches[0]);
+      requireMatchingEnvironmentProfile(outdatedMatches[0]);
+      const environment2 = requireMatchingEnvironmentProfile(
+        await activate(outdatedMatches[0])
+      );
       return {
         environment: environment2,
         requestedOntology: ontology,
@@ -16745,7 +16803,10 @@ var Granular = class _Granular {
       tagId: tag.tagId,
       permissionProfileId: null
     });
-    const environment = await activate(created);
+    requireMatchingEnvironmentProfile(created);
+    const environment = requireMatchingEnvironmentProfile(
+      await activate(created)
+    );
     return {
       environment,
       requestedOntology: ontology,
@@ -16955,22 +17016,16 @@ var Granular = class _Granular {
       metadata: options?.metadata
     });
   }
-  /**
-   * Mark a session closed in the control plane. If `environment` is the connected handle for that
-   * `sessionId`, disconnects the WebSocket so the runtime tears down cleanly.
-   */
+  /** End a session through the runtime, or disconnect its connected handle. */
   async closeSession(sessionId, environment) {
     if (environment && environment.sessionId === sessionId) {
       await environment.disconnect();
       return;
     }
-    await this.request(`/control/sessions/${encodeURIComponent(sessionId)}`, {
-      method: "PATCH",
-      body: JSON.stringify({
-        status: "closed",
-        lastSeenAt: (/* @__PURE__ */ new Date()).toISOString()
-      })
-    });
+    await this.request(
+      `/control/sessions/${encodeURIComponent(sessionId)}/close`,
+      { method: "POST" }
+    );
   }
   /**
    * Re-open a closed session in the index and connect to its existing runtime document.