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

package/src/repository/types.ts

@@ -1,111 +0,0 @@
-/**
- * Repository types - Shared types for repository operations
- * @packageDocumentation
- */
-
-import type { CollaboratorPermissions } from "../core/types.js";
-
-// ============================================================================
-// Basic Types
-// ============================================================================
-
-/**
- * Options for creating a repository instance
- */
-export 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
- */
-export interface CreateResult {
-  uri: string;
-  cid: string;
-}
-
-/**
- * Result of an update operation
- */
-export interface UpdateResult {
-  uri: string;
-  cid: string;
-}
-
-/**
- * Paginated list result
- */
-export interface PaginatedList<T> {
-  records: T[];
-  cursor?: string;
-}
-
-/**
- * List parameters
- */
-export interface ListParams {
-  limit?: number;
-  cursor?: string;
-}
-
-// ============================================================================
-// Collaborator Types
-// ============================================================================
-
-/**
- * Role for repository access
- */
-export type RepositoryRole = "viewer" | "editor" | "admin" | "owner";
-
-/**
- * Repository access grant
- */
-export interface RepositoryAccessGrant {
-  userDid: string;
-  role: RepositoryRole;
-  permissions: CollaboratorPermissions;
-  grantedBy: string;
-  grantedAt: string;
-  revokedAt?: string;
-}
-
-// ============================================================================
-// Organization Types
-// ============================================================================
-
-/**
- * Organization info
- */
-export 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 Types
-// ============================================================================
-
-/**
- * Progress step for long-running operations
- */
-export interface ProgressStep {
-  name: string;
-  status: "start" | "success" | "error";
-  data?: unknown;
-  error?: Error;
-}

package/src/services/hypercerts/types.ts

@@ -1,87 +0,0 @@
-/**
- * TypeScript types for hypercert lexicon schemas.
- *
- * Re-exports generated types and validation from `@hypercerts-org/lexicon`.
- *
- * @packageDocumentation
- */
-
-// Re-export everything from lexicon package
-export {
-  // Namespaced types with validation (isRecord, validateRecord)
-  OrgHypercertsClaim,
-  OrgHypercertsClaimRights,
-  OrgHypercertsClaimContribution,
-  OrgHypercertsClaimMeasurement,
-  OrgHypercertsClaimEvaluation,
-  OrgHypercertsClaimEvidence,
-  OrgHypercertsCollection,
-  AppCertifiedLocation,
-  ComAtprotoRepoStrongRef,
-  // Validation utilities
-  validate,
-  schemas,
-  schemaDict,
-  lexicons,
-  ids,
-  // Lexicon constants
-  HYPERCERT_LEXICONS,
-  HYPERCERT_COLLECTIONS,
-} from "@hypercerts-org/lexicon";
-
-export type { AppCertifiedDefs } from "@hypercerts-org/lexicon";
-
-import type {
-  OrgHypercertsClaim,
-  OrgHypercertsClaimRights,
-  OrgHypercertsClaimContribution,
-  OrgHypercertsClaimMeasurement,
-  OrgHypercertsClaimEvaluation,
-  OrgHypercertsCollection,
-  AppCertifiedLocation,
-  ComAtprotoRepoStrongRef,
-} from "@hypercerts-org/lexicon";
-
-// ============================================================================
-// Type Aliases
-// ============================================================================
-
-export type StrongRef = ComAtprotoRepoStrongRef.Main;
-export type HypercertClaim = OrgHypercertsClaim.Main;
-export type HypercertRights = OrgHypercertsClaimRights.Main;
-export type HypercertContribution = OrgHypercertsClaimContribution.Main;
-export type HypercertMeasurement = OrgHypercertsClaimMeasurement.Main;
-export type HypercertEvaluation = OrgHypercertsClaimEvaluation.Main;
-export type HypercertCollection = OrgHypercertsCollection.Main;
-export type HypercertCollectionClaimItem = OrgHypercertsCollection.ClaimItem;
-export type HypercertLocation = AppCertifiedLocation.Main;
-
-// ============================================================================
-// SDK Input Helper Types
-// ATProto API infers $type from the collection
-// ============================================================================
-
-/** Blob reference for uploaded files (images, GeoJSON, etc.) */
-export interface BlobRef {
-  $type: "blob";
-  ref: { $link: string };
-  mimeType: string;
-  size: number;
-}
-
-/** Evidence item for operations */
-export interface HypercertEvidence {
-  uri: string;
-  title?: string;
-  description?: string;
-}
-
-/** Image input for operations */
-export type HypercertImage = { type: "uri"; uri: string } | { type: "blob"; blob: Blob };
-
-/** Hypercert with AT Protocol metadata */
-export interface HypercertWithMetadata {
-  uri: string;
-  cid: string;
-  record: HypercertClaim;
-}

