@debros/network-ts-sdk 0.1.4

package/src/db/client.ts

@@ -0,0 +1,126 @@
+import { HttpClient } from "../core/http";
+import { QueryBuilder } from "./qb";
+import { Repository } from "./repository";
+import {
+  QueryResponse,
+  TransactionOp,
+  TransactionRequest,
+  Entity,
+  FindOptions,
+} from "./types";
+
+export class DBClient {
+  private httpClient: HttpClient;
+
+  constructor(httpClient: HttpClient) {
+    this.httpClient = httpClient;
+  }
+
+  /**
+   * Execute a write/DDL SQL statement.
+   */
+  async exec(
+    sql: string,
+    args: any[] = []
+  ): Promise<{ rows_affected: number; last_insert_id?: number }> {
+    return this.httpClient.post("/v1/rqlite/exec", { sql, args });
+  }
+
+  /**
+   * Execute a SELECT query.
+   */
+  async query<T = any>(sql: string, args: any[] = []): Promise<T[]> {
+    const response = await this.httpClient.post<QueryResponse>(
+      "/v1/rqlite/query",
+      { sql, args }
+    );
+    return response.items || [];
+  }
+
+  /**
+   * Find rows with map-based criteria.
+   */
+  async find<T = any>(
+    table: string,
+    criteria: Record<string, any> = {},
+    options: FindOptions = {}
+  ): Promise<T[]> {
+    const response = await this.httpClient.post<QueryResponse>(
+      "/v1/rqlite/find",
+      {
+        table,
+        criteria,
+        options,
+      }
+    );
+    return response.items || [];
+  }
+
+  /**
+   * Find a single row with map-based criteria.
+   */
+  async findOne<T = any>(
+    table: string,
+    criteria: Record<string, any>
+  ): Promise<T | null> {
+    return this.httpClient.post<T | null>("/v1/rqlite/find-one", {
+      table,
+      criteria,
+    });
+  }
+
+  /**
+   * Create a fluent QueryBuilder for complex SELECT queries.
+   */
+  createQueryBuilder(table: string): QueryBuilder {
+    return new QueryBuilder(this.httpClient, table);
+  }
+
+  /**
+   * Create a Repository for entity-based operations.
+   */
+  repository<T extends Record<string, any>>(
+    tableName: string,
+    primaryKey = "id"
+  ): Repository<T> {
+    return new Repository(this.httpClient, tableName, primaryKey);
+  }
+
+  /**
+   * Execute multiple operations atomically.
+   */
+  async transaction(
+    ops: TransactionOp[],
+    returnResults = true
+  ): Promise<any[]> {
+    const response = await this.httpClient.post<{ results?: any[] }>(
+      "/v1/rqlite/transaction",
+      {
+        ops,
+        return_results: returnResults,
+      }
+    );
+    return response.results || [];
+  }
+
+  /**
+   * Create a table from DDL SQL.
+   */
+  async createTable(schema: string): Promise<void> {
+    await this.httpClient.post("/v1/rqlite/create-table", { schema });
+  }
+
+  /**
+   * Drop a table.
+   */
+  async dropTable(table: string): Promise<void> {
+    await this.httpClient.post("/v1/rqlite/drop-table", { table });
+  }
+
+  /**
+   * Get current database schema.
+   */
+  async getSchema(): Promise<any> {
+    return this.httpClient.get("/v1/rqlite/schema");
+  }
+}

package/src/db/qb.ts

