### Install Koolbase CLI

Source: https://docs.koolbase.com/cli/installation

Installs the CLI to /usr/local/bin by detecting the platform and verifying the checksum.

```bash
curl -fsSL https://get.koolbase.com/install.sh | sh
```

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

### Verify SDK Installation

Source: https://docs.koolbase.com/installation

Check the dependency tree to confirm the package is correctly installed.

```bash
flutter pub deps | grep koolbase_flutter
```

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

### GET /v1/sdk/bootstrap

Source: https://docs.koolbase.com/api/feature-flags

Fetch all flags, configuration, and version policy for SDK initialization.

```APIDOC
## GET /v1/sdk/bootstrap

### Description
The Flutter SDK calls this single endpoint on init to fetch all flags, config, and version policy in one request.

### Method
GET

### Endpoint
/v1/sdk/bootstrap

### Parameters
#### Query Parameters
- **key** (string) - Required - SDK key

### Response
#### Success Response (200)
- **flags** (object) - Map of flag keys to boolean values
- **config** (object) - Configuration settings
- **version_policy** (object) - Version policy details

### Response Example
{
  "flags": {
    "new_checkout": true,
    "dark_mode": false
  },
  "config": {
    "api_base_url": "https://api.myapp.com",
    "timeout_seconds": 30
  },
  "version_policy": {
    "min_version": "2.1.0",
    "status": "force_update",
    "message": "Please update to continue.",
    "store_url": "https://apps.apple.com/..."
  }
}
```

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

### Install Koolbase SDK

Source: https://docs.koolbase.com/quick-start

Add the dependency to your project configuration or use the CLI to install the package.

```yaml
dependencies:
  flutter:
  sdk: flutter
  koolbase_flutter: ^9.4.0
```

```bash
flutter pub add koolbase_flutter
```

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

### Curl Examples for Usage History

Source: https://docs.koolbase.com/storage/usage-history

Examples for querying storage usage history using curl with different parameters.

```bash
# Default window (last 30 days, project-wide)
curl -H "Authorization: Bearer $TOKEN"   "https://api.koolbase.com/v1/projects/$PROJECT_ID/storage/usage/history"

# Explicit range
curl -H "Authorization: Bearer $TOKEN"   "https://api.koolbase.com/v1/projects/$PROJECT_ID/storage/usage/history?from=2026-05-01&to=2026-06-05"

# Per-bucket
curl -H "Authorization: Bearer $TOKEN"   "https://api.koolbase.com/v1/projects/$PROJECT_ID/storage/usage/history?bucket_id=$BUCKET_ID"
```

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

### Install a Koolbase engine

Source: https://docs.koolbase.com/code-push/engines

Downloads and installs the engine corresponding to the specified Flutter version.

```bash
# Install the Koolbase engine for your Flutter version
koolbase engine install 3.44.0
```

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

### Install SDK via Command Line

Source: https://docs.koolbase.com/installation

Use the Flutter CLI to add the package and fetch dependencies.

```bash
flutter pub add koolbase_flutter
```

```bash
flutter pub get
```

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

### Quick Start Commands

Source: https://docs.koolbase.com/cli/installation

Common commands for deploying functions, listing resources, and managing cron schedules.

```bash
# Login
koolbase login

# Deploy a TypeScript function
koolbase deploy send-email --file ./send_email.ts --project <project_id>

# Deploy a Dart function
koolbase deploy process-order --file ./process.dart --project <project_id>

# List functions
koolbase functions list --project <project_id>

# Invoke a function
koolbase invoke send-email --project <project_id> --data '{"to":"user@example.com"}'

# View logs
koolbase logs send-email --project <project_id>

# Add a cron schedule
koolbase crons add send-email --cron "0 9 * * *" --project <project_id>
```

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

### Install the React Native SDK

Source: https://docs.koolbase.com/sdk/react-native

Choose the package manager command appropriate for your project environment.

```bash
npm install @koolbase/react-native
```

```bash
yarn add @koolbase/react-native
```

```bash
pnpm add @koolbase/react-native
```

```bash
bun add @koolbase/react-native
```

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

### Verify CLI Installation

Source: https://docs.koolbase.com/cli/installation

Checks the currently installed version of the Koolbase CLI.

```bash
koolbase version
```

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

### Runtime Bundle JSON Configuration Files

Source: https://docs.koolbase.com/code-push/runtime-bundles

Example content for the configuration, flags, and directives files within a bundle.

```json
// config.json
{
  "api_timeout_ms": 8000,
  "max_retry_count": 5,
  "support_url": "https://help.myapp.com"
}

// flags.json
{
  "new_checkout_flow": true,
  "legacy_auth": false,
  "dark_mode_beta": true
}

// directives.json
{
  "force_logout_all": false
}
```

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

### View Login URL

Source: https://docs.koolbase.com/cli/login

Example output displayed when the browser fails to open automatically.

```text
Opening your browser to sign in with Google...

If your browser didn't open, visit this URL to continue:

https://accounts.google.com/o/oauth2/v2/auth?client_id=...

 Logged in as you@example.com
```

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

### CLI Configuration File

Source: https://docs.koolbase.com/cli/installation

Example of the local configuration file used to store session tokens and default project settings.

