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

package/dist/testing.mjs

@@ -0,0 +1,410 @@
+/**
+ * Mock factories for testing.
+ *
+ * This module provides factory functions to create mock objects
+ * for testing SDK functionality without real AT Protocol connections.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Creates a mock OAuth session for testing.
+ *
+ * The mock session includes all required properties and a mock
+ * `fetchHandler` that returns empty successful responses by default.
+ *
+ * @param overrides - Partial session object to override default values
+ * @returns A mock Session object suitable for testing
+ *
+ * @remarks
+ * The mock session is cast to `Session` type for compatibility.
+ * In real usage, sessions come from the OAuth flow and contain
+ * actual tokens and a real fetch handler.
+ *
+ * **Default Values**:
+ * - `did`: `"did:plc:test123"`
+ * - `handle`: `"test.bsky.social"`
+ * - `fetchHandler`: Returns `Response` with `{}` body
+ *
+ * @example Basic mock session
+ * ```typescript
+ * import { createMockSession } from "@hypercerts-org/sdk/testing";
+ *
+ * const session = createMockSession();
+ * const repo = sdk.repository(session);
+ * ```
+ *
+ * @example With custom DID
+ * ```typescript
+ * const session = createMockSession({
+ *   did: "did:plc:custom-test-user",
+ *   handle: "custom.bsky.social",
+ * });
+ * ```
+ *
+ * @example With custom fetch handler
+ * ```typescript
+ * const session = createMockSession({
+ *   fetchHandler: async (url, init) => {
+ *     // Custom response logic
+ *     return new Response(JSON.stringify({ success: true }));
+ *   },
+ * });
+ * ```
+ */
+function createMockSession(overrides = {}) {
+    const mockSession = {
+        did: "did:plc:test123",
+        sub: "did:plc:test123",
+        handle: "test.bsky.social",
+        accessJwt: "mock-access-jwt",
+        refreshJwt: "mock-refresh-jwt",
+        active: true,
+        fetchHandler: async (_input, _init) => {
+            return new Response(JSON.stringify({}), {
+                status: 200,
+                headers: { "Content-Type": "application/json" },
+            });
+        },
+        ...overrides,
+    };
+    return mockSession;
+}
+/**
+ * Creates a mock SDK configuration for testing.
+ *
+ * The configuration includes all required OAuth settings with
+ * placeholder values suitable for testing (not real credentials).
+ *
+ * @param overrides - Partial configuration to override default values
+ * @returns A complete ATProtoSDKConfig suitable for testing
+ *
+ * @remarks
+ * The default configuration uses example.com domains and a minimal
+ * JWK structure. This is sufficient for unit tests but won't work
+ * for integration tests that require real OAuth flows.
+ *
+ * **Default Values**:
+ * - `clientId`: `"https://test.example.com/client-metadata.json"`
+ * - `pds`: `"https://bsky.social"`
+ * - `sds`: `"https://sds.example.com"`
+ *
+ * @example Basic test config
+ * ```typescript
+ * import { createTestConfig } from "@hypercerts-org/sdk/testing";
+ *
+ * const config = createTestConfig();
+ * const sdk = new ATProtoSDK(config);
+ * ```
+ *
+ * @example With custom PDS
+ * ```typescript
+ * const config = createTestConfig({
+ *   servers: {
+ *     pds: "https://custom-pds.example.com",
+ *   },
+ * });
+ * ```
+ *
+ * @example With logger for debugging tests
+ * ```typescript
+ * const config = createTestConfig({
+ *   logger: console,
+ * });
+ * ```
+ */
+function createTestConfig(overrides = {}) {
+    return {
+        oauth: {
+            clientId: "https://test.example.com/client-metadata.json",
+            redirectUri: "https://test.example.com/callback",
+            scope: "atproto transition:generic",
+            jwksUri: "https://test.example.com/jwks.json",
+            jwkPrivate: JSON.stringify({
+                kty: "EC",
+                crv: "P-256",
+                x: "test",
+                y: "test",
+                d: "test",
+            }),
+        },
+        servers: {
+            pds: "https://bsky.social",
+            sds: "https://sds.example.com",
+        },
+        ...overrides,
+    };
+}
+
+/**
+ * Mock storage implementations for testing.
+ *
+ * This module provides mock implementations of SessionStore and StateStore
+ * that track all operations for verification in tests.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Mock session store that tracks all operations.
+ *
+ * This implementation stores sessions in memory and records all
+ * method calls for verification in tests.
+ *
+ * @remarks
+ * Use this in tests to:
+ * - Verify that sessions are being stored correctly
+ * - Check what DIDs have been accessed
+ * - Assert on the number and order of operations
+ * - Pre-populate sessions for testing restore flows
+ *
+ * @example Basic usage
+ * ```typescript
+ * import { MockSessionStore } from "@hypercerts-org/sdk/testing";
+ *
+ * const sessionStore = new MockSessionStore();
+ * const sdk = new ATProtoSDK({
+ *   ...config,
+ *   storage: { sessionStore },
+ * });
+ *
+ * // After some operations...
+ * expect(sessionStore.setCalls).toHaveLength(1);
+ * expect(sessionStore.getCalls).toContain("did:plc:test123");
+ * ```
+ *
+ * @example Pre-populating for tests
+ * ```typescript
+ * const sessionStore = new MockSessionStore();
+ *
+ * // Pre-populate a session
+ * await sessionStore.set("did:plc:existing", mockSessionData);
+ *
+ * // Reset tracking (keeps the data)
+ * sessionStore.getCalls = [];
+ * sessionStore.setCalls = [];
+ *
+ * // Now test restore behavior
+ * const session = await sdk.restoreSession("did:plc:existing");
+ * expect(sessionStore.getCalls).toContain("did:plc:existing");
+ * ```
+ *
+ * @example Asserting on operations
+ * ```typescript
+ * const sessionStore = new MockSessionStore();
+ *
+ * // ... perform operations ...
+ *
+ * // Verify session was stored for correct DID
+ * expect(sessionStore.setCalls[0].did).toBe("did:plc:expected");
+ *
+ * // Verify session was deleted on logout
+ * expect(sessionStore.delCalls).toContain("did:plc:logged-out");
+ * ```
+ */
+class MockSessionStore {
+    constructor() {
+        /**
+         * Internal storage for sessions.
+         * @internal
+         */
+        this.store = new Map();
+        /**
+         * Record of all `get()` calls made to this store.
+         *
+         * Each entry is the DID that was requested.
+         */
+        this.getCalls = [];
+        /**
+         * Record of all `set()` calls made to this store.
+         *
+         * Each entry contains the DID and session that was stored.
+         */
+        this.setCalls = [];
+        /**
+         * Record of all `del()` calls made to this store.
+         *
+         * Each entry is the DID that was deleted.
+         */
+        this.delCalls = [];
+    }
+    /**
+     * Retrieves a session by DID.
+     *
+     * Records the call in `getCalls`.
+     *
+     * @param did - The DID to look up
+     * @returns The stored session or undefined
+     */
+    async get(did) {
+        this.getCalls.push(did);
+        return this.store.get(did);
+    }
+    /**
+     * Stores a session.
+     *
+     * Records the call in `setCalls`.
+     *
+     * @param did - The DID to store under
+     * @param session - The session data to store
+     */
+    async set(did, session) {
+        this.setCalls.push({ did, session });
+        this.store.set(did, session);
+    }
+    /**
+     * Deletes a session.
+     *
+     * Records the call in `delCalls`.
+     *
+     * @param did - The DID to delete
+     */
+    async del(did) {
+        this.delCalls.push(did);
+        this.store.delete(did);
+    }
+    /**
+     * Resets the store to initial state.
+     *
+     * Clears all stored sessions and all recorded calls.
+     * Call this in `beforeEach` or `afterEach` to ensure test isolation.
+     *
+     * @example
+     * ```typescript
+     * beforeEach(() => {
+     *   sessionStore.reset();
+     * });
+     * ```
+     */
+    reset() {
+        this.store.clear();
+        this.getCalls = [];
+        this.setCalls = [];
+        this.delCalls = [];
+    }
+}
+/**
+ * Mock state store that tracks all operations.
+ *
+ * This implementation stores OAuth state in memory and records all
+ * method calls for verification in tests.
+ *
+ * @remarks
+ * Use this in tests to:
+ * - Verify OAuth state is being created during authorization
+ * - Check that state is retrieved during callback
+ * - Assert that state is cleaned up after use
+ * - Test error handling for missing/invalid state
+ *
+ * @example Basic usage
+ * ```typescript
+ * import { MockStateStore } from "@hypercerts-org/sdk/testing";
+ *
+ * const stateStore = new MockStateStore();
+ * const sdk = new ATProtoSDK({
+ *   ...config,
+ *   storage: { stateStore },
+ * });
+ *
+ * // After authorize()
+ * expect(stateStore.setCalls).toHaveLength(1);
+ *
+ * // After callback()
+ * expect(stateStore.getCalls).toHaveLength(1);
+ * expect(stateStore.delCalls).toHaveLength(1);
+ * ```
+ *
+ * @example Testing invalid state
+ * ```typescript
+ * const stateStore = new MockStateStore();
+ * // Don't pre-populate - state will be missing
+ *
+ * // This should fail because state doesn't exist
+ * await expect(sdk.callback(params)).rejects.toThrow();
+ *
+ * // Verify the lookup was attempted
+ * expect(stateStore.getCalls).toContain(stateKey);
+ * ```
+ */
+class MockStateStore {
+    constructor() {
+        /**
+         * Internal storage for OAuth state.
+         * @internal
+         */
+        this.store = new Map();
+        /**
+         * Record of all `get()` calls made to this store.
+         *
+         * Each entry is the state key that was requested.
+         */
+        this.getCalls = [];
+        /**
+         * Record of all `set()` calls made to this store.
+         *
+         * Each entry contains the key and state that was stored.
+         */
+        this.setCalls = [];
+        /**
+         * Record of all `del()` calls made to this store.
+         *
+         * Each entry is the state key that was deleted.
+         */
+        this.delCalls = [];
+    }
+    /**
+     * Retrieves OAuth state by key.
+     *
+     * Records the call in `getCalls`.
+     *
+     * @param key - The state key to look up
+     * @returns The stored state or undefined
+     */
+    async get(key) {
+        this.getCalls.push(key);
+        return this.store.get(key);
+    }
+    /**
+     * Stores OAuth state.
+     *
+     * Records the call in `setCalls`.
+     *
+     * @param key - The state key to store under
+     * @param state - The OAuth state data to store
+     */
+    async set(key, state) {
+        this.setCalls.push({ key, state });
+        this.store.set(key, state);
+    }
+    /**
+     * Deletes OAuth state.
+     *
+     * Records the call in `delCalls`.
+     *
+     * @param key - The state key to delete
+     */
+    async del(key) {
+        this.delCalls.push(key);
+        this.store.delete(key);
+    }
+    /**
+     * Resets the store to initial state.
+     *
+     * Clears all stored state and all recorded calls.
+     * Call this in `beforeEach` or `afterEach` to ensure test isolation.
+     *
+     * @example
+     * ```typescript
+     * beforeEach(() => {
+     *   stateStore.reset();
+     * });
+     * ```
+     */
+    reset() {
+        this.store.clear();
+        this.getCalls = [];
+        this.setCalls = [];
+        this.delCalls = [];
+    }
+}
+
+export { MockSessionStore, MockStateStore, createMockSession, createTestConfig };
+//# sourceMappingURL=testing.mjs.map

