@granular-software/sdk 0.4.6 → 0.4.7

package/README.md

@@ -55,16 +55,16 @@ import { Granular, type ManifestContent } from '@granular-software/sdk';
 
 const granular = new Granular({ apiKey: process.env.GRANULAR_API_KEY });
 
-// 1. Record user with permissions
-const user = await granular.recordUser({
+// 1. Connect to sandbox for one of your app users
+const env = await granular.connect({
+  sandbox: 'my-sandbox',
   userId: 'user_123',
   permissions: ['agent'],
+  name: 'Jane Doe',           // optional
+  email: 'jane@example.com',  // optional
 });
 
-// 2. Connect to sandbox
-const env = await granular.connect({ sandbox: 'my-sandbox', user });
-
-// 3. Define your domain ontology
+// 2. Define your domain ontology
 const manifest: ManifestContent = {
   schemaVersion: 2,
   name: 'my-app',
@@ -105,7 +105,7 @@ const manifest: ManifestContent = {
 
 await env.applyManifest(manifest);
 
-// 4. Record object instances
+// 3. Record object instances
 await env.recordObject({
   className: 'customer',
   id: 'cust_42',
@@ -113,7 +113,7 @@ await env.recordObject({
   fields: { name: 'Acme Corp', email: 'billing@acme.com', tier: 'enterprise' },
 });
 
-// 5. Register live effect handlers for effects already declared in the build manifest
+// 4. Register live effect handlers for effects already declared in the build manifest
 await granular.registerEffects(env.sandboxId, [
   {
     name: 'get_billing_summary',
@@ -172,11 +172,11 @@ Effects must be declared ahead of time in the sandbox build manifest with `withE
 ## Core Flow
 
 ```
-declare effects in build manifest → connect() → recordObject() → registerEffects() → submitJob()
+declare effects in build manifest → connect({ userId }) → recordObject() → registerEffects() → submitJob()
 ```
 
-1. **`recordUser()`** — Register a user and their permission profiles
-2. **`connect()`** — Connect to a sandbox, returning an `Environment`
+1. **`connect()`** — Connect to a sandbox for a given `userId`, returning an `Environment`
+2. **`recordUser()`** — Optional explicit user upsert when you want the returned `granularId`
 3. **`applyManifest()`** — Define your domain ontology (classes, properties, relationships)
 4. **`recordObject()`** — Create/update instances of your classes with fields and relationships
 5. **`granular.registerEffects()`** — Register sandbox-scoped live handlers for effects declared in the build manifest
@@ -232,9 +232,15 @@ await env.applyManifest(manifest);
 
 ## Recording Object Instances
 
-After defining the ontology, populate it with data:
+After defining the ontology, connect as a user and populate it with data:
 
 ```typescript
+const env = await granular.connect({
+  sandbox: 'library-app',
+  userId: 'user_123',
+  permissions: ['agent'],
+});
+
 const tolkien = await env.recordObject({
   className: 'author',
   id: 'tolkien',               // Real-world ID (unique per class)

package/dist/cli/index.js

@@ -8622,17 +8622,12 @@ const granular = new Granular({`);
   lines.push(`  ...(process.env.GRANULAR_TOKEN ? { token: process.env.GRANULAR_TOKEN } : { apiKey: process.env.GRANULAR_API_KEY! }),`);
   lines.push(`});`);
   lines.push(`
-// 1. Record the user (creates or updates identity)`);
-  lines.push(`const user = await granular.recordUser({`);
-  lines.push(`  userId: 'user_123', // Your internal ID`);
-  lines.push(`  email: 'user@example.com',`);
-  lines.push(`  permissions: ['default'], // Permission profile`);
-  lines.push(`});`);
-  lines.push(`
-// 2. Connect to the sandbox`);
+// 1. Connect to the sandbox for one of your app users`);
   lines.push(`const env = await granular.connect({`);
   lines.push(`  sandbox: '${sandboxId}',`);
-  lines.push(`  user,`);
+  lines.push(`  userId: 'user_123', // Your app's user ID`);
+  lines.push(`  email: 'user@example.com', // optional`);
+  lines.push(`  permissions: ['default'], // Permission profile`);
   lines.push(`});`);
   lines.push(`
 console.log('Connected to:', env.environmentId);`);
@@ -8643,6 +8638,12 @@ console.log('Connected to:', env.environmentId);`);
   if (classes.length > 0) {
     lines.push(`
 \`\`\`typescript`);
+    lines.push(`const env = await granular.connect({`);
+    lines.push(`  sandbox: '${sandboxId}',`);
+    lines.push(`  userId: 'user_123',`);
+    lines.push(`  permissions: ['default'],`);
+    lines.push(`});`);
+    lines.push(``);
     for (const cls of classes) {
       const exampleFields = {};
       for (const [k, v] of Object.entries(cls.fields)) {

package/dist/index.d.mts

@@ -40,9 +40,13 @@ type GranularAuth = string;
  * A user/subject object returned from recordUser()
  */
 interface User {
-    /** Internal subject ID */
+    /** Internal Granular user identifier */
+    granularId: string;
+    /** External user identifier from your app */
+    userId: string;
+    /** @deprecated Use `granularId` instead */
     subjectId: string;
-    /** External identity ID (e.g. Auth0 ID) */
+    /** @deprecated Use `userId` instead */
     identityId: string;
     /** User's display name */
     name?: string;
@@ -68,6 +72,10 @@ interface RecordUserOptions {
  * Subject as returned from the API
  */
 interface Subject {
+    /** Internal Granular user identifier */
+    granularId: string;
+    /** External user identifier from your app */
+    userId: string;
     subjectId: string;
     tenantId: string;
     identityId: string;
@@ -83,8 +91,24 @@ interface Subject {
 interface ConnectOptions {
     /** The sandbox name or ID to connect to */
     sandbox: string;
-    /** The user to connect as (from recordUser()) */
-    user: User;
+    /**
+     * External user identifier from your app. This is the primary input for
+     * connecting to a sandbox and the only required user field in the common case.
+     */
+    userId?: string;
+    /**
+     * Internal Granular user identifier. Optional fallback when you only know
+     * the Granular-side ID for an existing subject.
+     */
+    granularId?: string;
+    /** Optional display name used when upserting the user */
+    name?: string;
+    /** Optional email used when upserting the user */
+    email?: string;
+    /** Permission profile IDs or names to ensure before connecting */
+    permissions?: string[];
+    /** Backwards-compatible user object returned from recordUser() */
+    user?: User;
     /** Optional stable client ID. Defaults to `client_${Date.now()}`. Use a fixed
      *  value for long-lived effect hosts so tool catalogs don't accumulate. */
     clientId?: string;
@@ -274,6 +298,8 @@ interface EffectHandlerContext {
     principalId?: string;
     permissionProfileId?: string;
     user: {
+        granularId?: string;
+        userId?: string;
         subjectId: string;
         identityId?: string;
         principalId?: string;
@@ -1017,6 +1043,8 @@ declare class Environment extends Session {
     get sandboxId(): string;
     /** The subject ID */
     get subjectId(): string;
+    /** Internal Granular user identifier for this environment */
+    get granularId(): string;
     /** The permission profile ID */
     get permissionProfileId(): string;
     /** The GraphQL API endpoint URL */
@@ -1330,7 +1358,7 @@ declare class Granular {
      * 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
@@ -1342,6 +1370,7 @@ declare class Granular {
      * ```
      */
     recordUser(options: RecordUserOptions): Promise<User>;
+    private resolveConnectUser;
     /**
      * Connect to a sandbox and establish a real-time environment session.
      *
@@ -1354,14 +1383,10 @@ declare class Granular {
      *
      * @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', {

package/dist/index.d.ts

@@ -40,9 +40,13 @@ type GranularAuth = string;
  * A user/subject object returned from recordUser()
  */
 interface User {
-    /** Internal subject ID */
+    /** Internal Granular user identifier */
+    granularId: string;
+    /** External user identifier from your app */
+    userId: string;
+    /** @deprecated Use `granularId` instead */
     subjectId: string;
-    /** External identity ID (e.g. Auth0 ID) */
+    /** @deprecated Use `userId` instead */
     identityId: string;
     /** User's display name */
     name?: string;
@@ -68,6 +72,10 @@ interface RecordUserOptions {
  * Subject as returned from the API
  */
 interface Subject {
+    /** Internal Granular user identifier */
+    granularId: string;
+    /** External user identifier from your app */
+    userId: string;
     subjectId: string;
     tenantId: string;
     identityId: string;
@@ -83,8 +91,24 @@ interface Subject {
 interface ConnectOptions {
     /** The sandbox name or ID to connect to */
     sandbox: string;
-    /** The user to connect as (from recordUser()) */
-    user: User;
+    /**
+     * External user identifier from your app. This is the primary input for
+     * connecting to a sandbox and the only required user field in the common case.
+     */
+    userId?: string;
+    /**
+     * Internal Granular user identifier. Optional fallback when you only know
+     * the Granular-side ID for an existing subject.
+     */
+    granularId?: string;
+    /** Optional display name used when upserting the user */
+    name?: string;
+    /** Optional email used when upserting the user */
+    email?: string;
+    /** Permission profile IDs or names to ensure before connecting */
+    permissions?: string[];
+    /** Backwards-compatible user object returned from recordUser() */
+    user?: User;
     /** Optional stable client ID. Defaults to `client_${Date.now()}`. Use a fixed
      *  value for long-lived effect hosts so tool catalogs don't accumulate. */
     clientId?: string;
@@ -274,6 +298,8 @@ interface EffectHandlerContext {
     principalId?: string;
     permissionProfileId?: string;
     user: {
+        granularId?: string;
+        userId?: string;
         subjectId: string;
         identityId?: string;
         principalId?: string;
@@ -1017,6 +1043,8 @@ declare class Environment extends Session {
     get sandboxId(): string;
     /** The subject ID */
     get subjectId(): string;
+    /** Internal Granular user identifier for this environment */
+    get granularId(): string;
     /** The permission profile ID */
     get permissionProfileId(): string;
     /** The GraphQL API endpoint URL */
@@ -1330,7 +1358,7 @@ declare class Granular {
      * 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
@@ -1342,6 +1370,7 @@ declare class Granular {
      * ```
      */
     recordUser(options: RecordUserOptions): Promise<User>;
+    private resolveConnectUser;
     /**
      * Connect to a sandbox and establish a real-time environment session.
      *
@@ -1354,14 +1383,10 @@ declare class Granular {
      *
      * @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', {

package/dist/index.js

@@ -4503,6 +4503,8 @@ var Session = class {
       environmentId: "",
       sessionId: "",
       user: {
+        granularId: "",
+        userId: "",
         subjectId: ""
       }
     };
@@ -5197,6 +5199,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;
@@ -5219,6 +5244,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;
@@ -6016,7 +6045,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
@@ -6028,21 +6057,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.
@@ -6056,14 +6125,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', {
@@ -6084,13 +6149,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);
@@ -6523,7 +6589,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`);
@@ -6536,17 +6602,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}`));
       }
     };
   }