@@ -0,0 +1,111 @@
+import { HttpClient } from "../core/http";
+import { SelectOptions, QueryResponse } from "./types";
+
+export class QueryBuilder {
+  private httpClient: HttpClient;
+  private table: string;
+  private options: SelectOptions = {};
+
+  constructor(httpClient: HttpClient, table: string) {
+    this.httpClient = httpClient;
+    this.table = table;
+  }
+
+  select(...columns: string[]): this {
+    this.options.select = columns;
+    return this;
+  }
+
+  innerJoin(table: string, on: string): this {
+    if (!this.options.joins) this.options.joins = [];
+    this.options.joins.push({ kind: "INNER", table, on });
+    return this;
+  }
+
+  leftJoin(table: string, on: string): this {
+    if (!this.options.joins) this.options.joins = [];
+    this.options.joins.push({ kind: "LEFT", table, on });
+    return this;
+  }
+
+  rightJoin(table: string, on: string): this {
+    if (!this.options.joins) this.options.joins = [];
+    this.options.joins.push({ kind: "RIGHT", table, on });
+    return this;
+  }
+
+  where(expr: string, args?: any[]): this {
+    if (!this.options.where) this.options.where = [];
+    this.options.where.push({ conj: "AND", expr, args });
+    return this;
+  }
+
+  andWhere(expr: string, args?: any[]): this {
+    return this.where(expr, args);
+  }
+
+  orWhere(expr: string, args?: any[]): this {
+    if (!this.options.where) this.options.where = [];
+    this.options.where.push({ conj: "OR", expr, args });
+    return this;
+  }
+
+  groupBy(...columns: string[]): this {
+    this.options.group_by = columns;
+    return this;
+  }
+
+  orderBy(...columns: string[]): this {
+    this.options.order_by = columns;
+    return this;
+  }
+
+  limit(n: number): this {
+    this.options.limit = n;
+    return this;
+  }
+
+  offset(n: number): this {
+    this.options.offset = n;
+    return this;
+  }
+
+  async getMany<T = any>(ctx?: any): Promise<T[]> {
+    const response = await this.httpClient.post<QueryResponse>(
+      "/v1/rqlite/select",
+      {
+        table: this.table,
+        ...this.options,
+      }
+    );
+    return response.items || [];
+  }
+
+  async getOne<T = any>(ctx?: any): Promise<T | null> {
+    const response = await this.httpClient.post<QueryResponse>(
+      "/v1/rqlite/select",
+      {
+        table: this.table,
+        ...this.options,
+        one: true,
+        limit: 1,
+      }
+    );
+    const items = response.items || [];
+    return items.length > 0 ? items[0] : null;
+  }
+
+  async count(): Promise<number> {
+    const response = await this.httpClient.post<QueryResponse>(
+      "/v1/rqlite/select",
+      {
+        table: this.table,
+        select: ["COUNT(*) AS count"],
+        where: this.options.where,
+        one: true,
+      }
+    );
+    const items = response.items || [];
+    return items.length > 0 ? items[0].count : 0;
+  }
+}

package/src/db/repository.ts

@@ -0,0 +1,124 @@
+import { HttpClient } from "../core/http";
+import { QueryBuilder } from "./qb";
+import { QueryResponse, FindOptions } from "./types";
+import { SDKError } from "../errors";
+
+export class Repository<T extends Record<string, any>> {
+  private httpClient: HttpClient;
+  private tableName: string;
+  private primaryKey: string;
+
+  constructor(httpClient: HttpClient, tableName: string, primaryKey = "id") {
+    this.httpClient = httpClient;
+    this.tableName = tableName;
+    this.primaryKey = primaryKey;
+  }
+
+  createQueryBuilder(): QueryBuilder {
+    return new QueryBuilder(this.httpClient, this.tableName);
+  }
+
+  async find(
+    criteria: Record<string, any> = {},
+    options: FindOptions = {}
+  ): Promise<T[]> {
+    const response = await this.httpClient.post<QueryResponse>(
+      "/v1/rqlite/find",
+      {
+        table: this.tableName,
+        criteria,
+        options,
+      }
+    );
+    return response.items || [];
+  }
+
+  async findOne(criteria: Record<string, any>): Promise<T | null> {
+    try {
+      const response = await this.httpClient.post<T | null>(
+        "/v1/rqlite/find-one",
+        {
+          table: this.tableName,
+          criteria,
+        }
+      );
+      return response;
+    } catch (error) {
+      // Return null if not found instead of throwing
+      if (error instanceof SDKError && error.httpStatus === 404) {
+        return null;
+      }
+      throw error;
+    }
+  }
+
+  async save(entity: T): Promise<T> {
+    const pkValue = entity[this.primaryKey];
+
+    if (!pkValue) {
+      // INSERT
+      const response = await this.httpClient.post<{
+        rows_affected: number;
+        last_insert_id: number;
+      }>("/v1/rqlite/exec", {
+        sql: this.buildInsertSql(entity),
+        args: this.buildInsertArgs(entity),
+      });
+
+      if (response.last_insert_id) {
+        (entity as any)[this.primaryKey] = response.last_insert_id;
+      }
+      return entity;
+    } else {
+      // UPDATE
+      await this.httpClient.post("/v1/rqlite/exec", {
+        sql: this.buildUpdateSql(entity),
+        args: this.buildUpdateArgs(entity),
+      });
+      return entity;
+    }
+  }
+
+  async remove(entity: T | Record<string, any>): Promise<void> {
+    const pkValue = entity[this.primaryKey];
+    if (!pkValue) {
+      throw new SDKError(
+        `Primary key "${this.primaryKey}" is required for remove`,
+        400,
+        "MISSING_PK"
+      );
+    }
+
+    await this.httpClient.post("/v1/rqlite/exec", {
+      sql: `DELETE FROM ${this.tableName} WHERE ${this.primaryKey} = ?`,
+      args: [pkValue],
+    });
+  }
+
+  private buildInsertSql(entity: T): string {
+    const columns = Object.keys(entity).filter((k) => entity[k] !== undefined);
+    const placeholders = columns.map(() => "?").join(", ");
+    return `INSERT INTO ${this.tableName} (${columns.join(", ")}) VALUES (${placeholders})`;
+  }
+
+  private buildInsertArgs(entity: T): any[] {
+    return Object.entries(entity)
+      .filter(([, v]) => v !== undefined)
+      .map(([, v]) => v);
+  }
+
+  private buildUpdateSql(entity: T): string {
+    const columns = Object.keys(entity)
+      .filter((k) => entity[k] !== undefined && k !== this.primaryKey)
+      .map((k) => `${k} = ?`);
+    return `UPDATE ${this.tableName} SET ${columns.join(", ")} WHERE ${this.primaryKey} = ?`;
+  }
+
+  private buildUpdateArgs(entity: T): any[] {
+    const args = Object.entries(entity)
+      .filter(([k, v]) => v !== undefined && k !== this.primaryKey)
+      .map(([, v]) => v);
+    args.push(entity[this.primaryKey]);
+    return args;
+  }
+}