package/dist/testing.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"testing.mjs","sources":["../src/testing/mocks.ts","../src/testing/stores.ts"],"sourcesContent":["/**\n * Mock factories for testing.\n *\n * This module provides factory functions to create mock objects\n * for testing SDK functionality without real AT Protocol connections.\n *\n * @packageDocumentation\n */\n\nimport type { Session } from \"../core/types.js\";\nimport type { ATProtoSDKConfig } from \"../core/config.js\";\n\n/**\n * Creates a mock OAuth session for testing.\n *\n * The mock session includes all required properties and a mock\n * `fetchHandler` that returns empty successful responses by default.\n *\n * @param overrides - Partial session object to override default values\n * @returns A mock Session object suitable for testing\n *\n * @remarks\n * The mock session is cast to `Session` type for compatibility.\n * In real usage, sessions come from the OAuth flow and contain\n * actual tokens and a real fetch handler.\n *\n * **Default Values**:\n * - `did`: `\"did:plc:test123\"`\n * - `handle`: `\"test.bsky.social\"`\n * - `fetchHandler`: Returns `Response` with `{}` body\n *\n * @example Basic mock session\n * ```typescript\n * import { createMockSession } from \"@hypercerts-org/sdk/testing\";\n *\n * const session = createMockSession();\n * const repo = sdk.repository(session);\n * ```\n *\n * @example With custom DID\n * ```typescript\n * const session = createMockSession({\n *   did: \"did:plc:custom-test-user\",\n *   handle: \"custom.bsky.social\",\n * });\n * ```\n *\n * @example With custom fetch handler\n * ```typescript\n * const session = createMockSession({\n *   fetchHandler: async (url, init) => {\n *     // Custom response logic\n *     return new Response(JSON.stringify({ success: true }));\n *   },\n * });\n * ```\n */\nexport function createMockSession(overrides: Partial<Session> = {}): Session {\n  const mockSession = {\n    did: \"did:plc:test123\",\n    sub: \"did:plc:test123\",\n    handle: \"test.bsky.social\",\n    accessJwt: \"mock-access-jwt\",\n    refreshJwt: \"mock-refresh-jwt\",\n    active: true,\n    fetchHandler: async (_input: RequestInfo | URL, _init?: RequestInit) => {\n      return new Response(JSON.stringify({}), {\n        status: 200,\n        headers: { \"Content-Type\": \"application/json\" },\n      });\n    },\n    ...overrides,\n  } as unknown as Session;\n\n  return mockSession;\n}\n\n/**\n * Creates a mock SDK configuration for testing.\n *\n * The configuration includes all required OAuth settings with\n * placeholder values suitable for testing (not real credentials).\n *\n * @param overrides - Partial configuration to override default values\n * @returns A complete ATProtoSDKConfig suitable for testing\n *\n * @remarks\n * The default configuration uses example.com domains and a minimal\n * JWK structure. This is sufficient for unit tests but won't work\n * for integration tests that require real OAuth flows.\n *\n * **Default Values**:\n * - `clientId`: `\"https://test.example.com/client-metadata.json\"`\n * - `pds`: `\"https://bsky.social\"`\n * - `sds`: `\"https://sds.example.com\"`\n *\n * @example Basic test config\n * ```typescript\n * import { createTestConfig } from \"@hypercerts-org/sdk/testing\";\n *\n * const config = createTestConfig();\n * const sdk = new ATProtoSDK(config);\n * ```\n *\n * @example With custom PDS\n * ```typescript\n * const config = createTestConfig({\n *   servers: {\n *     pds: \"https://custom-pds.example.com\",\n *   },\n * });\n * ```\n *\n * @example With logger for debugging tests\n * ```typescript\n * const config = createTestConfig({\n *   logger: console,\n * });\n * ```\n */\nexport function createTestConfig(overrides: Partial<ATProtoSDKConfig> = {}): ATProtoSDKConfig {\n  return {\n    oauth: {\n      clientId: \"https://test.example.com/client-metadata.json\",\n      redirectUri: \"https://test.example.com/callback\",\n      scope: \"atproto transition:generic\",\n      jwksUri: \"https://test.example.com/jwks.json\",\n      jwkPrivate: JSON.stringify({\n        kty: \"EC\",\n        crv: \"P-256\",\n        x: \"test\",\n        y: \"test\",\n        d: \"test\",\n      }),\n    },\n    servers: {\n      pds: \"https://bsky.social\",\n      sds: \"https://sds.example.com\",\n    },\n    ...overrides,\n  };\n}\n","/**\n * Mock storage implementations for testing.\n *\n * This module provides mock implementations of SessionStore and StateStore\n * that track all operations for verification in tests.\n *\n * @packageDocumentation\n */\n\nimport type { SessionStore, StateStore } from \"../core/interfaces.js\";\nimport type { NodeSavedSession, NodeSavedState } from \"@atproto/oauth-client-node\";\n\n/**\n * Mock session store that tracks all operations.\n *\n * This implementation stores sessions in memory and records all\n * method calls for verification in tests.\n *\n * @remarks\n * Use this in tests to:\n * - Verify that sessions are being stored correctly\n * - Check what DIDs have been accessed\n * - Assert on the number and order of operations\n * - Pre-populate sessions for testing restore flows\n *\n * @example Basic usage\n * ```typescript\n * import { MockSessionStore } from \"@hypercerts-org/sdk/testing\";\n *\n * const sessionStore = new MockSessionStore();\n * const sdk = new ATProtoSDK({\n *   ...config,\n *   storage: { sessionStore },\n * });\n *\n * // After some operations...\n * expect(sessionStore.setCalls).toHaveLength(1);\n * expect(sessionStore.getCalls).toContain(\"did:plc:test123\");\n * ```\n *\n * @example Pre-populating for tests\n * ```typescript\n * const sessionStore = new MockSessionStore();\n *\n * // Pre-populate a session\n * await sessionStore.set(\"did:plc:existing\", mockSessionData);\n *\n * // Reset tracking (keeps the data)\n * sessionStore.getCalls = [];\n * sessionStore.setCalls = [];\n *\n * // Now test restore behavior\n * const session = await sdk.restoreSession(\"did:plc:existing\");\n * expect(sessionStore.getCalls).toContain(\"did:plc:existing\");\n * ```\n *\n * @example Asserting on operations\n * ```typescript\n * const sessionStore = new MockSessionStore();\n *\n * // ... perform operations ...\n *\n * // Verify session was stored for correct DID\n * expect(sessionStore.setCalls[0].did).toBe(\"did:plc:expected\");\n *\n * // Verify session was deleted on logout\n * expect(sessionStore.delCalls).toContain(\"did:plc:logged-out\");\n * ```\n */\nexport class MockSessionStore implements SessionStore {\n  /**\n   * Internal storage for sessions.\n   * @internal\n   */\n  private store = new Map<string, NodeSavedSession>();\n\n  /**\n   * Record of all `get()` calls made to this store.\n   *\n   * Each entry is the DID that was requested.\n   */\n  public getCalls: string[] = [];\n\n  /**\n   * Record of all `set()` calls made to this store.\n   *\n   * Each entry contains the DID and session that was stored.\n   */\n  public setCalls: Array<{ did: string; session: NodeSavedSession }> = [];\n\n  /**\n   * Record of all `del()` calls made to this store.\n   *\n   * Each entry is the DID that was deleted.\n   */\n  public delCalls: string[] = [];\n\n  /**\n   * Retrieves a session by DID.\n   *\n   * Records the call in `getCalls`.\n   *\n   * @param did - The DID to look up\n   * @returns The stored session or undefined\n   */\n  async get(did: string): Promise<NodeSavedSession | undefined> {\n    this.getCalls.push(did);\n    return this.store.get(did);\n  }\n\n  /**\n   * Stores a session.\n   *\n   * Records the call in `setCalls`.\n   *\n   * @param did - The DID to store under\n   * @param session - The session data to store\n   */\n  async set(did: string, session: NodeSavedSession): Promise<void> {\n    this.setCalls.push({ did, session });\n    this.store.set(did, session);\n  }\n\n  /**\n   * Deletes a session.\n   *\n   * Records the call in `delCalls`.\n   *\n   * @param did - The DID to delete\n   */\n  async del(did: string): Promise<void> {\n    this.delCalls.push(did);\n    this.store.delete(did);\n  }\n\n  /**\n   * Resets the store to initial state.\n   *\n   * Clears all stored sessions and all recorded calls.\n   * Call this in `beforeEach` or `afterEach` to ensure test isolation.\n   *\n   * @example\n   * ```typescript\n   * beforeEach(() => {\n   *   sessionStore.reset();\n   * });\n   * ```\n   */\n  reset(): void {\n    this.store.clear();\n    this.getCalls = [];\n    this.setCalls = [];\n    this.delCalls = [];\n  }\n}\n\n/**\n * Mock state store that tracks all operations.\n *\n * This implementation stores OAuth state in memory and records all\n * method calls for verification in tests.\n *\n * @remarks\n * Use this in tests to:\n * - Verify OAuth state is being created during authorization\n * - Check that state is retrieved during callback\n * - Assert that state is cleaned up after use\n * - Test error handling for missing/invalid state\n *\n * @example Basic usage\n * ```typescript\n * import { MockStateStore } from \"@hypercerts-org/sdk/testing\";\n *\n * const stateStore = new MockStateStore();\n * const sdk = new ATProtoSDK({\n *   ...config,\n *   storage: { stateStore },\n * });\n *\n * // After authorize()\n * expect(stateStore.setCalls).toHaveLength(1);\n *\n * // After callback()\n * expect(stateStore.getCalls).toHaveLength(1);\n * expect(stateStore.delCalls).toHaveLength(1);\n * ```\n *\n * @example Testing invalid state\n * ```typescript\n * const stateStore = new MockStateStore();\n * // Don't pre-populate - state will be missing\n *\n * // This should fail because state doesn't exist\n * await expect(sdk.callback(params)).rejects.toThrow();\n *\n * // Verify the lookup was attempted\n * expect(stateStore.getCalls).toContain(stateKey);\n * ```\n */\nexport class MockStateStore implements StateStore {\n  /**\n   * Internal storage for OAuth state.\n   * @internal\n   */\n  private store = new Map<string, NodeSavedState>();\n\n  /**\n   * Record of all `get()` calls made to this store.\n   *\n   * Each entry is the state key that was requested.\n   */\n  public getCalls: string[] = [];\n\n  /**\n   * Record of all `set()` calls made to this store.\n   *\n   * Each entry contains the key and state that was stored.\n   */\n  public setCalls: Array<{ key: string; state: NodeSavedState }> = [];\n\n  /**\n   * Record of all `del()` calls made to this store.\n   *\n   * Each entry is the state key that was deleted.\n   */\n  public delCalls: string[] = [];\n\n  /**\n   * Retrieves OAuth state by key.\n   *\n   * Records the call in `getCalls`.\n   *\n   * @param key - The state key to look up\n   * @returns The stored state or undefined\n   */\n  async get(key: string): Promise<NodeSavedState | undefined> {\n    this.getCalls.push(key);\n    return this.store.get(key);\n  }\n\n  /**\n   * Stores OAuth state.\n   *\n   * Records the call in `setCalls`.\n   *\n   * @param key - The state key to store under\n   * @param state - The OAuth state data to store\n   */\n  async set(key: string, state: NodeSavedState): Promise<void> {\n    this.setCalls.push({ key, state });\n    this.store.set(key, state);\n  }\n\n  /**\n   * Deletes OAuth state.\n   *\n   * Records the call in `delCalls`.\n   *\n   * @param key - The state key to delete\n   */\n  async del(key: string): Promise<void> {\n    this.delCalls.push(key);\n    this.store.delete(key);\n  }\n\n  /**\n   * Resets the store to initial state.\n   *\n   * Clears all stored state and all recorded calls.\n   * Call this in `beforeEach` or `afterEach` to ensure test isolation.\n   *\n   * @example\n   * ```typescript\n   * beforeEach(() => {\n   *   stateStore.reset();\n   * });\n   * ```\n   */\n  reset(): void {\n    this.store.clear();\n    this.getCalls = [];\n    this.setCalls = [];\n    this.delCalls = [];\n  }\n}\n"],"names":[],"mappings":"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"}

