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

package/src/core/types.ts

@@ -1,282 +0,0 @@
-import type { OAuthSession } from "@atproto/oauth-client-node";
-import { z } from "zod";
-
-/**
- * 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
- */
-export 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
- */
-export 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.
- */
-export const CollaboratorPermissionsSchema = z.object({
-  /**
-   * Can read/view records in the repository.
-   * This is the most basic permission level.
-   */
-  read: z.boolean(),
-
-  /**
-   * Can create new records in the repository.
-   * Typically implies `read` permission.
-   */
-  create: z.boolean(),
-
-  /**
-   * Can modify existing records in the repository.
-   * Typically implies `read` and `create` permissions.
-   */
-  update: z.boolean(),
-
-  /**
-   * Can delete records from the repository.
-   * Typically implies `read`, `create`, and `update` permissions.
-   */
-  delete: z.boolean(),
-
-  /**
-   * Can manage collaborators and their permissions.
-   * Administrative permission that allows inviting/removing collaborators.
-   */
-  admin: 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: z.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,
- * };
- * ```
- */
-export 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.
- */
-export const OrganizationSchema = z.object({
-  /**
-   * The organization's DID - unique identifier.
-   * Format: "did:plc:..." or "did:web:..."
-   */
-  did: z.string(),
-
-  /**
-   * The organization's handle - human-readable identifier.
-   * Format: "orgname.sds.hypercerts.org" or similar
-   */
-  handle: z.string(),
-
-  /**
-   * Display name for the organization.
-   */
-  name: z.string(),
-
-  /**
-   * Optional description of the organization's purpose.
-   */
-  description: z.string().optional(),
-
-  /**
-   * ISO 8601 timestamp when the organization was created.
-   * Format: "2024-01-15T10:30:00.000Z"
-   */
-  createdAt: 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
-   * - `"shared"`: User was invited to collaborate (has permissions)
-   * - `"none"`: User has no access to this organization
-   */
-  accessType: z.enum(["owner", "shared", "none"]),
-});
-
-/**
- * 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",
- * };
- * ```
- */
-export 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.
- */
-export const CollaboratorSchema = z.object({
-  /**
-   * The collaborator's DID - their unique identifier.
-   * Format: "did:plc:..." or "did:web:..."
-   */
-  userDid: z.string(),
-
-  /**
-   * The permissions granted to this collaborator.
-   */
-  permissions: CollaboratorPermissionsSchema,
-
-  /**
-   * DID of the user who granted these permissions.
-   * Useful for audit trails.
-   */
-  grantedBy: z.string(),
-
-  /**
-   * ISO 8601 timestamp when permissions were granted.
-   * Format: "2024-01-15T10:30:00.000Z"
-   */
-  grantedAt: z.string(),
-
-  /**
-   * ISO 8601 timestamp when permissions were revoked, if applicable.
-   * Undefined if the collaborator is still active.
-   */
-  revokedAt: z.string().optional(),
-});
-
-/**
- * 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",
- * };
- * ```
- */
-export type Collaborator = z.infer<typeof CollaboratorSchema>;

package/src/errors.ts

@@ -1,57 +0,0 @@
-/**
- * Errors entrypoint - All SDK error classes.
- *
- * This sub-entrypoint exports all error classes used by the SDK.
- * Import from here when you need to catch or check specific error types.
- *
- * @remarks
- * Import from `@hypercerts-org/sdk/errors`:
- *
- * ```typescript
- * import {
- *   ATProtoSDKError,
- *   AuthenticationError,
- *   ValidationError,
- * } from "@hypercerts-org/sdk/errors";
- * ```
- *
- * **Error Hierarchy**:
- * - {@link ATProtoSDKError} - Base class for all SDK errors
- *   - {@link AuthenticationError} - OAuth/authentication failures
- *   - {@link SessionExpiredError} - Session expired, needs re-auth
- *   - {@link ValidationError} - Input/schema validation failures
- *   - {@link NetworkError} - Network/server errors
- *   - {@link SDSRequiredError} - SDS-only operation on PDS
- *
- * @example Catching specific errors
- * ```typescript
- * import {
- *   ATProtoSDKError,
- *   AuthenticationError,
- *   ValidationError,
- * } from "@hypercerts-org/sdk/errors";
- *
- * try {
- *   await sdk.authorize(identifier);
- * } catch (error) {
- *   if (error instanceof AuthenticationError) {
- *     console.error("Auth failed:", error.message);
- *   } else if (error instanceof ValidationError) {
- *     console.error("Invalid input:", error.message);
- *   } else if (error instanceof ATProtoSDKError) {
- *     console.error(`SDK error [${error.code}]:`, error.message);
- *   }
- * }
- * ```
- *
- * @packageDocumentation
- */
-
-export {
-  ATProtoSDKError,
-  AuthenticationError,
-  SessionExpiredError,
-  ValidationError,
-  NetworkError,
-  SDSRequiredError,
-} from "./core/errors.js";

package/src/index.ts

@@ -1,107 +0,0 @@
-/**
- * Hypercerts SDK - Main entrypoint.
- *
- * @packageDocumentation
- */
-
-// Core SDK
-export { ATProtoSDK, createATProtoSDK } from "./core/SDK.js";
-export type { AuthorizeOptions } from "./core/SDK.js";
-export type { ATProtoSDKConfig } from "./core/config.js";
-export type { Session } from "./core/types.js";
-
-// Repository (fluent API)
-export { Repository } from "./repository/Repository.js";
-export type {
-  RepositoryOptions,
-  CreateResult,
-  UpdateResult,
-  PaginatedList,
-  ListParams,
-  RepositoryRole,
-  RepositoryAccessGrant,
-  OrganizationInfo,
-  ProgressStep,
-} from "./repository/types.js";
-export type {
-  RecordOperations,
-  BlobOperations,
-  ProfileOperations,
-  HypercertOperations,
-  HypercertEvents,
-  CollaboratorOperations,
-  OrganizationOperations,
-  CreateHypercertParams,
-  CreateHypercertResult,
-} from "./repository/interfaces.js";
-
-// Lexicon Registry
-export { LexiconRegistry } from "./repository/LexiconRegistry.js";
-export type { ValidationResult } from "./repository/LexiconRegistry.js";
-
-// ============================================================================
-// Lexicon Types and Validation (from @hypercerts-org/lexicon)
-// ============================================================================
-
-// Namespaced types with validation functions (isRecord, validateRecord)
-export {
-  OrgHypercertsClaim,
-  OrgHypercertsClaimRights,
-  OrgHypercertsClaimContribution,
-  OrgHypercertsClaimMeasurement,
-  OrgHypercertsClaimEvaluation,
-  OrgHypercertsClaimEvidence,
-  OrgHypercertsCollection,
-  AppCertifiedLocation,
-  ComAtprotoRepoStrongRef,
-  // Validation utilities
-  validate,
-  schemas,
-  schemaDict,
-  lexicons,
-  ids,
-  // Lexicon constants
-  HYPERCERT_LEXICONS,
-  HYPERCERT_COLLECTIONS,
-} from "./services/hypercerts/types.js";
-
-// Type-only exports
-export type { AppCertifiedDefs } from "./services/hypercerts/types.js";
-
-// Type aliases for generated lexicon types
-export type {
-  StrongRef,
-  HypercertClaim,
-  HypercertRights,
-  HypercertContribution,
-  HypercertMeasurement,
-  HypercertEvaluation,
-  HypercertCollection,
-  HypercertCollectionClaimItem,
-  HypercertLocation,
-  // SDK-specific types
-  HypercertEvidence,
-  HypercertImage,
-  BlobRef,
-  HypercertWithMetadata,
-} from "./services/hypercerts/types.js";
-
-// Errors
-export {
-  ATProtoSDKError,
-  AuthenticationError,
-  SessionExpiredError,
-  ValidationError,
-  NetworkError,
-  SDSRequiredError,
-} from "./core/errors.js";
-
-// Storage interfaces and implementations
-export type { SessionStore, StateStore, CacheInterface, LoggerInterface } from "./core/interfaces.js";
-export { InMemorySessionStore } from "./storage/InMemorySessionStore.js";
-export { InMemoryStateStore } from "./storage/InMemoryStateStore.js";
-
-// Core types and schemas
-export type { DID, Organization, Collaborator, CollaboratorPermissions } from "./core/types.js";
-export { OrganizationSchema, CollaboratorSchema, CollaboratorPermissionsSchema } from "./core/types.js";
-export { ATProtoSDKConfigSchema, OAuthConfigSchema, ServerConfigSchema, TimeoutConfigSchema } from "./core/config.js";

package/src/lexicons.ts

@@ -1,64 +0,0 @@
-/**
- * Lexicons entrypoint - Lexicon definitions and registry.
- *
- * This sub-entrypoint exports the lexicon registry and hypercert
- * lexicon constants for working with AT Protocol record schemas.
- *
- * @remarks
- * Import from `@hypercerts-org/sdk/lexicons`:
- *
- * ```typescript
- * import {
- *   LexiconRegistry,
- *   HYPERCERT_LEXICONS,
- *   HYPERCERT_COLLECTIONS,
- * } from "@hypercerts-org/sdk/lexicons";
- * ```
- *
- * **Exports**:
- * - {@link LexiconRegistry} - Registry for managing and validating lexicons
- * - {@link HYPERCERT_LEXICONS} - Array of all hypercert lexicon documents
- * - {@link HYPERCERT_COLLECTIONS} - Constants for collection NSIDs
- *
- * @example Using collection constants
- * ```typescript
- * import { HYPERCERT_COLLECTIONS } from "@hypercerts-org/sdk/lexicons";
- *
- * // List hypercerts using the correct collection name
- * const records = await repo.records.list({
- *   collection: HYPERCERT_COLLECTIONS.RECORD,
- * });
- *
- * // List contributions
- * const contributions = await repo.records.list({
- *   collection: HYPERCERT_COLLECTIONS.CONTRIBUTION,
- * });
- * ```
- *
- * @example Custom lexicon registration
- * ```typescript
- * import { LexiconRegistry } from "@hypercerts-org/sdk/lexicons";
- *
- * const registry = sdk.getLexiconRegistry();
- *
- * // Register custom lexicon
- * registry.register({
- *   lexicon: 1,
- *   id: "org.myapp.customRecord",
- *   defs: { ... },
- * });
- *
- * // Validate a record
- * const result = registry.validate("org.myapp.customRecord", record);
- * if (!result.valid) {
- *   console.error(result.error);
- * }
- * ```
- *
- * @packageDocumentation
- */
-
-export { LexiconRegistry } from "./repository/LexiconRegistry.js";
-export type { ValidationResult } from "./repository/LexiconRegistry.js";
-
-export { HYPERCERT_LEXICONS, HYPERCERT_COLLECTIONS } from "@hypercerts-org/lexicon";

package/src/repository/BlobOperationsImpl.ts

@@ -1,199 +0,0 @@
-/**
- * BlobOperationsImpl - Blob upload and retrieval operations.
- *
- * This module provides the implementation for AT Protocol blob operations,
- * handling binary data like images and files.
- *
- * @packageDocumentation
- */
-
-import type { Agent } from "@atproto/api";
-import { NetworkError } from "../core/errors.js";
-import type { BlobOperations } from "./interfaces.js";
-
-/**
- * Implementation of blob operations for binary data handling.
- *
- * Blobs in AT Protocol are content-addressed binary objects stored
- * separately from records. They are referenced in records using a
- * blob reference object with a CID ($link).
- *
- * @remarks
- * This class is typically not instantiated directly. Access it through
- * {@link Repository.blobs}.
- *
- * **Blob Size Limits**: PDS servers typically impose size limits on blobs.
- * Common limits are:
- * - Images: 1MB
- * - Other files: Varies by server configuration
- *
- * **Supported MIME Types**: Any MIME type is technically supported, but
- * servers may reject certain types. Images (JPEG, PNG, GIF, WebP) are
- * universally supported.
- *
- * @example
- * ```typescript
- * // Upload an image blob
- * 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: "Check out this image!",
- *     image: ref,  // { $link: "bafyrei..." }
- *     createdAt: new Date().toISOString(),
- *   },
- * });
- * ```
- *
- * @internal
- */
-export class BlobOperationsImpl implements BlobOperations {
-  /**
-   * Creates a new BlobOperationsImpl.
-   *
-   * @param agent - AT Protocol Agent for making API calls
-   * @param repoDid - DID of the repository (used for blob retrieval)
-   * @param _serverUrl - Server URL (reserved for future use)
-   *
-   * @internal
-   */
-  constructor(
-    private agent: Agent,
-    private repoDid: string,
-    private _serverUrl: string,
-  ) {}
-
-  /**
-   * Uploads a blob to the server.
-   *
-   * @param blob - The blob to upload (File or Blob object)
-   * @returns Promise resolving to blob reference and metadata
-   * @throws {@link NetworkError} if the upload fails
-   *
-   * @remarks
-   * The returned `ref` object should be used directly in records to
-   * reference the blob. The `$link` property contains the blob's CID.
-   *
-   * **MIME Type Detection**: If the blob has no type, it defaults to
-   * `application/octet-stream`. For best results, always specify the
-   * correct MIME type when creating the Blob.
-   *
-   * @example Uploading an image
-   * ```typescript
-   * // From a File input
-   * const file = fileInput.files[0];
-   * const { ref } = await repo.blobs.upload(file);
-   *
-   * // From raw data
-   * const imageBlob = new Blob([uint8Array], { type: "image/png" });
-   * const { ref, mimeType, size } = await repo.blobs.upload(imageBlob);
-   *
-   * console.log(`Uploaded ${size} bytes of ${mimeType}`);
-   * console.log(`CID: ${ref.$link}`);
-   * ```
-   *
-   * @example Using in a hypercert
-   * ```typescript
-   * const coverImage = new Blob([imageData], { type: "image/jpeg" });
-   * const { ref } = await repo.blobs.upload(coverImage);
-   *
-   * // The ref is used directly in the record
-   * await repo.hypercerts.create({
-   *   title: "My Hypercert",
-   *   // ... other fields
-   *   image: coverImage,  // HypercertOperations handles upload internally
-   * });
-   * ```
-   */
-  async upload(blob: Blob): Promise<{ ref: { $link: string }; mimeType: string; size: number }> {
-    try {
-      const arrayBuffer = await blob.arrayBuffer();
-      const uint8Array = new Uint8Array(arrayBuffer);
-
-      const result = await this.agent.com.atproto.repo.uploadBlob(uint8Array, {
-        encoding: blob.type || "application/octet-stream",
-      });
-
-      if (!result.success) {
-        throw new NetworkError("Failed to upload blob");
-      }
-
-      return {
-        ref: { $link: result.data.blob.ref.toString() },
-        mimeType: result.data.blob.mimeType,
-        size: result.data.blob.size,
-      };
-    } catch (error) {
-      if (error instanceof NetworkError) throw error;
-      throw new NetworkError(
-        `Failed to upload blob: ${error instanceof Error ? error.message : "Unknown error"}`,
-        error,
-      );
-    }
-  }
-
-  /**
-   * Retrieves a blob by its CID.
-   *
-   * @param cid - Content Identifier (CID) of the blob, typically from a blob
-   *              reference's `$link` property
-   * @returns Promise resolving to blob data and MIME type
-   * @throws {@link NetworkError} if the blob is not found or retrieval fails
-   *
-   * @remarks
-   * The returned data is a Uint8Array which can be converted to other
-   * formats as needed (Blob, ArrayBuffer, Base64, etc.).
-   *
-   * **MIME Type**: The returned MIME type comes from the Content-Type header.
-   * If the server doesn't provide one, it defaults to `application/octet-stream`.
-   *
-   * @example Basic retrieval
-   * ```typescript
-   * // Get a blob from a record's blob reference
-   * const record = await repo.records.get({ collection, rkey });
-   * const blobRef = (record.value as any).image;
-   *
-   * const { data, mimeType } = await repo.blobs.get(blobRef.$link);
-   *
-   * // Convert to a Blob for use in the browser
-   * const blob = new Blob([data], { type: mimeType });
-   * const url = URL.createObjectURL(blob);
-   * ```
-   *
-   * @example Displaying an image
-   * ```typescript
-   * const { data, mimeType } = await repo.blobs.get(imageCid);
-   *
-   * // Create data URL for <img> src
-   * const base64 = btoa(String.fromCharCode(...data));
-   * const dataUrl = `data:${mimeType};base64,${base64}`;
-   *
-   * // Or use object URL
-   * const blob = new Blob([data], { type: mimeType });
-   * img.src = URL.createObjectURL(blob);
-   * ```
-   */
-  async get(cid: string): Promise<{ data: Uint8Array; mimeType: string }> {
-    try {
-      const result = await this.agent.com.atproto.sync.getBlob({
-        did: this.repoDid,
-        cid,
-      });
-
-      if (!result.success) {
-        throw new NetworkError("Failed to get blob");
-      }
-
-      return {
-        data: result.data,
-        mimeType: result.headers["content-type"] || "application/octet-stream",
-      };
-    } catch (error) {
-      if (error instanceof NetworkError) throw error;
-      throw new NetworkError(`Failed to get blob: ${error instanceof Error ? error.message : "Unknown error"}`, error);
-    }
-  }
-}