@hypercerts-org/sdk-core 0.4.0-beta.0 → 0.6.0-beta.0

package/src/core/errors.ts

@@ -1,257 +0,0 @@
-/**
- * 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;
- *     }
- *   }
- * }
- * ```
- */
-export 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: string,
-    public code: string,
-    public status?: number,
-    public cause?: unknown,
-  ) {
-    super(message);
-    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);
- *   }
- * }
- * ```
- */
-export 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: string, cause?: unknown) {
-    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";
- *   }
- * }
- * ```
- */
-export 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: string = "Session expired", cause?: unknown) {
-    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}`);
- *     });
- *   }
- * }
- * ```
- */
-export 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: string, cause?: unknown) {
-    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));
- *   }
- * }
- * ```
- */
-export 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: string, cause?: unknown) {
-    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();
- *   }
- * }
- * ```
- */
-export class SDSRequiredError extends ATProtoSDKError {
-  /**
-   * Creates an SDS required error.
-   *
-   * @param message - Description of which operation requires SDS
-   * @param cause - Any underlying error
-   */
-  constructor(message: string = "This operation requires a Shared Data Server (SDS)", cause?: unknown) {
-    super(message, "SDS_REQUIRED", 400, cause);
-    this.name = "SDSRequiredError";
-  }
-}

package/src/core/interfaces.ts

