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

package/src/core/types.ts

@@ -0,0 +1,281 @@
+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
+   * - `"collaborator"`: User was invited to collaborate
+   */
+  accessType: z.enum(["owner", "collaborator"]),
+});
+
+/**
+ * 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

@@ -0,0 +1,57 @@
+/**
+ * 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

@@ -0,0 +1,107 @@
+/**
+ * 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

@@ -0,0 +1,64 @@
+/**
+ * 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

@@ -0,0 +1,199 @@
+/**
+ * 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: result.data.blob.ref,
+        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);
+    }
+  }
+}