Configuration Details

This document helps you understand the Lovrabet SDK configuration mechanism, enabling you to get started quickly and use it efficiently.

Why Configuration is Needed?

When using Lovrabet SDK to access data, each dataset has a unique datasetCode (e.g., 8d2dcbae08b54bdd84c00be558ed48df). Without a configuration mechanism, your code would look like this:

// ❌ Without configuration: Need to manually fill appCode and datasetCode every call
const response = await fetch('/api/data', {
  body: JSON.stringify({
    appCode: 'my-app',
    datasetCode: '8d2dcbae08b54bdd84c00be558ed48df',
    // ...other parameters
  })
});

Configuration mechanism solves these pain points:

• ✅ Configure once, use everywhere - No need to fill appCode and datasetCode every time
• ✅ Cleaner code - client.models.dataset_xxx.filter() gets it done in one line
• ✅ Type safety - TypeScript intelligent hints reduce errors
• ✅ AI-friendly - datasetCode is globally unique, making it easy for AI tools to generate accurate code

---

Quick Start: CLI Auto-Configuration (Recommended)

The easiest way: Use Lovrabet CLI to generate configuration files with one click.

Haven't installed CLI yet?

Please follow the CLI Installation Guide to complete installation, then follow 5-Minute Quick Start to create a project.

Step 1: Pull Configuration

Execute in the project root directory:

lovrabet api pull

📖 For detailed parameter descriptions, please refer to CLI API Integration Documentation

The CLI will automatically pull your dataset information from the platform and generate the configuration file src/api/api.ts:

// src/api/api.ts (CLI auto-generated)
import { registerModels, type ModelsConfig } from "@lovrabet/sdk";

export const LOVRABET_MODELS_CONFIG: ModelsConfig = {
  appCode: "app-c4c89304",
  models: [
    {
      datasetCode: "71494bcba13f4ec7858abe90794183ad",
      tableName: "users",
      alias: "users",
      name: "User Management",
    },
    {
      datasetCode: "d26ed512e878461ca97d287a47606fd3",
      tableName: "orders",
      alias: "orders",
      name: "Order Management",
    },
  ],
} as const;

// Auto-register configuration
registerModels(LOVRABET_MODELS_CONFIG);

Step 2: Use Configuration

Create a client directly in business code and use it:

import { createClient } from "@lovrabet/sdk";
import "./api/api"; // Import configuration file, auto-registers

const client = createClient();

// Standard access method (recommended) - Use dataset_ prefix + datasetCode
const users = await client.models.dataset_71494bcba13f4ec7858abe90794183ad.filter();
const orders = await client.models.dataset_d26ed512e878461ca97d287a47606fd3.getOne("order-001");

💡 Why recommend standard method? datasetCode is globally unique, AI tools (like Claude, Cursor) won't create ambiguity when generating code.

Step 3 (Optional): Use Alias

If you find datasetCode too long to read, you can use the alias from the configuration:

// Alias method (syntactic sugar) - Use configured alias
const users = await client.models.users.filter();
const orders = await client.models.orders.getOne("order-001");

📌 Note: Alias is just a pointer, internally still uses datasetCode for access, all features are identical to the standard method.

---

Manual Configuration (For Special Scenarios)

If you don't use CLI, or need more flexible control, you can configure manually.

💡 Recommended approach: In most cases, it's recommended to use CLI auto-configuration to save time and effort.

Method 1: Pre-register Configuration

Use registerModels() to pre-register configuration, then create clients anywhere:

import { registerModels, createClient } from "@lovrabet/sdk";

// Register configuration (usually executed once at application entry)
registerModels({
  appCode: "my-app",
  models: [
    {
      datasetCode: "8d2dcbae08b54bdd84c00be558ed48df",
      tableName: "users",
      alias: "users",  // Optional
      name: "User Table",  // Optional
    },
    {
      datasetCode: "a1b2c3d4e5f6789012345678abcdef12",
      tableName: "orders",
      alias: "orders",
      name: "Order Table",
    },
  ],
});

// Create client anywhere (no need to pass configuration again)
const client = createClient();

// Standard access method
const users = await client.models.dataset_8d2dcbae08b54bdd84c00be558ed48df.filter();

Use Cases:

• Need to share the same configuration across multiple modules
• Want to separate configuration from business logic

Method 2: Pass Configuration Directly

Pass configuration object directly when creating client:

import { createClient } from "@lovrabet/sdk";

const client = createClient({
  appCode: "my-app",
  models: [
    {
      datasetCode: "8d2dcbae08b54bdd84c00be558ed48df",
      tableName: "users",
      alias: "users",
    },
  ],
});

// Standard access method
const users = await client.models.dataset_8d2dcbae08b54bdd84c00be558ed48df.filter();

// Alias access method (syntactic sugar)
const users = await client.models.users.filter();

Use Cases:

• Temporary testing or one-time use
• Need complete control over each client's configuration

---

Model Access Methods Explained

The SDK provides two ways to access models, with identical functionality:

Standard Method (Recommended)

Use dataset_ prefix + datasetCode to access:

// Format: client.models.dataset_[datasetCode]
const users = await client.models.dataset_8d2dcbae08b54bdd84c00be558ed48df.filter();
const order = await client.models.dataset_a1b2c3d4e5f6789012345678abcdef12.getOne("id");