package/src/storage/InMemorySessionStore.ts

@@ -1,127 +0,0 @@
-import type { SessionStore } from "../core/interfaces.js";
-import type { NodeSavedSession } from "@atproto/oauth-client-node";
-
-/**
- * In-memory implementation of the SessionStore interface.
- *
- * This store keeps OAuth sessions in memory using a Map. It's intended
- * for development, testing, and simple use cases where session persistence
- * across restarts is not required.
- *
- * @remarks
- * **Warning**: This implementation is **not suitable for production** because:
- * - Sessions are lost when the process restarts
- * - Sessions cannot be shared across multiple server instances
- * - No automatic cleanup of expired sessions
- *
- * For production, implement {@link SessionStore} with a persistent backend:
- * - **Redis**: Good for distributed systems, supports TTL
- * - **PostgreSQL/MySQL**: Good for existing database infrastructure
- * - **MongoDB**: Good for document-based storage
- *
- * @example Basic usage
- * ```typescript
- * import { InMemorySessionStore } from "@hypercerts-org/sdk/storage";
- *
- * const sessionStore = new InMemorySessionStore();
- *
- * const sdk = new ATProtoSDK({
- *   oauth: { ... },
- *   storage: {
- *     sessionStore,  // Will warn in logs for production
- *   },
- * });
- * ```
- *
- * @example Testing usage
- * ```typescript
- * const sessionStore = new InMemorySessionStore();
- *
- * // After tests, clean up
- * sessionStore.clear();
- * ```
- *
- * @see {@link SessionStore} for the interface definition
- * @see {@link InMemoryStateStore} for the corresponding state store
- */
-export class InMemorySessionStore implements SessionStore {
-  /**
-   * Internal storage for sessions, keyed by DID.
-   * @internal
-   */
-  private sessions = new Map<string, NodeSavedSession>();
-
-  /**
-   * Retrieves a session by DID.
-   *
-   * @param did - The user's Decentralized Identifier
-   * @returns Promise resolving to the session, or `undefined` if not found
-   *
-   * @example
-   * ```typescript
-   * const session = await sessionStore.get("did:plc:abc123");
-   * if (session) {
-   *   console.log("Session found");
-   * }
-   * ```
-   */
-  async get(did: string): Promise<NodeSavedSession | undefined> {
-    return this.sessions.get(did);
-  }
-
-  /**
-   * Stores or updates a session.
-   *
-   * @param did - The user's DID to use as the key
-   * @param session - The session data to store
-   *
-   * @remarks
-   * If a session already exists for the DID, it is overwritten.
-   *
-   * @example
-   * ```typescript
-   * await sessionStore.set("did:plc:abc123", sessionData);
-   * ```
-   */
-  async set(did: string, session: NodeSavedSession): Promise<void> {
-    this.sessions.set(did, session);
-  }
-
-  /**
-   * Deletes a session by DID.
-   *
-   * @param did - The DID of the session to delete
-   *
-   * @remarks
-   * If no session exists for the DID, this is a no-op.
-   *
-   * @example
-   * ```typescript
-   * await sessionStore.del("did:plc:abc123");
-   * ```
-   */
-  async del(did: string): Promise<void> {
-    this.sessions.delete(did);
-  }
-
-  /**
-   * Clears all stored sessions.
-   *
-   * This is primarily useful for testing to ensure a clean state
-   * between test runs.
-   *
-   * @remarks
-   * This method is synchronous (not async) for convenience in test cleanup.
-   *
-   * @example
-   * ```typescript
-   * // In test teardown
-   * afterEach(() => {
-   *   sessionStore.clear();
-   * });
-   * ```
-   */
-  clear(): void {
-    this.sessions.clear();
-  }
-}

package/src/storage/InMemoryStateStore.ts