@@ -1,324 +0,0 @@
-import type { NodeSavedSession, NodeSavedState } from "@atproto/oauth-client-node";
-
-/**
- * Storage interface for persisting OAuth sessions.
- *
- * Implement this interface to provide persistent storage for user sessions.
- * Sessions contain sensitive data including access tokens, refresh tokens,
- * and DPoP key pairs.
- *
- * The SDK provides {@link InMemorySessionStore} for development/testing,
- * but **production applications should implement persistent storage**
- * (e.g., Redis, PostgreSQL, MongoDB).
- *
- * @remarks
- * - Sessions are keyed by the user's DID (Decentralized Identifier)
- * - The `NodeSavedSession` type comes from `@atproto/oauth-client-node`
- * - Sessions may be large (~2-4KB) due to embedded cryptographic keys
- * - Consider encrypting sessions at rest for additional security
- *
- * @example Redis implementation
- * ```typescript
- * import { Redis } from "ioredis";
- * import type { SessionStore } from "@hypercerts-org/sdk";
- * import type { NodeSavedSession } from "@atproto/oauth-client-node";
- *
- * class RedisSessionStore implements SessionStore {
- *   constructor(private redis: Redis, private prefix = "session:") {}
- *
- *   async get(did: string): Promise<NodeSavedSession | undefined> {
- *     const data = await this.redis.get(this.prefix + did);
- *     return data ? JSON.parse(data) : undefined;
- *   }
- *
- *   async set(did: string, session: NodeSavedSession): Promise<void> {
- *     // Set with 30-day expiry (sessions can be refreshed)
- *     await this.redis.setex(
- *       this.prefix + did,
- *       30 * 24 * 60 * 60,
- *       JSON.stringify(session)
- *     );
- *   }
- *
- *   async del(did: string): Promise<void> {
- *     await this.redis.del(this.prefix + did);
- *   }
- * }
- * ```
- *
- * @see {@link InMemorySessionStore} for the default in-memory implementation
- */
-export interface SessionStore {
-  /**
-   * Retrieves a session by DID.
-   *
-   * @param did - The user's Decentralized Identifier (e.g., "did:plc:abc123...")
-   * @returns The stored session, or `undefined` if not found
-   */
-  get(did: string): Promise<NodeSavedSession | undefined>;
-
-  /**
-   * Stores or updates a session.
-   *
-   * This is called after successful authentication and whenever tokens are refreshed.
-   *
-   * @param did - The user's DID to use as the storage key
-   * @param session - The session data to store (contains tokens, DPoP keys, etc.)
-   */
-  set(did: string, session: NodeSavedSession): Promise<void>;
-
-  /**
-   * Deletes a session.
-   *
-   * Called when a user logs out or when a session is revoked.
-   *
-   * @param did - The user's DID
-   */
-  del(did: string): Promise<void>;
-}
-
-/**
- * Storage interface for OAuth state during the authorization flow.
- *
- * Implement this interface to provide temporary storage for OAuth state
- * parameters. State is used for CSRF protection and PKCE (Proof Key for
- * Code Exchange) during the authorization flow.
- *
- * @remarks
- * - State is short-lived (typically 10-15 minutes)
- * - Keys are random state strings generated by the OAuth client
- * - The `NodeSavedState` type comes from `@atproto/oauth-client-node`
- * - State should be automatically cleaned up after expiry
- *
- * @example Redis implementation with automatic expiry
- * ```typescript
- * import { Redis } from "ioredis";
- * import type { StateStore } from "@hypercerts-org/sdk";
- * import type { NodeSavedState } from "@atproto/oauth-client-node";
- *
- * class RedisStateStore implements StateStore {
- *   constructor(
- *     private redis: Redis,
- *     private prefix = "oauth-state:",
- *     private ttlSeconds = 900  // 15 minutes
- *   ) {}
- *
- *   async get(key: string): Promise<NodeSavedState | undefined> {
- *     const data = await this.redis.get(this.prefix + key);
- *     return data ? JSON.parse(data) : undefined;
- *   }
- *
- *   async set(key: string, state: NodeSavedState): Promise<void> {
- *     await this.redis.setex(
- *       this.prefix + key,
- *       this.ttlSeconds,
- *       JSON.stringify(state)
- *     );
- *   }
- *
- *   async del(key: string): Promise<void> {
- *     await this.redis.del(this.prefix + key);
- *   }
- * }
- * ```
- *
- * @see {@link InMemoryStateStore} for the default in-memory implementation
- */
-export interface StateStore {
-  /**
-   * Retrieves OAuth state by key.
-   *
-   * @param key - The state key (random string from authorization URL)
-   * @returns The stored state, or `undefined` if not found or expired
-   */
-  get(key: string): Promise<NodeSavedState | undefined>;
-
-  /**
-   * Stores OAuth state temporarily.
-   *
-   * Called when starting the authorization flow. The state should be
-   * stored with a short TTL (10-15 minutes recommended).
-   *
-   * @param key - The state key to use for storage
-   * @param state - The OAuth state data (includes PKCE verifier, etc.)
-   */
-  set(key: string, state: NodeSavedState): Promise<void>;
-
-  /**
-   * Deletes OAuth state.
-   *
-   * Called after the state has been used (successful or failed callback).
-   *
-   * @param key - The state key to delete
-   */
-  del(key: string): Promise<void>;
-}
-
-/**
- * Generic cache interface for profiles, metadata, and other data.
- *
- * Implement this interface to provide caching for frequently accessed data.
- * Caching can significantly reduce API calls and improve performance.
- *
- * @remarks
- * The SDK does not provide a default cache implementation - you must
- * implement this interface if you want caching. Consider using:
- * - In-memory cache (e.g., `lru-cache`) for single-instance applications
- * - Redis for distributed applications
- * - Database-backed cache for persistence
- *
- * @example LRU cache implementation
- * ```typescript
- * import { LRUCache } from "lru-cache";
- * import type { CacheInterface } from "@hypercerts-org/sdk";
- *
- * class LRUCacheAdapter implements CacheInterface {
- *   private cache = new LRUCache<string, unknown>({
- *     max: 1000,
- *     ttl: 5 * 60 * 1000,  // 5 minutes default
- *   });
- *
- *   async get<T>(key: string): Promise<T | undefined> {
- *     return this.cache.get(key) as T | undefined;
- *   }
- *
- *   async set<T>(key: string, value: T, ttlSeconds?: number): Promise<void> {
- *     this.cache.set(key, value, {
- *       ttl: ttlSeconds ? ttlSeconds * 1000 : undefined,
- *     });
- *   }
- *
- *   async del(key: string): Promise<void> {
- *     this.cache.delete(key);
- *   }
- *
- *   async clear(): Promise<void> {
- *     this.cache.clear();
- *   }
- * }
- * ```
- */
-export interface CacheInterface {
-  /**
-   * Gets a cached value by key.
-   *
-   * @typeParam T - The expected type of the cached value
-   * @param key - The cache key
-   * @returns The cached value, or `undefined` if not found or expired
-   */
-  get<T>(key: string): Promise<T | undefined>;
-
-  /**
-   * Sets a cached value with optional TTL (time-to-live).
-   *
-   * @typeParam T - The type of the value being cached
-   * @param key - The cache key
-   * @param value - The value to cache
-   * @param ttlSeconds - Optional time-to-live in seconds. If not provided,
-   *                     the cache implementation should use its default TTL.
-   */
-  set<T>(key: string, value: T, ttlSeconds?: number): Promise<void>;
-
-  /**
-   * Deletes a cached value.
-   *
-   * @param key - The cache key to delete
-   */
-  del(key: string): Promise<void>;
-
-  /**
-   * Clears all cached values.
-   *
-   * Use with caution in production as this affects all cached data.
-   */
-  clear(): Promise<void>;
-}
-
-/**
- * Logger interface for debugging and observability.
- *
- * Implement this interface to receive log messages from the SDK.
- * The interface is compatible with `console` and most popular
- * logging libraries (Pino, Winston, Bunyan, etc.).
- *
- * @remarks
- * Log levels follow standard conventions:
- * - `debug`: Detailed information for debugging (tokens, request details)
- * - `info`: General operational messages (initialization, successful auth)
- * - `warn`: Potentially problematic situations (deprecated features, retries)
- * - `error`: Errors that don't crash the application (failed requests, validation)
- *
- * @example Using console
- * ```typescript
- * const sdk = new ATProtoSDK({
- *   // ...
- *   logger: console,
- * });
- * ```
- *
- * @example Using Pino
- * ```typescript
- * import pino from "pino";
- *
- * const logger = pino({ level: "debug" });
- * const sdk = new ATProtoSDK({
- *   // ...
- *   logger: logger,
- * });
- * ```
- *
- * @example Custom logger with context
- * ```typescript
- * const logger: LoggerInterface = {
- *   debug: (msg, ...args) => console.debug(`[SDK] ${msg}`, ...args),
- *   info: (msg, ...args) => console.info(`[SDK] ${msg}`, ...args),
- *   warn: (msg, ...args) => console.warn(`[SDK] ${msg}`, ...args),
- *   error: (msg, ...args) => console.error(`[SDK] ${msg}`, ...args),
- * };
- * ```
- */
-export interface LoggerInterface {
-  /**
-   * Logs debug-level messages.
-   *
-   * Used for detailed diagnostic information. May include sensitive
-   * data like request URLs and headers (but not tokens).
-   *
-   * @param message - The log message
-   * @param args - Additional arguments (objects, error details, etc.)
-   */
-  debug(message: string, ...args: unknown[]): void;
-
-  /**
-   * Logs info-level messages.
-   *
-   * Used for general operational information like successful
-   * initialization, authentication events, etc.
-   *
-   * @param message - The log message
-   * @param args - Additional arguments
-   */
-  info(message: string, ...args: unknown[]): void;
-
-  /**
-   * Logs warning-level messages.
-   *
-   * Used for potentially problematic situations that don't prevent
-   * operation but may indicate issues.
-   *
-   * @param message - The log message
-   * @param args - Additional arguments
-   */
-  warn(message: string, ...args: unknown[]): void;
-
-  /**
-   * Logs error-level messages.
-   *
-   * Used for error conditions that should be investigated.
-   * The SDK continues to operate after logging errors.
-   *
-   * @param message - The log message
-   * @param args - Additional arguments (typically includes the error object)
-   */
-  error(message: string, ...args: unknown[]): void;
-}