```json
{
  "api_key": "your-session-token",
  "email": "you@example.com",
  "base_url": "https://api.koolbase.com",
  "project_id": "your-default-project-id"
}
```

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

### Deploy Koolbase with Docker Compose

Source: https://docs.koolbase.com/self-hosting

Clone the repository and start the full stack including API, database, cache, and storage services.

```bash
git clone https://github.com/kennedyowusu/koolbase-api
cd koolbase-api
cp .env.example .env
docker compose up
```

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

### koolbase mcp install

Source: https://docs.koolbase.com/cli/commands

Configures the Koolbase MCP server for Claude Desktop.

```APIDOC
## koolbase mcp install

### Description
Wire the Koolbase MCP server into Claude Desktop in one command.

### Parameters
- **--key** (string) - Required - Koolbase API key.
- **--codepush-mutations** (flag) - Optional - Enable code-push publish/recall tools.

### Usage
`koolbase mcp install --key <key>`
```

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

### GET /v1/environments/{env_id}/configs

Source: https://docs.koolbase.com/api/remote-config

List all configuration keys for a specific environment.

```APIDOC
## GET /v1/environments/{env_id}/configs

### Description
List all config keys for the specified environment.

### Method
GET

### Endpoint
/v1/environments/{env_id}/configs

### Parameters
#### Path Parameters
- **env_id** (string) - Required - The unique identifier of the environment.
```

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

### Send a welcome email via function

Source: https://docs.koolbase.com/functions/deploy

A practical example demonstrating database lookup, secret retrieval, and an external API call using fetch.

```typescript
export async function handler(ctx) {
  const { userId } = ctx.request;

  // Read the user from the database
  const users = await ctx.db.find('users', { id: userId });
  if (!users.length) {
    return { error: 'User not found' };
  }

  const user = users[0];
  const apiKey = Deno.env.get('SENDGRID_KEY');

  // Call external email API
  const res = await fetch('https://api.sendgrid.com/v3/mail/send', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${apiKey}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      to: [{ email: user.data.email }],
      from: { email: 'hello@myapp.com' },
      subject: 'Welcome to MyApp!',
      text: `Hi ${user.data.name}, welcome aboard!`,
    }),
  });

  return { sent: res.ok, email: user.data.email };
}
```

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

### GET /v1/code-push/check

Source: https://docs.koolbase.com/api/code-push

Check whether a newer bundle is available for the device.

```APIDOC
## GET /v1/code-push/check

### Description
Check whether a newer bundle is available for this device. Rate-limited per device_id.

### Method
GET

### Endpoint
/v1/code-push/check
```

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

### Configure MCP server

Source: https://docs.koolbase.com/cli/commands

Commands to install the MCP server configuration or run the server process over stdio.

```bash
koolbase mcp install --key kb_live_your_key_here
```

```bash
KOOLBASE_API_KEY=kb_live_... koolbase mcp serve
```

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

### GET /v1/projects/{id}/snapshot

Source: https://docs.koolbase.com/promote

Exports the configuration of a specified project as a snapshot.

```APIDOC
## GET /v1/projects/{id}/snapshot

### Description
Export the source project's config as a snapshot.

### Method
GET

### Endpoint
/v1/projects/{id}/snapshot

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the project.
```

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

### Initialize Koolbase SDK

Source: https://docs.koolbase.com/quick-start

Call the initialization method before the application starts to configure the connection.

```dart
import 'package:flutter/material.dart';
import 'package:koolbase_flutter/koolbase_flutter.dart';
void main() async {
  WidgetsFlutterBinding.ensureInitialized();
  await Koolbase.initialize(const KoolbaseConfig(
    publicKey: 'pk_live_your_key_here',
    baseUrl: 'https://api.koolbase.com',
  ));
  runApp(const MyApp());
}
```

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

### List available engines

Source: https://docs.koolbase.com/code-push/engines

Displays engines available for the current host and target, indicating which are already installed locally.

```bash
koolbase engine list
```

```text
Available engines for host macos/arm64, target android/arm64:
  ✓ 3.44.3-koolbase.1  (flutter 3.44.3, 425 MB)
  ✓ 3.41.9-koolbase.1  (flutter 3.41.9, 411 MB)
  ✓ 3.38.10-koolbase.1 (flutter 3.38.10, 404 MB)
  ✓ 3.35.7-koolbase.1  (flutter 3.35.7, 401 MB)
  ✓ 3.32.8-koolbase.1  (flutter 3.32.8, 379 MB)
  ✓ 3.32.1-koolbase.1  (flutter 3.32.1, 379 MB)
✓ = installed locally
(Earlier patch revisions of each minor are also published — run the command for the full list.)
```

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

### Security Warnings in Deploy Response

Source: https://docs.koolbase.com/functions/dependency-security

Example of the JSON response structure containing security warnings for a successful deployment.

```json
{
  "id": "…",
  "name": "send-welcome-email",
  "version": 7,
  "security_warnings": [
    "archive@3.3.0: GHSA-xxxx-xxxx-xxxx (MODERATE) Path traversal in extract…"
  ]
}
```

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

### GET /p/{project_id}/{preset_name}/{bucket}/{path}

Source: https://docs.koolbase.com/storage/image-transforms

Retrieve an image transformed according to a pre-configured named preset.

