@lotics/cli 0.1.0

package/README.md

@@ -0,0 +1,65 @@
+# @lotics/cli
+
+CLI and SDK for AI agents to interact with Lotics.
+
+## Install
+
+```bash
+npm install -g @lotics/cli
+```
+
+## Update
+
+```bash
+npm install -g @lotics/cli@latest
+```
+
+The CLI checks for updates once per day and prompts when a new version is available.
+
+## CLI
+
+```bash
+# 1. Authenticate
+lotics auth
+
+# 2. Discover tools
+lotics tools                    # list all tool names
+lotics tools query_records      # show description + input schema
+
+# 3. Execute
+lotics run query_tables '{}'
+lotics run query_records '{"table_id":"tbl_...","field_keys":["name"]}'
+lotics run query_records --json '{"table_id":"tbl_..."}'
+
+# Pipe args via stdin
+echo '{"table_id":"tbl_..."}' | lotics run query_records
+
+# Upload a file
+lotics upload ./report.pdf
+lotics upload ./photo.jpg --as cover.jpg
+
+# Generate a file, then download it
+lotics run generate_excel_from_template '{"..."}' --json
+# → {"file_id":"fil_...","url":"...","filename":"report.xlsx",...}
+lotics download fil_... -o ./reports/
+
+# CI / non-interactive
+LOTICS_API_KEY=ltk_... lotics run query_tables '{}'
+```
+
+## SDK
+
+```typescript
+import { LoticsClient } from "@lotics/cli";
+
+const client = new LoticsClient({
+  apiKey: "ltk_...",
+  baseUrl: "https://api.lotics.com",
+});
+
+const { result } = await client.execute("query_tables", {});
+const upload = await client.uploadFile("./report.pdf");
+await client.downloadFile(url, "./output.xlsx");
+const { tools } = await client.listTools();
+const info = await client.getTool("query_records");
+```

package/dist/src/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/src/cli.js

