@vaiftechnologies/vaif-client 0.1.2 → 0.2.0

package/dist/index.cjs

@@ -25,21 +25,142 @@ __export(index_exports, {
   VaifAdmin: () => VaifAdmin,
   VaifApiKeys: () => VaifApiKeys,
   VaifAuth: () => VaifAuth,
+  VaifAuthError: () => VaifAuthError,
   VaifClient: () => VaifClient,
+  VaifConflictError: () => VaifConflictError,
   VaifDatabase: () => VaifDatabase,
+  VaifError: () => VaifError,
   VaifFunctions: () => VaifFunctions,
   VaifIntegrations: () => VaifIntegrations,
+  VaifNetworkError: () => VaifNetworkError,
+  VaifNotFoundError: () => VaifNotFoundError,
   VaifProjects: () => VaifProjects,
+  VaifRateLimitError: () => VaifRateLimitError,
   VaifRealtime: () => VaifRealtime,
   VaifSchema: () => VaifSchema,
   VaifStorage: () => VaifStorage,
+  VaifTimeoutError: () => VaifTimeoutError,
   VaifTypeGen: () => VaifTypeGen,
+  VaifValidationError: () => VaifValidationError,
   createClient: () => createClient,
   createTypeGen: () => createTypeGen,
-  createVaifClient: () => createClient
+  createVaifClient: () => createClient,
+  isVaifAuthError: () => isVaifAuthError,
+  isVaifConflictError: () => isVaifConflictError,
+  isVaifError: () => isVaifError,
+  isVaifNetworkError: () => isVaifNetworkError,
+  isVaifNotFoundError: () => isVaifNotFoundError,
+  isVaifRateLimitError: () => isVaifRateLimitError,
+  isVaifTimeoutError: () => isVaifTimeoutError,
+  isVaifValidationError: () => isVaifValidationError
 });
 module.exports = __toCommonJS(index_exports);
 