```APIDOC
## GET /p/{project_id}/{preset_name}/{bucket}/{path}

### Description
Retrieve an image using a server-side stored preset, which defines a fixed set of transformation options.

### Method
GET

### Endpoint
https://cdn.koolbase.com/p/{project_id}/{preset_name}/{bucket}/{path}

### Parameters
#### Path Parameters
- **project_id** (string) - Required - The unique project identifier
- **preset_name** (string) - Required - The name of the stored preset (e.g., thumbnail, hero, card)
- **bucket** (string) - Required - The storage bucket name
- **path** (string) - Required - The file path to the source image

### Request Example
https://cdn.koolbase.com/p/my-project/thumbnail/my-bucket/images/photo.jpg
```

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

### Initialize SDK and Handle Fallbacks

Source: https://docs.koolbase.com/sdk/offline-support

Demonstrates SDK initialization and safe access to flags and config values when offline or without a cache.

```dart
// SDK init — safe even with no network
await Koolbase.init(apiKey: 'pk_live_...');
// If no network and no cache: flags={}, config={}, version=null

// These will all return fallbacks safely
final show = Koolbase.flags['new_ui'] ?? false;          // false
final url  = Koolbase.config.getString('api_url',
  fallback: 'https://api.myapp.com');                    // fallback
final ver  = await Koolbase.version.check();             // upToDate
```

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

### Phone Number Format Examples

Source: https://docs.koolbase.com/auth/phone-otp

Examples of valid and invalid phone number formats for E.164 compliance.

```text
Valid
  +233244000000     Ghana
  +14155551234      United States
  +442079460000     United Kingdom

Invalid (will fail SDK validation)
  0244000000        — missing country code
  +233 244 000 000  — spaces not allowed
  +233-244-000000   — dashes not allowed
```

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

### GET /v1/apps/{app_id}/bundles

Source: https://docs.koolbase.com/api/code-push

List all bundles for an app.

```APIDOC
## GET /v1/apps/{app_id}/bundles

### Description
List all bundles for an app.

### Method
GET

### Endpoint
/v1/apps/{app_id}/bundles
```

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

### Initialize Koolbase

Source: https://docs.koolbase.com/code-push/quickstart

Configure the SDK at application startup to enable Runtime Bundles and VM patch staging.

```dart
import 'package:koolbase_flutter/koolbase_flutter.dart';

Future<void> main() async {
  WidgetsFlutterBinding.ensureInitialized();

  await Koolbase.initialize(
    KoolbaseConfig(
      baseUrl: 'https://api.koolbase.com',
      publicKey: 'pk_live_...',
      codePushChannel: 'stable',
    ),
  );

  runApp(const MyApp());
}
```

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

### GET /sdk/auth/me

Source: https://docs.koolbase.com/api/authentication

Retrieves the profile of the currently authenticated user.

```APIDOC
## GET /sdk/auth/me

### Description
Get the currently authenticated user.

### Method
GET

### Endpoint
/sdk/auth/me

### Response
#### Success Response (200)
- **id** (string) - User UUID
- **email** (string) - User email
- **verified** (boolean) - Verification status
- **created_at** (string) - Creation timestamp

#### Response Example
{
  "id": "uuid",
  "email": "user@example.com",
  "verified": true,
  "created_at": "2026-01-01T00:00:00Z"
}
```

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

### Add Koolbase SDK

Source: https://docs.koolbase.com/code-push/quickstart

Install the required dependency into your Flutter project.

```bash
flutter pub add koolbase_flutter
```

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

### Bootstrap SDK Configuration

Source: https://docs.koolbase.com/api/feature-flags

Fetches all flags, configuration, and version policies required for SDK initialization.

```json
GET /v1/sdk/bootstrap?key=pk_live_...

// Response 200
{
  "flags": {
    "new_checkout": true,
    "dark_mode": false
  },
  "config": {
    "api_base_url": "https://api.myapp.com",
    "timeout_seconds": 30
  },
  "version_policy": {
    "min_version": "2.1.0",
    "status": "force_update",
    "message": "Please update to continue.",
    "store_url": "https://apps.apple.com/..."
  }
}
```

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

### GET /v1/apps/{app_id}/bundles/{bundle_id}

Source: https://docs.koolbase.com/api/code-push

Fetch a single bundle.

```APIDOC
## GET /v1/apps/{app_id}/bundles/{bundle_id}

### Description
Fetch a single bundle.

### Method
GET

### Endpoint
/v1/apps/{app_id}/bundles/{bundle_id}
```

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

### GET /v1/environments/{env_id}/flags

Source: https://docs.koolbase.com/api/feature-flags

List all flags for a specific environment.

```APIDOC
## GET /v1/environments/{env_id}/flags

### Description
List all flags for an environment.

### Method
GET

### Endpoint
/v1/environments/{env_id}/flags

### Parameters
#### Path Parameters
- **env_id** (string) - Required - The environment identifier.
```

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

### Deploy a bundle

Source: https://docs.koolbase.com/cli/commands

Packages and deploys a bundle directory to a specific app and platform.

```bash
koolbase bundle deploy   --app d2bc2c2c-fb42-4891-b758-45e48a1cd871   --platform ios   --channel stable   --base-app-version 1.2.0   --max-app-version 1.2.99   --bundle-dir ./bundle   --rollout 10
```

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

