@findatruck/convex-client 0.1.0 → 0.2.1

package/dist/index.cjs

@@ -65,11 +65,19 @@ var ConvexClient = class {
   constructor(config) {
     this.baseUrl = config.baseUrl.replace(/\/$/, "");
     this.workerSecret = config.workerSecret;
+    this.retryConfig = {
+      maxAttempts: config.retry?.maxAttempts ?? 5,
+      baseDelayMs: config.retry?.baseDelayMs ?? 250,
+      maxDelayMs: config.retry?.maxDelayMs ?? 15e3,
+      maxElapsedMs: config.retry?.maxElapsedMs ?? 6e4,
+      perAttemptTimeoutMs: config.retry?.perAttemptTimeoutMs ?? 2e4
+    };
   }
   /**
    * Posts driver view data to the Convex ingestion endpoint.
+   * Uses retry logic with exponential backoff for resilience.
    */
-  async postDriverView(data) {
+  async postDriverView(data, options) {
     const route = routes.ingestDriverView;
     const parseResult = route.requestSchema.safeParse(data);
     if (!parseResult.success) {
@@ -78,12 +86,14 @@ var ConvexClient = class {
         route.path
       );
     }
-    await this.makeRequest(route.path, route.method, data);
+    const effectiveBaseUrl = options?.baseUrl?.replace(/\/$/, "") ?? this.baseUrl;
+    await this.makeRequestWithRetry(effectiveBaseUrl, route.path, route.method, data);
   }
   /**
    * Posts provider account status updates to the Convex ingestion endpoint.
+   * Does NOT use retry logic (single attempt only).
    */
-  async postProviderAccountStatus(data) {
+  async postProviderAccountStatus(data, options) {
     const route = routes.ingestProviderAccountStatus;
     const parseResult = route.requestSchema.safeParse(data);
     if (!parseResult.success) {
@@ -92,15 +102,16 @@ var ConvexClient = class {
         route.path
       );
     }
-    await this.makeRequest(route.path, route.method, data);
+    const effectiveBaseUrl = options?.baseUrl?.replace(/\/$/, "") ?? this.baseUrl;
+    await this.makeRequest(effectiveBaseUrl, route.path, route.method, data);
   }
-  async makeRequest(path, method, body) {
-    const url = `${this.baseUrl}${path}`;
+  async makeRequest(baseUrl, path, method, body) {
+    const url = `${baseUrl}${path}`;
     const response = await fetch(url, {
       method,
       headers: {
         "Content-Type": "application/json",
-        "Authorization": `Bearer ${this.workerSecret}`
+        "x-worker-secret": this.workerSecret
       },
       body: JSON.stringify(body)
     });
@@ -119,21 +130,151 @@ var ConvexClient = class {
       );
     }
   }
+  async makeRequestWithRetry(baseUrl, path, method, body) {
+    const url = `${baseUrl}${path}`;
+    const { maxAttempts, baseDelayMs, maxDelayMs, maxElapsedMs, perAttemptTimeoutMs } = this.retryConfig;
+    const retryOnStatuses = [429, 500, 502, 503, 504];
+    const startedAt = Date.now();
+    let attempt = 0;
+    const calcBackoff = (retriesSoFar) => Math.floor(Math.random() * Math.min(maxDelayMs, baseDelayMs * 2 ** retriesSoFar));
+    while (true) {
+      attempt += 1;
+      if (Date.now() - startedAt > maxElapsedMs) {
+        throw new ConvexClientError(
+          `Request to ${path} exceeded max elapsed time ${maxElapsedMs}ms`,
+          path
+        );
+      }
+      let response;
+      let error;
+      try {
+        response = await this.attemptFetch(url, method, body, perAttemptTimeoutMs);
+        if (response.ok) return;
+        if (!retryOnStatuses.includes(response.status)) {
+          let responseBody;
+          try {
+            responseBody = await response.json();
+          } catch {
+            responseBody = await response.text();
+          }
+          throw new ConvexClientError(
+            `Request to ${path} failed with status ${response.status}`,
+            path,
+            response.status,
+            responseBody
+          );
+        }
+      } catch (e) {
+        error = e;
+        if (e instanceof ConvexClientError) throw e;
+        if (this.isAbortError(e)) throw e;
+      }
+      if (attempt >= maxAttempts) {
+        if (response) {
+          let responseBody;
+          try {
+            responseBody = await response.json();
+          } catch {
+            responseBody = await response.text();
+          }
+          throw new ConvexClientError(
+            `Request to ${path} failed after ${attempt} attempts with status ${response.status}`,
+            path,
+            response.status,
+            responseBody
+          );
+        }
+        if (error instanceof Error) throw error;
+        throw new ConvexClientError(
+          `Request to ${path} failed without response after ${attempt} attempts`,
+          path
+        );
+      }
+      let delayMs = 0;
+      const retryAfter = response?.headers.get("retry-after");
+      if (retryAfter) {
+        const parsed = this.parseRetryAfter(retryAfter);
+        if (parsed != null) delayMs = Math.min(parsed, maxDelayMs);
+      }
+      if (delayMs === 0) {
+        delayMs = calcBackoff(attempt - 1);
+      }
+      const elapsed = Date.now() - startedAt;
+      if (elapsed + delayMs > maxElapsedMs) {
+        delayMs = Math.max(0, maxElapsedMs - elapsed);
+        if (delayMs === 0) {
+          if (response) {
+            throw new ConvexClientError(
+              `Request to ${path} time budget exhausted before retry`,
+              path,
+              response.status
+            );
+          }
+          if (error instanceof Error) throw error;
+          throw new ConvexClientError(
+            `Request to ${path} time budget exhausted before retry`,
+            path
+          );
+        }
+      }
+      await this.sleep(delayMs);
+    }
+  }
+  async attemptFetch(url, method, body, perAttemptTimeoutMs) {
+    const controller = new AbortController();
+    const timeoutId = perAttemptTimeoutMs > 0 ? setTimeout(() => {
+      controller.abort(new Error(`per-attempt timeout ${perAttemptTimeoutMs}ms`));
+    }, perAttemptTimeoutMs) : null;
+    try {
+      return await fetch(url, {
+        method,
+        headers: {
+          "Content-Type": "application/json",
+          "x-worker-secret": this.workerSecret
+        },
+        body: JSON.stringify(body),
+        signal: controller.signal
+      });
+    } finally {
+      if (timeoutId) clearTimeout(timeoutId);
+    }
+  }
+  parseRetryAfter(value) {
+    const secs = Number(value);
+    if (Number.isFinite(secs)) return Math.max(0, secs * 1e3);
+    const dateMs = Date.parse(value);
+    if (!Number.isNaN(dateMs)) {
+      const delta = dateMs - Date.now();
+      return Math.max(0, delta);
+    }
+    return null;
+  }
+  sleep(ms) {
+    return new Promise((resolve) => {
+      if (ms <= 0) {
+        resolve();
+        return;
+      }
+      setTimeout(resolve, ms);
+    });
+  }
+  isAbortError(err) {
+    return err instanceof DOMException && err.name === "AbortError" || err instanceof Error && /abort/i.test(err.name + " " + err.message);
+  }
 };
 
 // src/validation.ts
 function checkWorkerSecret(req, expectedSecret) {
-  const authHeader = req.headers.get("Authorization");
-  if (!authHeader) {
+  const secretHeader = req.headers.get("x-worker-secret");
+  if (!secretHeader) {
     return false;
   }
-  const expectedValue = `Bearer ${expectedSecret}`;
-  if (authHeader.length !== expectedValue.length) {
+  if (secretHeader.length !== expectedSecret.length) {
     return false;
   }
   let result = 0;
-  for (let i = 0; i < authHeader.length; i++) {
-    result |= authHeader.charCodeAt(i) ^ expectedValue.charCodeAt(i);
+  for (let i = 0; i < secretHeader.length; i++) {
+    result |= secretHeader.charCodeAt(i) ^ expectedSecret.charCodeAt(i);
   }
   return result === 0;
 }

package/dist/index.d.cts

@@ -3,6 +3,21 @@ import { ConvexUpdateData, UpdateScrapeStatusMessage } from '@findatruck/shared-
 export { BatchConvexUpdateData, BatchConvexUpdateSchema, ConvexDriverData, ConvexDriverSchema, ConvexUpdateData, ConvexUpdateSchema, ScrapeStatus, UpdateScrapeStatusMessage, UpdateScrapeStatusMessage as UpdateScrapeStatusMessageType } from '@findatruck/shared-schemas';
 import { z } from 'zod';
 
+/**
+ * Configuration for retry behavior
+ */
+interface RetryConfig {
+    /** Max number of attempts (first try + retries). Default: 5 */
+    maxAttempts?: number;
+    /** Base delay in ms before backoff. Default: 250 */
+    baseDelayMs?: number;
+    /** Max delay cap in ms. Default: 15_000 */
+    maxDelayMs?: number;
+    /** Max total elapsed time budget in ms (includes all attempts). Default: 60_000 */
+    maxElapsedMs?: number;
+    /** Per-attempt timeout in ms. Default: 20_000 */
+    perAttemptTimeoutMs?: number;
+}
 /**
  * Configuration for the ConvexClient
  */
@@ -11,6 +26,15 @@ interface ConvexClientConfig {
     baseUrl: string;
     /** Worker shared secret for authentication */
     workerSecret: string;
+    /** Optional retry configuration for postDriverView (postProviderAccountStatus does not retry) */
+    retry?: RetryConfig;
+}
+/**
+ * Options for individual request methods
+ */
+interface RequestOptions {
+    /** Override the base URL for this specific request */
+    baseUrl?: string;
 }
 /**
  * Error thrown by the ConvexClient when requests fail
@@ -40,6 +64,10 @@ type ValidationResult<T> = {
  * const client = new ConvexClient({
  *   baseUrl: process.env.CONVEX_HTTP_URL,
  *   workerSecret: process.env.WORKER_SHARED_SECRET,
+ *   retry: {
+ *     maxAttempts: 5,
+ *     perAttemptTimeoutMs: 5000,
+ *   },
  * });
  *
  * await client.postDriverView(convexUpdate);
@@ -49,16 +77,24 @@ type ValidationResult<T> = {
 declare class ConvexClient {
     private readonly baseUrl;
     private readonly workerSecret;
+    private readonly retryConfig;
     constructor(config: ConvexClientConfig);
     /**
      * Posts driver view data to the Convex ingestion endpoint.
+     * Uses retry logic with exponential backoff for resilience.
      */
-    postDriverView(data: ConvexUpdateData): Promise<void>;
+    postDriverView(data: ConvexUpdateData, options?: RequestOptions): Promise<void>;
     /**
      * Posts provider account status updates to the Convex ingestion endpoint.
+     * Does NOT use retry logic (single attempt only).
      */
-    postProviderAccountStatus(data: UpdateScrapeStatusMessage): Promise<void>;
+    postProviderAccountStatus(data: UpdateScrapeStatusMessage, options?: RequestOptions): Promise<void>;
     private makeRequest;
+    private makeRequestWithRetry;
+    private attemptFetch;
+    private parseRetryAfter;
+    private sleep;
+    private isAbortError;
 }
 
 /**
@@ -121,7 +157,7 @@ type RouteName = keyof typeof routes;
 
 /**
  * Constant-time string comparison to prevent timing attacks.
- * Returns true if the Authorization header matches the expected Bearer token.
+ * Returns true if the x-worker-secret header matches the expected secret.
  */
 declare function checkWorkerSecret(req: Request, expectedSecret: string): boolean;
 /**
@@ -151,4 +187,4 @@ declare const responses: {
     readonly serverError: (error?: string) => Response;
 };
 
-export { ConvexClient, type ConvexClientConfig, ConvexClientError, type RouteDefinition, type RouteName, type ValidationResult, checkWorkerSecret, parseAndValidate, responses, routes };
+export { ConvexClient, type ConvexClientConfig, ConvexClientError, type RequestOptions, type RetryConfig, type RouteDefinition, type RouteName, type ValidationResult, checkWorkerSecret, parseAndValidate, responses, routes };

package/dist/index.d.ts

@@ -3,6 +3,21 @@ import { ConvexUpdateData, UpdateScrapeStatusMessage } from '@findatruck/shared-
 export { BatchConvexUpdateData, BatchConvexUpdateSchema, ConvexDriverData, ConvexDriverSchema, ConvexUpdateData, ConvexUpdateSchema, ScrapeStatus, UpdateScrapeStatusMessage, UpdateScrapeStatusMessage as UpdateScrapeStatusMessageType } from '@findatruck/shared-schemas';
 import { z } from 'zod';
 
+/**
+ * Configuration for retry behavior
+ */
+interface RetryConfig {
+    /** Max number of attempts (first try + retries). Default: 5 */
+    maxAttempts?: number;
+    /** Base delay in ms before backoff. Default: 250 */
+    baseDelayMs?: number;
+    /** Max delay cap in ms. Default: 15_000 */
+    maxDelayMs?: number;
+    /** Max total elapsed time budget in ms (includes all attempts). Default: 60_000 */
+    maxElapsedMs?: number;
+    /** Per-attempt timeout in ms. Default: 20_000 */
+    perAttemptTimeoutMs?: number;
+}
 /**
  * Configuration for the ConvexClient
  */
@@ -11,6 +26,15 @@ interface ConvexClientConfig {
     baseUrl: string;
     /** Worker shared secret for authentication */
     workerSecret: string;
+    /** Optional retry configuration for postDriverView (postProviderAccountStatus does not retry) */
+    retry?: RetryConfig;
+}
+/**
+ * Options for individual request methods
+ */
+interface RequestOptions {
+    /** Override the base URL for this specific request */
+    baseUrl?: string;
 }
 /**
  * Error thrown by the ConvexClient when requests fail
@@ -40,6 +64,10 @@ type ValidationResult<T> = {
  * const client = new ConvexClient({
  *   baseUrl: process.env.CONVEX_HTTP_URL,
  *   workerSecret: process.env.WORKER_SHARED_SECRET,
+ *   retry: {
+ *     maxAttempts: 5,
+ *     perAttemptTimeoutMs: 5000,
+ *   },
  * });
  *
  * await client.postDriverView(convexUpdate);
@@ -49,16 +77,24 @@ type ValidationResult<T> = {
 declare class ConvexClient {
     private readonly baseUrl;
     private readonly workerSecret;
+    private readonly retryConfig;
     constructor(config: ConvexClientConfig);
     /**
      * Posts driver view data to the Convex ingestion endpoint.
+     * Uses retry logic with exponential backoff for resilience.
      */
-    postDriverView(data: ConvexUpdateData): Promise<void>;
+    postDriverView(data: ConvexUpdateData, options?: RequestOptions): Promise<void>;
     /**
      * Posts provider account status updates to the Convex ingestion endpoint.
+     * Does NOT use retry logic (single attempt only).
      */
-    postProviderAccountStatus(data: UpdateScrapeStatusMessage): Promise<void>;
+    postProviderAccountStatus(data: UpdateScrapeStatusMessage, options?: RequestOptions): Promise<void>;
     private makeRequest;
+    private makeRequestWithRetry;
+    private attemptFetch;
+    private parseRetryAfter;
+    private sleep;
+    private isAbortError;
 }
 
 /**
@@ -121,7 +157,7 @@ type RouteName = keyof typeof routes;
 
 /**
  * Constant-time string comparison to prevent timing attacks.
- * Returns true if the Authorization header matches the expected Bearer token.
+ * Returns true if the x-worker-secret header matches the expected secret.
  */
 declare function checkWorkerSecret(req: Request, expectedSecret: string): boolean;
 /**
@@ -151,4 +187,4 @@ declare const responses: {
     readonly serverError: (error?: string) => Response;
 };
 
-export { ConvexClient, type ConvexClientConfig, ConvexClientError, type RouteDefinition, type RouteName, type ValidationResult, checkWorkerSecret, parseAndValidate, responses, routes };
+export { ConvexClient, type ConvexClientConfig, ConvexClientError, type RequestOptions, type RetryConfig, type RouteDefinition, type RouteName, type ValidationResult, checkWorkerSecret, parseAndValidate, responses, routes };

package/dist/index.js

@@ -32,11 +32,19 @@ var ConvexClient = class {
   constructor(config) {
     this.baseUrl = config.baseUrl.replace(/\/$/, "");
     this.workerSecret = config.workerSecret;
+    this.retryConfig = {
+      maxAttempts: config.retry?.maxAttempts ?? 5,
+      baseDelayMs: config.retry?.baseDelayMs ?? 250,
+      maxDelayMs: config.retry?.maxDelayMs ?? 15e3,
+      maxElapsedMs: config.retry?.maxElapsedMs ?? 6e4,
+      perAttemptTimeoutMs: config.retry?.perAttemptTimeoutMs ?? 2e4
+    };
   }
   /**
    * Posts driver view data to the Convex ingestion endpoint.
+   * Uses retry logic with exponential backoff for resilience.
    */
-  async postDriverView(data) {
+  async postDriverView(data, options) {
     const route = routes.ingestDriverView;
     const parseResult = route.requestSchema.safeParse(data);
     if (!parseResult.success) {
@@ -45,12 +53,14 @@ var ConvexClient = class {
         route.path
       );
     }
-    await this.makeRequest(route.path, route.method, data);
+    const effectiveBaseUrl = options?.baseUrl?.replace(/\/$/, "") ?? this.baseUrl;
+    await this.makeRequestWithRetry(effectiveBaseUrl, route.path, route.method, data);
   }
   /**
    * Posts provider account status updates to the Convex ingestion endpoint.
+   * Does NOT use retry logic (single attempt only).
    */
-  async postProviderAccountStatus(data) {
+  async postProviderAccountStatus(data, options) {
     const route = routes.ingestProviderAccountStatus;
     const parseResult = route.requestSchema.safeParse(data);
     if (!parseResult.success) {
@@ -59,15 +69,16 @@ var ConvexClient = class {
         route.path
       );
     }
-    await this.makeRequest(route.path, route.method, data);
+    const effectiveBaseUrl = options?.baseUrl?.replace(/\/$/, "") ?? this.baseUrl;
+    await this.makeRequest(effectiveBaseUrl, route.path, route.method, data);
   }
-  async makeRequest(path, method, body) {
-    const url = `${this.baseUrl}${path}`;
+  async makeRequest(baseUrl, path, method, body) {
+    const url = `${baseUrl}${path}`;
     const response = await fetch(url, {
       method,
       headers: {
         "Content-Type": "application/json",
-        "Authorization": `Bearer ${this.workerSecret}`
+        "x-worker-secret": this.workerSecret
       },
       body: JSON.stringify(body)
     });
@@ -86,21 +97,151 @@ var ConvexClient = class {
       );
     }
   }
+  async makeRequestWithRetry(baseUrl, path, method, body) {
+    const url = `${baseUrl}${path}`;
+    const { maxAttempts, baseDelayMs, maxDelayMs, maxElapsedMs, perAttemptTimeoutMs } = this.retryConfig;
+    const retryOnStatuses = [429, 500, 502, 503, 504];
+    const startedAt = Date.now();
+    let attempt = 0;
+    const calcBackoff = (retriesSoFar) => Math.floor(Math.random() * Math.min(maxDelayMs, baseDelayMs * 2 ** retriesSoFar));
+    while (true) {
+      attempt += 1;
+      if (Date.now() - startedAt > maxElapsedMs) {
+        throw new ConvexClientError(
+          `Request to ${path} exceeded max elapsed time ${maxElapsedMs}ms`,
+          path
+        );
+      }
+      let response;
+      let error;
+      try {
+        response = await this.attemptFetch(url, method, body, perAttemptTimeoutMs);
+        if (response.ok) return;
+        if (!retryOnStatuses.includes(response.status)) {
+          let responseBody;
+          try {
+            responseBody = await response.json();
+          } catch {
+            responseBody = await response.text();
+          }
+          throw new ConvexClientError(
+            `Request to ${path} failed with status ${response.status}`,
+            path,
+            response.status,
+            responseBody
+          );
+        }
+      } catch (e) {
+        error = e;
+        if (e instanceof ConvexClientError) throw e;
+        if (this.isAbortError(e)) throw e;
+      }
+      if (attempt >= maxAttempts) {
+        if (response) {
+          let responseBody;
+          try {
+            responseBody = await response.json();
+          } catch {
+            responseBody = await response.text();
+          }
+          throw new ConvexClientError(
+            `Request to ${path} failed after ${attempt} attempts with status ${response.status}`,
+            path,
+            response.status,
+            responseBody
+          );
+        }
+        if (error instanceof Error) throw error;
+        throw new ConvexClientError(
+          `Request to ${path} failed without response after ${attempt} attempts`,
+          path
+        );
+      }
+      let delayMs = 0;
+      const retryAfter = response?.headers.get("retry-after");
+      if (retryAfter) {
+        const parsed = this.parseRetryAfter(retryAfter);
+        if (parsed != null) delayMs = Math.min(parsed, maxDelayMs);
+      }
+      if (delayMs === 0) {
+        delayMs = calcBackoff(attempt - 1);
+      }
+      const elapsed = Date.now() - startedAt;
+      if (elapsed + delayMs > maxElapsedMs) {
+        delayMs = Math.max(0, maxElapsedMs - elapsed);
+        if (delayMs === 0) {
+          if (response) {
+            throw new ConvexClientError(
+              `Request to ${path} time budget exhausted before retry`,
+              path,
+              response.status
+            );
+          }
+          if (error instanceof Error) throw error;
+          throw new ConvexClientError(
+            `Request to ${path} time budget exhausted before retry`,
+            path
+          );
+        }
+      }
+      await this.sleep(delayMs);
+    }
+  }
+  async attemptFetch(url, method, body, perAttemptTimeoutMs) {
+    const controller = new AbortController();
+    const timeoutId = perAttemptTimeoutMs > 0 ? setTimeout(() => {
+      controller.abort(new Error(`per-attempt timeout ${perAttemptTimeoutMs}ms`));
+    }, perAttemptTimeoutMs) : null;
+    try {
+      return await fetch(url, {
+        method,
+        headers: {
+          "Content-Type": "application/json",
+          "x-worker-secret": this.workerSecret
+        },
+        body: JSON.stringify(body),
+        signal: controller.signal
+      });
+    } finally {
+      if (timeoutId) clearTimeout(timeoutId);
+    }
+  }
+  parseRetryAfter(value) {
+    const secs = Number(value);
+    if (Number.isFinite(secs)) return Math.max(0, secs * 1e3);
+    const dateMs = Date.parse(value);
+    if (!Number.isNaN(dateMs)) {
+      const delta = dateMs - Date.now();
+      return Math.max(0, delta);
+    }
+    return null;
+  }
+  sleep(ms) {
+    return new Promise((resolve) => {
+      if (ms <= 0) {
+        resolve();
+        return;
+      }
+      setTimeout(resolve, ms);
+    });
+  }
+  isAbortError(err) {
+    return err instanceof DOMException && err.name === "AbortError" || err instanceof Error && /abort/i.test(err.name + " " + err.message);
+  }
 };
 
 // src/validation.ts
 function checkWorkerSecret(req, expectedSecret) {
-  const authHeader = req.headers.get("Authorization");
-  if (!authHeader) {
+  const secretHeader = req.headers.get("x-worker-secret");
+  if (!secretHeader) {
     return false;
   }
-  const expectedValue = `Bearer ${expectedSecret}`;
-  if (authHeader.length !== expectedValue.length) {
+  if (secretHeader.length !== expectedSecret.length) {
     return false;
   }
   let result = 0;
-  for (let i = 0; i < authHeader.length; i++) {
-    result |= authHeader.charCodeAt(i) ^ expectedValue.charCodeAt(i);
+  for (let i = 0; i < secretHeader.length; i++) {
+    result |= secretHeader.charCodeAt(i) ^ expectedSecret.charCodeAt(i);
   }
   return result === 0;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@findatruck/convex-client",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "type": "module",
   "main": "./dist/index.cjs",
   "module": "./dist/index.js",
@@ -23,7 +23,7 @@
     "test:watch": "vitest"
   },
   "dependencies": {
-    "@findatruck/shared-schemas": "^2.9.0"
+    "@findatruck/shared-schemas": "^2.10.0"
   },
   "peerDependencies": {
     "zod": "^4.1.11"