package/dist/types.cjs

@@ -0,0 +1,220 @@
+'use strict';
+
+var zod = require('zod');
+
+/**
+ * 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.
+ */
+const OAuthConfigSchema = zod.z.object({
+    /**
+     * URL to the OAuth client metadata JSON document.
+     * This document describes your application to the authorization server.
+     *
+     * @see https://atproto.com/specs/oauth#client-metadata
+     */
+    clientId: zod.z.string().url(),
+    /**
+     * URL where users are redirected after authentication.
+     * Must match one of the redirect URIs in your client metadata.
+     */
+    redirectUri: zod.z.string().url(),
+    /**
+     * OAuth scopes to request, space-separated.
+     * Common scopes: "atproto", "transition:generic"
+     */
+    scope: zod.z.string(),
+    /**
+     * URL to your public JWKS (JSON Web Key Set) endpoint.
+     * Used by the authorization server to verify your client's signatures.
+     */
+    jwksUri: zod.z.string().url(),
+    /**
+     * Private JWK (JSON Web Key) as a JSON string.
+     * Used for signing DPoP proofs and client assertions.
+     *
+     * @remarks
+     * This should be kept secret and never exposed to clients.
+     * Typically loaded from environment variables or a secrets manager.
+     */
+    jwkPrivate: zod.z.string(),
+});
+/**
+ * Zod schema for server URL configuration.
+ *
+ * @remarks
+ * At least one server (PDS or SDS) should be configured for the SDK to be useful.
+ */
+const ServerConfigSchema = zod.z.object({
+    /**
+     * Personal Data Server URL - the user's own AT Protocol server.
+     * This is the primary server for user data operations.
+     *
+     * @example "https://bsky.social"
+     */
+    pds: zod.z.string().url().optional(),
+    /**
+     * Shared Data Server URL - for collaborative data storage.
+     * Required for collaborator and organization operations.
+     *
+     * @example "https://sds.hypercerts.org"
+     */
+    sds: zod.z.string().url().optional(),
+});
+/**
+ * Zod schema for timeout configuration.
+ *
+ * @remarks
+ * All timeout values are in milliseconds.
+ */
+const TimeoutConfigSchema = zod.z.object({
+    /**
+     * Timeout for fetching PDS metadata during identity resolution.
+     * @default 5000 (5 seconds, set by OAuthClient)
+     */
+    pdsMetadata: zod.z.number().positive().optional(),
+    /**
+     * Timeout for general API requests to PDS/SDS.
+     * @default 30000 (30 seconds)
+     */
+    apiRequests: zod.z.number().positive().optional(),
+});
+/**
+ * Zod schema for SDK configuration validation.
+ *
+ * @remarks
+ * This schema validates only the primitive/serializable parts of the configuration.
+ * Storage interfaces ({@link SessionStore}, {@link StateStore}) cannot be validated
+ * with Zod as they are runtime objects.
+ */
+const ATProtoSDKConfigSchema = zod.z.object({
+    oauth: OAuthConfigSchema,
+    servers: ServerConfigSchema.optional(),
+    timeouts: TimeoutConfigSchema.optional(),
+});
+
+/**
+ * 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.
+ */
+const CollaboratorPermissionsSchema = zod.z.object({
+    /**
+     * Can read/view records in the repository.
+     * This is the most basic permission level.
+     */
+    read: zod.z.boolean(),
+    /**
+     * Can create new records in the repository.
+     * Typically implies `read` permission.
+     */
+    create: zod.z.boolean(),
+    /**
+     * Can modify existing records in the repository.
+     * Typically implies `read` and `create` permissions.
+     */
+    update: zod.z.boolean(),
+    /**
+     * Can delete records from the repository.
+     * Typically implies `read`, `create`, and `update` permissions.
+     */
+    delete: zod.z.boolean(),
+    /**
+     * Can manage collaborators and their permissions.
+     * Administrative permission that allows inviting/removing collaborators.
+     */
+    admin: zod.z.boolean(),
+    /**
+     * 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: zod.z.boolean(),
+});
+/**
+ * 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.
+ */
+const OrganizationSchema = zod.z.object({
+    /**
+     * The organization's DID - unique identifier.
+     * Format: "did:plc:..." or "did:web:..."
+     */
+    did: zod.z.string(),
+    /**
+     * The organization's handle - human-readable identifier.
+     * Format: "orgname.sds.hypercerts.org" or similar
+     */
+    handle: zod.z.string(),
+    /**
+     * Display name for the organization.
+     */
+    name: zod.z.string(),
+    /**
+     * Optional description of the organization's purpose.
+     */
+    description: zod.z.string().optional(),
+    /**
+     * ISO 8601 timestamp when the organization was created.
+     * Format: "2024-01-15T10:30:00.000Z"
+     */
+    createdAt: zod.z.string(),
+    /**
+     * The current user's permissions within this organization.
+     */
+    permissions: CollaboratorPermissionsSchema,
+    /**
+     * How the current user relates to this organization.
+     * - `"owner"`: User created or owns the organization
+     * - `"collaborator"`: User was invited to collaborate
+     */
+    accessType: zod.z.enum(["owner", "collaborator"]),
+});
+/**
+ * Zod schema for collaborator data.
+ *
+ * Represents a user who has been granted access to a shared repository
+ * or organization with specific permissions.
+ */
+const CollaboratorSchema = zod.z.object({
+    /**
+     * The collaborator's DID - their unique identifier.
+     * Format: "did:plc:..." or "did:web:..."
+     */
+    userDid: zod.z.string(),
+    /**
+     * The permissions granted to this collaborator.
+     */
+    permissions: CollaboratorPermissionsSchema,
+    /**
+     * DID of the user who granted these permissions.
+     * Useful for audit trails.
+     */
+    grantedBy: zod.z.string(),
+    /**
+     * ISO 8601 timestamp when permissions were granted.
+     * Format: "2024-01-15T10:30:00.000Z"
+     */
+    grantedAt: zod.z.string(),
+    /**
+     * ISO 8601 timestamp when permissions were revoked, if applicable.
+     * Undefined if the collaborator is still active.
+     */
+    revokedAt: zod.z.string().optional(),
+});
+
+exports.ATProtoSDKConfigSchema = ATProtoSDKConfigSchema;
+exports.CollaboratorPermissionsSchema = CollaboratorPermissionsSchema;
+exports.CollaboratorSchema = CollaboratorSchema;
+exports.OAuthConfigSchema = OAuthConfigSchema;
+exports.OrganizationSchema = OrganizationSchema;
+exports.ServerConfigSchema = ServerConfigSchema;
+exports.TimeoutConfigSchema = TimeoutConfigSchema;
+//# sourceMappingURL=types.cjs.map