nodegres-api-client

TypeScript/JavaScript client for the Nodegres engine API.

Installation

npm install nodegres-api-client
# or
yarn add nodegres-api-client
# or
pnpm add nodegres-api-client

Quick Start

import { NodegresClient } from "nodegres-api-client";

const client = new NodegresClient({
  baseUrl: "http://localhost:8000/api",
});

// Login and store the token automatically
const { accessToken } = await client.auth.login({
  identity: "[email protected]",
  password: "secret",
});
client.setToken(accessToken);

// Query data
const users = await client.entities.findMany("public", "users", {
  where: { active: { _eq: true } },
  orderBy: { created_at: "desc" },
  limit: 20,
});

Configuration

const client = new NodegresClient({
  // Required: base URL of your Nodegres API
  baseUrl: "http://localhost:8000/api",

  // Optional: initial Bearer token
  token: "your-access-token",

  // Optional: API key (sent as x-api-key header)
  apiKey: "your-api-key",

  // Optional: called automatically on 401 — return a new token or null
  onTokenRefresh: async () => {
    const tokens = await client.auth.refreshToken(storedRefreshToken);
    return tokens.accessToken;
  },

  // Optional: extra headers on every request
  headers: { "x-tenant-id": "acme" },
});

Resources

All resources are available as properties on the client instance.

entities — Data CRUD

// findMany — with filtering, sorting, pagination
const result = await client.entities.findMany<User>("public", "users", {
  where: { role: { _eq: "admin" } },
  select: { id: true, email: true },
  orderBy: { created_at: "desc" },
  limit: 10,
  paginate: true, // returns PaginatedResponse<User>
});

// findOne
const user = await client.entities.findOne<User>("public", "users", {
  where: { id: { _eq: "123" } },
});

// aggregate
const stats = await client.entities.aggregate("public", "orders", {
  _count: true,
  _sum: { total: true },
  groupBy: ["status"],
});

// createOne / createMany
const newUser = await client.entities.createOne("public", "users", {
  email: "[email protected]",
});
const newUsers = await client.entities.createMany("public", "users", [
  { email: "[email protected]" },
]);

// updateOne / updateMany
const updated = await client.entities.updateOne(
  "public",
  "users",
  { name: "Alice" },
  {
    where: { id: { _eq: "123" } },
  },
);

// deleteOne / deleteMany
await client.entities.deleteOne("public", "users", {
  where: { id: { _eq: "123" } },
});

// transaction — all operations succeed or all roll back
const results = await client.entities.transaction([
  {
    action: "createOne",
    schema: "public",
    table: "orders",
    data: { total: 100 },
  },
  {
    action: "updateOne",
    schema: "public",
    table: "inventory",
    update: { qty: 49 },
    where: { id: { _eq: 1 } },
  },
]);

auth — Authentication

const { accessToken, refreshToken } = await client.auth.login({
  email,
  password,
});
await client.auth.register({ email, password, username });
const tokens = await client.auth.refreshToken(refreshToken);
const me = await client.auth.me();
await client.auth.updateProfile({ first_name: "Alice" });
await client.auth.changePassword({
  oldPassword,
  currentPassword,
  verifyPassword,
});

users — User Management

const users = await client.users.getMany();
const user = await client.users.getOne(userId);
const newUser = await client.users.create({ email, password, role_id });
await client.users.update(userId, { blocked: true });
await client.users.delete(userId);

roles — Role Management

const roles = await client.roles.getMany();
const role  = await client.roles.create({ name: 'editor', permissions: { ... } });
await client.roles.update(roleId, { name: 'content-editor' });
await client.roles.delete(roleId);

apiKeys — API Key Management

const keys = await client.apiKeys.getMany();
const newKey = await client.apiKeys.create({ role_id: roleId });
await client.apiKeys.update(keyId, { enabled: false });
await client.apiKeys.delete(keyId);

webhooks — Webhook Management

const hooks = await client.webhooks.getMany();
const hook = await client.webhooks.create({
  database_schema: "public",
  database_table: "orders",
  endpoint: "https://example.com/hook",
  events: ["createOne", "updateOne"],
  type: "post_exec",
  forward_auth_headers: false,
  graphql: false,
  rest: true,
});
await client.webhooks.delete(webhookId);

dataTriggers — Data Triggers

const triggers = await client.dataTriggers.getMany();
const trigger  = await client.dataTriggers.create({ ... });
await client.dataTriggers.delete(triggerId);

relations — Join Aliases

const relations = await client.relations.getMany();
const rel = await client.relations.create({
  alias: "userOrders",
  from_schema: "public",
  from_table: "users",
  from_column: ["id"],
  to_table: "orders",
  to_column: ["user_id"],
  type: "array",
});
await client.relations.delete(relationId);

datasources — External Datasources

const sources = await client.datasources.getMany();
await client.datasources.create({ name: 'legacy_db', type: 'postgres', settings: { ... } });

fileLibrary — File Library

const libraries = await client.fileLibrary.getLibraries();
const lib = await client.fileLibrary.createLibrary({
  name: "avatars",
  is_public: true,
});

// Upload a file
const formData = new FormData();
formData.append("file", blob, "photo.jpg");
const file = await client.fileLibrary.uploadFile(libraryId, formData);

const files = await client.fileLibrary.getFiles(libraryId);
await client.fileLibrary.deleteFile(libraryId, fileId);

settings — Engine Settings

const settings = await client.settings.getMany();
await client.settings.update(settingId, {
  config: { type: "boolean", value: true },
});
await client.settings.reload();

tableSettings — Per-Table Cache & Pagination

const all = await client.tableSettings.getMany();
const ts = await client.tableSettings.create({
  database_schema: "public",
  database_table: "products",
  settings: { cache: { ttl: 60 }, pagination: { defaultLimit: 25 } },
});
await client.tableSettings.update(tsId, {
  settings: { cache: { disabled: true } },
});

database — Schema Management

const schemas = await client.database.getSchemas();
const tables = await client.database.getTables("public");

await client.database.createTable("public", "products", [
  { name: "id", type: "uuid", primary: true },
  { name: "title", type: "varchar", length: 255, nullable: false },
  { name: "price", type: "numeric", nullable: true },
]);

await client.database.addColumn("public", "products", {
  name: "description",
  type: "text",
  nullable: true,
});

await client.database.dropColumn("public", "products", "description");
await client.database.dropTable("public", "products");

Filtering Reference

The where clause supports a rich set of operators:

where: {
  // Comparison
  age:    { _gt: 18 },
  status: { _in: ['active', 'pending'] },
  name:   { _ilike: '%alice%' },

  // Logical
  _and: [{ age: { _gte: 18 } }, { age: { _lte: 65 } }],
  _or:  [{ role: { _eq: 'admin' } }, { role: { _eq: 'editor' } }],
  _not: { blocked: { _eq: true } },

  // Null checks
  deleted_at: { _is: null },

  // JSON / array operators
  tags:     { _contains: ['typescript'] },
  metadata: { _key_exists: 'theme' },

  // Full-text search
  body: { _text_search: 'nodegres' },

  // PostGIS spatial
  location: { _st_d_within: someGeometry },
}

Error Handling

import { NodegresClient, NodegresHttpError } from "nodegres-api-client";

try {
  await client.entities.findOne("public", "users", {
    where: { id: { _eq: "bad" } },
  });
} catch (err) {
  if (err instanceof NodegresHttpError) {
    console.error(err.status, err.statusText, err.body);
  }
}

License

ISC