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

package/dist/types.d.ts

@@ -0,0 +1,2118 @@
+import { OAuthSession, NodeSavedSession, NodeSavedState } from '@atproto/oauth-client-node';
+import { z } from 'zod';
+import { EventEmitter } from 'eventemitter3';
+import { OrgHypercertsClaim, OrgHypercertsCollection, OrgHypercertsClaimRights, AppCertifiedLocation, OrgHypercertsClaimContribution, OrgHypercertsClaimMeasurement, OrgHypercertsClaimEvaluation } from '@hypercerts-org/lexicon';
+
+/**
+ * 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>;
+
+/**
+ * Storage interface for persisting OAuth sessions.
+ *
+ * Implement this interface to provide persistent storage for user sessions.
+ * Sessions contain sensitive data including access tokens, refresh tokens,
+ * and DPoP key pairs.
+ *
+ * The SDK provides {@link InMemorySessionStore} for development/testing,
+ * but **production applications should implement persistent storage**
+ * (e.g., Redis, PostgreSQL, MongoDB).
+ *
+ * @remarks
+ * - Sessions are keyed by the user's DID (Decentralized Identifier)
+ * - The `NodeSavedSession` type comes from `@atproto/oauth-client-node`
+ * - Sessions may be large (~2-4KB) due to embedded cryptographic keys
+ * - Consider encrypting sessions at rest for additional security
+ *
+ * @example Redis implementation
+ * ```typescript
+ * import { Redis } from "ioredis";
+ * import type { SessionStore } from "@hypercerts-org/sdk";
+ * import type { NodeSavedSession } from "@atproto/oauth-client-node";
+ *
+ * class RedisSessionStore implements SessionStore {
+ *   constructor(private redis: Redis, private prefix = "session:") {}
+ *
+ *   async get(did: string): Promise<NodeSavedSession | undefined> {
+ *     const data = await this.redis.get(this.prefix + did);
+ *     return data ? JSON.parse(data) : undefined;
+ *   }
+ *
+ *   async set(did: string, session: NodeSavedSession): Promise<void> {
+ *     // Set with 30-day expiry (sessions can be refreshed)
+ *     await this.redis.setex(
+ *       this.prefix + did,
+ *       30 * 24 * 60 * 60,
+ *       JSON.stringify(session)
+ *     );
+ *   }
+ *
+ *   async del(did: string): Promise<void> {
+ *     await this.redis.del(this.prefix + did);
+ *   }
+ * }
+ * ```
+ *
+ * @see {@link InMemorySessionStore} for the default in-memory implementation
+ */
+interface SessionStore {
+    /**
+     * Retrieves a session by DID.
+     *
+     * @param did - The user's Decentralized Identifier (e.g., "did:plc:abc123...")
+     * @returns The stored session, or `undefined` if not found
+     */
+    get(did: string): Promise<NodeSavedSession | undefined>;
+    /**
+     * Stores or updates a session.
+     *
+     * This is called after successful authentication and whenever tokens are refreshed.
+     *
+     * @param did - The user's DID to use as the storage key
+     * @param session - The session data to store (contains tokens, DPoP keys, etc.)
+     */
+    set(did: string, session: NodeSavedSession): Promise<void>;
+    /**
+     * Deletes a session.
+     *
+     * Called when a user logs out or when a session is revoked.
+     *
+     * @param did - The user's DID
+     */
+    del(did: string): Promise<void>;
+}
+/**
+ * Storage interface for OAuth state during the authorization flow.
+ *
+ * Implement this interface to provide temporary storage for OAuth state
+ * parameters. State is used for CSRF protection and PKCE (Proof Key for
+ * Code Exchange) during the authorization flow.
+ *
+ * @remarks
+ * - State is short-lived (typically 10-15 minutes)
+ * - Keys are random state strings generated by the OAuth client
+ * - The `NodeSavedState` type comes from `@atproto/oauth-client-node`
+ * - State should be automatically cleaned up after expiry
+ *
+ * @example Redis implementation with automatic expiry
+ * ```typescript
+ * import { Redis } from "ioredis";
+ * import type { StateStore } from "@hypercerts-org/sdk";
+ * import type { NodeSavedState } from "@atproto/oauth-client-node";
+ *
+ * class RedisStateStore implements StateStore {
+ *   constructor(
+ *     private redis: Redis,
+ *     private prefix = "oauth-state:",
+ *     private ttlSeconds = 900  // 15 minutes
+ *   ) {}
+ *
+ *   async get(key: string): Promise<NodeSavedState | undefined> {
+ *     const data = await this.redis.get(this.prefix + key);
+ *     return data ? JSON.parse(data) : undefined;
+ *   }
+ *
+ *   async set(key: string, state: NodeSavedState): Promise<void> {
+ *     await this.redis.setex(
+ *       this.prefix + key,
+ *       this.ttlSeconds,
+ *       JSON.stringify(state)
+ *     );
+ *   }
+ *
+ *   async del(key: string): Promise<void> {
+ *     await this.redis.del(this.prefix + key);
+ *   }
+ * }
+ * ```
+ *
+ * @see {@link InMemoryStateStore} for the default in-memory implementation
+ */
+interface StateStore {
+    /**
+     * Retrieves OAuth state by key.
+     *
+     * @param key - The state key (random string from authorization URL)
+     * @returns The stored state, or `undefined` if not found or expired
+     */
+    get(key: string): Promise<NodeSavedState | undefined>;
+    /**
+     * Stores OAuth state temporarily.
+     *
+     * Called when starting the authorization flow. The state should be
+     * stored with a short TTL (10-15 minutes recommended).
+     *
+     * @param key - The state key to use for storage
+     * @param state - The OAuth state data (includes PKCE verifier, etc.)
+     */
+    set(key: string, state: NodeSavedState): Promise<void>;
+    /**
+     * Deletes OAuth state.
+     *
+     * Called after the state has been used (successful or failed callback).
+     *
+     * @param key - The state key to delete
+     */
+    del(key: string): Promise<void>;
+}
+/**
+ * Generic cache interface for profiles, metadata, and other data.
+ *
+ * Implement this interface to provide caching for frequently accessed data.
+ * Caching can significantly reduce API calls and improve performance.
+ *
+ * @remarks
+ * The SDK does not provide a default cache implementation - you must
+ * implement this interface if you want caching. Consider using:
+ * - In-memory cache (e.g., `lru-cache`) for single-instance applications
+ * - Redis for distributed applications
+ * - Database-backed cache for persistence
+ *
+ * @example LRU cache implementation
+ * ```typescript
+ * import { LRUCache } from "lru-cache";
+ * import type { CacheInterface } from "@hypercerts-org/sdk";
+ *
+ * class LRUCacheAdapter implements CacheInterface {
+ *   private cache = new LRUCache<string, unknown>({
+ *     max: 1000,
+ *     ttl: 5 * 60 * 1000,  // 5 minutes default
+ *   });
+ *
+ *   async get<T>(key: string): Promise<T | undefined> {
+ *     return this.cache.get(key) as T | undefined;
+ *   }
+ *
+ *   async set<T>(key: string, value: T, ttlSeconds?: number): Promise<void> {
+ *     this.cache.set(key, value, {
+ *       ttl: ttlSeconds ? ttlSeconds * 1000 : undefined,
+ *     });
+ *   }
+ *
+ *   async del(key: string): Promise<void> {
+ *     this.cache.delete(key);
+ *   }
+ *
+ *   async clear(): Promise<void> {
+ *     this.cache.clear();
+ *   }
+ * }
+ * ```
+ */
+interface CacheInterface {
+    /**
+     * Gets a cached value by key.
+     *
+     * @typeParam T - The expected type of the cached value
+     * @param key - The cache key
+     * @returns The cached value, or `undefined` if not found or expired
+     */
+    get<T>(key: string): Promise<T | undefined>;
+    /**
+     * Sets a cached value with optional TTL (time-to-live).
+     *
+     * @typeParam T - The type of the value being cached
+     * @param key - The cache key
+     * @param value - The value to cache
+     * @param ttlSeconds - Optional time-to-live in seconds. If not provided,
+     *                     the cache implementation should use its default TTL.
+     */
+    set<T>(key: string, value: T, ttlSeconds?: number): Promise<void>;
+    /**
+     * Deletes a cached value.
+     *
+     * @param key - The cache key to delete
+     */
+    del(key: string): Promise<void>;
+    /**
+     * Clears all cached values.
+     *
+     * Use with caution in production as this affects all cached data.
+     */
+    clear(): Promise<void>;
+}
+/**
+ * Logger interface for debugging and observability.
+ *
+ * Implement this interface to receive log messages from the SDK.
+ * The interface is compatible with `console` and most popular
+ * logging libraries (Pino, Winston, Bunyan, etc.).
+ *
+ * @remarks
+ * Log levels follow standard conventions:
+ * - `debug`: Detailed information for debugging (tokens, request details)
+ * - `info`: General operational messages (initialization, successful auth)
+ * - `warn`: Potentially problematic situations (deprecated features, retries)
+ * - `error`: Errors that don't crash the application (failed requests, validation)
+ *
+ * @example Using console
+ * ```typescript
+ * const sdk = new ATProtoSDK({
+ *   // ...
+ *   logger: console,
+ * });
+ * ```
+ *
+ * @example Using Pino
+ * ```typescript
+ * import pino from "pino";
+ *
+ * const logger = pino({ level: "debug" });
+ * const sdk = new ATProtoSDK({
+ *   // ...
+ *   logger: logger,
+ * });
+ * ```
+ *
+ * @example Custom logger with context
+ * ```typescript
+ * const logger: LoggerInterface = {
+ *   debug: (msg, ...args) => console.debug(`[SDK] ${msg}`, ...args),
+ *   info: (msg, ...args) => console.info(`[SDK] ${msg}`, ...args),
+ *   warn: (msg, ...args) => console.warn(`[SDK] ${msg}`, ...args),
+ *   error: (msg, ...args) => console.error(`[SDK] ${msg}`, ...args),
+ * };
+ * ```
+ */
+interface LoggerInterface {
+    /**
+     * Logs debug-level messages.
+     *
+     * Used for detailed diagnostic information. May include sensitive
+     * data like request URLs and headers (but not tokens).
+     *
+     * @param message - The log message
+     * @param args - Additional arguments (objects, error details, etc.)
+     */
+    debug(message: string, ...args: unknown[]): void;
+    /**
+     * Logs info-level messages.
+     *
+     * Used for general operational information like successful
+     * initialization, authentication events, etc.
+     *
+     * @param message - The log message
+     * @param args - Additional arguments
+     */
+    info(message: string, ...args: unknown[]): void;
+    /**
+     * Logs warning-level messages.
+     *
+     * Used for potentially problematic situations that don't prevent
+     * operation but may indicate issues.
+     *
+     * @param message - The log message
+     * @param args - Additional arguments
+     */
+    warn(message: string, ...args: unknown[]): void;
+    /**
+     * Logs error-level messages.
+     *
+     * Used for error conditions that should be investigated.
+     * The SDK continues to operate after logging errors.
+     *
+     * @param message - The log message
+     * @param args - Additional arguments (typically includes the error object)
+     */
+    error(message: string, ...args: unknown[]): void;
+}
+
+/**
+ * Zod schema for OAuth configuration validation.
+ *
+ * @remarks
+ * All URLs must be valid and use HTTPS in production. The `jwkPrivate` field
+ * should contain the private key in JWK (JSON Web Key) format as a string.
+ */
+declare const OAuthConfigSchema: z.ZodObject<{
+    /**
+     * URL to the OAuth client metadata JSON document.
+     * This document describes your application to the authorization server.
+     *
+     * @see https://atproto.com/specs/oauth#client-metadata
+     */
+    clientId: z.ZodString;
+    /**
+     * URL where users are redirected after authentication.
+     * Must match one of the redirect URIs in your client metadata.
+     */
+    redirectUri: z.ZodString;
+    /**
+     * OAuth scopes to request, space-separated.
+     * Common scopes: "atproto", "transition:generic"
+     */
+    scope: z.ZodString;
+    /**
+     * URL to your public JWKS (JSON Web Key Set) endpoint.
+     * Used by the authorization server to verify your client's signatures.
+     */
+    jwksUri: z.ZodString;
+    /**
+     * Private JWK (JSON Web Key) as a JSON string.
+     * Used for signing DPoP proofs and client assertions.
+     *
+     * @remarks
+     * This should be kept secret and never exposed to clients.
+     * Typically loaded from environment variables or a secrets manager.
+     */
+    jwkPrivate: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    clientId: string;
+    redirectUri: string;
+    scope: string;
+    jwksUri: string;
+    jwkPrivate: string;
+}, {
+    clientId: string;
+    redirectUri: string;
+    scope: string;
+    jwksUri: string;
+    jwkPrivate: string;
+}>;
+/**
+ * Zod schema for server URL configuration.
+ *
+ * @remarks
+ * At least one server (PDS or SDS) should be configured for the SDK to be useful.
+ */
+declare const ServerConfigSchema: z.ZodObject<{
+    /**
+     * Personal Data Server URL - the user's own AT Protocol server.
+     * This is the primary server for user data operations.
+     *
+     * @example "https://bsky.social"
+     */
+    pds: z.ZodOptional<z.ZodString>;
+    /**
+     * Shared Data Server URL - for collaborative data storage.
+     * Required for collaborator and organization operations.
+     *
+     * @example "https://sds.hypercerts.org"
+     */
+    sds: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    pds?: string | undefined;
+    sds?: string | undefined;
+}, {
+    pds?: string | undefined;
+    sds?: string | undefined;
+}>;
+/**
+ * Zod schema for timeout configuration.
+ *
+ * @remarks
+ * All timeout values are in milliseconds.
+ */
+declare const TimeoutConfigSchema: z.ZodObject<{
+    /**
+     * Timeout for fetching PDS metadata during identity resolution.
+     * @default 5000 (5 seconds, set by OAuthClient)
+     */
+    pdsMetadata: z.ZodOptional<z.ZodNumber>;
+    /**
+     * Timeout for general API requests to PDS/SDS.
+     * @default 30000 (30 seconds)
+     */
+    apiRequests: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    pdsMetadata?: number | undefined;
+    apiRequests?: number | undefined;
+}, {
+    pdsMetadata?: number | undefined;
+    apiRequests?: number | undefined;
+}>;
+/**
+ * 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;
+}
+
+/**
+ * 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;
+}
+
+/**
+ * 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 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[]>;
+}
+
+/**
+ * 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;
+}
+
+export { ATProtoSDKConfigSchema, CollaboratorPermissionsSchema, CollaboratorSchema, OAuthConfigSchema, OrganizationSchema, ServerConfigSchema, TimeoutConfigSchema };
+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, UpdateResult, ValidationResult };