### GET /v1/projects/{id}/crons

Source: https://docs.koolbase.com/functions/cron

Lists all cron schedules associated with a project.

```APIDOC
## GET /v1/projects/{id}/crons

### Description
Retrieves a list of all cron schedules configured for the specified project.

### Method
GET

### Endpoint
/v1/projects/{id}/crons

### Parameters
#### Path Parameters
- **id** (string) - Required - The project ID.
```

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

### Register New User

Source: https://docs.koolbase.com/api/authentication

Create a new account by providing an email and password.

```json
// Request
{
  "email": "user@example.com",
  "password": "securepassword"
}

// Response 201
{
  "id": "uuid",
  "email": "user@example.com",
  "verified": false,
  "created_at": "2026-01-01T00:00:00Z"
}
```

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

### GET /sdk/storage/download-url

Source: https://docs.koolbase.com/api/storage

Retrieves a temporary download URL for a specific file in a bucket.

```APIDOC
## GET /sdk/storage/download-url

### Description
Generates a public download URL for an object stored in a bucket.

### Method
GET

### Endpoint
/sdk/storage/download-url

### Parameters
#### Query Parameters
- **bucket** (string) - Required - The bucket name.
- **path** (string) - Required - The file path.

### Response
#### Success Response (200)
- **url** (string) - The generated download URL.

#### Response Example
{
  "url": "https://pub-xxx.r2.dev/user_abc123.jpg"
}
```

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

### Deploy a bundle via CLI

Source: https://docs.koolbase.com/code-push/runtime-bundles

Packages, uploads, and publishes a bundle directory in a single command.

```bash
koolbase bundle deploy \
  --app <project_id> \
  --platform ios \
  --channel stable \
  --base-app-version 1.2.0 \
  --max-app-version 1.2.99 \
  --bundle-dir ./bundle \
  --rollout 10
```

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

### GET /v1/apps/{app_id}/bundles/{bundle_id}/stats

Source: https://docs.koolbase.com/api/code-push

Fetch stats for a bundle.

```APIDOC
## GET /v1/apps/{app_id}/bundles/{bundle_id}/stats

### Description
Fetch check / download / activation / failure counts for a bundle.

### Method
GET

### Endpoint
/v1/apps/{app_id}/bundles/{bundle_id}/stats
```

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

### GET /v1/projects/{id}/domains

Source: https://docs.koolbase.com/auth/email-branding

List all registered sender domains for the project.

```APIDOC
## GET /v1/projects/{id}/domains

### Description
List registered domains for the project.

### Method
GET

### Endpoint
/v1/projects/{id}/domains

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the project.
```

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

### GET /v1/projects/{id}

Source: https://docs.koolbase.com/auth/email-branding

Fetch the current branding state for a specific project.

```APIDOC
## GET /v1/projects/{id}

### Description
Fetch current branding state for the specified project.

### Method
GET

### Endpoint
/v1/projects/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the project.
```

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

### Create a bundle draft

Source: https://docs.koolbase.com/api/code-push

Initializes a new bundle in draft status. Requires a valid session token and app configuration.

```bash
curl -X POST "https://api.koolbase.com/v1/apps/{app_id}/bundles" \
  -H "Authorization: Bearer YOUR_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "base_app_version": "1.2.0",
    "max_app_version": "1.2.99",
    "platform": "ios",
    "channel": "stable",
    "rollout_percentage": 10,
    "mandatory": false,
    "release_notes": "Updated checkout config",
    "payload": {
      "config": { "api_timeout_ms": 8000 },
      "flags": { "new_checkout_flow": true },
      "directives": {},
      "assets": { "images": [], "json": [], "fonts": [] }
    }
  }'
```

```json
{
  "bundle_id": "e3347496-9fd3-406c-bd3c-494c5778b1d8",
  "app_id": "d2bc2c2c-fb42-4891-b758-45e48a1cd871",
  "version": 3,
  "base_app_version": "1.2.0",
  "max_app_version": "1.2.99",
  "platform": "ios",
  "channel": "stable",
  "status": "draft",
  "rollout_percentage": 10,
  "mandatory": false,
  "release_notes": "Updated checkout config",
  "checksum": "",
  "signature": "",
  "size_bytes": 0,
  "storage_key": "code-push/.../stable/v3.zip",
  "payload": { "config": {}, "flags": {}, "directives": {}, "assets": {} },
  "created_by": "usr_...",
  "created_at": "2026-05-20T10:14:00Z"
}
```

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

### Publish bundle

Source: https://docs.koolbase.com/api/code-push

Makes the uploaded bundle live. This action recalls any previously published bundle for the same app, platform, and channel.

```bash
curl -X POST "https://api.koolbase.com/v1/apps/{app_id}/bundles/{bundle_id}/publish" \
  -H "Authorization: Bearer YOUR_SESSION_TOKEN"
```

```json
{ "status": "published" }
```

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

### Manage bundles via CLI

Source: https://docs.koolbase.com/code-push/runtime-bundles

Commands for listing, recalling, and dry-running bundle deployments.

```bash
# List all bundles for an app
koolbase bundle list --app <project_id>

# Recall a published bundle (devices revert on next cold launch)
koolbase bundle recall --app <project_id> --bundle <bundle_id>

# Dry run — validate and package without uploading
koolbase bundle deploy ... --dry-run
```

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

