@hypercerts-org/sdk-core 0.5.0-beta.0 → 0.7.0-beta.0

package/src/core/SDK.ts

@@ -1,410 +0,0 @@
-import { OAuthClient } from "../auth/OAuthClient.js";
-import { LexiconRegistry } from "../repository/LexiconRegistry.js";
-import { Repository } from "../repository/Repository.js";
-import type { RepositoryOptions } from "../repository/types.js";
-import { InMemorySessionStore } from "../storage/InMemorySessionStore.js";
-import { InMemoryStateStore } from "../storage/InMemoryStateStore.js";
-import type { ATProtoSDKConfig } from "./config.js";
-import { ATProtoSDKConfigSchema } from "./config.js";
-import { ValidationError } from "./errors.js";
-import type { Session } from "./types.js";
-
-/**
- * Options for the OAuth authorization flow.
- */
-export interface AuthorizeOptions {
-  /**
-   * OAuth scope string to request specific permissions.
-   * Overrides the default scope configured in {@link ATProtoSDKConfig.oauth.scope}.
-   *
-   * @example
-   * ```typescript
-   * // Request read-only access
-   * await sdk.authorize("user.bsky.social", { scope: "atproto" });
-   *
-   * // Request full access (default typically includes transition:generic)
-   * await sdk.authorize("user.bsky.social", { scope: "atproto transition:generic" });
-   * ```
-   */
-  scope?: string;
-}
-
-/**
- * Main ATProto SDK class providing OAuth authentication and repository access.
- *
- * This is the primary entry point for interacting with AT Protocol servers.
- * It handles the OAuth 2.0 flow with DPoP (Demonstrating Proof of Possession)
- * and provides access to repository operations for managing records, blobs,
- * and profiles.
- *
- * @example Basic usage with OAuth flow
- * ```typescript
- * import { ATProtoSDK, InMemorySessionStore, InMemoryStateStore } from "@hypercerts-org/sdk";
- *
- * const sdk = new ATProtoSDK({
- *   oauth: {
- *     clientId: "https://my-app.com/client-metadata.json",
- *     redirectUri: "https://my-app.com/callback",
- *     scope: "atproto transition:generic",
- *     jwksUri: "https://my-app.com/.well-known/jwks.json",
- *     jwkPrivate: process.env.JWK_PRIVATE_KEY!,
- *   },
- *   servers: {
- *     pds: "https://bsky.social",
- *     sds: "https://sds.hypercerts.org",
- *   },
- * });
- *
- * // Start OAuth flow - redirect user to this URL
- * const authUrl = await sdk.authorize("user.bsky.social");
- *
- * // After user returns, handle the callback
- * const session = await sdk.callback(new URLSearchParams(window.location.search));
- *
- * // Get a repository to work with data
- * const repo = sdk.repository(session);
- * ```
- *
- * @example Restoring an existing session
- * ```typescript
- * // Restore a previous session by DID
- * const session = await sdk.restoreSession("did:plc:abc123...");
- * if (session) {
- *   const repo = sdk.repository(session);
- *   // Continue working with the restored session
- * }
- * ```
- *
- * @see {@link ATProtoSDKConfig} for configuration options
- * @see {@link Repository} for data operations
- * @see {@link OAuthClient} for OAuth implementation details
- */
-export class ATProtoSDK {
-  private oauthClient: OAuthClient;
-  private config: ATProtoSDKConfig;
-  private logger?: ATProtoSDKConfig["logger"];
-  private lexiconRegistry: LexiconRegistry;
-
-  /**
-   * Creates a new ATProto SDK instance.
-   *
-   * @param config - SDK configuration including OAuth credentials, server URLs, and optional storage adapters
-   * @throws {@link ValidationError} if the configuration is invalid (e.g., malformed URLs, missing required fields)
-   *
-   * @remarks
-   * If no storage adapters are provided, in-memory implementations are used.
-   * These are suitable for development and testing but **not recommended for production**
-   * as sessions will be lost on restart.
-   *
-   * @example
-   * ```typescript
-   * // Minimal configuration (uses in-memory storage)
-   * const sdk = new ATProtoSDK({
-   *   oauth: {
-   *     clientId: "https://my-app.com/client-metadata.json",
-   *     redirectUri: "https://my-app.com/callback",
-   *     scope: "atproto",
-   *     jwksUri: "https://my-app.com/.well-known/jwks.json",
-   *     jwkPrivate: privateKeyJwk,
-   *   },
-   *   servers: { pds: "https://bsky.social" },
-   * });
-   * ```
-   */
-  constructor(config: ATProtoSDKConfig) {
-    // Validate configuration
-    const validationResult = ATProtoSDKConfigSchema.safeParse(config);
-    if (!validationResult.success) {
-      throw new ValidationError(`Invalid SDK configuration: ${validationResult.error.message}`, validationResult.error);
-    }
-
-    // Apply defaults for optional storage
-    const configWithDefaults: ATProtoSDKConfig = {
-      ...config,
-      storage: {
-        sessionStore: config.storage?.sessionStore ?? new InMemorySessionStore(),
-        stateStore: config.storage?.stateStore ?? new InMemoryStateStore(),
-      },
-    };
-
-    this.config = configWithDefaults;
-    this.logger = config.logger;
-
-    // Initialize OAuth client
-    this.oauthClient = new OAuthClient(configWithDefaults);
-
-    // Initialize lexicon registry
-    this.lexiconRegistry = new LexiconRegistry();
-
-    this.logger?.info("ATProto SDK initialized");
-  }
-
-  /**
-   * Initiates the OAuth authorization flow.
-   *
-   * This method starts the OAuth 2.0 authorization flow by resolving the user's
-   * identity and generating an authorization URL. The user should be redirected
-   * to this URL to authenticate.
-   *
-   * @param identifier - The user's ATProto identifier. Can be:
-   *   - A handle (e.g., `"user.bsky.social"`)
-   *   - A DID (e.g., `"did:plc:abc123..."`)
-   *   - A PDS URL (e.g., `"https://bsky.social"`)
-   * @param options - Optional authorization settings
-   * @returns A Promise resolving to the authorization URL to redirect the user to
-   * @throws {@link ValidationError} if the identifier is empty or invalid
-   * @throws {@link NetworkError} if the identity cannot be resolved
-   *
-   * @example
-   * ```typescript
-   * // Using a handle
-   * const authUrl = await sdk.authorize("alice.bsky.social");
-   *
-   * // Using a DID directly
-   * const authUrl = await sdk.authorize("did:plc:abc123xyz");
-   *
-   * // With custom scope
-   * const authUrl = await sdk.authorize("alice.bsky.social", {
-   *   scope: "atproto transition:generic"
-   * });
-   *
-   * // Redirect user to authUrl
-   * window.location.href = authUrl;
-   * ```
-   */
-  async authorize(identifier: string, options?: AuthorizeOptions): Promise<string> {
-    if (!identifier || !identifier.trim()) {
-      throw new ValidationError("ATProto identifier is required");
-    }
-
-    return this.oauthClient.authorize(identifier.trim(), options);
-  }
-
-  /**
-   * Handles the OAuth callback and exchanges the authorization code for tokens.
-   *
-   * Call this method when the user is redirected back to your application
-   * after authenticating. It validates the OAuth state, exchanges the
-   * authorization code for access/refresh tokens, and creates a session.
-   *
-   * @param params - URL search parameters from the callback URL
-   * @returns A Promise resolving to the authenticated OAuth session
-   * @throws {@link AuthenticationError} if the callback parameters are invalid or the code exchange fails
-   * @throws {@link ValidationError} if required parameters are missing
-   *
-   * @example
-   * ```typescript
-   * // In your callback route handler
-   * const params = new URLSearchParams(window.location.search);
-   * // params contains: code, state, iss (issuer)
-   *
-   * const session = await sdk.callback(params);
-   * console.log(`Authenticated as ${session.did}`);
-   *
-   * // Store the DID to restore the session later
-   * localStorage.setItem("userDid", session.did);
-   * ```
-   */
-  async callback(params: URLSearchParams): Promise<Session> {
-    return this.oauthClient.callback(params);
-  }
-
-  /**
-   * Restores an existing OAuth session by DID.
-   *
-   * Use this method to restore a previously authenticated session, typically
-   * on application startup. The method retrieves the stored session and
-   * automatically refreshes expired tokens if needed.
-   *
-   * @param did - The user's Decentralized Identifier (DID), e.g., `"did:plc:abc123..."`
-   * @returns A Promise resolving to the restored session, or `null` if no session exists
-   * @throws {@link ValidationError} if the DID is empty
-   * @throws {@link SessionExpiredError} if the session cannot be refreshed
-   *
-   * @example
-   * ```typescript
-   * // On application startup
-   * const savedDid = localStorage.getItem("userDid");
-   * if (savedDid) {
-   *   const session = await sdk.restoreSession(savedDid);
-   *   if (session) {
-   *     // User is still authenticated
-   *     const repo = sdk.repository(session);
-   *   } else {
-   *     // Session not found, user needs to re-authenticate
-   *     const authUrl = await sdk.authorize(savedDid);
-   *   }
-   * }
-   * ```
-   */
-  async restoreSession(did: string): Promise<Session | null> {
-    if (!did || !did.trim()) {
-      throw new ValidationError("DID is required");
-    }
-
-    return this.oauthClient.restore(did.trim());
-  }
-
-  /**
-   * Revokes an OAuth session, logging the user out.
-   *
-   * This method invalidates the session's tokens and removes it from storage.
-   * After revocation, the session can no longer be used or restored.
-   *
-   * @param did - The user's DID to revoke the session for
-   * @throws {@link ValidationError} if the DID is empty
-   *
-   * @example
-   * ```typescript
-   * // Log out the user
-   * await sdk.revokeSession(session.did);
-   * localStorage.removeItem("userDid");
-   * ```
-   */
-  async revokeSession(did: string): Promise<void> {
-    if (!did || !did.trim()) {
-      throw new ValidationError("DID is required");
-    }
-
-    return this.oauthClient.revoke(did.trim());
-  }
-
-  /**
-   * Creates a repository instance for data operations.
-   *
-   * The repository provides a fluent API for working with AT Protocol data
-   * including records, blobs, profiles, and domain-specific operations like
-   * hypercerts and collaborators.
-   *
-   * @param session - An authenticated OAuth session
-   * @param options - Repository configuration options
-   * @returns A {@link Repository} instance configured for the specified server
-   * @throws {@link ValidationError} if the session is invalid or server URL is not configured
-   *
-   * @remarks
-   * - **PDS (Personal Data Server)**: User's own data storage, default for most operations
-   * - **SDS (Shared Data Server)**: Shared data storage with collaborator support
-   *
-   * @example Using default PDS
-   * ```typescript
-   * const repo = sdk.repository(session);
-   * const profile = await repo.profile.get();
-   * ```
-   *
-   * @example Using configured SDS
-   * ```typescript
-   * const sdsRepo = sdk.repository(session, { server: "sds" });
-   * const collaborators = await sdsRepo.collaborators.list();
-   * ```
-   *
-   * @example Using custom server URL
-   * ```typescript
-   * const customRepo = sdk.repository(session, {
-   *   serverUrl: "https://custom.atproto.server"
-   * });
-   * ```
-   */
-  repository(session: Session, options?: RepositoryOptions): Repository {
-    if (!session) {
-      throw new ValidationError("Session is required");
-    }
-
-    // Determine server URL
-    let serverUrl: string;
-    let isSDS = false;
-
-    if (options?.serverUrl) {
-      // Custom URL provided
-      serverUrl = options.serverUrl;
-      // Check if it matches configured SDS
-      isSDS = this.config.servers?.sds === serverUrl;
-    } else if (options?.server === "sds") {
-      // Use configured SDS
-      if (!this.config.servers?.sds) {
-        throw new ValidationError("SDS server URL not configured");
-      }
-      serverUrl = this.config.servers.sds;
-      isSDS = true;
-    } else if (options?.server === "pds" || !options?.server) {
-      // Use configured PDS (default)
-      if (!this.config.servers?.pds) {
-        throw new ValidationError("PDS server URL not configured");
-      }
-      serverUrl = this.config.servers.pds;
-      isSDS = false;
-    } else {
-      // Custom server string (treat as URL)
-      serverUrl = options.server;
-      isSDS = this.config.servers?.sds === serverUrl;
-    }
-
-    // Get repository DID (default to session DID)
-    const repoDid = session.did || session.sub;
-
-    return new Repository(session, serverUrl, repoDid, this.lexiconRegistry, isSDS, this.logger);
-  }
-
-  /**
-   * Gets the lexicon registry for schema validation.
-   *
-   * The lexicon registry manages AT Protocol lexicon schemas used for
-   * validating record data. You can register custom lexicons to extend
-   * the SDK's capabilities.
-   *
-   * @returns The {@link LexiconRegistry} instance
-   *
-   * @example
-   * ```typescript
-   * const registry = sdk.getLexiconRegistry();
-   *
-   * // Register custom lexicons
-   * registry.register(myCustomLexicons);
-   *
-   * // Check if a lexicon is registered
-   * const hasLexicon = registry.has("org.example.myRecord");
-   * ```
-   */
-  getLexiconRegistry(): LexiconRegistry {
-    return this.lexiconRegistry;
-  }
-
-  /**
-   * The configured PDS (Personal Data Server) URL.
-   *
-   * @returns The PDS URL if configured, otherwise `undefined`
-   */
-  get pdsUrl(): string | undefined {
-    return this.config.servers?.pds;
-  }
-
-  /**
-   * The configured SDS (Shared Data Server) URL.
-   *
-   * @returns The SDS URL if configured, otherwise `undefined`
-   */
-  get sdsUrl(): string | undefined {
-    return this.config.servers?.sds;
-  }
-}
-
-/**
- * Factory function to create an ATProto SDK instance.
- *
- * This is a convenience function equivalent to `new ATProtoSDK(config)`.
- *
- * @param config - SDK configuration
- * @returns A new {@link ATProtoSDK} instance
- *
- * @example
- * ```typescript
- * import { createATProtoSDK } from "@hypercerts-org/sdk";
- *
- * const sdk = createATProtoSDK({
- *   oauth: { ... },
- *   servers: { pds: "https://bsky.social" },
- * });
- * ```
- */
-export function createATProtoSDK(config: ATProtoSDKConfig): ATProtoSDK {
-  return new ATProtoSDK(config);
-}

