@hypercerts-org/sdk-core 0.4.0-beta.0 → 0.6.0-beta.0

package/src/testing/mocks.ts

@@ -1,142 +0,0 @@
-/**
- * Mock factories for testing.
- *
- * This module provides factory functions to create mock objects
- * for testing SDK functionality without real AT Protocol connections.
- *
- * @packageDocumentation
- */
-
-import type { Session } from "../core/types.js";
-import type { ATProtoSDKConfig } from "../core/config.js";
-
-/**
- * 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 }));
- *   },
- * });
- * ```
- */
-export function createMockSession(overrides: Partial<Session> = {}): Session {
-  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: RequestInfo | URL, _init?: RequestInit) => {
-      return new Response(JSON.stringify({}), {
-        status: 200,
-        headers: { "Content-Type": "application/json" },
-      });
-    },
-    ...overrides,
-  } as unknown as Session;
-
-  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,
- * });
- * ```
- */
-export function createTestConfig(overrides: Partial<ATProtoSDKConfig> = {}): ATProtoSDKConfig {
-  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,
-  };
-}

package/src/testing/stores.ts

@@ -1,285 +0,0 @@
-/**
- * Mock storage implementations for testing.
- *
- * This module provides mock implementations of SessionStore and StateStore
- * that track all operations for verification in tests.
- *
- * @packageDocumentation
- */
-
-import type { SessionStore, StateStore } from "../core/interfaces.js";
-import type { NodeSavedSession, NodeSavedState } from "@atproto/oauth-client-node";
-
-/**
- * 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");
- * ```
- */
-export class MockSessionStore implements SessionStore {
-  /**
-   * Internal storage for sessions.
-   * @internal
-   */
-  private store = new Map<string, NodeSavedSession>();
-
-  /**
-   * Record of all `get()` calls made to this store.
-   *
-   * Each entry is the DID that was requested.
-   */
-  public getCalls: string[] = [];
-
-  /**
-   * Record of all `set()` calls made to this store.
-   *
-   * Each entry contains the DID and session that was stored.
-   */
-  public setCalls: Array<{ did: string; session: NodeSavedSession }> = [];
-
-  /**
-   * Record of all `del()` calls made to this store.
-   *
-   * Each entry is the DID that was deleted.
-   */
-  public delCalls: string[] = [];
-
-  /**
-   * Retrieves a session by DID.
-   *
-   * Records the call in `getCalls`.
-   *
-   * @param did - The DID to look up
-   * @returns The stored session or undefined
-   */
-  async get(did: string): Promise<NodeSavedSession | undefined> {
-    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: string, session: NodeSavedSession): Promise<void> {
-    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: string): Promise<void> {
-    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(): void {
-    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);
- * ```
- */
-export class MockStateStore implements StateStore {
-  /**
-   * Internal storage for OAuth state.
-   * @internal
-   */
-  private store = new Map<string, NodeSavedState>();
-
-  /**
-   * Record of all `get()` calls made to this store.
-   *
-   * Each entry is the state key that was requested.
-   */
-  public getCalls: string[] = [];
-
-  /**
-   * Record of all `set()` calls made to this store.
-   *
-   * Each entry contains the key and state that was stored.
-   */
-  public setCalls: Array<{ key: string; state: NodeSavedState }> = [];
-
-  /**
-   * Record of all `del()` calls made to this store.
-   *
-   * Each entry is the state key that was deleted.
-   */
-  public delCalls: string[] = [];
-
-  /**
-   * Retrieves OAuth state by key.
-   *
-   * Records the call in `getCalls`.
-   *
-   * @param key - The state key to look up
-   * @returns The stored state or undefined
-   */
-  async get(key: string): Promise<NodeSavedState | undefined> {
-    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: string, state: NodeSavedState): Promise<void> {
-    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: string): Promise<void> {
-    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(): void {
-    this.store.clear();
-    this.getCalls = [];
-    this.setCalls = [];
-    this.delCalls = [];
-  }
-}

package/src/testing.ts

@@ -1,64 +0,0 @@
-/**
- * Testing entrypoint - Test utilities and mocks
- *
- * This module provides utilities for testing applications built with the Hypercerts SDK.
- * Includes mock factories for creating test data and mock store implementations
- * with call tracking for assertions.
- *
- * @remarks
- * These utilities are designed for use in unit and integration tests.
- * They should NOT be used in production code.
- *
- * The mock stores track all method calls, making it easy to verify
- * that your code interacts with storage correctly.
- *
- * @example
- * ```typescript
- * // Basic test setup
- * import {
- *   createMockSession,
- *   createTestConfig,
- *   MockSessionStore,
- *   MockStateStore
- * } from "@hypercerts-org/sdk/testing";
- * import { HypercertsSDK } from "@hypercerts-org/sdk";
- *
- * describe("MyComponent", () => {
- *   let sdk: HypercertsSDK;
- *   let sessionStore: MockSessionStore;
- *
- *   beforeEach(() => {
- *     sessionStore = new MockSessionStore();
- *     sdk = new HypercertsSDK(createTestConfig({
- *       sessionStore,
- *       stateStore: new MockStateStore(),
- *     }));
- *   });
- *
- *   it("should store session after login", async () => {
- *     // ... perform login flow
- *     expect(sessionStore.setCalls).toHaveLength(1);
- *   });
- * });
- * ```
- *
- * @example
- * ```typescript
- * // Creating mock data for tests
- * import { createMockSession } from "@hypercerts-org/sdk/testing";
- *
- * const session = createMockSession({
- *   did: "did:plc:testuser123",
- *   handle: "testuser.bsky.social",
- * });
- *
- * // Session has all required fields populated with test values
- * expect(session.did).toBe("did:plc:testuser123");
- * expect(session.accessToken).toBeDefined();
- * ```
- *
- * @packageDocumentation
- */
-
-export { createMockSession, createTestConfig } from "./testing/mocks.js";
-export { MockSessionStore, MockStateStore } from "./testing/stores.js";

package/src/types.ts

@@ -1,86 +0,0 @@
-/**
- * Types entrypoint - All TypeScript types and interfaces.
- *
- * This sub-entrypoint exports only TypeScript types and Zod schemas,
- * with no runtime code. Use this for type-only imports to reduce
- * bundle size when you only need types.
- *
- * @remarks
- * Import from `@hypercerts-org/sdk/types` when you only need types:
- *
- * ```typescript
- * import type {
- *   HypercertClaim,
- *   Session,
- *   CreateHypercertParams,
- * } from "@hypercerts-org/sdk/types";
- * ```
- *
- * **Categories of exports**:
- * - Core types (DID, Session, Config)
- * - Entity types (Organization, Collaborator)
- * - Repository types (CreateResult, PaginatedList)
- * - Operation interfaces (RecordOperations, HypercertOperations)
- * - Hypercert record types (HypercertClaim, HypercertRights, etc.)
- * - Zod schemas for runtime validation
- *
- * @packageDocumentation
- */
-
-// Core types
-export type { DID, Session } from "./core/types.js";
-export type { ATProtoSDKConfig } from "./core/config.js";
-export type { AuthorizeOptions } from "./core/SDK.js";
-export type { SessionStore, StateStore, CacheInterface, LoggerInterface } from "./core/interfaces.js";
-
-// Entity types
-export type { Organization, Collaborator, CollaboratorPermissions } from "./core/types.js";
-
-// Zod schemas (for runtime validation)
-export { ATProtoSDKConfigSchema, OAuthConfigSchema, ServerConfigSchema, TimeoutConfigSchema } from "./core/config.js";
-export { OrganizationSchema, CollaboratorSchema, CollaboratorPermissionsSchema } from "./core/types.js";
-
-// Repository class
-export type { ValidationResult } from "./repository/LexiconRegistry.js";
-
-// Repository types
-export type {
-  RepositoryOptions,
-  CreateResult,
-  UpdateResult,
-  PaginatedList,
-  ListParams,
-  RepositoryRole,
-  RepositoryAccessGrant,
-  OrganizationInfo,
-  ProgressStep,
-} from "./repository/types.js";
-
-// Operation interfaces
-export type {
-  RecordOperations,
-  BlobOperations,
-  ProfileOperations,
-  HypercertOperations,
-  HypercertEvents,
-  CollaboratorOperations,
-  OrganizationOperations,
-  CreateHypercertParams,
-  CreateHypercertResult,
-} from "./repository/interfaces.js";
-
-// Hypercert types
-export type {
-  HypercertClaim,
-  HypercertRights,
-  HypercertLocation,
-  HypercertContribution,
-  HypercertMeasurement,
-  HypercertEvaluation,
-  HypercertCollection,
-  HypercertCollectionClaimItem,
-  HypercertEvidence,
-  HypercertImage,
-  BlobRef,
-  HypercertWithMetadata,
-} from "./services/hypercerts/types.js";