### Initialize Koolbase Analytics

Source: https://docs.koolbase.com/sdk/analytics

Configure the SDK and register the navigator observer for automatic screen tracking within a MaterialApp.

```dart
await Koolbase.initialize(KoolbaseConfig(
  publicKey: 'pk_live_xxx',
  baseUrl: 'https://api.koolbase.com',
  analyticsEnabled: true, // default — can be omitted
));

// Add to MaterialApp for automatic screen tracking
MaterialApp(
  navigatorObservers: [
    KoolbaseNavigatorObserver(client: Koolbase.analytics),
  ],
  home: const HomeScreen(),
)
```

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

### GET /sdk/storage/list

Source: https://docs.koolbase.com/api/storage

Lists files within a bucket, optionally filtered by a path prefix.

```APIDOC
## GET /sdk/storage/list

### Description
Returns a list of files stored in the specified bucket, filtered by an optional prefix.

### Method
GET

### Endpoint
/sdk/storage/list

### Parameters
#### Query Parameters
- **bucket** (string) - Required - The bucket name.
- **prefix** (string) - Optional - The path prefix to filter results.

### Response
#### Success Response (200)
- **files** (array) - A list of file objects.

#### Response Example
{
  "files": [
    {
      "path": "user_abc123.jpg",
      "size": 204800,
      "content_type": "image/jpeg",
      "metadata": { "user_id": "usr_a4f9b21c" },
      "created_at": "2026-01-01T00:00:00Z"
    }
  ]
}
```

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

### POST /v1/environments/{env_id}/configs

Source: https://docs.koolbase.com/api/remote-config

Create a new configuration key-value pair.

```APIDOC
## POST /v1/environments/{env_id}/configs

### Description
Create a new config key in the specified environment.

### Method
POST

### Endpoint
/v1/environments/{env_id}/configs

### Parameters
#### Path Parameters
- **env_id** (string) - Required - The unique identifier of the environment.

#### Request Body
- **key** (string) - Required - The configuration key name.
- **value** (any) - Required - The value associated with the key (string, number, boolean, or json).
- **type** (string) - Required - The data type (string, number, boolean, json).

### Response
#### Success Response (201)
- **id** (string) - The unique identifier of the created config.
- **key** (string) - The config key.
- **value** (any) - The config value.
- **type** (string) - The data type.
- **created_at** (string) - Timestamp of creation.
- **updated_at** (string) - Timestamp of last update.
```

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

### GET /v1/projects/{project_id}/environments

Source: https://docs.koolbase.com/api/environments

Retrieves a list of all environments associated with a specific project.

```APIDOC
## GET /v1/projects/{project_id}/environments

### Description
List all environments for a given project.

### Method
GET

### Endpoint
/v1/projects/{project_id}/environments

### Parameters
#### Path Parameters
- **project_id** (string) - Required - The unique identifier of the project.

### Response
#### Success Response (200)
- **id** (string) - Environment ID
- **project_id** (string) - Project ID
- **name** (string) - Environment name
- **public_key** (string) - Public key
- **created_at** (string) - Creation timestamp

#### Response Example
[
  {
    "id": "uuid",
    "project_id": "project_uuid",
    "name": "Production",
    "public_key": "pk_live_6e4abe...",
    "created_at": "2026-01-01T00:00:00Z"
  }
]
```

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

### Initialize App and Check Session

Source: https://docs.koolbase.com/examples/flutter-auth

Configures the Koolbase SDK and determines the initial route based on the current user session and version enforcement status.

```Dart
import 'package:flutter/material.dart';
import 'package:koolbase/koolbase.dart';

void main() async {
  WidgetsFlutterBinding.ensureInitialized();
  await Koolbase.init(apiKey: 'pk_live_your_key_here');

  // Check version enforcement first
  final versionCheck = await Koolbase.version.check();
  if (versionCheck.status == VersionStatus.forceUpdate) {
    runApp(ForceUpdateApp(message: versionCheck.message));
    return;
  }

  // Check for existing session
  final user = await Koolbase.auth.currentUser();
  runApp(MyApp(initialRoute: user != null ? '/home' : '/login'));
}

class MyApp extends StatelessWidget {
  final String initialRoute;
  const MyApp({required this.initialRoute, super.key});

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      initialRoute: initialRoute,
      routes: {
        '/login': (_) => const LoginScreen(),
        '/register': (_) => const RegisterScreen(),
        '/home': (_) => const HomeScreen(),
      },
    );
  }
}
```

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

### Check for updates

Source: https://docs.koolbase.com/api/code-push

Initiates a check for new bundles on cold launch. Requires app_version, platform, channel, and device_id parameters.

```bash
curl "https://api.koolbase.com/v1/code-push/check?app_version=1.2.0&platform=ios&channel=stable&device_id=abc-123&current_bundle=2" \
  -H "x-api-key: pk_live_xxxx"
```

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

### Public function handler

Source: https://docs.koolbase.com/functions/authentication

An example of a function that skips authentication checks to allow anonymous access.

```typescript
export async function handler(ctx) {
  // No auth check — anyone can call this.
  await ctx.db.insert('events', {
    name: ctx.request.body.event,
    timestamp: new Date().toISOString(),
  });
  return { ok: true };
}
```

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

