kalam-link 0.2.0-alpha1

package/LICENSE

@@ -0,0 +1,17 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   Copyright 2025 KalamDB Team
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,423 @@
+# kalam-link
+
+Official TypeScript/JavaScript client for KalamDB.
+
+- Execute SQL over HTTP
+- Subscribe to real-time changes over WebSocket
+- Works in modern browsers and Node.js (>= 18)
+
+## Installation
+
+```bash
+npm i kalam-link
+```
+
+## Quick Start
+
+```ts
+import { createClient, Auth, MessageType, ChangeType } from 'kalam-link';
+
+const client = createClient({
+  url: 'http://localhost:8080',
+  auth: Auth.basic('admin', 'admin'),
+});
+
+await client.connect();
+
+// Query
+const result = await client.query('SELECT 1 AS ok');
+console.log(result.results[0]);
+
+// Subscribe (returns an unsubscribe function)
+const unsubscribe = await client.subscribe('app.messages', (event) => {
+  switch (event.type) {
+    case MessageType.Change:
+      if (event.change_type === ChangeType.Insert) {
+        console.log('New row:', event.rows);
+      }
+      break;
+    case MessageType.InitialDataBatch:
+      console.log('Initial data:', event.rows);
+      break;
+    case MessageType.Error:
+      console.error('Subscription error:', event.message);
+      break;
+  }
+});
+
+// Later
+await unsubscribe();
+await client.disconnect();
+```
+
+## Authentication
+
+```ts
+import { createClient, Auth } from 'kalam-link';
+
+// Username/password
+createClient({ url: 'http://localhost:8080', auth: Auth.basic('user', 'pass') });
+
+// JWT token
+createClient({ url: 'http://localhost:8080', auth: Auth.jwt('eyJhbGciOiJIUzI1NiIs...') });
+
+// No auth (for local/dev setups that allow it)
+createClient({ url: 'http://localhost:8080', auth: Auth.none() });
+```
+
+## API Reference (Complete)
+
+Everything below is exported from `kalam-link` unless noted otherwise.
+
+### Imports
+
+```ts
+import KalamDBClient, {
+  createClient,
+  Auth,
+  // Enums
+  MessageType,
+  ChangeType,
+  BatchStatus,
+  // Types
+  type AuthCredentials,
+  type BasicAuthCredentials,
+  type JwtAuthCredentials,
+  type NoAuthCredentials,
+  type ClientOptions,
+  type ClientOptionsWithAuth,
+  type ClientOptionsLegacy,
+  type ConnectionOptions,
+  type SubscriptionOptions,
+  type SubscribeOptions,
+  type QueryResponse,
+  type QueryResult,
+  type SchemaField,
+  type ErrorDetail,
+  type ServerMessage,
+  type BatchControl,
+  type SubscriptionCallback,
+  type SubscriptionInfo,
+  type Unsubscribe,
+  type WasmKalamClient,
+  // Helpers
+  buildAuthHeader,
+  encodeBasicAuth,
+  isAuthenticated,
+  isBasicAuth,
+  isJwtAuth,
+  isNoAuth,
+} from 'kalam-link';
+```
+
+### Factory
+
+#### `createClient(options: ClientOptions): KalamDBClient`
+
+```ts
+type ClientOptions = ClientOptionsWithAuth | ClientOptionsLegacy;
+
+interface ClientOptionsWithAuth {
+  url: string;
+  auth: AuthCredentials;
+}
+
+interface ClientOptionsLegacy {
+  url: string;
+  username: string;
+  password: string;
+}
+```
+
+### Class: `KalamDBClient` (default export)
+
+#### Constructors
+
+```ts
+new KalamDBClient(options: ClientOptionsWithAuth)
+
+// Legacy (deprecated)
+new KalamDBClient(url: string, username: string, password: string)
+```
+
+#### Lifecycle
+
+```ts
+initialize(): Promise<void>
+connect(): Promise<void>
+disconnect(): Promise<void>
+isConnected(): boolean
+```
+
+#### Authentication
+
+```ts
+getAuthType(): 'basic' | 'jwt' | 'none'
+```
+
+#### Queries
+
+```ts
+query(sql: string, params?: any[]): Promise<QueryResponse>
+```
+
+#### Convenience DML
+
+```ts
+insert(tableName: string, data: Record<string, any>): Promise<QueryResponse>
+delete(tableName: string, rowId: string | number): Promise<void>
+```
+
+#### Subscriptions
+
+```ts
+subscribe(
+  tableName: string,
+  callback: SubscriptionCallback,
+  options?: SubscriptionOptions
+): Promise<Unsubscribe>
+
+subscribeWithSql(
+  sql: string,
+  callback: SubscriptionCallback,
+  options?: SubscriptionOptions
+): Promise<Unsubscribe>
+
+unsubscribe(subscriptionId: string): Promise<void>
+unsubscribeAll(): Promise<void>
+```
+
+Subscription helpers:
+
+```ts
+getSubscriptionCount(): number
+getSubscriptions(): SubscriptionInfo[]
+isSubscribedTo(tableNameOrSql: string): boolean
+getLastSeqId(subscriptionId: string): string | undefined
+```
+
+#### Reconnection controls
+
+```ts
+setAutoReconnect(enabled: boolean): void
+setReconnectDelay(initialDelayMs: number, maxDelayMs: number): void
+setMaxReconnectAttempts(maxAttempts: number): void
+getReconnectAttempts(): number
+isReconnecting(): boolean
+```
+
+### Auth API
+
+#### Types
+
+```ts
+interface BasicAuthCredentials { type: 'basic'; username: string; password: string }
+interface JwtAuthCredentials { type: 'jwt'; token: string }
+interface NoAuthCredentials { type: 'none' }
+
+type AuthCredentials =
+  | BasicAuthCredentials
+  | JwtAuthCredentials
+  | NoAuthCredentials;
+```
+
+#### Factories
+
+```ts
+Auth.basic(username: string, password: string): BasicAuthCredentials
+Auth.jwt(token: string): JwtAuthCredentials
+Auth.none(): NoAuthCredentials
+```
+
+#### Helpers
+
+```ts
+encodeBasicAuth(username: string, password: string): string
+buildAuthHeader(auth: AuthCredentials): string | undefined
+
+isBasicAuth(auth: AuthCredentials): auth is BasicAuthCredentials
+isJwtAuth(auth: AuthCredentials): auth is JwtAuthCredentials
+isNoAuth(auth: AuthCredentials): auth is NoAuthCredentials
+isAuthenticated(auth: AuthCredentials): auth is BasicAuthCredentials | JwtAuthCredentials
+```
+
+### Query result types
+
+```ts
+interface SchemaField {
+  name: string;
+  data_type: string;
+  index: number;
+}
+
+interface QueryResult {
+  schema: SchemaField[];
+  rows?: unknown[][];
+  row_count: number;
+  message?: string;
+}
+
+interface QueryResponse {
+  status: 'success' | 'error';
+  results: QueryResult[];
+  took?: number;
+  error?: ErrorDetail;
+}
+
+interface ErrorDetail {
+  code: string;
+  message: string;
+  details?: any;
+}
+```
+
+### Enums
+
+```ts
+// Message type for WebSocket subscription events
+enum MessageType {
+  SubscriptionAck = 'subscription_ack',
+  InitialDataBatch = 'initial_data_batch',
+  Change = 'change',
+  Error = 'error',
+}
+
+// Change type for live subscription change events
+enum ChangeType {
+  Insert = 'insert',
+  Update = 'update',
+  Delete = 'delete',
+}
+
+// Batch loading status
+enum BatchStatus {
+  Loading = 'loading',
+  LoadingBatch = 'loading_batch',
+  Ready = 'ready',
+}
+```
+
+### Live subscription event types
+
+```ts
+type ServerMessage =
+  | {
+      type: MessageType.SubscriptionAck;
+      subscription_id: string;
+      total_rows: number;
+      batch_control: BatchControl;
+      schema: SchemaField[];
+    }
+  | {
+      type: MessageType.InitialDataBatch;
+      subscription_id: string;
+      rows: Record<string, any>[];
+      batch_control: BatchControl;
+    }
+  | {
+      type: MessageType.Change;
+      subscription_id: string;
+      change_type: ChangeType;
+      rows?: Record<string, any>[];
+      old_values?: Record<string, any>[];
+    }
+  | {
+      type: MessageType.Error;
+      subscription_id: string;
+      code: string;
+      message: string;
+    };
+
+interface BatchControl {
+  batch_num: number;
+  has_more: boolean;
+  status: BatchStatus;
+  last_seq_id?: string;
+  snapshot_end_seq?: string;
+}
+
+type SubscriptionCallback = (event: ServerMessage) => void;
+type Unsubscribe = () => Promise<void>;
+
+interface SubscriptionInfo {
+  id: string;
+  tableName: string;
+  createdAt: Date;
+}
+```
+
+### Options
+
+```ts
+interface ConnectionOptions {
+  auto_reconnect?: boolean;
+  reconnect_delay_ms?: number;
+  max_reconnect_delay_ms?: number;
+  max_reconnect_attempts?: number;
+}
+
+interface SubscriptionOptions {
+  batch_size?: number;
+  last_rows?: number;
+  from_seq_id?: string;
+}
+
+type SubscribeOptions = SubscriptionOptions;
+```
+
+### Advanced: WASM entrypoint (`kalam-link/wasm`)
+
+```ts
+import init, {
+  KalamClient,
+  WasmTimestampFormatter,
+  parseIso8601,
+  timestampNow,
+  initSync,
+} from 'kalam-link/wasm';
+```
+
+Exports:
+
+- `default init(moduleOrPath?) => Promise<InitOutput>`
+- `initSync(moduleOrBytes) => InitOutput`
+- `class KalamClient` (low-level WASM client)
+- `class WasmTimestampFormatter`
+- `parseIso8601(isoString: string): number`
+- `timestampNow(): number`
+
+## Notes (Browser/Node)
+
+This package includes a small `.wasm` runtime under the hood.
+
+- In browsers with bundlers (Vite/Webpack/Rollup), it should “just work”.
+- If you see WASM loading errors, ensure your build serves/copies:
+  `node_modules/kalam-link/dist/wasm/kalam_link_bg.wasm`
+
+## Links
+
+- KalamDB repository: https://github.com/jamals86/KalamDB
+- Issues: https://github.com/jamals86/KalamDB/issues
+
+## Development (Build From This Repo)
+
+Only needed if you are contributing to the SDK.
+
+Prerequisites:
+
+- Node.js `>=18`
+- Rust toolchain + `wasm-pack`
+
+```bash
+cd link/sdks/typescript
+npm install
+npm run build
+```
+
+## License
+
+Apache-2.0 (see the repository root).
+
+## Contributing
+
+Issues/PRs are welcome: https://github.com/jamals86/KalamDB/issues

