### Qelos CLI Quick Start Installation and Setup

Source: https://docs.qelos.io/cli

Provides essential commands for installing the Qelos CLI, setting up environment variables, and performing initial project and resource management tasks.

```bash
# Install the CLI
npm install -g @qelos/cli

# Set up a .env file for your instance
echo 'QELOS_URL=https://my-instance.qelos.app' > .env
echo 'QELOS_USERNAME=admin@company.com' >> .env
echo 'QELOS_PASSWORD=secret' >> .env

# Create a new plugin
qplay create my-plugin

# Pull components from your Qelos instance
qelos pull components ./my-components

# Pull blueprints
qelos pull blueprints ./my-blueprints

# Pull configurations
qelos pull config ./my-configs

# Pull integrations & connections
qelos pull integrations ./my-integrations
qelos pull connections ./my-connections

# Generate IDE rules for better AI assistance
qelos generate rules all

# Preview what will be pushed
qelos get staged .
qelos get committed .

# Make changes locally

# Push changes back to Qelos
qelos push components ./my-components
qelos push blueprints ./my-blueprints
qelos push config ./my-configs
qelos push integrations ./my-integrations
qelos push connections ./my-connections

# Push with hard flag to remove remote resources that don't exist locally
qelos push components ./my-components --hard
qelos push all ./my-project --hard

# Push to a different environment using --env
qelos --env production push components ./my-components

# Interact with AI agents
qelos agent code-wizard --message "Hello, how can you help me?"
echo "What's the weather?" | qelos agent weather-agent --stream
qelos agent assistant --log conversation.json --export response.md

# Save agent preferences for reuse
qelos agent code-wizard --stream --log chat.json --save
qelos agent code-wizard -m "Hello"  # uses saved defaults
```

--------------------------------

### Complete Configuration Management Example (Admin)

Source: https://docs.qelos.io/sdk/managing_configurations

A comprehensive example demonstrating initialization, authentication, and full lifecycle management (get list, create, get specific, update, remove) of configurations using the administrator SDK.

```typescript
import QelosAdminSDK from '@qelos/sdk/administrator';

// Initialize the admin SDK
const sdkAdmin = new QelosAdminSDK({
  appUrl: 'https://your-qelos-app.com',
  fetch: globalThis.fetch
});

// Authenticate as admin
await sdkAdmin.authentication.oAuthSignin({
  username: 'admin@example.com',
  password: 'password'
});

// Get all configurations
const configurations = await sdkAdmin.manageConfigurations.getList();
console.log(`Found ${configurations.length} configurations`);

// Create a new configuration
await sdkAdmin.manageConfigurations.create({
  key: 'email-settings',
  public: false,
  description: 'Email service configuration',
  metadata: {
    smtpHost: 'smtp.example.com',
    smtpPort: 587,
    fromEmail: 'noreply@example.com'
  }
});

// Get specific configuration
const emailConfig = await sdkAdmin.manageConfigurations.getConfiguration('email-settings');
console.log('Email config:', emailConfig.metadata);

// Update configuration
await sdkAdmin.manageConfigurations.update('email-settings', {
  metadata: {
    smtpHost: 'smtp.newprovider.com',
    smtpPort: 465,
    fromEmail: 'noreply@example.com'
  }
});

// Remove configuration
await sdkAdmin.manageConfigurations.remove('email-settings');
console.log('Configuration removed');
```

--------------------------------

### Complete SDK Setup Example

Source: https://docs.qelos.io/sdk/core_functionality

Demonstrates initializing the SDK, setting custom headers, authenticating a user, and making an initial API call.

```typescript
import QelosSDK from '@qelos/sdk';

// Initialize the SDK
const sdk = new QelosSDK({
  appUrl: 'https://your-qelos-app.com',
  fetch: globalThis.fetch,
  forceRefresh: true,
});

// Add custom headers for tracking
sdk.setCustomHeader('X-Client-Version', '1.0.0');
sdk.setCustomHeader('X-Client-Platform', 'web');

// Authenticate the user
await sdk.authentication.oAuthSignin({
  username: 'user@example.com',
  password: 'password'
});

// Now you can use any of the SDK modules
const workspaces = await sdk.workspaces.getList();
const userProfile = await sdk.authentication.getLoggedInUser();
```

--------------------------------

### Complete Plugin Management Example

Source: https://docs.qelos.io/sdk/managing_plugins

A comprehensive example demonstrating the initialization of the Qelos Admin SDK, authentication, and the full lifecycle of plugin management: getting, creating, updating, retrieving, and removing plugins.

```typescript
import QelosAdminSDK from '@qelos/sdk/administrator';

// Initialize the admin SDK
const sdkAdmin = new QelosAdminSDK({
  appUrl: 'https://your-qelos-app.com',
  fetch: globalThis.fetch
});

// Authenticate as admin
await sdkAdmin.authentication.oAuthSignin({
  username: 'admin@example.com',
  password: 'password'
});

// Get all plugins
const plugins = await sdkAdmin.managePlugins.getList();
console.log(`Found ${plugins.length} plugins`);

// Create a new plugin
const newPlugin = await sdkAdmin.managePlugins.create({
  name: 'Analytics Plugin',
  appUrl: 'https://analytics.example.com',
  description: 'Provides analytics functionality',
  version: '1.0.0'
});

console.log(`Created plugin with ID: ${newPlugin._id}`);

// Update the plugin
const updatedPlugin = await sdkAdmin.managePlugins.update(newPlugin._id, {
  version: '1.0.1',
  description: 'Provides enhanced analytics functionality'
});

// Get specific plugin
const plugin = await sdkAdmin.managePlugins.getById(newPlugin._id);
console.log(`Plugin name: ${plugin.name}`);

// Remove the plugin
await sdkAdmin.managePlugins.remove(newPlugin._id);
console.log('Plugin removed');
```