@@ -0,0 +1,277 @@
+#!/usr/bin/env node
+import readline from "node:readline";
+import { LoticsClient } from "./client.js";
+import { resolveAuth, loadConfig, saveConfig, deleteConfig, getConfigPath, checkForUpdate } from "./config.js";
+import { VERSION } from "./version.js";
+function printHelp() {
+    console.log(`Lotics CLI v${VERSION} — AI agent interface for Lotics
+
+Lotics is an AI-powered operations platform for structured data,
+document generation, automations, and knowledge management.
+
+COMMANDS
+  lotics auth                    Save API key (interactive)
+  lotics logout                  Remove saved credentials
+  lotics tools                   List all available tools
+  lotics tools <name>            Show tool description and input schema
+  lotics run <tool> '<json>'     Execute a tool
+  lotics run <tool> --json       Full JSON output instead of compact text
+  lotics upload <file>           Upload a local file
+  lotics download <file_id>      Download a file by ID
+
+FLAGS
+  --json             Full JSON output
+  --timeout <ms>     Timeout for tool execution (default: 60000)
+  -o <path>          Output dir for downloads
+  --as <name>        Override upload filename
+  --api-key <key>    API key (for CI/agents)
+  --api-url <url>    API URL override
+  --version          Show version
+
+WORKFLOW
+  1. lotics auth                 Authenticate once
+  2. lotics tools                See what's available
+  3. lotics tools <name>         Read the schema before calling
+  4. lotics run <tool> '<json>'  Execute with correct args
+
+ENVIRONMENT
+  LOTICS_API_KEY    API key (overrides saved config)
+  LOTICS_API_URL    API URL (overrides saved config)`);
+}
+function parseArgs(argv) {
+    const flags = {
+        json: false,
+        timeout: undefined,
+        output: undefined,
+        as: undefined,
+        apiKey: undefined,
+        apiUrl: undefined,
+        version: false,
+        help: false,
+    };
+    let command;
+    let subcommand;
+    let toolArgs;
+    let i = 0;
+    while (i < argv.length) {
+        const arg = argv[i];
+        switch (arg) {
+            case "--json":
+                flags.json = true;
+                break;
+            case "--timeout":
+                flags.timeout = parseInt(argv[++i], 10);
+                break;
+            case "--output":
+            case "-o":
+                flags.output = argv[++i];
+                break;
+            case "--as":
+                flags.as = argv[++i];
+                break;
+            case "--api-key":
+                flags.apiKey = argv[++i];
+                break;
+            case "--api-url":
+                flags.apiUrl = argv[++i];
+                break;
+            case "--version":
+            case "-v":
+                flags.version = true;
+                break;
+            case "--help":
+            case "-h":
+                flags.help = true;
+                break;
+            default:
+                if (!command) {
+                    command = arg;
+                }
+                else if (!subcommand) {
+                    subcommand = arg;
+                }
+                else if (!toolArgs) {
+                    toolArgs = arg;
+                }
+                break;
+        }
+        i++;
+    }
+    return { command, subcommand, toolArgs, flags };
+}
+function readStdin() {
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        process.stdin.on("data", (chunk) => chunks.push(chunk));
+        process.stdin.on("end", () => resolve(Buffer.concat(chunks).toString("utf-8").trim()));
+        process.stdin.on("error", reject);
+    });
+}
+function prompt(question) {
+    const rl = readline.createInterface({
+        input: process.stdin,
+        output: process.stderr,
+    });
+    return new Promise((resolve) => {
+        rl.question(question, (answer) => {
+            rl.close();
+            resolve(answer.trim());
+        });
+    });
+}
+async function handleAuth(flags) {
+    const apiKey = await prompt("Enter your API key: ");
+    if (!apiKey) {
+        console.error("No API key provided.");
+        process.exit(1);
+    }
+    const apiUrlInput = flags.apiUrl ?? (await prompt("API URL (default: https://api.lotics.com): "));
+    const apiUrl = apiUrlInput || "https://api.lotics.com";
+    const client = new LoticsClient({ apiKey, baseUrl: apiUrl });
+    try {
+        await client.listTools();
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        console.error(`Authentication failed: ${message}`);
+        process.exit(1);
+    }
+    const existing = loadConfig() ?? {};
+    saveConfig({ ...existing, api_key: apiKey, api_url: apiUrl });
+    console.error(`Authenticated. Config saved to ${getConfigPath()}`);
+}
+function requireClient(flags) {
+    const auth = resolveAuth(flags);
+    if (!auth) {
+        console.error('Not authenticated. Run "lotics auth" or set LOTICS_API_KEY.');
+        process.exit(1);
+    }
+    return new LoticsClient({ apiKey: auth.apiKey, baseUrl: auth.apiUrl });
+}
+async function main() {
+    const { command, subcommand, toolArgs, flags } = parseArgs(process.argv.slice(2));
+    if (flags.help || (!command && !flags.version)) {
+        printHelp();
+        return;
+    }
+    if (flags.version) {
+        console.log(VERSION);
+        return;
+    }
+    // --- Commands that don't require auth ---
+    if (command === "auth") {
+        await handleAuth(flags);
+        return;
+    }
+    if (command === "logout") {
+        deleteConfig();
+        console.error("Logged out. Credentials removed.");
+        return;
+    }
+    // --- Validate command before auth ---
+    if (command !== "tools" && command !== "upload" && command !== "run" && command !== "download") {
+        console.error(`Unknown command: ${command}`);
+        console.error('Run "lotics --help" for usage.');
+        process.exit(1);
+    }
+    if (command === "run" && !subcommand) {
+        console.error('Usage: lotics run <tool> \'<json_args>\'');
+        console.error('Run "lotics tools" to see available tools.');
+        process.exit(1);
+    }
+    if (command === "upload" && !subcommand) {
+        console.error('Usage: lotics upload <file> [--as <name>]');
+        console.error('Uploads a local file and returns its file_id.');
+        process.exit(1);
+    }
+    if (command === "download" && !subcommand) {
+        console.error('Usage: lotics download <file_id> [-o <dir>]');
+        console.error('File IDs come from upload results or generate_* tool output (--json).');
+        process.exit(1);
+    }
+    const client = requireClient(flags);
+    // lotics tools / lotics tools <name>
+    if (command === "tools") {
+        if (subcommand) {
+            const info = await client.getTool(subcommand);
+            console.log(JSON.stringify(info, null, 2));
+        }
+        else {
+            const { categories } = await client.listTools();
+            for (const [category, names] of Object.entries(categories)) {
+                console.log(`\n${category}`);
+                console.log(`  ${names.join("  ")}`);
+            }
+            console.log("");
+        }
+        return;
+    }
+    // lotics upload <file> [--as <name>]
+    if (command === "upload") {
+        const upload = await client.uploadFile(subcommand, {
+            filename: flags.as,
+        });
+        if (upload.errors.length > 0) {
+            console.error(`Upload failed: ${upload.errors[0].error}`);
+            process.exit(1);
+        }
+        console.log(JSON.stringify(upload.files[0], null, 2));
+        return;
+    }
+    // lotics download <file_id> [-o <path>]
+    if (command === "download") {
+        const { path: filePath, filename } = await client.downloadFileById(subcommand, flags.output);
+        console.error(`Downloaded: ${filePath} (${filename})`);
+        return;
+    }
+    // lotics run <tool> [json_args]
+    if (command === "run") {
+        const toolName = subcommand;
+        let rawArgs = toolArgs;
+        if (!rawArgs && !process.stdin.isTTY) {
+            rawArgs = await readStdin();
+        }
+        let args = {};
+        if (rawArgs) {
+            try {
+                args = JSON.parse(rawArgs);
+            }
+            catch {
+                console.error(`Invalid JSON: ${rawArgs}`);
+                process.exit(1);
+            }
+        }
+        const format = flags.json ? "json" : "text";
+        const timeoutMs = flags.timeout ?? 60000;
+        const result = await client.execute(toolName, args, { format, timeoutMs });
+        if (result.error) {
+            console.error(result.error);
+            console.error(`\nHint: run "lotics tools ${toolName}" to see the expected input schema.`);
+            process.exit(1);
+        }
+        if (format === "text" && result.model_output) {
+            console.log(result.model_output);
+        }
+        else {
+            console.log(JSON.stringify(result.result, null, 2));
+        }
+        return;
+    }
+}
+main()
+    .then(() => checkForUpdate(VERSION))
+    .catch((error) => {
+    const message = error instanceof Error ? error.message : String(error);
+    if (message.includes("fetch failed") || message.includes("ECONNREFUSED")) {
+        console.error("Could not connect to the Lotics API.");
+        console.error('Check your API URL or run "lotics auth" to reconfigure.');
+    }
+    else if (message.includes("ENOENT")) {
+        const pathMatch = message.match(/open '([^']+)'/);
+        console.error(`File not found: ${pathMatch?.[1] ?? message}`);
+    }
+    else {
+        console.error(message);
+    }
+    process.exit(1);
+});