### Deploy a function

Source: https://docs.koolbase.com/api/functions

Create or update a function by providing the name, source code, and timeout configuration.

```json
// Request
{
  "name": "send-welcome-email",
  "code": "export async function handler(ctx) { return { ok: true }; }",
  "timeout_ms": 10000
}

// Response 201
{
  "id": "uuid",
  "name": "send-welcome-email",
  "version": 1,
  "is_active": true,
  "timeout_ms": 10000,
  "last_deployed_at": "2026-01-01T00:00:00Z"
}
```

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

### Promote project definitions via CLI

Source: https://docs.koolbase.com/promote

Use these commands to pull a project definition and apply it to a target project. The process relies on a koolbase.json file as the source of truth.

```bash
# 1. Pull the source project's definition (writes ./koolbase.json)
koolbase snapshot pull --project SOURCE_PROJECT_ID

# 2. Commit it — your backend definition now lives in version control
git add koolbase.json && git commit -m "Update backend definition"

# 3. Preview what would change in the target (writes nothing)
koolbase snapshot apply --project TARGET_PROJECT_ID --dry-run

# 4. Apply for real
koolbase snapshot apply --project TARGET_PROJECT_ID
```

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

### Get specific version details

Source: https://docs.koolbase.com/storage/versioning

Retrieve metadata for a single version using its unique ID.

```Flutter
final v = await Koolbase.storage.getVersion(
  bucket: 'documents',
  path: 'contract.pdf',
  versionId: '019e98ed-eed6-7e71-...',
);
```

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

### Deploy functions

Source: https://docs.koolbase.com/cli/commands

Deploy a function from a local file. The runtime is automatically detected based on the file extension.

```bash
koolbase deploy send-email --file ./send_email.ts --project proj_123
koolbase deploy process --file ./process.dart --project proj_123
```

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

### GET /projects/{id}/buckets

Source: https://docs.koolbase.com/api/storage

Retrieves a list of all storage buckets associated with a specific project.

```APIDOC
## GET /projects/{id}/buckets

### Description
Retrieves a list of all storage buckets associated with a specific project.

### Method
GET

### Endpoint
/projects/{id}/buckets

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the project.

### Response
#### Success Response (200)
- **id** (string) - Unique bucket identifier
- **project_id** (string) - Associated project identifier
- **name** (string) - Bucket name
- **public** (boolean) - Public access status
- **max_size_bytes** (integer) - Maximum total size allowed
- **max_file_size_bytes** (integer) - Maximum size per file allowed
- **allowed_mime_types** (array) - List of allowed MIME types
- **current_size_bytes** (integer) - Current total size of files in bucket
- **created_at** (string) - Creation timestamp

### Response Example
[
  {
    "id": "buc_a4f9b21c",
    "project_id": "proj_d8c7a2",
    "name": "avatars",
    "public": false,
    "max_size_bytes": 1073741824,
    "max_file_size_bytes": 5242880,
    "allowed_mime_types": ["image/*"],
    "current_size_bytes": 204800,
    "created_at": "2026-01-01T00:00:00Z"
  }
]
```

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

### Get a single record by ID

Source: https://docs.koolbase.com/database/insert-query

Retrieves a specific document from a collection using its unique identifier.

```dart
final record = await Koolbase.db
  .collection('posts')
  .doc('record-uuid-here')
  .get();

print(record.data['title']);
```

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

### POST /sdk/storage/upload-url

Source: https://docs.koolbase.com/api/storage

Get a presigned R2 upload URL to initiate the file upload process.

```APIDOC
## POST /sdk/storage/upload-url

### Description
Get a presigned R2 upload URL. After receiving the URL, PUT the file bytes directly to the provided upload_url. The URL expires in 300 seconds.

### Method
POST

### Endpoint
/sdk/storage/upload-url

### Request Body
- **bucket** (string) - Required - The name of the bucket.
- **path** (string) - Required - The file path.
- **content_type** (string) - Required - The MIME type of the file.
- **size** (integer) - Required - The size of the file in bytes.
- **overwrite** (boolean) - Optional - Whether to overwrite an existing file. Defaults to false.

### Request Example
{
  "bucket": "avatars",
  "path": "user_abc123.jpg",
  "content_type": "image/jpeg",
  "size": 204800,
  "overwrite": false
}

### Response
#### Success Response (200)
- **upload_url** (string) - The presigned URL for the upload.
- **expires_in** (integer) - Expiration time in seconds.

#### Response Example
{
  "upload_url": "https://r2.example.com/presigned?...",
  "expires_in": 300
}
```

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

### Manage API keys

Source: https://docs.koolbase.com/cli/commands

Commands for creating, listing, and revoking organization API keys for programmatic access.

```bash
koolbase keys create --name claude-desktop --scope write
```

```bash
koolbase keys list
```

```bash
koolbase keys revoke 4e1cd5b6-bc92-4c2d-98f1-a47dd6931828
```

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

### Build a patchable release

Source: https://docs.koolbase.com/code-push/shipping-a-release

Use this command to build an Android release with the necessary engine and registration. Ensure the --project flag is included to avoid creating an unpatchable build.

```bash
koolbase release android \
  --engine <engine-version> \
  --flutter-sdk /path/to/matching/flutter \
  --flavor prod \
  --dart-define-from-file=.env \
  --channel stable \
  --project <your-project-id>
```

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