--------------------------------

### Basic Plugin Development Workflow

Source: https://docs.qelos.io/cli/create

This example outlines a common workflow: creating a plugin, navigating into its directory, and starting the development server.

```bash
qplay create my-plugin
cd my-plugin
npm run dev
```

--------------------------------

### Multi-Environment Setup Example

Source: https://docs.qelos.io/cli/pull

Demonstrates pulling components from different Qelos environments (production and staging) by setting the QELOS_URL environment variable, and then comparing the differences.

```bash
# Pull from production
export QELOS_URL=https://production.qelos.com
qelos pull components ./prod-components

# Pull from staging
export QELOS_URL=https://staging.qelos.com
qelos pull components ./staging-components

# Compare differences
diff -r prod-components staging-components
```

--------------------------------

### Create Plugin with Custom Name and Install Dependencies

Source: https://docs.qelos.io/cli/create

This example shows creating a plugin with a specific name ('customer-dashboard') and then manually installing its dependencies.

```bash
qplay create customer-dashboard
cd customer-dashboard
npm install
```

--------------------------------

### Complete Blocks Module Usage Example

Source: https://docs.qelos.io/sdk/managing_blocks

Demonstrates initializing the SDK, authenticating, getting all blocks, creating a new block, and updating an existing block.

```typescript
import { QelosSDK } from '@qelos/sdk';

// Initialize the SDK
const sdk = new QelosSDK({
  appUrl: 'https://your-qelos-app.com',
});

// Authenticate the user
await sdk.authentication.oAuthSignin({
  username: 'user@example.com',
  password: 'password'
});

// Get all blocks
const blocks = await sdk.blocks.getList();
console.log(`Found ${blocks.length} blocks`);

// Create a new block
const headerBlock = await sdk.blocks.create({
  name: "Header",
  description: "Main site header with navigation",
  content: `
    <header>
      <nav>
        <ul>
          <li><a href="/">Home</a></li>
          <li><a href="/about">About</a></li>
          <li><a href="/contact">Contact</a></li>
        </ul>
      </nav>
    </header>
  `,
  contentType: "html"
});

console.log(`Created new block with ID: ${headerBlock._id}`);

// Update the block
const updatedBlock = await sdk.blocks.update(headerBlock._id, {
  content: `
    <header>
      <nav>
        <ul>
          <li><a href="/">Home</a></li>
          <li><a href="/about">About</a></li>
          <li><a href="/contact">Contact</a></li>
          <li><a href="/blog">Blog</a></li>
        </ul>
      </nav>
    </header>
  `
});

console.log(`Updated block with new content`);
```

--------------------------------

### Basic Setup for Vanilla JavaScript

Source: https://docs.qelos.io/web-sdk/installation

Integrate the Qelos Web SDK into a vanilla JavaScript application. This example shows how to authorize and display user information and session code.

```html
<!DOCTYPE html>
<html>
<head>
    <title>My Micro-Frontend</title>
</head>
<body>
    <div id="app">
        <h1>Loading...</h1>
    </div>

    <script type="module">
        import { authorize, code } from '@qelos/web-sdk';

        // Initialize authentication
        const userData = await authorize();
        
        document.getElementById('app').innerHTML = `
            <h1>Welcome, ${userData.user.fullName}!</h1>
            <p>Session Code: ${code}</p>
        `;
    </script>
</body>
</html>
```

--------------------------------

### Basic Setup for React Application

Source: https://docs.qelos.io/web-sdk/installation

Integrate the Qelos Web SDK into a React application. This example demonstrates authorization and displaying user data within a component.

```tsx
// App.tsx
import { useEffect, useState } from 'react';
import { authorize, code } from '@qelos/web-sdk';

function App() {
  const [userData, setUserData] = useState(null);
  const [loading, setLoading] = useState(true);

  useEffect(() => {
    authorize()
      .then(data => {
        setUserData(data);
        setLoading(false);
      })
      .catch(err => {
        console.error('Authorization failed:', err);
        setLoading(false);
      });
  }, []);

  if (loading) {
    return <div>Loading...</div>;
  }

  return (
    <div>
      <h1>Welcome, {userData?.user?.fullName}!</h1>
      <p>Session Code: {code}</p>
    </div>
  );
}

export default App;
```

--------------------------------

### Install Dependencies

Source: https://docs.qelos.io/cli/create

Install the necessary project dependencies using npm. This step is crucial before starting development.

```bash
npm install
```

--------------------------------

### Complete Example

Source: https://docs.qelos.io/sdk/execute_lambdas

A complete example demonstrating SDK initialization and triggering a webhook with POST data.

```APIDOC
## Complete Example

```typescript
import { QelosSDK } from '@qelos/sdk';

const sdk = new QelosSDK({
  apiKey: process.env.QELOS_API_KEY,
  baseUrl: 'https://api.qelos.io'
});

// Trigger a webhook with POST data
const response = await sdk.lambdas.post('webhook-integration-id', {
  body: {
    event: 'user.created',
    userId: '12345',
    email: 'user@example.com'
  }
});

console.log('Webhook response:', response);
```
```

--------------------------------

### Example Configuration JSON

Source: https://docs.qelos.io/cli/push

An example of an application settings configuration file.

```json
{
  "key": "app-settings",
  "public": true,
  "kind": "settings",
  "description": "Application settings",
  "metadata": {
    "theme": "dark",
    "language": "en",
    "notifications": {
      "email": true,
      "push": false
    },
    "features": {
      "darkMode": true,
      "betaFeatures": false
    }
  }
}
```

--------------------------------

### Basic Setup for Angular Application

Source: https://docs.qelos.io/web-sdk/installation