@@ -1,146 +0,0 @@
-import type { StateStore } from "../core/interfaces.js";
-import type { NodeSavedState } from "@atproto/oauth-client-node";
-
-/**
- * In-memory implementation of the StateStore interface.
- *
- * This store keeps OAuth state parameters in memory using a Map. State is
- * used during the OAuth authorization flow for CSRF protection and PKCE.
- *
- * @remarks
- * **Warning**: This implementation is **not suitable for production** because:
- * - State is lost when the process restarts (breaking in-progress OAuth flows)
- * - State cannot be shared across multiple server instances
- * - No automatic cleanup of expired state (memory leak potential)
- *
- * For production, implement {@link StateStore} with a persistent backend
- * that supports TTL (time-to-live):
- * - **Redis**: Ideal choice with built-in TTL support
- * - **Database with cleanup job**: PostgreSQL/MySQL with periodic cleanup
- *
- * **State Lifecycle**:
- * 1. Created when user starts OAuth flow (`authorize()`)
- * 2. Retrieved and validated during callback
- * 3. Deleted after successful or failed callback
- * 4. Should expire after ~15 minutes if callback never happens
- *
- * @example Basic usage
- * ```typescript
- * import { InMemoryStateStore } from "@hypercerts-org/sdk/storage";
- *
- * const stateStore = new InMemoryStateStore();
- *
- * const sdk = new ATProtoSDK({
- *   oauth: { ... },
- *   storage: {
- *     stateStore,  // Will warn in logs for production
- *   },
- * });
- * ```
- *
- * @example Testing usage
- * ```typescript
- * const stateStore = new InMemoryStateStore();
- *
- * // After tests, clean up
- * stateStore.clear();
- * ```
- *
- * @see {@link StateStore} for the interface definition
- * @see {@link InMemorySessionStore} for the corresponding session store
- */
-export class InMemoryStateStore implements StateStore {
-  /**
-   * Internal storage for OAuth state, keyed by state string.
-   * @internal
-   */
-  private states = new Map<string, NodeSavedState>();
-
-  /**
-   * Retrieves OAuth state by key.
-   *
-   * @param key - The state key (random string from authorization URL)
-   * @returns Promise resolving to the state, or `undefined` if not found
-   *
-   * @remarks
-   * The key is a cryptographically random string generated during
-   * the authorization request. It's included in the callback URL
-   * and used to retrieve the associated PKCE verifier and other data.
-   *
-   * @example
-   * ```typescript
-   * // During OAuth callback
-   * const state = await stateStore.get(params.get("state")!);
-   * if (!state) {
-   *   throw new Error("Invalid or expired state");
-   * }
-   * ```
-   */
-  async get(key: string): Promise<NodeSavedState | undefined> {
-    return this.states.get(key);
-  }
-
-  /**
-   * Stores OAuth state temporarily.
-   *
-   * @param key - The state key to use for storage
-   * @param state - The OAuth state data (includes PKCE verifier, etc.)
-   *
-   * @remarks
-   * In production implementations, state should be stored with a TTL
-   * of approximately 10-15 minutes to prevent stale state accumulation.
-   *
-   * @example
-   * ```typescript
-   * // Called internally by OAuthClient during authorize()
-   * await stateStore.set(stateKey, {
-   *   // PKCE code verifier, redirect URI, etc.
-   * });
-   * ```
-   */
-  async set(key: string, state: NodeSavedState): Promise<void> {
-    this.states.set(key, state);
-  }
-
-  /**
-   * Deletes OAuth state by key.
-   *
-   * @param key - The state key to delete
-   *
-   * @remarks
-   * Called after the OAuth callback is processed (whether successful or not)
-   * to clean up the temporary state.
-   *
-   * @example
-   * ```typescript
-   * // After processing callback
-   * await stateStore.del(stateKey);
-   * ```
-   */
-  async del(key: string): Promise<void> {
-    this.states.delete(key);
-  }
-
-  /**
-   * Clears all stored state.
-   *
-   * This is primarily useful for testing to ensure a clean state
-   * between test runs.
-   *
-   * @remarks
-   * This method is synchronous (not async) for convenience in test cleanup.
-   * In production, be careful using this as it will invalidate all
-   * in-progress OAuth flows.
-   *
-   * @example
-   * ```typescript
-   * // In test teardown
-   * afterEach(() => {
-   *   stateStore.clear();
-   * });
-   * ```
-   */
-  clear(): void {
-    this.states.clear();
-  }
-}

