@rimori/client 1.1.10 → 1.3.0

package/README.md

@@ -5,6 +5,8 @@ The **@rimori/client** package is a comprehensive React library that enables plu
 ## Table of Contents
 
 - [Installation](#installation)
+- [Quick Start Plugin Development](#quick-start-plugin-development)
+- [Releasing Your Plugin to Rimori](#releasing-your-plugin-to-rimori)
 - [Quick Start](#quick-start)
 - [Core API - usePlugin Hook](#core-api---useplugin-hook)
 - [Database Integration](#database-integration)
@@ -25,75 +27,194 @@ npm install @rimori/client
 yarn add @rimori/client
 ```
 
-## Quick Start
+## Quick Start Plugin Development
 
-### Basic Setup
+The Rimori Client package includes powerful CLI tools to eliminate the tedious setup process and get you building your plugin fast. The initialization script handles authentication, plugin registration, environment setup, and all necessary boilerplate configuration.
 
-```typescript
-import { lazy } from "react";
-import { PluginProvider, usePlugin } from "@rimori/client";
-import { HashRouter, Route, Routes } from "react-router-dom";
+### Prerequisites
 
-// Load pages lazily for optimal performance
-const SettingsPage = lazy(() => import("./pages/settings/SettingsPage"));
-const MainPage = lazy(() => import("./pages/MainPage"));
+Before initializing your plugin, ensure you have:
 
-const App = () => (
-  <PluginProvider pluginId="rimori-plugin-id">
-    <HashRouter future={{ v7_startTransition: true, v7_relativeSplatPath: true }}>
-      <Routes>
-        <Route path="/" element={<MainPage />} />
-        <Route path="/settings" element={<SettingsPage />} />
-      </Routes>
-    </HashRouter>
-  </PluginProvider>
-);
+1. **Node.js and yarn/npm installed**
+2. **A Rimori account** - You'll need to login during initialization to receive your access token
 
-export default App;
+### Initializing a New Plugin
+
+Open Lovable and vibe code the look of your plugin. 
+
+Then connect it to your Github account.
+
+Clone the git repository: 
+
+```bash
+git clone ...
+cd my-awesome-plugin
+
+# Initialize with Rimori Client (this handles everything!)
+npx @rimori/client rimori-init
 ```
 
-### TailwindCSS Configuration
+### What the Init Script Does
 
-Add the library to your `tailwind.config.js`:
+The `rimori-init` command automates the entire plugin setup process:
 
-```javascript
-export default {
-  darkMode: ["class"],  // Required for theme detection
-  content: [
-    "./src/**/*.{js,jsx,ts,tsx}",
-    "node_modules/@rimori/client/dist/components/**/*.{js,jsx}",
-  ],
-  // ... rest of config
-}
+1. **🔐 Authentication**: Prompts for your Rimori credentials and authenticates with the platform
+2. **🚀 Plugin Registration**: Automatically registers your plugin and generates a unique plugin ID
+3. **🔑 Access Token**: Provides you with an access token for future plugin releases
+4. **📦 Package Configuration**: Updates `package.json` with plugin-specific settings
+5. **⚙️ Environment Setup**: Creates `.env` files with your credentials
+6. **📁 File Structure**: Copies all necessary boilerplate files and examples
+7. **🎨 Configuration**: Sets up Vite, Tailwind, and router configurations
+8. **📖 Documentation**: Provides example documentation and getting started guides
+
+### Upgrade Mode
+
+If you need to upgrade an existing plugin's configuration without changing the plugin ID:
+
+```bash
+yarn rimori-init --upgrade
 ```
 
-### Vite Configuration
+### Development Setup
+
+After initialization, start developing immediately:
+
+```bash
+# Start development server
+yarn dev
+
+# Your plugin will be available at:
+# http://localhost:3000 (or your chosen port)
+```
+
+Rimori client comes pre-configured with:
+- ✅ **Hot reload** for instant development feedback
+- ✅ **TypeScript support** with full type safety
+- ✅ **TailwindCSS** for modern styling
+- ✅ **React Router** for navigation
+- ✅ **Example components** and documentation
+
+## Releasing Your Plugin to Rimori
+
+Publishing your plugin to the Rimori platform is streamlined through the built-in `rimori-release` CLI tool. The release process handles database updates, file uploads, and plugin activation automatically.
+
+### Prerequisites
+
+1. **Plugin must be initialized** - Use `rimori-init` first to set up your plugin
+2. **Build your plugin** - Ensure your plugin is built and the output is in the `dist/` directory
+3. **Environment configured** - Your `.env` file should contain `RIMORI_TOKEN` (set during initialization)
+
+### Quick Release (Recommended)
+
+During plugin initialization, convenient release scripts are automatically added to your `package.json`. These scripts handle building and releasing in one command:
+
+```bash
+# Quick release commands (build + release)
+yarn release:alpha     # Build and release to alpha channel
+yarn release:beta      # Build and release to beta channel  
+yarn release:stable    # Build and release to stable channel
+```
+
+### Manual Release Process
+
+If you prefer more control or need to understand the underlying process, you can use the `rimori-release` command directly:
+
+```bash
+# Build your plugin first
+yarn build
+
+# Then release to different channels
+yarn rimori-release alpha    # For alpha testing
+yarn rimori-release beta     # For beta releases  
+yarn rimori-release stable   # For production releases
+```
+
+The plugin version is automatically read from your `package.json`, and the plugin ID is retrieved from the `r_id` field (set during initialization).
+
+### What the Release Script Does
+
+The `rimori-release` command performs a complete release workflow:
+
+1. **📋 Configuration Upload**: Sends plugin metadata and configuration to the platform
+2. **🗄️ Database Updates**: Updates plugin information and release records
+3. **📁 File Upload**: Uploads all files from your `dist/` directory to the platform
+4. **🚀 Plugin Activation**: Activates the new version on the specified release channel
+
+### Release Channels
+
+- **`alpha`**: Early development releases for internal testing
+- **`beta`**: Pre-release versions for beta testers
+- **`stable`**: Production-ready releases for all users
+
+### Automatic Configuration
+
+During plugin initialization, the following are automatically configured:
+- `RIMORI_TOKEN`: Your authentication token (stored in `.env`)
+- `r_id`: Your unique plugin ID (stored in `package.json`)
+- **Release scripts**: `yarn release:alpha`, `yarn release:beta`, `yarn release:stable`
+- **Build configuration**: TypeScript checking, Vite setup, and worker builds
+
+### Troubleshooting
+
+If you encounter release issues:
+
+1. **Missing token**: Ensure `RIMORI_TOKEN` is in your `.env` file
+2. **No plugin ID**: Verify `r_id` exists in your `package.json`
+3. **Build errors**: Run `yarn build` successfully before releasing
+4. **Authentication**: Your token may have expired - re-run `rimori-init` if needed
+
+#### Worker Process Errors
+
+If you encounter errors like:
+```
+ReferenceError: process is not defined
+```
+
+**Root Cause**: Your plugin is importing a library that tries to access `process` or `process.env` in the worker context. Web workers don't have access to Node.js globals like `process`.
+
+**Debugging Steps**:
+
+1. **Check your imports**: Look through the files used in the worker which might import libraries that might access `process.env`:
+   - React libraries (React Router, React Query, etc.)
+   - UI component libraries (Material-UI, Ant Design, etc.)
+   - Utility libraries that check for environment variables
+
+2. **Verify Rimori Client imports**: Ensure you're importing from `@rimori/client/core` and not from `@rimori/client`:
+   ```typescript
+   // ✅ Correct - import from rimori client
+   import { RimoriClient } from '@rimori/client/core';
+   
+   // ❌ Incorrect - direct imports that might access process.env directly or through their dependencies
+   import { Avatar } from '@rimori/client';
+   import { useQuery } from '@tanstack/react-query';
+   ```
+
+3. **Check your dependencies**: Look at your `package.json` for libraries that might be bundled into the worker:
+   - UI frameworks (React, Vue, etc.)
+   - State management libraries
+   - Routing libraries
+   - Any library that checks `process.env.NODE_ENV`
+
+
+**Solution**: Use only `@rimori/client/core` exports in your worker code. The Rimori client provides all necessary functionality without requiring Node.js globals.
+
+**Note**: The worker bundling order is determined by the build system and cannot be controlled. Libraries that access `process.env` will always cause this error in the worker context.
+
+
 
-Add the following to your `vite.config.ts`:
 
-```javascript
-import { defineConfig } from 'vite'
-import react from '@vitejs/plugin-react'
 
-export default defineConfig({
-  plugins: [react()],
-  base: './', // Set base path for proper asset loading
-  build: {
-    outDir: 'dist',
-    assetsDir: 'assets'
-  }
-})
 ```
 
 ## Core API - usePlugin Hook
 
-The `usePlugin()` hook is the main interface for accessing Rimori platform features:
+The `useRimori()` hook is the main interface for accessing Rimori platform features:
 
 ```typescript
-import { usePlugin } from "@rimori/client";
+import { useRimori } from "@rimori/client";
 
 const MyComponent = () => {
-  const client = usePlugin();
+  const client = useRimori();
   
   // Access all client features
   const { db, llm, event, community, plugin } = client;
@@ -105,7 +226,7 @@ const MyComponent = () => {
 ### Plugin Interface
 
 ```typescript
-const { plugin } = usePlugin();
+const { plugin } = useRimori();
 
 // Plugin information and settings
 plugin.pluginId: string                              // Current plugin ID
@@ -127,7 +248,7 @@ interface FlashcardSettings {
 }
 
 const FlashcardSettingsComponent = () => {
-  const { plugin } = usePlugin();
+  const { plugin } = useRimori();
   const [settings, setSettings] = useState<FlashcardSettings>();
 
   useEffect(() => {
@@ -196,7 +317,7 @@ const FlashcardSettingsComponent = () => {
 Access your plugin's dedicated database tables with full TypeScript support:
 
 ```typescript
-const { db } = usePlugin();
+const { db } = useRimori();
 
 // Database interface
 db.from(tableName)                    // Query builder for tables/views - supports ALL Supabase operations
@@ -214,6 +335,12 @@ The `db.from()` method provides access to the complete Supabase PostgREST API, s
 
 All operations automatically use your plugin's table prefix for security and isolation.
 
+**Column deprecation and removal (short policy)**
+
+- To remove a column, use a two-step process:
+  1. Mark the column with `deprecated: true` in your `rimori/db.config.ts` and release. The backend renames the column to `<name>_old`.
+  2. In a subsequent release, remove the column from the config. The backend drops `<name>_old`.
+
 **Example: CRUD Operations**
 
 ```typescript
@@ -226,7 +353,7 @@ interface StudySession {
 }
 
 const StudySessionManager = () => {
-  const { db } = usePlugin();
+  const { db } = useRimori();
   
   // Create a new study session
   const createSession = async (session: Omit<StudySession, 'id'>) => {
@@ -277,7 +404,7 @@ const StudySessionManager = () => {
 
 ```typescript
 const FileManager = () => {
-  const { db } = usePlugin();
+  const { db } = useRimori();
   
   const uploadFile = async (file: File) => {
     const fileName = `uploads/${Date.now()}-${file.name}`;
@@ -308,7 +435,7 @@ const FileManager = () => {
 Powerful AI/Language Model capabilities built-in:
 
 ```typescript
-const { llm } = usePlugin();
+const { llm } = useRimori();
 
 // Text generation
 llm.getText(messages: Message[], tools?: Tool[]): Promise<string>
@@ -377,7 +504,7 @@ const ChatAssistant = () => {
 
 ```typescript
 const QuizGenerator = () => {
-  const { llm } = usePlugin();
+  const { llm } = useRimori();
   
   const generateQuiz = async (topic: string) => {
     const quiz = await llm.getObject({
@@ -413,7 +540,7 @@ const QuizGenerator = () => {
 
 ```typescript
 const VoiceAssistant = () => {
-  const { llm } = usePlugin();
+  const { llm } = useRimori();
   
   const speakText = async (text: string) => {
     const audioBlob = await llm.getVoice(text, "alloy", 1, "en");
@@ -436,7 +563,7 @@ const VoiceAssistant = () => {
 Robust inter-plugin communication and platform integration:
 
 ```typescript
-const { event } = usePlugin();
+const { event } = useRimori();
 
 // Event methods
 event.emit(topic: string, data?: any, eventId?: number): void
@@ -457,7 +584,7 @@ event.emitSidebarAction(pluginId: string, actionKey: string, text?: string): voi
 
 ```typescript
 const PluginCommunicator = () => {
-  const { event } = usePlugin();
+  const { event } = useRimori();
   
   useEffect(() => {
     // Listen for messages from other plugins
@@ -507,7 +634,7 @@ const PluginCommunicator = () => {
 
 ```typescript
 const AccomplishmentTracker = () => {
-  const { event } = usePlugin();
+  const { event } = useRimori();
   
   const trackAccomplishment = () => {
     event.emitAccomplishment({
@@ -538,7 +665,7 @@ const AccomplishmentTracker = () => {
 
 ```typescript
 const SidebarIntegration = () => {
-  const { event } = usePlugin();
+  const { event } = useRimori();
   
   const openTranslator = (text: string) => {
     // Trigger translator plugin in sidebar
@@ -568,7 +695,7 @@ const SidebarIntegration = () => {
 Share and discover content created by other users:
 
 ```typescript
-const { community } = usePlugin();
+const { community } = useRimori();
 
 // Shared content methods
 community.sharedContent.get<T>(contentType: string, id: string): Promise<BasicAssignment<T>>
@@ -595,7 +722,7 @@ interface Exercise {
 }
 
 const ExerciseManager = () => {
-  const { community } = usePlugin();
+  const { community } = useRimori();
   const [exercises, setExercises] = useState<BasicAssignment<Exercise>[]>([]);
 
   // Load community exercises
@@ -913,7 +1040,7 @@ import {
 import { HashRouter, Route, Routes } from 'react-router-dom';
 
 const StudyNotesPlugin = () => {
-  const { db, llm, plugin, community } = usePlugin();
+  const { db, llm, plugin, community } = useRimori();
   const [notes, setNotes] = useState([]);
   const [isLoading, setIsLoading] = useState(true);
   const { messages, append } = useChat();
@@ -1013,5 +1140,4 @@ export default App;
 4. **Event Cleanup**: Always unsubscribe from events in useEffect cleanup
 5. **Responsive Design**: Use TailwindCSS classes for responsive layouts
 
-## License
 

package/dist/cli/scripts/init/dev-registration.d.ts

@@ -0,0 +1,35 @@
+export interface UserCredentials {
+    email: string;
+    password: string;
+}
+export interface DeveloperRegisterResponse {
+    plugin_id: string;
+    access_token: string;
+}
+/**
+ * Prompts user for email and password credentials.
+ * @returns Promise resolving to user credentials.
+ */
+export declare function askForCredentials(): Promise<UserCredentials>;
+/**
+ * Prompts user for development port with default value.
+ * @returns Promise resolving to the selected port.
+ */
+export declare function askForPort(): Promise<number>;
+/**
+ * Authenticates with Supabase using email and password.
+ * @param param
+ * @param param.email - User email address.
+ * @param param.password - User password.
+ * @returns Promise resolving to JWT access token.
+ * @throws {Error} if authentication fails.
+ */
+export declare function authenticateWithSupabase({ email, password, }: UserCredentials): Promise<string>;
+/**
+ * Registers developer and gets plugin credentials from the backend.
+ * @param jwtToken - JWT token from Supabase authentication.
+ * @param port - Development port for the plugin.
+ * @returns Promise resolving to plugin ID and access token.
+ * @throws {Error} if registration request fails.
+ */
+export declare function registerDeveloper(jwtToken: string, port: number): Promise<DeveloperRegisterResponse>;

package/dist/cli/scripts/init/dev-registration.js

@@ -0,0 +1,174 @@
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+import { createClient } from '@supabase/supabase-js';
+import path from 'path';
+import * as readline from 'readline';
+import { DEFAULT_ANON_KEY, DEFAULT_ENDPOINT } from '../../../utils/endpoint.js';
+/**
+ * Prompts user for email and password credentials.
+ * @returns Promise resolving to user credentials.
+ */
+export function askForCredentials() {
+    return __awaiter(this, void 0, void 0, function* () {
+        const rl = readline.createInterface({
+            input: process.stdin,
+            output: process.stdout,
+        });
+        return new Promise((resolve) => {
+            rl.question('Enter your email: ', (email) => {
+                rl.close();
+                // Create a new interface for password input with muted output
+                const passwordRl = readline.createInterface({
+                    input: process.stdin,
+                    output: process.stdout,
+                    terminal: false
+                });
+                process.stdout.write('Enter your password: ');
+                // Set up stdin for raw input
+                process.stdin.setRawMode(true);
+                process.stdin.resume();
+                let password = '';
+                const onData = (buffer) => {
+                    const char = buffer.toString('utf8');
+                    if (char === '\r' || char === '\n') {
+                        // Enter pressed
+                        process.stdin.setRawMode(false);
+                        process.stdin.pause();
+                        process.stdin.removeListener('data', onData);
+                        process.stdout.write('\n');
+                        passwordRl.close();
+                        resolve({ email: email.trim(), password: password.trim() });
+                    }
+                    else if (char === '\u0003') {
+                        // Ctrl+C
+                        process.stdin.setRawMode(false);
+                        process.stdin.pause();
+                        process.stdin.removeListener('data', onData);
+                        process.stdout.write('\n');
+                        process.exit(0);
+                    }
+                    else if (char === '\u007f' || char === '\b') {
+                        // Backspace
+                        if (password.length > 0) {
+                            password = password.slice(0, -1);
+                            process.stdout.write('\b \b');
+                        }
+                    }
+                    else if (char.charCodeAt(0) >= 32 && char.charCodeAt(0) <= 126) {
+                        // Printable characters
+                        password += char;
+                        process.stdout.write('*');
+                    }
+                };
+                process.stdin.on('data', onData);
+            });
+        });
+    });
+}
+/**
+ * Prompts user for development port with default value.
+ * @returns Promise resolving to the selected port.
+ */
+export function askForPort() {
+    return __awaiter(this, void 0, void 0, function* () {
+        const rl = readline.createInterface({
+            input: process.stdin,
+            output: process.stdout,
+        });
+        return new Promise((resolve) => {
+            rl.question('Enter development port (default: 3000): ', (answer) => {
+                rl.close();
+                const port = answer.trim() || '3000';
+                // Validate port is a number
+                const portNumber = parseInt(port, 10);
+                if (isNaN(portNumber) || portNumber < 1 || portNumber > 65535) {
+                    console.error('Error: Port must be a valid number between 1 and 65535');
+                    process.exit(1);
+                }
+                resolve(portNumber);
+            });
+        });
+    });
+}
+/**
+ * Authenticates with Supabase using email and password.
+ * @param param
+ * @param param.email - User email address.
+ * @param param.password - User password.
+ * @returns Promise resolving to JWT access token.
+ * @throws {Error} if authentication fails.
+ */
+export function authenticateWithSupabase(_a) {
+    return __awaiter(this, arguments, void 0, function* ({ email, password, }) {
+        var _b;
+        console.log('🔐 Authenticating with Supabase...');
+        // Initialize Supabase client (you may need to adjust the URL and key)
+        const supabaseUrl = process.env.SUPABASE_URL || DEFAULT_ENDPOINT;
+        const supabaseKey = process.env.SUPABASE_ANON_KEY || DEFAULT_ANON_KEY;
+        const supabase = createClient(supabaseUrl, supabaseKey);
+        try {
+            const { data, error } = yield supabase.auth.signInWithPassword({
+                email,
+                password,
+            });
+            if (error) {
+                throw new Error(`Authentication failed: ${error.message}`);
+            }
+            if (!((_b = data.session) === null || _b === void 0 ? void 0 : _b.access_token)) {
+                throw new Error('No access token received from authentication');
+            }
+            console.log('✅ Supabase authentication successful!');
+            return data.session.access_token;
+        }
+        catch (error) {
+            throw new Error(`Supabase authentication failed: ${error}`);
+        }
+    });
+}
+/**
+ * Registers developer and gets plugin credentials from the backend.
+ * @param jwtToken - JWT token from Supabase authentication.
+ * @param port - Development port for the plugin.
+ * @returns Promise resolving to plugin ID and access token.
+ * @throws {Error} if registration request fails.
+ */
+export function registerDeveloper(jwtToken, port) {
+    return __awaiter(this, void 0, void 0, function* () {
+        console.log('🚀 Registering developer and creating plugin...');
+        try {
+            const currentFolderName = path.basename(process.cwd());
+            const body = { port, pluginName: currentFolderName };
+            const backendUrl = process.env.RIMORI_BACKEND_URL || "https://api.rimori.se";
+            const response = yield fetch(backendUrl + '/developer/register', {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    'Authorization': `Bearer ${jwtToken}`,
+                },
+                body: JSON.stringify(body),
+            });
+            if (!response.ok) {
+                console.error(yield response.text());
+                throw new Error(`HTTP error! status: ${response.status}`);
+            }
+            const data = yield response.json();
+            if (!data.plugin_id || !data.access_token) {
+                throw new Error('Invalid response: missing pluginId or access_token');
+            }
+            console.log('✅ Plugin registration successful!');
+            console.log(`Plugin ID: ${data.plugin_id}`);
+            return data;
+        }
+        catch (error) {
+            console.error(error);
+            throw new Error(`Developer registration failed: ${error}`);
+        }
+    });
+}

package/dist/cli/scripts/init/env-setup.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Creates or updates the .env file with the plugin token.
+ * @param token - The plugin authentication token.
+ */
+export declare function setupEnvFile(token: string): void;
+/**
+ * Updates .gitignore to exclude .env files.
+ */
+export declare function updateGitignore(): void;

package/dist/cli/scripts/init/env-setup.js

@@ -0,0 +1,43 @@
+import * as fs from 'fs';
+import * as path from 'path';
+/**
+ * Creates or updates the .env file with the plugin token.
+ * @param token - The plugin authentication token.
+ */
+export function setupEnvFile(token) {
+    const envPath = path.resolve('.env');
+    if (!fs.existsSync(envPath)) {
+        const envContent = `RIMORI_TOKEN=${token}\n`;
+        fs.writeFileSync(envPath, envContent, 'utf8');
+        console.log('Created .env file with RIMORI_TOKEN');
+    }
+    else {
+        console.log('.env file already exists, skipping creation');
+    }
+}
+/**
+ * Updates .gitignore to exclude .env files.
+ */
+export function updateGitignore() {
+    const gitignorePath = path.resolve('.gitignore');
+    let gitignoreContent = '';
+    let needsUpdate = false;
+    if (fs.existsSync(gitignorePath)) {
+        gitignoreContent = fs.readFileSync(gitignorePath, 'utf8');
+        // Check if .env is already in .gitignore
+        if (!gitignoreContent.includes('.env')) {
+            needsUpdate = true;
+        }
+    }
+    else {
+        needsUpdate = true;
+    }
+    if (needsUpdate) {
+        gitignoreContent += '\n.env\npublic/web-worker.js\n';
+        fs.writeFileSync(gitignorePath, gitignoreContent, 'utf8');
+        console.log('Added .env to .gitignore');
+    }
+    else {
+        console.log('.env already in .gitignore, skipping update');
+    }
+}

package/dist/cli/scripts/init/file-operations.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Copies necessary files and creates directories for the plugin setup.
+ */
+export declare function copyPluginFiles(): void;