### GET /v1/environments/{env_id}/version

Source: https://docs.koolbase.com/api/version-policy

Retrieves the current version policy configuration for a specified environment.

```APIDOC
## GET /v1/environments/{env_id}/version

### Description
Get the current version policy for the specified environment.

### Method
GET

### Endpoint
/v1/environments/{env_id}/version

### Parameters
#### Path Parameters
- **env_id** (string) - Required - The unique identifier of the environment.
```

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

### Limit and offset query results

Source: https://docs.koolbase.com/database/insert-query

Controls the number of returned records and the starting position for pagination.

```dart
// Get first 10 records
final page1 = await Koolbase.db
  .collection('posts')
  .limit(10)
  .get();

// Get next 10 records
final page2 = await Koolbase.db
  .collection('posts')
  .limit(10)
  .offset(10)
  .get();
```

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

### Automate backend promotion with GitHub Actions

Source: https://docs.koolbase.com/promote

Configure a CI/CD pipeline to automatically preview changes on pull requests and apply updates to production upon merging to main.

```yaml
name: Koolbase backend

on:
  pull_request:
    paths: ["koolbase.json"]
  push:
    branches: [main]
    paths: ["koolbase.json"]

env:
  KOOLBASE_BASE_URL: https://api.koolbase.com
  KOOLBASE_API_KEY: ${{ secrets.KOOLBASE_API_KEY }}

jobs:
  plan:
    if: github.event_name == 'pull_request'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-go@v5
        with:
          go-version: stable
      - run: go install github.com/kennedyowusu/koolbase-cli@latest
      - run: koolbase-cli snapshot apply --project ${{ vars.KOOLBASE_PROD_PROJECT_ID }} --dry-run

  apply:
    if: github.event_name == 'push'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-go@v5
        with:
          go-version: stable
      - run: go install github.com/kennedyowusu/koolbase-cli@latest
      - run: koolbase-cli snapshot apply --project ${{ vars.KOOLBASE_PROD_PROJECT_ID }}
```

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

### Initialize the SDK

Source: https://docs.koolbase.com/sdk/react-native

Initialize the Koolbase instance at app startup and restore existing sessions before rendering the application.

```typescript
import { useEffect, useState } from 'react';
import {
  Koolbase,
  RestoreResult,
} from '@koolbase/react-native';

export default function App() {
  const [ready, setReady] = useState(false);

  useEffect(() => {
    (async () => {
      await Koolbase.initialize({
        publicKey: 'pk_live_your_key_here',
        baseUrl: 'https://api.koolbase.com',
        codePushChannel: 'stable',
        analyticsEnabled: true,
        appVersion: '1.0.0',
        authTimeout: 10000, // optional, default 10s
        onMandatoryUpdate: ({ version, bundleId }) => {
          // A mandatory code push bundle staged — prompt to restart
          console.log('Mandatory bundle staged', version, bundleId);
        },
      });

      // Restore any session persisted from a previous launch.
      // Optimistic state is populated before any network call, so
      // authenticated UI renders immediately if a session exists.
      const result = await Koolbase.auth.restoreSession();
      switch (result) {
        case RestoreResult.Restored:
        case RestoreResult.Offline:    // optimistic restore, will revalidate
        case RestoreResult.NoSession:
        case RestoreResult.Expired:
          break;
      }
      setReady(true);
    })();
  }, []);

  if (!ready) return null;
  return <Navigation />;
}
```

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

### Configure Environment Variables

Source: https://docs.koolbase.com/self-hosting

Define database, Redis, JWT, email, and storage settings in the .env file.

```env
# Database
DATABASE_URL=postgres://postgres:password@postgres:5432/koolbase?sslmode=disable

# Redis
REDIS_URL=redis://redis:6379

# JWT
JWT_SECRET=change-me-to-a-long-random-string

# Email (Resend)
RESEND_API_KEY=re_xxxx
EMAIL_FROM=Koolbase <noreply@yourdomain.com>

# Storage — MinIO (default for self-hosting)
S3_ENDPOINT=http://minio:9000
R2_ACCESS_KEY_ID=minioadmin
R2_SECRET_ACCESS_KEY=minioadmin
R2_BUCKET=koolbase
R2_PUBLIC_URL=http://localhost:9000/koolbase

# App
APP_URL=http://localhost:3001
PORT=8080

# Internal API key
INTERNAL_API_KEY=change-me-to-a-random-string
```

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

### Configure Base URL and API Key

Source: https://docs.koolbase.com/api/authentication

Set the base URL and include the required x-api-key header for all SDK requests.

```text
Base URL: https://api.koolbase.com/v1/sdk

All requests require:
  x-api-key: pk_live_your_public_key_here
```

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

### Invalid Origin Formats

Source: https://docs.koolbase.com/storage/trusted-origins

Examples of formats that will be rejected by the dashboard, such as those containing paths, wildcards, or missing schemes.

```text
https://app.example.com/dashboard   # contains a path
https://*.example.com                # wildcards not supported
example.com                          # missing scheme
https://app.example.com/             # trailing slash
```

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

### Access Cron Metadata in Function

Source: https://docs.koolbase.com/functions/cron