package/src/storage.ts

@@ -1,63 +0,0 @@
-/**
- * Storage entrypoint - Storage implementations and interfaces
- *
- * This module provides storage adapters for persisting OAuth sessions and state.
- * Includes in-memory implementations for development and testing, plus interfaces
- * for implementing custom storage backends (Redis, database, etc.).
- *
- * @remarks
- * The in-memory implementations are suitable for:
- * - Development and testing environments
- * - Single-server deployments with acceptable session loss on restart
- * - Prototyping and demos
- *
- * For production multi-server deployments, implement the interfaces with
- * a distributed storage backend like Redis, PostgreSQL, or a managed
- * key-value store.
- *
- * @example
- * ```typescript
- * // Using built-in in-memory stores (development)
- * import { InMemorySessionStore, InMemoryStateStore } from "@hypercerts-org/sdk";
- *
- * const sessionStore = new InMemorySessionStore();
- * const stateStore = new InMemoryStateStore();
- *
- * const sdk = new HypercertsSDK({
- *   sessionStore,
- *   stateStore,
- *   // ... other config
- * });
- * ```
- *
- * @example
- * ```typescript
- * // Implementing custom storage (production)
- * import type { SessionStore, StateStore } from "@hypercerts-org/sdk";
- * import Redis from "ioredis";
- *
- * class RedisSessionStore implements SessionStore {
- *   constructor(private redis: Redis) {}
- *
- *   async get(did: string) {
- *     const data = await this.redis.get(`session:${did}`);
- *     return data ? JSON.parse(data) : undefined;
- *   }
- *
- *   async set(did: string, session: Session) {
- *     await this.redis.set(`session:${did}`, JSON.stringify(session));
- *   }
- *
- *   async delete(did: string) {
- *     await this.redis.del(`session:${did}`);
- *   }
- * }
- * ```
- *
- * @packageDocumentation
- */
-
-export { InMemorySessionStore } from "./storage/InMemorySessionStore.js";
-export { InMemoryStateStore } from "./storage/InMemoryStateStore.js";
-
-export type { SessionStore, StateStore, CacheInterface } from "./core/interfaces.js";

package/src/testing/index.ts

@@ -1,67 +0,0 @@
-/**
- * Testing utilities for the Hypercerts SDK.
- *
- * This module exports mock implementations and factory functions
- * for testing applications that use the SDK.
- *
- * @remarks
- * Import from `@hypercerts-org/sdk/testing` to access these utilities:
- *
- * ```typescript
- * import {
- *   createMockSession,
- *   createTestConfig,
- *   MockSessionStore,
- *   MockStateStore,
- * } from "@hypercerts-org/sdk/testing";
- * ```
- *
- * **Available Utilities**:
- *
- * - {@link createMockSession} - Factory for mock OAuth sessions
- * - {@link createTestConfig} - Factory for test SDK configurations
- * - {@link MockSessionStore} - Mock session store with call tracking
- * - {@link MockStateStore} - Mock state store with call tracking
- *
- * @example Setting up tests
- * ```typescript
- * import { ATProtoSDK } from "@hypercerts-org/sdk";
- * import {
- *   createTestConfig,
- *   createMockSession,
- *   MockSessionStore,
- *   MockStateStore,
- * } from "@hypercerts-org/sdk/testing";
- *
- * describe("MyApp", () => {
- *   let sdk: ATProtoSDK;
- *   let sessionStore: MockSessionStore;
- *   let stateStore: MockStateStore;
- *
- *   beforeEach(() => {
- *     sessionStore = new MockSessionStore();
- *     stateStore = new MockStateStore();
- *
- *     sdk = new ATProtoSDK(createTestConfig({
- *       storage: { sessionStore, stateStore },
- *     }));
- *   });
- *
- *   afterEach(() => {
- *     sessionStore.reset();
- *     stateStore.reset();
- *   });
- *
- *   it("should work with mock session", () => {
- *     const session = createMockSession();
- *     const repo = sdk.repository(session);
- *     // ... test repository operations
- *   });
- * });
- * ```
- *
- * @packageDocumentation
- */
-
-export { createMockSession, createTestConfig } from "./mocks.js";
-export { MockSessionStore, MockStateStore } from "./stores.js";