package/dist/auth.d.ts

@@ -0,0 +1,113 @@
+/**
+ * Authentication types and utilities for KalamDB client
+ *
+ * Provides a type-safe authentication API with support for:
+ * - Basic Auth (username/password)
+ * - JWT Token Auth
+ * - Anonymous (no auth - for localhost bypass)
+ */
+/**
+ * Basic authentication credentials (username/password)
+ */
+export interface BasicAuthCredentials {
+    type: 'basic';
+    username: string;
+    password: string;
+}
+/**
+ * JWT token authentication credentials
+ */
+export interface JwtAuthCredentials {
+    type: 'jwt';
+    token: string;
+}
+/**
+ * No authentication (anonymous access)
+ */
+export interface NoAuthCredentials {
+    type: 'none';
+}
+/**
+ * Union type for all authentication credential types
+ */
+export type AuthCredentials = BasicAuthCredentials | JwtAuthCredentials | NoAuthCredentials;
+/**
+ * Type guard to check if credentials are Basic Auth
+ */
+export declare function isBasicAuth(auth: AuthCredentials): auth is BasicAuthCredentials;
+/**
+ * Type guard to check if credentials are JWT Auth
+ */
+export declare function isJwtAuth(auth: AuthCredentials): auth is JwtAuthCredentials;
+/**
+ * Type guard to check if credentials are No Auth
+ */
+export declare function isNoAuth(auth: AuthCredentials): auth is NoAuthCredentials;
+/**
+ * Type guard to check if any authentication is configured
+ */
+export declare function isAuthenticated(auth: AuthCredentials): auth is BasicAuthCredentials | JwtAuthCredentials;
+/**
+ * Encode username and password for Basic Auth header
+ *
+ * @param username - Username
+ * @param password - Password
+ * @returns Base64 encoded credentials string
+ */
+export declare function encodeBasicAuth(username: string, password: string): string;
+/**
+ * Build the Authorization header value for the given credentials
+ *
+ * @param auth - Authentication credentials
+ * @returns Authorization header value or undefined for no auth
+ */
+export declare function buildAuthHeader(auth: AuthCredentials): string | undefined;
+/**
+ * Auth factory for creating type-safe authentication credentials
+ *
+ * @example
+ * ```typescript
+ * import { createClient, Auth } from 'kalam-link';
+ *
+ * // Basic Auth
+ * const client = createClient({
+ *   url: 'http://localhost:8080',
+ *   auth: Auth.basic('admin', 'admin')
+ * });
+ *
+ * // JWT Token
+ * const jwtClient = createClient({
+ *   url: 'http://localhost:8080',
+ *   auth: Auth.jwt('eyJhbGciOiJIUzI1NiIs...')
+ * });
+ *
+ * // Anonymous (no auth)
+ * const anonClient = createClient({
+ *   url: 'http://localhost:8080',
+ *   auth: Auth.none()
+ * });
+ * ```
+ */
+export declare const Auth: {
+    /**
+     * Create Basic Auth credentials
+     *
+     * @param username - Username for authentication
+     * @param password - Password for authentication
+     * @returns BasicAuthCredentials object
+     */
+    readonly basic: (username: string, password: string) => BasicAuthCredentials;
+    /**
+     * Create JWT Auth credentials
+     *
+     * @param token - JWT token string
+     * @returns JwtAuthCredentials object
+     */
+    readonly jwt: (token: string) => JwtAuthCredentials;
+    /**
+     * Create No Auth credentials (anonymous access)
+     *
+     * @returns NoAuthCredentials object
+     */
+    readonly none: () => NoAuthCredentials;
+};

