roboto-js 1.9.5 → 1.9.7

package/.last-build

@@ -1 +1 @@
-2025-12-08T03:12:14.784Z
+2025-12-31T10:58:16.804Z

package/README.md

@@ -0,0 +1,580 @@
+# roboto-js
+
+JavaScript/TypeScript SDK for the Roboto platform - a unified client library for managing objects, files, users, and real-time data synchronization.
+
+**Version:** 1.9.5
+
+## Features
+
+- **Object Management**: Create, read, update, and delete platform objects with a simple API
+- **File Handling**: Upload and manage files with resumable uploads via tus protocol
+- **User Authentication**: Login, registration, OAuth, and session management
+- **Real-time Sync**: WebSocket-based live updates for collaborative applications
+- **Access Control**: Fine-grained permissions with user, group, and organization-level sharing
+- **Storage Adapters**: Flexible authentication storage (cookies, localStorage, custom)
+- **Metrics & Analytics**: Built-in metrics API for tracking and analytics
+- **Dual Module Support**: Works in both CommonJS and ES Module environments
+- **Browser & Node.js**: Runs in browsers and Node.js server environments
+
+## Installation
+
+```bash
+npm install roboto-js
+```
+
+## Quick Start
+
+### Basic Initialization
+
+```javascript
+import Roboto from 'roboto-js';
+
+const roboto = new Roboto({
+  host: 'your-api-host.com',
+  accessKey: 'your-access-key'
+});
+```
+
+### Authentication
+
+```javascript
+// Login
+const user = await roboto.login({
+  email: 'user@example.com',
+  password: 'password'
+});
+
+// Get current user
+const currentUser = await roboto.loadCurrentUser();
+
+// Logout
+await roboto.logout();
+```
+
+### Working with Objects
+
+```javascript
+// Create a new object
+const site = await roboto.create('<@doc_website.site>', {
+  configs: {
+    label: 'My Website',
+    domain: 'example.com'
+  }
+});
+
+// Load an object
+const loadedSite = await roboto.load('<@doc_website.site>', 'site-id-123');
+
+// Update and save
+site.set('configs.label', 'Updated Website');
+await site.save();
+
+// Query objects
+const sites = await roboto.query('<@doc_website.site>', {
+  where: 'configs.status=active'
+});
+```
+
+### File Uploads
+
+```javascript
+// Create a file object
+const file = await roboto.createFile({
+  filename: 'document.pdf',
+  mimetype: 'application/pdf'
+});
+
+// Upload with progress tracking
+await file.upload(fileBlob, {
+  onProgress: (bytesUploaded, bytesTotal) => {
+    const percent = (bytesUploaded / bytesTotal) * 100;
+    console.log(`Upload progress: ${percent.toFixed(2)}%`);
+  }
+});
+```
+
+## Configuration Options
+
+```javascript
+const roboto = new Roboto({
+  host: 'api.example.com',              // API host (required)
+  accessKey: 'your-access-key',          // Access key (required)
+  authToken: 'token',                    // Optional: pre-set auth token
+  apiKey: 'key',                         // Optional: API key for service calls
+  useCookies: true,                      // Use cookies for auth (default: true)
+  cookieDomain: 'auto',                  // Cookie domain: 'auto', 'none', or explicit domain
+  localStorageAdaptor: customAdaptor,    // Custom storage adapter
+  disableWebSocket: false,               // Disable WebSocket connections
+  metricsHost: 'metrics.example.com'     // Separate metrics host (optional)
+});
+```
+
+## Core API Methods
+
+### Object Operations
+
+- `create(type, data)` - Create a new object
+- `load(type, ids, options)` - Load object(s) by ID
+- `query(type, params)` - Query objects with filters
+- `wrapAsRbtObjects(data)` - Convert raw JSON to RbtObject instances
+
+### User Management
+
+- `login(params)` - Authenticate user
+- `loginWithOauth(params)` - OAuth authentication
+- `logout()` - End session
+- `registerUser(params)` - Create new user account
+- `loadCurrentUser()` - Get authenticated user
+- `confirmUserEmail(params)` - Verify email address
+
+### Organization Management
+
+- `loadCurrentOrganization(forceReload)` - Load user's current organization
+- `switchOrganization(orgId)` - Switch to a different organization
+- `getCurrentOrganization()` - Get cached current organization
+- `currentOrganization` - Getter for current organization
+
+### File Operations
+
+- `createFile(data)` - Create file object
+- `loadFile(id)` - Load file by ID
+- `loadFiles(ids)` - Load multiple files
+
+### Task Execution
+
+- `runTask(params, callbacks)` - Execute background task
+- `stopJob(params)` - Cancel running job
+- `pollTaskProgress(params)` - Check task status
+
+### HTTP Methods
+
+- `get(endpoint, params)` - GET request with auto-wrapping
+- `post(endpoint, data)` - POST request with auto-wrapping
+
+## RbtObject Methods
+
+RbtObject is the core class for working with platform data:
+
+```javascript
+// Data access
+object.get('path.to.property')        // Get value
+object.getData(['key1', 'key2'])      // Get multiple values
+object.set('path.to.property', value) // Set value
+object.set('path', value, { merge: true }) // Merge objects
+
+// Persistence
+await object.save()                   // Save changes
+await object.delete()                 // Delete object
+await object.reload()                 // Refresh from server
+
+// Metadata
+object.id                             // Object ID
+object.getType()                      // Object type
+object.getRevision()                  // Revision number
+object.hasUnsavedChanges()           // Check for pending changes
+
+// Real-time sync
+object.enableRealtime()              // Enable live updates
+object.disableRealtime()             // Disable live updates
+object.on('change', callback)        // Listen for changes
+object.broadcastChange('path')       // Broadcast to other clients
+```
+
+## Access Control & Sharing
+
+Control who can access your objects:
+
+```javascript
+// Make object public
+await object.publishObject();
+await object.unpublishObject();
+
+// Check if published
+if (object.isPublished()) {
+  console.log('Object is public');
+}
+
+// Grant access to users
+await object.grantAccess({
+  userIds: ['user1', 'user2'],
+  write: false  // read-only
+});
+
+// Grant access to groups
+await object.grantAccess({
+  groupIds: ['grpAdmins'],
+  write: true  // read and write
+});
+
+// Revoke access
+await object.revokeAccess({
+  userIds: ['user1'],
+  groupIds: ['grpViewers']
+});
+
+// Get current permissions
+const perms = object.getSharing();
+console.log(perms.readGrants.users);
+console.log(perms.writeGrants.userGroups);
+```
+
+See [SHARING_GUIDE.md](./SHARING_GUIDE.md) for detailed examples and patterns.
+
+## Organization Management
+
+Manage the current organization context for multi-tenant applications:
+
+```javascript
+// Load current organization (automatic on login)
+const org = await roboto.loadCurrentOrganization();
+console.log('Current org:', org.get('name'));
+
+// Access organization data
+const orgName = org.get('name');
+const taxId = org.get('profile.taxId');
+
+// Access module-specific settings
+const fiscalYearEnd = org.get('mod.accounting.fiscalYearEnd');
+const defaultPipeline = org.get('mod.crm.defaultPipeline');
+
+// Update organization data
+org.set('name', 'Updated Company Name');
+org.set('mod.accounting.baseCurrency', 'USD');
+await org.save();
+
+// Switch to a different organization
+const newOrg = await roboto.switchOrganization('org-456');
+console.log('Switched to:', newOrg.get('name'));
+
+// Get cached organization (no API call)
+const cached = roboto.getCurrentOrganization();
+// or
+const cached = roboto.currentOrganization;
+```
+
+### Organization on Login
+
+Organizations are automatically loaded after successful login:
+
+```javascript
+await roboto.login({ 
+  email: 'user@example.com', 
+  password: 'password'
+});
+
+// Organization is now available
+const org = roboto.currentOrganization;
+console.log('Logged in to:', org.get('name'));
+
+// Disable automatic organization load
+await roboto.login({ 
+  email: 'user@example.com', 
+  password: 'password',
+  loadOrganization: false  // Skip org loading
+});
+```
+
+### Server-Side Organization Context
+
+```javascript
+// Express middleware with per-request organization
+app.use((req, res, next) => {
+  req.roboto = new Roboto({
+    host: 'api.example.com',
+    accessKey: process.env.ROBOTO_ACCESS_KEY
+  }, req);
+  next();
+});
+
+// Use in routes
+app.get('/api/accounts', async (req, res) => {
+  const org = await req.roboto.loadCurrentOrganization();
+  
+  // Query automatically scoped to organization via IAC
+  const accounts = await req.roboto.query('<@accounting.account>', {});
+  
+  res.json({ 
+    organization: org.get('name'),
+    accounts 
+  });
+});
+```
+
+### Multi-Tenant Data Scoping
+
+Organization context enables automatic multi-tenant data scoping:
+
+```javascript
+// All queries are automatically scoped to current organization
+const org = await roboto.loadCurrentOrganization();
+
+// These queries only return data the organization has access to
+const accounts = await roboto.query('<@accounting.account>', {});
+const invoices = await roboto.query('<@accounting.invoice>', {});
+const contacts = await roboto.query('<@crm.contact>', {});
+
+// Switch organizations and queries update automatically
+await roboto.switchOrganization('different-org-id');
+const newAccounts = await roboto.query('<@accounting.account>', {});
+// Now returns accounts for the new organization
+```
+
+## Real-time Collaboration
+
+Enable live updates across clients:
+
+```javascript
+// Enable real-time on an object
+const doc = await roboto.load('<@doc.document>', 'doc-123');
+doc.enableRealtime();
+
+// Listen for changes
+doc.on('change', (path, value) => {
+  console.log(`${path} changed to`, value);
+});
+
+// Broadcast changes to other clients
+doc.set('content.text', 'Updated text');
+doc.broadcastChange('content.text'); // Others receive this immediately
+
+// Disable when done
+doc.disableRealtime();
+```
+
+## Storage Adapters
+
+### Cookie Storage (Default for Browser)
+
+```javascript
+import Roboto, { CookieStorageAdaptor } from 'roboto-js';
+
+const roboto = new Roboto({
+  host: 'api.example.com',
+  accessKey: 'key',
+  useCookies: true,  // Enabled by default
+  cookieDomain: 'auto'  // Auto-detect root domain
+});
+
+// Custom cookie configuration
+const cookieAdaptor = new CookieStorageAdaptor({
+  secure: true,
+  sameSite: 'Lax',
+  maxAge: 86400,  // 24 hours
+  domain: '.example.com'
+});
+
+const roboto = new Roboto({
+  host: 'api.example.com',
+  accessKey: 'key',
+  localStorageAdaptor: cookieAdaptor
+});
+```
+
+### Custom Storage Adapter
+
+```javascript
+const customAdaptor = {
+  getItem: async (key) => {
+    // Return stored value
+  },
+  setItem: async (key, value) => {
+    // Store value
+  },
+  removeItem: async (key) => {
+    // Remove value
+  }
+};
+
+const roboto = new Roboto({
+  host: 'api.example.com',
+  accessKey: 'key',
+  localStorageAdaptor: customAdaptor
+});
+```
+
+## Server-Side Usage (Node.js)
+
+Use with Express middleware for per-request instances:
+
+```javascript
+import Roboto from 'roboto-js';
+
+// Middleware to attach roboto to each request
+app.use((req, res, next) => {
+  // proxyReq allows per-request authentication
+  req.roboto = new Roboto({
+    host: 'api.example.com',
+    accessKey: process.env.ROBOTO_ACCESS_KEY
+  }, req);  // Pass request object
+  
+  next();
+});
+
+// Use in routes
+app.get('/api/sites', async (req, res) => {
+  const sites = await req.roboto.query('<@doc_website.site>', {});
+  res.json(sites);
+});
+```
+
+## Metrics API
+
+Track events and analytics:
+
+```javascript
+// Using default metrics endpoint
+await roboto.metrics.logEvent({
+  event: 'user_action',
+  properties: {
+    action: 'button_click',
+    page: 'home'
+  }
+});
+
+// Custom metrics host
+roboto.setMetricsHost('metrics.example.com');
+```
+
+## Environment-Specific Features
+
+### Browser
+
+- Automatic WebSocket connection
+- IndexedDB for local caching
+- Cookie-based authentication by default
+- Cross-subdomain cookie support
+
+### Node.js
+
+- Per-request instances with `proxyReq`
+- Custom header support for authentication
+- No WebSocket auto-connection
+
+## Advanced Features
+
+### Auto-Wrapping Responses
+
+The SDK automatically converts doctree objects to RbtObject instances:
+
+```javascript
+// Raw API call returns plain objects
+const response = await fetch('/api/custom-endpoint');
+const data = await response.json();
+
+// Wrap for RbtObject functionality
+const objects = roboto.wrapAsRbtObjects(data.items);
+
+// Now use RbtObject methods
+objects[0].set('title', 'New Title');
+await objects[0].save();
+```
+
+### Object Caching
+
+Objects are cached automatically to prevent duplicate instances:
+
+```javascript
+// Both calls return the same instance
+const obj1 = await roboto.load('<@doc.item>', 'abc123');
+const obj2 = await roboto.load('<@doc.item>', 'abc123');
+
+console.log(obj1 === obj2);  // true
+```
+
+### Error Handling
+
+Set a custom error handler:
+
+```javascript
+roboto.setErrorHandler((error, context) => {
+  console.error('API Error:', error.message);
+  console.error('Context:', context);
+  
+  // Custom error reporting
+  errorReporter.report(error);
+});
+```
+
+## Build & Development
+
+```bash
+# Install dependencies
+npm install
+
+# Build for production (strips console.log, keeps console.error)
+npm run build
+
+# Build CommonJS only
+npm run build:cjs
+
+# Build ES Modules only
+npm run build:esm
+
+# Update version
+npm run update-version
+
+# Clean install
+npm run clean
+```
+
+See [BUILD_NOTES.md](./BUILD_NOTES.md) for build configuration details.
+
+## Module Formats
+
+The package supports both module systems:
+
+**ES Modules (import)**
+```javascript
+import Roboto, { RbtObject, RbtFile } from 'roboto-js';
+```
+
+**CommonJS (require)**
+```javascript
+const Roboto = require('roboto-js');
+const { RbtObject, RbtFile } = require('roboto-js');
+```
+
+## TypeScript Support
+
+While this is a JavaScript library, it works seamlessly with TypeScript projects. Type definitions may be added in future versions.
+
+## Examples
+
+See the [examples](./examples) directory for complete working examples:
+
+- [sharing-example.js](./examples/sharing-example.js) - Access control patterns
+
+## Exports
+
+```javascript
+import Roboto, {
+  RbtApi,           // Low-level API client
+  RbtObject,        // Object wrapper class
+  RbtFile,          // File wrapper class
+  CookieStorageAdaptor  // Cookie-based storage
+} from 'roboto-js';
+```
+
+## Browser Compatibility
+
+- Modern browsers with ES6+ support
+- IndexedDB support for local caching
+- WebSocket support for real-time features
+- Cookie support for authentication
+
+## Node.js Compatibility
+
+- Node.js 14+ recommended
+- ES Modules or CommonJS
+- No browser-specific APIs used in core functionality
+
+## License
+
+ISC
+
+## Version History
+
+Current version: **1.9.5**
+
+Version is automatically synced from `package.json` during build.
+

