@hypercerts-org/sdk-core 0.2.0-beta.0

package/dist/errors.mjs

@@ -0,0 +1,253 @@
+/**
+ * Base error class for all SDK errors.
+ *
+ * All errors thrown by the Hypercerts SDK extend this class, making it easy
+ * to catch and handle SDK-specific errors.
+ *
+ * @example Catching all SDK errors
+ * ```typescript
+ * try {
+ *   await sdk.authorize("user.bsky.social");
+ * } catch (error) {
+ *   if (error instanceof ATProtoSDKError) {
+ *     console.error(`SDK Error [${error.code}]: ${error.message}`);
+ *     console.error(`HTTP Status: ${error.status}`);
+ *   }
+ * }
+ * ```
+ *
+ * @example Checking error codes
+ * ```typescript
+ * try {
+ *   await repo.records.get(collection, rkey);
+ * } catch (error) {
+ *   if (error instanceof ATProtoSDKError) {
+ *     switch (error.code) {
+ *       case "AUTHENTICATION_ERROR":
+ *         // Redirect to login
+ *         break;
+ *       case "VALIDATION_ERROR":
+ *         // Show form errors
+ *         break;
+ *       case "NETWORK_ERROR":
+ *         // Retry or show offline message
+ *         break;
+ *     }
+ *   }
+ * }
+ * ```
+ */
+class ATProtoSDKError extends Error {
+    /**
+     * Creates a new SDK error.
+     *
+     * @param message - Human-readable error description
+     * @param code - Machine-readable error code for programmatic handling
+     * @param status - HTTP status code associated with this error type
+     * @param cause - The underlying error that caused this error, if any
+     */
+    constructor(message, code, status, cause) {
+        super(message);
+        this.code = code;
+        this.status = status;
+        this.cause = cause;
+        this.name = "ATProtoSDKError";
+        Error.captureStackTrace?.(this, this.constructor);
+    }
+}
+/**
+ * Error thrown when authentication fails.
+ *
+ * This error indicates problems with the OAuth flow, invalid credentials,
+ * or failed token exchanges. Common causes:
+ * - Invalid authorization code
+ * - Expired or invalid state parameter
+ * - Revoked or invalid tokens
+ * - User denied authorization
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   const session = await sdk.callback(params);
+ * } catch (error) {
+ *   if (error instanceof AuthenticationError) {
+ *     // Clear any stored state and redirect to login
+ *     console.error("Authentication failed:", error.message);
+ *   }
+ * }
+ * ```
+ */
+class AuthenticationError extends ATProtoSDKError {
+    /**
+     * Creates an authentication error.
+     *
+     * @param message - Description of what went wrong during authentication
+     * @param cause - The underlying error (e.g., from the OAuth client)
+     */
+    constructor(message, cause) {
+        super(message, "AUTHENTICATION_ERROR", 401, cause);
+        this.name = "AuthenticationError";
+    }
+}
+/**
+ * Error thrown when a session has expired and cannot be refreshed.
+ *
+ * This typically occurs when:
+ * - The refresh token has expired (usually after extended inactivity)
+ * - The user has revoked access to your application
+ * - The PDS has invalidated all sessions for the user
+ *
+ * When this error occurs, the user must re-authenticate.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   const session = await sdk.restoreSession(did);
+ * } catch (error) {
+ *   if (error instanceof SessionExpiredError) {
+ *     // Clear stored session and prompt user to log in again
+ *     localStorage.removeItem("userDid");
+ *     window.location.href = "/login";
+ *   }
+ * }
+ * ```
+ */
+class SessionExpiredError extends ATProtoSDKError {
+    /**
+     * Creates a session expired error.
+     *
+     * @param message - Description of why the session expired
+     * @param cause - The underlying error from the token refresh attempt
+     */
+    constructor(message = "Session expired", cause) {
+        super(message, "SESSION_EXPIRED", 401, cause);
+        this.name = "SessionExpiredError";
+    }
+}
+/**
+ * Error thrown when input validation fails.
+ *
+ * This error indicates that provided data doesn't meet the required format
+ * or constraints. Common causes:
+ * - Missing required fields
+ * - Invalid URL formats
+ * - Invalid DID format
+ * - Schema validation failures for records
+ * - Invalid configuration values
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await sdk.authorize("");  // Empty identifier
+ * } catch (error) {
+ *   if (error instanceof ValidationError) {
+ *     console.error("Invalid input:", error.message);
+ *     // Show validation error to user
+ *   }
+ * }
+ * ```
+ *
+ * @example With Zod validation cause
+ * ```typescript
+ * try {
+ *   await repo.records.create(collection, record);
+ * } catch (error) {
+ *   if (error instanceof ValidationError && error.cause) {
+ *     // error.cause may be a ZodError with detailed field errors
+ *     const zodError = error.cause as ZodError;
+ *     zodError.errors.forEach(e => {
+ *       console.error(`Field ${e.path.join(".")}: ${e.message}`);
+ *     });
+ *   }
+ * }
+ * ```
+ */
+class ValidationError extends ATProtoSDKError {
+    /**
+     * Creates a validation error.
+     *
+     * @param message - Description of what validation failed
+     * @param cause - The underlying validation error (e.g., ZodError)
+     */
+    constructor(message, cause) {
+        super(message, "VALIDATION_ERROR", 400, cause);
+        this.name = "ValidationError";
+    }
+}
+/**
+ * Error thrown when a network request fails.
+ *
+ * This error indicates connectivity issues or server unavailability.
+ * Common causes:
+ * - No internet connection
+ * - DNS resolution failure
+ * - Server timeout
+ * - Server returned 5xx error
+ * - TLS/SSL errors
+ *
+ * These errors are typically transient and may succeed on retry.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await repo.records.list(collection);
+ * } catch (error) {
+ *   if (error instanceof NetworkError) {
+ *     // Implement retry logic or show offline indicator
+ *     console.error("Network error:", error.message);
+ *     await retryWithBackoff(() => repo.records.list(collection));
+ *   }
+ * }
+ * ```
+ */
+class NetworkError extends ATProtoSDKError {
+    /**
+     * Creates a network error.
+     *
+     * @param message - Description of the network failure
+     * @param cause - The underlying error (e.g., fetch error, timeout)
+     */
+    constructor(message, cause) {
+        super(message, "NETWORK_ERROR", 503, cause);
+        this.name = "NetworkError";
+    }
+}
+/**
+ * Error thrown when an SDS-only operation is attempted on a PDS.
+ *
+ * Certain operations are only available on Shared Data Servers (SDS),
+ * such as collaborator management and organization operations.
+ * This error is thrown when these operations are attempted on a
+ * Personal Data Server (PDS).
+ *
+ * @example
+ * ```typescript
+ * const pdsRepo = sdk.repository(session);  // Default is PDS
+ *
+ * try {
+ *   // This will throw SDSRequiredError
+ *   await pdsRepo.collaborators.list();
+ * } catch (error) {
+ *   if (error instanceof SDSRequiredError) {
+ *     // Switch to SDS for this operation
+ *     const sdsRepo = sdk.repository(session, { server: "sds" });
+ *     const collaborators = await sdsRepo.collaborators.list();
+ *   }
+ * }
+ * ```
+ */
+class SDSRequiredError extends ATProtoSDKError {
+    /**
+     * Creates an SDS required error.
+     *
+     * @param message - Description of which operation requires SDS
+     * @param cause - Any underlying error
+     */
+    constructor(message = "This operation requires a Shared Data Server (SDS)", cause) {
+        super(message, "SDS_REQUIRED", 400, cause);
+        this.name = "SDSRequiredError";
+    }
+}
+
+export { ATProtoSDKError, AuthenticationError, NetworkError, SDSRequiredError, SessionExpiredError, ValidationError };
+//# sourceMappingURL=errors.mjs.map

