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

package/dist/testing.d.ts

@@ -0,0 +1,928 @@
+import { OAuthSession, NodeSavedSession, NodeSavedState } from '@atproto/oauth-client-node';
+import { z } from 'zod';
+
+/**
+ * OAuth session with DPoP (Demonstrating Proof of Possession) support.
+ *
+ * This type represents an authenticated user session. It wraps the
+ * `@atproto/oauth-client-node` OAuthSession and contains:
+ * - Access token for API requests
+ * - Refresh token for obtaining new access tokens
+ * - DPoP key pair for proof-of-possession
+ * - User's DID and other identity information
+ *
+ * @remarks
+ * Sessions are managed by the SDK and automatically refresh when tokens expire.
+ * Store the user's DID to restore sessions later with {@link ATProtoSDK.restoreSession}.
+ *
+ * Key properties from OAuthSession:
+ * - `did` or `sub`: The user's DID
+ * - `handle`: The user's handle (e.g., "user.bsky.social")
+ *
+ * @example
+ * ```typescript
+ * const session = await sdk.callback(params);
+ *
+ * // Access user identity
+ * console.log(`Logged in as: ${session.did}`);
+ *
+ * // Use session for repository operations
+ * const repo = sdk.repository(session);
+ * ```
+ *
+ * @see https://atproto.com/specs/oauth for OAuth specification
+ */
+type Session = OAuthSession;
+
+/**
+ * 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
+ */
+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
+ */
+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();
+ *   }
+ * }
+ * ```
+ */
+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),
+ * };
+ * ```
+ */
+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;
+}
+
+/**
+ * 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.
+ */
+declare const OAuthConfigSchema: z.ZodObject<{
+    /**
+     * 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.ZodString;
+    /**
+     * URL where users are redirected after authentication.
+     * Must match one of the redirect URIs in your client metadata.
+     */
+    redirectUri: z.ZodString;
+    /**
+     * OAuth scopes to request, space-separated.
+     * Common scopes: "atproto", "transition:generic"
+     */
+    scope: z.ZodString;
+    /**
+     * URL to your public JWKS (JSON Web Key Set) endpoint.
+     * Used by the authorization server to verify your client's signatures.
+     */
+    jwksUri: z.ZodString;
+    /**
+     * 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.ZodString;
+}, "strip", z.ZodTypeAny, {
+    clientId: string;
+    redirectUri: string;
+    scope: string;
+    jwksUri: string;
+    jwkPrivate: string;
+}, {
+    clientId: string;
+    redirectUri: string;
+    scope: string;
+    jwksUri: string;
+    jwkPrivate: string;
+}>;
+/**
+ * Zod schema for server URL configuration.
+ *
+ * @remarks
+ * At least one server (PDS or SDS) should be configured for the SDK to be useful.
+ */
+declare const ServerConfigSchema: z.ZodObject<{
+    /**
+     * 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.ZodOptional<z.ZodString>;
+    /**
+     * Shared Data Server URL - for collaborative data storage.
+     * Required for collaborator and organization operations.
+     *
+     * @example "https://sds.hypercerts.org"
+     */
+    sds: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    pds?: string | undefined;
+    sds?: string | undefined;
+}, {
+    pds?: string | undefined;
+    sds?: string | undefined;
+}>;
+/**
+ * Zod schema for timeout configuration.
+ *
+ * @remarks
+ * All timeout values are in milliseconds.
+ */
+declare const TimeoutConfigSchema: z.ZodObject<{
+    /**
+     * Timeout for fetching PDS metadata during identity resolution.
+     * @default 5000 (5 seconds, set by OAuthClient)
+     */
+    pdsMetadata: z.ZodOptional<z.ZodNumber>;
+    /**
+     * Timeout for general API requests to PDS/SDS.
+     * @default 30000 (30 seconds)
+     */
+    apiRequests: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    pdsMetadata?: number | undefined;
+    apiRequests?: number | undefined;
+}, {
+    pdsMetadata?: number | undefined;
+    apiRequests?: number | undefined;
+}>;
+/**
+ * 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,
+ * };
+ * ```
+ */
+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;
+}
+
+/**
+ * Mock factories for testing.
+ *
+ * This module provides factory functions to create mock objects
+ * for testing SDK functionality without real AT Protocol connections.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Creates a mock OAuth session for testing.
+ *
+ * The mock session includes all required properties and a mock
+ * `fetchHandler` that returns empty successful responses by default.
+ *
+ * @param overrides - Partial session object to override default values
+ * @returns A mock Session object suitable for testing
+ *
+ * @remarks
+ * The mock session is cast to `Session` type for compatibility.
+ * In real usage, sessions come from the OAuth flow and contain
+ * actual tokens and a real fetch handler.
+ *
+ * **Default Values**:
+ * - `did`: `"did:plc:test123"`
+ * - `handle`: `"test.bsky.social"`
+ * - `fetchHandler`: Returns `Response` with `{}` body
+ *
+ * @example Basic mock session
+ * ```typescript
+ * import { createMockSession } from "@hypercerts-org/sdk/testing";
+ *
+ * const session = createMockSession();
+ * const repo = sdk.repository(session);
+ * ```
+ *
+ * @example With custom DID
+ * ```typescript
+ * const session = createMockSession({
+ *   did: "did:plc:custom-test-user",
+ *   handle: "custom.bsky.social",
+ * });
+ * ```
+ *
+ * @example With custom fetch handler
+ * ```typescript
+ * const session = createMockSession({
+ *   fetchHandler: async (url, init) => {
+ *     // Custom response logic
+ *     return new Response(JSON.stringify({ success: true }));
+ *   },
+ * });
+ * ```
+ */
+declare function createMockSession(overrides?: Partial<Session>): Session;
+/**
+ * Creates a mock SDK configuration for testing.
+ *
+ * The configuration includes all required OAuth settings with
+ * placeholder values suitable for testing (not real credentials).
+ *
+ * @param overrides - Partial configuration to override default values
+ * @returns A complete ATProtoSDKConfig suitable for testing
+ *
+ * @remarks
+ * The default configuration uses example.com domains and a minimal
+ * JWK structure. This is sufficient for unit tests but won't work
+ * for integration tests that require real OAuth flows.
+ *
+ * **Default Values**:
+ * - `clientId`: `"https://test.example.com/client-metadata.json"`
+ * - `pds`: `"https://bsky.social"`
+ * - `sds`: `"https://sds.example.com"`
+ *
+ * @example Basic test config
+ * ```typescript
+ * import { createTestConfig } from "@hypercerts-org/sdk/testing";
+ *
+ * const config = createTestConfig();
+ * const sdk = new ATProtoSDK(config);
+ * ```
+ *
+ * @example With custom PDS
+ * ```typescript
+ * const config = createTestConfig({
+ *   servers: {
+ *     pds: "https://custom-pds.example.com",
+ *   },
+ * });
+ * ```
+ *
+ * @example With logger for debugging tests
+ * ```typescript
+ * const config = createTestConfig({
+ *   logger: console,
+ * });
+ * ```
+ */
+declare function createTestConfig(overrides?: Partial<ATProtoSDKConfig>): ATProtoSDKConfig;
+
+/**
+ * Mock storage implementations for testing.
+ *
+ * This module provides mock implementations of SessionStore and StateStore
+ * that track all operations for verification in tests.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Mock session store that tracks all operations.
+ *
+ * This implementation stores sessions in memory and records all
+ * method calls for verification in tests.
+ *
+ * @remarks
+ * Use this in tests to:
+ * - Verify that sessions are being stored correctly
+ * - Check what DIDs have been accessed
+ * - Assert on the number and order of operations
+ * - Pre-populate sessions for testing restore flows
+ *
+ * @example Basic usage
+ * ```typescript
+ * import { MockSessionStore } from "@hypercerts-org/sdk/testing";
+ *
+ * const sessionStore = new MockSessionStore();
+ * const sdk = new ATProtoSDK({
+ *   ...config,
+ *   storage: { sessionStore },
+ * });
+ *
+ * // After some operations...
+ * expect(sessionStore.setCalls).toHaveLength(1);
+ * expect(sessionStore.getCalls).toContain("did:plc:test123");
+ * ```
+ *
+ * @example Pre-populating for tests
+ * ```typescript
+ * const sessionStore = new MockSessionStore();
+ *
+ * // Pre-populate a session
+ * await sessionStore.set("did:plc:existing", mockSessionData);
+ *
+ * // Reset tracking (keeps the data)
+ * sessionStore.getCalls = [];
+ * sessionStore.setCalls = [];
+ *
+ * // Now test restore behavior
+ * const session = await sdk.restoreSession("did:plc:existing");
+ * expect(sessionStore.getCalls).toContain("did:plc:existing");
+ * ```
+ *
+ * @example Asserting on operations
+ * ```typescript
+ * const sessionStore = new MockSessionStore();
+ *
+ * // ... perform operations ...
+ *
+ * // Verify session was stored for correct DID
+ * expect(sessionStore.setCalls[0].did).toBe("did:plc:expected");
+ *
+ * // Verify session was deleted on logout
+ * expect(sessionStore.delCalls).toContain("did:plc:logged-out");
+ * ```
+ */
+declare class MockSessionStore implements SessionStore {
+    /**
+     * Internal storage for sessions.
+     * @internal
+     */
+    private store;
+    /**
+     * Record of all `get()` calls made to this store.
+     *
+     * Each entry is the DID that was requested.
+     */
+    getCalls: string[];
+    /**
+     * Record of all `set()` calls made to this store.
+     *
+     * Each entry contains the DID and session that was stored.
+     */
+    setCalls: Array<{
+        did: string;
+        session: NodeSavedSession;
+    }>;
+    /**
+     * Record of all `del()` calls made to this store.
+     *
+     * Each entry is the DID that was deleted.
+     */
+    delCalls: string[];
+    /**
+     * Retrieves a session by DID.
+     *
+     * Records the call in `getCalls`.
+     *
+     * @param did - The DID to look up
+     * @returns The stored session or undefined
+     */
+    get(did: string): Promise<NodeSavedSession | undefined>;
+    /**
+     * Stores a session.
+     *
+     * Records the call in `setCalls`.
+     *
+     * @param did - The DID to store under
+     * @param session - The session data to store
+     */
+    set(did: string, session: NodeSavedSession): Promise<void>;
+    /**
+     * Deletes a session.
+     *
+     * Records the call in `delCalls`.
+     *
+     * @param did - The DID to delete
+     */
+    del(did: string): Promise<void>;
+    /**
+     * Resets the store to initial state.
+     *
+     * Clears all stored sessions and all recorded calls.
+     * Call this in `beforeEach` or `afterEach` to ensure test isolation.
+     *
+     * @example
+     * ```typescript
+     * beforeEach(() => {
+     *   sessionStore.reset();
+     * });
+     * ```
+     */
+    reset(): void;
+}
+/**
+ * Mock state store that tracks all operations.
+ *
+ * This implementation stores OAuth state in memory and records all
+ * method calls for verification in tests.
+ *
+ * @remarks
+ * Use this in tests to:
+ * - Verify OAuth state is being created during authorization
+ * - Check that state is retrieved during callback
+ * - Assert that state is cleaned up after use
+ * - Test error handling for missing/invalid state
+ *
+ * @example Basic usage
+ * ```typescript
+ * import { MockStateStore } from "@hypercerts-org/sdk/testing";
+ *
+ * const stateStore = new MockStateStore();
+ * const sdk = new ATProtoSDK({
+ *   ...config,
+ *   storage: { stateStore },
+ * });
+ *
+ * // After authorize()
+ * expect(stateStore.setCalls).toHaveLength(1);
+ *
+ * // After callback()
+ * expect(stateStore.getCalls).toHaveLength(1);
+ * expect(stateStore.delCalls).toHaveLength(1);
+ * ```
+ *
+ * @example Testing invalid state
+ * ```typescript
+ * const stateStore = new MockStateStore();
+ * // Don't pre-populate - state will be missing
+ *
+ * // This should fail because state doesn't exist
+ * await expect(sdk.callback(params)).rejects.toThrow();
+ *
+ * // Verify the lookup was attempted
+ * expect(stateStore.getCalls).toContain(stateKey);
+ * ```
+ */
+declare class MockStateStore implements StateStore {
+    /**
+     * Internal storage for OAuth state.
+     * @internal
+     */
+    private store;
+    /**
+     * Record of all `get()` calls made to this store.
+     *
+     * Each entry is the state key that was requested.
+     */
+    getCalls: string[];
+    /**
+     * Record of all `set()` calls made to this store.
+     *
+     * Each entry contains the key and state that was stored.
+     */
+    setCalls: Array<{
+        key: string;
+        state: NodeSavedState;
+    }>;
+    /**
+     * Record of all `del()` calls made to this store.
+     *
+     * Each entry is the state key that was deleted.
+     */
+    delCalls: string[];
+    /**
+     * Retrieves OAuth state by key.
+     *
+     * Records the call in `getCalls`.
+     *
+     * @param key - The state key to look up
+     * @returns The stored state or undefined
+     */
+    get(key: string): Promise<NodeSavedState | undefined>;
+    /**
+     * Stores OAuth state.
+     *
+     * Records the call in `setCalls`.
+     *
+     * @param key - The state key to store under
+     * @param state - The OAuth state data to store
+     */
+    set(key: string, state: NodeSavedState): Promise<void>;
+    /**
+     * Deletes OAuth state.
+     *
+     * Records the call in `delCalls`.
+     *
+     * @param key - The state key to delete
+     */
+    del(key: string): Promise<void>;
+    /**
+     * Resets the store to initial state.
+     *
+     * Clears all stored state and all recorded calls.
+     * Call this in `beforeEach` or `afterEach` to ensure test isolation.
+     *
+     * @example
+     * ```typescript
+     * beforeEach(() => {
+     *   stateStore.reset();
+     * });
+     * ```
+     */
+    reset(): void;
+}
+
+export { MockSessionStore, MockStateStore, createMockSession, createTestConfig };