@useatlas/types 0.0.1 → 0.0.3

package/dist/errors.d.ts

@@ -1,7 +1,17 @@
 import type { AuthMode } from "./auth";
-export declare const CHAT_ERROR_CODES: readonly ["auth_error", "rate_limited", "configuration_error", "no_datasource", "invalid_request", "provider_model_not_found", "provider_auth_error", "provider_rate_limit", "provider_timeout", "provider_unreachable", "provider_error", "internal_error"];
+export declare const CHAT_ERROR_CODES: readonly ["auth_error", "session_expired", "rate_limited", "configuration_error", "no_datasource", "invalid_request", "provider_model_not_found", "provider_auth_error", "provider_rate_limit", "provider_timeout", "provider_unreachable", "provider_error", "internal_error", "validation_error", "not_found", "forbidden", "forbidden_role", "org_not_found", "plan_limit_exceeded", "trial_expired", "billing_check_failed", "workspace_check_failed", "workspace_suspended", "workspace_throttled", "workspace_deleted"];
 /** Union of all error codes the server can return in the `error` field. */
 export type ChatErrorCode = (typeof CHAT_ERROR_CODES)[number];
+/** Type guard — checks whether a string is a known `ChatErrorCode`. */
+export declare function isChatErrorCode(value: string): value is ChatErrorCode;
+/** Returns `true` if the given error code represents a transient, retryable failure. */
+export declare function isRetryableError(code: ChatErrorCode): boolean;
+/**
+ * Client-side error codes for conditions detected before/without a server response.
+ * These are distinct from `ChatErrorCode` (server-originated codes).
+ */
+export declare const CLIENT_ERROR_CODES: readonly ["api_unreachable", "auth_failure", "rate_limited_http", "server_error", "offline"];
+export type ClientErrorCode = (typeof CLIENT_ERROR_CODES)[number];
 /**
  * Structured error info extracted from a chat error response.
  *
@@ -10,13 +20,48 @@ export type ChatErrorCode = (typeof CHAT_ERROR_CODES)[number];
  * - `retryAfterSeconds` — Seconds to wait before retrying (rate_limited only).
  *   Clamped to [0, 300].
  * - `code` — The server error code, if the response was valid JSON with a known code.
+ * - `clientCode` — Client-side error classification (network/offline/HTTP status).
+ *   Present when the error is detected client-side before parsing a server response.
+ * - `retryable` — Whether the client should offer to retry. Three states:
+ *   - `true` — transient error, retrying may succeed.
+ *   - `false` — permanent error, retrying will not help.
+ *   - `undefined` — error code is unknown or response was not valid JSON;
+ *     the client cannot determine retryability.
+ * - `requestId` — Server-assigned request ID (UUID) for log correlation.
  */
 export interface ChatErrorInfo {
     title: string;
     detail?: string;
     retryAfterSeconds?: number;
     code?: ChatErrorCode;
+    clientCode?: ClientErrorCode;
+    retryable?: boolean;
+    requestId?: string;
+}
+/**
+ * Result from `matchError()` — a pattern-matched, user-safe error.
+ *
+ * `code` is a suggested `ChatErrorCode`. Callers may override it based
+ * on context (e.g. ECONNREFUSED in the chat route is `provider_unreachable`,
+ * but in startup it's `internal_error`).
+ */
+export interface MatchedError {
+    code: ChatErrorCode;
+    message: string;
 }
+/**
+ * Pattern-match common runtime errors into user-safe messages.
+ *
+ * Returns `null` when no pattern matches — the caller should fall through
+ * to a generic `internal_error` response with a request ID.
+ *
+ * @param error  - The caught error (any type).
+ * @param opts.timeoutSeconds - Configured query/request timeout, included in
+ *   timeout messages so users know the limit. Defaults to 30.
+ */
+export declare function matchError(error: unknown, opts?: {
+    timeoutSeconds?: number;
+}): MatchedError | null;
 /**
  * Map an auth mode to a user-friendly error message.
  *
@@ -27,11 +72,27 @@ export interface ChatErrorInfo {
  * - `none`: auth should not fail in this mode; a generic message is shown.
  */
 export declare function authErrorMessage(authMode: AuthMode): string;
