@ird.sh/node-client

Node.js client for ird.sh - an encrypted log-driven database.

Overview

This library provides a client for the ird.sh API, implementing an encrypted log-driven database pattern where:

1. All database operations are serialized as DBLog actions (schema, set, delete, migrate)
2. Actions are encrypted and stored on the server as chain log entries
3. Clients sync chain logs and replay them locally to construct a SQLite database

Installation

npm install @ird.sh/node-client

Quick Start

import { createIrdClient, generateKeyPair } from "@ird.sh/node-client";

// Generate or load your key pair
const keyPair = generateKeyPair();

// Create the client
const client = createIrdClient({
  apiBaseUrl: "https://api.ird.sh",
  databasePath: "./myapp.db",
  credentials: {
    publicKey: keyPair.publicKey,
    privateKey: keyPair.privateKey,
  },
});

// Initialize (syncs chain logs and opens database)
await client.initialize();

// Create a table
await client.db.createTable("todos", {
  id: "TEXT PRIMARY KEY",
  title: "TEXT NOT NULL",
  completed: "INTEGER DEFAULT 0",
  createdAt: "INTEGER NOT NULL",
});

// Insert data
await client.db.set("todos", "todo-1", {
  title: { type: "string", value: "Learn ird.sh" },
  completed: { type: "bool", value: false },
  createdAt: { type: "int", value: Date.now() },
});

// Query data
const todos = client.db.queryAll("todos");

// Cleanup when done
client.cleanup();

Components

Cryptograph

Ethereum-style cryptography using secp256k1 (viem + eciesjs compatible):

import {
  generateKeyPair,
  signMessage,
  encryptForPublicKey,
  decryptToString,
} from "@ird.sh/node-client";

const keyPair = generateKeyPair();
const signed = await signMessage("Hello", keyPair.privateKey);
const encrypted = encryptForPublicKey("Secret", keyPair.publicKey);
const decrypted = decryptToString(encrypted, keyPair.privateKey);

API Client

HTTP client for the ird.sh REST API with automatic encryption/decryption:

import { createAPIClient } from "@ird.sh/node-client";

const api = createAPIClient({ baseUrl: "https://api.ird.sh" });
api.setCredentials(publicKey, privateKey);

// KV Store
await api.setKvItem("mykey", "myvalue");
const item = await api.getKvItem("mykey");

// Lists
await api.pushListItem("mylist", "item value");
const items = await api.getListItems("mylist");

// Chain Logs
const { logs, hasMore } = await api.listChainLogs(0, 100);
await api.appendChainLog({ index, prevHash, content, nonce, hash, signature });

DBLog Service

High-level interface for the log-driven database:

// Use batch for multiple operations
await db.batch((batch) => {
  batch.createTable("users", {
    id: "TEXT PRIMARY KEY",
    name: "TEXT NOT NULL",
  });
  batch.set("users", "user-1", {
    name: { type: "string", value: "Alice" },
  });
});

// Query data
const users = db.queryAll("users");
const user = db.get("users", "user-1");
const active = db.query("users", "active = 1");

// Migrations
await db.migrate("users", 2, [
  { op: "add_column", column: "avatar", columnType: "TEXT" },
]);

DBLogValue Types

import {
  DBLogNull,
  DBLogBool,
  DBLogInt,
  DBLogDouble,
  DBLogString,
  DBLogArray,
  DBLogObject,
  toDBLogValue,
} from "@ird.sh/node-client";

const data = {
  name: DBLogString("test"),
  count: DBLogInt(5),
  active: DBLogBool(true),
  tags: DBLogArray([DBLogString("a"), DBLogString("b")]),
};

// Or convert from plain JS
const value = toDBLogValue({ name: "test", count: 5 });

License

MIT