Integrate the Qelos Web SDK into an Angular application. This example demonstrates authorization and displaying user data within an Angular component.

```typescript
// app.component.ts
import { Component, OnInit } from '@angular/core';
import { authorize, code } from '@qelos/web-sdk';

@Component({
  selector: 'app-root',
  template: `
    <div *ngIf="loading">Loading...</div>
    <div *ngIf="!loading">
      <h1>Welcome, {{ userData?.user?.fullName }}!</h1>
      <p>Session Code: {{ sessionCode }}</p>
    </div>
  `
})
export class AppComponent implements OnInit {
  userData: any = null;
  loading = true;
  sessionCode = code;

  async ngOnInit() {
    try {
      this.userData = await authorize();
    } catch (err) {
      console.error('Authorization failed:', err);
    } finally {
      this.loading = false;
    }
  }
}
```

--------------------------------

### Create a Basic Plugin with Plugin Play

Source: https://docs.qelos.io/plugin-play

A minimal example demonstrating how to configure, add an endpoint, register an event hook, and start a Plugin Play application.

```typescript
import { start, configure, addEndpoint, registerToHook } from '@qelos/plugin-play';

// Configure your plugin
configure({
  name: 'My Plugin',
  version: '1.0.0',
  description: 'A sample plugin',
  manifestUrl: '/manifest.json',
  proxyPath: '/api/proxy'
}, {
  qelosUrl: process.env.QELOS_URL,
  qelosUsername: process.env.QELOS_USERNAME,
  qelosPassword: process.env.QELOS_PASSWORD
});

// Add an endpoint
addEndpoint('/api/hello', {
  method: 'GET',
  handler: async (request, reply) => {
    return { message: 'Hello from my plugin!' };
  }
});

// Subscribe to events
registerToHook({
  eventName: 'user.created'
}, async (request, reply) => {
  const { user } = request.body;
  console.log('New user created:', user);
  return { received: true };
});

// Start the server
start();
```

--------------------------------

### Example .env file with Username/Password

Source: https://docs.qelos.io/cli

An example of an `.env` file configured for username and password authentication.

```bash
QELOS_URL=https://my-instance.qelos.app
QELOS_USERNAME=admin@company.com
QELOS_PASSWORD=secret
```

--------------------------------

### Build and Start Production Application

Source: https://docs.qelos.io/plugin-play/installation

Build your application for production and start the server using npm scripts.

```bash
npm run build
npm start
```

--------------------------------

### Example: Create 'my-awesome-plugin'

Source: https://docs.qelos.io/cli/create

This example demonstrates creating a new plugin named 'my-awesome-plugin'. The command generates a standard project structure.

```bash
# Create a new plugin called "my-awesome-plugin"
qplay create my-awesome-plugin
```

--------------------------------

### Run Qelos Locally

Source: https://docs.qelos.io/

Clone the Qelos repository, install dependencies, build the packages, and start the development environment. Populate the database in a separate terminal.

```bash
git clone https://github.com/qelos-io/qelos.git
cd qelos
pnpm install      # install dependencies
pnpm build        # build packages
pnpm dev          # start the dev environment (includes MongoDB)
pnpm populate-db  # seed initial data (in a new terminal)
```

--------------------------------

### Install Qelos CLI and Integrators

Source: https://docs.qelos.io/

Install the Qelos CLI globally and then install the specific integrator package for your framework. Finally, install the Qelos SDK.

```bash
# 1. Install the CLI
npm install -g @qelos/cli

# 2. Initialize in your project (detects framework, scaffolds config)
qelos init

# 3. Install the integrator for your framework
npm install @qelos/integrator-next   # or express, nuxt, fastify, nest

# 4. Install the SDK
npm install @qelos/sdk
```

--------------------------------

### Example .env file with API Token

Source: https://docs.qelos.io/cli

An example of an `.env` file configured for API token authentication.

```bash
QELOS_URL=https://my-instance.qelos.app
QELOS_API_TOKEN=ql_your_api_token_here
```

--------------------------------

### Install Qelos Web SDK with yarn

Source: https://docs.qelos.io/web-sdk/installation

Install the Web SDK using yarn.

```bash
yarn add @qelos/web-sdk
```

--------------------------------

### Install Qelos Web SDK with npm

Source: https://docs.qelos.io/web-sdk/installation

Install the Web SDK using npm.

```bash
npm install @qelos/web-sdk
```

--------------------------------

### Install Qelos Web SDK

Source: https://docs.qelos.io/web-sdk

Install the Web SDK using npm, yarn, or pnpm.

```bash
npm install @qelos/web-sdk
# or
yarn add @qelos/web-sdk
# or
pnpm add @qelos/web-sdk
```

--------------------------------

### Navigate and Install Plugin Dependencies

Source: https://docs.qelos.io/plugins/create

After creating the plugin, navigate to its directory and install the necessary npm packages.

```shell
cd my-new-plugin
npm install
```

--------------------------------

### Complete Invites Management Example

Source: https://docs.qelos.io/sdk/managing_invites

An example demonstrating SDK initialization, authentication, fetching invites, and processing them by accepting or declining.

```typescript
import { QelosSDK } from '@qelos/sdk';

// Initialize the SDK
const sdk = new QelosSDK({
  appUrl: 'https://your-qelos-app.com',
});

// Authenticate the user
await sdk.authentication.oAuthSignin({
  username: 'user@example.com',
  password: 'password'
});

// Get all invites for the current user
const invites = await sdk.invites.getList();

// Process each invite
invites.forEach(async (invite) => {
  const workspaceId = invite.workspace._id;
  
  // Accept the invitation
  // You could implement your own logic to determine whether to accept or decline
  await sdk.invites.acceptWorkspace(workspaceId);
  
  // Or decline the invitation
  // await sdk.invites.declineWorkspace(workspaceId);
});
```

