@granular-software/sdk 0.4.6 → 0.4.8

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)