package/src/core/config.ts

@@ -1,243 +0,0 @@
-import { z } from "zod";
-import type { SessionStore, StateStore, CacheInterface, LoggerInterface } from "./interfaces.js";
-
-/**
- * Zod schema for OAuth configuration validation.
- *
- * @remarks
- * All URLs must be valid and use HTTPS in production. The `jwkPrivate` field
- * should contain the private key in JWK (JSON Web Key) format as a string.
- */
-export const OAuthConfigSchema = z.object({
-  /**
-   * URL to the OAuth client metadata JSON document.
-   * This document describes your application to the authorization server.
-   *
-   * @see https://atproto.com/specs/oauth#client-metadata
-   */
-  clientId: z.string().url(),
-
-  /**
-   * URL where users are redirected after authentication.
-   * Must match one of the redirect URIs in your client metadata.
-   */
-  redirectUri: z.string().url(),
-
-  /**
-   * OAuth scopes to request, space-separated.
-   * Common scopes: "atproto", "transition:generic"
-   */
-  scope: z.string(),
-
-  /**
-   * URL to your public JWKS (JSON Web Key Set) endpoint.
-   * Used by the authorization server to verify your client's signatures.
-   */
-  jwksUri: z.string().url(),
-
-  /**
-   * Private JWK (JSON Web Key) as a JSON string.
-   * Used for signing DPoP proofs and client assertions.
-   *
-   * @remarks
-   * This should be kept secret and never exposed to clients.
-   * Typically loaded from environment variables or a secrets manager.
-   */
-  jwkPrivate: z.string(),
-});
-
-/**
- * Zod schema for server URL configuration.
- *
- * @remarks
- * At least one server (PDS or SDS) should be configured for the SDK to be useful.
- */
-export const ServerConfigSchema = z.object({
-  /**
-   * Personal Data Server URL - the user's own AT Protocol server.
-   * This is the primary server for user data operations.
-   *
-   * @example "https://bsky.social"
-   */
-  pds: z.string().url().optional(),
-
-  /**
-   * Shared Data Server URL - for collaborative data storage.
-   * Required for collaborator and organization operations.
-   *
-   * @example "https://sds.hypercerts.org"
-   */
-  sds: z.string().url().optional(),
-});
-
-/**
- * Zod schema for timeout configuration.
- *
- * @remarks
- * All timeout values are in milliseconds.
- */
-export const TimeoutConfigSchema = z.object({
-  /**
-   * Timeout for fetching PDS metadata during identity resolution.
-   * @default 5000 (5 seconds, set by OAuthClient)
-   */
-  pdsMetadata: z.number().positive().optional(),
-
-  /**
-   * Timeout for general API requests to PDS/SDS.
-   * @default 30000 (30 seconds)
-   */
-  apiRequests: z.number().positive().optional(),
-});
-
-/**
- * Zod schema for SDK configuration validation.
- *
- * @remarks
- * This schema validates only the primitive/serializable parts of the configuration.
- * Storage interfaces ({@link SessionStore}, {@link StateStore}) cannot be validated
- * with Zod as they are runtime objects.
- */
-export const ATProtoSDKConfigSchema = z.object({
-  oauth: OAuthConfigSchema,
-  servers: ServerConfigSchema.optional(),
-  timeouts: TimeoutConfigSchema.optional(),
-});
-
-/**
- * Configuration options for the ATProto SDK.
- *
- * This interface defines all configuration needed to initialize the SDK,
- * including OAuth credentials, server endpoints, and optional customizations.
- *
- * @example Minimal configuration
- * ```typescript
- * const config: ATProtoSDKConfig = {
- *   oauth: {
- *     clientId: "https://my-app.com/client-metadata.json",
- *     redirectUri: "https://my-app.com/callback",
- *     scope: "atproto transition:generic",
- *     jwksUri: "https://my-app.com/.well-known/jwks.json",
- *     jwkPrivate: process.env.JWK_PRIVATE_KEY!,
- *   },
- *   servers: {
- *     pds: "https://bsky.social",
- *   },
- * };
- * ```
- *
- * @example Full configuration with custom storage
- * ```typescript
- * const config: ATProtoSDKConfig = {
- *   oauth: { ... },
- *   servers: {
- *     pds: "https://bsky.social",
- *     sds: "https://sds.hypercerts.org",
- *   },
- *   storage: {
- *     sessionStore: new RedisSessionStore(redisClient),
- *     stateStore: new RedisStateStore(redisClient),
- *   },
- *   timeouts: {
- *     pdsMetadata: 5000,
- *     apiRequests: 30000,
- *   },
- *   logger: console,
- * };
- * ```
- */
-export interface ATProtoSDKConfig {
-  /**
-   * OAuth 2.0 configuration for authentication.
-   *
-   * Required fields for the OAuth flow with DPoP (Demonstrating Proof of Possession).
-   * Your application must host the client metadata and JWKS endpoints.
-   *
-   * @see https://atproto.com/specs/oauth for AT Protocol OAuth specification
-   */
-  oauth: z.infer<typeof OAuthConfigSchema>;
-
-  /**
-   * Server URLs for PDS and SDS connections.
-   *
-   * - **PDS**: Personal Data Server - user's own data storage
-   * - **SDS**: Shared Data Server - collaborative storage with access control
-   */
-  servers?: z.infer<typeof ServerConfigSchema>;
-
-  /**
-   * Storage adapters for persisting OAuth sessions and state.
-   *
-   * If not provided, in-memory implementations are used automatically.
-   * **Warning**: In-memory storage is lost on process restart - use persistent
-   * storage (Redis, database, etc.) in production.
-   *
-   * @example
-   * ```typescript
-   * storage: {
-   *   sessionStore: new RedisSessionStore(redis),
-   *   stateStore: new RedisStateStore(redis),
-   * }
-   * ```
-   */
-  storage?: {
-    /**
-     * Persistent storage for OAuth sessions.
-     * Sessions contain access tokens, refresh tokens, and DPoP keys.
-     */
-    sessionStore?: SessionStore;
-
-    /**
-     * Temporary storage for OAuth state during the authorization flow.
-     * State is short-lived and used for PKCE and CSRF protection.
-     */
-    stateStore?: StateStore;
-  };
-
-  /**
-   * Custom fetch implementation for HTTP requests.
-   *
-   * Use this to add custom headers, logging, or to use a different HTTP client.
-   * Must be compatible with the standard Fetch API.
-   *
-   * @example
-   * ```typescript
-   * fetch: async (url, init) => {
-   *   console.log(`Fetching: ${url}`);
-   *   return globalThis.fetch(url, init);
-   * }
-   * ```
-   */
-  fetch?: typeof fetch;
-
-  /**
-   * Timeout configuration for network requests.
-   * Values are in milliseconds.
-   */
-  timeouts?: z.infer<typeof TimeoutConfigSchema>;
-
-  /**
-   * Cache for profiles, metadata, and other frequently accessed data.
-   *
-   * Implementing caching can significantly reduce API calls and improve performance.
-   * The SDK does not provide a default cache - you must implement {@link CacheInterface}.
-   */
-  cache?: CacheInterface;
-
-  /**
-   * Logger for debugging and observability.
-   *
-   * The logger receives debug, info, warn, and error messages from the SDK.
-   * Compatible with `console` or any logger implementing {@link LoggerInterface}.
-   *
-   * @example
-   * ```typescript
-   * logger: console
-   * // or
-   * logger: pino()
-   * // or
-   * logger: winston.createLogger({ ... })
-   * ```
-   */
-  logger?: LoggerInterface;
-}