--------------------------------

### Install Qelos Web SDK with pnpm

Source: https://docs.qelos.io/web-sdk/installation

Install the Web SDK using pnpm.

```bash
pnpm add @qelos/web-sdk
```

--------------------------------

### Install @qelos/integrator-next

Source: https://docs.qelos.io/integrators/next

Install the Next.js integrator and SDK. Ensure Next.js (>=13.4) and React are installed as peer dependencies.

```bash
npm install @qelos/integrator-next @qelos/sdk
```

--------------------------------

### Basic Setup for Vue 3 Application

Source: https://docs.qelos.io/web-sdk/installation

Integrate the Qelos Web SDK into a Vue 3 application. This example shows how to handle authorization and display user information using Vue's Composition API.

```vue
<!-- App.vue -->
<template>
  <div v-if="loading">Loading...</div>
  <div v-else>
    <h1>Welcome, {{ userData?.user?.fullName }}!</h1>
    <p>Session Code: {{ sessionCode }}</p>
  </div>
</template>

<script setup>
import { ref, onMounted } from 'vue';
import { authorize, code } from '@qelos/web-sdk';

const userData = ref(null);
const loading = ref(true);
const sessionCode = ref(code);

onMounted(async () => {
  try {
    userData.value = await authorize();
  } catch (err) {
    console.error('Authorization failed:', err);
  } finally {
    loading.value = false;
  }
});
</script>
```

--------------------------------

### Public SDK: List and Get Plans

Source: https://docs.qelos.io/payments/plans

Examples of using the public SDK to fetch available pricing plans. Use `getPlans()` to list all active plans and `getPlan(planId)` to retrieve a specific one.

```typescript
// List available plans
const plans = await sdk.payments.getPlans();

// Get specific plan
const plan = await sdk.payments.getPlan('plan-id');
```

--------------------------------

### Install @qelos/integrator-express

Source: https://docs.qelos.io/integrators/express

Install the Express integrator and the Qelos SDK. Express is a peer dependency and must be installed separately.

```bash
npm install @qelos/integrator-express @qelos/sdk
# express is a peer dependency
npm install express
```

--------------------------------

### Verify CLI Installation

Source: https://docs.qelos.io/cli

After installation, verify that the `qelos` and `qplay` commands are available and check their versions.

```bash
qelos --version
qplay --version
```

--------------------------------

### Install Fastify Integrator and SDK

Source: https://docs.qelos.io/getting-started/integrators

Install the `@qelos/integrator-fastify` package along with the `@qelos/sdk` for Fastify applications.

```bash
npm install @qelos/integrator-fastify @qelos/sdk

```

--------------------------------

### Install Next.js Integrator and SDK

Source: https://docs.qelos.io/getting-started/integrators

Install the `@qelos/integrator-next` package along with the `@qelos/sdk` for Next.js applications.

```bash
npm install @qelos/integrator-next @qelos/sdk

```

--------------------------------

### Install Plugin Play

Source: https://docs.qelos.io/plugin-play

Install Plugin Play using npm, yarn, or pnpm.

```bash
npm install @qelos/plugin-play
# or
yarn add @qelos/plugin-play
# or
pnpm add @qelos/plugin-play
```

--------------------------------

### Basic Quick Table Example

Source: https://docs.qelos.io/pre-designed-frontends/components/quick-table

A simple example of using the `<quick-table>` component with inline column definitions for name, email, and role.

```html
<quick-table :data="users" :columns="[
  { prop: 'name', label: 'Name' },
  { prop: 'email', label: 'Email' },
  { prop: 'role', label: 'Role' }
]"></quick-table>
```

--------------------------------

### Qelos config file example

Source: https://docs.qelos.io/cli/interfaces

Example JSON configuration file for Qelos, specifying interface generation settings.

```json
{
  "interfaces": {
    "lang": "ts",
    "out": "./src/generated",
    "path": "./blueprints"
  }
}
```

--------------------------------

### End-to-End Example: Setting Up and Using Global Environments

Source: https://docs.qelos.io/cli/global

This example demonstrates the complete workflow of registering multiple global environments, verifying the registry, and then using these environments from a different directory to run Qelos commands.

```bash
# Step 1: go to your main project and register it
cd ~/projects/my-qelos-app
qelos global set
# → Global env "default" set to: /Users/david/projects/my-qelos-app

# Step 2: register a staging project under a different name
cd ~/projects/my-qelos-staging
qelos global set staging
# → Global env "staging" set to: /Users/david/projects/my-qelos-staging

# Step 3: verify the registry
qelos global list
# → default: /Users/david/projects/my-qelos-app
# → staging: /Users/david/projects/my-qelos-staging

# Step 4: from ANY directory, run an agent using the default global
cd /tmp
qelos agent code-wizard --global -m "Hello from /tmp!"
# Loads .env from /Users/david/projects/my-qelos-app
# Resolves integration name from its integrations/ folder

# Step 5: use the staging environment
qelos agent code-wizard --global staging -m "Test on staging"

# Step 6: dump blueprints using the staging env's config & credentials
qelos dump blueprints --global staging

# Step 7: clean up when staging is gone
qelos global delete staging
```

--------------------------------

### Basic Confirmation Example

Source: https://docs.qelos.io/pre-designed-frontends/components/confirm-message

Example demonstrating a basic confirmation dialog for a delete action, including script setup and template.

```APIDOC
## Basic Confirmation Example

### Description
This example shows how to implement a basic confirmation dialog for a destructive action like deleting an item. It uses `ref` for dialog visibility and a handler function for the confirmation logic.

### Script Setup
```javascript
import { ref } from 'vue';

const showDialog = ref(false);

