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

package/dist/index.d.ts

@@ -0,0 +1,3430 @@
+import { Agent } from '@atproto/api';
+import { LexiconDoc } from '@atproto/lexicon';
+import { NodeSavedSession, NodeSavedState, OAuthSession } from '@atproto/oauth-client-node';
+import { z } from 'zod';
+import { EventEmitter } from 'eventemitter3';
+import { OrgHypercertsClaim, OrgHypercertsCollection, ComAtprotoRepoStrongRef, OrgHypercertsClaimRights, OrgHypercertsClaimContribution, OrgHypercertsClaimMeasurement, OrgHypercertsClaimEvaluation, AppCertifiedLocation } from '@hypercerts-org/lexicon';
+export { AppCertifiedDefs, AppCertifiedLocation, ComAtprotoRepoStrongRef, HYPERCERT_COLLECTIONS, HYPERCERT_LEXICONS, OrgHypercertsClaim, OrgHypercertsClaimContribution, OrgHypercertsClaimEvaluation, OrgHypercertsClaimEvidence, OrgHypercertsClaimMeasurement, OrgHypercertsClaimRights, OrgHypercertsCollection, ids, lexicons, schemaDict, schemas, validate } from '@hypercerts-org/lexicon';
+
+/**
+ * Result of validating a record against a lexicon schema.
+ */
+interface ValidationResult {
+    /**
+     * Whether the record is valid according to the lexicon schema.
+     */
+    valid: boolean;
+    /**
+     * Error message if validation failed.
+     *
+     * Only present when `valid` is `false`.
+     */
+    error?: string;
+}
+/**
+ * Registry for managing and validating AT Protocol lexicon schemas.
+ *
+ * Lexicons are schema definitions that describe the structure of records
+ * in the AT Protocol. This registry allows you to:
+ *
+ * - Register custom lexicons for your application's record types
+ * - Validate records against their lexicon schemas
+ * - Extend the AT Protocol Agent with custom lexicon support
+ *
+ * @remarks
+ * The SDK automatically registers hypercert lexicons when creating a Repository.
+ * You only need to use this class directly if you're working with custom
+ * record types.
+ *
+ * **Lexicon IDs** follow the NSID (Namespaced Identifier) format:
+ * `{authority}.{name}` (e.g., `org.hypercerts.hypercert`)
+ *
+ * @example Registering custom lexicons
+ * ```typescript
+ * const registry = sdk.getLexiconRegistry();
+ *
+ * // Register a single lexicon
+ * registry.register({
+ *   lexicon: 1,
+ *   id: "org.example.myRecord",
+ *   defs: {
+ *     main: {
+ *       type: "record",
+ *       key: "tid",
+ *       record: {
+ *         type: "object",
+ *         required: ["title", "createdAt"],
+ *         properties: {
+ *           title: { type: "string" },
+ *           description: { type: "string" },
+ *           createdAt: { type: "string", format: "datetime" },
+ *         },
+ *       },
+ *     },
+ *   },
+ * });
+ *
+ * // Register multiple lexicons at once
+ * registry.registerMany([lexicon1, lexicon2, lexicon3]);
+ * ```
+ *
+ * @example Validating records
+ * ```typescript
+ * const result = registry.validate("org.example.myRecord", {
+ *   title: "Test",
+ *   createdAt: new Date().toISOString(),
+ * });
+ *
+ * if (!result.valid) {
+ *   console.error(`Validation failed: ${result.error}`);
+ * }
+ * ```
+ *
+ * @see https://atproto.com/specs/lexicon for the Lexicon specification
+ */
+declare class LexiconRegistry {
+    /** Map of lexicon ID to lexicon document */
+    private lexicons;
+    /** Lexicons collection for validation */
+    private lexiconsCollection;
+    /**
+     * Creates a new LexiconRegistry.
+     *
+     * The registry starts empty. Use {@link register} or {@link registerMany}
+     * to add lexicons.
+     */
+    constructor();
+    /**
+     * Registers a single lexicon schema.
+     *
+     * @param lexicon - The lexicon document to register
+     * @throws {@link ValidationError} if the lexicon doesn't have an `id` field
+     *
+     * @remarks
+     * If a lexicon with the same ID is already registered, it will be
+     * replaced with the new definition. This is useful for testing but
+     * should generally be avoided in production.
+     *
+     * @example
+     * ```typescript
+     * registry.register({
+     *   lexicon: 1,
+     *   id: "org.example.post",
+     *   defs: {
+     *     main: {
+     *       type: "record",
+     *       key: "tid",
+     *       record: {
+     *         type: "object",
+     *         required: ["text", "createdAt"],
+     *         properties: {
+     *           text: { type: "string", maxLength: 300 },
+     *           createdAt: { type: "string", format: "datetime" },
+     *         },
+     *       },
+     *     },
+     *   },
+     * });
+     * ```
+     */
+    register(lexicon: LexiconDoc): void;
+    /**
+     * Registers multiple lexicons at once.
+     *
+     * @param lexicons - Array of lexicon documents to register
+     *
+     * @example
+     * ```typescript
+     * import { HYPERCERT_LEXICONS } from "@hypercerts-org/sdk/lexicons";
+     *
+     * registry.registerMany(HYPERCERT_LEXICONS);
+     * ```
+     */
+    registerMany(lexicons: LexiconDoc[]): void;
+    /**
+     * Gets a lexicon document by ID.
+     *
+     * @param id - The lexicon NSID (e.g., "org.hypercerts.hypercert")
+     * @returns The lexicon document, or `undefined` if not registered
+     *
+     * @example
+     * ```typescript
+     * const lexicon = registry.get("org.hypercerts.hypercert");
+     * if (lexicon) {
+     *   console.log(`Found lexicon: ${lexicon.id}`);
+     * }
+     * ```
+     */
+    get(id: string): LexiconDoc | undefined;
+    /**
+     * Validates a record against a collection's lexicon schema.
+     *
+     * @param collection - The collection NSID (same as lexicon ID)
+     * @param record - The record data to validate
+     * @returns Validation result with `valid` boolean and optional `error` message
+     *
+     * @remarks
+     * - If no lexicon is registered for the collection, validation passes
+     *   (we can't validate against unknown schemas)
+     * - Validation checks required fields and type constraints defined
+     *   in the lexicon schema
+     *
+     * @example
+     * ```typescript
+     * const result = registry.validate("org.hypercerts.hypercert", {
+     *   title: "My Hypercert",
+     *   description: "Description...",
+     *   // ... other fields
+     * });
+     *
+     * if (!result.valid) {
+     *   throw new Error(`Invalid record: ${result.error}`);
+     * }
+     * ```
+     */
+    validate(collection: string, record: unknown): ValidationResult;
+    /**
+     * Adds all registered lexicons to an AT Protocol Agent instance.
+     *
+     * This allows the Agent to understand custom lexicon types when making
+     * API requests.
+     *
+     * @param agent - The Agent instance to extend
+     *
+     * @remarks
+     * This is called automatically when creating a Repository. You typically
+     * don't need to call this directly unless you're using the Agent
+     * independently.
+     *
+     * @internal
+     */
+    addToAgent(agent: Agent): void;
+    /**
+     * Gets all registered lexicon IDs.
+     *
+     * @returns Array of lexicon NSIDs
+     *
+     * @example
+     * ```typescript
+     * const ids = registry.getRegisteredIds();
+     * console.log(`Registered lexicons: ${ids.join(", ")}`);
+     * ```
+     */
+    getRegisteredIds(): string[];
+    /**
+     * Checks if a lexicon is registered.
+     *
+     * @param id - The lexicon NSID to check
+     * @returns `true` if the lexicon is registered
+     *
+     * @example
+     * ```typescript
+     * if (registry.has("org.hypercerts.hypercert")) {
+     *   // Hypercert lexicon is available
+     * }
+     * ```
+     */
+    has(id: string): boolean;
+}
+
+/**
+ * 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;
+}
+
+/**
+ * Decentralized Identifier (DID) - a unique, persistent identifier for AT Protocol users.
+ *
+ * DIDs are the canonical identifier for users in the AT Protocol ecosystem.
+ * Unlike handles which can change, DIDs remain constant for the lifetime of an account.
+ *
+ * @remarks
+ * AT Protocol supports multiple DID methods:
+ * - `did:plc:` - PLC (Public Ledger of Credentials) DIDs, most common for Bluesky users
+ * - `did:web:` - Web DIDs, resolved via HTTPS
+ *
+ * @example
+ * ```typescript
+ * const did: DID = "did:plc:ewvi7nxzyoun6zhxrhs64oiz";
+ * const webDid: DID = "did:web:example.com";
+ * ```
+ *
+ * @see https://atproto.com/specs/did for DID specification
+ */
+type DID = string;
+/**
+ * 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;
+/**
+ * Zod schema for collaborator permissions in SDS repositories.
+ *
+ * Defines the granular permissions a collaborator can have on a shared repository.
+ * Permissions follow a hierarchical model where higher-level permissions
+ * typically imply lower-level ones.
+ */
+declare const CollaboratorPermissionsSchema: z.ZodObject<{
+    /**
+     * Can read/view records in the repository.
+     * This is the most basic permission level.
+     */
+    read: z.ZodBoolean;
+    /**
+     * Can create new records in the repository.
+     * Typically implies `read` permission.
+     */
+    create: z.ZodBoolean;
+    /**
+     * Can modify existing records in the repository.
+     * Typically implies `read` and `create` permissions.
+     */
+    update: z.ZodBoolean;
+    /**
+     * Can delete records from the repository.
+     * Typically implies `read`, `create`, and `update` permissions.
+     */
+    delete: z.ZodBoolean;
+    /**
+     * Can manage collaborators and their permissions.
+     * Administrative permission that allows inviting/removing collaborators.
+     */
+    admin: z.ZodBoolean;
+    /**
+     * Full ownership of the repository.
+     * Owners have all permissions and cannot be removed by other admins.
+     * There must always be at least one owner.
+     */
+    owner: z.ZodBoolean;
+}, "strip", z.ZodTypeAny, {
+    read: boolean;
+    create: boolean;
+    update: boolean;
+    delete: boolean;
+    admin: boolean;
+    owner: boolean;
+}, {
+    read: boolean;
+    create: boolean;
+    update: boolean;
+    delete: boolean;
+    admin: boolean;
+    owner: boolean;
+}>;
+/**
+ * Collaborator permissions for SDS (Shared Data Server) repositories.
+ *
+ * These permissions control what actions a collaborator can perform
+ * on records within a shared repository.
+ *
+ * @example
+ * ```typescript
+ * // Read-only collaborator
+ * const readOnlyPerms: CollaboratorPermissions = {
+ *   read: true,
+ *   create: false,
+ *   update: false,
+ *   delete: false,
+ *   admin: false,
+ *   owner: false,
+ * };
+ *
+ * // Editor collaborator
+ * const editorPerms: CollaboratorPermissions = {
+ *   read: true,
+ *   create: true,
+ *   update: true,
+ *   delete: false,
+ *   admin: false,
+ *   owner: false,
+ * };
+ *
+ * // Admin collaborator
+ * const adminPerms: CollaboratorPermissions = {
+ *   read: true,
+ *   create: true,
+ *   update: true,
+ *   delete: true,
+ *   admin: true,
+ *   owner: false,
+ * };
+ * ```
+ */
+type CollaboratorPermissions = z.infer<typeof CollaboratorPermissionsSchema>;
+/**
+ * Zod schema for SDS organization data.
+ *
+ * Organizations are top-level entities in SDS that can own repositories
+ * and have multiple collaborators with different permission levels.
+ */
+declare const OrganizationSchema: z.ZodObject<{
+    /**
+     * The organization's DID - unique identifier.
+     * Format: "did:plc:..." or "did:web:..."
+     */
+    did: z.ZodString;
+    /**
+     * The organization's handle - human-readable identifier.
+     * Format: "orgname.sds.hypercerts.org" or similar
+     */
+    handle: z.ZodString;
+    /**
+     * Display name for the organization.
+     */
+    name: z.ZodString;
+    /**
+     * Optional description of the organization's purpose.
+     */
+    description: z.ZodOptional<z.ZodString>;
+    /**
+     * ISO 8601 timestamp when the organization was created.
+     * Format: "2024-01-15T10:30:00.000Z"
+     */
+    createdAt: z.ZodString;
+    /**
+     * The current user's permissions within this organization.
+     */
+    permissions: z.ZodObject<{
+        /**
+         * Can read/view records in the repository.
+         * This is the most basic permission level.
+         */
+        read: z.ZodBoolean;
+        /**
+         * Can create new records in the repository.
+         * Typically implies `read` permission.
+         */
+        create: z.ZodBoolean;
+        /**
+         * Can modify existing records in the repository.
+         * Typically implies `read` and `create` permissions.
+         */
+        update: z.ZodBoolean;
+        /**
+         * Can delete records from the repository.
+         * Typically implies `read`, `create`, and `update` permissions.
+         */
+        delete: z.ZodBoolean;
+        /**
+         * Can manage collaborators and their permissions.
+         * Administrative permission that allows inviting/removing collaborators.
+         */
+        admin: z.ZodBoolean;
+        /**
+         * Full ownership of the repository.
+         * Owners have all permissions and cannot be removed by other admins.
+         * There must always be at least one owner.
+         */
+        owner: z.ZodBoolean;
+    }, "strip", z.ZodTypeAny, {
+        read: boolean;
+        create: boolean;
+        update: boolean;
+        delete: boolean;
+        admin: boolean;
+        owner: boolean;
+    }, {
+        read: boolean;
+        create: boolean;
+        update: boolean;
+        delete: boolean;
+        admin: boolean;
+        owner: boolean;
+    }>;
+    /**
+     * How the current user relates to this organization.
+     * - `"owner"`: User created or owns the organization
+     * - `"collaborator"`: User was invited to collaborate
+     */
+    accessType: z.ZodEnum<["owner", "collaborator"]>;
+}, "strip", z.ZodTypeAny, {
+    did: string;
+    handle: string;
+    name: string;
+    createdAt: string;
+    permissions: {
+        read: boolean;
+        create: boolean;
+        update: boolean;
+        delete: boolean;
+        admin: boolean;
+        owner: boolean;
+    };
+    accessType: "owner" | "collaborator";
+    description?: string | undefined;
+}, {
+    did: string;
+    handle: string;
+    name: string;
+    createdAt: string;
+    permissions: {
+        read: boolean;
+        create: boolean;
+        update: boolean;
+        delete: boolean;
+        admin: boolean;
+        owner: boolean;
+    };
+    accessType: "owner" | "collaborator";
+    description?: string | undefined;
+}>;
+/**
+ * SDS Organization entity.
+ *
+ * Represents an organization on a Shared Data Server. Organizations
+ * provide a way to group repositories and manage access for teams.
+ *
+ * @example
+ * ```typescript
+ * const org: Organization = {
+ *   did: "did:plc:org123abc",
+ *   handle: "my-team.sds.hypercerts.org",
+ *   name: "My Team",
+ *   description: "A team working on impact certificates",
+ *   createdAt: "2024-01-15T10:30:00.000Z",
+ *   permissions: {
+ *     read: true,
+ *     create: true,
+ *     update: true,
+ *     delete: true,
+ *     admin: true,
+ *     owner: true,
+ *   },
+ *   accessType: "owner",
+ * };
+ * ```
+ */
+type Organization = z.infer<typeof OrganizationSchema>;
+/**
+ * Zod schema for collaborator data.
+ *
+ * Represents a user who has been granted access to a shared repository
+ * or organization with specific permissions.
+ */
+declare const CollaboratorSchema: z.ZodObject<{
+    /**
+     * The collaborator's DID - their unique identifier.
+     * Format: "did:plc:..." or "did:web:..."
+     */
+    userDid: z.ZodString;
+    /**
+     * The permissions granted to this collaborator.
+     */
+    permissions: z.ZodObject<{
+        /**
+         * Can read/view records in the repository.
+         * This is the most basic permission level.
+         */
+        read: z.ZodBoolean;
+        /**
+         * Can create new records in the repository.
+         * Typically implies `read` permission.
+         */
+        create: z.ZodBoolean;
+        /**
+         * Can modify existing records in the repository.
+         * Typically implies `read` and `create` permissions.
+         */
+        update: z.ZodBoolean;
+        /**
+         * Can delete records from the repository.
+         * Typically implies `read`, `create`, and `update` permissions.
+         */
+        delete: z.ZodBoolean;
+        /**
+         * Can manage collaborators and their permissions.
+         * Administrative permission that allows inviting/removing collaborators.
+         */
+        admin: z.ZodBoolean;
+        /**
+         * Full ownership of the repository.
+         * Owners have all permissions and cannot be removed by other admins.
+         * There must always be at least one owner.
+         */
+        owner: z.ZodBoolean;
+    }, "strip", z.ZodTypeAny, {
+        read: boolean;
+        create: boolean;
+        update: boolean;
+        delete: boolean;
+        admin: boolean;
+        owner: boolean;
+    }, {
+        read: boolean;
+        create: boolean;
+        update: boolean;
+        delete: boolean;
+        admin: boolean;
+        owner: boolean;
+    }>;
+    /**
+     * DID of the user who granted these permissions.
+     * Useful for audit trails.
+     */
+    grantedBy: z.ZodString;
+    /**
+     * ISO 8601 timestamp when permissions were granted.
+     * Format: "2024-01-15T10:30:00.000Z"
+     */
+    grantedAt: z.ZodString;
+    /**
+     * ISO 8601 timestamp when permissions were revoked, if applicable.
+     * Undefined if the collaborator is still active.
+     */
+    revokedAt: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    permissions: {
+        read: boolean;
+        create: boolean;
+        update: boolean;
+        delete: boolean;
+        admin: boolean;
+        owner: boolean;
+    };
+    userDid: string;
+    grantedBy: string;
+    grantedAt: string;
+    revokedAt?: string | undefined;
+}, {
+    permissions: {
+        read: boolean;
+        create: boolean;
+        update: boolean;
+        delete: boolean;
+        admin: boolean;
+        owner: boolean;
+    };
+    userDid: string;
+    grantedBy: string;
+    grantedAt: string;
+    revokedAt?: string | undefined;
+}>;
+/**
+ * Collaborator information for SDS repositories.
+ *
+ * Represents a user who has been granted access to collaborate on
+ * a shared repository or organization.
+ *
+ * @example
+ * ```typescript
+ * const collaborator: Collaborator = {
+ *   userDid: "did:plc:user456def",
+ *   permissions: {
+ *     read: true,
+ *     create: true,
+ *     update: true,
+ *     delete: false,
+ *     admin: false,
+ *     owner: false,
+ *   },
+ *   grantedBy: "did:plc:owner123abc",
+ *   grantedAt: "2024-02-01T14:00:00.000Z",
+ * };
+ * ```
+ */
+type Collaborator = z.infer<typeof CollaboratorSchema>;
+
+/**
+ * Repository types - Shared types for repository operations
+ * @packageDocumentation
+ */
+
+/**
+ * Options for creating a repository instance
+ */
+interface RepositoryOptions {
+    /** Use "sds" for configured SDS server, or provide a custom URL */
+    server?: "pds" | "sds" | string;
+    /** Custom server URL (overrides server option) */
+    serverUrl?: string;
+}
+/**
+ * Result of a create operation
+ */
+interface CreateResult {
+    uri: string;
+    cid: string;
+}
+/**
+ * Result of an update operation
+ */
+interface UpdateResult {
+    uri: string;
+    cid: string;
+}
+/**
+ * Paginated list result
+ */
+interface PaginatedList<T> {
+    records: T[];
+    cursor?: string;
+}
+/**
+ * List parameters
+ */
+interface ListParams {
+    limit?: number;
+    cursor?: string;
+}
+/**
+ * Role for repository access
+ */
+type RepositoryRole = "viewer" | "editor" | "admin" | "owner";
+/**
+ * Repository access grant
+ */
+interface RepositoryAccessGrant {
+    userDid: string;
+    role: RepositoryRole;
+    permissions: CollaboratorPermissions;
+    grantedBy: string;
+    grantedAt: string;
+    revokedAt?: string;
+}
+/**
+ * Organization info
+ */
+interface OrganizationInfo {
+    did: string;
+    handle: string;
+    name: string;
+    description?: string;
+    createdAt: string;
+    accessType: "owner" | "collaborator";
+    permissions: CollaboratorPermissions;
+    collaboratorCount?: number;
+    profile?: {
+        displayName?: string;
+        avatar?: string;
+        banner?: string;
+        website?: string;
+    };
+}
+/**
+ * Progress step for long-running operations
+ */
+interface ProgressStep {
+    name: string;
+    status: "start" | "success" | "error";
+    data?: unknown;
+    error?: Error;
+}
+
+/**
+ * TypeScript types for hypercert lexicon schemas.
+ *
+ * Re-exports generated types and validation from `@hypercerts-org/lexicon`.
+ *
+ * @packageDocumentation
+ */
+
+type StrongRef = ComAtprotoRepoStrongRef.Main;
+type HypercertClaim = OrgHypercertsClaim.Main;
+type HypercertRights = OrgHypercertsClaimRights.Main;
+type HypercertContribution = OrgHypercertsClaimContribution.Main;
+type HypercertMeasurement = OrgHypercertsClaimMeasurement.Main;
+type HypercertEvaluation = OrgHypercertsClaimEvaluation.Main;
+type HypercertCollection = OrgHypercertsCollection.Main;
+type HypercertCollectionClaimItem = OrgHypercertsCollection.ClaimItem;
+type HypercertLocation = AppCertifiedLocation.Main;
+/** Blob reference for uploaded files (images, GeoJSON, etc.) */
+interface BlobRef {
+    $type: "blob";
+    ref: {
+        $link: string;
+    };
+    mimeType: string;
+    size: number;
+}
+/** Evidence item for operations */
+interface HypercertEvidence {
+    uri: string;
+    title?: string;
+    description?: string;
+}
+/** Image input for operations */
+type HypercertImage = {
+    type: "uri";
+    uri: string;
+} | {
+    type: "blob";
+    blob: Blob;
+};
+/** Hypercert with AT Protocol metadata */
+interface HypercertWithMetadata {
+    uri: string;
+    cid: string;
+    record: HypercertClaim;
+}
+
+/**
+ * Repository interfaces - Operation contracts for repository functionality.
+ *
+ * This module defines the interfaces for all repository operations,
+ * providing clear contracts for record management, blob handling,
+ * profile management, and domain-specific operations.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Parameters for creating a new hypercert.
+ *
+ * This interface defines all the data needed to create a hypercert
+ * along with optional related records (location, contributions, evidence).
+ *
+ * @example Minimal hypercert
+ * ```typescript
+ * const params: CreateHypercertParams = {
+ *   title: "Community Garden Project",
+ *   description: "Established a 1-acre community garden serving 50 families",
+ *   workScope: "Food Security",
+ *   workTimeframeFrom: "2024-01-01",
+ *   workTimeframeTo: "2024-06-30",
+ *   rights: {
+ *     name: "Attribution",
+ *     type: "license",
+ *     description: "CC-BY-4.0",
+ *   },
+ * };
+ * ```
+ *
+ * @example Full hypercert with all options
+ * ```typescript
+ * const params: CreateHypercertParams = {
+ *   title: "Reforestation Initiative",
+ *   description: "Planted 10,000 trees in deforested areas",
+ *   shortDescription: "10K trees planted",
+ *   workScope: "Environmental Restoration",
+ *   workTimeframeFrom: "2024-01-01",
+ *   workTimeframeTo: "2024-12-31",
+ *   rights: {
+ *     name: "Open Impact",
+ *     type: "impact-rights",
+ *     description: "Transferable impact rights",
+ *   },
+ *   image: coverImageBlob,
+ *   location: {
+ *     value: "Amazon Rainforest, Brazil",
+ *     name: "Amazon Basin",
+ *     description: "Southern Amazon region",
+ *   },
+ *   contributions: [
+ *     {
+ *       contributors: ["did:plc:lead-org"],
+ *       role: "coordinator",
+ *       description: "Project coordination and funding",
+ *     },
+ *     {
+ *       contributors: ["did:plc:local-partner"],
+ *       role: "implementer",
+ *       description: "On-ground planting and monitoring",
+ *     },
+ *   ],
+ *   evidence: [
+ *     {
+ *       uri: "https://example.com/satellite-data",
+ *       description: "Satellite imagery showing reforestation progress",
+ *     },
+ *   ],
+ *   onProgress: (step) => console.log(`${step.name}: ${step.status}`),
+ * };
+ * ```
+ */
+interface CreateHypercertParams {
+    /**
+     * Title of the hypercert.
+     *
+     * Should be concise but descriptive of the impact claim.
+     */
+    title: string;
+    /**
+     * Detailed description of the impact.
+     *
+     * Can include methodology, outcomes, and other relevant details.
+     * Supports markdown formatting.
+     */
+    description: string;
+    /**
+     * Scope of work or impact area.
+     *
+     * @example "Climate Action", "Education", "Healthcare"
+     */
+    workScope: string;
+    /**
+     * Start date of the work period.
+     *
+     * ISO 8601 date format (YYYY-MM-DD).
+     */
+    workTimeframeFrom: string;
+    /**
+     * End date of the work period.
+     *
+     * ISO 8601 date format (YYYY-MM-DD).
+     */
+    workTimeframeTo: string;
+    /**
+     * Rights associated with the hypercert.
+     */
+    rights: {
+        /**
+         * Name of the rights.
+         *
+         * @example "Attribution", "Impact Rights", "Public Domain"
+         */
+        name: string;
+        /**
+         * Type of rights.
+         *
+         * @example "license", "impact-rights", "ownership"
+         */
+        type: string;
+        /**
+         * Description of the rights terms.
+         *
+         * @example "CC-BY-4.0", "Transferable impact rights"
+         */
+        description: string;
+    };
+    /**
+     * Optional short description for display in lists/cards.
+     *
+     * Should be under 200 characters.
+     */
+    shortDescription?: string;
+    /**
+     * Optional cover image for the hypercert.
+     *
+     * Recommended size: 1200x630 pixels (social media preview ratio).
+     */
+    image?: Blob;
+    /**
+     * Optional geographic location of the impact.
+     */
+    location?: {
+        /**
+         * Location value/address.
+         *
+         * @example "San Francisco, CA, USA"
+         */
+        value: string;
+        /**
+         * Human-readable location name.
+         *
+         * @example "SF Bay Area"
+         */
+        name?: string;
+        /**
+         * Description of the location scope.
+         */
+        description?: string;
+        /**
+         * Spatial Reference System identifier.
+         *
+         * @example "EPSG:4326" for WGS84
+         */
+        srs?: string;
+        /**
+         * GeoJSON file as a Blob for precise boundaries.
+         */
+        geojson?: Blob;
+    };
+    /**
+     * Optional list of contributions to the impact.
+     *
+     * Use this to credit multiple contributors with different roles.
+     */
+    contributions?: Array<{
+        /**
+         * DIDs of the contributors.
+         */
+        contributors: string[];
+        /**
+         * Role in the contribution.
+         *
+         * @example "coordinator", "implementer", "funder", "volunteer"
+         */
+        role: string;
+        /**
+         * Description of the contribution.
+         */
+        description?: string;
+    }>;
+    /**
+     * Optional evidence supporting the impact claim.
+     */
+    evidence?: HypercertEvidence[];
+    /**
+     * Optional callback for progress updates during creation.
+     *
+     * Called for each step of the creation process (image upload,
+     * record creation, attachment linking, etc.).
+     */
+    onProgress?: (step: ProgressStep) => void;
+}
+/**
+ * Result of creating a hypercert.
+ *
+ * Contains URIs and CIDs for all created records.
+ */
+interface CreateHypercertResult {
+    /**
+     * AT-URI of the main hypercert record.
+     */
+    hypercertUri: string;
+    /**
+     * AT-URI of the associated rights record.
+     */
+    rightsUri: string;
+    /**
+     * CID of the hypercert record.
+     */
+    hypercertCid: string;
+    /**
+     * CID of the rights record.
+     */
+    rightsCid: string;
+    /**
+     * AT-URI of the location record, if location was provided.
+     */
+    locationUri?: string;
+    /**
+     * AT-URIs of contribution records, if contributions were provided.
+     */
+    contributionUris?: string[];
+}
+/**
+ * Low-level record operations for AT Protocol CRUD.
+ *
+ * Use this interface for direct access to AT Protocol records when
+ * the high-level APIs don't meet your needs.
+ *
+ * @example
+ * ```typescript
+ * // Create a record
+ * const { uri, cid } = await repo.records.create({
+ *   collection: "org.example.mytype",
+ *   record: { foo: "bar", createdAt: new Date().toISOString() },
+ * });
+ *
+ * // Get a record
+ * const { value } = await repo.records.get({
+ *   collection: "org.example.mytype",
+ *   rkey: "abc123",
+ * });
+ *
+ * // Update a record
+ * await repo.records.update({
+ *   collection: "org.example.mytype",
+ *   rkey: "abc123",
+ *   record: { ...value, foo: "updated" },
+ * });
+ *
+ * // List records
+ * const { records, cursor } = await repo.records.list({
+ *   collection: "org.example.mytype",
+ *   limit: 50,
+ * });
+ *
+ * // Delete a record
+ * await repo.records.delete({
+ *   collection: "org.example.mytype",
+ *   rkey: "abc123",
+ * });
+ * ```
+ */
+interface RecordOperations {
+    /**
+     * Creates a new record in a collection.
+     *
+     * @param params - Creation parameters
+     * @param params.collection - NSID of the collection (e.g., "org.hypercerts.hypercert")
+     * @param params.record - Record data (must conform to collection's lexicon)
+     * @param params.rkey - Optional record key. Auto-generated if not provided.
+     * @returns Promise resolving to the created record's URI and CID
+     */
+    create(params: {
+        collection: string;
+        record: unknown;
+        rkey?: string;
+    }): Promise<CreateResult>;
+    /**
+     * Updates an existing record.
+     *
+     * @param params - Update parameters
+     * @param params.collection - NSID of the collection
+     * @param params.rkey - Record key to update
+     * @param params.record - New record data (replaces entire record)
+     * @returns Promise resolving to the updated record's URI and CID
+     */
+    update(params: {
+        collection: string;
+        rkey: string;
+        record: unknown;
+    }): Promise<UpdateResult>;
+    /**
+     * Gets a single record by collection and key.
+     *
+     * @param params - Get parameters
+     * @param params.collection - NSID of the collection
+     * @param params.rkey - Record key
+     * @returns Promise resolving to the record's URI, CID, and value
+     */
+    get(params: {
+        collection: string;
+        rkey: string;
+    }): Promise<{
+        uri: string;
+        cid: string;
+        value: unknown;
+    }>;
+    /**
+     * Lists records in a collection with pagination.
+     *
+     * @param params - List parameters
+     * @param params.collection - NSID of the collection
+     * @param params.limit - Maximum records to return (default varies by server)
+     * @param params.cursor - Pagination cursor from previous response
+     * @returns Promise resolving to paginated list of records
+     */
+    list(params: {
+        collection: string;
+        limit?: number;
+        cursor?: string;
+    }): Promise<PaginatedList<{
+        uri: string;
+        cid: string;
+        value: unknown;
+    }>>;
+    /**
+     * Deletes a record.
+     *
+     * @param params - Delete parameters
+     * @param params.collection - NSID of the collection
+     * @param params.rkey - Record key to delete
+     */
+    delete(params: {
+        collection: string;
+        rkey: string;
+    }): Promise<void>;
+}
+/**
+ * Blob operations for binary data handling.
+ *
+ * Blobs are used for images, files, and other binary content.
+ * They are referenced from records using blob references.
+ *
+ * @example
+ * ```typescript
+ * // Upload an image
+ * const imageBlob = new Blob([imageData], { type: "image/jpeg" });
+ * const { ref, mimeType, size } = await repo.blobs.upload(imageBlob);
+ *
+ * // Use the ref in a record
+ * await repo.records.create({
+ *   collection: "org.example.post",
+ *   record: {
+ *     text: "Hello!",
+ *     image: ref,  // { $link: "bafyrei..." }
+ *   },
+ * });
+ *
+ * // Retrieve a blob
+ * const { data, mimeType } = await repo.blobs.get(ref.$link);
+ * ```
+ */
+interface BlobOperations {
+    /**
+     * Uploads a blob to the server.
+     *
+     * @param blob - The blob to upload
+     * @returns Promise resolving to blob reference and metadata
+     */
+    upload(blob: Blob): Promise<{
+        /**
+         * Blob reference to use in records.
+         *
+         * Contains `$link` property with the CID.
+         */
+        ref: {
+            $link: string;
+        };
+        /**
+         * MIME type of the uploaded blob.
+         */
+        mimeType: string;
+        /**
+         * Size of the blob in bytes.
+         */
+        size: number;
+    }>;
+    /**
+     * Retrieves a blob by its CID.
+     *
+     * @param cid - Content Identifier of the blob
+     * @returns Promise resolving to blob data and MIME type
+     */
+    get(cid: string): Promise<{
+        /**
+         * Raw blob data as Uint8Array.
+         */
+        data: Uint8Array;
+        /**
+         * MIME type of the blob.
+         */
+        mimeType: string;
+    }>;
+}
+/**
+ * Profile operations for user profile management.
+ *
+ * @example
+ * ```typescript
+ * // Get profile
+ * const profile = await repo.profile.get();
+ * console.log(profile.displayName);
+ *
+ * // Update profile
+ * await repo.profile.update({
+ *   displayName: "New Name",
+ *   description: "Updated bio",
+ * });
+ *
+ * // Update avatar
+ * await repo.profile.update({
+ *   avatar: new Blob([avatarData], { type: "image/png" }),
+ * });
+ *
+ * // Clear a field by passing null
+ * await repo.profile.update({
+ *   website: null,  // Removes website
+ * });
+ * ```
+ */
+interface ProfileOperations {
+    /**
+     * Gets the repository's profile.
+     *
+     * @returns Promise resolving to profile data
+     */
+    get(): Promise<{
+        /**
+         * User's handle (e.g., "alice.bsky.social").
+         */
+        handle: string;
+        /**
+         * Display name.
+         */
+        displayName?: string;
+        /**
+         * Profile description/bio.
+         */
+        description?: string;
+        /**
+         * Avatar image URL or blob reference.
+         */
+        avatar?: string;
+        /**
+         * Banner image URL or blob reference.
+         */
+        banner?: string;
+        /**
+         * Website URL.
+         */
+        website?: string;
+    }>;
+    /**
+     * Updates the repository's profile.
+     *
+     * Pass `null` to clear a field. Omitted fields are unchanged.
+     *
+     * @param params - Fields to update
+     * @returns Promise resolving to update result
+     */
+    update(params: {
+        displayName?: string | null;
+        description?: string | null;
+        avatar?: Blob | null;
+        banner?: Blob | null;
+        website?: string | null;
+    }): Promise<UpdateResult>;
+}
+/**
+ * Events emitted by hypercert operations.
+ *
+ * Use these to track progress of complex operations or react
+ * to record changes.
+ */
+interface HypercertEvents {
+    /**
+     * Emitted when a hypercert record is created.
+     */
+    recordCreated: {
+        uri: string;
+        cid: string;
+    };
+    /**
+     * Emitted when a hypercert record is updated.
+     */
+    recordUpdated: {
+        uri: string;
+        cid: string;
+    };
+    /**
+     * Emitted when a rights record is created.
+     */
+    rightsCreated: {
+        uri: string;
+        cid: string;
+    };
+    /**
+     * Emitted when a location is attached to a hypercert.
+     */
+    locationAttached: {
+        uri: string;
+        cid: string;
+        hypercertUri: string;
+    };
+    /**
+     * Emitted when a contribution record is created.
+     */
+    contributionCreated: {
+        uri: string;
+        cid: string;
+    };
+    /**
+     * Emitted when evidence is added to a hypercert.
+     */
+    evidenceAdded: {
+        uri: string;
+        cid: string;
+    };
+    /**
+     * Emitted when a collection is created.
+     */
+    collectionCreated: {
+        uri: string;
+        cid: string;
+    };
+}
+/**
+ * High-level hypercert operations.
+ *
+ * Provides a convenient API for creating and managing hypercerts
+ * with automatic handling of related records (rights, locations,
+ * contributions, etc.).
+ *
+ * Extends EventEmitter to provide progress events.
+ *
+ * @example Basic usage
+ * ```typescript
+ * // Create a hypercert
+ * const result = await repo.hypercerts.create({
+ *   title: "Impact Project",
+ *   description: "Description...",
+ *   workScope: "Climate",
+ *   workTimeframeFrom: "2024-01-01",
+ *   workTimeframeTo: "2024-12-31",
+ *   rights: { name: "CC-BY", type: "license", description: "..." },
+ * });
+ *
+ * // List hypercerts
+ * const { records } = await repo.hypercerts.list({ limit: 20 });
+ *
+ * // Get a specific hypercert
+ * const hypercert = await repo.hypercerts.get(result.hypercertUri);
+ * ```
+ *
+ * @example With events
+ * ```typescript
+ * repo.hypercerts.on("recordCreated", ({ uri }) => {
+ *   console.log(`Created: ${uri}`);
+ * });
+ * ```
+ */
+interface HypercertOperations extends EventEmitter<HypercertEvents> {
+    /**
+     * Creates a new hypercert with all related records.
+     *
+     * @param params - Creation parameters
+     * @returns Promise resolving to URIs and CIDs of created records
+     */
+    create(params: CreateHypercertParams): Promise<CreateHypercertResult>;
+    /**
+     * Updates an existing hypercert.
+     *
+     * @param params - Update parameters
+     * @param params.uri - AT-URI of the hypercert to update
+     * @param params.updates - Fields to update
+     * @param params.image - New image, or `null` to remove
+     * @returns Promise resolving to update result
+     */
+    update(params: {
+        uri: string;
+        updates: Partial<Omit<HypercertClaim, "$type" | "createdAt" | "rights">>;
+        image?: Blob | null;
+    }): Promise<UpdateResult>;
+    /**
+     * Gets a hypercert by URI.
+     *
+     * @param uri - AT-URI of the hypercert
+     * @returns Promise resolving to hypercert data
+     */
+    get(uri: string): Promise<{
+        uri: string;
+        cid: string;
+        record: HypercertClaim;
+    }>;
+    /**
+     * Lists hypercerts with pagination.
+     *
+     * @param params - Optional pagination parameters
+     * @returns Promise resolving to paginated list
+     */
+    list(params?: ListParams): Promise<PaginatedList<{
+        uri: string;
+        cid: string;
+        record: HypercertClaim;
+    }>>;
+    /**
+     * Deletes a hypercert.
+     *
+     * Note: This does not automatically delete related records
+     * (rights, locations, contributions).
+     *
+     * @param uri - AT-URI of the hypercert to delete
+     */
+    delete(uri: string): Promise<void>;
+    /**
+     * Attaches a location to an existing hypercert.
+     *
+     * @param uri - AT-URI of the hypercert
+     * @param location - Location data
+     * @returns Promise resolving to location record result
+     */
+    attachLocation(uri: string, location: {
+        value: string;
+        name?: string;
+        description?: string;
+        srs?: string;
+        geojson?: Blob;
+    }): Promise<CreateResult>;
+    /**
+     * Adds evidence to an existing hypercert.
+     *
+     * @param uri - AT-URI of the hypercert
+     * @param evidence - Array of evidence items to add
+     * @returns Promise resolving to update result
+     */
+    addEvidence(uri: string, evidence: HypercertEvidence[]): Promise<UpdateResult>;
+    /**
+     * Creates a contribution record.
+     *
+     * @param params - Contribution parameters
+     * @returns Promise resolving to contribution record result
+     */
+    addContribution(params: {
+        hypercertUri?: string;
+        contributors: string[];
+        role: string;
+        description?: string;
+    }): Promise<CreateResult>;
+    /**
+     * Creates a measurement record for a hypercert.
+     *
+     * @param params - Measurement parameters
+     * @returns Promise resolving to measurement record result
+     */
+    addMeasurement(params: {
+        hypercertUri: string;
+        measurers: string[];
+        metric: string;
+        value: string;
+        methodUri?: string;
+        evidenceUris?: string[];
+    }): Promise<CreateResult>;
+    /**
+     * Creates an evaluation record.
+     *
+     * @param params - Evaluation parameters
+     * @returns Promise resolving to evaluation record result
+     */
+    addEvaluation(params: {
+        subjectUri: string;
+        evaluators: string[];
+        summary: string;
+    }): Promise<CreateResult>;
+    /**
+     * Creates a collection of hypercerts.
+     *
+     * @param params - Collection parameters
+     * @returns Promise resolving to collection record result
+     */
+    createCollection(params: {
+        title: string;
+        claims: Array<{
+            uri: string;
+            cid: string;
+            weight: string;
+        }>;
+        shortDescription?: string;
+        coverPhoto?: Blob;
+    }): Promise<CreateResult>;
+    /**
+     * Gets a collection by URI.
+     *
+     * @param uri - AT-URI of the collection
+     * @returns Promise resolving to collection data
+     */
+    getCollection(uri: string): Promise<{
+        uri: string;
+        cid: string;
+        record: HypercertCollection;
+    }>;
+    /**
+     * Lists collections with pagination.
+     *
+     * @param params - Optional pagination parameters
+     * @returns Promise resolving to paginated list
+     */
+    listCollections(params?: ListParams): Promise<PaginatedList<{
+        uri: string;
+        cid: string;
+        record: HypercertCollection;
+    }>>;
+}
+/**
+ * Collaborator operations for SDS access control.
+ *
+ * **SDS Only**: These operations are only available on Shared Data Servers.
+ *
+ * @example
+ * ```typescript
+ * // Grant access
+ * await repo.collaborators.grant({
+ *   userDid: "did:plc:new-user",
+ *   role: "editor",
+ * });
+ *
+ * // List collaborators
+ * const collaborators = await repo.collaborators.list();
+ *
+ * // Check access
+ * const hasAccess = await repo.collaborators.hasAccess("did:plc:someone");
+ * const role = await repo.collaborators.getRole("did:plc:someone");
+ *
+ * // Revoke access
+ * await repo.collaborators.revoke({ userDid: "did:plc:former-user" });
+ * ```
+ */
+interface CollaboratorOperations {
+    /**
+     * Grants repository access to a user.
+     *
+     * @param params - Grant parameters
+     * @param params.userDid - DID of the user to grant access to
+     * @param params.role - Role to assign
+     */
+    grant(params: {
+        userDid: string;
+        role: RepositoryRole;
+    }): Promise<void>;
+    /**
+     * Revokes repository access from a user.
+     *
+     * @param params - Revoke parameters
+     * @param params.userDid - DID of the user to revoke access from
+     */
+    revoke(params: {
+        userDid: string;
+    }): Promise<void>;
+    /**
+     * Lists all collaborators on the repository.
+     *
+     * @returns Promise resolving to array of access grants
+     */
+    list(): Promise<RepositoryAccessGrant[]>;
+    /**
+     * Checks if a user has any access to the repository.
+     *
+     * @param userDid - DID to check
+     * @returns Promise resolving to boolean
+     */
+    hasAccess(userDid: string): Promise<boolean>;
+    /**
+     * Gets the role assigned to a user.
+     *
+     * @param userDid - DID to check
+     * @returns Promise resolving to role, or `null` if no access
+     */
+    getRole(userDid: string): Promise<RepositoryRole | null>;
+}
+/**
+ * Organization operations for SDS organization management.
+ *
+ * **SDS Only**: These operations are only available on Shared Data Servers.
+ *
+ * @example
+ * ```typescript
+ * // Create an organization
+ * const org = await repo.organizations.create({
+ *   name: "My Team",
+ *   description: "A team for impact projects",
+ * });
+ *
+ * // List organizations
+ * const orgs = await repo.organizations.list();
+ *
+ * // Get organization details
+ * const orgInfo = await repo.organizations.get(org.did);
+ * ```
+ */
+interface OrganizationOperations {
+    /**
+     * Creates a new organization.
+     *
+     * @param params - Organization parameters
+     * @param params.name - Organization name
+     * @param params.description - Optional description
+     * @param params.handle - Optional custom handle
+     * @returns Promise resolving to organization info
+     */
+    create(params: {
+        name: string;
+        description?: string;
+        handle?: string;
+    }): Promise<OrganizationInfo>;
+    /**
+     * Gets an organization by DID.
+     *
+     * @param did - Organization DID
+     * @returns Promise resolving to organization info, or `null` if not found
+     */
+    get(did: string): Promise<OrganizationInfo | null>;
+    /**
+     * Lists organizations the current user has access to.
+     *
+     * @returns Promise resolving to array of organization info
+     */
+    list(): Promise<OrganizationInfo[]>;
+}
+
+/**
+ * Repository - Unified fluent API for ATProto repository operations.
+ *
+ * This module provides the main interface for interacting with AT Protocol
+ * data servers (PDS and SDS) through a consistent, fluent API.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Repository provides a fluent API for AT Protocol data operations.
+ *
+ * This class is the primary interface for working with data in the AT Protocol
+ * ecosystem. It provides organized access to:
+ *
+ * - **Records**: Low-level CRUD operations for any AT Protocol record type
+ * - **Blobs**: Binary data upload and retrieval (images, files)
+ * - **Profile**: User profile management
+ * - **Hypercerts**: High-level hypercert creation and management
+ * - **Collaborators**: Access control for shared repositories (SDS only)
+ * - **Organizations**: Organization management (SDS only)
+ *
+ * @remarks
+ * The Repository uses lazy initialization for operation handlers - they are
+ * created only when first accessed. This improves performance when you only
+ * need a subset of operations.
+ *
+ * **PDS vs SDS:**
+ * - **PDS (Personal Data Server)**: User's own data storage. All operations
+ *   except collaborators and organizations are available.
+ * - **SDS (Shared Data Server)**: Collaborative data storage with access
+ *   control. All operations including collaborators and organizations.
+ *
+ * @example Basic usage
+ * ```typescript
+ * // Get a repository from the SDK
+ * const repo = sdk.repository(session);
+ *
+ * // Access user profile
+ * const profile = await repo.profile.get();
+ *
+ * // Create a hypercert
+ * const result = await repo.hypercerts.create({
+ *   title: "My Impact",
+ *   description: "Description of the impact",
+ *   workScope: "Climate Action",
+ *   workTimeframeFrom: "2024-01-01",
+ *   workTimeframeTo: "2024-12-31",
+ *   rights: {
+ *     name: "Attribution",
+ *     type: "license",
+ *     description: "CC-BY-4.0",
+ *   },
+ * });
+ * ```
+ *
+ * @example Working with a different user's repository
+ * ```typescript
+ * // Get the current user's repo
+ * const myRepo = sdk.repository(session);
+ *
+ * // Get another user's repo (read-only for most operations)
+ * const otherRepo = myRepo.repo("did:plc:other-user-did");
+ * const theirProfile = await otherRepo.profile.get();
+ * ```
+ *
+ * @example SDS operations
+ * ```typescript
+ * // Get SDS repository for collaborator features
+ * const sdsRepo = sdk.repository(session, { server: "sds" });
+ *
+ * // Manage collaborators
+ * await sdsRepo.collaborators.grant({
+ *   userDid: "did:plc:collaborator",
+ *   role: "editor",
+ * });
+ *
+ * // List organizations
+ * const orgs = await sdsRepo.organizations.list();
+ * ```
+ *
+ * @see {@link ATProtoSDK.repository} for creating Repository instances
+ */
+declare class Repository {
+    private session;
+    private serverUrl;
+    private repoDid;
+    private lexiconRegistry;
+    private logger?;
+    private agent;
+    private _isSDS;
+    private _records?;
+    private _blobs?;
+    private _profile?;
+    private _hypercerts?;
+    private _collaborators?;
+    private _organizations?;
+    /**
+     * Creates a new Repository instance.
+     *
+     * @param session - Authenticated OAuth session
+     * @param serverUrl - Base URL of the AT Protocol server
+     * @param repoDid - DID of the repository to operate on
+     * @param lexiconRegistry - Registry for lexicon validation
+     * @param isSDS - Whether this is a Shared Data Server
+     * @param logger - Optional logger for debugging
+     *
+     * @remarks
+     * This constructor is typically not called directly. Use
+     * {@link ATProtoSDK.repository} to create Repository instances.
+     *
+     * @internal
+     */
+    constructor(session: Session, serverUrl: string, repoDid: string, lexiconRegistry: LexiconRegistry, isSDS: boolean, logger?: LoggerInterface);
+    /**
+     * The DID (Decentralized Identifier) of this repository.
+     *
+     * This is the user or organization that owns the repository data.
+     *
+     * @example
+     * ```typescript
+     * console.log(`Working with repo: ${repo.did}`);
+     * // Output: Working with repo: did:plc:abc123xyz...
+     * ```
+     */
+    get did(): string;
+    /**
+     * Whether this repository is on a Shared Data Server (SDS).
+     *
+     * SDS servers support additional features like collaborators and
+     * organizations. Attempting to use these features on a PDS will
+     * throw {@link SDSRequiredError}.
+     *
+     * @example
+     * ```typescript
+     * if (repo.isSDS) {
+     *   const collaborators = await repo.collaborators.list();
+     * }
+     * ```
+     */
+    get isSDS(): boolean;
+    /**
+     * Gets the server URL this repository connects to.
+     *
+     * @returns The base URL of the AT Protocol server
+     *
+     * @example
+     * ```typescript
+     * console.log(repo.getServerUrl());
+     * // Output: https://bsky.social or https://sds.hypercerts.org
+     * ```
+     */
+    getServerUrl(): string;
+    /**
+     * Creates a Repository instance for a different DID on the same server.
+     *
+     * This allows you to read data from other users' repositories while
+     * maintaining your authenticated session.
+     *
+     * @param did - The DID of the repository to access
+     * @returns A new Repository instance for the specified DID
+     *
+     * @remarks
+     * Write operations on another user's repository will typically fail
+     * unless you have been granted collaborator access (SDS only).
+     *
+     * @example
+     * ```typescript
+     * // Read another user's profile
+     * const otherRepo = repo.repo("did:plc:other-user");
+     * const profile = await otherRepo.profile.get();
+     *
+     * // List their public hypercerts
+     * const hypercerts = await otherRepo.hypercerts.list();
+     * ```
+     */
+    repo(did: string): Repository;
+    /**
+     * Low-level record operations for CRUD on any AT Protocol record type.
+     *
+     * Use this for direct access to AT Protocol records when the high-level
+     * APIs don't meet your needs.
+     *
+     * @returns {@link RecordOperations} interface for record CRUD
+     *
+     * @example
+     * ```typescript
+     * // Create a custom record
+     * const result = await repo.records.create({
+     *   collection: "org.example.myRecord",
+     *   record: { foo: "bar" },
+     * });
+     *
+     * // List records in a collection
+     * const list = await repo.records.list({
+     *   collection: "org.example.myRecord",
+     *   limit: 50,
+     * });
+     *
+     * // Get a specific record
+     * const record = await repo.records.get({
+     *   collection: "org.example.myRecord",
+     *   rkey: "abc123",
+     * });
+     * ```
+     */
+    get records(): RecordOperations;
+    /**
+     * Blob operations for uploading and retrieving binary data.
+     *
+     * Blobs are used for images, files, and other binary content associated
+     * with records.
+     *
+     * @returns {@link BlobOperations} interface for blob management
+     *
+     * @example
+     * ```typescript
+     * // Upload an image
+     * const imageBlob = new Blob([imageData], { type: "image/png" });
+     * const uploadResult = await repo.blobs.upload(imageBlob);
+     *
+     * // The ref can be used in records
+     * console.log(uploadResult.ref.$link);  // CID of the blob
+     *
+     * // Retrieve a blob by CID
+     * const { data, mimeType } = await repo.blobs.get(cid);
+     * ```
+     */
+    get blobs(): BlobOperations;
+    /**
+     * Profile operations for managing user profiles.
+     *
+     * @returns {@link ProfileOperations} interface for profile management
+     *
+     * @example
+     * ```typescript
+     * // Get current profile
+     * const profile = await repo.profile.get();
+     * console.log(profile.displayName);
+     *
+     * // Update profile
+     * await repo.profile.update({
+     *   displayName: "New Name",
+     *   description: "Updated bio",
+     *   avatar: avatarBlob,  // Optional: update avatar image
+     * });
+     * ```
+     */
+    get profile(): ProfileOperations;
+    /**
+     * High-level hypercert operations.
+     *
+     * Provides a convenient API for creating and managing hypercerts,
+     * including related records like locations, contributions, and evidence.
+     *
+     * @returns {@link HypercertOperations} interface with EventEmitter capabilities
+     *
+     * @example Creating a hypercert
+     * ```typescript
+     * const result = await repo.hypercerts.create({
+     *   title: "Climate Action Project",
+     *   description: "Reduced carbon emissions by 1000 tons",
+     *   workScope: "Climate Action",
+     *   workTimeframeFrom: "2024-01-01",
+     *   workTimeframeTo: "2024-06-30",
+     *   rights: {
+     *     name: "Public Domain",
+     *     type: "license",
+     *     description: "CC0 - No Rights Reserved",
+     *   },
+     *   image: imageBlob,  // Optional cover image
+     *   location: {
+     *     value: "San Francisco, CA",
+     *     name: "SF Bay Area",
+     *   },
+     * });
+     * console.log(`Created: ${result.hypercertUri}`);
+     * ```
+     *
+     * @example Listening to events
+     * ```typescript
+     * repo.hypercerts.on("recordCreated", ({ uri, cid }) => {
+     *   console.log(`Record created: ${uri}`);
+     * });
+     * ```
+     */
+    get hypercerts(): HypercertOperations;
+    /**
+     * Collaborator operations for managing repository access.
+     *
+     * **SDS Only**: This property throws {@link SDSRequiredError} if accessed
+     * on a PDS repository.
+     *
+     * @returns {@link CollaboratorOperations} interface for access control
+     * @throws {@link SDSRequiredError} if not connected to an SDS server
+     *
+     * @example
+     * ```typescript
+     * // Ensure we're on SDS
+     * const sdsRepo = sdk.repository(session, { server: "sds" });
+     *
+     * // Grant editor access
+     * await sdsRepo.collaborators.grant({
+     *   userDid: "did:plc:new-collaborator",
+     *   role: "editor",
+     * });
+     *
+     * // List all collaborators
+     * const collaborators = await sdsRepo.collaborators.list();
+     *
+     * // Check access
+     * const hasAccess = await sdsRepo.collaborators.hasAccess("did:plc:someone");
+     *
+     * // Revoke access
+     * await sdsRepo.collaborators.revoke({ userDid: "did:plc:former-collaborator" });
+     * ```
+     */
+    get collaborators(): CollaboratorOperations;
+    /**
+     * Organization operations for creating and managing organizations.
+     *
+     * **SDS Only**: This property throws {@link SDSRequiredError} if accessed
+     * on a PDS repository.
+     *
+     * @returns {@link OrganizationOperations} interface for organization management
+     * @throws {@link SDSRequiredError} if not connected to an SDS server
+     *
+     * @example
+     * ```typescript
+     * // Ensure we're on SDS
+     * const sdsRepo = sdk.repository(session, { server: "sds" });
+     *
+     * // Create an organization
+     * const org = await sdsRepo.organizations.create({
+     *   name: "My Organization",
+     *   description: "A team working on impact certificates",
+     *   handle: "my-org",  // Optional custom handle
+     * });
+     *
+     * // List organizations you have access to
+     * const orgs = await sdsRepo.organizations.list();
+     *
+     * // Get specific organization
+     * const orgInfo = await sdsRepo.organizations.get(org.did);
+     * ```
+     */
+    get organizations(): OrganizationOperations;
+}
+
+/**
+ * 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;
+}>;
+/**
+ * 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.
+ */
+declare const ATProtoSDKConfigSchema: z.ZodObject<{
+    oauth: 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;
+    }>;
+    servers: z.ZodOptional<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;
+    }>>;
+    timeouts: z.ZodOptional<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;
+    }>>;
+}, "strip", z.ZodTypeAny, {
+    oauth: {
+        clientId: string;
+        redirectUri: string;
+        scope: string;
+        jwksUri: string;
+        jwkPrivate: string;
+    };
+    servers?: {
+        pds?: string | undefined;
+        sds?: string | undefined;
+    } | undefined;
+    timeouts?: {
+        pdsMetadata?: number | undefined;
+        apiRequests?: number | undefined;
+    } | undefined;
+}, {
+    oauth: {
+        clientId: string;
+        redirectUri: string;
+        scope: string;
+        jwksUri: string;
+        jwkPrivate: string;
+    };
+    servers?: {
+        pds?: string | undefined;
+        sds?: string | undefined;
+    } | undefined;
+    timeouts?: {
+        pdsMetadata?: number | undefined;
+        apiRequests?: number | undefined;
+    } | 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;
+}
+
+/**
+ * Options for the OAuth authorization flow.
+ */
+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
+ */
+declare class ATProtoSDK {
+    private oauthClient;
+    private config;
+    private logger?;
+    private 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);
+    /**
+     * 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;
+     * ```
+     */
+    authorize(identifier: string, options?: AuthorizeOptions): Promise<string>;
+    /**
+     * 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);
+     * ```
+     */
+    callback(params: URLSearchParams): Promise<Session>;
+    /**
+     * 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);
+     *   }
+     * }
+     * ```
+     */
+    restoreSession(did: string): Promise<Session | null>;
+    /**
+     * 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");
+     * ```
+     */
+    revokeSession(did: string): Promise<void>;
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * The configured PDS (Personal Data Server) URL.
+     *
+     * @returns The PDS URL if configured, otherwise `undefined`
+     */
+    get pdsUrl(): string | undefined;
+    /**
+     * The configured SDS (Shared Data Server) URL.
+     *
+     * @returns The SDS URL if configured, otherwise `undefined`
+     */
+    get sdsUrl(): string | undefined;
+}
+/**
+ * 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" },
+ * });
+ * ```
+ */
+declare function createATProtoSDK(config: ATProtoSDKConfig): ATProtoSDK;
+
+/**
+ * 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;
+ *     }
+ *   }
+ * }
+ * ```
+ */
+declare class ATProtoSDKError extends Error {
+    code: string;
+    status?: number | undefined;
+    cause?: unknown | undefined;
+    /**
+     * 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, code: string, status?: number | undefined, cause?: unknown | undefined);
+}
+/**
+ * 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);
+ *   }
+ * }
+ * ```
+ */
+declare 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);
+}
+/**
+ * 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";
+ *   }
+ * }
+ * ```
+ */
+declare 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, cause?: unknown);
+}
+/**
+ * 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}`);
+ *     });
+ *   }
+ * }
+ * ```
+ */
+declare 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);
+}
+/**
+ * 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));
+ *   }
+ * }
+ * ```
+ */
+declare 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);
+}
+/**
+ * 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();
+ *   }
+ * }
+ * ```
+ */
+declare 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, cause?: unknown);
+}
+
+/**
+ * In-memory implementation of the SessionStore interface.
+ *
+ * This store keeps OAuth sessions in memory using a Map. It's intended
+ * for development, testing, and simple use cases where session persistence
+ * across restarts is not required.
+ *
+ * @remarks
+ * **Warning**: This implementation is **not suitable for production** because:
+ * - Sessions are lost when the process restarts
+ * - Sessions cannot be shared across multiple server instances
+ * - No automatic cleanup of expired sessions
+ *
+ * For production, implement {@link SessionStore} with a persistent backend:
+ * - **Redis**: Good for distributed systems, supports TTL
+ * - **PostgreSQL/MySQL**: Good for existing database infrastructure
+ * - **MongoDB**: Good for document-based storage
+ *
+ * @example Basic usage
+ * ```typescript
+ * import { InMemorySessionStore } from "@hypercerts-org/sdk/storage";
+ *
+ * const sessionStore = new InMemorySessionStore();
+ *
+ * const sdk = new ATProtoSDK({
+ *   oauth: { ... },
+ *   storage: {
+ *     sessionStore,  // Will warn in logs for production
+ *   },
+ * });
+ * ```
+ *
+ * @example Testing usage
+ * ```typescript
+ * const sessionStore = new InMemorySessionStore();
+ *
+ * // After tests, clean up
+ * sessionStore.clear();
+ * ```
+ *
+ * @see {@link SessionStore} for the interface definition
+ * @see {@link InMemoryStateStore} for the corresponding state store
+ */
+declare class InMemorySessionStore implements SessionStore {
+    /**
+     * Internal storage for sessions, keyed by DID.
+     * @internal
+     */
+    private sessions;
+    /**
+     * Retrieves a session by DID.
+     *
+     * @param did - The user's Decentralized Identifier
+     * @returns Promise resolving to the session, or `undefined` if not found
+     *
+     * @example
+     * ```typescript
+     * const session = await sessionStore.get("did:plc:abc123");
+     * if (session) {
+     *   console.log("Session found");
+     * }
+     * ```
+     */
+    get(did: string): Promise<NodeSavedSession | undefined>;
+    /**
+     * Stores or updates a session.
+     *
+     * @param did - The user's DID to use as the key
+     * @param session - The session data to store
+     *
+     * @remarks
+     * If a session already exists for the DID, it is overwritten.
+     *
+     * @example
+     * ```typescript
+     * await sessionStore.set("did:plc:abc123", sessionData);
+     * ```
+     */
+    set(did: string, session: NodeSavedSession): Promise<void>;
+    /**
+     * Deletes a session by DID.
+     *
+     * @param did - The DID of the session to delete
+     *
+     * @remarks
+     * If no session exists for the DID, this is a no-op.
+     *
+     * @example
+     * ```typescript
+     * await sessionStore.del("did:plc:abc123");
+     * ```
+     */
+    del(did: string): Promise<void>;
+    /**
+     * Clears all stored sessions.
+     *
+     * This is primarily useful for testing to ensure a clean state
+     * between test runs.
+     *
+     * @remarks
+     * This method is synchronous (not async) for convenience in test cleanup.
+     *
+     * @example
+     * ```typescript
+     * // In test teardown
+     * afterEach(() => {
+     *   sessionStore.clear();
+     * });
+     * ```
+     */
+    clear(): void;
+}
+
+/**
+ * In-memory implementation of the StateStore interface.
+ *
+ * This store keeps OAuth state parameters in memory using a Map. State is
+ * used during the OAuth authorization flow for CSRF protection and PKCE.
+ *
+ * @remarks
+ * **Warning**: This implementation is **not suitable for production** because:
+ * - State is lost when the process restarts (breaking in-progress OAuth flows)
+ * - State cannot be shared across multiple server instances
+ * - No automatic cleanup of expired state (memory leak potential)
+ *
+ * For production, implement {@link StateStore} with a persistent backend
+ * that supports TTL (time-to-live):
+ * - **Redis**: Ideal choice with built-in TTL support
+ * - **Database with cleanup job**: PostgreSQL/MySQL with periodic cleanup
+ *
+ * **State Lifecycle**:
+ * 1. Created when user starts OAuth flow (`authorize()`)
+ * 2. Retrieved and validated during callback
+ * 3. Deleted after successful or failed callback
+ * 4. Should expire after ~15 minutes if callback never happens
+ *
+ * @example Basic usage
+ * ```typescript
+ * import { InMemoryStateStore } from "@hypercerts-org/sdk/storage";
+ *
+ * const stateStore = new InMemoryStateStore();
+ *
+ * const sdk = new ATProtoSDK({
+ *   oauth: { ... },
+ *   storage: {
+ *     stateStore,  // Will warn in logs for production
+ *   },
+ * });
+ * ```
+ *
+ * @example Testing usage
+ * ```typescript
+ * const stateStore = new InMemoryStateStore();
+ *
+ * // After tests, clean up
+ * stateStore.clear();
+ * ```
+ *
+ * @see {@link StateStore} for the interface definition
+ * @see {@link InMemorySessionStore} for the corresponding session store
+ */
+declare class InMemoryStateStore implements StateStore {
+    /**
+     * Internal storage for OAuth state, keyed by state string.
+     * @internal
+     */
+    private states;
+    /**
+     * Retrieves OAuth state by key.
+     *
+     * @param key - The state key (random string from authorization URL)
+     * @returns Promise resolving to the state, or `undefined` if not found
+     *
+     * @remarks
+     * The key is a cryptographically random string generated during
+     * the authorization request. It's included in the callback URL
+     * and used to retrieve the associated PKCE verifier and other data.
+     *
+     * @example
+     * ```typescript
+     * // During OAuth callback
+     * const state = await stateStore.get(params.get("state")!);
+     * if (!state) {
+     *   throw new Error("Invalid or expired state");
+     * }
+     * ```
+     */
+    get(key: string): Promise<NodeSavedState | undefined>;
+    /**
+     * Stores OAuth state temporarily.
+     *
+     * @param key - The state key to use for storage
+     * @param state - The OAuth state data (includes PKCE verifier, etc.)
+     *
+     * @remarks
+     * In production implementations, state should be stored with a TTL
+     * of approximately 10-15 minutes to prevent stale state accumulation.
+     *
+     * @example
+     * ```typescript
+     * // Called internally by OAuthClient during authorize()
+     * await stateStore.set(stateKey, {
+     *   // PKCE code verifier, redirect URI, etc.
+     * });
+     * ```
+     */
+    set(key: string, state: NodeSavedState): Promise<void>;
+    /**
+     * Deletes OAuth state by key.
+     *
+     * @param key - The state key to delete
+     *
+     * @remarks
+     * Called after the OAuth callback is processed (whether successful or not)
+     * to clean up the temporary state.
+     *
+     * @example
+     * ```typescript
+     * // After processing callback
+     * await stateStore.del(stateKey);
+     * ```
+     */
+    del(key: string): Promise<void>;
+    /**
+     * Clears all stored state.
+     *
+     * This is primarily useful for testing to ensure a clean state
+     * between test runs.
+     *
+     * @remarks
+     * This method is synchronous (not async) for convenience in test cleanup.
+     * In production, be careful using this as it will invalidate all
+     * in-progress OAuth flows.
+     *
+     * @example
+     * ```typescript
+     * // In test teardown
+     * afterEach(() => {
+     *   stateStore.clear();
+     * });
+     * ```
+     */
+    clear(): void;
+}
+
+export { ATProtoSDK, ATProtoSDKConfigSchema, ATProtoSDKError, AuthenticationError, CollaboratorPermissionsSchema, CollaboratorSchema, InMemorySessionStore, InMemoryStateStore, LexiconRegistry, NetworkError, OAuthConfigSchema, OrganizationSchema, Repository, SDSRequiredError, ServerConfigSchema, SessionExpiredError, TimeoutConfigSchema, ValidationError, createATProtoSDK };
+export type { ATProtoSDKConfig, AuthorizeOptions, BlobOperations, BlobRef, CacheInterface, Collaborator, CollaboratorOperations, CollaboratorPermissions, CreateHypercertParams, CreateHypercertResult, CreateResult, DID, HypercertClaim, HypercertCollection, HypercertCollectionClaimItem, HypercertContribution, HypercertEvaluation, HypercertEvents, HypercertEvidence, HypercertImage, HypercertLocation, HypercertMeasurement, HypercertOperations, HypercertRights, HypercertWithMetadata, ListParams, LoggerInterface, Organization, OrganizationInfo, OrganizationOperations, PaginatedList, ProfileOperations, ProgressStep, RecordOperations, RepositoryAccessGrant, RepositoryOptions, RepositoryRole, Session, SessionStore, StateStore, StrongRef, UpdateResult, ValidationResult };