package/src/db/types.ts

@@ -0,0 +1,67 @@
+export interface Entity {
+  TableName(): string;
+}
+
+export interface QueryResponse {
+  columns?: string[];
+  rows?: any[][];
+  count?: number;
+  items?: any[];
+}
+
+export interface TransactionOp {
+  kind: "exec" | "query";
+  sql: string;
+  args?: any[];
+}
+
+export interface TransactionRequest {
+  statements?: string[];
+  ops?: TransactionOp[];
+  return_results?: boolean;
+}
+
+export interface SelectOptions {
+  select?: string[];
+  joins?: Array<{
+    kind: "INNER" | "LEFT" | "RIGHT" | "FULL";
+    table: string;
+    on: string;
+  }>;
+  where?: Array<{
+    conj?: "AND" | "OR";
+    expr: string;
+    args?: any[];
+  }>;
+  group_by?: string[];
+  order_by?: string[];
+  limit?: number;
+  offset?: number;
+  one?: boolean;
+}
+
+export type FindOptions = Omit<SelectOptions, "select" | "joins" | "one">;
+
+export interface ColumnDefinition {
+  name: string;
+  isPrimaryKey?: boolean;
+  isAutoIncrement?: boolean;
+}
+
+export function extractTableName(entity: Entity | string): string {
+  if (typeof entity === "string") return entity;
+  return entity.TableName();
+}
+
+export function extractPrimaryKey(entity: any): string | undefined {
+  if (typeof entity === "string") return undefined;
+
+  // Check for explicit pk tag
+  const metadata = (entity as any)._dbMetadata;
+  if (metadata?.primaryKey) return metadata.primaryKey;
+
+  // Check for ID field
+  if (entity.id !== undefined) return "id";
+
+  return undefined;
+}

package/src/errors.ts

@@ -0,0 +1,38 @@
+export class SDKError extends Error {
+  public readonly httpStatus: number;
+  public readonly code: string;
+  public readonly details: Record<string, any>;
+
+  constructor(
+    message: string,
+    httpStatus: number = 500,
+    code: string = "SDK_ERROR",
+    details: Record<string, any> = {}
+  ) {
+    super(message);
+    this.name = "SDKError";
+    this.httpStatus = httpStatus;
+    this.code = code;
+    this.details = details;
+  }
+
+  static fromResponse(
+    status: number,
+    body: any,
+    message?: string
+  ): SDKError {
+    const errorMsg = message || body?.error || `HTTP ${status}`;
+    const code = body?.code || `HTTP_${status}`;
+    return new SDKError(errorMsg, status, code, body);
+  }
+
+  toJSON() {
+    return {
+      name: this.name,
+      message: this.message,
+      httpStatus: this.httpStatus,
+      code: this.code,
+      details: this.details,
+    };
+  }
+}