function deleteItem() {
  showDialog.value = true;
}

function handleConfirm() {
  // Perform delete action
  console.log('Item deleted');
}
```

### Template
```html
<template>
  <el-button @click="deleteItem" type="danger">
    Delete Item
  </el-button>
  
  <confirm-message 
    v-model="showDialog"
    message="This action cannot be undone. Are you sure?"
    type="danger"
    @confirm="handleConfirm"
  />
</template>
```
```

--------------------------------

### Basic Plugin Configuration and Start

Source: https://docs.qelos.io/plugin-play/installation

Sets up the main plugin file with essential configuration like name, version, and Qelos connection details, then starts the Plugin Play server.

```typescript
import { start, configure } from '@qelos/plugin-play';

// Configure the plugin
configure({
  name: 'My Plugin',
  version: '1.0.0',
  description: 'My first Qelos plugin',
  manifestUrl: '/manifest.json',
  proxyPath: '/api/proxy'
}, {
  qelosUrl: process.env.QELOS_URL,
  qelosUsername: process.env.QELOS_USERNAME,
  qelosPassword: process.env.QELOS_PASSWORD,
  port: 3000
});

// Start the server
start().then(() => {
  console.log('Plugin is running!');
});
```

--------------------------------

### Webpack Configuration Example

Source: https://docs.qelos.io/web-sdk/installation

Example Webpack configuration file. Ensure proper module resolution for the Qelos Web SDK.

```javascript
// webpack.config.js
module.exports = {
  resolve: {
    extensions: ['.ts', '.js'],
  },
  // Your other configuration
};
```

--------------------------------

### Agent Helper SDK Usage

Source: https://docs.qelos.io/api/gateway-endpoint-reference

Examples of using the SDK for agent-related operations like listing, getting, and chatting with agents.

```typescript
await sdk.ai.agents.list({ active: true });
```

```typescript
await sdk.ai.agents.get('AGENT_ID');
```

```typescript
await sdk.ai.agents.chat('AGENT_ID', 'Hello');
```

--------------------------------

### Public SDK: Get and Cancel Subscription

Source: https://docs.qelos.io/payments/subscriptions

Examples of using the public SDK to retrieve the current subscription and to cancel an existing one.

```typescript
// Get current subscription
const subscription = await sdk.payments.getMySubscription();

// Cancel subscription
await sdk.payments.cancelSubscription('subscription-id');
```

--------------------------------

### Scripting with JSON Output

Source: https://docs.qelos.io/cli/get

A bash script example demonstrating how to utilize the JSON output from the 'qelos get' command for automated tasks.

```bash
#!/bin/bash

```

--------------------------------

### Environment Variables Example

Source: https://docs.qelos.io/web-sdk/installation

Example `.env` file for configuring your micro-frontend with environment variables, such as API URLs and application names.

```bash
# .env
VITE_API_URL=https://your-backend.com
VITE_APP_NAME=My Micro-Frontend
```

--------------------------------

### Get Roles using cURL

Source: https://docs.qelos.io/api/gateway-endpoint-reference

Example cURL command to fetch the catalog of role names. The caller must satisfy privileged checks.

```bash
curl -sS "$BASE/api/roles" \
  -H "Authorization: Bearer ACCESS_TOKEN"
```

--------------------------------

### Full Migration Workflow Example

Source: https://docs.qelos.io/cli/restore

This example demonstrates a typical migration workflow. First, dump data from the source environment, then set the Qelos URL for the target environment and restore the blueprints.

```bash
# On source environment
export QELOS_URL=https://prod.example.com
qelos dump users
qelos dump workspaces
qelos dump blueprints

# On target environment
export QELOS_URL=https://staging.example.com
qelos restore blueprints
```

--------------------------------

### Basic Remove Button Example

Source: https://docs.qelos.io/pre-designed-frontends/components/remove-button

Demonstrates the basic integration of the remove button with a script setup for handling the deletion logic and loading state.

```html
<script setup>
const isRemoving = ref(false)

async function handleRemove() {
  isRemoving.value = true
  try {
    await deleteItem(itemId)
    ElMessage.success('Item removed successfully')
  } finally {
    isRemoving.value = false
  }
}
</script>

<template>
  <remove-button 
    @remove="handleRemove"
    :loading="isRemoving"
  />
</template>
```

--------------------------------

### Qelos SDK: User and Workspace Operations

Source: https://docs.qelos.io/getting-started/quick-reference

Examples of using the Qelos SDK to get the current user, access workspace information, and check permissions.

```typescript
// Current user
const user = await sdk.auth.getCurrentUser()

// Workspace
const workspace = await sdk.workspaces.getCurrent()

// Permissions
const canEdit = await sdk.permissions.check('product:edit')
```

--------------------------------

### Create Plugins from Templates

Source: https://docs.qelos.io/getting-started/design-products-faster

Quickly start new projects or plugins by using pre-defined templates with the Qelos CLI. The 'saas-starter' template provides a solid foundation for SaaS applications.

```bash
# Start from proven templates
qelos create plugin --template=saas-starter
```

--------------------------------

### Complete Blueprint Management Example

Source: https://docs.qelos.io/sdk/blueprints_operations

This comprehensive example demonstrates the full lifecycle of managing blueprints, including initialization, authentication, creation, retrieval, update, and deletion. It requires the QelosAdminSDK and proper authentication credentials.

