@hypercerts-org/sdk-core 0.5.0-beta.0 → 0.7.0-beta.0

package/src/repository/LexiconRegistry.ts

@@ -1,332 +0,0 @@
-import type { Agent } from "@atproto/api";
-import type { LexiconDoc } from "@atproto/lexicon";
-import { Lexicons } from "@atproto/lexicon";
-import { ValidationError } from "../core/errors.js";
-
-/**
- * Result of validating a record against a lexicon schema.
- */
-export interface ValidationResult {
-  /**
-   * Whether the record is valid according to the lexicon schema.
-   */
-  valid: boolean;
-
-  /**
-   * Error message if validation failed.
-   *
-   * Only present when `valid` is `false`.
-   */
-  error?: string;
-}
-
-/**
- * Registry for managing and validating AT Protocol lexicon schemas.
- *
- * Lexicons are schema definitions that describe the structure of records
- * in the AT Protocol. This registry allows you to:
- *
- * - Register custom lexicons for your application's record types
- * - Validate records against their lexicon schemas
- * - Extend the AT Protocol Agent with custom lexicon support
- *
- * @remarks
- * The SDK automatically registers hypercert lexicons when creating a Repository.
- * You only need to use this class directly if you're working with custom
- * record types.
- *
- * **Lexicon IDs** follow the NSID (Namespaced Identifier) format:
- * `{authority}.{name}` (e.g., `org.hypercerts.hypercert`)
- *
- * @example Registering custom lexicons
- * ```typescript
- * const registry = sdk.getLexiconRegistry();
- *
- * // Register a single lexicon
- * registry.register({
- *   lexicon: 1,
- *   id: "org.example.myRecord",
- *   defs: {
- *     main: {
- *       type: "record",
- *       key: "tid",
- *       record: {
- *         type: "object",
- *         required: ["title", "createdAt"],
- *         properties: {
- *           title: { type: "string" },
- *           description: { type: "string" },
- *           createdAt: { type: "string", format: "datetime" },
- *         },
- *       },
- *     },
- *   },
- * });
- *
- * // Register multiple lexicons at once
- * registry.registerMany([lexicon1, lexicon2, lexicon3]);
- * ```
- *
- * @example Validating records
- * ```typescript
- * const result = registry.validate("org.example.myRecord", {
- *   title: "Test",
- *   createdAt: new Date().toISOString(),
- * });
- *
- * if (!result.valid) {
- *   console.error(`Validation failed: ${result.error}`);
- * }
- * ```
- *
- * @see https://atproto.com/specs/lexicon for the Lexicon specification
- */
-export class LexiconRegistry {
-  /** Map of lexicon ID to lexicon document */
-  private lexicons = new Map<string, LexiconDoc>();
-
-  /** Lexicons collection for validation */
-  private lexiconsCollection: Lexicons;
-
-  /**
-   * Creates a new LexiconRegistry.
-   *
-   * The registry starts empty. Use {@link register} or {@link registerMany}
-   * to add lexicons.
-   */
-  constructor() {
-    this.lexiconsCollection = new Lexicons();
-  }
-
-  /**
-   * Registers a single lexicon schema.
-   *
-   * @param lexicon - The lexicon document to register
-   * @throws {@link ValidationError} if the lexicon doesn't have an `id` field
-   *
-   * @remarks
-   * If a lexicon with the same ID is already registered, it will be
-   * replaced with the new definition. This is useful for testing but
-   * should generally be avoided in production.
-   *
-   * @example
-   * ```typescript
-   * registry.register({
-   *   lexicon: 1,
-   *   id: "org.example.post",
-   *   defs: {
-   *     main: {
-   *       type: "record",
-   *       key: "tid",
-   *       record: {
-   *         type: "object",
-   *         required: ["text", "createdAt"],
-   *         properties: {
-   *           text: { type: "string", maxLength: 300 },
-   *           createdAt: { type: "string", format: "datetime" },
-   *         },
-   *       },
-   *     },
-   *   },
-   * });
-   * ```
-   */
-  register(lexicon: LexiconDoc): void {
-    if (!lexicon.id) {
-      throw new ValidationError("Lexicon must have an 'id' field");
-    }
-
-    // Remove existing lexicon if present (to allow overwriting)
-    if (this.lexicons.has(lexicon.id)) {
-      // Lexicons collection doesn't support removal, so we create a new one
-      // This is a limitation - in practice, lexicons shouldn't be overwritten
-      // But we allow it for testing and flexibility
-      const existingLexicon = this.lexicons.get(lexicon.id);
-      if (existingLexicon) {
-        // Try to remove from collection (may fail if not supported)
-        try {
-          // eslint-disable-next-line @typescript-eslint/no-explicit-any
-          (this.lexiconsCollection as any).remove?.(lexicon.id);
-        } catch {
-          // If removal fails, create a new collection
-          this.lexiconsCollection = new Lexicons();
-          // Re-register all other lexicons
-          for (const [id, lex] of this.lexicons.entries()) {
-            if (id !== lexicon.id) {
-              this.lexiconsCollection.add(lex);
-            }
-          }
-        }
-      }
-    }
-
-    this.lexicons.set(lexicon.id, lexicon);
-    this.lexiconsCollection.add(lexicon);
-  }
-
-  /**
-   * Registers multiple lexicons at once.
-   *
-   * @param lexicons - Array of lexicon documents to register
-   *
-   * @example
-   * ```typescript
-   * import { HYPERCERT_LEXICONS } from "@hypercerts-org/sdk/lexicons";
-   *
-   * registry.registerMany(HYPERCERT_LEXICONS);
-   * ```
-   */
-  registerMany(lexicons: LexiconDoc[]): void {
-    for (const lexicon of lexicons) {
-      this.register(lexicon);
-    }
-  }
-
-  /**
-   * Gets a lexicon document by ID.
-   *
-   * @param id - The lexicon NSID (e.g., "org.hypercerts.hypercert")
-   * @returns The lexicon document, or `undefined` if not registered
-   *
-   * @example
-   * ```typescript
-   * const lexicon = registry.get("org.hypercerts.hypercert");
-   * if (lexicon) {
-   *   console.log(`Found lexicon: ${lexicon.id}`);
-   * }
-   * ```
-   */
-  get(id: string): LexiconDoc | undefined {
-    return this.lexicons.get(id);
-  }
-
-  /**
-   * Validates a record against a collection's lexicon schema.
-   *
-   * @param collection - The collection NSID (same as lexicon ID)
-   * @param record - The record data to validate
-   * @returns Validation result with `valid` boolean and optional `error` message
-   *
-   * @remarks
-   * - If no lexicon is registered for the collection, validation passes
-   *   (we can't validate against unknown schemas)
-   * - Validation checks required fields and type constraints defined
-   *   in the lexicon schema
-   *
-   * @example
-   * ```typescript
-   * const result = registry.validate("org.hypercerts.hypercert", {
-   *   title: "My Hypercert",
-   *   description: "Description...",
-   *   // ... other fields
-   * });
-   *
-   * if (!result.valid) {
-   *   throw new Error(`Invalid record: ${result.error}`);
-   * }
-   * ```
-   */
-  validate(collection: string, record: unknown): ValidationResult {
-    // Check if we have a lexicon registered for this collection
-    // Collection format is typically "namespace.collection" (e.g., "app.bsky.feed.post")
-    // Lexicon ID format is the same
-    const lexiconId = collection;
-    const lexicon = this.lexicons.get(lexiconId);
-    if (!lexicon) {
-      // No lexicon registered - validation passes (can't validate unknown schemas)
-      return { valid: true };
-    }
-
-    // Check required fields if the lexicon defines them
-    const recordDef = lexicon.defs?.record;
-    if (recordDef && typeof recordDef === "object" && "record" in recordDef) {
-      const recordSchema = recordDef.record;
-      if (typeof recordSchema === "object" && "required" in recordSchema && Array.isArray(recordSchema.required)) {
-        const recordObj = record as Record<string, unknown>;
-        for (const requiredField of recordSchema.required) {
-          if (typeof requiredField === "string" && !(requiredField in recordObj)) {
-            return {
-              valid: false,
-              error: `Missing required field: ${requiredField}`,
-            };
-          }
-        }
-      }
-    }
-
-    try {
-      this.lexiconsCollection.assertValidRecord(collection, record);
-      return { valid: true };
-    } catch (error) {
-      // If error indicates lexicon not found, treat as validation pass
-      // (the lexicon might exist in Agent's collection but not ours)
-      const errorMessage = error instanceof Error ? error.message : String(error);
-      if (errorMessage.includes("not found") || errorMessage.includes("Lexicon not found")) {
-        return { valid: true };
-      }
-      return {
-        valid: false,
-        error: errorMessage,
-      };
-    }
-  }
-
-  /**
-   * Adds all registered lexicons to an AT Protocol Agent instance.
-   *
-   * This allows the Agent to understand custom lexicon types when making
-   * API requests.
-   *
-   * @param agent - The Agent instance to extend
-   *
-   * @remarks
-   * This is called automatically when creating a Repository. You typically
-   * don't need to call this directly unless you're using the Agent
-   * independently.
-   *
-   * @internal
-   */
-  addToAgent(agent: Agent): void {
-    // Access the internal lexicons collection and merge our lexicons
-    // The Agent's lex property is a Lexicons instance
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    const agentLex = (agent as any).lex as Lexicons;
-
-    // Add each registered lexicon to the agent
-    for (const lexicon of this.lexicons.values()) {
-      agentLex.add(lexicon);
-    }
-  }
-
-  /**
-   * Gets all registered lexicon IDs.
-   *
-   * @returns Array of lexicon NSIDs
-   *
-   * @example
-   * ```typescript
-   * const ids = registry.getRegisteredIds();
-   * console.log(`Registered lexicons: ${ids.join(", ")}`);
-   * ```
-   */
-  getRegisteredIds(): string[] {
-    return Array.from(this.lexicons.keys());
-  }
-
-  /**
-   * Checks if a lexicon is registered.
-   *
-   * @param id - The lexicon NSID to check
-   * @returns `true` if the lexicon is registered
-   *
-   * @example
-   * ```typescript
-   * if (registry.has("org.hypercerts.hypercert")) {
-   *   // Hypercert lexicon is available
-   * }
-   * ```
-   */
-  has(id: string): boolean {
-    return this.lexicons.has(id);
-  }
-}

