@xtr-dev/rondevu-client 0.20.1 → 0.21.3

package/dist/api/batcher.js

@@ -1,111 +1,155 @@
 /**
- * RPC Batcher - Throttles and batches RPC requests to reduce HTTP overhead
+ * RPC Request Batcher with throttling
+ *
+ * Collects RPC requests over a short time window and sends them efficiently.
+ *
+ * Due to server authentication design (signature covers method+params),
+ * authenticated requests are sent individually while unauthenticated
+ * requests can be truly batched together.
  */
 /**
- * Batches and throttles RPC requests to optimize network usage
+ * RpcBatcher - Batches RPC requests with throttling
  *
  * @example
  * ```typescript
- * const batcher = new RpcBatcher(
- *   (requests) => api.rpcBatch(requests),
- *   { maxBatchSize: 10, maxWaitTime: 50 }
- * )
+ * const batcher = new RpcBatcher('https://api.example.com', {
+ *   delay: 10,
+ *   maxBatchSize: 50
+ * })
  *
- * // These will be batched together if called within maxWaitTime
- * const result1 = await batcher.add(request1)
- * const result2 = await batcher.add(request2)
- * const result3 = await batcher.add(request3)
+ * // Requests made within the delay window are batched
+ * const [result1, result2] = await Promise.all([
+ *   batcher.add({ method: 'getOffer', params: {...} }, null),
+ *   batcher.add({ method: 'getOffer', params: {...} }, null)
+ * ])
  * ```
  */
 export class RpcBatcher {
-    constructor(sendBatch, options) {
+    constructor(baseUrl, options = {}) {
+        this.baseUrl = baseUrl;
         this.queue = [];
-        this.batchTimeout = null;
-        this.lastBatchTime = 0;
-        this.sendBatch = sendBatch;
-        this.options = {
-            maxBatchSize: options?.maxBatchSize ?? 10,
-            maxWaitTime: options?.maxWaitTime ?? 50,
-            throttleInterval: options?.throttleInterval ?? 10,
-        };
+        this.flushTimer = null;
+        this.delay = options.delay ?? 10;
+        this.maxBatchSize = options.maxBatchSize ?? 50;
     }
     /**
-     * Add an RPC request to the batch queue
-     * Returns a promise that resolves when the request completes
+     * Add a request to the batch queue
+     * @param request - The RPC request
+     * @param authHeaders - Auth headers for authenticated requests, null for unauthenticated
+     * @returns Promise that resolves with the request result
      */
-    async add(request) {
+    add(request, authHeaders) {
         return new Promise((resolve, reject) => {
-            this.queue.push({ request, resolve, reject });
-            // Send immediately if batch is full
-            if (this.queue.length >= this.options.maxBatchSize) {
-                this.flush();
-                return;
-            }
-            // Schedule batch if not already scheduled
-            if (!this.batchTimeout) {
-                this.batchTimeout = setTimeout(() => {
-                    this.flush();
-                }, this.options.maxWaitTime);
-            }
+            this.queue.push({ request, authHeaders, resolve, reject });
+            this.scheduleFlush();
         });
     }
     /**
-     * Flush the queue immediately
+     * Schedule a flush after the delay
+     */
+    scheduleFlush() {
+        if (this.flushTimer)
+            return;
+        this.flushTimer = setTimeout(() => {
+            this.flushTimer = null;
+            this.flush();
+        }, this.delay);
+    }
+    /**
+     * Flush all queued requests
      */
     async flush() {
-        // Clear timeout if set
-        if (this.batchTimeout) {
-            clearTimeout(this.batchTimeout);
-            this.batchTimeout = null;
-        }
-        // Nothing to flush
-        if (this.queue.length === 0) {
+        if (this.queue.length === 0)
             return;
-        }
-        // Throttle: wait if we sent a batch too recently
-        const now = Date.now();
-        const timeSinceLastBatch = now - this.lastBatchTime;
-        if (timeSinceLastBatch < this.options.throttleInterval) {
-            const waitTime = this.options.throttleInterval - timeSinceLastBatch;
-            await new Promise(resolve => setTimeout(resolve, waitTime));
-        }
-        // Extract requests from queue
-        const batch = this.queue.splice(0, this.options.maxBatchSize);
-        const requests = batch.map(item => item.request);
-        this.lastBatchTime = Date.now();
-        try {
-            // Send batch request
-            const results = await this.sendBatch(requests);
-            // Resolve individual promises
-            for (let i = 0; i < batch.length; i++) {
-                batch[i].resolve(results[i]);
+        const items = this.queue;
+        this.queue = [];
+        // Separate authenticated vs unauthenticated requests
+        const unauthenticated = [];
+        const authenticated = [];
+        for (const item of items) {
+            if (item.authHeaders) {
+                authenticated.push(item);
             }
-        }
-        catch (error) {
-            // Reject all promises in batch
-            for (const item of batch) {
-                item.reject(error);
+            else {
+                unauthenticated.push(item);
             }
         }
+        // Process unauthenticated requests in batches
+        await this.processUnauthenticatedBatches(unauthenticated);
+        // Process authenticated requests individually (each needs unique signature)
+        await this.processAuthenticatedRequests(authenticated);
     }
     /**
-     * Get current queue size
+     * Process unauthenticated requests in batches
      */
-    getQueueSize() {
-        return this.queue.length;
+    async processUnauthenticatedBatches(items) {
+        if (items.length === 0)
+            return;
+        // Split into chunks of maxBatchSize
+        for (let i = 0; i < items.length; i += this.maxBatchSize) {
+            const chunk = items.slice(i, i + this.maxBatchSize);
+            await this.sendBatch(chunk, null);
+        }
+    }
+    /**
+     * Process authenticated requests individually
+     * Each authenticated request needs its own HTTP call because
+     * the signature covers the specific method+params
+     */
+    async processAuthenticatedRequests(items) {
+        // Send all authenticated requests in parallel, each as its own batch of 1
+        await Promise.all(items.map(item => this.sendBatch([item], item.authHeaders)));
     }
     /**
-     * Clear the queue without sending
+     * Send a batch of requests
      */
-    clear() {
-        if (this.batchTimeout) {
-            clearTimeout(this.batchTimeout);
-            this.batchTimeout = null;
+    async sendBatch(items, authHeaders) {
+        try {
+            const requests = items.map(item => item.request);
+            const headers = {
+                'Content-Type': 'application/json',
+            };
+            if (authHeaders) {
+                Object.assign(headers, authHeaders);
+            }
+            const response = await fetch(`${this.baseUrl}/rpc`, {
+                method: 'POST',
+                headers,
+                body: JSON.stringify(requests), // Always send as array
+            });
+            if (!response.ok) {
+                const error = new Error(`HTTP ${response.status}: ${response.statusText}`);
+                items.forEach(item => item.reject(error));
+                return;
+            }
+            const results = await response.json();
+            // Match responses to requests (server returns array in same order)
+            items.forEach((item, index) => {
+                const result = results[index];
+                if (!result) {
+                    item.reject(new Error('Missing response from server'));
+                }
+                else if (!result.success) {
+                    item.reject(new Error(result.error || 'RPC call failed'));
+                }
+                else {
+                    item.resolve(result.result);
+                }
+            });
         }
-        // Reject all pending requests
-        for (const item of this.queue) {
-            item.reject(new Error('Batch queue cleared'));
+        catch (error) {
+            // Network or parsing error - reject all
+            items.forEach(item => item.reject(error));
         }
-        this.queue = [];
+    }
+    /**
+     * Flush immediately (useful for cleanup/testing)
+     */
+    async flushNow() {
+        if (this.flushTimer) {
+            clearTimeout(this.flushTimer);
+            this.flushTimer = null;
+        }
+        await this.flush();
     }
 }

package/dist/api/client.d.ts

@@ -1,29 +1,46 @@
 /**
  * Rondevu API Client - RPC interface
  */
-import { CryptoAdapter, Keypair } from '../crypto/adapter.js';
+import { CryptoAdapter, Credential } from '../crypto/adapter.js';
 import { BatcherOptions } from './batcher.js';
-export type { Keypair } from '../crypto/adapter.js';
+export type { Credential } from '../crypto/adapter.js';
 export type { BatcherOptions } from './batcher.js';
 export interface OfferRequest {
     sdp: string;
 }
-export interface ServiceRequest {
-    serviceFqn: string;
+export interface PublishRequest {
+    tags: string[];
     offers: OfferRequest[];
     ttl?: number;
 }
-export interface ServiceOffer {
+export interface DiscoverRequest {
+    tags: string[];
+    limit?: number;
+    offset?: number;
+}
+export interface TaggedOffer {
     offerId: string;
+    username: string;
+    tags: string[];
     sdp: string;
     createdAt: number;
     expiresAt: number;
 }
-export interface Service {
-    serviceId: string;
-    offers: ServiceOffer[];
+export interface DiscoverResponse {
+    offers: TaggedOffer[];
+    count: number;
+    limit: number;
+    offset: number;
+}
+export interface PublishResponse {
     username: string;
-    serviceFqn: string;
+    tags: string[];
+    offers: Array<{
+        offerId: string;
+        sdp: string;
+        createdAt: number;
+        expiresAt: number;
+    }>;
     createdAt: number;
     expiresAt: number;
 }
@@ -37,84 +54,111 @@ export interface IceCandidate {
  */
 export declare class RondevuAPI {
     private baseUrl;
-    private username;
-    private keypair;
+    private credential;
+    private static readonly DEFAULT_MAX_RETRIES;
+    private static readonly DEFAULT_TIMEOUT_MS;
+    private static readonly DEFAULT_CREDENTIAL_NAME_MAX_LENGTH;
+    private static readonly DEFAULT_SECRET_MIN_LENGTH;
+    private static readonly MAX_BACKOFF_MS;
+    private static readonly MAX_CANONICALIZE_DEPTH;
     private crypto;
     private batcher;
-    constructor(baseUrl: string, username: string, keypair: Keypair, cryptoAdapter?: CryptoAdapter, batcherOptions?: BatcherOptions | false);
+    constructor(baseUrl: string, credential: Credential, cryptoAdapter?: CryptoAdapter, batcherOptions?: BatcherOptions);
     /**
-     * Create canonical JSON string with sorted keys for deterministic signing
+     * Canonical JSON serialization with sorted keys
+     * Ensures deterministic output regardless of property insertion order
      */
     private canonicalJSON;
     /**
-     * Generate authentication headers for RPC request
-     * Signs the payload (method + params + timestamp + username)
+     * Build signature message following server format
+     * Format: timestamp:nonce:method:canonicalJSON(params || {})
+     *
+     * Uses canonical JSON (sorted keys) to ensure deterministic serialization
+     * across different JavaScript engines and platforms.
+     *
+     * Note: When params is undefined, it's serialized as "{}" (empty object).
+     * This matches the server's expectation for parameterless RPC calls.
      */
-    private generateAuthHeaders;
+    private buildSignatureMessage;
     /**
-     * Generate authentication fields embedded in request body (for batch requests)
-     * Signs the payload (method + params + timestamp + username)
+     * Generate cryptographically secure nonce
+     * Uses crypto.randomUUID() if available, falls back to secure random bytes
+     *
+     * Note: this.crypto is always initialized in constructor (WebCryptoAdapter or NodeCryptoAdapter)
+     * and TypeScript enforces that both implement randomBytes(), so the fallback is always safe.
      */
-    private generateAuthForRequest;
-    /**
-     * Execute RPC call with optional batching
-     */
-    private rpc;
+    private generateNonce;
     /**
-     * Execute single RPC call directly (bypasses batcher)
-     */
-    private rpcDirect;
-    /**
-     * Execute batch RPC calls directly (bypasses batcher)
-     * Each request in the batch has its own embedded authentication (signature, timestamp, username, publicKey)
-     */
-    private rpcBatchDirect;
-    /**
-     * Generate an Ed25519 keypair for username claiming and service publishing
-     * @param cryptoAdapter - Optional crypto adapter (defaults to WebCryptoAdapter)
-     */
-    static generateKeypair(cryptoAdapter?: CryptoAdapter): Promise<Keypair>;
-    /**
-     * Sign a message with an Ed25519 private key
-     * @param cryptoAdapter - Optional crypto adapter (defaults to WebCryptoAdapter)
+     * Generate authentication headers for RPC request
+     * Uses HMAC-SHA256 signature with nonce for replay protection
+     *
+     * Security notes:
+     * - Nonce: Cryptographically secure random value (UUID or 128-bit hex)
+     * - Timestamp: Prevents replay attacks outside the server's time window
+     *   - Server validates timestamp is within acceptable range (typically ±5 minutes)
+     *   - Tolerates reasonable clock skew between client and server
+     *   - Requests with stale timestamps are rejected
+     * - Signature: HMAC-SHA256 ensures message integrity and authenticity
+     * - Server validates nonce uniqueness to prevent replay within time window
+     *   - Each nonce can only be used once within the timestamp validity window
+     *   - Server maintains nonce cache with expiration matching timestamp window
      */
-    static signMessage(message: string, privateKeyBase64: string, cryptoAdapter?: CryptoAdapter): Promise<string>;
+    private generateAuthHeaders;
     /**
-     * Verify an Ed25519 signature
-     * @param cryptoAdapter - Optional crypto adapter (defaults to WebCryptoAdapter)
+     * Execute RPC call via batcher
+     * Requests are batched with throttling for efficiency
      */
-    static verifySignature(message: string, signatureBase64: string, publicKeyBase64: string, cryptoAdapter?: CryptoAdapter): Promise<boolean>;
+    private rpc;
     /**
-     * Check if a username is available
+     * Generate new credentials (name + secret pair)
+     * This is the entry point for new users - no authentication required
+     * Credentials are generated server-side to ensure security and uniqueness
+     *
+     * ⚠️ SECURITY NOTE:
+     * - Store the returned credential securely
+     * - The secret provides full access to this identity
+     * - Credentials should be persisted encrypted and never logged
+     *
+     * @param baseUrl - Rondevu server URL
+     * @param expiresAt - Optional custom expiry timestamp (defaults to 1 year)
+     * @param options - Optional: { maxRetries: number, timeout: number }
+     * @returns Generated credential with name and secret
      */
-    isUsernameAvailable(username: string): Promise<boolean>;
+    static generateCredentials(baseUrl: string, options?: {
+        name?: string;
+        expiresAt?: number;
+        maxRetries?: number;
+        timeout?: number;
+    }): Promise<Credential>;
     /**
-     * Check if current username is claimed
+     * Generate a random secret locally (for advanced use cases)
+     * @param cryptoAdapter - Optional crypto adapter
      */
-    isUsernameClaimed(): Promise<boolean>;
+    static generateSecret(cryptoAdapter?: CryptoAdapter): string;
     /**
-     * Publish a service
+     * Publish offers with tags
      */
-    publishService(service: ServiceRequest): Promise<Service>;
+    publish(request: PublishRequest): Promise<PublishResponse>;
     /**
-     * Get service by FQN (direct lookup, random, or paginated)
+     * Discover offers by tags
+     * @param request - Discovery request with tags and optional pagination
+     * @returns Paginated response if limit provided, single offer if not
      */
-    getService(serviceFqn: string, options?: {
-        limit?: number;
-        offset?: number;
-    }): Promise<any>;
+    discover(request: DiscoverRequest): Promise<DiscoverResponse | TaggedOffer>;
     /**
-     * Delete a service
+     * Delete an offer by ID
      */
-    deleteService(serviceFqn: string): Promise<void>;
+    deleteOffer(offerId: string): Promise<{
+        success: boolean;
+    }>;
     /**
      * Answer an offer
      */
-    answerOffer(serviceFqn: string, offerId: string, sdp: string): Promise<void>;
+    answerOffer(offerId: string, sdp: string): Promise<void>;
     /**
      * Get answer for a specific offer (offerer polls this)
      */
-    getOfferAnswer(serviceFqn: string, offerId: string): Promise<{
+    getOfferAnswer(offerId: string): Promise<{
         sdp: string;
         offerId: string;
         answererId: string;
@@ -126,7 +170,6 @@ export declare class RondevuAPI {
     poll(since?: number): Promise<{
         answers: Array<{
             offerId: string;
-            serviceId?: string;
             answererId: string;
             sdp: string;
             answeredAt: number;
@@ -141,14 +184,14 @@ export declare class RondevuAPI {
     /**
      * Add ICE candidates to a specific offer
      */
-    addOfferIceCandidates(serviceFqn: string, offerId: string, candidates: RTCIceCandidateInit[]): Promise<{
+    addOfferIceCandidates(offerId: string, candidates: RTCIceCandidateInit[]): Promise<{
         count: number;
         offerId: string;
     }>;
     /**
      * Get ICE candidates for a specific offer
      */
-    getOfferIceCandidates(serviceFqn: string, offerId: string, since?: number): Promise<{
+    getOfferIceCandidates(offerId: string, since?: number): Promise<{
         candidates: IceCandidate[];
         offerId: string;
     }>;