@granular-software/sdk 0.4.5 → 0.4.7

package/README.md

@@ -8,7 +8,7 @@ The official TypeScript SDK for Granular.
 
 - 🏗️ **Domain Ontology** — Define classes, properties, and relationships as a typed graph
 - 🔧 **Class-Based Tools** — Attach instance methods, static methods, and global tools with typed I/O
-- 🤖 **Domain Synthesis** — Auto-generated TypeScript classes with `find()`, relationship accessors, and typed methods
+- 🤖 **Domain Synthesis** — Auto-generated TypeScript classes with `get({ path })`, `list()`, relationship accessors, and typed methods
 - 🔒 **Secure Execution** — Run AI-generated code in isolated sandboxes
 - 👥 **User Permissions** — Control what each user can access
 - ⚡ **Real-time** — WebSocket-based streaming and events
@@ -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',
@@ -147,8 +147,10 @@ await granular.registerEffects(env.sandboxId, [
 const job = await env.submitJob(`
   import { Customer } from './sandbox-tools';
 
-  // Find returns a typed Customer instance with loaded field values
-  const acme = await Customer.find({ id: 'cust_42' });
+  // list() discovers instances; get({ path }) hydrates a specific graph object
+  const customers = await Customer.list();
+  const acme = customers.find((customer) => customer.name === 'Acme Corp');
+  if (!acme) throw new Error('Customer not found');
   console.log(acme.name);   // "Acme Corp"
   console.log(acme.email);  // "billing@acme.com"
 
@@ -170,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
@@ -230,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)
@@ -340,8 +348,11 @@ export declare class Author {
 
   constructor(id: string, fields?: Record<string, any>);
 
-  /** Find an Author by ID */
-  static find(query: { id: string }): Promise<Author | null>;
+  /** Get a cached Author by graph path, hydrating from the graph when needed */
+  static get(query: { path: string; refresh?: boolean }): Promise<Author | null>;
+
+  /** List known Author instances */
+  static list(query?: { limit?: number; saveAs?: string; refresh?: boolean }): Promise<Author[]>;
 
   /** Get biography of an author */
   get_bio(input?: { detailed?: boolean }): Promise<{ bio: string; source?: string }>;
@@ -359,7 +370,9 @@ export declare class Book {
   readonly isbn: string;
   readonly published_year: number;
 
-  static find(query: { id: string }): Promise<Book | null>;
+  static get(query: { path: string; refresh?: boolean }): Promise<Book | null>;
+
+  static list(query?: { limit?: number; saveAs?: string; refresh?: boolean }): Promise<Book[]>;
 
   /** Navigate to author (many_to_one) */
   get_author(): Promise<Author | null>;
@@ -374,7 +387,9 @@ The LLM or user writes code against these typed classes:
 ```typescript
 import { Author, Book, global_search } from './sandbox-tools';
 
-const tolkien = await Author.find({ id: 'tolkien' });
+const authors = await Author.list();
+const tolkien = authors.find((author) => author.name === 'J.R.R. Tolkien');
+if (!tolkien) throw new Error('Author not found');
 console.log(tolkien.name);              // "J.R.R. Tolkien"
 
 const bio = await tolkien.get_bio({ detailed: true });

package/dist/cli/index.js

@@ -7771,7 +7771,31 @@ async function main() {
     await granular.registerEffects(SANDBOX_ID, ${effectsArray});
 
     log('Effects registered. Process kept alive for simulator. Press Ctrl+C to exit.');
-    await new Promise(() => {});
+
+    const keepAliveTimer = setInterval(() => {
+        // Keep an active event-loop handle so Bun/Node does not exit immediately.
+    }, 60_000);
+
+    await new Promise<void>((resolve) => {
+        let shuttingDown = false;
+
+        const shutdown = async (signal: string) => {
+            if (shuttingDown) return;
+            shuttingDown = true;
+            clearInterval(keepAliveTimer);
+            log(\`Received \${signal}. Shutting down effects host...\`);
+            try {
+                await granular.disconnectEffects(SANDBOX_ID);
+            } catch (error) {
+                console.warn('[Effects] Failed to disconnect live effects cleanly:', error);
+            }
+            resolve();
+            process.exit(0);
+        };
+
+        process.once('SIGINT', () => { void shutdown('SIGINT'); });
+        process.once('SIGTERM', () => { void shutdown('SIGTERM'); });
+    });
 }
 
 main().catch((err) => {
@@ -8598,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);`);
@@ -8619,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)) {
@@ -8714,12 +8739,16 @@ console.log('Connected to:', env.environmentId);`);
   if (classes.length > 0) {
     const cls = classes[0];
     const ClassName = cls.name.charAt(0).toUpperCase() + cls.name.slice(1);
-    lines.push(`  // 1. Find object`);
-    lines.push(`  const item = await ${ClassName}.find({ id: 'unique_${cls.name}_id' });`);
-    lines.push(`  console.log('Found:', item.id);`);
+    lines.push(`  // 1. List objects`);
+    lines.push(`  const items = await ${ClassName}.list({ limit: 10, saveAs: '${cls.name}_items' });`);
+    lines.push(`  const item = items[0] ?? null;`);
+    lines.push(`  console.log('Loaded:', item?.id);`);
     lines.push(``);
     lines.push(`  // 2. Call instance method`);
-    lines.push(`  const summary = await item.summarize({ maxLength: 100 });`);
+    lines.push(`  if (item) {`);
+    lines.push(`    const summary = await item.summarize({ maxLength: 100 });`);
+    lines.push(`    console.log(summary);`);
+    lines.push(`  }`);
     lines.push(``);
     lines.push(`  // 3. Call static method`);
     lines.push(`  const results = await ${ClassName}.search({ query: 'test' });`);

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;
@@ -904,7 +930,8 @@ declare class Session {
      * ```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();
      * ```
@@ -1016,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 */
@@ -1329,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
@@ -1341,6 +1370,7 @@ declare class Granular {
      * ```
      */
     recordUser(options: RecordUserOptions): Promise<User>;
+    private resolveConnectUser;
     /**
      * Connect to a sandbox and establish a real-time environment session.
      *
@@ -1353,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', {
@@ -1410,6 +1436,13 @@ declare class Granular {
      * sandbox-scoped live catalog.
      */
     unregisterEffect(sandboxNameOrId: string, name: string): Promise<void>;
+    /**
+     * 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.
+     */
+    disconnectEffects(sandboxNameOrId?: string): Promise<void>;
     /**
      * Unregister all effects for a 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;
@@ -904,7 +930,8 @@ declare class Session {
      * ```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();
      * ```
@@ -1016,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 */
@@ -1329,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
@@ -1341,6 +1370,7 @@ declare class Granular {
      * ```
      */
     recordUser(options: RecordUserOptions): Promise<User>;
+    private resolveConnectUser;
     /**
      * Connect to a sandbox and establish a real-time environment session.
      *
@@ -1353,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', {
@@ -1410,6 +1436,13 @@ declare class Granular {
      * sandbox-scoped live catalog.
      */
     unregisterEffect(sandboxNameOrId: string, name: string): Promise<void>;
+    /**
+     * 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.
+     */
+    disconnectEffects(sandboxNameOrId?: string): Promise<void>;
     /**
      * Unregister all effects for a sandbox.
      */