@granular-software/sdk 0.4.5 → 0.4.7

package/dist/index.mjs

@@ -4481,6 +4481,8 @@ var Session = class {
       environmentId: "",
       sessionId: "",
       user: {
+        granularId: "",
+        userId: "",
         subjectId: ""
       }
     };
@@ -4555,7 +4557,8 @@ var Session = class {
    * ```typescript
    * import { Author, Book, global_search } from './sandbox-tools';
    *
-   * const tolkien = await Author.find({ id: 'tolkien' });
+   * const authors = await Author.list({ limit: 10, saveAs: 'recent_authors' });
+   * const tolkien = await Author.get({ path: 'author_tolkien' });
    * const bio = await tolkien.get_bio({ detailed: true });
    * const books = await tolkien.get_books();
    * ```
@@ -5174,6 +5177,29 @@ function normalizeHeapSnapshot(raw) {
     updatedAt: typeof heap.updatedAt === "number" ? heap.updatedAt : Date.now()
   };
 }
+function normalizeSubject(subject) {
+  const granularId = subject.granularId || subject.subjectId;
+  const userId = subject.userId || subject.identityId || granularId;
+  return {
+    ...subject,
+    granularId,
+    userId,
+    subjectId: granularId,
+    identityId: subject.identityId || userId
+  };
+}
+function normalizeUser(user) {
+  const granularId = user.granularId || user.subjectId;
+  const userId = user.userId || user.identityId || granularId;
+  return {
+    ...user,
+    granularId,
+    userId,
+    subjectId: granularId,
+    identityId: user.identityId || userId,
+    permissions: Array.isArray(user.permissions) ? user.permissions : []
+  };
+}
 var Environment = class _Environment extends Session {
   envData;
   _apiKey;
@@ -5196,6 +5222,10 @@ var Environment = class _Environment extends Session {
   get subjectId() {
     return this.envData.subjectId;
   }
+  /** Internal Granular user identifier for this environment */
+  get granularId() {
+    return this.envData.subjectId;
+  }
   /** The permission profile ID */
   get permissionProfileId() {
     return this.envData.permissionProfileId;
@@ -5993,7 +6023,7 @@ var Granular = class {
    * Records/upserts a user and prepares them for sandbox connections
    * 
    * @param options - User options
-   * @returns The user object to pass to connect()
+   * @returns The recorded user with both `userId` and `granularId`
    * 
    * @example
    * ```typescript
@@ -6005,21 +6035,61 @@ var Granular = class {
    * ```
    */
   async recordUser(options) {
-    const subject = await this.request("/control/subjects", {
+    const subject = normalizeSubject(await this.request("/control/subjects", {
       method: "POST",
       body: JSON.stringify({
         identityId: options.userId,
         name: options.name,
         email: options.email
       })
-    });
-    return {
+    }));
+    return normalizeUser({
+      granularId: subject.granularId,
+      userId: options.userId,
       subjectId: subject.subjectId,
-      identityId: options.userId,
-      name: options.name,
-      email: options.email,
+      identityId: subject.identityId,
+      name: options.name || subject.name || void 0,
+      email: options.email || subject.email || void 0,
       permissions: options.permissions || []
-    };
+    });
+  }
+  async resolveConnectUser(options) {
+    if (options.user) {
+      const user = normalizeUser(options.user);
+      return {
+        granularId: user.granularId,
+        userId: user.userId,
+        name: options.name || user.name,
+        email: options.email || user.email,
+        permissions: options.permissions || user.permissions
+      };
+    }
+    if (options.userId) {
+      const user = await this.recordUser({
+        userId: options.userId,
+        name: options.name,
+        email: options.email,
+        permissions: options.permissions
+      });
+      return {
+        granularId: user.granularId,
+        userId: user.userId,
+        name: user.name,
+        email: user.email,
+        permissions: options.permissions || user.permissions
+      };
+    }
+    if (options.granularId) {
+      const subject = await this.subjects.get(options.granularId);
+      return {
+        granularId: subject.granularId,
+        userId: subject.userId,
+        name: options.name || subject.name || void 0,
+        email: options.email || subject.email || void 0,
+        permissions: options.permissions || []
+      };
+    }
+    throw new Error("connect() requires either userId, granularId, or a user object returned by recordUser().");
   }
   /**
    * Connect to a sandbox and establish a real-time environment session.
@@ -6033,14 +6103,10 @@ var Granular = class {
    * 
    * @example
    * ```typescript
-   * const user = await granular.recordUser({
-   *   userId: 'user_123',
-   *   permissions: ['agent'],
-   * });
-   * 
    * const environment = await granular.connect({
    *   sandbox: 'my-sandbox',
-   *   user,
+   *   userId: 'user_123',
+   *   permissions: ['agent'],
    * });
    * 
    * await granular.registerEffect('my-sandbox', {
@@ -6061,13 +6127,14 @@ var Granular = class {
    */
   async connect(options) {
     const clientId = options.clientId || `client_${Date.now()}`;
+    const user = await this.resolveConnectUser(options);
     const sandbox = await this.findOrCreateSandbox(options.sandbox);
-    for (const profileName of options.user.permissions) {
+    for (const profileName of user.permissions) {
       const profileId = await this.ensurePermissionProfile(sandbox.sandboxId, profileName);
-      await this.ensureAssignment(options.user.subjectId, sandbox.sandboxId, profileId);
+      await this.ensureAssignment(user.granularId, sandbox.sandboxId, profileId);
     }
     const envData = await this.environments.create(sandbox.sandboxId, {
-      subjectId: options.user.subjectId,
+      subjectId: user.granularId,
       permissionProfileId: null
     });
     await this.activateEnvironment(envData.environmentId);
@@ -6127,7 +6194,21 @@ var Granular = class {
     const effects = Array.from(this.getSandboxEffectMap(host.sandboxId).values()).map(
       (effect) => this.serializeEffect(effect)
     );
-    await host.wsClient.call("effects.publishCatalog", { effects });
+    const result = await host.wsClient.call("effects.publishCatalog", { effects });
+    const acceptedCount = typeof result?.acceptedCount === "number" ? result.acceptedCount : 0;
+    const rejected = Array.isArray(result?.rejected) ? result.rejected : [];
+    if (acceptedCount === 0 && rejected.length > 0) {
+      const detail = rejected.map((entry) => `${entry.name || "unknown"}: ${entry.reason || "rejected"}`).join("; ");
+      throw new Error(
+        `Failed to publish live effects for sandbox ${host.sandboxId}: ${detail}`
+      );
+    }
+    if (rejected.length > 0) {
+      console.warn(
+        `[Granular] Some live effects were rejected for sandbox ${host.sandboxId}:`,
+        rejected
+      );
+    }
   }
   async syncSandboxEffectCatalog(sandboxId) {
     const host = await this.ensureSandboxEffectHost(sandboxId);
@@ -6293,6 +6374,22 @@ var Granular = class {
     }
     await this.syncSandboxEffectCatalog(sandboxId);
   }
+  /**
+   * Disconnect one sandbox-scoped effect host, or all of them when no sandbox is provided.
+   *
+   * This is primarily useful for long-lived helper processes such as generated
+   * `granular-effects.ts` scripts that need to shut down cleanly on SIGINT/SIGTERM.
+   */
+  async disconnectEffects(sandboxNameOrId) {
+    if (sandboxNameOrId) {
+      const sandbox = await this.findOrCreateSandbox(sandboxNameOrId);
+      this.disconnectSandboxEffectHost(sandbox.sandboxId);
+      return;
+    }
+    for (const sandboxId of Array.from(this.sandboxEffectHosts.keys())) {
+      this.disconnectSandboxEffectHost(sandboxId);
+    }
+  }
   /**
    * Unregister all effects for a sandbox.
    */
@@ -6470,7 +6567,7 @@ var Granular = class {
   get subjects() {
     return {
       get: async (subjectId) => {
-        return this.request(`/control/subjects/${subjectId}`);
+        return normalizeSubject(await this.request(`/control/subjects/${subjectId}`));
       },
       listAssignments: async (subjectId) => {
         return this.request(`/control/subjects/${subjectId}/assignments`);
@@ -6483,17 +6580,17 @@ var Granular = class {
   get users() {
     return {
       create: async (data) => {
-        return this.request("/control/subjects", {
+        return normalizeSubject(await this.request("/control/subjects", {
           method: "POST",
           body: JSON.stringify({
             identityId: data.id,
             name: data.name,
             email: data.email
           })
-        });
+        }));
       },
       get: async (id) => {
-        return this.request(`/control/subjects/${id}`);
+        return normalizeSubject(await this.request(`/control/subjects/${id}`));
       }
     };
   }