package/dist/errors.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.mjs","sources":["../src/core/errors.ts"],"sourcesContent":["/**\n * Base error class for all SDK errors.\n *\n * All errors thrown by the Hypercerts SDK extend this class, making it easy\n * to catch and handle SDK-specific errors.\n *\n * @example Catching all SDK errors\n * ```typescript\n * try {\n *   await sdk.authorize(\"user.bsky.social\");\n * } catch (error) {\n *   if (error instanceof ATProtoSDKError) {\n *     console.error(`SDK Error [${error.code}]: ${error.message}`);\n *     console.error(`HTTP Status: ${error.status}`);\n *   }\n * }\n * ```\n *\n * @example Checking error codes\n * ```typescript\n * try {\n *   await repo.records.get(collection, rkey);\n * } catch (error) {\n *   if (error instanceof ATProtoSDKError) {\n *     switch (error.code) {\n *       case \"AUTHENTICATION_ERROR\":\n *         // Redirect to login\n *         break;\n *       case \"VALIDATION_ERROR\":\n *         // Show form errors\n *         break;\n *       case \"NETWORK_ERROR\":\n *         // Retry or show offline message\n *         break;\n *     }\n *   }\n * }\n * ```\n */\nexport class ATProtoSDKError extends Error {\n  /**\n   * Creates a new SDK error.\n   *\n   * @param message - Human-readable error description\n   * @param code - Machine-readable error code for programmatic handling\n   * @param status - HTTP status code associated with this error type\n   * @param cause - The underlying error that caused this error, if any\n   */\n  constructor(\n    message: string,\n    public code: string,\n    public status?: number,\n    public cause?: unknown,\n  ) {\n    super(message);\n    this.name = \"ATProtoSDKError\";\n    Error.captureStackTrace?.(this, this.constructor);\n  }\n}\n\n/**\n * Error thrown when authentication fails.\n *\n * This error indicates problems with the OAuth flow, invalid credentials,\n * or failed token exchanges. Common causes:\n * - Invalid authorization code\n * - Expired or invalid state parameter\n * - Revoked or invalid tokens\n * - User denied authorization\n *\n * @example\n * ```typescript\n * try {\n *   const session = await sdk.callback(params);\n * } catch (error) {\n *   if (error instanceof AuthenticationError) {\n *     // Clear any stored state and redirect to login\n *     console.error(\"Authentication failed:\", error.message);\n *   }\n * }\n * ```\n */\nexport class AuthenticationError extends ATProtoSDKError {\n  /**\n   * Creates an authentication error.\n   *\n   * @param message - Description of what went wrong during authentication\n   * @param cause - The underlying error (e.g., from the OAuth client)\n   */\n  constructor(message: string, cause?: unknown) {\n    super(message, \"AUTHENTICATION_ERROR\", 401, cause);\n    this.name = \"AuthenticationError\";\n  }\n}\n\n/**\n * Error thrown when a session has expired and cannot be refreshed.\n *\n * This typically occurs when:\n * - The refresh token has expired (usually after extended inactivity)\n * - The user has revoked access to your application\n * - The PDS has invalidated all sessions for the user\n *\n * When this error occurs, the user must re-authenticate.\n *\n * @example\n * ```typescript\n * try {\n *   const session = await sdk.restoreSession(did);\n * } catch (error) {\n *   if (error instanceof SessionExpiredError) {\n *     // Clear stored session and prompt user to log in again\n *     localStorage.removeItem(\"userDid\");\n *     window.location.href = \"/login\";\n *   }\n * }\n * ```\n */\nexport class SessionExpiredError extends ATProtoSDKError {\n  /**\n   * Creates a session expired error.\n   *\n   * @param message - Description of why the session expired\n   * @param cause - The underlying error from the token refresh attempt\n   */\n  constructor(message: string = \"Session expired\", cause?: unknown) {\n    super(message, \"SESSION_EXPIRED\", 401, cause);\n    this.name = \"SessionExpiredError\";\n  }\n}\n\n/**\n * Error thrown when input validation fails.\n *\n * This error indicates that provided data doesn't meet the required format\n * or constraints. Common causes:\n * - Missing required fields\n * - Invalid URL formats\n * - Invalid DID format\n * - Schema validation failures for records\n * - Invalid configuration values\n *\n * @example\n * ```typescript\n * try {\n *   await sdk.authorize(\"\");  // Empty identifier\n * } catch (error) {\n *   if (error instanceof ValidationError) {\n *     console.error(\"Invalid input:\", error.message);\n *     // Show validation error to user\n *   }\n * }\n * ```\n *\n * @example With Zod validation cause\n * ```typescript\n * try {\n *   await repo.records.create(collection, record);\n * } catch (error) {\n *   if (error instanceof ValidationError && error.cause) {\n *     // error.cause may be a ZodError with detailed field errors\n *     const zodError = error.cause as ZodError;\n *     zodError.errors.forEach(e => {\n *       console.error(`Field ${e.path.join(\".\")}: ${e.message}`);\n *     });\n *   }\n * }\n * ```\n */\nexport class ValidationError extends ATProtoSDKError {\n  /**\n   * Creates a validation error.\n   *\n   * @param message - Description of what validation failed\n   * @param cause - The underlying validation error (e.g., ZodError)\n   */\n  constructor(message: string, cause?: unknown) {\n    super(message, \"VALIDATION_ERROR\", 400, cause);\n    this.name = \"ValidationError\";\n  }\n}\n\n/**\n * Error thrown when a network request fails.\n *\n * This error indicates connectivity issues or server unavailability.\n * Common causes:\n * - No internet connection\n * - DNS resolution failure\n * - Server timeout\n * - Server returned 5xx error\n * - TLS/SSL errors\n *\n * These errors are typically transient and may succeed on retry.\n *\n * @example\n * ```typescript\n * try {\n *   await repo.records.list(collection);\n * } catch (error) {\n *   if (error instanceof NetworkError) {\n *     // Implement retry logic or show offline indicator\n *     console.error(\"Network error:\", error.message);\n *     await retryWithBackoff(() => repo.records.list(collection));\n *   }\n * }\n * ```\n */\nexport class NetworkError extends ATProtoSDKError {\n  /**\n   * Creates a network error.\n   *\n   * @param message - Description of the network failure\n   * @param cause - The underlying error (e.g., fetch error, timeout)\n   */\n  constructor(message: string, cause?: unknown) {\n    super(message, \"NETWORK_ERROR\", 503, cause);\n    this.name = \"NetworkError\";\n  }\n}\n\n/**\n * Error thrown when an SDS-only operation is attempted on a PDS.\n *\n * Certain operations are only available on Shared Data Servers (SDS),\n * such as collaborator management and organization operations.\n * This error is thrown when these operations are attempted on a\n * Personal Data Server (PDS).\n *\n * @example\n * ```typescript\n * const pdsRepo = sdk.repository(session);  // Default is PDS\n *\n * try {\n *   // This will throw SDSRequiredError\n *   await pdsRepo.collaborators.list();\n * } catch (error) {\n *   if (error instanceof SDSRequiredError) {\n *     // Switch to SDS for this operation\n *     const sdsRepo = sdk.repository(session, { server: \"sds\" });\n *     const collaborators = await sdsRepo.collaborators.list();\n *   }\n * }\n * ```\n */\nexport class SDSRequiredError extends ATProtoSDKError {\n  /**\n   * Creates an SDS required error.\n   *\n   * @param message - Description of which operation requires SDS\n   * @param cause - Any underlying error\n   */\n  constructor(message: string = \"This operation requires a Shared Data Server (SDS)\", cause?: unknown) {\n    super(message, \"SDS_REQUIRED\", 400, cause);\n    this.name = \"SDSRequiredError\";\n  }\n}\n"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAsCG;AACG,MAAO,eAAgB,SAAQ,KAAK,CAAA;AACxC;;;;;;;AAOG;AACH,IAAA,WAAA,CACE,OAAe,EACR,IAAY,EACZ,MAAe,EACf,KAAe,EAAA;QAEtB,KAAK,CAAC,OAAO,CAAC;QAJP,IAAA,CAAA,IAAI,GAAJ,IAAI;QACJ,IAAA,CAAA,MAAM,GAAN,MAAM;QACN,IAAA,CAAA,KAAK,GAAL,KAAK;AAGZ,QAAA,IAAI,CAAC,IAAI,GAAG,iBAAiB;QAC7B,KAAK,CAAC,iBAAiB,GAAG,IAAI,EAAE,IAAI,CAAC,WAAW,CAAC;IACnD;AACD;AAED;;;;;;;;;;;;;;;;;;;;;AAqBG;AACG,MAAO,mBAAoB,SAAQ,eAAe,CAAA;AACtD;;;;;AAKG;IACH,WAAA,CAAY,OAAe,EAAE,KAAe,EAAA;QAC1C,KAAK,CAAC,OAAO,EAAE,sBAAsB,EAAE,GAAG,EAAE,KAAK,CAAC;AAClD,QAAA,IAAI,CAAC,IAAI,GAAG,qBAAqB;IACnC;AACD;AAED;;;;;;;;;;;;;;;;;;;;;;AAsBG;AACG,MAAO,mBAAoB,SAAQ,eAAe,CAAA;AACtD;;;;;AAKG;IACH,WAAA,CAAY,OAAA,GAAkB,iBAAiB,EAAE,KAAe,EAAA;QAC9D,KAAK,CAAC,OAAO,EAAE,iBAAiB,EAAE,GAAG,EAAE,KAAK,CAAC;AAC7C,QAAA,IAAI,CAAC,IAAI,GAAG,qBAAqB;IACnC;AACD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAqCG;AACG,MAAO,eAAgB,SAAQ,eAAe,CAAA;AAClD;;;;;AAKG;IACH,WAAA,CAAY,OAAe,EAAE,KAAe,EAAA;QAC1C,KAAK,CAAC,OAAO,EAAE,kBAAkB,EAAE,GAAG,EAAE,KAAK,CAAC;AAC9C,QAAA,IAAI,CAAC,IAAI,GAAG,iBAAiB;IAC/B;AACD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;AAyBG;AACG,MAAO,YAAa,SAAQ,eAAe,CAAA;AAC/C;;;;;AAKG;IACH,WAAA,CAAY,OAAe,EAAE,KAAe,EAAA;QAC1C,KAAK,CAAC,OAAO,EAAE,eAAe,EAAE,GAAG,EAAE,KAAK,CAAC;AAC3C,QAAA,IAAI,CAAC,IAAI,GAAG,cAAc;IAC5B;AACD;AAED;;;;;;;;;;;;;;;;;;;;;;;AAuBG;AACG,MAAO,gBAAiB,SAAQ,eAAe,CAAA;AACnD;;;;;AAKG;IACH,WAAA,CAAY,OAAA,GAAkB,oDAAoD,EAAE,KAAe,EAAA;QACjG,KAAK,CAAC,OAAO,EAAE,cAAc,EAAE,GAAG,EAAE,KAAK,CAAC;AAC1C,QAAA,IAAI,CAAC,IAAI,GAAG,kBAAkB;IAChC;AACD;;;;"}