package/dist/src/client.d.ts

@@ -0,0 +1,51 @@
+export interface LoticsClientOptions {
+    apiKey: string;
+    baseUrl?: string;
+}
+export interface ToolExecuteResult {
+    result: unknown;
+    model_output?: string;
+    error?: string;
+}
+export interface ToolInfo {
+    name: string;
+    description: string;
+    input_schema: unknown;
+}
+export interface FileUploadResult {
+    files: Array<{
+        id: string;
+        filename: string;
+        mime_type: string;
+    }>;
+    errors: Array<{
+        filename: string;
+        error: string;
+    }>;
+}
+export declare class LoticsClient {
+    private apiKey;
+    private baseUrl;
+    constructor(options: LoticsClientOptions);
+    private throwResponseError;
+    private request;
+    listTools(): Promise<{
+        tools: Array<{
+            name: string;
+        }>;
+        categories: Record<string, string[]>;
+    }>;
+    getTool(name: string): Promise<ToolInfo>;
+    execute(tool: string, args: Record<string, unknown>, options?: {
+        format?: "json" | "text";
+        timeoutMs?: number;
+    }): Promise<ToolExecuteResult>;
+    downloadFile(url: string, outputPath: string): Promise<string>;
+    downloadFileById(fileId: string, outputDir?: string): Promise<{
+        path: string;
+        filename: string;
+    }>;
+    uploadFile(filePath: string, options?: {
+        filename?: string;
+    }): Promise<FileUploadResult>;
+}

package/dist/src/client.js