package/src/index.ts

@@ -0,0 +1,82 @@
+import { HttpClient, HttpClientConfig } from "./core/http";
+import { AuthClient } from "./auth/client";
+import { DBClient } from "./db/client";
+import { PubSubClient } from "./pubsub/client";
+import { NetworkClient } from "./network/client";
+import { WSClientConfig } from "./core/ws";
+import { StorageAdapter, MemoryStorage, LocalStorageAdapter } from "./auth/types";
+
+export interface ClientConfig extends Omit<HttpClientConfig, "fetch"> {
+  apiKey?: string;
+  jwt?: string;
+  storage?: StorageAdapter;
+  wsConfig?: Partial<WSClientConfig>;
+  fetch?: typeof fetch;
+}
+
+export interface Client {
+  auth: AuthClient;
+  db: DBClient;
+  pubsub: PubSubClient;
+  network: NetworkClient;
+}
+
+export function createClient(config: ClientConfig): Client {
+  const httpClient = new HttpClient({
+    baseURL: config.baseURL,
+    timeout: config.timeout,
+    maxRetries: config.maxRetries,
+    retryDelayMs: config.retryDelayMs,
+    fetch: config.fetch,
+  });
+
+  const auth = new AuthClient({
+    httpClient,
+    storage: config.storage,
+    apiKey: config.apiKey,
+    jwt: config.jwt,
+  });
+
+  // Derive WebSocket URL from baseURL if not explicitly provided
+  const wsURL = config.wsConfig?.wsURL ?? 
+    config.baseURL.replace(/^http/, 'ws').replace(/\/$/, '');
+
+  const db = new DBClient(httpClient);
+  const pubsub = new PubSubClient(httpClient, {
+    ...config.wsConfig,
+    wsURL,
+  });
+  const network = new NetworkClient(httpClient);
+
+  return {
+    auth,
+    db,
+    pubsub,
+    network,
+  };
+}
+
+// Re-exports
+export { HttpClient } from "./core/http";
+export { WSClient } from "./core/ws";
+export { AuthClient } from "./auth/client";
+export { DBClient } from "./db/client";
+export { QueryBuilder } from "./db/qb";
+export { Repository } from "./db/repository";
+export { PubSubClient, Subscription } from "./pubsub/client";
+export { NetworkClient } from "./network/client";
+export { SDKError } from "./errors";
+export { MemoryStorage, LocalStorageAdapter } from "./auth/types";
+export type {
+  StorageAdapter,
+  AuthConfig,
+  WhoAmI,
+} from "./auth/types";
+export type * from "./db/types";
+export type {
+  Message,
+  MessageHandler,
+  ErrorHandler,
+  CloseHandler,
+} from "./pubsub/client";
+export type { PeerInfo, NetworkStatus } from "./network/client";

package/src/network/client.ts

@@ -0,0 +1,65 @@
+import { HttpClient } from "../core/http";
+
+export interface PeerInfo {
+  id: string;
+  addresses: string[];
+  lastSeen?: string;
+}
+
+export interface NetworkStatus {
+  healthy: boolean;
+  peers: number;
+  uptime?: number;
+}
+
+export class NetworkClient {
+  private httpClient: HttpClient;
+
+  constructor(httpClient: HttpClient) {
+    this.httpClient = httpClient;
+  }
+
+  /**
+   * Check gateway health.
+   */
+  async health(): Promise<boolean> {
+    try {
+      await this.httpClient.get("/v1/health");
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  /**
+   * Get network status.
+   */
+  async status(): Promise<NetworkStatus> {
+    const response = await this.httpClient.get<NetworkStatus>("/v1/status");
+    return response;
+  }
+
+  /**
+   * Get connected peers.
+   */
+  async peers(): Promise<PeerInfo[]> {
+    const response = await this.httpClient.get<{ peers: PeerInfo[] }>(
+      "/v1/network/peers"
+    );
+    return response.peers || [];
+  }
+
+  /**
+   * Connect to a peer.
+   */
+  async connect(peerAddr: string): Promise<void> {
+    await this.httpClient.post("/v1/network/connect", { peer_addr: peerAddr });
+  }
+
+  /**
+   * Disconnect from a peer.
+   */
+  async disconnect(peerId: string): Promise<void> {
+    await this.httpClient.post("/v1/network/disconnect", { peer_id: peerId });
+  }
+}