+// src/errors.ts
+var VaifError = class _VaifError extends Error {
+  constructor(message, options) {
+    super(message);
+    this.name = "VaifError";
+    this.code = options.code;
+    this.statusCode = options.statusCode;
+    this.requestId = options.requestId;
+    this.details = options.details;
+    const ErrorWithCapture = Error;
+    if (ErrorWithCapture.captureStackTrace) {
+      ErrorWithCapture.captureStackTrace(this, _VaifError);
+    }
+  }
+  toJSON() {
+    return {
+      name: this.name,
+      message: this.message,
+      code: this.code,
+      statusCode: this.statusCode,
+      requestId: this.requestId,
+      details: this.details
+    };
+  }
+};
+var VaifAuthError = class extends VaifError {
+  constructor(message, options) {
+    super(message, {
+      code: options?.code ?? "AUTH_ERROR",
+      statusCode: options?.statusCode ?? 401,
+      requestId: options?.requestId
+    });
+    this.name = "VaifAuthError";
+  }
+};
+var VaifValidationError = class extends VaifError {
+  constructor(message, options) {
+    super(message, {
+      code: "VALIDATION_ERROR",
+      statusCode: 400,
+      requestId: options?.requestId,
+      details: options?.details ?? options?.fieldErrors
+    });
+    this.name = "VaifValidationError";
+    this.fieldErrors = options?.fieldErrors;
+  }
+};
+var VaifNetworkError = class extends VaifError {
+  constructor(message, cause) {
+    super(message, { code: "NETWORK_ERROR" });
+    this.name = "VaifNetworkError";
+    this.cause = cause;
+  }
+};
+var VaifRateLimitError = class extends VaifError {
+  constructor(message, retryAfter) {
+    super(message, { code: "RATE_LIMITED", statusCode: 429 });
+    this.name = "VaifRateLimitError";
+    this.retryAfter = retryAfter;
+  }
+};
+var VaifNotFoundError = class extends VaifError {
+  constructor(message, requestId) {
+    super(message, { code: "NOT_FOUND", statusCode: 404, requestId });
+    this.name = "VaifNotFoundError";
+  }
+};
+var VaifConflictError = class extends VaifError {
+  constructor(message, requestId) {
+    super(message, { code: "CONFLICT", statusCode: 409, requestId });
+    this.name = "VaifConflictError";
+  }
+};
+var VaifTimeoutError = class extends VaifNetworkError {
+  constructor(message, timeoutMs) {
+    super(message);
+    this.name = "VaifTimeoutError";
+    this.timeoutMs = timeoutMs;
+  }
+};
+function isVaifError(error) {
+  return error instanceof VaifError;
+}
+function isVaifAuthError(error) {
+  return error instanceof VaifAuthError;
+}
+function isVaifValidationError(error) {
+  return error instanceof VaifValidationError;
+}
+function isVaifNetworkError(error) {
+  return error instanceof VaifNetworkError;
+}
+function isVaifRateLimitError(error) {
+  return error instanceof VaifRateLimitError;
+}
+function isVaifNotFoundError(error) {
+  return error instanceof VaifNotFoundError;
+}
+function isVaifConflictError(error) {
+  return error instanceof VaifConflictError;
+}
+function isVaifTimeoutError(error) {
+  return error instanceof VaifTimeoutError;
+}
+
 // src/lib/database.ts
 var VaifDatabase = class {
   constructor(client) {
@@ -48,6 +169,9 @@ var VaifDatabase = class {
   /**
    * Start a query on a table
    *
+   * @param table - Table name to query
+   * @returns A query builder for chaining operations
+   *
    * @example
    * ```typescript
    * const users = await vaif.db.from('users').select('*').execute();
@@ -59,6 +183,10 @@ var VaifDatabase = class {
   /**
    * Execute raw SQL query (admin only)
    *
+   * @param sql - SQL query string with $1, $2, etc. parameter placeholders
+   * @param params - Parameter values for the query
+   * @returns Query result with typed rows
+   *
    * @example
    * ```typescript
    * const result = await vaif.db.raw('SELECT * FROM users WHERE id = $1', [userId]);
@@ -86,7 +214,16 @@ var VaifDatabase = class {
     };
   }
   /**
-   * Execute a function (stored procedure)
+   * Execute a stored procedure (RPC call)
+   *
+   * @param functionName - Name of the database function to call
+   * @param params - Parameters to pass to the function
+   * @returns Query result with the function's return value
+   *
+   * @example
+   * ```typescript
+   * const result = await vaif.db.rpc('get_user_stats', { userId: '123' });
+   * ```
    */
   async rpc(functionName, params) {
     const response = await this.client.request(`/db/rpc/${functionName}`, {
@@ -175,72 +312,85 @@ var QueryBuilder = class {
     this.onConflictUpdate = data;
     return this;
   }
-  // Filter methods
+  /** Filter by equality (column = value) */
   eq(column, value) {
     this.addFilter(column, this.negateNext ? "neq" : "eq", value);
     this.negateNext = false;
     return this;
   }
+  /** Filter by inequality (column != value) */
   neq(column, value) {
     this.addFilter(column, this.negateNext ? "eq" : "neq", value);
     this.negateNext = false;
     return this;
   }
+  /** Filter by greater than (column > value) */
   gt(column, value) {
     this.addFilter(column, this.negateNext ? "lte" : "gt", value);
     this.negateNext = false;
     return this;
   }
+  /** Filter by greater than or equal (column >= value) */
   gte(column, value) {
     this.addFilter(column, this.negateNext ? "lt" : "gte", value);
     this.negateNext = false;
     return this;
   }
+  /** Filter by less than (column < value) */
   lt(column, value) {
     this.addFilter(column, this.negateNext ? "gte" : "lt", value);
     this.negateNext = false;
     return this;
   }
+  /** Filter by less than or equal (column <= value) */
   lte(column, value) {
     this.addFilter(column, this.negateNext ? "gt" : "lte", value);
     this.negateNext = false;
     return this;
   }
+  /** Filter by pattern matching (case-sensitive LIKE) */
   like(column, pattern) {
     this.addFilter(column, this.negateNext ? "nlike" : "like", pattern);
     this.negateNext = false;
     return this;
   }
+  /** Filter by pattern matching (case-insensitive ILIKE) */
   ilike(column, pattern) {
     this.addFilter(column, this.negateNext ? "nilike" : "ilike", pattern);
     this.negateNext = false;
     return this;
   }
+  /** Filter by IS (null/boolean checks) */
   is(column, value) {
     this.addFilter(column, this.negateNext ? "isnot" : "is", value);
     this.negateNext = false;
     return this;
   }
+  /** Filter by inclusion in an array of values */
   in(column, values) {
     this.addFilter(column, this.negateNext ? "nin" : "in", values);
     this.negateNext = false;
     return this;
   }
+  /** Filter by array containment (@>) */
   contains(column, value) {
     this.addFilter(column, "cs", value);
     this.negateNext = false;
     return this;
   }
+  /** Filter by array being contained by (<@) */
   containedBy(column, value) {
     this.addFilter(column, "cd", value);
     this.negateNext = false;
     return this;
   }
+  /** Filter by array overlap (&&) */
   overlaps(column, value) {
     this.addFilter(column, "ov", value);
     this.negateNext = false;
     return this;
   }
+  /** Full-text search filter */
   textSearch(column, query, options) {
     this.addFilter(column, "fts", query, options?.config);
     this.negateNext = false;
@@ -1916,6 +2066,63 @@ var VaifAI = class {
     }
     return { data: response.data, error: null };
   }
+  /**
+   * Get Copilot observability metrics for the current project
+   *
+   * @example
+   * ```typescript
+   * const { data, error } = await vaif.ai.getCopilotMetrics({ range: '24h' });
+   * console.log(`Success rate: ${data.summary.successRate}%`);
+   * console.log(`Total tokens: ${data.summary.totalTokens}`);
+   * ```
+   */
+  async getCopilotMetrics(options = {}) {
+    const config = this.client.getConfig();
+    const range = options.range ?? "24h";
+    const response = await this.client.request(
+      `/copilot/metrics/${config.projectId}?range=${range}`,
+      { method: "GET" }
+    );
+    if (response.error) {
+      return {
+        data: null,
+        error: {
+          message: response.error.message,
+          code: response.error.code,
+          status: response.status
+        }
+      };
+    }
+    return { data: response.data, error: null };
+  }
+  /**
+   * Get Copilot observability metrics for an organization
+   *
+   * @example
+   * ```typescript
+   * const { data, error } = await vaif.ai.getCopilotOrgMetrics(orgId, { range: '7d' });
+   * console.log(`Total requests: ${data.summary.totalRequests}`);
+   * console.log(`Projects: ${data.summary.uniqueProjects}`);
+   * ```
+   */
+  async getCopilotOrgMetrics(orgId, options = {}) {
+    const range = options.range ?? "24h";
+    const response = await this.client.request(
+      `/copilot/metrics/org/${orgId}?range=${range}`,
+      { method: "GET" }
+    );
+    if (response.error) {
+      return {
+        data: null,
+        error: {
+          message: response.error.message,
+          code: response.error.code,
+          status: response.status
+        }
+      };
+    }
+    return { data: response.data, error: null };
+  }
 };
 
 // src/lib/schema.ts
@@ -3271,6 +3478,14 @@ var VaifIntegrations = class {
 var DEFAULT_API_URL = "https://api.vaif.studio";
 var DEFAULT_REALTIME_URL = "wss://realtime.vaif.studio";
 var DEFAULT_TIMEOUT = 3e4;
+var DEFAULT_RETRY = {
+  maxRetries: 3,
+  retryDelay: 1e3,
+  maxRetryDelay: 3e4,
+  backoffMultiplier: 2,
+  retryOn: [429, 500, 502, 503, 504],
+  retryOnNetworkError: true
+};
 var memoryStorage = {
   data: /* @__PURE__ */ new Map(),
   getItem(key) {
@@ -3288,6 +3503,18 @@ var browserStorage = typeof window !== "undefined" && window.localStorage ? {
   setItem: (key, value) => window.localStorage.setItem(key, value),
   removeItem: (key) => window.localStorage.removeItem(key)
 } : null;
+function calculateRetryDelay(attempt, config) {
+  const exponentialDelay = config.retryDelay * Math.pow(config.backoffMultiplier, attempt);
+  const cappedDelay = Math.min(exponentialDelay, config.maxRetryDelay);
+  const jitter = 0.5 + Math.random();
+  return Math.floor(cappedDelay * jitter);
+}
+function isRetryableStatus(status, config) {
+  return config.retryOn.includes(status);
+}
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
 function createClient(options) {
   return new VaifClient(options);
 }
@@ -3297,10 +3524,10 @@ var VaifClient = class {
     const isAdminClient = options.baseUrl || options.accessToken;
     if (!isAdminClient) {
       if (!options.projectId) {
-        throw new Error("projectId is required");
+        throw new VaifError("projectId is required", { code: "INVALID_CONFIG" });
       }
       if (!options.apiKey) {
-        throw new Error("apiKey is required");
+        throw new VaifError("apiKey is required", { code: "INVALID_CONFIG" });
       }
     }
     this.config = {
@@ -3314,7 +3541,13 @@ var VaifClient = class {
       debug: options.debug ?? false,
       autoRefreshToken: options.autoRefreshToken ?? true,
       persistSession: options.persistSession ?? true,
-      storage: options.storage ?? browserStorage ?? memoryStorage
+      storage: options.storage ?? browserStorage ?? memoryStorage,
+      retry: {
+        ...DEFAULT_RETRY,
+        ...options.retry,
+        retryOn: options.retry?.retryOn ?? DEFAULT_RETRY.retryOn
+      },
+      interceptors: options.interceptors ?? {}
     };
     if (options.accessToken) {
       this.accessToken = options.accessToken;
@@ -3333,120 +3566,228 @@ var VaifClient = class {
     this.integrations = new VaifIntegrations(this);
     this.restoreSession();
   }
-  /**
-   * Get current configuration
-   */
+  /** Get current configuration */
   getConfig() {
     return this.config;
   }
-  /**
-   * Set access token for authenticated requests
-   */
+  /** Set access token for authenticated requests */
   setAccessToken(token) {
     this.accessToken = token;
   }
-  /**
-   * Get current access token
-   */
+  /** Get current access token */
   getAccessToken() {
     return this.accessToken;
   }
   /**
-   * Make an authenticated API request
+   * Make an authenticated API request with automatic retry and interceptors
+   *
+   * @param path - API path (relative to base URL)
+   * @param options - Request options (method, body, params, etc.)
+   * @returns Typed API response with data, error, status, and headers
    */
   async request(path, options = {}) {
-    const url = new URL(path, this.config.apiUrl);
-    if (options.params) {
-      Object.entries(options.params).forEach(([key, value]) => {
-        if (value !== void 0) {
-          url.searchParams.set(key, String(value));
+    const { retry, interceptors } = this.config;
+    for (let attempt = 0; attempt <= retry.maxRetries; attempt++) {
+      const startTime = Date.now();
+      const url = new URL(path, this.config.apiUrl);
+      if (options.params) {
+        Object.entries(options.params).forEach(([key, value]) => {
+          if (value !== void 0) {
+            url.searchParams.set(key, String(value));
+          }
+        });
+      }
+      const headers = {
+        "Content-Type": "application/json",
+        ...this.config.headers,
+        ...options.headers
+      };
+      if (this.config.projectId) {
+        headers["X-Project-ID"] = this.config.projectId;
+      }
+      if (this.config.apiKey) {
+        headers[this.config.apiKeyHeader] = this.config.apiKey;
+      }
+      if (this.accessToken) {
+        headers.Authorization = `Bearer ${this.accessToken}`;
+      }
+      let requestContext = {
+        url: url.toString(),
+        path,
+        method: options.method ?? "GET",
+        headers: { ...headers },
+        body: options.body && options.method !== "GET" ? JSON.stringify(options.body) : void 0,
+        attempt
+      };
+      if (interceptors.onRequest) {
+        try {
+          const modified = await interceptors.onRequest(requestContext);
+          if (modified) {
+            requestContext = modified;
+          }
+        } catch {
         }
-      });
-    }
-    const headers = {
-      "Content-Type": "application/json",
-      ...this.config.headers,
-      ...options.headers
-    };
-    if (this.config.projectId) {
-      headers["X-Project-ID"] = this.config.projectId;
-    }
-    if (this.config.apiKey) {
-      headers[this.config.apiKeyHeader] = this.config.apiKey;
-    }
-    if (this.accessToken) {
-      headers.Authorization = `Bearer ${this.accessToken}`;
-    }
-    const fetchOptions = {
-      method: options.method ?? "GET",
-      headers,
-      signal: options.signal
-    };
-    if (options.body && options.method !== "GET") {
-      fetchOptions.body = JSON.stringify(options.body);
-    }
-    const timeoutMs = options.timeout ?? this.config.timeout;
-    const timeoutController = new AbortController();
-    const timeoutId = setTimeout(() => timeoutController.abort(), timeoutMs);
-    if (options.signal) {
-      options.signal.addEventListener("abort", () => timeoutController.abort());
-    }
-    fetchOptions.signal = timeoutController.signal;
-    try {
-      if (this.config.debug) {
-        console.log(`[VAIF] ${options.method ?? "GET"} ${url.toString()}`);
       }
-      const response = await fetch(url.toString(), fetchOptions);
-      clearTimeout(timeoutId);
-      const contentType = response.headers.get("content-type");
-      let data = null;
-      let error = null;
-      if (contentType?.includes("application/json")) {
-        const json = await response.json();
-        if (response.ok) {
-          data = json;
-        } else {
+      const fetchOptions = {
+        method: requestContext.method,
+        headers: requestContext.headers,
+        signal: options.signal
+      };
+      if (requestContext.body) {
+        fetchOptions.body = requestContext.body;
+      }
+      const timeoutMs = options.timeout ?? this.config.timeout;
+      const timeoutController = new AbortController();
+      const timeoutId = setTimeout(() => timeoutController.abort(), timeoutMs);
+      if (options.signal) {
+        options.signal.addEventListener("abort", () => timeoutController.abort());
+      }
+      fetchOptions.signal = timeoutController.signal;
+      try {
+        if (this.config.debug) {
+          console.log(`[VAIF] ${requestContext.method} ${requestContext.url} (attempt ${attempt + 1})`);
+        }
+        const response = await fetch(requestContext.url, fetchOptions);
+        clearTimeout(timeoutId);
+        const durationMs = Date.now() - startTime;
+        const contentType = response.headers.get("content-type");
+        let data = null;
+        let error = null;
+        if (contentType?.includes("application/json")) {
+          const json = await response.json();
+          if (response.ok) {
+            data = json;
+          } else {
+            error = {
+              message: json.message ?? json.error ?? "Request failed",
+              code: json.code,
+              status: response.status,
+              details: json.details,
+              requestId: response.headers.get("x-request-id") ?? void 0
+            };
+          }
+        } else if (!response.ok) {
           error = {
-            message: json.message ?? json.error ?? "Request failed",
-            code: json.code,
-            status: response.status,
-            details: json.details,
-            requestId: response.headers.get("x-request-id") ?? void 0
+            message: `Request failed with status ${response.status}`,
+            status: response.status
           };
         }
-      } else if (!response.ok) {
-        error = {
-          message: `Request failed with status ${response.status}`,
-          status: response.status
+        const responseHeaders = {};
+        response.headers.forEach((value, key) => {
+          responseHeaders[key] = value;
+        });
+        if (error && attempt < retry.maxRetries && isRetryableStatus(response.status, retry)) {
+          if (interceptors.onError) {
+            try {
+              await interceptors.onError({
+                request: requestContext,
+                error: new VaifError(error.message, {
+                  code: error.code ?? "REQUEST_ERROR",
+                  statusCode: response.status
+                }),
+                durationMs,
+                willRetry: true
+              });
+            } catch {
+            }
+          }
+          const delay = calculateRetryDelay(attempt, retry);
+          if (this.config.debug) {
+            console.log(`[VAIF] Retrying in ${delay}ms (attempt ${attempt + 2}/${retry.maxRetries + 1})`);
+          }
+          await sleep(delay);
+          continue;
+        }
+        if (!error && interceptors.onResponse) {
+          try {
+            await interceptors.onResponse({
+              request: requestContext,
+              data,
+              status: response.status,
+              headers: responseHeaders,
+              durationMs
+            });
+          } catch {
+          }
+        }
+        if (error && interceptors.onError) {
+          try {
+            await interceptors.onError({
+              request: requestContext,
+              error: new VaifError(error.message, {
+                code: error.code ?? "REQUEST_ERROR",
+                statusCode: response.status
+              }),
+              durationMs,
+              willRetry: false
+            });
+          } catch {
+          }
+        }
+        return {
+          data,
+          error,
+          status: response.status,
+          headers: responseHeaders
+        };
+      } catch (err) {
+        clearTimeout(timeoutId);
+        const durationMs = Date.now() - startTime;
+        const isTimeout = err instanceof Error && err.name === "AbortError";
+        const isNetworkError = !isTimeout;
+        if (isNetworkError && retry.retryOnNetworkError && attempt < retry.maxRetries) {
+          if (interceptors.onError) {
+            try {
+              await interceptors.onError({
+                request: requestContext,
+                error: err instanceof Error ? err : new Error(String(err)),
+                durationMs,
+                willRetry: true
+              });
+            } catch {
+            }
+          }
+          const delay = calculateRetryDelay(attempt, retry);
+          if (this.config.debug) {
+            console.log(`[VAIF] Network error, retrying in ${delay}ms`);
+          }
+          await sleep(delay);
+          continue;
+        }
+        const error = {
+          message: err instanceof Error ? isTimeout ? "Request timed out" : err.message : "Unknown error",
+          code: isTimeout ? "TIMEOUT" : "NETWORK_ERROR"
+        };
+        if (interceptors.onError) {
+          try {
+            await interceptors.onError({
+              request: requestContext,
+              error: isTimeout ? new VaifTimeoutError("Request timed out", timeoutMs) : new VaifNetworkError(
+                err instanceof Error ? err.message : "Network error",
+                err instanceof Error ? err : void 0
+              ),
+              durationMs,
+              willRetry: false
+            });
+          } catch {
+          }
+        }
+        return {
+          data: null,
+          error,
+          status: 0,
+          headers: {}
         };
       }
-      const responseHeaders = {};
-      response.headers.forEach((value, key) => {
-        responseHeaders[key] = value;
-      });
-      return {
-        data,
-        error,
-        status: response.status,
-        headers: responseHeaders
-      };
-    } catch (err) {
-      clearTimeout(timeoutId);
-      const error = {
-        message: err instanceof Error ? err.name === "AbortError" ? "Request timed out" : err.message : "Unknown error",
-        code: err instanceof Error && err.name === "AbortError" ? "TIMEOUT" : "NETWORK_ERROR"
-      };
-      return {
-        data: null,
-        error,
-        status: 0,
-        headers: {}
-      };
     }
+    return {
+      data: null,
+      error: { message: "Max retries exceeded", code: "MAX_RETRIES" },
+      status: 0,
+      headers: {}
+    };
   }
-  /**
-   * Restore session from storage
-   */
+  /** Restore session from storage */
   async restoreSession() {
     if (!this.config.persistSession) return;
     try {
@@ -3462,9 +3803,7 @@ var VaifClient = class {
     } catch {
     }
   }
-  /**
-   * Log debug messages
-   */
+  /** Log debug messages */
   debug(...args) {
     if (this.config.debug) {
       console.log("[VAIF]", ...args);
@@ -3478,16 +3817,32 @@ var VaifClient = class {
   VaifAdmin,
   VaifApiKeys,
   VaifAuth,
+  VaifAuthError,
   VaifClient,
+  VaifConflictError,
   VaifDatabase,
+  VaifError,
   VaifFunctions,
   VaifIntegrations,
+  VaifNetworkError,
+  VaifNotFoundError,
   VaifProjects,
+  VaifRateLimitError,
   VaifRealtime,
   VaifSchema,
   VaifStorage,
+  VaifTimeoutError,
   VaifTypeGen,
+  VaifValidationError,
   createClient,
   createTypeGen,
-  createVaifClient
+  createVaifClient,
+  isVaifAuthError,
+  isVaifConflictError,
+  isVaifError,
+  isVaifNetworkError,
+  isVaifNotFoundError,
+  isVaifRateLimitError,
+  isVaifTimeoutError,
+  isVaifValidationError
 });