package/dist/auth.js

@@ -0,0 +1,131 @@
+/**
+ * Authentication types and utilities for KalamDB client
+ *
+ * Provides a type-safe authentication API with support for:
+ * - Basic Auth (username/password)
+ * - JWT Token Auth
+ * - Anonymous (no auth - for localhost bypass)
+ */
+/**
+ * Type guard to check if credentials are Basic Auth
+ */
+export function isBasicAuth(auth) {
+    return auth.type === 'basic';
+}
+/**
+ * Type guard to check if credentials are JWT Auth
+ */
+export function isJwtAuth(auth) {
+    return auth.type === 'jwt';
+}
+/**
+ * Type guard to check if credentials are No Auth
+ */
+export function isNoAuth(auth) {
+    return auth.type === 'none';
+}
+/**
+ * Type guard to check if any authentication is configured
+ */
+export function isAuthenticated(auth) {
+    return auth.type !== 'none';
+}
+/**
+ * Base64 encode a string (works in both Node.js and browser)
+ */
+function base64Encode(str) {
+    if (typeof btoa === 'function') {
+        // Browser environment
+        return btoa(str);
+    }
+    else if (typeof Buffer !== 'undefined') {
+        // Node.js environment
+        return Buffer.from(str).toString('base64');
+    }
+    throw new Error('No base64 encoding available');
+}
+/**
+ * Encode username and password for Basic Auth header
+ *
+ * @param username - Username
+ * @param password - Password
+ * @returns Base64 encoded credentials string
+ */
+export function encodeBasicAuth(username, password) {
+    return base64Encode(`${username}:${password}`);
+}
+/**
+ * Build the Authorization header value for the given credentials
+ *
+ * @param auth - Authentication credentials
+ * @returns Authorization header value or undefined for no auth
+ */
+export function buildAuthHeader(auth) {
+    switch (auth.type) {
+        case 'basic':
+            return `Basic ${encodeBasicAuth(auth.username, auth.password)}`;
+        case 'jwt':
+            return `Bearer ${auth.token}`;
+        case 'none':
+            return undefined;
+        default:
+            // Exhaustiveness check
+            const _exhaustive = auth;
+            throw new Error(`Unknown auth type: ${_exhaustive.type}`);
+    }
+}
+/**
+ * Auth factory for creating type-safe authentication credentials
+ *
+ * @example
+ * ```typescript
+ * import { createClient, Auth } from 'kalam-link';
+ *
+ * // Basic Auth
+ * const client = createClient({
+ *   url: 'http://localhost:8080',
+ *   auth: Auth.basic('admin', 'admin')
+ * });
+ *
+ * // JWT Token
+ * const jwtClient = createClient({
+ *   url: 'http://localhost:8080',
+ *   auth: Auth.jwt('eyJhbGciOiJIUzI1NiIs...')
+ * });
+ *
+ * // Anonymous (no auth)
+ * const anonClient = createClient({
+ *   url: 'http://localhost:8080',
+ *   auth: Auth.none()
+ * });
+ * ```
+ */
+export const Auth = {
+    /**
+     * Create Basic Auth credentials
+     *
+     * @param username - Username for authentication
+     * @param password - Password for authentication
+     * @returns BasicAuthCredentials object
+     */
+    basic(username, password) {
+        return { type: 'basic', username, password };
+    },
+    /**
+     * Create JWT Auth credentials
+     *
+     * @param token - JWT token string
+     * @returns JwtAuthCredentials object
+     */
+    jwt(token) {
+        return { type: 'jwt', token };
+    },
+    /**
+     * Create No Auth credentials (anonymous access)
+     *
+     * @returns NoAuthCredentials object
+     */
+    none() {
+        return { type: 'none' };
+    }
+};