+/**
+ * Detect client-side error conditions from the raw Error object.
+ *
+ * The AI SDK wraps fetch failures in an Error whose message is the response body
+ * (for HTTP errors) or the fetch error message (for network failures). We detect:
+ *
+ * - `TypeError` / "fetch failed" / "Failed to fetch" / "NetworkError" → `api_unreachable`
+ * - `navigator.onLine === false` → `offline`
+ * - HTTP status text patterns: "401" → `auth_failure`, "429" → `rate_limited_http`,
+ *   "5xx" → `server_error`
+ */
+export declare function classifyClientError(error: Error): ClientErrorCode | null;
 /**
  * Parse an AI SDK chat error into a user-friendly `ChatErrorInfo`.
  *
  * Expects `error.message` to contain a JSON string with `{ error, message, retryAfterSeconds? }`.
- * Falls back to a generic message when the body is not valid JSON (e.g. network failures,
- * HTML error pages, or unexpected formats).
+ * Falls back to a generic title when the body is not valid JSON (e.g. network failures,
+ * HTML error pages, or unexpected formats), preserving the original message as `detail`
+ * (truncated to 200 characters).
+ *
+ * Also classifies client-side errors (network failures, offline, HTTP status) before
+ * attempting JSON parse, setting the `clientCode` field on the result.
  */
 export declare function parseChatError(error: Error, authMode: AuthMode): ChatErrorInfo;

package/dist/errors.js

