@symbo.ls/sdk 3.4.6 → 3.4.11

package/README.md

@@ -1,5 +1,16 @@
-# SDK
+# @symbo.ls/sdk
+
+[![npm version](https://img.shields.io/npm/v/@symbo.ls/sdk.svg)](https://www.npmjs.com/package/@symbo.ls/sdk)
+[![npm downloads](https://img.shields.io/npm/dm/@symbo.ls/sdk.svg)](https://www.npmjs.com/package/@symbo.ls/sdk)
+[![bundle size](https://img.shields.io/bundlephobia/minzip/@symbo.ls/sdk)](https://bundlephobia.com/package/@symbo.ls/sdk)
+[![license](https://img.shields.io/npm/l/@symbo.ls/sdk.svg)](https://github.com/nicholasgasior/symbo.ls/blob/main/LICENSE)
+[![node](https://img.shields.io/node/v/@symbo.ls/sdk.svg)](https://nodejs.org)
+[![ESM](https://img.shields.io/badge/module-ESM%20%7C%20CJS-blue)](https://www.npmjs.com/package/@symbo.ls/sdk)
+
+> Official SDK for the [Symbols](https://symbols.app) design platform — manage projects, collaborate in real-time, handle branches, pull requests, and more.
+
 ## Installation
+
 ```bash
 npm install @symbo.ls/sdk
 ```
@@ -7,11 +18,11 @@ npm install @symbo.ls/sdk
 ## Basic Usage
 
 ### Initialize SDK
+
 ```javascript
 import { SDK } from '@symbo.ls/sdk'
 
 const sdk = new SDK({
-  useNewServices: true,  // Use new service implementations
   apiUrl: 'https://api.symbols.app',
   socketUrl: 'https://api.symbols.app',
   timeout: 30000,
@@ -19,902 +30,688 @@ const sdk = new SDK({
   debug: false
 })
 
-// Initialize with context
 await sdk.initialize({
   authToken: 'your-auth-token',
-  appKey: 'your-app-key',
+  appKey: 'your-app-key'
 })
 ```
 
 ### Service Access
+
 ```javascript
-// Get service instances
 const auth = sdk.getService('auth')
-const socket = sdk.getService('socket')
-const symstory = sdk.getService('symstory')
-const based = sdk.getService('based')
-const ai = sdk.getService('ai')
+const project = sdk.getService('project')
+const branch = sdk.getService('branch')
+const pullRequest = sdk.getService('pullRequest')
+const collab = sdk.getService('collab')
+const file = sdk.getService('file')
+const payment = sdk.getService('payment')
+const plan = sdk.getService('plan')
+const subscription = sdk.getService('subscription')
+const dns = sdk.getService('dns')
+const admin = sdk.getService('admin')
+const screenshot = sdk.getService('screenshot')
+const tracking = sdk.getService('tracking')
+const waitlist = sdk.getService('waitlist')
+const metrics = sdk.getService('metrics')
+const integration = sdk.getService('integration')
+const featureFlag = sdk.getService('featureFlag')
+```
+
+All service methods are also available directly on the SDK instance via proxy methods:
+
+```javascript
+// These are equivalent:
+sdk.getService('project').getProject(projectId)
+sdk.getProject(projectId)
 ```
 
-### Status Checking
+### Status & Context
+
 ```javascript
 // Check if SDK is ready
-const ready = sdk.isReady()
+sdk.isReady()
 
 // Get detailed status
 const status = sdk.getStatus()
-console.log(status)
-/* Output:
-{
-  ready: true,
-  services: [
-    { name: 'auth', ready: true, ... },
-    { name: 'socket', ready: true, ... },
-    { name: 'symstory', ready: true, ... },
-    { name: 'based', ready: true, ... },
-    { name: 'ai', ready: true, ... }
-  ],
-  context: { ... }
-}
-*/
+// { ready: true, services: [...], context: {...} }
+
+// Update context
+sdk.updateContext({ ... })
+
+// Cleanup
+await sdk.destroy()
 ```
 
-### Context Management
+### Root Event Bus
+
+The SDK exposes a global event bus for cross-service communication:
+
 ```javascript
-// Update context
-sdk.updateContext({
-  auth: {
-    authToken: 'new-token'
-  }
-})
+sdk.rootBus.on('checkpoint:done', (payload) => { ... })
+sdk.rootBus.on('clients:updated', (payload) => { ... })
+sdk.rootBus.on('bundle:done', (payload) => { ... })
+sdk.rootBus.on('bundle:error', (payload) => { ... })
 ```
 
-## Service-Specific Usage
+---
+
+## Services
 
 ### Auth Service
+
+**Authentication:**
+
 ```javascript
 const auth = sdk.getService('auth')
 
-/**
- * Login a user
- * @param {string} email - User's email
- * @param {string} password - User's password
- */
-await auth.login(email, password)
-
-/**
- * Register a new user
- * @param {Object} userData - User data
- */
-await auth.register(userData)
-
-/**
- * Logout the current user
- */
+await auth.register(userData, options)
+await auth.login(email, password, options)
 await auth.logout()
-
-/**
- * Request a password reset
- * @param {string} email - User's email
- */
+await auth.refreshToken(refreshToken)
+await auth.googleAuth(idToken, inviteToken, options)
+await auth.googleAuthCallback(code, redirectUri, inviteToken, options)
+await auth.githubAuth(code, inviteToken, options)
 await auth.requestPasswordReset(email)
-
-/**
- * Confirm a password reset
- * @param {string} token - Reset token
- * @param {string} newPassword - New password
- */
-await auth.confirmPasswordReset(token, newPassword)
-
-/**
- * Update a user's role
- * @param {string} userId - User ID
- * @param {string} newRole - New role
- */
-await auth.updateUserRole(userId, newRole)
-
-/**
- * Update a member's role in a project
- * @param {string} projectId - Project ID
- * @param {string} userId - User ID
- * @param {string} role - New role
- */
-await auth.updateMemberRole(projectId, userId, role)
-
-/**
- * Update a project's tier
- * @param {string} projectId - Project ID
- * @param {string} newTier - New tier
- */
-await auth.updateProjectTier(projectId, newTier)
-
-/**
- * Invite a member to a project
- * @param {string} projectId - Project ID
- * @param {string} email - Member's email
- * @param {string} role - Member's role
- * @param {string} name - Member's name
- */
-await auth.inviteMember(projectId, email, role, name)
-
-/**
- * Accept an invite
- * @param {string} token - Invite token
- */
-await auth.acceptInvite(token)
-
-/**
- * Confirm a user's registration
- * @param {string} token - Registration token
- */
+await auth.confirmPasswordReset(token, password)
 await auth.confirmRegistration(token)
+await auth.requestPasswordChange()
+await auth.confirmPasswordChange(currentPassword, newPassword, code)
+```
 
-/**
- * Get members of a project
- * @param {string} projectId - Project ID
- */
-await auth.getProjectMembers(projectId)
-
-/**
- * Check if a user has a specific permission
- * @param {string} projectId - Project ID
- * @param {string} permission - Permission to check
- */
-const hasPermission = auth.hasPermission(projectId, 'edit')
-
-/**
- * Check if a user has a global permission
- * @param {string} globalRole - User's global role
- * @param {string} permission - Permission to check
- */
-const hasGlobalPermission = auth.hasGlobalPermission('admin', 'manage')
-
-/**
- * Check if a user has a project-specific permission
- * @param {Object} projectRoles - User's project roles
- * @param {string} projectId - Project ID
- * @param {string} requiredPermission - Permission to check
- */
-const hasProjectPermission = auth.checkProjectPermission(projectRoles, projectId, 'edit')
-
-/**
- * Check if a project has a specific feature
- * @param {string} projectTier - Project's tier
- * @param {string} feature - Feature to check
- */
-const hasProjectFeature = auth.checkProjectFeature('pro1', 'aiCopilot:5')
-
-/**
- * Check if a user can perform a specific operation
- * @param {string} projectId - Project ID
- * @param {string} operation - Operation to check
- * @param {Object} options - Additional options
- */
-const canPerformOperation = await auth.canPerformOperation(projectId, 'edit', { checkFeatures: true })
-
-/**
- * Execute an action with permission check
- * @param {string} projectId - Project ID
- * @param {string} operation - Operation to check
- * @param {function} action - Action to execute
- */
-await auth.withPermission(projectId, 'edit', () => {
-  // Action to perform
-})
+**User Data:**
 
-/**
- * Get project access information
- * @param {string} projectId - Project ID
- */
-const projectAccess = await auth.getProjectAccess(projectId)
+```javascript
+await auth.getMe(options)
+auth.getStoredAuthState()
+auth.getAuthToken()
+auth.getUserProfile()
+await auth.updateUserProfile(profileData)
+await auth.getUserProjects()
+await auth.getUser(userId)
+await auth.getUserByEmail(email)
+auth.isAuthenticated()
+auth.hasValidTokens()
+auth.getCurrentUser()
 ```
 
-### Socket Service
+**Project Roles:**
+
 ```javascript
-const socket = sdk.getService('socket')
+await auth.getMyProjectRole(projectId)       // cached
+await auth.getMyProjectRoleByKey(projectKey)  // cached
+auth.clearProjectRoleCache(projectId)
+```
 
-/**
- * Subscribe to events
- * @param {string} event - Event name
- * @param {function} callback - Callback function
- * @returns {function} Unsubscribe function
- */
-const unsubscribe = socket.subscribe('updates', (data) => {
-  console.log('Received:', data)
-})
+**Permissions:**
 
-/**
- * Send data
- * @param {string} event - Event name
- * @param {Object} data - Data to send
- */
-socket.send('update', {
-  type: 'change',
-  data: { ... }
-})
+```javascript
+auth.hasPermission(requiredPermission)
+auth.hasGlobalPermission(globalRole, requiredPermission)
+auth.checkProjectPermission(projectRole, requiredPermission)
+auth.checkProjectFeature(projectTier, feature)
+await auth.canPerformOperation(projectId, operation, options)
+await auth.withPermission(projectId, operation, action)
+```
 
-// Cleanup
-unsubscribe()
-```
-
-### Symstory Service
-```javascript
-const symstory = sdk.getService('symstory')
-
-/**
- * Get data
- * @param {Object} query - Query object
- */
-await symstory.getData(query)
-
-/**
- * Update data
- * @param {Object} changes - Changes to apply
- */
-await symstory.updateData(changes)
-
-/**
- * Delete data
- * @param {string} path - Path to data
- */
-await symstory.deleteData(path)
-
-/**
- * Get an item
- * @param {string} type - Item type
- * @param {string} key - Item key
- */
-await symstory.getItem(type, key)
-
-/**
- * Add an item
- * @param {string} type - Item type
- * @param {Object} data - Item data
- */
-await symstory.addItem(type, data)
-
-/**
- * Update an item
- * @param {string} type - Item type
- * @param {Object} data - Item data
- */
-await symstory.updateItem(type, data)
-
-/**
- * Delete an item
- * @param {string} type - Item type
- * @param {string} key - Item key
- */
-await symstory.deleteItem(type, key)
-
-/**
- * Get branches
- */
-await symstory.getBranches()
-
-/**
- * Create a branch
- * @param {Object} branch - Branch data
- */
-await symstory.createBranch(branch)
-
-/**
- * Merge a branch
- * @param {Object} branch - Branch data
- */
-await symstory.mergeBranch(branch)
-
-/**
- * Restore a version
- * @param {Object} version - Version data
- */
-await symstory.restoreVersion(version)
-```
-
-### Based Service
-```javascript
-const based = sdk.getService('based')
-
-/**
- * Query data
- * @param {string} collection - Collection name
- * @param {Object} query - Query object
- */
-const result = await based.query(collection, query)
-
-/**
- * Subscribe to changes
- * @param {string} collection - Collection name
- * @param {Object} query - Query object
- * @param {function} callback - Callback function
- * @returns {function} Unsubscribe function
- */
-const unsubscribe = based.subscribe(collection, query, (data) => {
-  console.log('Data updated:', data)
-})
+### Project Service
 
-/**
- * Call a function
- * @param {string} functionName - Function name
- * @param {Object} params - Function parameters
- */
-await based.call('functionName', params)
+**Project Management:**
 
-/**
- * Get a project
- * @param {string} projectId - Project ID
- */
-await based.getProject(projectId)
+```javascript
+const project = sdk.getService('project')
 
-/**
- * Create a project
- * @param {Object} projectData - Project data
- */
-await based.createProject(projectData)
+await project.createProject(projectData)
+await project.getProjects(params)
+await project.getProject(projectId)
+await project.getProjectByKey(key)
+await project.getProjectDataByKey(key, options)
+await project.getPublicProject(projectId)
+await project.listPublicProjects(params)
+await project.updateProject(projectId, data)
+await project.updateProjectComponents(projectId, components)
+await project.updateProjectSettings(projectId, settings)
+await project.updateProjectName(projectId, name)
+await project.updateProjectPackage(projectId, pkg)
+await project.duplicateProject(projectId, newName, newKey, targetUserId)
+await project.removeProject(projectId)
+await project.checkProjectKeyAvailability(key)
+```
 
-/**
- * Fetch a user
- * @param {string} userId - User ID
- */
-await based.fetchUser(userId)
+**Role Permissions Config:**
 
-/**
- * Fetch a project
- * @param {string} projectId - Project ID
- */
-await based.fetchProject(projectId)
+```javascript
+await project.getProjectRolePermissionsConfig(projectId, options)
+await project.updateProjectRolePermissionsConfig(projectId, rolePermissions, options)
 ```
 
-### AI Service
+**Members:**
+
 ```javascript
-const ai = sdk.getService('ai')
+await project.getProjectMembers(projectId)
+await project.inviteMember(projectId, email, role, options)
+await project.createMagicInviteLink(projectId, options)
+await project.acceptInvite(token)
+await project.updateMemberRole(projectId, memberId, role)
+await project.removeMember(projectId, memberId)
+```
+
+**Libraries:**
 
-/**
- * Prompt the AI
- * @param {string} query - Query string
- * @param {Object} options - Query options
- */
-const response = await ai.prompt(query, options)
+```javascript
+await project.getAvailableLibraries(params)
+await project.getProjectLibraries(projectId)
+await project.addProjectLibraries(projectId, libraryIds)
+await project.removeProjectLibraries(projectId, libraryIds)
 ```
 
-### Tracking Service (Grafana Faro)
+**Project Data (Version Control):**
+
 ```javascript
-// 1) Initialize SDK with tracking config (early in app startup)
-const sdk = new SDK({
-  useNewServices: true,
-  apiUrl: 'https://api.symbols.app',
-  // Tracking configuration mirrors TrackingService options
-  tracking: {
-    url: 'https://<your-faro-receiver-url>', // FO ingest/collector URL
-    appName: 'Symbols Platform',
-    environment: 'development',              // 'production' | 'staging' | 'testing' | 'development'
-    appVersion: '1.0.0',
-    sessionTracking: true,
-    enableTracing: true,                     // adds browser tracing when available
-    globalAttributes: { region: 'us-east-1' }
-  }
-})
-await sdk.initialize()
+await project.applyProjectChanges(projectId, changes, options)
+// changes: [['update', ['components', 'Button'], { color: 'blue' }], ['delete', ['pages', 'old']]]
+// options: { message: 'Update button', type: 'patch' }
 
-// 2) Get the tracking service
-const tracking = sdk.getService('tracking')
+await project.getProjectData(projectId, options)
+await project.getProjectVersions(projectId, options)
+await project.restoreProjectVersion(projectId, version, options)
+await project.updateProjectItem(projectId, path, value, options)
+await project.deleteProjectItem(projectId, path, options)
+await project.setProjectValue(projectId, path, value, options)
+await project.addProjectItems(projectId, items, options)
+await project.getProjectItemByPath(projectId, path, options)
+```
+
+**Environments:**
 
-// 3) Send signals
-tracking.trackEvent('purchase', { amount: 42, currency: 'USD' })
-tracking.trackMeasurement('cart_value', { value: 42 })
-tracking.logError('checkout failed', { step: 'payment' })
-tracking.trackView('Checkout', { stage: 'payment' })
-tracking.setUser({ id: 'u_123', email: 'user@example.com' })
-```
-
-#### Configuration
-Provide these under `tracking` when creating the `SDK` (or later via `tracking.configureTracking()`):
-
-- `url` string: Frontend Observability/Faro ingestion URL. If omitted and no custom transports are provided, tracking is disabled.
-- `appName` string: Logical application name used in Grafana dashboards.
-- `appVersion` string: App version shown in Grafana.
-- `environment` string: One of your environments; default resolves from runtime (`production`, `staging`, `testing`, `development`).
-- `sessionTracking` boolean: Enable Faro session tracking. Default: `true`.
-- `enableTracing` boolean: Enable web tracing and send to Tempo (if collector configured). Default: `true`.
-- `globalAttributes` object: Key/values merged into every signal.
-- `user` object: Initial user attributes.
-- `maxQueueSize` number: Max queued calls before client setup. Default: `100`.
-- `isolate` boolean: Create an isolated Faro instance.
-- `transports` array | `transport` any: Custom transports (advanced).
-- `instrumentations` array | `instrumentationsFactory(runtime) => Promise<array>` | `webInstrumentationOptions` object: Control Faro web instrumentations.
-
-Note:
-- Tracking is automatically disabled in non‑browser environments.
-- Calls are queued until the Faro client is ready. For specific calls, pass `{ queue: false }` to skip queuing.
-
-#### Method reference
-The following methods are available via `sdk.getService('tracking')` and map to `utils/services.js`:
-
-- `configureTracking(trackingOptions)` / `configure(trackingOptions)`: Merge/override runtime tracking options (supports all config keys above).
-- `trackEvent(name, attributes?, options?)`
-  - `name` string (required)
-  - `attributes` object merged with global attributes
-  - `options` object:
-    - `domain` string | null
-    - `queue` boolean (whether to queue if client not ready)
-    - Additional transport options are forwarded to Faro
-  - Example:
-  ```javascript
-  tracking.trackEvent('signup_attempt', { method: 'email' }, { domain: 'auth' })
-  ```
-- `trackError(error, options?)` / `captureException(error, options?)`
-  - `error` Error | string
-  - `options` can be:
-    - object with Faro error options (`context`, `type`, `stackFrames`, `skipDedupe`, `timestampOverwriteMs`, etc.)
-    - or a plain context object (shorthand)
-    - `queue` boolean supported
-  - Example:
-  ```javascript
-  tracking.trackError(new Error('Login failed'), { context: { screen: 'Login' } })
-  ```
-- `logMessage(message, level='info', context?)`
-  - Convenience wrappers: `logDebug`, `logInfo`, `logWarning`/`logWarn`, `logErrorMessage`/`logError`
-  - `message` string | string[]
-  - `context` object merged with global attributes
-  - Example:
-  ```javascript
-  tracking.logWarning('Slow response', { route: '/checkout', ttfbMs: 900 })
-  ```
-- `addBreadcrumb(message, attributes?)`
-  - Adds a low‑cost breadcrumb via `trackEvent('breadcrumb', ...)`
-  - Example:
-  ```javascript
-  tracking.addBreadcrumb('Open modal', { id: 'planLimits' })
-  ```
-- `trackMeasurement(type, values, options?)`
-  - `type` string (required)
-  - `values` object | number. If number, it becomes `{ value: <number> }`.
-  - `options`:
-    - `attributes` object (merged into payload.attributes)
-    - `context` object (transport context)
-    - `queue` boolean
-    - Any additional transport options
-  - Example:
-  ```javascript
-  tracking.trackMeasurement('cart_value', 42, { context: { currency: 'USD' } })
-  ```
-- `trackView(name, attributes?)`
-  - Sets the current view/page in Faro
-  - Example:
-  ```javascript
-  tracking.trackView('Dashboard', { section: 'Analytics' })
-  ```
-- `setUser(user, options?)` / `clearUser()`
-  - `user` object with arbitrary attributes; supports `{ queue: boolean }`
-  - Example:
-  ```javascript
-  tracking.setUser({ id: 'u_123', role: 'admin' })
-  ```
-- `setSession(session, options?)` / `clearSession()`
-  - Attach custom session data; supports `{ queue: boolean, ...sessionOptions }`
-- `setGlobalAttributes(attributes)` / `setGlobalAttribute(key, value)` / `removeGlobalAttribute(key)`
-  - Manage the global attributes merged into every signal
-- `flushQueue()`
-  - Immediately runs all queued calls (no‑op if client not ready)
-- `getClient()`
-  - Returns the underlying Faro client (or `null` if not ready)
-- `isEnabled()` / `isInitialized()`
-  - Status helpers
-
-#### Example: auth error tracking from services
-The SDK’s services automatically send errors to tracking:
 ```javascript
-try {
-  await auth.login(email, password)
-} catch (error) {
-  // BaseService forwards details to tracking.trackError(...)
-}
+await project.listEnvironments(projectId, options)
+await project.activateMultipleEnvironments(projectId, options)
+await project.upsertEnvironment(projectId, envKey, config, options)
+await project.updateEnvironment(projectId, envKey, updates, options)
+await project.publishToEnvironment(projectId, envKey, payload, options)
+await project.deleteEnvironment(projectId, envKey, options)
+await project.promoteEnvironment(projectId, fromEnvKey, toEnvKey, options)
 ```
 
-#### Visualizing in Grafana
-- Use the Frontend Observability (Faro) data source and pick:
-  - Service = your `appName`
-  - Environment = your `environment`
-- Panels for page loads and Web Vitals require web instrumentations and real page traffic.
-- If self‑hosting with a Faro collector → Loki/Tempo, ensure the FO app is installed and the dashboard uses the FO data source; otherwise create custom panels with LogQL over Loki.
+**Favorites & Recent:**
 
-## Error Handling
 ```javascript
-try {
-  await sdk.initialize()
-} catch (error) {
-  console.error('SDK initialization failed:', error.message)
-}
+await project.getFavoriteProjects()
+await project.addFavoriteProject(projectId)
+await project.removeFavoriteProject(projectId)
+await project.getRecentProjects(options)
 ```
 
-## Cleanup
+**Access Control:**
+
 ```javascript
-// Services are automatically cleaned up when SDK is destroyed
-sdk.destroy()
+await project.setProjectAccess(projectId, access)       // account/team/organization/public
+await project.setProjectVisibility(projectId, visibility) // public/private/password-protected
 ```
 
-## Configuration Options
+### Branch Service
+
 ```javascript
-const options = {
-  useNewServices: true,
-  apiUrl: 'https://api.symbols.app',
-  socketUrl: 'https://api.symbols.app',
-  timeout: 30000,
-  retryAttempts: 3,
-  debug: false
-}
+const branch = sdk.getService('branch')
 
-const sdk = new SDK(options)
-```
+await branch.listBranches(projectId)
+await branch.createBranch(projectId, branchData)
+await branch.deleteBranch(projectId, branchName)
+await branch.renameBranch(projectId, branchName, newName)
+await branch.getBranchChanges(projectId, branchName, options)
+await branch.mergeBranch(projectId, branchName, mergeData)
+await branch.resetBranch(projectId, branchName)
+await branch.publishVersion(projectId, publishData)
 
-# Permissions System
+// Helper methods
+await branch.createFeatureBranch(projectId, featureName)  // creates 'feature/<name>'
+await branch.createHotfixBranch(projectId, hotfixName)
+await branch.branchExists(projectId, branchName)
+await branch.previewMerge(projectId, sourceBranch, targetBranch)
+await branch.commitMerge(projectId, sourceBranch, options)
+await branch.getBranchStatus(projectId, branchName)
+await branch.deleteBranchSafely(projectId, branchName, options)
+await branch.getBranchesWithStatus(projectId)
+branch.validateBranchName(branchName)
+branch.sanitizeBranchName(branchName)
+```
 
-## Quick Start
+### Pull Request Service
 
 ```javascript
-// Check if user can edit a project
-const canEdit = sdk.hasPermission(projectId, 'edit')
+const pr = sdk.getService('pullRequest')
 
-// Check if project has AI Copilot feature
-const hasCopilot = sdk.checkProjectFeature(projectTier, 'aiCopilot')
+await pr.createPullRequest(projectId, pullRequestData)
+await pr.listPullRequests(projectId, options)
+await pr.getPullRequest(projectId, prId)
+await pr.reviewPullRequest(projectId, prId, reviewData)
+await pr.addPullRequestComment(projectId, prId, commentData)
+await pr.mergePullRequest(projectId, prId)
+await pr.getPullRequestDiff(projectId, prId)
+await pr.closePullRequest(projectId, prId)
+await pr.reopenPullRequest(projectId, prId)
 
-// Check if user has global admin access
-const isAdmin = sdk.hasGlobalPermission('admin', 'governance')
+// Helper methods
+await pr.approvePullRequest(projectId, prId, comment)
+await pr.requestPullRequestChanges(projectId, prId, threads)
+await pr.getOpenPullRequests(projectId, options)
+await pr.getClosedPullRequests(projectId, options)
+await pr.getMergedPullRequests(projectId, options)
+await pr.isPullRequestMergeable(projectId, prId)
+await pr.getPullRequestStatusSummary(projectId, prId)
+await pr.getPullRequestStats(projectId, options)
 ```
 
-## Permission Types
+### Collab Service
+
+Real-time collaboration via WebSocket and Yjs.
 
-### Core Permissions
-| Permission | Use Case | Required Permissions | Features |
-|------------|----------|---------------------|-----------|
-| edit | Edit content | editMode, showCode | editMode |
-| view | View content | showContent | canvasPages |
-| design | Access design tools | editMode, showCode | accessToSymbolsLibrary |
-| manage | Project settings | projectSettings, iam | workspaceAdministration |
+```javascript
+const collab = sdk.getService('collab')
 
-### Version Control
-| Permission | Use Case | Required Permissions | Features |
-|------------|----------|---------------------|-----------|
-| branch | Manage branches | versions | branching, versionHistory |
-| merge | Merge changes | versions | branching |
+// Connection
+await collab.connect({ projectId, branch, authToken })
+collab.disconnect()
+collab.isConnected()
+collab.getConnectionInfo()
 
-### AI Features
-| Permission | Use Case | Tier Limits |
-|------------|----------|-------------|
-| aiCopilot | AI assistance | Free: 3, Pro1: 5, Pro2: 15 |
-| aiChatbot | Chat support | Free: 3, Pro1: 5, Pro2: 15 |
+// Data updates
+collab.updateData(tuples, options)
+collab.addItem(type, data, opts)
+collab.addMultipleItems(items, opts)
+collab.updateItem(type, data, opts)
+collab.deleteItem(type, key, opts)
 
-## Examples
+// Undo/Redo
+collab.undo()
+collab.redo()
+collab.canUndo()
+collab.canRedo()
+collab.getUndoStackSize()
+collab.getRedoStackSize()
+collab.clearUndoHistory()
+collab.checkpoint()
 
-### 1. Basic Permission Check
-```javascript
-const projectId = '123'
-const canUserEdit = sdk.hasPermission(projectId, 'edit')
+// Presence
+collab.sendCursor(data)
+collab.sendPresence(data)
+collab.toggleLive(flag)
 
-if (canUserEdit) {
-  // Allow editing
-  sdk.enableEditMode()
-} else {
-  // Show view-only mode
-  sdk.enableViewMode()
-}
+// Accessors
+collab.ydoc   // Yjs document
+collab.socket  // Socket instance
 ```
 
-### 2. Feature Access by Tier
+### File Service
+
 ```javascript
-// Check AI feature access
-const projectTier = 'pro1'
-const copilotTokens = sdk.checkProjectFeature(projectTier, 'aiCopilot')
+const file = sdk.getService('file')
 
-if (copilotTokens) {
-  console.log(`User has access to ${copilotTokens} AI tokens`)
-} else {
-  console.log('No AI access available')
-}
+await file.uploadFile(file, options)
+await file.updateProjectIcon(projectId, iconFile)
+await file.uploadImage(imageFile, options)
+await file.uploadDocument(documentFile, options)
+await file.uploadMultipleFiles(files, options)
+file.getFileUrl(fileId)
+file.validateFile(file, options)
 ```
 
-### 3. Role-Based Access
+### Payment Service
+
 ```javascript
-// Admin checking multiple permissions
-const isProjectAdmin = sdk.checkProjectPermission(
-  userRoles,
-  projectId,
-  'admin'
-)
+const payment = sdk.getService('payment')
 
-if (isProjectAdmin) {
-  // Can access admin features
-  const canInvite = sdk.hasPermission(projectId, 'invite')
-  const canManage = sdk.hasPermission(projectId, 'manage')
-}
+await payment.checkout(options)
+await payment.getSubscriptionStatus(projectId)
+await payment.hasActiveSubscription(projectId)
+await payment.getSubscriptionDetails(projectId)
+await payment.checkoutForPlan(options)
+await payment.checkoutForTeam(options)
+await payment.getSubscriptionSummary(projectId)
 ```
 
-### 4. Complex Permission Scenarios
+### Plan Service
+
 ```javascript
-// Check if user can perform branch merge
-const canMerge = projectId => {
-  const hasPermission = sdk.hasPermission(projectId, 'merge')
-  const isProtectedBranch = sdk.getBranchProtection(projectId)
+const plan = sdk.getService('plan')
 
-  if (isProtectedBranch) {
-    return hasPermission && sdk.hasPermission(projectId, 'manage')
-  }
+// Public (no auth required)
+await plan.getPlans()
+await plan.getPlan(planId)
+await plan.getPlansWithPricing()
+await plan.getPlanByKey(key)
+await plan.getActivePlans()
+await plan.getPlansByPriceRange(minPrice, maxPrice)
 
-  return hasPermission
-}
+// Admin
+await plan.getAdminPlans()
+await plan.createPlan(planData)
+await plan.updatePlan(planId, planData)
+await plan.deletePlan(planId)
+await plan.initializePlans()
 ```
 
-## Role Permissions
+### Subscription Service
 
-### Global Roles
 ```javascript
-const ROLE_PERMISSIONS = {
-  guest: ['viewPublicProjects'],
-  user: ['viewPublicProjects', 'createProject'],
-  admin: ['viewPublicProjects', 'createProject', 'governance'],
-  superAdmin: ['viewPublicProjects', 'createProject', 'governance', 'managePlatform']
-}
+const subscription = sdk.getService('subscription')
+
+await subscription.createSubscription(subscriptionData)
+await subscription.getProjectStatus(projectId)
+await subscription.getUsage(subscriptionId)
+await subscription.cancelSubscription(subscriptionId)
+await subscription.listInvoices(subscriptionId, options)
+await subscription.getPortalUrl(projectId)
+await subscription.getProjectSubscription(projectId)
+await subscription.getProjectUsage(projectId)
+await subscription.hasActiveSubscription(projectId)
+await subscription.changeSubscription(projectId, planId)
+await subscription.downgrade(projectId)
 ```
 
-### Project Roles
+### DNS Service
+
 ```javascript
-const PROJECT_ROLE_PERMISSIONS = {
-  guest: ['platformSettings', 'showContent'],
-  editor: ['platformSettings', 'showContent', 'showCode', 'editMode', 'versions'],
-  admin: [
-    // Editor permissions +
-    'inviteMembers',
-    'branchProtection',
-    'projectSettings'
-  ],
-  owner: [
-    // Admin permissions +
-    'copyPasteAllowanceSetting',
-    'iam'
-  ]
-}
+const dns = sdk.getService('dns')
+
+await dns.createDnsRecord(domain, options)
+await dns.getDnsRecord(domain)
+await dns.removeDnsRecord(domain)
+await dns.getCustomHost(hostname)
+await dns.addProjectCustomDomains(projectId, customDomains, options)
+await dns.isDomainAvailable(domain)
+await dns.getDomainStatus(domain)
+await dns.verifyDomainOwnership(domain)
+await dns.getProjectDomains(projectId)
+await dns.removeProjectCustomDomain(projectId, domain)
+dns.validateDomain(domain)
+dns.formatDomain(domain)
+dns.extractDomainFromUrl(url)
 ```
 
-## Common Use Cases
+### Admin Service
 
-1. **Creating New Project**
 ```javascript
-if (sdk.hasGlobalPermission(userRole, 'createProject')) {
-  const projectId = await sdk.createProject()
-  await sdk.assignUserRole(userId, projectId, 'owner')
-}
+const admin = sdk.getService('admin')
+
+await admin.getAdminUsers(params)
+await admin.updateUser(userId, userData)
+await admin.searchAdminUsers(searchQuery, options)
+await admin.getAdminUsersByEmails(emails)
+await admin.getAdminUsersByIds(ids)
+await admin.assignProjectsToUser(userId, options)
+await admin.assignSpecificProjectsToUser(userId, projectIds, role)
+await admin.assignAllProjectsToUser(userId, role)
+await admin.getUserStats(userId)
+await admin.bulkUpdateUsers(updates)
+await admin.getUsersByRole(role)
+await admin.getUsersByStatus(status)
+await admin.activateUser(userId)
+await admin.deactivateUser(userId)
+await admin.suspendUser(userId)
+await admin.promoteToAdmin(userId)
+await admin.demoteFromAdmin(userId)
 ```
 
-2. **Inviting Team Members**
+### Screenshot Service
+
 ```javascript
-const canInvite = sdk.hasPermission(projectId, 'invite')
-if (canInvite) {
-  const tier = sdk.getProjectTier(projectId)
-  const maxMembers = TIER_LIMITS[tier].teamMembers
-  const currentSize = await sdk.getCurrentTeamSize()
+const screenshot = sdk.getService('screenshot')
 
-  if (currentSize < maxMembers) {
-    await sdk.inviteTeamMember(email, 'editor')
-  }
-}
+await screenshot.createScreenshotProject(payload)
+await screenshot.getProjectScreenshots(projectKey, params)
+await screenshot.reprocessProjectScreenshots(projectKey, body)
+await screenshot.recreateProjectScreenshots(projectKey, body)
+await screenshot.deleteProjectScreenshots(projectKey)
+await screenshot.getThumbnailCandidate(projectKey, options)
+await screenshot.updateProjectThumbnail(projectKey, body)
+await screenshot.refreshThumbnail(projectKey)
+await screenshot.getPageScreenshot(screenshotId, format)
+await screenshot.getComponentScreenshot(screenshotId, format)
+await screenshot.getScreenshotByKey(key)
+await screenshot.getQueueStatistics()
 ```
 
-3. **Managing AI Features**
+### Tracking Service (Grafana Faro)
+
 ```javascript
-const handleAIFeature = async (projectId) => {
-  const tier = await sdk.getProjectTier(projectId)
-  const copilotAccess = sdk.checkProjectFeature(tier, 'aiCopilot')
+const tracking = sdk.getService('tracking')
 
-  if (copilotAccess) {
-    const tokensLeft = await sdk.getAITokensRemaining(projectId)
-    return {
-      hasAccess: true,
-      tokens: tokensLeft,
-      maxTokens: copilotAccess
-    }
-  }
+// Events
+tracking.trackEvent('purchase', { amount: 42, currency: 'USD' })
+tracking.trackError(new Error('Login failed'), { context: { screen: 'Login' } })
+tracking.captureException(error, context)
+tracking.trackMeasurement('cart_value', 42, { context: { currency: 'USD' } })
+tracking.trackView('Dashboard', { section: 'Analytics' })
 
-  return { hasAccess: false }
-}
-```
+// Logging
+tracking.logMessage(message)
+tracking.logDebug(message)
+tracking.logInfo(message)
+tracking.logWarning(message)
+tracking.logError(message)
+tracking.addBreadcrumb('Open modal', { id: 'planLimits' })
 
-4. **Branch Protection**
-```javascript
-const protectBranch = async (projectId, branchName) => {
-  const canManage = sdk.hasPermission(projectId, 'manage')
-  if (!canManage) return false
+// User & Session
+tracking.setUser({ id: 'u_123', role: 'admin' })
+tracking.clearUser()
+tracking.setSession(session)
+tracking.clearSession()
 
-  return sdk.setBranchProtection(projectId, branchName, {
-    requireReview: true,
-    requiredApprovals: 2,
-    enforceAdminReview: true
-  })
-}
+// Global Attributes
+tracking.setGlobalAttributes(attributes)
+tracking.setGlobalAttribute(key, value)
+tracking.removeGlobalAttribute(key)
+
+// Queue & Status
+tracking.flushQueue()
+tracking.getClient()
+tracking.isEnabled()
+tracking.isInitialized()
 ```
 
-## Error Handling
+#### Tracking Configuration
 
 ```javascript
-try {
-  const hasAccess = await sdk.hasPermission(projectId, 'edit')
-  if (!hasAccess) {
-    throw new Error('PERMISSION_DENIED')
-  }
-  await sdk.editProject(projectId)
-} catch (error) {
-  switch (error.code) {
-    case 'PERMISSION_DENIED':
-      console.error('User lacks required permissions')
-      break
-    case 'TIER_LIMIT_EXCEEDED':
-      console.error('Upgrade required for this feature')
-      break
-    default:
-      console.error('Unexpected error:', error)
+const sdk = new SDK({
+  tracking: {
+    url: 'https://<your-faro-receiver-url>',
+    appName: 'Symbols Platform',
+    environment: 'production',
+    appVersion: '1.0.0',
+    sessionTracking: true,
+    enableTracing: true,
+    globalAttributes: { region: 'us-east-1' }
   }
-}
+})
 ```
 
-## Token Management
+Tracking is automatically disabled on localhost and in non-browser environments.
+
+### Waitlist Service
+
+```javascript
+const waitlist = sdk.getService('waitlist')
 
-The SDK now includes automatic token management with persistence and refresh capabilities:
+await waitlist.joinWaitlist(data)              // public
+await waitlist.listWaitlistEntries(options)     // admin
+await waitlist.updateWaitlistEntry(id, update)  // admin
+await waitlist.inviteWaitlistEntry(id)          // admin
+```
 
-### Features
-- **Automatic Token Refresh**: Tokens are refreshed automatically before expiration
-- **Persistent Storage**: Tokens persist across page refreshes using localStorage
-- **Secure Handling**: Automatic cleanup on logout and error handling
-- **Flexible Storage**: Supports localStorage, sessionStorage, or memory storage
+### Metrics Service
 
-### Configuration
 ```javascript
-import { getTokenManager } from '@symbols/sdk'
+const metrics = sdk.getService('metrics')
 
-// Configure token management (optional - handled automatically by CoreService)
-const tokenManager = getTokenManager({
-  storageType: 'localStorage', // 'localStorage' | 'sessionStorage' | 'memory'
-  refreshBuffer: 60 * 1000, // Refresh 1 minute before expiry
-  apiUrl: '/api',
-  onTokenRefresh: (tokens) => console.log('Token refreshed'),
-  onTokenExpired: () => console.log('Session expired'),
-  onTokenError: (error) => console.error('Token error:', error)
-})
+await metrics.getContributions(options)  // contribution heat-map stats
 ```
 
-### Usage with CoreService
+### Integration Service
+
 ```javascript
-// Initialize SDK - token management is automatic
-const symbols = new Symbols({
-  appKey: 'your-app-key',
-  authToken: 'your-initial-token' // Optional
-})
+const integration = sdk.getService('integration')
+
+// Integration management
+await integration.integrationWhoami(apiKey, options)
+await integration.listIntegrations(options)
+await integration.createIntegration(data)
+await integration.updateIntegration(integrationId, update)
 
-// Login - tokens are automatically managed
-const loginResult = await symbols.login('user@example.com', 'password')
+// API Keys
+await integration.createIntegrationApiKey(integrationId, data)
+await integration.listIntegrationApiKeys(integrationId)
+await integration.revokeIntegrationApiKey(integrationId, keyId)
 
-// All subsequent API calls automatically use fresh tokens
-const projects = await symbols.getProjects()
-const projectData = await symbols.getProjectData('projectId123')
+// Webhooks
+await integration.createIntegrationWebhook(integrationId, data)
+await integration.listIntegrationWebhooks(integrationId)
+await integration.updateIntegrationWebhook(integrationId, webhookId, update)
+await integration.deleteIntegrationWebhook(integrationId, webhookId)
+await integration.listIntegrationWebhookDeliveries(integrationId, webhookId, options)
+await integration.replayIntegrationWebhookDelivery(integrationId, webhookId, deliveryId)
 
-// Logout - tokens are automatically cleared
-await symbols.logout()
+// GitHub Connectors
+await integration.listGitHubConnectors()
+await integration.createGitHubConnector(data)
+await integration.updateGitHubConnector(connectorId, update)
+await integration.deleteGitHubConnector(connectorId)
 ```
 
-## New Core Service Methods
+### Feature Flag Service
 
-### Project Data Management (Symstory Replacement)
 ```javascript
-// Apply changes to project
-await symbols.applyProjectChanges('projectId', [
-  ['update', ['components', 'Button'], { color: 'blue' }],
-  ['delete', ['pages', 'oldPage']]
-], { message: 'Update button color', type: 'patch' })
+const featureFlag = sdk.getService('featureFlag')
 
-// Get current project data
-const projectData = await symbols.getProjectData('projectId', {
-  branch: 'main',
-  includeHistory: true
-})
-
-// Restore to previous version
-await symbols.restoreProjectVersion('projectId', '1.2.0', {
-  message: 'Rollback to stable version'
-})
+// User-facing
+await featureFlag.getFeatureFlags(params)
+await featureFlag.getFeatureFlag(key)
 
-// Helper methods for single operations
-await symbols.updateProjectItem('projectId', ['components', 'Button'], { color: 'red' })
-await symbols.deleteProjectItem('projectId', ['pages', 'unused'])
-await symbols.setProjectValue('projectId', ['settings', 'theme'], 'dark')
+// Admin
+await featureFlag.getAdminFeatureFlags(params)
+await featureFlag.createFeatureFlag(flagData)
+await featureFlag.updateFeatureFlag(id, patch)
+await featureFlag.archiveFeatureFlag(id)
 ```
 
-### Pull Request Management
+---
+
+## Token Management
+
+The SDK includes automatic token management with persistence and refresh:
+
+- **Automatic Token Refresh** - tokens are refreshed before expiration
+- **Persistent Storage** - tokens persist across page refreshes via localStorage
+- **Secure Handling** - automatic cleanup on logout
+- **Flexible Storage** - supports localStorage, sessionStorage, or memory
+
 ```javascript
-// Create pull request
-const pr = await symbols.createPullRequest('projectId', {
-  source: 'feature/new-ui',
-  target: 'main',
-  title: 'Add new UI components',
-  description: 'Modern UI overhaul'
-})
+import { getTokenManager } from '@symbo.ls/sdk'
 
-// List pull requests
-const { pullRequests, pagination } = await symbols.listPullRequests('projectId', {
-  status: 'open',
-  page: 1,
-  limit: 10
+const tokenManager = getTokenManager({
+  storageType: 'localStorage',        // 'localStorage' | 'sessionStorage' | 'memory'
+  refreshBuffer: 60 * 1000,           // refresh 1 minute before expiry
+  apiUrl: '/api',
+  onTokenRefresh: (tokens) => { ... },
+  onTokenExpired: () => { ... },
+  onTokenError: (error) => { ... }
 })
+```
 
-// Review pull request
-await symbols.approvePullRequest('projectId', 'pr_123', 'Great work!')
+All authenticated API calls automatically use fresh tokens via the BaseService `_request()` method.
 
-// Request changes
-await symbols.requestPullRequestChanges('projectId', 'pr_123', [
-  {
-    file: 'src/Button.js',
-    line: 25,
-    comment: 'Add error handling',
-    type: 'issue'
-  }
-])
+---
+
+## Permissions
+
+### Role Permissions
 
-// Merge pull request
-await symbols.mergePullRequest('projectId', 'pr_123')
+```javascript
+// Global roles
+const ROLE_PERMISSIONS = {
+  guest: ['viewPublicProjects'],
+  user: ['viewPublicProjects', 'createProject'],
+  admin: ['viewPublicProjects', 'createProject', 'governance'],
+  superAdmin: ['viewPublicProjects', 'createProject', 'governance', 'managePlatform']
+}
 
-// Get diff
-const diff = await symbols.getPullRequestDiff('projectId', 'pr_123')
+// Project roles
+const PROJECT_ROLE_PERMISSIONS = {
+  guest: ['platformSettings', 'showContent'],
+  editor: ['platformSettings', 'showContent', 'showCode', 'editMode', 'versions'],
+  admin: [/* editor + */ 'inviteMembers', 'branchProtection', 'projectSettings'],
+  owner: [/* admin + */ 'copyPasteAllowanceSetting', 'iam']
+}
 ```
 
-### Branch Management
+### Permission Checks
+
 ```javascript
-// List branches
-const branches = await symbols.listBranches('projectId')
+auth.hasPermission('edit')
+auth.hasGlobalPermission('admin', 'governance')
+auth.checkProjectPermission('editor', 'editMode')
+auth.checkProjectFeature('pro1', 'aiCopilot')  // returns tier limit (e.g. 5)
+await auth.canPerformOperation(projectId, 'edit', { checkFeatures: true })
+await auth.withPermission(projectId, 'edit', () => { /* action */ })
+```
 
-// Create branch
-await symbols.createFeatureBranch('projectId', 'user authentication')
-// Creates: 'feature/user-authentication'
+### Tier Features
 
-// Check branch status
-const status = await symbols.getBranchStatus('projectId', 'feature/new-ui')
+| Feature | Free | Pro1 | Pro2 |
+|---------|------|------|------|
+| aiCopilot | 3 | 5 | 15 |
+| aiChatbot | 3 | 5 | 15 |
 
-// Preview merge
-const preview = await symbols.previewMerge('projectId', 'feature/new-ui', 'main')
-if (preview.data.conflicts.length === 0) {
-  // Commit merge if no conflicts
-  await symbols.commitMerge('projectId', 'feature/new-ui', {
-    message: 'Add new UI features',
-    type: 'minor'
-  })
-}
+---
 
-// Delete branch safely
-await symbols.deleteBranchSafely('projectId', 'feature/old-feature')
+## Environment Configuration
 
-// Publish version
-await symbols.publishVersion('projectId', {
-  version: '1.2.0',
-  branch: 'main'
-})
+The SDK auto-detects environment from hostname and provides:
+
+```javascript
+import { environment } from '@symbo.ls/sdk'
+
+environment.apiUrl      // HTTP API URL
+environment.socketUrl   // WebSocket URL
+environment.features    // { trackingEnabled, betaFeatures, newUserOnboarding }
 ```
 
-## Error Handling
+Supported environments: local, development, testing, upcoming, staging, preview, production.
+
+---
 
-The SDK provides comprehensive error handling for all scenarios:
+## Error Handling
 
 ```javascript
 try {
-  await symbols.mergePullRequest('projectId', 'pr_123')
+  await sdk.initialize()
+} catch (error) {
+  console.error('SDK initialization failed:', error.message)
+}
+
+try {
+  await project.mergePullRequest(projectId, prId)
 } catch (error) {
   if (error.message.includes('conflicts')) {
     // Handle merge conflicts
-    console.log('Manual conflict resolution required')
   } else if (error.message.includes('403')) {
     // Handle permission errors
-    console.log('Insufficient permissions')
-  } else {
-    // Handle other errors
-    console.error('Operation failed:', error.message)
   }
 }
 ```
 
+---
 
+## Direct Service Creation
+
+Services can be created independently without the SDK class:
+
+```javascript
+import { createAuthService, createProjectService } from '@symbo.ls/sdk'
+
+const auth = createAuthService({ context, options })
+await auth.init({ context, options })
+```
 
+Available factory functions: `createAuthService`, `createCollabService`, `createProjectService`, `createPlanService`, `createFileService`, `createPaymentService`, `createDnsService`, `createBranchService`, `createPullRequestService`, `createAdminService`, `createSubscriptionService`, `createScreenshotService`, `createTrackingService`, `createWaitlistService`, `createMetricsService`, `createIntegrationService`, `createFeatureFlagService`.