Why Standard Method?

• ✅ Globally unique - datasetCode is the unique identifier for datasets, never conflicts
• ✅ AI-friendly - AI tools can precisely locate when generating code, reducing hallucinations
• ✅ No configuration needed - Can access directly even without pre-configuring models

Alias Method (Syntactic Sugar)

If alias is defined in the configuration, you can access with a shorter name:

// Format: client.models.[alias]
const users = await client.models.users.filter();
const order = await client.models.orders.getOne("id");

About Alias:

• 📌 Just syntactic sugar - alias is just a pointer, internally still uses datasetCode
• 📌 Functionally identical - All API methods and type hints are the same as standard method
• 📌 Improves readability - Convenient for human developers to quickly read code

Comparison Summary

Method	Format	Characteristics
Standard Method	client.models.dataset_[datasetCode]	Globally unique, AI-friendly, recommended
Alias Method	client.models.[alias]	Syntactic sugar, human-friendly, requires alias configuration

---

Advanced Configuration

Multi-Project Configuration Management

If you're developing multiple projects simultaneously, you can register multiple configurations and switch by name:

import { registerModels, createClient } from "@lovrabet/sdk";

// Register multiple project configurations
registerModels(CONFIG_A, "project-a");
registerModels(CONFIG_B, "project-b");

// Create clients for different projects by name
const clientA = createClient("project-a");
const clientB = createClient("project-b");

ClientConfig Extended Options

You can pass additional configuration when creating a client:

const client = createClient({
  apiConfigName: "default",     // Which pre-registered configuration to use
  token: "your-auth-token",     // User authentication Token
  accessKey: "your-access-key", // OpenAPI access key
  secretKey: "your-secret-key", // OpenAPI secret key
  serverUrl: "https://custom.api.com", // Custom server address
  options: {
    timeout: 30000,             // Request timeout (milliseconds)
    onError: (error) => {       // Error callback
      console.error("API Error:", error);
    },
    onRedirectToLogin: () => {  // Login expiration callback
      window.location.href = "/login";
    },
  },
});

Dynamically Add Models

Dynamically add new models at runtime:

// Dynamically add model
client.addModel({
  datasetCode: "f7e6d5c4b3a2901234567890fedcba98",
  tableName: "products",
  alias: "products",
  name: "Product Management",
});

// Immediately available
const products = await client.models.dataset_f7e6d5c4b3a2901234567890fedcba98.filter();
// Or use alias
const products = await client.models.products.filter();

Get Model Information

// Get all configured model details
const details = client.getModelListDetails();
// Returns: [{ datasetCode: '...', alias: 'users', name: 'User Table' }, ...]

// Get all registered configuration names
import { getRegisteredConfigNames } from "@lovrabet/sdk";
console.log(getRegisteredConfigNames()); // ['default', 'project-a', 'project-b']

---

Configuration Structure Reference

ModelsConfig

interface ModelsConfig {
  appCode: string;           // Application code
  models: Array<{
    datasetCode: string;     // Dataset code (required, unique identifier)
    tableName: string;       // Data table name (required)
    alias?: string;          // Model alias (optional, for client.models.alias access)
    name?: string;           // Display name (optional, for UI display)
  }>;
}

ClientConfig

interface ClientConfig {
  apiConfigName?: string;    // Pre-registered configuration name
  serverUrl?: string;        // Custom server address
  token?: string;            // User authentication Token
  accessKey?: string;        // OpenAPI access key
  secretKey?: string;        // OpenAPI secret key
  options?: {
    timeout?: number;        // Request timeout (milliseconds)
    onError?: (error: any) => void;
    onRedirectToLogin?: () => void;
  };
}

---

Frequently Asked Questions

Q: What's the difference between CLI-generated configuration and manual configuration?

Functionally identical. CLI just helps you automatically generate configuration code, saving you the trouble of manually finding datasetCode.

👉 How to Use CLI to Generate Configuration

Q: Which should I use, standard method or alias method?

• AI-assisted development (Cursor, Claude, etc.) → Recommend standard method dataset_xxx, globally unique won't confuse
• Pure manual development → Can use alias method users, more readable
• Mixed scenarios → Both can be used, functionally identical

Q: What's the difference between alias and name?

• alias: Used to access models in code, e.g., client.models.users
• name: Used for UI display, e.g., model list in admin backend

Q: How to migrate old version configuration?

v1.2.0 is fully backward compatible with old object format configuration, no immediate migration needed. But it's recommended to use array format in new projects:

// Old format (still supported)
registerModels({
  appCode: "my-app",
  models: {
    users: { tableName: "users", datasetCode: "..." },
  },
});

// New format (recommended)
registerModels({
  appCode: "my-app",
  models: [
    { datasetCode: "...", tableName: "users", alias: "users" },
  ],
});

---

Next Steps

CLI Related:

• 🛠️ CLI Installation Guide - Install Lovrabet CLI
• 🚀 5-Minute Quick Start - Create project from scratch
• 📡 API Integration - Detailed lovrabet api pull usage

SDK Advanced:

• 🔐 Authentication Configuration - Configure Token or OpenAPI authentication
• 📊 API Usage Guide - Deep dive into CRUD operations
• 🚀 Advanced Features - Filter API, SQL API, etc.