@debros/network-ts-sdk 0.1.4

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) [year] [fullname]
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,329 @@
+# @network/sdk - TypeScript SDK for DeBros Network
+
+A modern, isomorphic TypeScript SDK for the DeBros Network gateway. Works seamlessly in both Node.js and browser environments with support for database operations, pub/sub messaging, and network management.
+
+## Features
+
+- **Isomorphic**: Works in Node.js and browsers (uses fetch and isomorphic-ws)
+- **Database ORM-like API**: QueryBuilder, Repository pattern, transactions
+- **Pub/Sub Messaging**: WebSocket subscriptions with automatic reconnection
+- **Authentication**: API key and JWT support with automatic token management
+- **TypeScript First**: Full type safety and IntelliSense
+- **Error Handling**: Unified SDKError with HTTP status and code
+
+## Installation
+
+```bash
+npm install @network/network-ts-sdk
+```
+
+## Quick Start
+
+### Initialize the Client
+
+```typescript
+import { createClient } from "@network/sdk";
+
+const client = createClient({
+  baseURL: "http://localhost:6001",
+  apiKey: "ak_your_api_key:namespace",
+});
+
+// Or with JWT
+const client = createClient({
+  baseURL: "http://localhost:6001",
+  jwt: "your_jwt_token",
+});
+```
+
+### Database Operations
+
+#### Create a Table
+
+```typescript
+await client.db.createTable(
+  "CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT, email TEXT)"
+);
+```
+
+#### Insert Data
+
+```typescript
+const result = await client.db.exec(
+  "INSERT INTO users (name, email) VALUES (?, ?)",
+  ["Alice", "alice@example.com"]
+);
+console.log(result.last_insert_id);
+```
+
+#### Query Data
+
+```typescript
+const users = await client.db.query("SELECT * FROM users WHERE email = ?", [
+  "alice@example.com",
+]);
+```
+
+#### Using QueryBuilder
+
+```typescript
+const activeUsers = await client.db
+  .createQueryBuilder("users")
+  .where("active = ?", [1])
+  .orderBy("name DESC")
+  .limit(10)
+  .getMany();
+
+const firstUser = await client.db
+  .createQueryBuilder("users")
+  .where("id = ?", [1])
+  .getOne();
+```
+
+#### Using Repository Pattern
+
+```typescript
+interface User {
+  id?: number;
+  name: string;
+  email: string;
+}
+
+const repo = client.db.repository<User>("users");
+
+// Find
+const users = await repo.find({ active: 1 });
+const user = await repo.findOne({ email: "alice@example.com" });
+
+// Save (INSERT or UPDATE)
+const newUser: User = { name: "Bob", email: "bob@example.com" };
+await repo.save(newUser);
+
+// Remove
+await repo.remove(newUser);
+```
+
+#### Transactions
+
+```typescript
+const results = await client.db.transaction([
+  {
+    kind: "exec",
+    sql: "INSERT INTO users (name, email) VALUES (?, ?)",
+    args: ["Charlie", "charlie@example.com"],
+  },
+  {
+    kind: "query",
+    sql: "SELECT COUNT(*) as count FROM users",
+    args: [],
+  },
+]);
+```
+
+### Pub/Sub Messaging
+
+#### Publish a Message
+
+```typescript
+await client.pubsub.publish("notifications", "Hello, Network!");
+```
+
+#### Subscribe to Topics
+
+```typescript
+const subscription = await client.pubsub.subscribe("notifications", {
+  onMessage: (msg) => {
+    console.log("Received:", msg.data);
+  },
+  onError: (err) => {
+    console.error("Subscription error:", err);
+  },
+  onClose: () => {
+    console.log("Subscription closed");
+  },
+});
+
+// Later, close the subscription
+subscription.close();
+```
+
+#### List Topics
+
+```typescript
+const topics = await client.pubsub.topics();
+console.log("Active topics:", topics);
+```
+
+### Authentication
+
+#### Switch API Key
+
+```typescript
+client.auth.setApiKey("ak_new_key:namespace");
+```
+
+#### Switch JWT
+
+```typescript
+client.auth.setJwt("new_jwt_token");
+```
+
+#### Get Current Token
+
+```typescript
+const token = client.auth.getToken(); // Returns API key or JWT
+```
+
+#### Get Authentication Info
+
+```typescript
+const info = await client.auth.whoami();
+console.log(info.authenticated, info.namespace);
+```
+
+#### Logout
+
+```typescript
+await client.auth.logout();
+```
+
+### Network Operations
+
+#### Check Health
+
+```typescript
+const healthy = await client.network.health();
+```
+
+#### Get Network Status
+
+```typescript
+const status = await client.network.status();
+console.log(status.healthy, status.peers);
+```
+
+#### List Peers
+
+```typescript
+const peers = await client.network.peers();
+peers.forEach((peer) => {
+  console.log(peer.id, peer.addresses);
+});
+```
+
+## Configuration
+
+### ClientConfig
+
+```typescript
+interface ClientConfig {
+  baseURL: string; // Gateway URL
+  apiKey?: string; // API key (optional, if using JWT instead)
+  jwt?: string; // JWT token (optional, if using API key instead)
+  timeout?: number; // Request timeout in ms (default: 30000)
+  maxRetries?: number; // Max retry attempts (default: 3)
+  retryDelayMs?: number; // Delay between retries (default: 1000)
+  storage?: StorageAdapter; // For persisting JWT/API key (default: MemoryStorage)
+  wsConfig?: Partial<WSClientConfig>; // WebSocket configuration
+  fetch?: typeof fetch; // Custom fetch implementation
+}
+```
+
+### Storage Adapters
+
+By default, credentials are stored in memory. For browser apps, use localStorage:
+
+```typescript
+import { createClient, LocalStorageAdapter } from "@network/sdk";
+
+const client = createClient({
+  baseURL: "http://localhost:6001",
+  storage: new LocalStorageAdapter(),
+  apiKey: "ak_your_key:namespace",
+});
+```
+
+## Error Handling
+
+The SDK throws `SDKError` for all errors:
+
+```typescript
+import { SDKError } from "@network/sdk";
+
+try {
+  await client.db.query("SELECT * FROM nonexistent");
+} catch (error) {
+  if (error instanceof SDKError) {
+    console.log(error.httpStatus); // e.g., 400
+    console.log(error.code); // e.g., "HTTP_400"
+    console.log(error.message); // Error message
+    console.log(error.details); // Full error response
+  }
+}
+```
+
+## Browser Usage
+
+The SDK works in browsers with minimal setup:
+
+```typescript
+// Browser example
+import { createClient } from "@network/sdk";
+
+const client = createClient({
+  baseURL: "https://gateway.example.com",
+  apiKey: "ak_browser_key:my-app",
+});
+
+// Use like any other API client
+const data = await client.db.query("SELECT * FROM items");
+```
+
+**Note**: For WebSocket connections in browsers with authentication, ensure your gateway supports either header-based auth or query parameter auth.
+
+## Testing
+
+Run E2E tests against a running gateway:
+
+```bash
+# Set environment variables
+export GATEWAY_BASE_URL=http://localhost:6001
+export GATEWAY_API_KEY=ak_test_key:default
+
+# Run tests
+npm run test:e2e
+```
+
+## Examples
+
+See the `tests/e2e/` directory for complete examples of:
+
+- Authentication (`auth.test.ts`)
+- Database operations (`db.test.ts`)
+- Transactions (`tx.test.ts`)
+- Pub/Sub messaging (`pubsub.test.ts`)
+- Network operations (`network.test.ts`)
+
+## Building
+
+```bash
+npm run build
+```
+
+Output goes to `dist/` with ESM and type declarations.
+
+## Development
+
+```bash
+npm run dev      # Watch mode
+npm run typecheck # Type checking
+npm run lint     # Linting (if configured)
+```
+
+## License
+
+MIT
+
+## Support
+
+For issues, questions, or contributions, please open an issue on GitHub or visit [DeBros Network Documentation](https://network.debros.io/docs/).

package/dist/index.d.ts

@@ -0,0 +1,367 @@
+import WebSocket from 'isomorphic-ws';
+
+interface HttpClientConfig {
+    baseURL: string;
+    timeout?: number;
+    maxRetries?: number;
+    retryDelayMs?: number;
+    fetch?: typeof fetch;
+}
+declare class HttpClient {
+    private baseURL;
+    private timeout;
+    private maxRetries;
+    private retryDelayMs;
+    private fetch;
+    private apiKey?;
+    private jwt?;
+    constructor(config: HttpClientConfig);
+    setApiKey(apiKey?: string): void;
+    setJwt(jwt?: string): void;
+    private getAuthHeaders;
+    private getAuthToken;
+    request<T = any>(method: "GET" | "POST" | "PUT" | "DELETE", path: string, options?: {
+        body?: any;
+        headers?: Record<string, string>;
+        query?: Record<string, string | number | boolean>;
+    }): Promise<T>;
+    private requestWithRetry;
+    get<T = any>(path: string, options?: Omit<Parameters<typeof this.request>[2], "body">): Promise<T>;
+    post<T = any>(path: string, body?: any, options?: Omit<Parameters<typeof this.request>[2], "body">): Promise<T>;
+    put<T = any>(path: string, body?: any, options?: Omit<Parameters<typeof this.request>[2], "body">): Promise<T>;
+    delete<T = any>(path: string, options?: Omit<Parameters<typeof this.request>[2], "body">): Promise<T>;
+    getToken(): string | undefined;
+}
+
+interface AuthConfig {
+    apiKey?: string;
+    jwt?: string;
+}
+interface WhoAmI {
+    address?: string;
+    namespace?: string;
+    authenticated: boolean;
+}
+interface StorageAdapter {
+    get(key: string): Promise<string | null>;
+    set(key: string, value: string): Promise<void>;
+    clear(): Promise<void>;
+}
+declare class MemoryStorage implements StorageAdapter {
+    private storage;
+    get(key: string): Promise<string | null>;
+    set(key: string, value: string): Promise<void>;
+    clear(): Promise<void>;
+}
+declare class LocalStorageAdapter implements StorageAdapter {
+    private prefix;
+    get(key: string): Promise<string | null>;
+    set(key: string, value: string): Promise<void>;
+    clear(): Promise<void>;
+}
+
+declare class AuthClient {
+    private httpClient;
+    private storage;
+    private currentApiKey?;
+    private currentJwt?;
+    constructor(config: {
+        httpClient: HttpClient;
+        storage?: StorageAdapter;
+        apiKey?: string;
+        jwt?: string;
+    });
+    setApiKey(apiKey: string): void;
+    setJwt(jwt: string): void;
+    getToken(): string | undefined;
+    whoami(): Promise<WhoAmI>;
+    refresh(): Promise<string>;
+    logout(): Promise<void>;
+    clear(): Promise<void>;
+}
+
+declare class QueryBuilder {
+    private httpClient;
+    private table;
+    private options;
+    constructor(httpClient: HttpClient, table: string);
+    select(...columns: string[]): this;
+    innerJoin(table: string, on: string): this;
+    leftJoin(table: string, on: string): this;
+    rightJoin(table: string, on: string): this;
+    where(expr: string, args?: any[]): this;
+    andWhere(expr: string, args?: any[]): this;
+    orWhere(expr: string, args?: any[]): this;
+    groupBy(...columns: string[]): this;
+    orderBy(...columns: string[]): this;
+    limit(n: number): this;
+    offset(n: number): this;
+    getMany<T = any>(ctx?: any): Promise<T[]>;
+    getOne<T = any>(ctx?: any): Promise<T | null>;
+    count(): Promise<number>;
+}
+
+interface Entity {
+    TableName(): string;
+}
+interface QueryResponse {
+    columns?: string[];
+    rows?: any[][];
+    count?: number;
+    items?: any[];
+}
+interface TransactionOp {
+    kind: "exec" | "query";
+    sql: string;
+    args?: any[];
+}
+interface TransactionRequest {
+    statements?: string[];
+    ops?: TransactionOp[];
+    return_results?: boolean;
+}
+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;
+}
+type FindOptions = Omit<SelectOptions, "select" | "joins" | "one">;
+interface ColumnDefinition {
+    name: string;
+    isPrimaryKey?: boolean;
+    isAutoIncrement?: boolean;
+}
+declare function extractTableName(entity: Entity | string): string;
+declare function extractPrimaryKey(entity: any): string | undefined;
+
+declare class Repository<T extends Record<string, any>> {
+    private httpClient;
+    private tableName;
+    private primaryKey;
+    constructor(httpClient: HttpClient, tableName: string, primaryKey?: string);
+    createQueryBuilder(): QueryBuilder;
+    find(criteria?: Record<string, any>, options?: FindOptions): Promise<T[]>;
+    findOne(criteria: Record<string, any>): Promise<T | null>;
+    save(entity: T): Promise<T>;
+    remove(entity: T | Record<string, any>): Promise<void>;
+    private buildInsertSql;
+    private buildInsertArgs;
+    private buildUpdateSql;
+    private buildUpdateArgs;
+}
+
+declare class DBClient {
+    private httpClient;
+    constructor(httpClient: HttpClient);
+    /**
+     * Execute a write/DDL SQL statement.
+     */
+    exec(sql: string, args?: any[]): Promise<{
+        rows_affected: number;
+        last_insert_id?: number;
+    }>;
+    /**
+     * Execute a SELECT query.
+     */
+    query<T = any>(sql: string, args?: any[]): Promise<T[]>;
+    /**
+     * Find rows with map-based criteria.
+     */
+    find<T = any>(table: string, criteria?: Record<string, any>, options?: FindOptions): Promise<T[]>;
+    /**
+     * Find a single row with map-based criteria.
+     */
+    findOne<T = any>(table: string, criteria: Record<string, any>): Promise<T | null>;
+    /**
+     * Create a fluent QueryBuilder for complex SELECT queries.
+     */
+    createQueryBuilder(table: string): QueryBuilder;
+    /**
+     * Create a Repository for entity-based operations.
+     */
+    repository<T extends Record<string, any>>(tableName: string, primaryKey?: string): Repository<T>;
+    /**
+     * Execute multiple operations atomically.
+     */
+    transaction(ops: TransactionOp[], returnResults?: boolean): Promise<any[]>;
+    /**
+     * Create a table from DDL SQL.
+     */
+    createTable(schema: string): Promise<void>;
+    /**
+     * Drop a table.
+     */
+    dropTable(table: string): Promise<void>;
+    /**
+     * Get current database schema.
+     */
+    getSchema(): Promise<any>;
+}
+
+interface WSClientConfig {
+    wsURL: string;
+    timeout?: number;
+    maxReconnectAttempts?: number;
+    reconnectDelayMs?: number;
+    heartbeatIntervalMs?: number;
+    authMode?: "header" | "query";
+    authToken?: string;
+    WebSocket?: typeof WebSocket;
+}
+type WSMessageHandler = (data: string) => void;
+type WSErrorHandler = (error: Error) => void;
+type WSCloseHandler = () => void;
+declare class WSClient {
+    private url;
+    private timeout;
+    private maxReconnectAttempts;
+    private reconnectDelayMs;
+    private heartbeatIntervalMs;
+    private authMode;
+    private authToken?;
+    private WebSocketClass;
+    private ws?;
+    private reconnectAttempts;
+    private heartbeatInterval?;
+    private messageHandlers;
+    private errorHandlers;
+    private closeHandlers;
+    private isManuallyClosed;
+    constructor(config: WSClientConfig);
+    connect(): Promise<void>;
+    private buildWSUrl;
+    private startHeartbeat;
+    private stopHeartbeat;
+    private attemptReconnect;
+    onMessage(handler: WSMessageHandler): () => boolean;
+    onError(handler: WSErrorHandler): () => boolean;
+    onClose(handler: WSCloseHandler): () => boolean;
+    send(data: string): void;
+    close(): void;
+    isConnected(): boolean;
+    setAuthToken(token?: string): void;
+}
+
+interface Message {
+    data: string;
+    topic: string;
+    timestamp?: number;
+}
+type MessageHandler = (message: Message) => void;
+type ErrorHandler = (error: Error) => void;
+type CloseHandler = () => void;
+declare class PubSubClient {
+    private httpClient;
+    private wsConfig;
+    constructor(httpClient: HttpClient, wsConfig?: Partial<WSClientConfig>);
+    /**
+     * Publish a message to a topic.
+     */
+    publish(topic: string, data: string | Uint8Array): Promise<void>;
+    /**
+     * List active topics in the current namespace.
+     */
+    topics(): Promise<string[]>;
+    /**
+     * Subscribe to a topic via WebSocket.
+     * Returns a subscription object with event handlers.
+     */
+    subscribe(topic: string, handlers?: {
+        onMessage?: MessageHandler;
+        onError?: ErrorHandler;
+        onClose?: CloseHandler;
+    }): Promise<Subscription>;
+}
+declare class Subscription {
+    private wsClient;
+    private topic;
+    private messageHandlers;
+    private errorHandlers;
+    private closeHandlers;
+    constructor(wsClient: WSClient, topic: string);
+    onMessage(handler: MessageHandler): () => boolean;
+    onError(handler: ErrorHandler): () => boolean;
+    onClose(handler: CloseHandler): () => boolean;
+    close(): void;
+    isConnected(): boolean;
+}
+
+interface PeerInfo {
+    id: string;
+    addresses: string[];
+    lastSeen?: string;
+}
+interface NetworkStatus {
+    healthy: boolean;
+    peers: number;
+    uptime?: number;
+}
+declare class NetworkClient {
+    private httpClient;
+    constructor(httpClient: HttpClient);
+    /**
+     * Check gateway health.
+     */
+    health(): Promise<boolean>;
+    /**
+     * Get network status.
+     */
+    status(): Promise<NetworkStatus>;
+    /**
+     * Get connected peers.
+     */
+    peers(): Promise<PeerInfo[]>;
+    /**
+     * Connect to a peer.
+     */
+    connect(peerAddr: string): Promise<void>;
+    /**
+     * Disconnect from a peer.
+     */
+    disconnect(peerId: string): Promise<void>;
+}
+
+declare class SDKError extends Error {
+    readonly httpStatus: number;
+    readonly code: string;
+    readonly details: Record<string, any>;
+    constructor(message: string, httpStatus?: number, code?: string, details?: Record<string, any>);
+    static fromResponse(status: number, body: any, message?: string): SDKError;
+    toJSON(): {
+        name: string;
+        message: string;
+        httpStatus: number;
+        code: string;
+        details: Record<string, any>;
+    };
+}
+
+interface ClientConfig extends Omit<HttpClientConfig, "fetch"> {
+    apiKey?: string;
+    jwt?: string;
+    storage?: StorageAdapter;
+    wsConfig?: Partial<WSClientConfig>;
+    fetch?: typeof fetch;
+}
+interface Client {
+    auth: AuthClient;
+    db: DBClient;
+    pubsub: PubSubClient;
+    network: NetworkClient;
+}
+declare function createClient(config: ClientConfig): Client;
+
+export { AuthClient, type AuthConfig, type Client, type ClientConfig, type CloseHandler, type ColumnDefinition, DBClient, type Entity, type ErrorHandler, type FindOptions, HttpClient, LocalStorageAdapter, MemoryStorage, type Message, type MessageHandler, NetworkClient, type NetworkStatus, type PeerInfo, PubSubClient, QueryBuilder, type QueryResponse, Repository, SDKError, type SelectOptions, type StorageAdapter, Subscription, type TransactionOp, type TransactionRequest, WSClient, type WhoAmI, createClient, extractPrimaryKey, extractTableName };