@@ -1,6 +1,7 @@
 // src/errors.ts
 var CHAT_ERROR_CODES = [
   "auth_error",
+  "session_expired",
   "rate_limited",
   "configuration_error",
   "no_datasource",
@@ -11,8 +12,118 @@ var CHAT_ERROR_CODES = [
   "provider_timeout",
   "provider_unreachable",
   "provider_error",
-  "internal_error"
+  "internal_error",
+  "validation_error",
+  "not_found",
+  "forbidden",
+  "forbidden_role",
+  "org_not_found",
+  "plan_limit_exceeded",
+  "trial_expired",
+  "billing_check_failed",
+  "workspace_check_failed",
+  "workspace_suspended",
+  "workspace_throttled",
+  "workspace_deleted"
 ];
+function isChatErrorCode(value) {
+  return CHAT_ERROR_CODES.includes(value);
+}
+var RETRYABLE_MAP = {
+  rate_limited: true,
+  provider_timeout: true,
+  provider_unreachable: true,
+  provider_error: true,
+  provider_rate_limit: true,
+  internal_error: true,
+  auth_error: false,
+  session_expired: false,
+  configuration_error: false,
+  no_datasource: false,
+  invalid_request: false,
+  provider_model_not_found: false,
+  provider_auth_error: false,
+  validation_error: false,
+  not_found: false,
+  forbidden: false,
+  forbidden_role: false,
+  org_not_found: false,
+  plan_limit_exceeded: false,
+  trial_expired: false,
+  billing_check_failed: true,
+  workspace_check_failed: true,
+  workspace_suspended: false,
+  workspace_throttled: true,
+  workspace_deleted: false
+};
+function isRetryableError(code) {
+  return RETRYABLE_MAP[code];
+}
+var CLIENT_ERROR_CODES = [
+  "api_unreachable",
+  "auth_failure",
+  "rate_limited_http",
+  "server_error",
+  "offline"
+];
+function extractHostFromError(msg) {
+  const refusedMatch = msg.match(/ECONNREFUSED\s+(\S+)/i);
+  if (refusedMatch)
+    return refusedMatch[1];
+  const notFoundMatch = msg.match(/ENOTFOUND\s+(\S+)/i);
+  if (notFoundMatch)
+    return notFoundMatch[1];
+  return "(unknown host)";
+}
+function matchError(error, opts) {
+  const msg = error instanceof Error ? error.message : String(error);
+  if (/too many (clients already|connections)|connection pool exhausted|remaining connection slots are reserved/i.test(msg)) {
+    return {
+      code: "rate_limited",
+      message: "Database connection pool exhausted — try again in a few seconds, or reduce concurrent queries"
+    };
+  }
+  if (/ECONNREFUSED/i.test(msg)) {
+    const host = extractHostFromError(msg);
+    return {
+      code: "internal_error",
+      message: `Database unreachable at ${host} — check that the database is running and accessible`
+    };
+  }
+  if (/ENOTFOUND/i.test(msg)) {
+    const host = extractHostFromError(msg);
+    return {
+      code: "internal_error",
+      message: `Could not resolve hostname "${host}" — check your connection URL`
+    };
+  }
+  if (/SELF_SIGNED_CERT|UNABLE_TO_VERIFY_LEAF_SIGNATURE|ssl\s+connection|tls\s+handshake|certificate\s+(has expired|verify|error|rejected)/i.test(msg)) {
+    return {
+      code: "internal_error",
+      message: "SSL connection failed — check sslmode in your connection string"
+    };
+  }
+  if (/timeout|timed out|AbortError/i.test(msg)) {
+    const seconds = Math.max(1, opts?.timeoutSeconds ?? 30);
+    return {
+      code: "provider_timeout",
+      message: `Query exceeded the ${seconds}-second timeout — try a simpler query or increase ATLAS_QUERY_TIMEOUT`
+    };
+  }
+  if (/\b502\s+Bad Gateway\b|\b503\s+Service Unavailable\b/i.test(msg)) {
+    return {
+      code: "provider_unreachable",
+      message: "AI provider API unavailable — this is usually temporary, retry in a few seconds"
+    };
+  }
+  if (/fetch failed/i.test(msg)) {
+    return {
+      code: "provider_unreachable",
+      message: "Network request failed — the remote service may be down or unreachable"
+    };
+  }
+  return null;
+}
 function authErrorMessage(authMode) {
   switch (authMode) {
     case "simple-key":
@@ -29,54 +140,164 @@ function authErrorMessage(authMode) {
     }
   }
 }
+function classifyClientError(error) {
+  const msg = error.message;
+  if (msg.startsWith("{") || msg.startsWith("[")) {
+    return null;
+  }
+  if (typeof window !== "undefined" && typeof navigator !== "undefined" && navigator.onLine === false) {
+    return "offline";
+  }
+  if (error.name === "TypeError" || /fetch failed|failed to fetch|networkerror|network\s+request\s+failed|ECONNREFUSED|ENOTFOUND|ERR_CONNECTION_REFUSED/i.test(msg)) {
+    return "api_unreachable";
+  }
+  if (/\b401\b|Unauthorized/i.test(msg) && !/\bretry/i.test(msg)) {
+    return "auth_failure";
+  }
+  if (/\b429\b|Too Many Requests/i.test(msg)) {
+    return "rate_limited_http";
+  }
+  if (/\b50[0-9]\b|Internal Server Error|Bad Gateway|Service Unavailable/i.test(msg)) {
+    return "server_error";
+  }
+  return null;
+}
+function clientErrorInfo(clientCode, authMode) {
+  switch (clientCode) {
+    case "offline":
+      return {
+        title: "You appear to be offline.",
+        detail: "Reconnecting when your network is restored...",
+        clientCode,
+        retryable: true
+      };
+    case "api_unreachable":
+      return {
+        title: "Unable to connect to Atlas.",
+        detail: "Check your API URL configuration and ensure the server is running.",
+        clientCode,
+        retryable: true
+      };
+    case "auth_failure":
+      return {
+        title: authErrorMessage(authMode),
+        clientCode,
+        retryable: false
+      };
+    case "rate_limited_http":
+      return {
+        title: "Too many requests.",
+        detail: "Please try again in a moment.",
+        retryAfterSeconds: 30,
+        clientCode,
+        retryable: true
+      };
+    case "server_error":
+      return {
+        title: "Something went wrong on our end.",
+        detail: "Please try again.",
+        clientCode,
+        retryable: true
+      };
+    default: {
+      const _exhaustive = clientCode;
+      return { title: `Unknown error (${_exhaustive}).` };
+    }
+  }
+}
 function parseChatError(error, authMode) {
+  const clientCode = classifyClientError(error);
   let parsed;
   try {
     parsed = JSON.parse(error.message);
   } catch {
-    return { title: "Something went wrong. Please try again." };
+    if (clientCode) {
+      return clientErrorInfo(clientCode, authMode);
+    }
+    const raw = error.message.length > 200 ? error.message.slice(0, 200) + "..." : error.message;
+    return { title: "Something went wrong. Please try again.", detail: raw };
   }
-  const code = typeof parsed.error === "string" ? parsed.error : undefined;
+  const rawCode = typeof parsed.error === "string" ? parsed.error : undefined;
   const serverMessage = typeof parsed.message === "string" ? parsed.message : undefined;
-  switch (code) {
+  const requestId = typeof parsed.requestId === "string" ? parsed.requestId : undefined;
+  if (rawCode === undefined || !isChatErrorCode(rawCode)) {
+    return { title: serverMessage ?? "Something went wrong. Please try again.", requestId };
+  }
+  const retryable = isRetryableError(rawCode);
+  switch (rawCode) {
     case "auth_error":
-      return { title: authErrorMessage(authMode), code };
+      return { title: authErrorMessage(authMode), code: rawCode, retryable, requestId };
     case "rate_limited": {
       const raw = typeof parsed.retryAfterSeconds === "number" ? parsed.retryAfterSeconds : undefined;
       const clamped = raw !== undefined ? Math.max(0, Math.min(raw, 300)) : undefined;
       return {
         title: "Too many requests.",
-        detail: clamped !== undefined ? `Try again in ${clamped} seconds.` : "Please wait before trying again.",
+        detail: clamped !== undefined ? `Try again in ${clamped} seconds.` : serverMessage ?? "Please wait before trying again.",
         retryAfterSeconds: clamped,
-        code
+        code: rawCode,
+        retryable,
+        requestId
       };
     }
     case "configuration_error":
-      return { title: "Atlas is not fully configured.", detail: serverMessage, code };
+      return { title: "Atlas is not fully configured.", detail: serverMessage, code: rawCode, retryable, requestId };
     case "no_datasource":
-      return { title: "No data source configured.", detail: serverMessage, code };
+      return { title: "No data source configured.", detail: serverMessage, code: rawCode, retryable, requestId };
     case "invalid_request":
-      return { title: "Invalid request.", detail: serverMessage, code };
+      return { title: "Invalid request.", detail: serverMessage, code: rawCode, retryable, requestId };
     case "provider_model_not_found":
-      return { title: "The configured AI model was not found.", detail: serverMessage, code };
+      return { title: "The configured AI model was not found.", detail: serverMessage, code: rawCode, retryable, requestId };
     case "provider_auth_error":
-      return { title: "The AI provider could not authenticate.", detail: serverMessage, code };
+      return { title: "The AI provider could not authenticate.", detail: serverMessage, code: rawCode, retryable, requestId };
     case "provider_rate_limit":
-      return { title: "The AI provider is rate limiting requests.", detail: serverMessage, code };
+      return { title: "The AI provider is rate limiting requests.", detail: serverMessage, code: rawCode, retryable, requestId };
     case "provider_timeout":
-      return { title: "The AI provider timed out.", detail: serverMessage, code };
+      return { title: "The AI provider timed out.", detail: serverMessage, code: rawCode, retryable, requestId };
     case "provider_unreachable":
-      return { title: "Could not reach the AI provider.", detail: serverMessage, code };
+      return { title: "Could not reach the AI provider.", detail: serverMessage, code: rawCode, retryable, requestId };
     case "provider_error":
-      return { title: "The AI provider returned an error.", detail: serverMessage, code };
+      return { title: "The AI provider returned an error.", detail: serverMessage, code: rawCode, retryable, requestId };
     case "internal_error":
-      return { title: serverMessage ?? "An unexpected error occurred.", code };
-    default:
-      return { title: serverMessage ?? "Something went wrong. Please try again." };
+      return { title: serverMessage ?? "An unexpected error occurred.", code: rawCode, retryable, requestId };
+    case "validation_error":
+      return { title: "Validation error.", detail: serverMessage, code: rawCode, retryable, requestId };
+    case "not_found":
+      return { title: "Not found.", detail: serverMessage, code: rawCode, retryable, requestId };
+    case "forbidden":
+      return { title: "Access denied.", detail: serverMessage, code: rawCode, retryable, requestId };
+    case "session_expired":
+      return { title: "Your session has expired.", detail: serverMessage ?? "Please sign in again.", code: rawCode, retryable, requestId };
+    case "forbidden_role":
+      return { title: "Admin role required.", detail: serverMessage, code: rawCode, retryable, requestId };
+    case "org_not_found":
+      return { title: "No active organization.", detail: serverMessage ?? "Select an organization and try again.", code: rawCode, retryable, requestId };
+    case "plan_limit_exceeded":
+      return { title: "Plan limit exceeded.", detail: serverMessage ?? "Upgrade your plan or wait until the next billing period.", code: rawCode, retryable, requestId };
+    case "trial_expired":
+      return { title: "Trial expired.", detail: serverMessage ?? "Upgrade to a paid plan to continue using Atlas.", code: rawCode, retryable, requestId };
+    case "billing_check_failed":
+      return { title: "Billing check failed.", detail: serverMessage ?? "Unable to verify billing status. Please try again.", code: rawCode, retryable, requestId };
+    case "workspace_check_failed":
+      return { title: "Workspace check failed.", detail: serverMessage ?? "Unable to verify workspace status. Please try again.", code: rawCode, retryable, requestId };
+    case "workspace_suspended":
+      return { title: "Workspace suspended.", detail: serverMessage ?? "Contact your workspace administrator to reactivate it.", code: rawCode, retryable, requestId };
+    case "workspace_throttled":
+      return { title: "Workspace throttled.", detail: serverMessage ?? "Your workspace has been temporarily throttled due to unusual activity. Requests will be delayed.", code: rawCode, retryable, requestId };
+    case "workspace_deleted":
+      return { title: "Workspace deleted.", detail: serverMessage ?? "This workspace has been permanently deleted. Create a new workspace to continue.", code: rawCode, retryable, requestId };
+    default: {
+      const _exhaustive = rawCode;
+      return { title: serverMessage ?? `Something went wrong (${_exhaustive}).`, requestId };
+    }
   }
 }
 export {
   parseChatError,
+  matchError,
+  isRetryableError,
+  isChatErrorCode,
+  classifyClientError,
   authErrorMessage,
+  CLIENT_ERROR_CODES,
   CHAT_ERROR_CODES
 };

package/dist/index.d.ts

@@ -4,5 +4,23 @@ export * from "./connection";
 export * from "./action";
 export * from "./scheduled-task";
 export * from "./errors";
+export * from "./compliance";
 export * from "./semantic";
 export * from "./share";
+export * from "./organization";
+export * from "./learned-pattern";
+export * from "./prompt";
+export * from "./query-suggestion";
+export * from "./sso";
+export * from "./billing";
+export * from "./profiler";
+export * from "./model-config";
+export * from "./approval";
+export * from "./platform";
+export * from "./branding";
+export * from "./onboarding-email";
+export * from "./abuse";
+export * from "./sla";
+export * from "./backups";
+export * from "./residency";
+export * from "./domain";