```typescript
import QelosAdminSDK from '@qelos/sdk/administrator';

// Initialize the admin SDK
const sdkAdmin = new QelosAdminSDK({
  appUrl: 'https://your-qelos-app.com',
  fetch: globalThis.fetch
});

// Authenticate as admin
await sdkAdmin.authentication.oAuthSignin({
  username: 'admin@example.com',
  password: 'password'
});

// Get all blueprints
const blueprints = await sdkAdmin.manageBlueprints.getList();
console.log(`Found ${blueprints.length} blueprints`);

// Create a new blueprint
const newBlueprint = await sdkAdmin.manageBlueprints.create({
  key: 'article',
  name: 'Article',
  description: 'Blog article blueprint',
  fields: [
    { key: 'title', type: 'string', required: true },
    { key: 'content', type: 'text', required: true },
    { key: 'author', type: 'string', required: true },
    { key: 'publishedAt', type: 'date', required: false }
  ]
});

console.log(`Created blueprint: ${newBlueprint.key}`);

// Update the blueprint
await sdkAdmin.manageBlueprints.update('article', {
  description: 'Enhanced blog article blueprint with tags',
  fields: [
    { key: 'title', type: 'string', required: true },
    { key: 'content', type: 'text', required: true },
    { key: 'author', type: 'string', required: true },
    { key: 'publishedAt', type: 'date', required: false },
    { key: 'tags', type: 'array', required: false }
  ]
});

// Get specific blueprint
const blueprint = await sdkAdmin.manageBlueprints.getBlueprint('article');
console.log(`Blueprint: ${blueprint.name}`);

// Remove the blueprint
await sdkAdmin.manageBlueprints.remove('article');
console.log('Blueprint removed');
```

--------------------------------

### Example Plugin-Micro-Frontend Dependency

Source: https://docs.qelos.io/cli/get

Illustrates a JSON structure where a plugin references a micro-frontend via a $ref. This helps in understanding how the 'get' command detects and reports such dependencies.

```json
{
  "name": "my-plugin",
  "routes": [
    {
      "path": "/my-route",
      "$ref": "./micro-frontends/my-html.html"
    }
  ]
}
```

--------------------------------

### Qelos CLI: Project Setup Commands

Source: https://docs.qelos.io/getting-started/quick-reference

Commands for creating new plugins and blueprints, generating CRUD interfaces, and managing remote resources.

```bash
# Create new plugin
qelos create plugin my-plugin

# Create new blueprint
qelos create blueprint Product

# Generate CRUD with UI
qelos generate crud Product --with-listing --with-forms

# Pull remote resources
qelos pull

# Push changes
qelos push
```

--------------------------------

### Dispatch a Custom Plugin Event

Source: https://docs.qelos.io/plugins/hooks

Dispatch custom events from your plugin using the Qelos SDK. This example shows how to get the SDK and dispatch an event with custom metadata.

```typescript
import { getSdk } from '@qelos/plugin-play'

getSdk().events.dispatch({
  user: '111',
  source: 'my-plugin',
  kind: 'my-type',
  eventName: 'thing-changed',
  metadata: {
    customData: 1
  }
})
```

--------------------------------

### Initialize SDK and Authenticate

Source: https://docs.qelos.io/ai/agents

Demonstrates how to initialize the Qelos SDK and authenticate a user using OAuth.

```APIDOC
## Initialize SDK and Authenticate

### Description
Initialize the Qelos SDK with your application's URL and authenticate using OAuth credentials.

### Method
```typescript
const sdk = new QelosSDK({ appUrl: 'https://your-qelos-instance.com', fetch: globalThis.fetch });
await sdk.authentication.oAuthSignin({ username, password });
```
```

--------------------------------

### Get Categories with Tenant-Scoped Articles

Source: https://docs.qelos.io/sdk/blueprints_operations

Retrieve categories and populate their associated articles, scoped to the tenant. This example shows how to apply limits, sorting, and field filtering for populated articles.

```typescript
// Get categories with articles (all-scoped, with limit and sorting)
const categories = await sdk.blueprints.entitiesOf('category').getList({
  $outerPopulate: {
    articles: {
      target: 'blog-posts',
      scope: 'tenant',
      limit: 10,
      sort: '-publishedAt',
      fields: ['title', 'publishedAt', 'author']
    }
  }
});
```

--------------------------------

### Get Products with Workspace-Scoped Orders

Source: https://docs.qelos.io/sdk/blueprints_operations

Retrieve products and populate their associated orders, scoped to the current workspace. This example demonstrates limiting the number of orders and specifying fields to retrieve.

```typescript
// Get products with their orders (workspace-scoped)
const productsWithOrders = await productEntities.getList({
  $limit: 20,
  $outerPopulate: {
    orders: {
      target: 'orders',
      scope: 'workspace',
      limit: 5,
      sort: '-created',
      fields: 'amount,status,created'
    }
  }
});
```

--------------------------------

### View Create Command Help

Source: https://docs.qelos.io/cli/create

To see all available options and flags for the `create` command, use the `--help` flag.

```bash
qplay create --help
```

--------------------------------

### Basic Form Example

Source: https://docs.qelos.io/pre-designed-frontends/components/general-form

A basic Vue 3 setup using the general-form component with predefined fields for name, email, and role. Includes data binding and a submit handler.

```html
<script setup>
const formData = ref({
  name: '',
  email: '',
  role: 'user'
})

const formSchema = {
  fields: [
    {
      name: 'name',
      label: 'Full Name',
      type: 'text',
      required: true,
      placeholder: 'Enter your full name'
    },
    {
      name: 'email',
      label: 'Email Address',
      type: 'email',
      required: true,
      validation: [{ type: 'email', message: 'Invalid email format' }]
    },
    {
      name: 'role',
      label: 'Role',
      type: 'select',
      options: [
        { label: 'User', value: 'user' },
        { label: 'Admin', value: 'admin' }
      ]
    }
  ]
}
</script>

<template>
  <general-form 
    :schema="formSchema"
    v-model="formData"
    @submit="saveUser"
  />
</template>
```

--------------------------------

### Complete Admin Workspace Management Example