@@ -0,0 +1,137 @@
+import fs from "node:fs";
+import path from "node:path";
+const MIME_MAP = {
+    ".jpg": "image/jpeg",
+    ".jpeg": "image/jpeg",
+    ".png": "image/png",
+    ".gif": "image/gif",
+    ".webp": "image/webp",
+    ".svg": "image/svg+xml",
+    ".pdf": "application/pdf",
+    ".csv": "text/csv",
+    ".xlsx": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+    ".docx": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+    ".txt": "text/plain",
+    ".json": "application/json",
+    ".html": "text/html",
+    ".xml": "application/xml",
+    ".zip": "application/zip",
+};
+function getMimeType(filename) {
+    const ext = path.extname(filename).toLowerCase();
+    return MIME_MAP[ext] ?? "application/octet-stream";
+}
+export class LoticsClient {
+    apiKey;
+    baseUrl;
+    constructor(options) {
+        this.apiKey = options.apiKey;
+        this.baseUrl = (options.baseUrl ?? "https://api.lotics.com").replace(/\/$/, "");
+    }
+    async throwResponseError(response) {
+        const text = await response.text();
+        let message;
+        try {
+            const json = JSON.parse(text);
+            message = json.message ?? text;
+        }
+        catch {
+            message = text;
+        }
+        throw new Error(`${response.status}: ${message}`);
+    }
+    async request(method, path, body) {
+        const url = `${this.baseUrl}${path}`;
+        const headers = {
+            "x-api-key": this.apiKey,
+        };
+        const init = { method, headers };
+        if (body !== undefined) {
+            headers["Content-Type"] = "application/json";
+            init.body = JSON.stringify(body);
+        }
+        const response = await fetch(url, init);
+        if (!response.ok)
+            await this.throwResponseError(response);
+        return response.json();
+    }
+    async listTools() {
+        return this.request("GET", "/v1/tools");
+    }
+    async getTool(name) {
+        return this.request("GET", `/v1/tools/${encodeURIComponent(name)}`);
+    }
+    async execute(tool, args, options) {
+        const body = { tool, args, format: options?.format ?? "text" };
+        if (options?.timeoutMs) {
+            const controller = new AbortController();
+            const timeout = setTimeout(() => controller.abort(), options.timeoutMs);
+            try {
+                const url = `${this.baseUrl}/v1/tools/execute`;
+                const response = await fetch(url, {
+                    method: "POST",
+                    headers: { "x-api-key": this.apiKey, "Content-Type": "application/json" },
+                    body: JSON.stringify(body),
+                    signal: controller.signal,
+                });
+                if (!response.ok)
+                    await this.throwResponseError(response);
+                return response.json();
+            }
+            catch (error) {
+                if (error instanceof Error && error.name === "AbortError") {
+                    throw new Error(`Tool execution timed out after ${options.timeoutMs}ms`);
+                }
+                throw error;
+            }
+            finally {
+                clearTimeout(timeout);
+            }
+        }
+        return this.request("POST", "/v1/tools/execute", body);
+    }
+    async downloadFile(url, outputPath) {
+        const response = await fetch(url);
+        if (!response.ok) {
+            throw new Error(`${response.status}: Failed to download file`);
+        }
+        const buffer = Buffer.from(await response.arrayBuffer());
+        const absolutePath = path.resolve(outputPath);
+        await fs.promises.writeFile(absolutePath, buffer);
+        return absolutePath;
+    }
+    async downloadFileById(fileId, outputDir) {
+        const url = `${this.baseUrl}/v1/files/${encodeURIComponent(fileId)}/download`;
+        const response = await fetch(url, {
+            headers: { "x-api-key": this.apiKey },
+        });
+        if (!response.ok)
+            await this.throwResponseError(response);
+        const disposition = response.headers.get("content-disposition") ?? "";
+        const match = disposition.match(/filename="?([^";\n]+)"?/);
+        const filename = match?.[1] ?? fileId;
+        const buffer = Buffer.from(await response.arrayBuffer());
+        const dir = outputDir ? path.resolve(outputDir) : process.cwd();
+        const absolutePath = path.join(dir, filename);
+        await fs.promises.writeFile(absolutePath, buffer);
+        return { path: absolutePath, filename };
+    }
+    async uploadFile(filePath, options) {
+        const absolutePath = path.resolve(filePath);
+        const buffer = await fs.promises.readFile(absolutePath);
+        const filename = options?.filename ?? path.basename(absolutePath);
+        const mimeType = getMimeType(filename);
+        const blob = new Blob([buffer], { type: mimeType });
+        const formData = new FormData();
+        formData.append("file", blob, filename);
+        const url = `${this.baseUrl}/v1/files`;
+        const response = await fetch(url, {
+            method: "POST",
+            headers: { "x-api-key": this.apiKey },
+            body: formData,
+        });
+        if (!response.ok)
+            await this.throwResponseError(response);
+        return response.json();
+    }
+}

package/dist/src/config.d.ts