package/src/repository/OrganizationOperationsImpl.ts

@@ -1,282 +0,0 @@
-/**
- * OrganizationOperationsImpl - SDS organization management operations.
- *
- * This module provides the implementation for creating and managing
- * organizations on Shared Data Server (SDS) instances.
- *
- * @packageDocumentation
- */
-
-import { NetworkError } from "../core/errors.js";
-import type { CollaboratorPermissions, Session } from "../core/types.js";
-import type { LoggerInterface } from "../core/interfaces.js";
-import type { OrganizationOperations } from "./interfaces.js";
-import type { OrganizationInfo } from "./types.js";
-
-/**
- * Implementation of organization operations for SDS management.
- *
- * Organizations on SDS provide a way to create shared repositories
- * that multiple users can collaborate on. Each organization has:
- *
- * - A unique DID (Decentralized Identifier)
- * - A handle for human-readable identification
- * - An owner and optional collaborators
- * - Its own repository for storing records
- *
- * @remarks
- * This class is typically not instantiated directly. Access it through
- * {@link Repository.organizations} on an SDS-connected repository.
- *
- * **SDS API Endpoints Used**:
- * - `com.sds.organization.create`: Create a new organization
- * - `com.sds.organization.list`: List accessible organizations
- *
- * **Access Types**:
- * - `"owner"`: User created or owns the organization
- * - `"collaborator"`: User was invited with specific permissions
- *
- * @example
- * ```typescript
- * // Get SDS repository
- * const sdsRepo = sdk.repository(session, { server: "sds" });
- *
- * // Create an organization
- * const org = await sdsRepo.organizations.create({
- *   name: "My Team",
- *   description: "A team for impact projects",
- * });
- *
- * // List organizations you have access to
- * const orgs = await sdsRepo.organizations.list();
- *
- * // Get specific organization
- * const orgInfo = await sdsRepo.organizations.get(org.did);
- * ```
- *
- * @internal
- */
-export class OrganizationOperationsImpl implements OrganizationOperations {
-  /**
-   * Creates a new OrganizationOperationsImpl.
-   *
-   * @param session - Authenticated OAuth session with fetchHandler
-   * @param _repoDid - DID of the user's repository (reserved for future use)
-   * @param serverUrl - SDS server URL
-   * @param _logger - Optional logger for debugging (reserved for future use)
-   *
-   * @internal
-   */
-  constructor(
-    private session: Session,
-    private _repoDid: string,
-    private serverUrl: string,
-    private _logger?: LoggerInterface,
-  ) {}
-
-  /**
-   * Creates a new organization.
-   *
-   * @param params - Organization parameters
-   * @param params.name - Display name for the organization
-   * @param params.description - Optional description of the organization's purpose
-   * @param params.handle - Optional custom handle. If not provided, one is auto-generated.
-   * @returns Promise resolving to the created organization info
-   * @throws {@link NetworkError} if organization creation fails
-   *
-   * @remarks
-   * The creating user automatically becomes the owner with full permissions.
-   *
-   * **Handle Format**: Handles are typically formatted as
-   * `{name}.sds.{domain}` (e.g., "my-team.sds.hypercerts.org").
-   * If you provide a custom handle, it must be unique on the SDS.
-   *
-   * @example Basic organization
-   * ```typescript
-   * const org = await repo.organizations.create({
-   *   name: "Climate Action Team",
-   * });
-   * console.log(`Created org: ${org.did}`);
-   * ```
-   *
-   * @example With description and custom handle
-   * ```typescript
-   * const org = await repo.organizations.create({
-   *   name: "Reforestation Initiative",
-   *   description: "Coordinating tree planting projects worldwide",
-   *   handle: "reforestation",
-   * });
-   * ```
-   */
-  async create(params: { name: string; description?: string; handle?: string }): Promise<OrganizationInfo> {
-    const userDid = this.session.did || this.session.sub;
-    if (!userDid) {
-      throw new NetworkError("No authenticated user found");
-    }
-
-    const response = await this.session.fetchHandler(`${this.serverUrl}/xrpc/com.sds.organization.create`, {
-      method: "POST",
-      headers: { "Content-Type": "application/json" },
-      body: JSON.stringify({
-        ...params,
-        creatorDid: userDid,
-      }),
-    });
-
-    if (!response.ok) {
-      throw new NetworkError(`Failed to create organization: ${response.statusText}`);
-    }
-
-    const data = await response.json();
-    return {
-      did: data.did,
-      handle: data.handle,
-      name: data.name,
-      description: data.description,
-      createdAt: data.createdAt || new Date().toISOString(),
-      accessType: data.accessType || "owner",
-      permissions: data.permissions || {
-        read: true,
-        create: true,
-        update: true,
-        delete: true,
-        admin: true,
-        owner: true,
-      },
-    };
-  }
-
-  /**
-   * Gets an organization by its DID.
-   *
-   * @param did - The organization's DID
-   * @returns Promise resolving to organization info, or `null` if not found
-   *
-   * @remarks
-   * This method searches through the user's accessible organizations.
-   * If the organization exists but the user doesn't have access,
-   * it will return `null`.
-   *
-   * @example
-   * ```typescript
-   * const org = await repo.organizations.get("did:plc:org123");
-   * if (org) {
-   *   console.log(`Found: ${org.name}`);
-   *   console.log(`Your role: ${org.accessType}`);
-   * } else {
-   *   console.log("Organization not found or no access");
-   * }
-   * ```
-   */
-  async get(did: string): Promise<OrganizationInfo | null> {
-    try {
-      const { organizations } = await this.list();
-      return organizations.find((o) => o.did === did) ?? null;
-    } catch {
-      return null;
-    }
-  }
-
-  /**
-   * Lists organizations the current user has access to.
-   *
-   * @param params - Optional pagination parameters
-   * @param params.limit - Maximum number of results (1-100, default 50)
-   * @param params.cursor - Pagination cursor from previous response
-   * @returns Promise resolving to organizations and optional cursor
-   * @throws {@link NetworkError} if the list operation fails
-   *
-   * @remarks
-   * Returns organizations where the user is either:
-   * - The owner
-   * - A collaborator with any permission level
-   *
-   * The `accessType` field indicates the user's relationship to each organization.
-   *
-   * @example
-   * ```typescript
-   * // Get first page
-   * const page1 = await repo.organizations.list({ limit: 20 });
-   * console.log(`Found ${page1.organizations.length} organizations`);
-   *
-   * // Get next page if available
-   * if (page1.cursor) {
-   *   const page2 = await repo.organizations.list({ limit: 20, cursor: page1.cursor });
-   * }
-   *
-   * // Filter by access type
-   * const owned = page1.organizations.filter(o => o.accessType === "owner");
-   * const shared = page1.organizations.filter(o => o.accessType === "shared");
-   * ```
-   *
-   * @example Display organization details
-   * ```typescript
-   * const { organizations } = await repo.organizations.list();
-   *
-   * for (const org of organizations) {
-   *   console.log(`${org.name} (@${org.handle})`);
-   *   console.log(`  DID: ${org.did}`);
-   *   console.log(`  Access: ${org.accessType}`);
-   *   if (org.description) {
-   *     console.log(`  Description: ${org.description}`);
-   *   }
-   * }
-   * ```
-   */
-  async list(params?: { limit?: number; cursor?: string }): Promise<{
-    organizations: OrganizationInfo[];
-    cursor?: string;
-  }> {
-    const userDid = this.session.did || this.session.sub;
-    if (!userDid) {
-      throw new NetworkError("No authenticated user found");
-    }
-
-    const queryParams = new URLSearchParams({
-      userDid,
-    });
-
-    if (params?.limit !== undefined) {
-      queryParams.set("limit", params.limit.toString());
-    }
-
-    if (params?.cursor) {
-      queryParams.set("cursor", params.cursor);
-    }
-
-    const response = await this.session.fetchHandler(
-      `${this.serverUrl}/xrpc/com.sds.organization.list?${queryParams.toString()}`,
-      { method: "GET" },
-    );
-
-    if (!response.ok) {
-      throw new NetworkError(`Failed to list organizations: ${response.statusText}`);
-    }
-
-    const data = await response.json();
-    const organizations = (data.organizations || []).map(
-      (r: {
-        did: string;
-        handle: string;
-        name: string;
-        description?: string;
-        createdAt?: string;
-        accessType: "owner" | "shared" | "none";
-        permissions: CollaboratorPermissions;
-      }) => ({
-        did: r.did,
-        handle: r.handle,
-        name: r.name,
-        description: r.description,
-        createdAt: r.createdAt || new Date().toISOString(),
-        accessType: r.accessType,
-        permissions: r.permissions,
-      }),
-    );
-
-    return {
-      organizations,
-      cursor: data.cursor,
-    };
-  }
-}