Examples of accessing cron metadata from the function context in JavaScript and Dart.

```javascript
export async function handler(ctx) {
  // ctx.request contains cron metadata
  const { cron_id, expression, fired_at } = ctx.request;

  console.log(`Cron ${expression} fired at ${fired_at}`);

  // Your logic here
  await ctx.db.insert('reports', {
    generated_at: fired_at,
    type: 'daily',
  });

  return { ok: true, fired_at };
}
```

```dart
Future<Map<String, dynamic>> handler(Map<String, dynamic> ctx) async {
  final request = ctx['request'] as Map<String, dynamic>;
  final firedAt = request['fired_at'] as String?;

  // Your logic here
  final db = ctx['db'] as Map<String, dynamic>;
  await (db['insert'] as Function)('reports', {
    'generated_at': firedAt,
    'type': 'daily',
  });

  return {'ok': true, 'fired_at': firedAt};
}
```

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

### Get current user in Dart

Source: https://docs.koolbase.com/auth/register-login

Retrieves the currently authenticated user or returns null if no session exists.

```dart
final user = await Koolbase.auth.currentUser();

if (user == null) {
  // Not logged in — show login screen
  Navigator.pushNamed(context, '/login');
} else {
  // Logged in — show app
  print('Welcome, ${user.email}');
}
```

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

### List functions

Source: https://docs.koolbase.com/cli/commands

List all deployed functions within a specific project.

```bash
koolbase functions list --project proj_123
```

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

### Get Authenticated User

Source: https://docs.koolbase.com/api/authentication

Retrieve details for the current user using the session token in the Authorization header.

```http
// Request headers
Authorization: Bearer <session_token>

// Response 200
{
  "id": "uuid",
  "email": "user@example.com",
  "verified": true,
  "created_at": "2026-01-01T00:00:00Z"
}
```

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

### POST /v1/apps/{app_id}/bundles

Source: https://docs.koolbase.com/api/code-push

Create a draft bundle.

```APIDOC
## POST /v1/apps/{app_id}/bundles

### Description
Create a draft bundle.

### Method
POST

### Endpoint
/v1/apps/{app_id}/bundles

### Parameters
#### Path Parameters
- **app_id** (string) - Required - The project ID.
```

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

### Initialize Flutter SDK

Source: https://docs.koolbase.com/self-hosting

Configure the Koolbase SDK to connect to your self-hosted instance by specifying the base URL.

```dart
await Koolbase.initialize(const KoolbaseConfig(
  publicKey: 'pk_live_xxxx',
  baseUrl: 'http://your-server-ip:8080', // or your domain
));
```

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

### Valid Origin Formats

Source: https://docs.koolbase.com/storage/trusted-origins

Examples of correctly formatted origins that include the scheme and host, without paths or wildcards.

```text
https://app.example.com
http://localhost:3000
https://staging.mycompany.com:8443
```

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

### Initialize Koolbase with Code Push

Source: https://docs.koolbase.com/code-push/runtime-bundles

Configure the SDK to support runtime bundles by specifying a codePushChannel during initialization.

```dart
await Koolbase.initialize(KoolbaseConfig(
  publicKey: 'pk_live_xxxx',
  baseUrl: 'https://api.koolbase.com',
  codePushChannel: 'stable', // or 'beta'
));

// After initialize() returns, bundle overrides are already active.
// Use SDK accessors as normal — they transparently return bundle values.
final timeout = Koolbase.configInt('api_timeout_ms', fallback: 3000);
final newCheckout = Koolbase.isEnabled('new_checkout_flow');
```

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

### Example server-side function handler

Source: https://docs.koolbase.com/sdk/functions-invoke

A sample Deno function handler that processes a request body and interacts with the database.

```javascript
export async function handler(ctx) {
  const { email, userId } = ctx.request.body

  if (!email) {
    return { error: 'email is required' }
  }

  // Insert a record, call an external API, send an email, etc.
  await ctx.db.insert('notifications', {
    user_id: userId,
    type: 'welcome',
    sent_at: new Date().toISOString(),
  })

  return { ok: true, message: 'Welcome email queued' }
}
```

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

### Build with Koolbase Engine

Source: https://docs.koolbase.com/code-push/quickstart

Use the Koolbase CLI to build release artifacts that support VM patching.

```bash
koolbase build android --release \
  --engine 3.32.0-koolbase.1 \
  --flutter-sdk /path/to/koolbase-engine
```

```bash
koolbase build ios --release \
  --engine 3.44.4-koolbase.4
```

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

### Denied Dependency Error Message

Source: https://docs.koolbase.com/functions/dependency-security

Example of the error message returned when a deployment includes a package from the platform-wide denylist.

```text
deploy blocked by denied dependencies: some_package@1.2.0
(known malicious — typosquat of some-package)
```

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

### Release checklist

Source: https://docs.koolbase.com/code-push/shipping-a-release

A summary checklist to ensure all steps for a successful patchable release have been completed.

```text
[ ]  Version bumped above the live build
       [ ]  koolbase release ... --project <id>
       [ ]  Output shows "registering releases" (NOT "NOT registered")
       [ ]  Recorded the rel_ IDs
       [ ]  jarsigner -verify  ->  jar verified
       [ ]  Uploaded outputs/koolbase/app-<flavor>-release.aab to the store
```