@@ -0,0 +1,27 @@
+export interface LoticsConfig {
+    api_key?: string;
+    api_url?: string;
+    last_update_check?: number;
+    latest_version?: string;
+}
+export declare function loadConfig(): LoticsConfig | null;
+export declare function saveConfig(config: LoticsConfig): void;
+export declare function deleteConfig(): void;
+export declare function getConfigPath(): string;
+/**
+ * Check for a newer CLI version. Synchronous — prints a warning to stderr
+ * if the cached latest version is newer than current. Kicks off a background
+ * fetch if the cache is stale (result is written to config for next run).
+ */
+export declare function checkForUpdate(currentVersion: string): void;
+/**
+ * Resolve API key and URL from flags, env vars, or config file.
+ * Priority: flag > env > config file > default.
+ */
+export declare function resolveAuth(flags: {
+    apiKey?: string;
+    apiUrl?: string;
+}): {
+    apiKey: string;
+    apiUrl: string;
+} | null;

package/dist/src/config.js

@@ -0,0 +1,91 @@
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+const CONFIG_DIR = path.join(os.homedir(), ".lotics");
+const CONFIG_FILE = path.join(CONFIG_DIR, "config.json");
+export function loadConfig() {
+    try {
+        const raw = fs.readFileSync(CONFIG_FILE, "utf-8");
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+export function saveConfig(config) {
+    fs.mkdirSync(CONFIG_DIR, { recursive: true });
+    fs.writeFileSync(CONFIG_FILE, JSON.stringify(config, null, 2) + "\n", "utf-8");
+}
+export function deleteConfig() {
+    try {
+        fs.unlinkSync(CONFIG_FILE);
+    }
+    catch {
+        // Already deleted or never existed
+    }
+}
+export function getConfigPath() {
+    return CONFIG_FILE;
+}
+const UPDATE_CHECK_INTERVAL_MS = 24 * 60 * 60 * 1000; // 24 hours
+/**
+ * Check for a newer CLI version. Synchronous — prints a warning to stderr
+ * if the cached latest version is newer than current. Kicks off a background
+ * fetch if the cache is stale (result is written to config for next run).
+ */
+export function checkForUpdate(currentVersion) {
+    const config = loadConfig();
+    const lastCheck = config?.last_update_check ?? 0;
+    if (Date.now() - lastCheck < UPDATE_CHECK_INTERVAL_MS) {
+        if (config?.latest_version && config.latest_version !== currentVersion) {
+            printUpdateWarning(currentVersion, config.latest_version);
+        }
+        return;
+    }
+    // Cache is stale — fetch in background, don't block exit
+    fetchLatestVersion().then((latest) => {
+        if (!latest)
+            return;
+        const existing = loadConfig() ?? {};
+        saveConfig({ ...existing, last_update_check: Date.now(), latest_version: latest });
+    }).catch(() => { });
+}
+async function fetchLatestVersion() {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), 3000);
+    timeout.unref();
+    try {
+        const response = await fetch("https://registry.npmjs.org/@lotics/cli/latest", {
+            signal: controller.signal,
+        });
+        if (!response.ok)
+            return null;
+        const data = (await response.json());
+        return data.version ?? null;
+    }
+    catch {
+        return null;
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+}
+function printUpdateWarning(current, latest) {
+    console.error(`\nUpdate available: ${current} → ${latest}`);
+    console.error(`Run: npm i -g @lotics/cli\n`);
+}
+/**
+ * Resolve API key and URL from flags, env vars, or config file.
+ * Priority: flag > env > config file > default.
+ */
+export function resolveAuth(flags) {
+    const config = loadConfig();
+    const apiKey = flags.apiKey ?? process.env.LOTICS_API_KEY ?? config?.api_key;
+    if (!apiKey)
+        return null;
+    const apiUrl = flags.apiUrl ??
+        process.env.LOTICS_API_URL ??
+        config?.api_url ??
+        "https://api.lotics.com";
+    return { apiKey, apiUrl };
+}

package/dist/src/version.d.ts

@@ -0,0 +1 @@
+export declare const VERSION = "0.1.0";

package/dist/src/version.js

@@ -0,0 +1 @@
+export const VERSION = "0.1.0";

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@lotics/cli",
+  "version": "0.1.0",
+  "description": "Lotics SDK and CLI for AI agents",
+  "type": "module",
+  "bin": {
+    "lotics": "./dist/src/cli.js"
+  },
+  "exports": {
+    ".": "./dist/src/client.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsgo",
+    "typecheck": "tsgo --noEmit",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "lotics",
+    "sdk",
+    "cli",
+    "ai-agent"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/lotics/lotics.git",
+    "directory": "packages/sdk"
+  }
+}