Source: https://docs.qelos.io/sdk/managing_workspaces

This example demonstrates initializing the admin SDK, authenticating, retrieving all workspaces, filtering workspaces by a user ID, and setting/getting encrypted data for a workspace. Ensure you have the correct app URL and admin credentials.

```typescript
import QelosAdminSDK from '@qelos/sdk/administrator';

// Initialize the admin SDK
const sdkAdmin = new QelosAdminSDK({
  appUrl: 'https://your-qelos-app.com',
  fetch: globalThis.fetch
});

// Authenticate as admin
await sdkAdmin.authentication.oAuthSignin({
  username: 'admin@example.com',
  password: 'password'
});

// Get all workspaces (admin only)
const allWorkspaces = await sdkAdmin.adminWorkspaces.getList();
console.log(`Found ${allWorkspaces.length} workspaces in the tenant`);

// Get workspaces filtered by member user ID
const userWorkspaces = await sdkAdmin.adminWorkspaces.getList({ 'members.user': 'userId' });
console.log(`User belongs to ${userWorkspaces.length} workspaces`);

// Store encrypted data for a workspace
await sdkAdmin.adminWorkspaces.setEncryptedData('workspaceId', 'api-credentials', {
  stripeApiKey: 'sk_test_xxx',
  stripeWebhookSecret: 'whsec_xxx'
});

// Retrieve encrypted data
const credentials = await sdkAdmin.adminWorkspaces.getEncryptedData('workspaceId', 'api-credentials');
console.log('Retrieved encrypted credentials');

```

--------------------------------

### Integrate SDK in User Creation Event Handler

Source: https://docs.qelos.io/plugin-play/events

Access the Qelos SDK within an event handler to interact with Qelos APIs. This example shows how to get the SDK for a specific tenant and create a block upon user creation.

```typescript
import { registerToHook, getSdkForTenant } from '@qelos/plugin-play';

registerToHook({
  eventName: 'user.created'
}, async (request, reply) => {
  const { user, tenant } = request.body;
  
  // Get SDK for this tenant
  const sdk = await getSdkForTenant(tenant);
  
  // Create a welcome block
  await sdk.blocks.create({
    name: `Welcome ${user.fullName}`,
    content: `Welcome to our platform, ${user.firstName}!`,
    contentType: 'html'
  });
  
  return { received: true };
});
```

--------------------------------

### Build an AI Chat Application with Qelos SDK

Source: https://docs.qelos.io/sdk/ai_operations

This example demonstrates how to create a full-featured AI chat application. It includes authentication, starting new conversations, sending messages, handling streaming responses, retrieving conversation history, and listing previous chats. Ensure you replace placeholder values with your actual application URL and integration ID.

```typescript
import QelosSDK from '@qelos/sdk';

class AIChatApp {
  private sdk: QelosSDK;
  private currentThread: string | null = null;
  private integrationId: string;

  constructor(appUrl: string, integrationId: string) {
    this.sdk = new QelosSDK({
      appUrl,
      fetch: globalThis.fetch,
      forceRefresh: true
    });
    this.integrationId = integrationId;
  }

  async authenticate(username: string, password: string) {
    await this.sdk.authentication.oAuthSignin({ username, password });
  }

  async startNewConversation(title?: string) {
    const thread = await this.sdk.ai.threads.create({
      integration: this.integrationId,
      title: title || `Chat ${new Date().toLocaleString()}`
    });
    
    this.currentThread = thread._id!;
    return thread;
  }

  async sendMessage(message: string): Promise<string> {
    if (!this.currentThread) {
      await this.startNewConversation();
    }

    const response = await this.sdk.ai.chat.chatInThread(
      this.integrationId,
      this.currentThread!,
      {
        messages: [{ role: 'user', content: message }],
        temperature: 0.7
      }
    );

    return response.choices[0].message.content;
  }

  async sendStreamingMessage(
    message: string,
    onChunk: (content: string) => void
  ): Promise<void> {
    if (!this.currentThread) {
      await this.startNewConversation();
    }

    const stream = await this.sdk.ai.chat.streamChatInThread(
      this.integrationId,
      this.currentThread!,
      {
        messages: [{ role: 'user', content: message }],
        temperature: 0.7
      }
    );

    for await (const chunk of this.sdk.ai.chat.parseSSEStream(stream)) {
      if (chunk.choices?.[0]?.delta?.content) {
        onChunk(chunk.choices[0].delta.content);
      }
    }
  }

  async getConversationHistory() {
    if (!this.currentThread) return [];
    
    const thread = await this.sdk.ai.threads.getOne(this.currentThread);
    return thread.messages;
  }

  async listPreviousChats() {
    const result = await this.sdk.ai.threads.list({
      integration: this.integrationId,
      limit: 50,
      sort: '-created'
    });
    
    return result.threads;
  }
}

// Usage
const chatApp = new AIChatApp('https://your-app.com', 'your-integration-id');

// Authenticate
await chatApp.authenticate('user@example.com', 'password');

// Start chatting
const response = await chatApp.sendMessage('Hello, how are you?');
console.log('AI:', response);

// Stream a response
await chatApp.sendStreamingMessage('Tell me a story', (chunk) => {
  process.stdout.write(chunk);
});

```

--------------------------------

### Verify Qelos CLI Installation

Source: https://docs.qelos.io/getting-started/integrators

Check the installed version of the Qelos CLI to confirm successful installation.

```bash
$ qelos --version
0.6.2
```

--------------------------------

### Typical Qelos Development Workflow

Source: https://docs.qelos.io/cli/generate

This example outlines a common workflow: pulling Qelos resources, generating IDE rules for enhanced development context, and leveraging the generated documentation within your IDE.