package/dist/cjs/cookie_storage_adaptor.cjs

@@ -48,6 +48,16 @@ var CookieStorageAdaptor = exports["default"] = /*#__PURE__*/function () {
       // Keys that should be stored without prefix for server-side access
       serverAccessKeys: (_options$serverAccess = options.serverAccessKeys) !== null && _options$serverAccess !== void 0 ? _options$serverAccess : ['authtoken', 'accessKey', 'apikey']
     }, options);
+    /*
+    console.log('[CookieStorageAdaptor] Initialized with options:', {
+      secure: this.options.secure,
+      sameSite: this.options.sameSite,
+      path: this.options.path,
+      maxAge: this.options.maxAge,
+      domain: this.options.domain,
+      prefix: this.options.prefix,
+      serverAccessKeys: this.options.serverAccessKeys
+    })*/
   }
 
   /**
@@ -72,7 +82,8 @@ var CookieStorageAdaptor = exports["default"] = /*#__PURE__*/function () {
               cookieName = usePrefix ? this.options.prefix + key : key;
               name = cookieName + '=';
               decodedCookie = decodeURIComponent(document.cookie);
-              cookies = decodedCookie.split(';');
+              cookies = decodedCookie.split(';'); //console.log(`[CookieStorageAdaptor] getItem(${key}): looking for cookie "${cookieName}" ${usePrefix ? '(prefixed)' : '(server-accessible)'}`)
+              //console.log(`[CookieStorageAdaptor] Available cookies:`, cookies.map(c => c.trim().split('=')[0]).join(', '))
               _iterator = _createForOfIteratorHelper(cookies);
               _context.prev = 8;
               _iterator.s();
@@ -87,9 +98,10 @@ var CookieStorageAdaptor = exports["default"] = /*#__PURE__*/function () {
                 _context.next = 23;
                 break;
               }
-              rawValue = cookie.substring(name.length, cookie.length);
+              rawValue = cookie.substring(name.length, cookie.length); //console.log(`[CookieStorageAdaptor] Found cookie "${cookieName}" with raw value:`, rawValue)
+              // Handle JSON values (like rbtUser)
               _context.prev = 15;
-              parsedValue = JSON.parse(rawValue);
+              parsedValue = JSON.parse(rawValue); //console.log(`[CookieStorageAdaptor] getItem(${key}): returning parsed JSON:`, parsedValue)
               return _context.abrupt("return", parsedValue);
             case 20:
               _context.prev = 20;
@@ -143,12 +155,14 @@ var CookieStorageAdaptor = exports["default"] = /*#__PURE__*/function () {
               // Check if this key should be stored without prefix for server access
               usePrefix = !this.options.serverAccessKeys.includes(key);
               cookieName = usePrefix ? this.options.prefix + key : key; // Stringify objects/arrays like localStorage does
-              cookieValue = _typeof(value) === 'object' ? JSON.stringify(value) : String(value);
+              cookieValue = _typeof(value) === 'object' ? JSON.stringify(value) : String(value); //console.log(`[CookieStorageAdaptor] setItem(${key}): storing as "${cookieName}" ${usePrefix ? '(prefixed)' : '(server-accessible)'}`)
+              //console.log(`[CookieStorageAdaptor] Original value:`, value)
+              //console.log(`[CookieStorageAdaptor] Cookie value:`, cookieValue)
               // Build cookie string with security options
               secureFlag = this.options.secure ? '; Secure' : '';
               domainFlag = this.options.domain ? "; Domain=".concat(this.options.domain) : '';
               httpOnlyFlag = this.options.httpOnly ? '; HttpOnly' : '';
-              cookieString = "".concat(cookieName, "=").concat(encodeURIComponent(cookieValue), "; path=").concat(this.options.path, "; max-age=").concat(this.options.maxAge, "; SameSite=").concat(this.options.sameSite).concat(secureFlag).concat(domainFlag).concat(httpOnlyFlag);
+              cookieString = "".concat(cookieName, "=").concat(encodeURIComponent(cookieValue), "; path=").concat(this.options.path, "; max-age=").concat(this.options.maxAge, "; SameSite=").concat(this.options.sameSite).concat(secureFlag).concat(domainFlag).concat(httpOnlyFlag); //console.log(`[CookieStorageAdaptor] Full cookie string:`, cookieString)
               document.cookie = cookieString;
 
               // Verify the cookie was set by immediately reading it back
@@ -190,7 +204,8 @@ var CookieStorageAdaptor = exports["default"] = /*#__PURE__*/function () {
             case 2:
               // Check if this key should be stored without prefix for server access
               usePrefix = !this.options.serverAccessKeys.includes(key);
-              cookieName = usePrefix ? this.options.prefix + key : key;
+              cookieName = usePrefix ? this.options.prefix + key : key; //console.log(`[CookieStorageAdaptor] removeItem(${key}): removing cookie "${cookieName}" ${usePrefix ? '(prefixed)' : '(server-accessible)'}`)
+              // Check if cookie exists before removal
               _context3.next = 6;
               return this.getItem(key);
             case 6:
@@ -198,7 +213,7 @@ var CookieStorageAdaptor = exports["default"] = /*#__PURE__*/function () {
               if (existingValue !== null) {} else {}
               secureFlag = this.options.secure ? '; Secure' : '';
               domainFlag = this.options.domain ? "; Domain=".concat(this.options.domain) : '';
-              removalString = "".concat(cookieName, "=; path=").concat(this.options.path, "; expires=Thu, 01 Jan 1970 00:00:00 GMT; SameSite=").concat(this.options.sameSite).concat(secureFlag).concat(domainFlag);
+              removalString = "".concat(cookieName, "=; path=").concat(this.options.path, "; expires=Thu, 01 Jan 1970 00:00:00 GMT; SameSite=").concat(this.options.sameSite).concat(secureFlag).concat(domainFlag); //console.log(`[CookieStorageAdaptor] Removal cookie string:`, removalString)
               document.cookie = removalString;
 
               // Verify the cookie was removed