roboto-js 1.7.5 → 1.8.2

package/examples/sharing-example.js

@@ -0,0 +1,424 @@
+/**
+ * Examples demonstrating object sharing and publishing in roboto-js
+ * 
+ * These examples show how to use the new shareObject() and publishObject() methods
+ * to control access to your rbtObjects using the mod-iac system.
+ */
+
+// Import roboto-js
+import Roboto from 'roboto-js';
+
+// Initialize roboto instance
+const roboto = new Roboto({
+  host: 'your-host.com',
+  accessKey: 'your-access-key'
+});
+
+// Wait for authentication
+await roboto.api.loadCurrentUser();
+
+// ============================================================================
+// EXAMPLE 1: Publishing an Object (Making it Public)
+// ============================================================================
+
+async function example1_PublishObject() {
+  console.log('\n=== Example 1: Publishing an Object ===\n');
+  
+  // Load an existing object
+  const myAgent = await roboto.api.load('<@doc_agent.bot>', 'agent_123');
+  
+  // Check if it's currently published
+  console.log('Is published?', myAgent.isPublished());
+  
+  // Publish it (make it publicly accessible)
+  await myAgent.publishObject();
+  console.log('✓ Agent is now public!');
+  
+  // Verify it's published
+  console.log('Is published?', myAgent.isPublished());
+  
+  // Later, you can unpublish it (explicit method)
+  await myAgent.unpublishObject();
+  console.log('✓ Agent is now private (using unpublishObject)');
+  
+  // Alternative: using publishObject with flag
+  // await myAgent.publishObject({ publish: false });
+}
+
+// ============================================================================
+// EXAMPLE 2: Sharing with Specific Users
+// ============================================================================
+
+async function example2_ShareWithUsers() {
+  console.log('\n=== Example 2: Sharing with Specific Users ===\n');
+  
+  const myDocument = await roboto.api.load('<@doc.document>', 'doc_456');
+  
+  // Share with specific users (read access)
+  await myDocument.shareObject({ 
+    userIds: ['user_123', 'user_456', 'user_789'] 
+  });
+  
+  console.log('✓ Document shared with 3 users');
+  
+  // View current permissions
+  const permissions = myDocument.getSharing();
+  console.log('Read users:', permissions.readGrants.users);
+}
+
+// ============================================================================
+// EXAMPLE 3: Sharing with User Groups
+// ============================================================================
+
+async function example3_ShareWithGroups() {
+  console.log('\n=== Example 3: Sharing with User Groups ===\n');
+  
+  const myTemplate = await roboto.api.load('<@doc_agent.bot>', 'template_789');
+  
+  // Share with user groups (read access)
+  await myTemplate.shareObject({ 
+    groupIds: ['grpRngAccount', 'grpPremiumUsers'] 
+  });
+  
+  console.log('✓ Template shared with 2 user groups');
+  
+  // View permissions
+  const permissions = myTemplate.getSharing();
+  console.log('Read groups:', permissions.readGrants.userGroups);
+}
+
+// ============================================================================
+// EXAMPLE 4: Granting Write Access
+// ============================================================================
+
+async function example4_GrantWriteAccess() {
+  console.log('\n=== Example 4: Granting Write Access ===\n');
+  
+  const myProject = await roboto.api.load('<@doc.project>', 'proj_abc');
+  
+  // Share with read access (default)
+  await myProject.shareObject({ 
+    groupIds: ['grpViewers']
+  });
+  
+  // Share with write access for editors
+  await myProject.shareObject({ 
+    groupIds: ['grpEditors'],
+    write: true 
+  });
+  
+  console.log('✓ Viewers can read, editors can write');
+  
+  // View all permissions
+  const permissions = myProject.getSharing();
+  console.log('Read groups:', permissions.readGrants.userGroups);
+  console.log('Write groups:', permissions.writeGrants.userGroups);
+}
+
+// ============================================================================
+// EXAMPLE 5: Combining Users and Groups
+// ============================================================================
+
+async function example5_CombineUsersAndGroups() {
+  console.log('\n=== Example 5: Combining Users and Groups ===\n');
+  
+  const myContent = await roboto.api.load('<@doc.content>', 'content_xyz');
+  
+  // Share with both users and groups
+  await myContent.shareObject({ 
+    userIds: ['user_special_123'],
+    groupIds: ['grpSubscribers', 'grpPremium']
+  });
+  
+  console.log('✓ Shared with 1 user and 2 groups');
+  
+  const permissions = myContent.getSharing();
+  console.log('Read users:', permissions.readGrants.users);
+  console.log('Read groups:', permissions.readGrants.userGroups);
+}
+
+// ============================================================================
+// EXAMPLE 6: Replacing vs. Merging Permissions
+// ============================================================================
+
+async function example6_ReplaceVsMerge() {
+  console.log('\n=== Example 6: Replacing vs. Merging ===\n');
+  
+  const myObject = await roboto.api.load('<@doc.item>', 'item_001');
+  
+  // First share with some users (merges with existing)
+  await myObject.shareObject({ 
+    userIds: ['user_a', 'user_b']
+  });
+  console.log('After merge:', myObject.getSharing().readGrants.users);
+  
+  // Add more users (merges again)
+  await myObject.shareObject({ 
+    userIds: ['user_c']
+  });
+  console.log('After another merge:', myObject.getSharing().readGrants.users);
+  
+  // Replace all permissions
+  await myObject.shareObject({ 
+    userIds: ['user_x', 'user_y'],
+    replace: true 
+  });
+  console.log('After replace:', myObject.getSharing().readGrants.users);
+}
+
+// ============================================================================
+// EXAMPLE 7: Batch Updates Without Auto-Save
+// ============================================================================
+
+async function example7_BatchUpdates() {
+  console.log('\n=== Example 7: Batch Updates Without Auto-Save ===\n');
+  
+  const myAgent = await roboto.api.load('<@doc_agent.bot>', 'agent_multi');
+  
+  // Update permissions without saving
+  await myAgent.shareObject({ 
+    groupIds: ['grpUsers'],
+    save: false 
+  });
+  console.log('✓ Added group (not saved)');
+  
+  // Publish without saving
+  await myAgent.publishObject({ save: false });
+  console.log('✓ Published (not saved)');
+  
+  // Make other changes
+  myAgent.set('configs.title', 'Updated Title');
+  console.log('✓ Updated title (not saved)');
+  
+  // Save once with all changes
+  await myAgent.save();
+  console.log('✓ All changes saved at once!');
+}
+
+// ============================================================================
+// EXAMPLE 8: Tiered Access Control
+// ============================================================================
+
+async function example8_TieredAccess() {
+  console.log('\n=== Example 8: Tiered Access Control ===\n');
+  
+  const myContent = await roboto.api.load('<@doc.content>', 'content_tiered');
+  
+  // Public can read
+  await myContent.publishObject({ save: false });
+  
+  // Editors can write
+  await myContent.shareObject({ 
+    groupIds: ['grpEditors'],
+    write: true,
+    save: false 
+  });
+  
+  // Admins can write
+  await myContent.shareObject({ 
+    groupIds: ['grpAdmins'],
+    write: true,
+    save: true 
+  });
+  
+  console.log('✓ Tiered access configured:');
+  console.log('  - Public: read');
+  console.log('  - Editors: write');
+  console.log('  - Admins: write');
+  
+  const permissions = myContent.getSharing();
+  console.log('\nRead users:', permissions.readGrants.users);
+  console.log('Write groups:', permissions.writeGrants.userGroups);
+}
+
+// ============================================================================
+// EXAMPLE 9: Template Publishing Pattern (like Ringable)
+// ============================================================================
+
+async function example9_TemplatePublishing() {
+  console.log('\n=== Example 9: Template Publishing Pattern ===\n');
+  
+  const template = await roboto.api.load('<@doc_agent.bot>', 'template_rng');
+  
+  // Function to publish/unpublish a template
+  async function setTemplatePublished(agent, isPublished) {
+    if (isPublished) {
+      // Share with all account users
+      await agent.shareObject({ 
+        groupIds: ['grpRngAccount'] 
+      });
+      console.log('✓ Template published to all account users');
+    } else {
+      // Remove the group
+      const current = agent.getSharing();
+      const remainingGroups = current.readGrants.userGroups
+        .filter(g => g !== 'grpRngAccount');
+      
+      await agent.shareObject({ 
+        groupIds: remainingGroups,
+        replace: true 
+      });
+      console.log('✓ Template unpublished from account users');
+    }
+  }
+  
+  // Publish the template
+  await setTemplatePublished(template, true);
+  
+  // Later, unpublish it
+  await setTemplatePublished(template, false);
+}
+
+// ============================================================================
+// EXAMPLE 10: Getting and Inspecting Permissions
+// ============================================================================
+
+async function example10_InspectPermissions() {
+  console.log('\n=== Example 10: Inspecting Permissions ===\n');
+  
+  const myObject = await roboto.api.load('<@doc.item>', 'item_inspect');
+  
+  // Get all permissions
+  const permissions = myObject.getSharing();
+  
+  console.log('Read Permissions:');
+  console.log('  Users:', permissions.readGrants.users);
+  console.log('  Groups:', permissions.readGrants.userGroups);
+  console.log('  Organizations:', permissions.readGrants.organizations);
+  
+  console.log('\nWrite Permissions:');
+  console.log('  Users:', permissions.writeGrants.users);
+  console.log('  Groups:', permissions.writeGrants.userGroups);
+  console.log('  Organizations:', permissions.writeGrants.organizations);
+  
+  // Check if public
+  console.log('\nIs Published?', myObject.isPublished());
+  
+  // Get raw IAC data
+  const iac = myObject.get('iac');
+  console.log('\nRaw IAC data:', JSON.stringify(iac, null, 2));
+}
+
+// ============================================================================
+// EXAMPLE 11: Removing Access with unshareObject
+// ============================================================================
+
+async function example11_RemovingAccess() {
+  console.log('\n=== Example 11: Removing Access with unshareObject ===\n');
+  
+  const myObject = await roboto.api.load('<@doc.item>', 'item_remove');
+  
+  // Get current permissions
+  const current = myObject.getSharing();
+  console.log('Current users:', current.readGrants.users);
+  console.log('Current groups:', current.readGrants.userGroups);
+  
+  // Remove specific users from read access (easy way)
+  await myObject.unshareObject({ 
+    userIds: ['user_123', 'user_456'] 
+  });
+  console.log('✓ Removed specific users');
+  console.log('Remaining users:', myObject.getSharing().readGrants.users);
+  
+  // Remove specific groups from read access
+  await myObject.unshareObject({ 
+    groupIds: ['grpViewers'] 
+  });
+  console.log('✓ Removed specific groups');
+  console.log('Remaining groups:', myObject.getSharing().readGrants.userGroups);
+  
+  // Remove write access from groups
+  await myObject.unshareObject({ 
+    groupIds: ['grpEditors'],
+    write: true 
+  });
+  console.log('✓ Removed write access from editors');
+  
+  // Alternative: using replace with shareObject
+  const currentAfter = myObject.getSharing();
+  const keepUsers = currentAfter.readGrants.users.filter(id => id !== 'user_789');
+  await myObject.shareObject({ 
+    userIds: keepUsers,
+    replace: true 
+  });
+  console.log('✓ Removed user_789 using replace method');
+}
+
+// ============================================================================
+// EXAMPLE 12: Creating and Sharing a New Object
+// ============================================================================
+
+async function example12_CreateAndShare() {
+  console.log('\n=== Example 12: Creating and Sharing a New Object ===\n');
+  
+  // Create a new object
+  const newAgent = await roboto.api.create('<@doc_agent.bot>', {
+    configs: {
+      title: 'My New Public Agent',
+      description: 'This agent will be shared with everyone'
+    }
+  });
+  
+  console.log('✓ Created new agent:', newAgent.id);
+  
+  // Immediately publish it
+  await newAgent.publishObject();
+  
+  console.log('✓ Published new agent');
+  console.log('Is published?', newAgent.isPublished());
+}
+
+// ============================================================================
+// Run all examples
+// ============================================================================
+
+async function runAllExamples() {
+  console.log('╔════════════════════════════════════════════════════════════╗');
+  console.log('║  roboto-js Sharing & Publishing Examples                  ║');
+  console.log('╚════════════════════════════════════════════════════════════╝');
+  
+  try {
+    // Uncomment the examples you want to run:
+    
+    // await example1_PublishObject();
+    // await example2_ShareWithUsers();
+    // await example3_ShareWithGroups();
+    // await example4_GrantWriteAccess();
+    // await example5_CombineUsersAndGroups();
+    // await example6_ReplaceVsMerge();
+    // await example7_BatchUpdates();
+    // await example8_TieredAccess();
+    // await example9_TemplatePublishing();
+    // await example10_InspectPermissions();
+    // await example11_RemovingAccess();
+    // await example12_CreateAndShare();
+    
+    console.log('\n✓ All examples completed!');
+  } catch (error) {
+    console.error('\n✗ Error running examples:', error);
+    console.error(error.stack);
+  }
+}
+
+// Run examples if this file is executed directly
+if (import.meta.url === `file://${process.argv[1]}`) {
+  runAllExamples();
+}
+
+// Export examples for use in other files
+export {
+  example1_PublishObject,
+  example2_ShareWithUsers,
+  example3_ShareWithGroups,
+  example4_GrantWriteAccess,
+  example5_CombineUsersAndGroups,
+  example6_ReplaceVsMerge,
+  example7_BatchUpdates,
+  example8_TieredAccess,
+  example9_TemplatePublishing,
+  example10_InspectPermissions,
+  example11_RemovingAccess,
+  example12_CreateAndShare,
+  runAllExamples
+};
+

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "roboto-js",
-  "version": "1.7.5",
+  "version": "1.8.2",
   "type": "module",
   "description": "",
   "main": "dist/cjs/index.cjs",