Ask questions in natural language to your MySQL, MariaDB, or PostgreSQL databases directly from your JavaScript and TypeScript applications (Node.js, Bun, Deno, and modern browser runtimes).

Installation

npm install @easysql/client
# or
bun add @easysql/client
# or
pnpm add @easysql/client

Quick Start

import { createEasySQLClient } from "@easysql/client";

const api = createEasySQLClient({
  baseUrl: "https://api.easysql.net",
  accessToken: "your-access-token",
});

Authentication

Authentication is OIDC-only — there is no password login endpoint. Obtain tokens from the sign-in flow (oidcStart / oidcCallback / oidcComplete), or rotate an existing pair with refresh:

// Rotate an existing refresh token into a fresh access token
const api = createEasySQLClient({ baseUrl: "https://api.easysql.net" });

const { data: tokens, error } = await api.refresh({
  refresh_token: "your-refresh-token",
});
if (error) throw new Error(`Refresh failed: ${JSON.stringify(error)}`);

const authApi = createEasySQLClient({
  baseUrl: "https://api.easysql.net",
  accessToken: tokens.access_token,
});
const { data: user } = await authApi.me();

Machine clients authenticate with an API key (see createApiKey) by sending it as the bearer token.

Running Natural Language Queries

The API generates the SQL; a client runtime executes it locally against the customer database (credentials never reach the API) and renders the answer and chart on its side — the API never receives customer data.

const { data: query } = await api.createQuery({
  connector_id: "conn_abc123",
  question: "How many users signed up this month?",
});

console.log(query?.sql_generated);        // Generated SQL
console.log(query?.needs_local_execution); // true — run it locally

// Execute locally with @easysql/connector-* and render the answer/chart here.

// List recent query history (cursor pagination)
const { data: history } = await api.listQueries({ limit: 10 });

See samples/ for runnable, end-to-end examples.

Managing Database Connectors

// Create a connector (schema-only: introspect locally, push only the schema)
const { data: connector } = await api.createConnector({
  name: "Production DB",
  type: "mysql",
  schema: [
    {
      name: "users",
      columns: [
        { name: "id", type: "int", nullable: false, primary_key: true },
        { name: "email", type: "varchar", nullable: false },
      ],
    },
  ],
});

// List connectors
const { data: connectors } = await api.listConnectors();

// Get connector details
const { data: conn } = await api.getConnector({ connector_id: "abc-123" });

// Update a connector
const { data: updated } = await api.updateConnector(
  { name: "Staging DB" },
  { path: { connector_id: "abc-123" } },
);

// Delete a connector
await api.deleteConnector({ connector_id: "abc-123" });

Dashboard & Analytics

const { data: stats } = await api.dashboardStats();

API Overview

| Module | Available Methods | |---|---| | Auth | refresh, me, updateMe, deleteMe, logout, oidcStart, oidcCallback, oidcComplete | | API keys | listApiKeys, createApiKey, deleteApiKey | | Queries | createQuery, listQueries, getQuery | | Connectors | listConnectors, createConnector, getConnector, updateConnector, deleteConnector, syncConnector, getConnectorSchema, getSuggestions, autocomplete | | Feedback | createFeedback | | Billing | getPlan, getUsage, checkout, portal | | Analytics | listAnalyticsQueries, getFlags | | Dashboard | dashboardStats | | Health | health, healthHealth |

Development & Contributing

Contributions are welcome! Please read our Contributing Guidelines for details on the development workflow, testing, and pull request process.

To run tests and build locally:

cp .env.example .env                 # configure API URL
make install                          # install dependencies
make generate                         # download OpenAPI spec -> regenerate client
make typecheck                        # run TypeScript checks
make test                             # run test suite
make build                            # compile to dist/

License

This project is open source and licensed under the MIT License.

Maintained by Clearsoft.