```bash
# Pull resources from Qelos
qelos pull components ./components
qelos pull blocks ./blocks
qelos pull blueprints ./blueprints
qelos pull plugins ./plugins

# Generate IDE rules to help with development
qelos generate rules all

# Now your IDE has context about:
# - Component naming conventions
# - Available global components
# - Blueprint structures
# - Block/micro-frontend limitations
```

--------------------------------

### Install @qelos/integrator-nuxt

Source: https://docs.qelos.io/integrators/nuxt

Install the Nuxt 3 module using npm. This also installs @qelos/sdk as a transitive dependency.

```bash
npm install @qelos/integrator-nuxt
```

--------------------------------

### Complete User Management Example

Source: https://docs.qelos.io/sdk/managing_users

Demonstrates a full workflow of user management using the Qelos Admin SDK, including authentication, listing, creating, updating, retrieving, storing encrypted data, and removing users.

```typescript
import QelosAdminSDK from '@qelos/sdk/administrator';

// Initialize the admin SDK
const sdkAdmin = new QelosAdminSDK({
  appUrl: 'https://your-qelos-app.com',
  fetch: globalThis.fetch
});

// Authenticate as admin
await sdkAdmin.authentication.oAuthSignin({
  username: 'admin@example.com',
  password: 'password'
});

// Get all users
const users = await sdkAdmin.users.getList();
console.log(`Found ${users.length} users`);

// Get users with specific role
const editors = await sdkAdmin.users.getList({ roles: ['editor'] });
console.log(`Found ${editors.length} editors`);

// Create a new user
const newUser = await sdkAdmin.users.create({
  username: 'johndoe',
  email: 'john@example.com',
  password: 'securePassword123',
  firstName: 'John',
  lastName: 'Doe',
  roles: ['user']
});

console.log(`Created user with ID: ${newUser._id}`);

// Update the user
const updatedUser = await sdkAdmin.users.update(newUser._id, {
  roles: ['user', 'editor'],
  metadata: {
    department: 'Engineering'
  }
});

// Get specific user
const user = await sdkAdmin.users.getUser(newUser._id);
console.log(`User: ${user.username} (${user.email})`);

// Store encrypted data
await sdkAdmin.users.setEncryptedData(newUser._id, 'api-keys', {
  githubToken: 'ghp_xxx',
  slackToken: 'xoxb-xxx'
});

// Retrieve encrypted data
const encryptedData = await sdkAdmin.users.getEncryptedData(newUser._id, 'api-keys');
console.log('Retrieved encrypted data');

// Remove the user
await sdkAdmin.users.remove(newUser._id);
console.log('User removed');
```

--------------------------------

### Example Integration-Prompt Dependency

Source: https://docs.qelos.io/cli/get

Shows a JSON configuration for an integration that references a prompt file. This demonstrates dependency detection for integration and prompt resources.

```json
{
  "name": "my-integration",
  "prompts": {
    "system": "./prompts/system-prompt.md"
  }
}
```

--------------------------------

### Navigate to Project Directory

Source: https://docs.qelos.io/cli/create

After creating the plugin, navigate into the newly created project directory to continue development.

```bash
cd my-awesome-plugin
```

--------------------------------

### GET Request

Source: https://docs.qelos.io/sdk/execute_lambdas

Send a GET request to an integration.

```APIDOC
## GET Request

```typescript
const result = await sdk.lambdas.get('integration-id');
```
```

--------------------------------

### Generate Blueprints and Skip SDK Guides

Source: https://docs.qelos.io/cli/blueprints

This command generates blueprint files and skips the creation of accompanying Markdown SDK guides by setting `--guides` to `false`.

```bash
qelos blueprints generate ./blueprints \
  --uri mongodb://localhost:27017/legacy_app \
  --guides false
```

--------------------------------

### Install Nuxt Integrator

Source: https://docs.qelos.io/getting-started/integrators

Install the `@qelos/integrator-nuxt` package for Nuxt.js applications.

```bash
npm install @qelos/integrator-nuxt

```

--------------------------------

### Quick Start with Qelos Web SDK

Source: https://docs.qelos.io/web-sdk

Initialize authentication and log user data and session code in your micro-frontend.

```typescript
import { authorize, code } from '@qelos/web-sdk';

// Initialize authentication
const userData = await authorize();
console.log('Current user:', userData);
console.log('Session code:', code);

// Your application code here
```

--------------------------------

### Qelos CLI: Development Workflow Commands

Source: https://docs.qelos.io/getting-started/quick-reference

Commands for starting the development environment, populating the database, building for production, and running tests.

```bash
# Start dev environment
pnpm dev

# Create initial data
pnpm populate-db

# Build for production
pnpm build

# Run tests
pnpm test
```

--------------------------------

### Save Button Examples

Source: https://docs.qelos.io/pre-designed-frontends/components/save-button

Examples demonstrating various configurations of the save-button component.

```APIDOC
## Examples 

### Basic Usage 

```html
<save-button @click="saveForm"></save-button>
```

### With Custom Text 

```html
<save-button text="Submit" @click="submitForm"></save-button>
```

### With Loading State 

```html
<save-button :loading="isSubmitting" @click="submitWithLoading"></save-button>
```

### Different Button Types 

```html
<save-button type="success" text="Approve" @click="approveItem"></save-button>
<save-button type="danger" text="Reject" @click="rejectItem"></save-button>
```

### With Different Sizes 

```html
<save-button size="large" text="Save All Changes" @click="saveAllChanges"></save-button>
<save-button size="small" text="Quick Save" @click="quickSave"></save-button>
```
```

--------------------------------

### Start Development Server

Source: https://docs.qelos.io/cli/create

Begin the development process by starting the development server. This command typically watches for file changes and enables hot-reloading.

```bash
npm run dev
```