@hypercerts-org/sdk-core 0.10.0-beta.8 → 0.10.0-beta.9

package/dist/index.cjs

@@ -4,9 +4,52 @@ var oauthClientNode = require('@atproto/oauth-client-node');
 var zod = require('zod');
 var api = require('@atproto/api');
 var lexicon$1 = require('@atproto/lexicon');
+var cid = require('multiformats/cid');
 var lexicon = require('@hypercerts-org/lexicon');
 var eventemitter3 = require('eventemitter3');
 
+/**
+ * Regular expression to match a valid URI with a scheme.
+ *
+ * Matches strings that start with a scheme (one or more alphanumeric characters,
+ * plus, period, or hyphen) followed by a colon. This covers schemes that the
+ * native URL constructor may not support (e.g., `at://`, `ipfs://`).
+ *
+ * @see https://www.rfc-editor.org/rfc/rfc3986#section-3.1
+ * @internal
+ */
+const URI_SCHEME_REGEX = /^[a-zA-Z][a-zA-Z0-9+\-.]*:/;
+/**
+ * Check if a string is a valid URI with a scheme.
+ *
+ * Validates that the string is a properly formatted URI. Uses the native
+ * `URL` constructor for standard schemes (http, https, ftp, etc.) and falls
+ * back to scheme detection for non-standard schemes like `at://` and `ipfs://`
+ * that the `URL` constructor does not support.
+ *
+ * @param uri - The string to validate
+ * @returns True if the string is a valid URI with a scheme, false otherwise
+ *
+ * @example
+ * ```typescript
+ * isValidUri("https://example.com/report.pdf"); // true
+ * isValidUri("ipfs://QmYwAPJzv5CZsnA625s3Xf2nemtYgPpHdWEz79ojWnPbdG"); // true
+ * isValidUri("at://did:plc:abc/org.col/rkey"); // true
+ * isValidUri("not-a-uri"); // false
+ * isValidUri(""); // false
+ * ```
+ */
+function isValidUri(uri) {
+    if (!uri)
+        return false;
+    try {
+        new URL(uri);
+        return true;
+    }
+    catch {
+        return URI_SCHEME_REGEX.test(uri);
+    }
+}
 /**
  * Type guard to check if a URL is a loopback address.
  *
@@ -1642,7 +1685,7 @@ function validateScope(scope) {
     const permissions = parseScope(scope);
     const invalidPermissions = [];
     // Pattern for valid permission prefixes
-    const validPrefixes = /^(atproto|transition:|account:|repo:|blob:?|rpc:|identity:|include:)/;
+    const validPrefixes = /^(atproto$|transition:|account:|repo[:?]|blob[:?]|rpc[:?]|identity:|include:)/;
     for (const permission of permissions) {
         if (!validPrefixes.test(permission)) {
             invalidPermissions.push(permission);
@@ -1686,7 +1729,7 @@ function validateScope(scope) {
  *     jwksUri: "https://my-app.com/.well-known/jwks.json",
  *     jwkPrivate: process.env.JWK_PRIVATE_KEY!,
  *   },
- *   servers: { pds: "https://bsky.social" },
+ *   handleResolver: "https://pds-eu-west4.test.certified.app",
  * });
  *
  * // Start authorization
@@ -1756,7 +1799,7 @@ class OAuthClient {
             keyset,
             stateStore: this.createStateStoreAdapter(stateStore),
             sessionStore: this.createSessionStoreAdapter(sessionStore),
-            handleResolver: this.config.servers?.pds,
+            handleResolver: this.config.handleResolver,
             fetch: this.config.fetch ?? fetchWithTimeout,
         });
         return this.client;
@@ -2878,6 +2921,148 @@ class RecordOperationsImpl {
     }
 }
 
+/**
+ * Validates that a string is a valid DID format.
+ *
+ * DIDs must follow the format: `did:<method>:<method-specific-id>`
+ * where method is lowercase letters and digits, and the identifier contains
+ * alphanumeric characters plus `.`, `_`, `:`, `%`, and `-`.
+ *
+ * @param did - The string to validate
+ * @returns true if the string is a valid DID format
+ *
+ * @example
+ * ```typescript
+ * isValidDid("did:plc:ewvi7nxzyoun6zhxrhs64oiz"); // true
+ * isValidDid("did:web:example.com"); // true
+ * isValidDid("not-a-did"); // false
+ * isValidDid("did:"); // false
+ * ```
+ *
+ * @see https://www.w3.org/TR/did-core/#did-syntax for DID syntax specification
+ */
+function isValidDid(did) {
+    // DID format: did:<method>:<method-specific-id>
+    // Method: lowercase letters and digits (per W3C DID Core spec)
+    // Identifier: alphanumeric plus . _ : % -
+    // method-specific-id must end with at least one non-colon idchar (W3C DID Core 1.0)
+    return /^did:[a-z0-9]+:(?:[a-zA-Z0-9._%-]+:)*[a-zA-Z0-9._%-]+$/.test(did);
+}
+/**
+ * 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.
+ */
+const CollaboratorPermissionsSchema = zod.z.object({
+    /**
+     * Can read/view records in the repository.
+     * This is the most basic permission level.
+     */
+    read: zod.z.boolean(),
+    /**
+     * Can create new records in the repository.
+     * Typically implies `read` permission.
+     */
+    create: zod.z.boolean(),
+    /**
+     * Can modify existing records in the repository.
+     * Typically implies `read` and `create` permissions.
+     */
+    update: zod.z.boolean(),
+    /**
+     * Can delete records from the repository.
+     * Typically implies `read`, `create`, and `update` permissions.
+     */
+    delete: zod.z.boolean(),
+    /**
+     * Can manage collaborators and their permissions.
+     * Administrative permission that allows inviting/removing collaborators.
+     */
+    admin: zod.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: zod.z.boolean(),
+});
+/**
+ * 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.
+ */
+const OrganizationSchema = zod.z.object({
+    /**
+     * The organization's DID - unique identifier.
+     * Format: "did:plc:..." or "did:web:..."
+     */
+    did: zod.z.string(),
+    /**
+     * The organization's handle - human-readable identifier.
+     * Format: "orgname.sds.hypercerts.org" or similar
+     */
+    handle: zod.z.string(),
+    /**
+     * Display name for the organization.
+     */
+    name: zod.z.string(),
+    /**
+     * Optional description of the organization's purpose.
+     */
+    description: zod.z.string().optional(),
+    /**
+     * ISO 8601 timestamp when the organization was created.
+     * Format: "2024-01-15T10:30:00.000Z"
+     */
+    createdAt: zod.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: zod.z.enum(["owner", "shared", "none"]),
+});
+/**
+ * Zod schema for collaborator data.
+ *
+ * Represents a user who has been granted access to a shared repository
+ * or organization with specific permissions.
+ */
+const CollaboratorSchema = zod.z.object({
+    /**
+     * The collaborator's DID - their unique identifier.
+     * Format: "did:plc:..." or "did:web:..."
+     */
+    userDid: zod.z.string(),
+    /**
+     * The permissions granted to this collaborator.
+     */
+    permissions: CollaboratorPermissionsSchema,
+    /**
+     * DID of the user who granted these permissions.
+     * Useful for audit trails.
+     */
+    grantedBy: zod.z.string(),
+    /**
+     * ISO 8601 timestamp when permissions were granted.
+     * Format: "2024-01-15T10:30:00.000Z"
+     */
+    grantedAt: zod.z.string(),
+    /**
+     * ISO 8601 timestamp when permissions were revoked, if applicable.
+     * Undefined if the collaborator is still active.
+     */
+    revokedAt: zod.z.string().optional(),
+});
+
 /**
  * BlobOperationsImpl - Blob upload and retrieval operations.
  *
@@ -2941,6 +3126,9 @@ class BlobOperationsImpl {
         this.repoDid = repoDid;
         this._serverUrl = _serverUrl;
         this.isSDS = isSDS;
+        if (!isValidDid(repoDid)) {
+            throw new ValidationError(`Invalid DID format: "${repoDid}". DIDs must start with "did:" (e.g., "did:plc:abc123")`);
+        }
     }
     /**
      * Uploads a blob to the server.
@@ -3000,11 +3188,7 @@ class BlobOperationsImpl {
             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,
-            };
+            return result.data.blob;
         }
         catch (error) {
             if (error instanceof NetworkError)
@@ -3038,13 +3222,18 @@ class BlobOperationsImpl {
         if (!response.ok) {
             throw new NetworkError(`SDS blob upload failed: ${response.statusText}`);
         }
+        // SDS returns { blob: { ref: { $link: string }, mimeType: string, size: number } }
+        // which is a JSON-serialized blob ref, not a BlobRef instance.
+        // Construct a BlobRef directly using CID.parse to preserve the size from the SDS response.
         const result = (await response.json());
-        const ref = typeof result.blob.ref === "string" ? result.blob.ref : result.blob.ref.$link;
-        return {
-            ref: { $link: ref },
-            mimeType: result.blob.mimeType,
-            size: result.blob.size,
-        };
+        let cid$1;
+        try {
+            cid$1 = cid.CID.parse(result.blob.ref.$link);
+        }
+        catch {
+            throw new NetworkError("SDS blob upload returned an invalid blob reference");
+        }
+        return new lexicon$1.BlobRef(cid$1, result.blob.mimeType, result.blob.size);
     }
     /**
      * Retrieves a blob by its CID.
@@ -3110,556 +3299,1125 @@ class BlobOperationsImpl {
 }
 
 /**
- * Repository types - Shared types for repository operations
- * @packageDocumentation
- */
-/**
- * Converts a blob upload result to JsonBlobRef format.
+ * Lexicons entrypoint - Lexicon definitions and registry.
  *
- * AT Protocol requires blob fields to include the full structure:
- * `{ $type: "blob", ref: { $link }, mimeType, size }`
+ * This sub-entrypoint exports the lexicon registry and hypercert
+ * lexicon constants for working with AT Protocol record schemas.
  *
- * @param uploadResult - Result from BlobOperations.upload()
- * @returns JsonBlobRef formatted for records
- */
-function uploadResultToBlobRef(uploadResult) {
-    return {
-        $type: "blob",
-        ref: uploadResult.ref,
-        mimeType: uploadResult.mimeType,
-        size: uploadResult.size,
-    };
-}
-
-/**
- * ProfileOperationsImpl - User profile operations.
+ * @remarks
+ * Import from `@hypercerts-org/sdk/lexicons`:
  *
- * This module provides the implementation for AT Protocol profile
- * management, including fetching and updating user profiles.
+ * ```typescript
+ * import {
+ *   LexiconRegistry,
+ *   HYPERCERT_LEXICONS,
+ *   HYPERCERT_COLLECTIONS,
+ * } from "@hypercerts-org/sdk/lexicons";
+ * ```
  *
- * @packageDocumentation
- */
-/**
- * Implementation of profile operations for user profile management.
+ * **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
  *
- * Profiles in AT Protocol are stored as records in the `app.bsky.actor.profile`
- * collection with the special rkey "self". This class provides a convenient
- * API for reading and updating profile data.
+ * @example Using collection constants
+ * ```typescript
+ * import { HYPERCERT_COLLECTIONS } from "@hypercerts-org/sdk/lexicons";
  *
- * @remarks
- * This class is typically not instantiated directly. Access it through
- * {@link Repository.profile}.
+ * // List hypercerts using the correct collection name
+ * const records = await repo.records.list({
+ *   collection: HYPERCERT_COLLECTIONS.RECORD,
+ * });
  *
- * **Profile Fields**:
- * - `handle`: Read-only, managed by the PDS
- * - `displayName`: User's display name (max 64 chars typically)
- * - `description`: Profile bio (max 256 chars typically)
- * - `avatar`: Profile picture blob reference
- * - `banner`: Banner image blob reference
- * - `website`: User's website URL (may not be available on all servers)
+ * // List contributions
+ * const contributions = await repo.records.list({
+ *   collection: HYPERCERT_COLLECTIONS.CONTRIBUTION,
+ * });
+ * ```
  *
- * @example
+ * @example Custom lexicon registration
  * ```typescript
- * // Get profile
- * const profile = await repo.profile.get();
- * console.log(`${profile.displayName} (@${profile.handle})`);
- *
- * // Update profile
- * await repo.profile.update({
- *   displayName: "New Name",
- *   description: "Updated bio",
- * });
+ * import { LexiconRegistry } from "@hypercerts-org/sdk/lexicons";
+ *
+ * const registry = sdk.getLexiconRegistry();
  *
- * // Update with new avatar
- * const avatarBlob = new Blob([imageData], { type: "image/png" });
- * await repo.profile.update({ avatar: avatarBlob });
+ * // Register custom lexicon
+ * registry.register({
+ *   lexicon: 1,
+ *   id: "org.myapp.customRecord",
+ *   defs: { ... },
+ * });
  *
- * // Remove a field
- * await repo.profile.update({ website: null });
+ * // Validate a record
+ * const result = registry.validate("org.myapp.customRecord", record);
+ * if (!result.valid) {
+ *   console.error(result.error);
+ * }
  * ```
  *
- * @internal
+ * @packageDocumentation
  */
-class ProfileOperationsImpl {
+/**
+ * All hypercert-related lexicons for registration with AT Protocol Agent.
+ * This array contains all lexicon documents from the published package.
+ */
+const HYPERCERT_LEXICONS = [
+    lexicon.CERTIFIED_DEFS_LEXICON_JSON,
+    lexicon.LOCATION_LEXICON_JSON,
+    lexicon.STRONG_REF_LEXICON_JSON,
+    lexicon.HYPERCERTS_DEFS_LEXICON_JSON,
+    lexicon.ACTIVITY_LEXICON_JSON,
+    lexicon.COLLECTION_LEXICON_JSON,
+    lexicon.CONTRIBUTION_DETAILS_LEXICON_JSON,
+    lexicon.CONTRIBUTOR_INFORMATION_LEXICON_JSON,
+    lexicon.EVALUATION_LEXICON_JSON,
+    lexicon.ATTACHMENT_LEXICON_JSON,
+    lexicon.MEASUREMENT_LEXICON_JSON,
+    lexicon.RIGHTS_LEXICON_JSON,
+    lexicon.ACTOR_PROFILE_LEXICON_JSON,
+    lexicon.BADGE_AWARD_LEXICON_JSON,
+    lexicon.BADGE_DEFINITION_LEXICON_JSON,
+    lexicon.BADGE_RESPONSE_LEXICON_JSON,
+    lexicon.FUNDING_RECEIPT_LEXICON_JSON,
+    lexicon.WORK_SCOPE_TAG_LEXICON_JSON,
+];
+/**
+ * Collection NSIDs (Namespaced Identifiers) for hypercert records.
+ *
+ * Use these constants when performing record operations to ensure
+ * correct collection names.
+ */
+const HYPERCERT_COLLECTIONS = {
     /**
-     * Creates a new ProfileOperationsImpl.
-     *
-     * @param agent - AT Protocol Agent for making API calls
-     * @param repoDid - DID of the repository/user
-     * @param blobs - Blob operations for uploading images
-     *
-     * @internal
+     * Main hypercert claim record collection.
      */
-    constructor(agent, repoDid, blobs) {
+    CLAIM: lexicon.ACTIVITY_NSID,
+    /**
+     * Rights record collection.
+     */
+    RIGHTS: lexicon.RIGHTS_NSID,
+    /**
+     * Location record collection (shared certified lexicon).
+     */
+    LOCATION: lexicon.LOCATION_NSID,
+    /**
+     * Contribution details record collection.
+     * For storing details about a specific contribution (role, description, timeframe).
+     */
+    CONTRIBUTION_DETAILS: lexicon.CONTRIBUTION_DETAILS_NSID,
+    /**
+     * Contributor information record collection.
+     * For storing contributor profile information (identifier, displayName, image).
+     */
+    CONTRIBUTOR_INFORMATION: lexicon.CONTRIBUTOR_INFORMATION_NSID,
+    /**
+     * Measurement record collection.
+     */
+    MEASUREMENT: lexicon.MEASUREMENT_NSID,
+    /**
+     * Evaluation record collection.
+     */
+    EVALUATION: lexicon.EVALUATION_NSID,
+    /**
+     * Attachment record collection.
+     */
+    ATTACHMENT: lexicon.ATTACHMENT_NSID,
+    /**
+     * Collection record collection (groups of hypercerts).
+     * Projects are now collections with type='project'.
+     */
+    COLLECTION: lexicon.COLLECTION_NSID,
+    /**
+     * Badge award record collection.
+     */
+    BADGE_AWARD: lexicon.BADGE_AWARD_NSID,
+    /**
+     * Badge definition record collection.
+     */
+    BADGE_DEFINITION: lexicon.BADGE_DEFINITION_NSID,
+    /**
+     * Badge response record collection.
+     */
+    BADGE_RESPONSE: lexicon.BADGE_RESPONSE_NSID,
+    /**
+     * Funding receipt record collection.
+     */
+    FUNDING_RECEIPT: lexicon.FUNDING_RECEIPT_NSID,
+    /**
+     * Work scope tag record collection.
+     * For defining reusable work scope atoms.
+     */
+    WORK_SCOPE_TAG: lexicon.WORK_SCOPE_TAG_NSID,
+    /**
+     * Bluesky profile collection (app.bsky.actor.profile).
+     */
+    BSKY_PROFILE: "app.bsky.actor.profile",
+    /**
+     * Certified profile collection (app.certified.actor.profile).
+     */
+    CERTIFIED_PROFILE: lexicon.ACTOR_PROFILE_NSID,
+};
+
+/**
+ * Blob URL Utilities
+ *
+ * Utilities for constructing AT Protocol blob URLs and extracting image references
+ * from Hypercert image records.
+ *
+ * @remarks
+ *
+ * ## Why these utilities exist
+ *
+ * AT Protocol stores blobs (images, videos, etc.) on PDS servers and returns blob objects
+ * containing a CID (Content Identifier) and mimetype. To make it easier for SDK users to
+ * consume these blobs, we provide utilities to:
+ *
+ * 1. **Convert blob references to URLs**: Transform CID + DID + PDS into a direct URL
+ * 2. **Extract image references**: Handle both blob-based images (CID) and direct URIs
+ *
+ * This allows users to consume images directly without manual URL construction:
+ * This can and will be reused across any response that has to return a blob.
+ *
+ *
+ * @packageDocumentation
+ */
+/**
+ * Constructs a URL for retrieving a blob from an AT Protocol server.
+ *
+ * @param pdsUrl - The PDS/server base URL (e.g., "https://pds1.certified.app")
+ * @param did - The DID of the repository owner
+ * @param cid - The Content Identifier (CID) of the blob
+ * @returns Full blob URL
+ *
+ * @throws {Error} If any parameter is empty or invalid
+ *
+ * @example
+ * ```typescript
+ * const url = getBlobUrl(
+ *   "https://pds1.certified.app",
+ *   "did:plc:r5p2aletd4fegsklphgiog3s",
+ *   "bafkreieie3unmfnzt6j7w2y3zkkcjhisvjtg3au5myonvpuyel6ecau52q"
+ * );
+ * // Returns: "https://pds1.certified.app/xrpc/com.atproto.sync.getBlob?did=did:plc:r5p2aletd4fegsklphgiog3s&cid=bafkreieie3unmfnzt6j7w2y3zkkcjhisvjtg3au5myonvpuyel6ecau52q"
+ * ```
+ *
+ * @public
+ */
+function getBlobUrl(pdsUrl, did, cid) {
+    if (!pdsUrl || typeof pdsUrl !== "string") {
+        throw new Error("pdsUrl must be a non-empty string");
+    }
+    if (!did || typeof did !== "string") {
+        throw new Error("did must be a non-empty string");
+    }
+    if (!cid || typeof cid !== "string") {
+        throw new Error("cid must be a non-empty string");
+    }
+    const normalizedPdsUrl = pdsUrl.replace(/\/$/, "");
+    return `${normalizedPdsUrl}/xrpc/com.atproto.sync.getBlob?did=${did}&cid=${cid}`;
+}
+/**
+ * Extracts the CID or URI from a Hypercert image record.
+ *
+ * Handles all Hypercert image formats:
+ * - `smallImage`: Avatar/thumbnail format with blob reference - returns CID
+ * - `largeImage`: Banner/cover format with blob reference - returns CID
+ * - `uri`: Direct URL - returns the URI string
+ *
+ * @param image - Hypercert image record
+ * @returns CID string if image contains a blob reference, URI string if uri format, undefined otherwise
+ *
+ * @example Blob format
+ * ```typescript
+ * const smallImage = {
+ *   $type: "org.hypercerts.defs#smallImage",
+ *   image: {
+ *     $type: "blob",
+ *     ref: { $link: "bafyrei123" },
+ *     mimeType: "image/png",
+ *     size: 1000
+ *   }
+ * };
+ *
+ * const cid = extractCidFromImage(smallImage);
+ * // Returns: "bafyrei123"
+ * ```
+ *
+ * @example URI format
+ * ```typescript
+ * const uriImage = {
+ *   $type: "org.hypercerts.defs#uri",
+ *   uri: "https://example.com/image.jpg"
+ * };
+ *
+ * const uri = extractCidFromImage(uriImage);
+ * // Returns: "https://example.com/image.jpg"
+ * ```
+ *
+ * @public
+ */
+function extractCidFromImage(image) {
+    if (!image || typeof image !== "object") {
+        return undefined;
+    }
+    // Check $type to determine format
+    const imageType = image.$type;
+    // If it's a URI format, return the URI string directly
+    if (imageType === "org.hypercerts.defs#uri") {
+        const uri = image.uri;
+        if (uri && typeof uri === "string") {
+            return uri;
+        }
+        return undefined;
+    }
+    if (imageType === "org.hypercerts.defs#smallImage" || imageType === "org.hypercerts.defs#largeImage") {
+        // Blob format: image.image.ref.$link
+        const imageData = image.image;
+        if (imageData && typeof imageData === "object") {
+            const ref = imageData.ref;
+            if (ref) {
+                return ref.toString();
+            }
+        }
+    }
+    return undefined;
+}
+
+/**
+ * ProfileOperationsImpl - User profile operations supporting dual profiles.
+ *
+ * This module provides operations for managing AT Protocol profiles:
+ * - Bluesky profiles (app.bsky.actor.profile) - Simple profiles with CDN images
+ * - Certified profiles (app.certified.actor.profile) - Hypercerts profiles with pronouns/website
+ *
+ * @packageDocumentation
+ */
+const BSKY_PROFILE_NSID = HYPERCERT_COLLECTIONS.BSKY_PROFILE;
+const CERTIFIED_PROFILE_NSID = HYPERCERT_COLLECTIONS.CERTIFIED_PROFILE;
+/** Profile record key (always "self" for the user's own profile) */
+const PROFILE_RKEY = "self";
+/**
+ * Implementation of profile operations supporting dual profiles.
+ *
+ * This class provides operations for both Bluesky and Certified profiles:
+ * - Bluesky profiles: Simple AT Protocol profiles with avatar/banner as CDN URLs
+ * - Certified profiles: Hypercerts profiles hypercerts image format
+ *
+ * @remarks
+ * This class is typically not instantiated directly. Access it through
+ * {@link Repository.profile}.
+ *
+ * **Profile Types**:
+ * - `app.bsky.actor.profile`: Standard Bluesky profile, images are simple blob refs
+ * - `app.certified.actor.profile`: Hypercerts profile, images wrapped in smallImage/largeImage. Omits some bsky profile properties like pinnedPost labels etc
+ *
+ * @example
+ * ```typescript
+ * // Get Bluesky profile
+ * const bskyProfile = await repo.profile.getBskyProfile();
+ * console.log(bskyProfile.displayName);
+ * console.log(bskyProfile.avatar); // CDN URL
+ *
+ * // Get Certified profile
+ * const certifiedProfile = await repo.profile.getCertifiedProfile();
+ * console.log(certifiedProfile.pronouns); // "she/her"
+ * console.log(certifiedProfile.avatar); // Blob URL
+ *
+ * // Create/update profiles
+ * await repo.profile.createBskyProfile({ displayName: "Alice" });
+ * await repo.profile.updateBskyProfile({ description: "New bio" });
+ *
+ * await repo.profile.createCertifiedProfile({
+ *   displayName: "Alice",
+ *   pronouns: "she/her",
+ * });
+ * ```
+ *
+ * @internal
+ */
+class ProfileOperationsImpl {
+    /**
+     * Creates a new ProfileOperationsImpl.
+     *
+     * @param agent - AT Protocol Agent for making API calls
+     * @param repoDid - DID of the repository/user
+     * @param blobs - Blob operations for uploading images
+     * @param pdsUrl - PDS URL for constructing blob URLs
+     *
+     * @internal
+     */
+    constructor(agent, repoDid, blobs, pdsUrl) {
         this.agent = agent;
         this.repoDid = repoDid;
         this.blobs = blobs;
+        this.pdsUrl = pdsUrl;
     }
     /**
-     * Applies a simple field (string or null) to the profile.
+     * Converts a Hypercert image record to a URL string.
+     *
+     * - URI format: returns the URI string directly
+     * - Blob format (smallImage/largeImage): constructs blob URL using PDS
+     *
+     * @param image - Hypercert image record
+     * @returns URL string
+     * @throws {Error} If image format is invalid or blob CID cannot be extracted
      *
      * @internal
      */
-    applySimpleField(result, field, value) {
-        if (value === undefined)
-            return;
-        if (value === null) {
-            delete result[field];
+    imageToUrl(image) {
+        const result = extractCidFromImage(image);
+        if (!result) {
+            throw new Error("Unable to extract CID or URI from image record");
         }
-        else {
-            result[field] = value;
+        if (isValidUri(result)) {
+            return result;
         }
+        // Otherwise, it's a CID - construct blob URL
+        return getBlobUrl(this.pdsUrl, this.repoDid, result);
     }
     /**
-     * Applies a blob field to the profile, uploading if needed.
+     * Applies an image field (avatar/banner) with format-specific wrapping.
+     *
+     * - null: removes the field
+     * - undefined: no change
+     * - Blob: uploads and wraps according to collection format
+     *
+     * @param result - The profile record being built
+     * @param field - Field name ("avatar" or "banner")
+     * @param value - Blob to upload, null to remove, or undefined to skip
+     * @param collection - Profile collection NSID (determines image wrapping format)
      *
      * @internal
      */
-    async applyBlobField(result, field, blob) {
-        if (blob === undefined)
+    async applyImageField(result, field, value, collection) {
+        if (value === undefined)
             return;
-        if (blob === null) {
+        if (value === null) {
             delete result[field];
+            return;
+        }
+        const blobRef = await this.blobs.upload(value);
+        // Bsky profiles use simple blob refs, Certified profiles wrap in smallImage/largeImage
+        if (collection === BSKY_PROFILE_NSID) {
+            result[field] = blobRef;
         }
         else {
-            const uploadResult = await this.blobs.upload(blob);
-            result[field] = uploadResultToBlobRef(uploadResult);
+            const isLargeImage = field === "banner";
+            result[field] = {
+                $type: isLargeImage ? "org.hypercerts.defs#largeImage" : "org.hypercerts.defs#smallImage",
+                image: blobRef,
+            };
         }
     }
     /**
-     * Applies profile params to a profile record, handling null values for deletion.
-     *
-     * Ensures $type and createdAt are always present on the record, using
-     * nullish coalescing to allow callers to override defaults.
+     * Validates a profile record against the appropriate lexicon schema.
      *
+     * @param profile - The profile record to validate
+     * @param collection - Profile collection NSID (determines validation schema)
+     * @throws {ValidationError} If validation fails
      * @internal
      */
-    async mergeParamsIntoProfile(profile, params) {
-        const result = { ...profile };
-        // Ensure $type and createdAt are always present
-        result.$type = params.$type ?? result.$type ?? "app.bsky.actor.profile";
-        result.createdAt = params.createdAt ?? result.createdAt ?? new Date().toISOString();
-        this.applySimpleField(result, "displayName", params.displayName);
-        this.applySimpleField(result, "description", params.description);
-        this.applySimpleField(result, "website", params.website);
-        await this.applyBlobField(result, "avatar", params.avatar);
-        await this.applyBlobField(result, "banner", params.banner);
-        return result;
-    }
-    /**
-     * Gets the repository's profile.
-     *
-     * @returns Promise resolving to profile data
-     * @throws {@link NetworkError} if the profile cannot be fetched
-     *
-     * @remarks
-     * This method fetches the full profile using the `getProfile` API,
-     * which includes resolved information like follower counts on some
-     * servers. For hypercerts SDK usage, the basic profile fields are
-     * returned.
-     *
-     * **Note**: The `website` field may not be available on all AT Protocol
-     * servers. Standard Bluesky profiles don't include this field.
-     *
-     * @example
-     * ```typescript
-     * const profile = await repo.profile.get();
-     *
-     * console.log(`Handle: @${profile.handle}`);
-     * console.log(`Name: ${profile.displayName || "(not set)"}`);
-     * console.log(`Bio: ${profile.description || "(no bio)"}`);
-     *
-     * if (profile.avatar) {
-     *   // Avatar is a URL or blob reference
-     *   console.log(`Avatar: ${profile.avatar}`);
-     * }
-     * ```
-     */
-    async get() {
-        try {
-            const result = await this.agent.getProfile({ actor: this.repoDid });
-            if (!result.success) {
-                throw new NetworkError("Failed to get profile");
+    validateProfileRecord(profile, collection) {
+        if (collection === CERTIFIED_PROFILE_NSID) {
+            const validation = lexicon.validate(profile, CERTIFIED_PROFILE_NSID, "main", false);
+            if (!validation.success) {
+                throw new ValidationError(`Invalid profile record: ${validation.error?.message}`);
             }
-            return {
-                handle: result.data.handle,
-                displayName: result.data.displayName,
-                description: result.data.description,
-                avatar: result.data.avatar,
-                banner: result.data.banner,
-                // Note: website may not be available in standard profile
-            };
         }
-        catch (error) {
-            if (error instanceof NetworkError)
-                throw error;
-            throw new NetworkError(`Failed to get profile: ${error instanceof Error ? error.message : "Unknown error"}`, error);
+        if (collection === BSKY_PROFILE_NSID) {
+            const validation = api.AppBskyActorProfile.validateMain(profile);
+            if (!validation.success) {
+                throw new ValidationError(`Invalid profile record: ${validation.error?.message}`);
+            }
         }
     }
     /**
-     * Creates a new profile for the repository.
+     * Creates a profile record with lexicon validation.
      *
-     * @param params - Profile fields to set
+     * @param collection - NSID of the collection (Bsky or Certified profile)
+     * @param params - Profile creation parameters
      * @returns Promise resolving to create result with URI and CID
-     * @throws {@link NetworkError} if the creation fails
-     *
-     * @remarks
-     * Use this method when no profile exists yet. If a profile already exists,
-     * use {@link update} instead.
-     *
-     * **Image Handling**: When providing `avatar` or `banner` as a Blob,
-     * the image is automatically uploaded and the blob reference is stored
-     * in the profile.
-     *
-     * @example Create a basic profile
-     * ```typescript
-     * await repo.profile.create({
-     *   displayName: "Alice",
-     *   description: "Building impact certificates",
-     * });
-     * ```
-     *
-     * @example Create a profile with avatar
-     * ```typescript
-     * const avatarBlob = new Blob([avatarData], { type: "image/png" });
-     * await repo.profile.create({
-     *   displayName: "Alice",
-     *   description: "Building impact certificates",
-     *   avatar: avatarBlob,
-     * });
-     * ```
+     * @throws {ValidationError} if validation fails
+     * @throws {NetworkError} if creation fails
+     * @internal
      */
-    async create(params) {
+    async createProfileRecord(collection, params) {
         try {
-            const profile = await this.mergeParamsIntoProfile({}, params);
-            const createParams = {
+            const { avatar, banner, $type, createdAt, ...otherFields } = params;
+            const profile = {
+                $type: $type ?? collection,
+                createdAt: createdAt ?? new Date().toISOString(),
+                ...otherFields,
+            };
+            await this.applyImageField(profile, "avatar", avatar, collection);
+            await this.applyImageField(profile, "banner", banner, collection);
+            // Validate profile record against lexicon schema
+            this.validateProfileRecord(profile, collection);
+            const result = await this.agent.com.atproto.repo.createRecord({
                 repo: this.repoDid,
-                collection: "app.bsky.actor.profile",
-                rkey: "self",
+                collection,
+                rkey: PROFILE_RKEY,
                 record: profile,
-            };
-            const result = await this.agent.com.atproto.repo.createRecord(createParams);
+            });
             if (!result.success) {
                 throw new NetworkError("Failed to create profile");
             }
             return { uri: result.data.uri, cid: result.data.cid };
         }
         catch (error) {
-            if (error instanceof NetworkError)
+            if (error instanceof NetworkError || error instanceof ValidationError)
                 throw error;
             throw new NetworkError(`Failed to create profile: ${error instanceof Error ? error.message : "Unknown error"}`, error);
         }
     }
     /**
-     * Updates the repository's profile.
-     *
-     * @param params - Fields to update. Pass `null` to remove a field.
-     *                 Omitted fields are preserved from the existing profile.
-     * @returns Promise resolving to update result with new URI and CID
-     * @throws {@link NetworkError} if the update fails
-     *
-     * @remarks
-     * This method performs a read-modify-write operation:
-     * 1. Fetches the existing profile record
-     * 2. Merges in the provided updates
-     * 3. Writes the updated profile back
-     *
-     * **Image Handling**: When providing `avatar` or `banner` as a Blob,
-     * the image is automatically uploaded and the blob reference is stored
-     * in the profile.
-     *
-     * **Field Removal**: Pass `null` to explicitly remove a field. Omitting
-     * a field (not including it in params) preserves the existing value.
-     *
-     * @example Update display name and bio
-     * ```typescript
-     * await repo.profile.update({
-     *   displayName: "Alice",
-     *   description: "Building impact certificates",
-     * });
-     * ```
-     *
-     * @example Update avatar image
-     * ```typescript
-     * // From a file input
-     * const file = document.getElementById("avatar").files[0];
-     * await repo.profile.update({ avatar: file });
-     *
-     * // From raw data
-     * const response = await fetch("https://example.com/my-avatar.png");
-     * const blob = await response.blob();
-     * await repo.profile.update({ avatar: blob });
-     * ```
-     *
-     * @example Remove description
-     * ```typescript
-     * // Removes the description field entirely
-     * await repo.profile.update({ description: null });
-     * ```
-     *
-     * @example Multiple updates at once
-     * ```typescript
-     * const newAvatar = new Blob([avatarData], { type: "image/png" });
-     * const newBanner = new Blob([bannerData], { type: "image/jpeg" });
+     * Updates a profile record with proper null handling and validation.
      *
-     * await repo.profile.update({
-     *   displayName: "New Name",
-     *   description: "New bio",
-     *   avatar: newAvatar,
-     *   banner: newBanner,
-     * });
-     * ```
+     * @param collection - NSID of the collection (Bsky or Certified profile)
+     * @param params - Profile update parameters (partial, with null for deletions)
+     * @returns Promise resolving to update result with URI and CID
+     * @throws {NetworkError} if profile not found or update fails
+     * @throws {ValidationError} if validation fails
+     * @internal
      */
-    async update(params) {
+    async updateProfileRecord(collection, params) {
         try {
-            // Get existing profile record
-            const getParams = {
+            const existing = await this.agent.com.atproto.repo.getRecord({
                 repo: this.repoDid,
-                collection: "app.bsky.actor.profile",
-                rkey: "self",
-            };
-            const existing = await this.agent.com.atproto.repo.getRecord(getParams);
+                collection,
+                rkey: PROFILE_RKEY,
+            });
             if (!existing.success) {
-                throw new NetworkError("Profile not found. Use create() for new profiles.");
+                throw new NetworkError("Profile not found");
+            }
+            const { avatar, banner, ...otherFields } = params;
+            const updatedProfile = {
+                ...existing.data.value,
+            };
+            // Apply non-image field updates, handling null deletions
+            for (const [key, value] of Object.entries(otherFields)) {
+                if (value === null) {
+                    delete updatedProfile[key];
+                }
+                else if (value !== undefined) {
+                    updatedProfile[key] = value;
+                }
             }
-            const existingProfile = existing.data.value || {};
-            const updatedProfile = await this.mergeParamsIntoProfile(existingProfile, params);
-            const putParams = {
+            await this.applyImageField(updatedProfile, "avatar", avatar, collection);
+            await this.applyImageField(updatedProfile, "banner", banner, collection);
+            // Validate updated record against lexicon schema
+            this.validateProfileRecord(updatedProfile, collection);
+            const result = await this.agent.com.atproto.repo.putRecord({
                 repo: this.repoDid,
-                collection: "app.bsky.actor.profile",
-                rkey: "self",
+                collection,
+                rkey: PROFILE_RKEY,
                 record: updatedProfile,
-            };
-            const result = await this.agent.com.atproto.repo.putRecord(putParams);
+            });
             if (!result.success) {
                 throw new NetworkError("Failed to update profile");
             }
             return { uri: result.data.uri, cid: result.data.cid };
         }
         catch (error) {
-            if (error instanceof NetworkError)
+            if (error instanceof NetworkError || error instanceof ValidationError)
                 throw error;
             throw new NetworkError(`Failed to update profile: ${error instanceof Error ? error.message : "Unknown error"}`, error);
         }
     }
-}
-
-/**
- * Lexicons entrypoint - Lexicon definitions and registry.
+    /**
+     * Upserts a profile record (creates if missing, updates if exists).
+     *
+     * @param collection - NSID of the collection (Bsky or Certified profile)
+     * @param params - Profile fields to set
+     * @returns Promise resolving to update result with URI and CID
+     * @throws {ValidationError} if validation fails
+     * @throws {NetworkError} if operation fails
+     * @internal
+     */
+    async upsertProfileRecord(collection, params) {
+        try {
+            // Check if profile exists
+            const existing = await this.agent.com.atproto.repo.getRecord({
+                repo: this.repoDid,
+                collection,
+                rkey: PROFILE_RKEY,
+            });
+            if (!existing.success) {
+                return this.createProfileRecord(collection, params);
+            }
+            const { avatar, banner, ...otherFields } = params;
+            const updatedProfile = {
+                ...existing.data.value,
+            };
+            for (const [key, value] of Object.entries(otherFields)) {
+                // ignore these since profile has already created
+                if (["$type", "createdAt"].includes(key))
+                    continue;
+                if (value === null) {
+                    delete updatedProfile[key];
+                }
+                else if (value !== undefined) {
+                    updatedProfile[key] = value;
+                }
+            }
+            await this.applyImageField(updatedProfile, "avatar", avatar, collection);
+            await this.applyImageField(updatedProfile, "banner", banner, collection);
+            this.validateProfileRecord(updatedProfile, collection);
+            const result = await this.agent.com.atproto.repo.putRecord({
+                repo: this.repoDid,
+                collection,
+                rkey: PROFILE_RKEY,
+                record: updatedProfile,
+            });
+            if (!result.success) {
+                throw new NetworkError("Failed to upsert profile");
+            }
+            return { uri: result.data.uri, cid: result.data.cid };
+        }
+        catch (error) {
+            if (error instanceof NetworkError || error instanceof ValidationError)
+                throw error;
+            throw new NetworkError(`Failed to upsert profile: ${error instanceof Error ? error.message : "Unknown error"}`, error);
+        }
+    }
+    /**
+     * Gets Bluesky profile (app.bsky.actor.profile).
+     *
+     * @returns Promise resolving to Bluesky profile data
+     * @throws {NetworkError} If profile cannot be fetched
+     *
+     * @example
+     * ```typescript
+     * const bskyProfile = await repo.profile.getBskyProfile();
+     * console.log(bskyProfile.displayName); // "Alice"
+     * console.log(bskyProfile.avatar); // "https://cdn.bsky.app/..."
+     * ```
+     */
+    async getBskyProfile() {
+        try {
+            const profileResult = await this.agent.getProfile({ actor: this.repoDid });
+            if (!profileResult.success) {
+                throw new NetworkError("Failed to get Bluesky profile");
+            }
+            return profileResult.data;
+        }
+        catch (error) {
+            if (error instanceof NetworkError)
+                throw error;
+            throw new NetworkError(`Failed to get Bluesky profile: ${error instanceof Error ? error.message : "Unknown error"}`, error);
+        }
+    }
+    /**
+     * Gets Certified profile (app.certified.actor.profile).
+     *
+     * Returns the profile record with avatar and banner converted to blob URLs.
+     * Includes the user's handle fetched from getProfile(). If getProfile() fails,
+     * handle is set to empty string.
+     *
+     * @returns Promise resolving to Certified profile data, or null if no profile exists
+     * @throws {NetworkError} If profile fetch fails due to network/server issues
+     *
+     * @example
+     * ```typescript
+     * const certifiedProfile = await repo.profile.getCertifiedProfile();
+     * if (certifiedProfile) {
+     *   console.log(certifiedProfile.displayName); // "Alice"
+     *   console.log(certifiedProfile.pronouns); // "she/her"
+     *   console.log(certifiedProfile.avatar); // "https://pds.../xrpc/..."
+     * } else {
+     *   console.log("User hasn't created a certified profile yet");
+     * }
+     * ```
+     */
+    async getCertifiedProfile() {
+        try {
+            // Fetch handle from Bluesky profile (non-blocking)
+            let handle = "";
+            try {
+                const profileResult = await this.agent.getProfile({ actor: this.repoDid });
+                if (profileResult.success) {
+                    handle = profileResult.data.handle;
+                }
+            }
+            catch {
+                // Ignore error, use empty string for handle
+                handle = "";
+            }
+            // Fetch certified profile record
+            const recordResult = await this.agent.com.atproto.repo.getRecord({
+                repo: this.repoDid,
+                collection: CERTIFIED_PROFILE_NSID,
+                rkey: PROFILE_RKEY,
+            });
+            if (!recordResult.success) {
+                return null;
+            }
+            const profileRecord = recordResult.data.value;
+            let avatar;
+            let banner;
+            if (profileRecord.avatar) {
+                avatar = this.imageToUrl(profileRecord.avatar);
+            }
+            if (profileRecord.banner) {
+                banner = this.imageToUrl(profileRecord.banner);
+            }
+            return {
+                ...profileRecord,
+                handle,
+                avatar,
+                banner,
+            };
+        }
+        catch (error) {
+            // Check for RecordNotFoundError from AT Protocol SDK
+            if (error && typeof error === "object" && "error" in error && error.error === "RecordNotFound") {
+                return null;
+            }
+            // Actual network/server errors still throw
+            if (error instanceof NetworkError)
+                throw error;
+            throw new NetworkError(`Failed to get Certified profile: ${error instanceof Error ? error.message : "Unknown error"}`, error);
+        }
+    }
+    /**
+     * Creates Bluesky profile (app.bsky.actor.profile).
+     *
+     * @param params - Profile fields to set
+     * @returns Promise resolving to create result with URI and CID
+     * @throws {NetworkError} If creation fails
+     *
+     * @example
+     * ```typescript
+     * await repo.profile.createBskyProfile({
+     *   displayName: "Alice",
+     *   description: "Building impact certificates",
+     * });
+     * ```
+     */
+    async createBskyProfile(params) {
+        return this.createProfileRecord(BSKY_PROFILE_NSID, params);
+    }
+    /**
+     * Updates Bluesky profile (app.bsky.actor.profile).
+     *
+     * @param params - Fields to update (pass null to remove)
+     * @returns Promise resolving to update result with URI and CID
+     * @throws {NetworkError} If update fails
+     *
+     * @example
+     * ```typescript
+     * await repo.profile.updateBskyProfile({
+     *   displayName: "New Name",
+     *   description: null,  // Remove description
+     * });
+     * ```
+     */
+    async updateBskyProfile(params) {
+        return this.updateProfileRecord(BSKY_PROFILE_NSID, params);
+    }
+    /**
+     * Creates Certified profile (app.certified.actor.profile).
+     *
+     * @param params - Profile fields to set
+     * @returns Promise resolving to create result with URI and CID
+     * @throws {NetworkError} If creation fails
+     *
+     * @example
+     * ```typescript
+     * await repo.profile.createCertifiedProfile({
+     *   displayName: "Alice",
+     *   description: "Building impact certificates",
+     *   pronouns: "she/her",
+     *   website: "https://alice.com",
+     * });
+     * ```
+     */
+    async createCertifiedProfile(params) {
+        return this.createProfileRecord(CERTIFIED_PROFILE_NSID, params);
+    }
+    /**
+     * Updates Certified profile (app.certified.actor.profile).
+     *
+     * @param params - Fields to update (pass null to remove)
+     * @returns Promise resolving to update result with URI and CID
+     * @throws {NetworkError} If update fails
+     *
+     * @example
+     * ```typescript
+     * await repo.profile.updateCertifiedProfile({
+     *   displayName: "New Name",
+     *   pronouns: null,  // Remove pronouns
+     * });
+     * ```
+     */
+    async updateCertifiedProfile(params) {
+        return this.updateProfileRecord(CERTIFIED_PROFILE_NSID, params);
+    }
+    /**
+     * Upserts Bluesky profile (creates if missing, updates if exists).
+     *
+     * Automatically detects whether the profile exists and creates or updates accordingly.
+     * This is the recommended method for most use cases.
+     *
+     * @param params - Profile fields to set
+     * @returns Promise resolving to update result with URI and CID
+     * @throws {NetworkError} If operation fails
+     * @throws {ValidationError} If validation fails
+     *
+     * @example
+     * ```typescript
+     * // Works whether profile exists or not
+     * await repo.profile.upsertBskyProfile({
+     *   displayName: "Alice",
+     *   description: "Building on AT Protocol",
+     * });
+     * ```
+     */
+    async upsertBskyProfile(params) {
+        return this.upsertProfileRecord(BSKY_PROFILE_NSID, params);
+    }
+    /**
+     * Upserts Certified profile (creates if missing, updates if exists).
+     *
+     * Automatically detects whether the profile exists and creates or updates accordingly.
+     * This is the recommended method for most use cases.
+     *
+     * @param params - Profile fields to set
+     * @returns Promise resolving to update result with URI and CID
+     * @throws {NetworkError} If operation fails
+     * @throws {ValidationError} If validation fails
+     *
+     * @example
+     * ```typescript
+     * // Works whether profile exists or not
+     * await repo.profile.upsertCertifiedProfile({
+     *   displayName: "Alice",
+     *   pronouns: "she/her",
+     *   website: "https://alice.com",
+     * });
+     * ```
+     */
+    async upsertCertifiedProfile(params) {
+        return this.upsertProfileRecord(CERTIFIED_PROFILE_NSID, params);
+    }
+}
+
+/**
+ * Crypto utilities for the SDK.
+ */
+/**
+ * Deterministically stringifies an object by sorting keys recursively.
+ * Handles deeply nested objects and null values correctly.
+ */
+function stableStringify(obj) {
+    if (obj === undefined || typeof obj === "function" || typeof obj === "symbol") {
+        return undefined;
+    }
+    if (obj === null || typeof obj !== "object") {
+        return JSON.stringify(obj);
+    }
+    if (Array.isArray(obj)) {
+        return JSON.stringify(obj.map((item) => {
+            const val = stableStringify(item);
+            return val === undefined ? null : JSON.parse(val);
+        }));
+    }
+    const sortedKeys = Object.keys(obj).sort();
+    const sortedObj = {};
+    for (const key of sortedKeys) {
+        const value = obj[key];
+        const str = stableStringify(value);
+        // Skip undefined or non-serializable values
+        if (str === undefined)
+            continue;
+        sortedObj[key] = JSON.parse(str);
+    }
+    return JSON.stringify(sortedObj);
+}
+/**
+ * Computes the SHA-256 hash of a JSON-serializable object.
+ * Returns the hash as a hexadecimal string.
  *
- * This sub-entrypoint exports the lexicon registry and hypercert
- * lexicon constants for working with AT Protocol record schemas.
+ * @param content - The content to hash (will be JSON serialized)
+ * @returns The SHA-256 hash of the content
+ * @throws {ValidationError} If content is not serializable (e.g. undefined, function, symbol)
+ */
+async function sha256Hash(content) {
+    // Use stable stringification to ensure deterministic output
+    const jsonString = stableStringify(content);
+    if (jsonString === undefined) {
+        throw new ValidationError(`Content illegal: not serializable (type: ${typeof content})`);
+    }
+    const msgBuffer = new TextEncoder().encode(jsonString);
+    if (typeof crypto !== "undefined" && crypto.subtle) {
+        // Browser / Modern Node.js
+        const hashBuffer = await crypto.subtle.digest("SHA-256", msgBuffer);
+        const hashArray = Array.from(new Uint8Array(hashBuffer));
+        return hashArray.map((b) => b.toString(16).padStart(2, "0")).join("");
+    }
+    else {
+        // Fallback for older environments or specific setups if global crypto isn't available
+        try {
+            // Dynamic import to avoid breaking browser builds if bundler doesn't handle it
+            const { createHash } = await import('node:crypto');
+            const hash = createHash("sha256").update(jsonString).digest("hex");
+            return hash;
+        }
+        catch (e) {
+            throw new NetworkError("SHA-256 hashing not supported in this environment", e);
+        }
+    }
+}
+
+/**
+ * Lexicon Development Utilities - AT-URI and StrongRef Helpers
+ *
+ * This module provides utilities for working with AT Protocol URIs and strongRefs
+ * when building custom lexicons. These tools help developers create type-safe
+ * references between records.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Regular expression for parsing AT-URIs.
+ *
+ * AT-URIs follow the format: `at://{did}/{collection}/{rkey}`
+ *
+ * Capture groups:
+ * - [1] did - The DID of the repository owner (e.g., "did:plc:abc123")
+ * - [2] collection - The NSID of the record type (e.g., "org.hypercerts.claim.activity")
+ * - [3] rkey - The record key (e.g., "3km2vj4kfqp2a")
+ *
+ * @example Direct regex usage
+ * ```typescript
+ * const match = AT_URI_REGEX.exec("at://did:plc:abc/org.hypercerts.claim.activity/xyz");
+ * if (match) {
+ *   const [, did, collection, rkey] = match;
+ * }
+ * ```
+ *
+ * @example Validation
+ * ```typescript
+ * if (AT_URI_REGEX.test(userInput)) {
+ *   // Valid AT-URI format
+ * }
+ * ```
  *
  * @remarks
- * Import from `@hypercerts-org/sdk/lexicons`:
+ * For most use cases, prefer using {@link parseAtUri} which provides
+ * better error messages and returns a typed object.
+ */
+const AT_URI_REGEX = /^at:\/\/([^/]+)\/([^/]+)\/([^/]+)$/;
+/**
+ * Parse an AT-URI into its component parts.
+ *
+ * Extracts the DID, collection NSID, and record key from an AT-URI string.
+ * AT-URIs follow the format: `at://{did}/{collection}/{rkey}`
+ *
+ * @param uri - The AT-URI to parse
+ * @returns The components of the URI
+ * @throws {Error} If the URI format is invalid
  *
+ * @example
  * ```typescript
- * import {
- *   LexiconRegistry,
- *   HYPERCERT_LEXICONS,
- *   HYPERCERT_COLLECTIONS,
- * } from "@hypercerts-org/sdk/lexicons";
+ * const components = parseAtUri("at://did:plc:abc123/org.hypercerts.claim.activity/3km2vj4kfqp2a");
+ * console.log(components);
+ * // {
+ * //   did: "did:plc:abc123",
+ * //   collection: "org.hypercerts.claim.activity",
+ * //   rkey: "3km2vj4kfqp2a"
+ * // }
  * ```
+ */
+function parseAtUri(uri) {
+    if (!uri.startsWith("at://")) {
+        throw new Error(`Invalid AT-URI format: must start with "at://", got "${uri}"`);
+    }
+    const withoutProtocol = uri.slice(5); // Remove "at://"
+    const parts = withoutProtocol.split("/");
+    if (parts.length !== 3) {
+        throw new Error(`Invalid AT-URI format: expected "at://{did}/{collection}/{rkey}", got "${uri}"`);
+    }
+    const [did, collection, rkey] = parts;
+    if (!did || !collection || !rkey) {
+        throw new Error(`Invalid AT-URI format: all components must be non-empty, got "${uri}"`);
+    }
+    return { did, collection, rkey };
+}
+/**
+ * Build an AT-URI from its component parts.
  *
- * **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
+ * Constructs a valid AT-URI string from a DID, collection NSID, and record key.
+ * The resulting URI follows the format: `at://{did}/{collection}/{rkey}`
  *
- * @example Using collection constants
+ * @param did - The repository owner's DID
+ * @param collection - The collection NSID (lexicon identifier)
+ * @param rkey - The record key (TID or custom string)
+ * @returns The complete AT-URI
+ *
+ * @example
  * ```typescript
- * import { HYPERCERT_COLLECTIONS } from "@hypercerts-org/sdk/lexicons";
+ * const uri = buildAtUri(
+ *   "did:plc:abc123",
+ *   "org.hypercerts.claim.activity",
+ *   "3km2vj4kfqp2a"
+ * );
+ * console.log(uri); // "at://did:plc:abc123/org.hypercerts.claim.activity/3km2vj4kfqp2a"
+ * ```
+ */
+function buildAtUri(did, collection, rkey) {
+    if (!did || !collection || !rkey) {
+        throw new Error("All AT-URI components (did, collection, rkey) must be non-empty");
+    }
+    return `at://${did}/${collection}/${rkey}`;
+}
+/**
+ * Extract the record key (TID or custom key) from an AT-URI.
  *
- * // List hypercerts using the correct collection name
- * const records = await repo.records.list({
- *   collection: HYPERCERT_COLLECTIONS.RECORD,
- * });
+ * Returns the last component of the AT-URI, which is the record key.
+ * This is equivalent to `parseAtUri(uri).rkey` but more efficient.
  *
- * // List contributions
- * const contributions = await repo.records.list({
- *   collection: HYPERCERT_COLLECTIONS.CONTRIBUTION,
- * });
+ * @param uri - The AT-URI to extract from
+ * @returns The record key (TID or custom string)
+ * @throws {Error} If the URI format is invalid
+ *
+ * @example
+ * ```typescript
+ * const rkey = extractRkeyFromUri("at://did:plc:abc123/org.hypercerts.claim.activity/3km2vj4kfqp2a");
+ * console.log(rkey); // "3km2vj4kfqp2a"
  * ```
+ */
+function extractRkeyFromUri(uri) {
+    const { rkey } = parseAtUri(uri);
+    return rkey;
+}
+/**
+ * Check if a string is a valid AT-URI format.
  *
- * @example Custom lexicon registration
+ * Validates that the string follows the AT-URI format without throwing errors.
+ * This is useful for input validation before parsing.
+ *
+ * @param uri - The string to validate
+ * @returns True if the string is a valid AT-URI, false otherwise
+ *
+ * @example
  * ```typescript
- * import { LexiconRegistry } from "@hypercerts-org/sdk/lexicons";
+ * if (isValidAtUri(userInput)) {
+ *   const components = parseAtUri(userInput);
+ *   // ... use components
+ * } else {
+ *   console.error("Invalid AT-URI");
+ * }
+ * ```
+ */
+function isValidAtUri(uri) {
+    try {
+        parseAtUri(uri);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Create a strongRef from a URI and CID.
  *
- * const registry = sdk.getLexiconRegistry();
+ * StrongRefs are the canonical way to reference specific versions of records
+ * in AT Protocol. They combine an AT-URI (which identifies the record) with
+ * a CID (which identifies the specific version).
+ *
+ * @param uri - The AT-URI of the record
+ * @param cid - The CID (Content Identifier) of the record version
+ * @returns A strongRef object
+ *
+ * @example
+ * ```typescript
+ * const ref = createStrongRef(
+ *   "at://did:plc:abc123/org.hypercerts.claim.activity/3km2vj4kfqp2a",
+ *   "bafyreiabc123..."
+ * );
+ * console.log(ref);
+ * // {
+ * //   uri: "at://did:plc:abc123/org.hypercerts.claim.activity/3km2vj4kfqp2a",
+ * //   cid: "bafyreiabc123..."
+ * // }
+ * ```
+ */
+function createStrongRef(uri, cid) {
+    if (!uri || !cid) {
+        throw new Error("Both uri and cid are required to create a strongRef");
+    }
+    return { uri, cid };
+}
+/**
+ * Create a strongRef from a CreateResult or UpdateResult.
+ *
+ * This is a convenience function that extracts the URI and CID from
+ * the result of a record creation or update operation.
+ *
+ * @param result - The result from creating or updating a record
+ * @returns A strongRef object
  *
- * // Register custom lexicon
- * registry.register({
- *   lexicon: 1,
- *   id: "org.myapp.customRecord",
- *   defs: { ... },
+ * @example
+ * ```typescript
+ * const hypercert = await repo.hypercerts.create({
+ *   title: "Climate Research",
+ *   // ... other params
  * });
  *
- * // Validate a record
- * const result = registry.validate("org.myapp.customRecord", record);
- * if (!result.valid) {
- *   console.error(result.error);
- * }
+ * const ref = createStrongRefFromResult(hypercert);
+ * // Now use ref in another record to reference this hypercert
  * ```
- *
- * @packageDocumentation
- */
-/**
- * All hypercert-related lexicons for registration with AT Protocol Agent.
- * This array contains all lexicon documents from the published package.
  */
-const HYPERCERT_LEXICONS = [
-    lexicon.CERTIFIED_DEFS_LEXICON_JSON,
-    lexicon.LOCATION_LEXICON_JSON,
-    lexicon.STRONG_REF_LEXICON_JSON,
-    lexicon.HYPERCERTS_DEFS_LEXICON_JSON,
-    lexicon.ACTIVITY_LEXICON_JSON,
-    lexicon.COLLECTION_LEXICON_JSON,
-    lexicon.CONTRIBUTION_DETAILS_LEXICON_JSON,
-    lexicon.CONTRIBUTOR_INFORMATION_LEXICON_JSON,
-    lexicon.EVALUATION_LEXICON_JSON,
-    lexicon.ATTACHMENT_LEXICON_JSON,
-    lexicon.MEASUREMENT_LEXICON_JSON,
-    lexicon.RIGHTS_LEXICON_JSON,
-    lexicon.BADGE_AWARD_LEXICON_JSON,
-    lexicon.BADGE_DEFINITION_LEXICON_JSON,
-    lexicon.BADGE_RESPONSE_LEXICON_JSON,
-    lexicon.FUNDING_RECEIPT_LEXICON_JSON,
-    lexicon.WORK_SCOPE_TAG_LEXICON_JSON,
-];
+function createStrongRefFromResult(result) {
+    return createStrongRef(result.uri, result.cid);
+}
 /**
- * Collection NSIDs (Namespaced Identifiers) for hypercert records.
+ * Validate that an object is a valid strongRef.
  *
- * Use these constants when performing record operations to ensure
- * correct collection names.
- */
-const HYPERCERT_COLLECTIONS = {
-    /**
-     * Main hypercert claim record collection.
-     */
-    CLAIM: lexicon.ACTIVITY_NSID,
-    /**
-     * Rights record collection.
-     */
-    RIGHTS: lexicon.RIGHTS_NSID,
-    /**
-     * Location record collection (shared certified lexicon).
-     */
-    LOCATION: lexicon.LOCATION_NSID,
-    /**
-     * Contribution details record collection.
-     * For storing details about a specific contribution (role, description, timeframe).
-     */
-    CONTRIBUTION_DETAILS: lexicon.CONTRIBUTION_DETAILS_NSID,
-    /**
-     * Contributor information record collection.
-     * For storing contributor profile information (identifier, displayName, image).
-     */
-    CONTRIBUTOR_INFORMATION: lexicon.CONTRIBUTOR_INFORMATION_NSID,
-    /**
-     * Measurement record collection.
-     */
-    MEASUREMENT: lexicon.MEASUREMENT_NSID,
-    /**
-     * Evaluation record collection.
-     */
-    EVALUATION: lexicon.EVALUATION_NSID,
-    /**
-     * Attachment record collection.
-     */
-    ATTACHMENT: lexicon.ATTACHMENT_NSID,
-    /**
-     * Collection record collection (groups of hypercerts).
-     * Projects are now collections with type='project'.
-     */
-    COLLECTION: lexicon.COLLECTION_NSID,
-    /**
-     * Badge award record collection.
-     */
-    BADGE_AWARD: lexicon.BADGE_AWARD_NSID,
-    /**
-     * Badge definition record collection.
-     */
-    BADGE_DEFINITION: lexicon.BADGE_DEFINITION_NSID,
-    /**
-     * Badge response record collection.
-     */
-    BADGE_RESPONSE: lexicon.BADGE_RESPONSE_NSID,
-    /**
-     * Funding receipt record collection.
-     */
-    FUNDING_RECEIPT: lexicon.FUNDING_RECEIPT_NSID,
-    /**
-     * Work scope tag record collection.
-     * For defining reusable work scope atoms.
-     */
-    WORK_SCOPE_TAG: lexicon.WORK_SCOPE_TAG_NSID,
-};
-
-/**
- * Crypto utilities for the SDK.
- */
-/**
- * Deterministically stringifies an object by sorting keys recursively.
- * Handles deeply nested objects and null values correctly.
+ * Checks that the object has the required `uri` and `cid` properties
+ * and that they are non-empty strings.
+ *
+ * @param ref - The object to validate
+ * @returns True if the object is a valid strongRef, false otherwise
+ *
+ * @example
+ * ```typescript
+ * const maybeRef = { uri: "at://...", cid: "bafyrei..." };
+ * if (validateStrongRef(maybeRef)) {
+ *   // Safe to use as strongRef
+ *   record.subject = maybeRef;
+ * }
+ * ```
  */
-function stableStringify(obj) {
-    if (obj === undefined || typeof obj === "function" || typeof obj === "symbol") {
-        return undefined;
-    }
-    if (obj === null || typeof obj !== "object") {
-        return JSON.stringify(obj);
-    }
-    if (Array.isArray(obj)) {
-        return JSON.stringify(obj.map((item) => {
-            const val = stableStringify(item);
-            return val === undefined ? null : JSON.parse(val);
-        }));
-    }
-    const sortedKeys = Object.keys(obj).sort();
-    const sortedObj = {};
-    for (const key of sortedKeys) {
-        const value = obj[key];
-        const str = stableStringify(value);
-        // Skip undefined or non-serializable values
-        if (str === undefined)
-            continue;
-        sortedObj[key] = JSON.parse(str);
+function validateStrongRef(ref) {
+    if (!ref || typeof ref !== "object") {
+        return false;
     }
-    return JSON.stringify(sortedObj);
+    const obj = ref;
+    return typeof obj.uri === "string" && obj.uri.length > 0 && typeof obj.cid === "string" && obj.cid.length > 0;
 }
 /**
- * Computes the SHA-256 hash of a JSON-serializable object.
- * Returns the hash as a hexadecimal string.
+ * Type guard to check if a value is a strongRef.
  *
- * @param content - The content to hash (will be JSON serialized)
- * @returns The SHA-256 hash of the content
- * @throws {ValidationError} If content is not serializable (e.g. undefined, function, symbol)
+ * This is an alias for `validateStrongRef` that provides better semantics
+ * for type narrowing in TypeScript.
+ *
+ * @param value - The value to check
+ * @returns True if the value is a strongRef, false otherwise
+ *
+ * @example
+ * ```typescript
+ * function processReference(ref: unknown) {
+ *   if (isStrongRef(ref)) {
+ *     // TypeScript knows ref is StrongRef here
+ *     console.log(ref.uri);
+ *   }
+ * }
+ * ```
  */
-async function sha256Hash(content) {
-    // Use stable stringification to ensure deterministic output
-    const jsonString = stableStringify(content);
-    if (jsonString === undefined) {
-        throw new ValidationError(`Content illegal: not serializable (type: ${typeof content})`);
-    }
-    const msgBuffer = new TextEncoder().encode(jsonString);
-    if (typeof crypto !== "undefined" && crypto.subtle) {
-        // Browser / Modern Node.js
-        const hashBuffer = await crypto.subtle.digest("SHA-256", msgBuffer);
-        const hashArray = Array.from(new Uint8Array(hashBuffer));
-        return hashArray.map((b) => b.toString(16).padStart(2, "0")).join("");
-    }
-    else {
-        // Fallback for older environments or specific setups if global crypto isn't available
-        try {
-            // Dynamic import to avoid breaking browser builds if bundler doesn't handle it
-            const { createHash } = await import('node:crypto');
-            const hash = createHash("sha256").update(jsonString).digest("hex");
-            return hash;
-        }
-        catch (e) {
-            throw new NetworkError("SHA-256 hashing not supported in this environment", e);
-        }
-    }
+function isStrongRef(value) {
+    return validateStrongRef(value);
 }
 
 /**
@@ -3720,21 +4478,98 @@ async function sha256Hash(content) {
  */
 class HypercertOperationsImpl extends eventemitter3.EventEmitter {
     /**
-     * Creates a new HypercertOperationsImpl.
-     *
-     * @param agent - AT Protocol Agent for making API calls
-     * @param repoDid - DID of the repository to operate on
-     * @param blobs - Blob operations for uploading images and files
-     * @param logger - Optional logger for debugging
+     * Creates a new HypercertOperationsImpl.
+     *
+     * @param agent - AT Protocol Agent for making API calls
+     * @param repoDid - DID of the repository to operate on
+     * @param blobs - Blob operations for uploading images and files
+     * @param logger - Optional logger for debugging
+     *
+     * @internal
+     */
+    constructor(agent, repoDid, blobs, logger) {
+        super();
+        this.agent = agent;
+        this.repoDid = repoDid;
+        this.blobs = blobs;
+        this.logger = logger;
+    }
+    /**
+     * Parses an AT-URI and throws ValidationError if invalid.
+     *
+     * This wrapper converts the generic Error from parseAtUri() to a ValidationError
+     * for consistent error handling throughout the SDK.
+     *
+     * @param uri - AT-URI to parse
+     * @returns Parsed URI components
+     * @throws {@link ValidationError} if URI format is invalid
+     * @internal
+     */
+    parseUri(uri) {
+        try {
+            return parseAtUri(uri);
+        }
+        catch (error) {
+            throw new ValidationError(error instanceof Error ? error.message : `Invalid URI format: ${uri}`);
+        }
+    }
+    /**
+     * Fetches any record by AT-URI with generic typing.
+     *
+     * Returns the record along with parsed URI components needed for updates.
+     * Unlike the public `get()` method which is typed for HypercertClaim,
+     * this method can fetch any record type.
+     *
+     * @typeParam T - The expected type of the record
+     * @param uri - AT-URI of the record to fetch
+     * @returns Record data with parsed URI components
+     * @throws {@link ValidationError} if URI format is invalid
+     * @throws {@link NetworkError} if record cannot be fetched
+     * @internal
+     */
+    async fetchRecord(uri) {
+        const { did, collection, rkey } = this.parseUri(uri);
+        const result = await this.agent.com.atproto.repo.getRecord({
+            repo: did,
+            collection,
+            rkey,
+        });
+        if (!result.success) {
+            throw new NetworkError(`Failed to fetch record: ${uri}`);
+        }
+        const cid = result.data.cid;
+        if (!cid) {
+            throw new NetworkError(`Record at ${uri} returned no CID`);
+        }
+        return {
+            uri: result.data.uri,
+            cid,
+            record: result.data.value,
+            collection,
+            rkey,
+        };
+    }
+    /**
+     * Updates a record in the repository.
      *
+     * @param collection - NSID of the collection
+     * @param rkey - Record key
+     * @param record - Updated record data
+     * @returns Update result with URI and CID
+     * @throws {@link NetworkError} if update fails
      * @internal
      */
-    constructor(agent, repoDid, blobs, logger) {
-        super();
-        this.agent = agent;
-        this.repoDid = repoDid;
-        this.blobs = blobs;
-        this.logger = logger;
+    async saveRecord(collection, rkey, record) {
+        const result = await this.agent.com.atproto.repo.putRecord({
+            repo: this.repoDid,
+            collection,
+            rkey,
+            record,
+        });
+        if (!result.success) {
+            throw new NetworkError(`Failed to save record: ${collection}/${rkey}`);
+        }
+        return { uri: result.data.uri, cid: result.data.cid };
     }
     /**
      * Emits a progress event to the optional progress handler.
@@ -3753,16 +4588,6 @@ class HypercertOperationsImpl extends eventemitter3.EventEmitter {
             }
         }
     }
-    /**
-     * Converts a blob upload result to JsonBlobRef format.
-     *
-     * @param uploadResult - Result from BlobOperations.upload()
-     * @returns JsonBlobRef formatted for records
-     * @internal
-     */
-    blobToJsonRef(uploadResult) {
-        return uploadResultToBlobRef(uploadResult);
-    }
     /**
      * Uploads an image blob and returns a blob reference.
      *
@@ -3781,7 +4606,7 @@ class HypercertOperationsImpl extends eventemitter3.EventEmitter {
                 status: "success",
                 data: { size: image.size },
             });
-            return this.blobToJsonRef(uploadResult);
+            return uploadResult;
         }
         catch (error) {
             this.emitProgress(onProgress, { name: "uploadImage", status: "error", error: error });
@@ -3860,7 +4685,10 @@ class HypercertOperationsImpl extends eventemitter3.EventEmitter {
             createdAt,
         };
         if (imageBlobRef) {
-            hypercertRecord.image = imageBlobRef;
+            hypercertRecord.image = {
+                $type: "org.hypercerts.defs#smallImage",
+                image: imageBlobRef,
+            };
         }
         // Add locations as embedded StrongRefs if provided
         if (locationRefs && locationRefs.length > 0) {
@@ -3892,6 +4720,11 @@ class HypercertOperationsImpl extends eventemitter3.EventEmitter {
         if (!hypercertValidation.success) {
             throw new ValidationError(`Invalid hypercert record: ${hypercertValidation.error?.message}`);
         }
+        // if its a blob ref guaranteed to have ref and a .toString method
+        let imageRef;
+        if (imageBlobRef) {
+            imageRef = imageBlobRef.ref.toString();
+        }
         // Generate rKey from stable content hash (idempotency)
         // Use NORMALIZED values (already resolved StrongRefs and processed data)
         // to ensure JSON-serializability and deterministic hashing.
@@ -3904,15 +4737,7 @@ class HypercertOperationsImpl extends eventemitter3.EventEmitter {
             workScope: params.workScope,
             startDate: params.startDate,
             endDate: params.endDate,
-            // Image: extract CID string from blob ref (stable content hash)
-            // JsonBlobRef can have ref.$link (upload result) or cid (existing record)
-            imageRef: imageBlobRef
-                ? "ref" in imageBlobRef && imageBlobRef.ref
-                    ? imageBlobRef.ref.$link
-                    : "cid" in imageBlobRef
-                        ? imageBlobRef.cid
-                        : undefined
-                : undefined,
+            imageRef,
             // Rights: canonical object with only known fields
             rights: {
                 name: params.rights.name,
@@ -3971,41 +4796,6 @@ class HypercertOperationsImpl extends eventemitter3.EventEmitter {
             throw error;
         }
     }
-    /**
-     * Creates contribution records with progress tracking.
-     *
-     * @param hypercertUri - URI of the hypercert
-     * @param contributions - Array of contribution data
-     * @param onProgress - Optional progress callback
-     * @returns Promise resolving to array of contribution URIs
-     * @internal
-     */
-    async createContributionsWithProgress(hypercertUri, contributions, onProgress) {
-        this.emitProgress(onProgress, { name: "createContributions", status: "start" });
-        try {
-            const contributionUris = [];
-            for (const contrib of contributions) {
-                const contribResult = await this.addContribution({
-                    hypercertUri,
-                    contributors: contrib.contributors.filter((c) => typeof c === "string"),
-                    role: contrib.role,
-                    description: contrib.description,
-                });
-                contributionUris.push(contribResult.uri);
-            }
-            this.emitProgress(onProgress, {
-                name: "createContributions",
-                status: "success",
-                data: { count: contributionUris.length },
-            });
-            return contributionUris;
-        }
-        catch (error) {
-            this.emitProgress(onProgress, { name: "createContributions", status: "error", error: error });
-            this.logger?.warn(`Failed to create contributions: ${error instanceof Error ? error.message : "Unknown"}`);
-            throw error;
-        }
-    }
     /**
      * Creates attachment records and returns their URIs.
      *
@@ -4194,19 +4984,7 @@ class HypercertOperationsImpl extends eventemitter3.EventEmitter {
      */
     async update(params) {
         try {
-            const uriMatch = params.uri.match(/^at:\/\/([^/]+)\/([^/]+)\/(.+)$/);
-            if (!uriMatch) {
-                throw new ValidationError(`Invalid URI format: ${params.uri}`);
-            }
-            const [, , collection, rkey] = uriMatch;
-            const existing = await this.agent.com.atproto.repo.getRecord({
-                repo: this.repoDid,
-                collection,
-                rkey,
-            });
-            // The existing record comes from ATProto, use it directly
-            // TypeScript ensures type safety through the HypercertClaim interface
-            const existingRecord = existing.data.value;
+            const { record: existingRecord, collection, rkey } = await this.fetchRecord(params.uri);
             const recordForUpdate = {
                 ...existingRecord,
                 ...params.updates,
@@ -4221,7 +4999,10 @@ class HypercertOperationsImpl extends eventemitter3.EventEmitter {
                 }
                 else {
                     const uploadResult = await this.blobs.upload(params.image);
-                    recordForUpdate.image = this.blobToJsonRef(uploadResult);
+                    recordForUpdate.image = {
+                        $type: "org.hypercerts.defs#smallImage",
+                        image: uploadResult,
+                    };
                 }
             }
             else if (existingRecord.image) {
@@ -4232,17 +5013,9 @@ class HypercertOperationsImpl extends eventemitter3.EventEmitter {
             if (!validation.success) {
                 throw new ValidationError(`Invalid hypercert record: ${validation.error?.message}`);
             }
-            const result = await this.agent.com.atproto.repo.putRecord({
-                repo: this.repoDid,
-                collection,
-                rkey,
-                record: recordForUpdate,
-            });
-            if (!result.success) {
-                throw new NetworkError("Failed to update hypercert");
-            }
-            this.emit("recordUpdated", { uri: result.data.uri, cid: result.data.cid });
-            return { uri: result.data.uri, cid: result.data.cid };
+            const result = await this.saveRecord(collection, rkey, recordForUpdate);
+            this.emit("recordUpdated", { uri: result.uri, cid: result.cid });
+            return result;
         }
         catch (error) {
             if (error instanceof ValidationError || error instanceof NetworkError)
@@ -4266,24 +5039,8 @@ class HypercertOperationsImpl extends eventemitter3.EventEmitter {
      */
     async get(uri) {
         try {
-            const uriMatch = uri.match(/^at:\/\/([^/]+)\/([^/]+)\/(.+)$/);
-            if (!uriMatch) {
-                throw new ValidationError(`Invalid URI format: ${uri}`);
-            }
-            const [, , collection, rkey] = uriMatch;
-            const result = await this.agent.com.atproto.repo.getRecord({
-                repo: this.repoDid,
-                collection,
-                rkey,
-            });
-            if (!result.success) {
-                throw new NetworkError("Failed to get hypercert");
-            }
-            return {
-                uri: result.data.uri,
-                cid: result.data.cid ?? "",
-                record: result.data.value,
-            };
+            const { uri: resultUri, cid, record } = await this.fetchRecord(uri);
+            return { uri: resultUri, cid, record };
         }
         catch (error) {
             if (error instanceof ValidationError || error instanceof NetworkError)
@@ -4353,11 +5110,7 @@ class HypercertOperationsImpl extends eventemitter3.EventEmitter {
      */
     async delete(uri) {
         try {
-            const uriMatch = uri.match(/^at:\/\/([^/]+)\/([^/]+)\/(.+)$/);
-            if (!uriMatch) {
-                throw new ValidationError(`Invalid URI format: ${uri}`);
-            }
-            const [, , collection, rkey] = uriMatch;
+            const { collection, rkey } = this.parseUri(uri);
             const result = await this.agent.com.atproto.repo.deleteRecord({
                 repo: this.repoDid,
                 collection,
@@ -4521,23 +5274,13 @@ class HypercertOperationsImpl extends eventemitter3.EventEmitter {
         if (this.isLocationObject(location)) {
             return this.createLocationRecord(location);
         }
-        // Otherwise it's string | StrongRef, resolve to StrongRef
+        // Otherwise it's RefUri, resolve to StrongRef
         return this.resolveToStrongRef(location);
     }
     async resolveStrongRefFromUri(uri) {
-        const uriMatch = uri.match(/^at:\/\/([^/]+)\/([^/]+)\/(.+)$/);
-        if (!uriMatch) {
-            throw new ValidationError(`Invalid AT-URI format: "${uri}"`);
-        }
-        const [, repo, collection, rkey] = uriMatch;
-        const record = await this.agent.com.atproto.repo.getRecord({ repo, collection, rkey });
-        if (!record.success) {
-            throw new NetworkError(`Failed to fetch record for repo=${repo}, collection=${collection}, rkey=${rkey}`);
-        }
-        if (!record.data.cid) {
-            throw new NetworkError(`Record missing CID for repo=${repo}, collection=${collection}, rkey=${rkey}`);
-        }
-        return { $type: "com.atproto.repo.strongRef", uri, cid: record.data.cid };
+        // fetchRecord already validates CID presence and throws NetworkError if absent
+        const fetchResult = await this.fetchRecord(uri);
+        return { $type: "com.atproto.repo.strongRef", uri, cid: fetchResult.cid };
     }
     /**
      * Resolves a string URI or StrongRef to a StrongRef.
@@ -4586,11 +5329,18 @@ class HypercertOperationsImpl extends eventemitter3.EventEmitter {
      *
      * @param contentInput - Single content item or array (URI strings or Blobs)
      * @returns Promise resolving to array of URI refs or Blob refs
+     * @throws {@link ValidationError} if a string content item is not a valid URI
      * @throws {@link NetworkError} if blob upload fails
      * @internal
      */
     async resolveAttachmentContent(contentInput) {
         const contentArray = Array.isArray(contentInput) ? contentInput : [contentInput];
+        // Validate that all string content items are valid URIs before resolving
+        for (const item of contentArray) {
+            if (typeof item === "string" && !isValidUri(item)) {
+                throw new ValidationError(`Invalid URI: "${item}". Content must be a valid URI with a scheme (e.g., https://example.com)`);
+            }
+        }
         return await Promise.all(contentArray.map((item) => this.resolveUriOrBlob(item, "application/octet-stream")));
     }
     /**
@@ -4766,23 +5516,42 @@ class HypercertOperationsImpl extends eventemitter3.EventEmitter {
     async processContributors(contributions, onProgress) {
         if (!contributions || contributions.length === 0)
             return undefined;
-        const contributorsPromises = contributions.map(async (contrib) => {
-            // Resolve contributionDetails
-            const detailsRef = await this.resolveContributionDetails(contrib.contributionDetails, onProgress);
-            // Resolve each contributor identity
-            const resolvedContributors = await Promise.all(contrib.contributors.map((identity) => this.resolveContributorIdentity(identity, onProgress)));
-            // Expand to one entry per contributor
-            return resolvedContributors.map((identity) => ({
-                contributorIdentity: identity,
-                contributionWeight: contrib.weight,
-                contributionDetails: detailsRef,
-            }));
-        });
-        const nestedContributors = await Promise.all(contributorsPromises);
+        const contributorPromises = contributions.map((contrib) => this.buildContributorEntries(contrib.contributors, contrib.contributionDetails, contrib.weight, onProgress));
+        const nestedContributors = await Promise.all(contributorPromises);
         return nestedContributors.flat();
     }
     /**
-     * Resolves ContributionDetailsParams to a ResolvedContributionDetails.
+     * Creates a standalone contributionDetails record.
+     * @internal
+     */
+    async createContributionDetailsRecord(params) {
+        const createdAt = new Date().toISOString();
+        const { role, contributionDescription, startDate, endDate, ...extraProps } = params;
+        const contributionRecord = {
+            $type: HYPERCERT_COLLECTIONS.CONTRIBUTION_DETAILS,
+            role,
+            createdAt,
+            contributionDescription,
+            startDate,
+            endDate,
+            ...extraProps,
+        };
+        const validation = lexicon.validate(contributionRecord, HYPERCERT_COLLECTIONS.CONTRIBUTION_DETAILS, "main", false);
+        if (!validation.success) {
+            throw new ValidationError(`Invalid contribution details record: ${validation.error?.message}`);
+        }
+        const result = await this.agent.com.atproto.repo.createRecord({
+            repo: this.repoDid,
+            collection: HYPERCERT_COLLECTIONS.CONTRIBUTION_DETAILS,
+            record: contributionRecord,
+        });
+        if (!result.success) {
+            throw new NetworkError("Failed to create contribution details");
+        }
+        return { uri: result.data.uri, cid: result.data.cid };
+    }
+    /**
+     * Resolves ContributionDetailsParams to a RefUri.
      * Creates a record if CreateContributionDetailsParams is provided.
      * @internal
      */
@@ -4799,14 +5568,7 @@ class HypercertOperationsImpl extends eventemitter3.EventEmitter {
             // CreateContributionDetailsParams - auto-create record
             try {
                 this.emitProgress(onProgress, { name: "createContribution", status: "start" });
-                const { role, contributionDescription, startDate, endDate, ...extraProps } = details;
-                const result = await this.addContribution({
-                    role,
-                    description: contributionDescription,
-                    startDate,
-                    endDate,
-                    ...extraProps,
-                });
+                const result = await this.createContributionDetailsRecord(details);
                 this.emitProgress(onProgress, {
                     name: "createContribution",
                     status: "success",
@@ -4826,13 +5588,13 @@ class HypercertOperationsImpl extends eventemitter3.EventEmitter {
         throw new ValidationError("Invalid contributionDetails format");
     }
     /**
-     * Resolves ContributorIdentityParams to a ResolvedContributorIdentity.
+     * Resolves ContributorIdentityParams to a RefUri.
      * Creates a contributorInformation record if CreateContributorInformationParams is provided.
      * @internal
      */
     async resolveContributorIdentity(identity, onProgress) {
         if (typeof identity === "string") {
-            // we still store as contribtorInformation since it cant directly be a string
+            // we still store as contributorInformation since it can't directly be a string
             const result = await this.addContributorInformation({ identifier: identity });
             return { uri: result.uri, cid: result.cid, $type: "com.atproto.repo.strongRef" };
         }
@@ -4879,62 +5641,100 @@ class HypercertOperationsImpl extends eventemitter3.EventEmitter {
         throw new ValidationError("Invalid contributorIdentity format");
     }
     /**
-     * Creates a contribution details record.
+     * Builds contributor entries from parameters by resolving identities and details.
      *
-     * This creates a standalone contribution details record that can be referenced
-     * from an activity's `contributors` array via a strong reference.
+     * This helper resolves contributor identities and contribution details,
+     * creating records as needed, then assembles them into the contributor entry
+     * format used in hypercert records.
+     *
+     * @param contributorParams - Array of contributor identity params (DID, StrongRef, or create params)
+     * @param detailsParams - Contribution details (inline role, StrongRef, or create params)
+     * @param weight - Optional contribution weight
+     * @param onProgress - Optional progress callback
+     * @returns Promise resolving to array of contributor entries ready for embedding
+     * @internal
+     * @protected
+     */
+    async buildContributorEntries(contributorParams, detailsParams, weight, onProgress) {
+        const detailsRef = await this.resolveContributionDetails(detailsParams, onProgress);
+        const resolvedIdentities = await Promise.all(contributorParams.map((identity) => this.resolveContributorIdentity(identity, onProgress)));
+        return resolvedIdentities.map((identity) => ({
+            contributorIdentity: identity,
+            contributionWeight: weight,
+            contributionDetails: detailsRef,
+        }));
+    }
+    /**
+     * Attaches contributor entries to a hypercert by appending to its contributors array.
+     *
+     * Fetches the existing hypercert, merges new contributors with existing ones,
+     * and updates the hypercert record.
+     *
+     * @param hypercertUri - URI of the hypercert to update
+     * @param newContributors - Array of contributor entries to add
+     * @returns Promise resolving to update result with new URI and CID
+     * @throws {@link ValidationError} if URI format is invalid or validation fails
+     * @throws {@link NetworkError} if fetching or updating fails
+     * @internal
+     * @protected
+     */
+    async attachContributorsToHypercert(hypercertUri, newContributors) {
+        const existing = await this.get(hypercertUri);
+        const existingContributors = existing.record.contributors || [];
+        const updatedContributors = [...existingContributors, ...newContributors];
+        return await this.update({
+            uri: hypercertUri,
+            updates: {
+                contributors: updatedContributors,
+            },
+        });
+    }
+    /**
+     * Adds contributors to an existing hypercert.
+     *
+     * This method creates or references contribution records and updates the hypercert
+     * to include the new contributors in its contributors array.
      *
      * @param params - Contribution parameters
-     * @param params.hypercertUri - Optional hypercert (unused, kept for backward compatibility)
-     * @param params.contributors - Array of contributor DIDs (unused, kept for backward compatibility)
-     * @param params.role - Role of the contributor (e.g., "coordinator", "implementer")
-     * @param params.description - Optional description of the contribution
-     * @returns Promise resolving to contribution details record URI and CID
+     * @returns Promise resolving to updated hypercert URI and CID
      * @throws {@link ValidationError} if validation fails
      * @throws {@link NetworkError} if the operation fails
      *
-     * @remarks
-     * In the new lexicon structure, contributions are stored differently:
-     * - Use `contributionDetails` for detailed contribution records (role, description, timeframe)
-     * - Use `contributorInformation` for contributor profiles (identifier, displayName, image)
-     * - Reference these from the activity's `contributors` array using strong refs
+     * @example Add multiple contributors with inline role
+     * ```typescript
+     * await repo.hypercerts.addContribution({
+     *   hypercertUri: "at://did:plc:abc/org.hypercerts.claim.activity/xyz",
+     *   contributors: ["did:plc:user1", "did:plc:user2"],
+     *   contributionDetails: "Developer",
+     *   weight: "1.0"
+     * });
+     * ```
      *
-     * @example
+     * @example Add contributor with detailed contribution record
      * ```typescript
      * await repo.hypercerts.addContribution({
-     *   role: "implementer",
-     *   description: "On-ground implementation team",
+     *   hypercertUri: hypercertUri,
+     *   contributors: [{
+     *     identifier: "did:plc:coordinator",
+     *     displayName: "Alice",
+     *     image: avatarBlob
+     *   }],
+     *   contributionDetails: {
+     *     role: "Project Coordinator",
+     *     contributionDescription: "Led coordination efforts",
+     *     startDate: "2024-01-01",
+     *     endDate: "2024-06-30"
+     *   },
+     *   weight: "2.0"
      * });
      * ```
      */
     async addContribution(params) {
         try {
-            const createdAt = new Date().toISOString();
-            // Extract known fields, spread the rest
-            const { hypercertUri: _hypercertUri, contributors: _contributors, role, description, startDate, endDate, ...extraProps } = params;
-            const contributionRecord = {
-                $type: HYPERCERT_COLLECTIONS.CONTRIBUTION_DETAILS,
-                role,
-                createdAt,
-                contributionDescription: description,
-                startDate,
-                endDate,
-                ...extraProps,
-            };
-            const validation = lexicon.validate(contributionRecord, HYPERCERT_COLLECTIONS.CONTRIBUTION_DETAILS, "main", false);
-            if (!validation.success) {
-                throw new ValidationError(`Invalid contribution details record: ${validation.error?.message}`);
-            }
-            const result = await this.agent.com.atproto.repo.createRecord({
-                repo: this.repoDid,
-                collection: HYPERCERT_COLLECTIONS.CONTRIBUTION_DETAILS,
-                record: contributionRecord,
-            });
-            if (!result.success) {
-                throw new NetworkError("Failed to create contribution details");
-            }
-            this.emit("contributionCreated", { uri: result.data.uri, cid: result.data.cid });
-            return { uri: result.data.uri, cid: result.data.cid };
+            const newContributors = await this.buildContributorEntries(params.contributors, params.contributionDetails, params.weight, params.onProgress);
+            const result = await this.attachContributorsToHypercert(params.hypercertUri, newContributors);
+            this.emit("contributionCreated", { uri: result.uri, cid: result.cid });
+            return result;
         }
         catch (error) {
             if (error instanceof ValidationError || error instanceof NetworkError)
@@ -4976,7 +5776,7 @@ class HypercertOperationsImpl extends eventemitter3.EventEmitter {
                     resolvedImage = { $type: "org.hypercerts.defs#uri", uri: image };
                 }
                 else {
-                    // JsonBlobRef from upload - wrap in smallImage
+                    // BlobRef from upload - wrap in smallImage
                     resolvedImage = {
                         $type: "org.hypercerts.defs#smallImage",
                         image: image,
@@ -5114,38 +5914,19 @@ class HypercertOperationsImpl extends eventemitter3.EventEmitter {
      */
     async updateMeasurement(uri, updates) {
         try {
-            const uriMatch = uri.match(/^at:\/\/([^/]+)\/([^/]+)\/(.+)$/);
-            if (!uriMatch) {
-                throw new ValidationError(`Invalid URI format: ${uri}`);
-            }
-            const [, , collection, rkey] = uriMatch;
+            const { collection, rkey } = this.parseUri(uri);
             if (collection !== HYPERCERT_COLLECTIONS.MEASUREMENT) {
                 throw new ValidationError(`URI must target a measurement collection. Expected '${HYPERCERT_COLLECTIONS.MEASUREMENT}', got '${collection}'`);
             }
-            const existing = await this.agent.com.atproto.repo.getRecord({
-                repo: this.repoDid,
-                collection,
-                rkey,
-            });
-            if (!existing.success) {
-                throw new NetworkError(`Measurement not found: ${uri}`);
-            }
-            const recordForUpdate = await this.applyMeasurementUpdates(existing.data.value, updates);
+            const { record: existingRecord } = await this.fetchRecord(uri);
+            const recordForUpdate = await this.applyMeasurementUpdates(existingRecord, updates);
             const validation = lexicon.validate(recordForUpdate, HYPERCERT_COLLECTIONS.MEASUREMENT, "main", false);
             if (!validation.success) {
                 throw new ValidationError(`Invalid measurement record: ${validation.error?.message}`);
             }
-            const result = await this.agent.com.atproto.repo.putRecord({
-                repo: this.repoDid,
-                collection,
-                rkey,
-                record: recordForUpdate,
-            });
-            if (!result.success) {
-                throw new NetworkError("Failed to update measurement");
-            }
-            this.emit("measurementUpdated", { uri: result.data.uri, cid: result.data.cid });
-            return { uri: result.data.uri, cid: result.data.cid };
+            const result = await this.saveRecord(collection, rkey, recordForUpdate);
+            this.emit("measurementUpdated", { uri: result.uri, cid: result.cid });
+            return result;
         }
         catch (error) {
             if (error instanceof ValidationError || error instanceof NetworkError)
@@ -5182,7 +5963,7 @@ class HypercertOperationsImpl extends eventemitter3.EventEmitter {
             const evaluationRecord = {
                 $type: HYPERCERT_COLLECTIONS.EVALUATION,
                 subject: { uri: subject.uri, cid: subject.cid },
-                evaluators: params.evaluators,
+                evaluators: params.evaluators.map((evaluator) => ({ did: evaluator })),
                 summary: params.summary,
                 createdAt,
             };
@@ -5330,29 +6111,13 @@ class HypercertOperationsImpl extends eventemitter3.EventEmitter {
      */
     async getCollection(uri) {
         try {
-            const uriMatch = uri.match(/^at:\/\/([^/]+)\/([^/]+)\/(.+)$/);
-            if (!uriMatch) {
-                throw new ValidationError(`Invalid URI format: ${uri}`);
-            }
-            const [, , collection, rkey] = uriMatch;
-            const result = await this.agent.com.atproto.repo.getRecord({
-                repo: this.repoDid,
-                collection,
-                rkey,
-            });
-            if (!result.success) {
-                throw new NetworkError("Failed to get collection");
-            }
+            const { uri: resultUri, cid, record } = await this.fetchRecord(uri);
             // Validate with lexicon registry (more lenient - doesn't require $type)
-            const validation = lexicon.validate(result.data.value, HYPERCERT_COLLECTIONS.COLLECTION, "main", false);
+            const validation = lexicon.validate(record, HYPERCERT_COLLECTIONS.COLLECTION, "main", false);
             if (!validation.success) {
                 throw new ValidationError(`Invalid collection record format: ${validation.error?.message}`);
             }
-            return {
-                uri: result.data.uri,
-                cid: result.data.cid ?? "",
-                record: result.data.value,
-            };
+            return { uri: resultUri, cid, record };
         }
         catch (error) {
             if (error instanceof ValidationError || error instanceof NetworkError)
@@ -5366,8 +6131,7 @@ class HypercertOperationsImpl extends eventemitter3.EventEmitter {
      * @param params - Optional pagination parameters
      * @returns Promise resolving to paginated list of collections
      * @throws {@link NetworkError} if the list operation fails
-     *
-     * @example
+     * * @example
      * ```typescript
      * const { records } = await repo.hypercerts.listCollections();
      * for (const { record } of records) {
@@ -5470,36 +6234,17 @@ class HypercertOperationsImpl extends eventemitter3.EventEmitter {
      */
     async getProject(uri) {
         try {
-            // Parse URI
-            const uriMatch = uri.match(/^at:\/\/([^/]+)\/([^/]+)\/(.+)$/);
-            if (!uriMatch) {
-                throw new ValidationError(`Invalid URI format: ${uri}`);
-            }
-            const [, , collection, rkey] = uriMatch;
-            // Fetch record
-            const result = await this.agent.com.atproto.repo.getRecord({
-                repo: this.repoDid,
-                collection,
-                rkey,
-            });
-            if (!result.success) {
-                throw new NetworkError("Failed to get project");
-            }
+            const { uri: resultUri, cid, record } = await this.fetchRecord(uri);
             // Validate as collection
-            const validation = lexicon.validate(result.data.value, HYPERCERT_COLLECTIONS.COLLECTION, "main", false);
+            const validation = lexicon.validate(record, HYPERCERT_COLLECTIONS.COLLECTION, "main", false);
             if (!validation.success) {
                 throw new ValidationError(`Invalid project record format: ${validation.error?.message}`);
             }
             // Verify it's actually a project (collection with type='project')
-            const record = result.data.value;
             if (record.type !== "project") {
                 throw new ValidationError(`Record is not a project (type='${record.type}')`);
             }
-            return {
-                uri: result.data.uri,
-                cid: result.data.cid ?? "",
-                record,
-            };
+            return { uri: resultUri, cid, record };
         }
         catch (error) {
             if (error instanceof ValidationError || error instanceof NetworkError)
@@ -5594,25 +6339,12 @@ class HypercertOperationsImpl extends eventemitter3.EventEmitter {
      */
     async updateProject(uri, updates) {
         // Verify it's a project before updating
-        const uriMatch = uri.match(/^at:\/\/([^/]+)\/([^/]+)\/(.+)$/);
-        if (!uriMatch) {
-            throw new ValidationError(`Invalid URI format: ${uri}`);
-        }
-        const [, , collection, rkey] = uriMatch;
-        const existing = await this.agent.com.atproto.repo.getRecord({
-            repo: this.repoDid,
-            collection,
-            rkey,
-        });
-        if (!existing.success) {
-            throw new NetworkError(`Project not found: ${uri}`);
+        const fetchResult = await this.fetchRecord(uri);
+        if (fetchResult.record.type !== "project") {
+            throw new ValidationError(`Record is not a project (type='${fetchResult.record.type}')`);
         }
-        const record = existing.data.value;
-        if (record.type !== "project") {
-            throw new ValidationError(`Record is not a project (type='${record.type}')`);
-        }
-        // Delegate to updateCollection
-        const result = await this.updateCollection(uri, updates);
+        // Pass pre-fetched record to avoid a second fetch in updateCollectionRecord
+        const result = await this.updateCollectionRecord(fetchResult, updates);
         this.emit("projectUpdated", { uri: result.uri, cid: result.cid });
         return result;
     }
@@ -5631,20 +6363,7 @@ class HypercertOperationsImpl extends eventemitter3.EventEmitter {
      * ```
      */
     async deleteProject(uri) {
-        const uriMatch = uri.match(/^at:\/\/([^/]+)\/([^/]+)\/(.+)$/);
-        if (!uriMatch) {
-            throw new ValidationError(`Invalid URI format: ${uri}`);
-        }
-        const [, , collection, rkey] = uriMatch;
-        const existing = await this.agent.com.atproto.repo.getRecord({
-            repo: this.repoDid,
-            collection,
-            rkey,
-        });
-        if (!existing.success) {
-            throw new NetworkError(`Project not found: ${uri}`);
-        }
-        const record = existing.data.value;
+        const { record } = await this.fetchRecord(uri);
         if (record.type !== "project") {
             throw new ValidationError(`Record is not a project (type='${record.type}')`);
         }
@@ -5691,21 +6410,25 @@ class HypercertOperationsImpl extends eventemitter3.EventEmitter {
      * ```
      */
     async updateCollection(uri, updates) {
+        const fetchResult = await this.fetchRecord(uri);
+        const result = await this.updateCollectionRecord(fetchResult, updates);
+        this.emit("collectionUpdated", { uri: result.uri, cid: result.cid });
+        return result;
+    }
+    /**
+     * Core collection update logic operating on a pre-fetched record.
+     *
+     * Extracted so that callers like {@link updateProject} can fetch once,
+     * validate the type, and then delegate here without a redundant fetch.
+     *
+     * @param fetchResult - The pre-fetched record, collection, and rkey
+     * @param updates - Fields to update (partial)
+     * @returns Promise resolving to updated URI and CID
+     * @internal
+     */
+    async updateCollectionRecord(fetchResult, updates) {
         try {
-            const uriMatch = uri.match(/^at:\/\/([^/]+)\/([^/]+)\/(.+)$/);
-            if (!uriMatch) {
-                throw new ValidationError(`Invalid URI format: ${uri}`);
-            }
-            const [, , collection, rkey] = uriMatch;
-            const existing = await this.agent.com.atproto.repo.getRecord({
-                repo: this.repoDid,
-                collection,
-                rkey,
-            });
-            if (!existing.success) {
-                throw new NetworkError(`Collection not found: ${uri}`);
-            }
-            const existingRecord = existing.data.value;
+            const { record: existingRecord, collection, rkey } = fetchResult;
             const recordForUpdate = {
                 ...existingRecord,
                 createdAt: existingRecord.createdAt,
@@ -5771,17 +6494,8 @@ class HypercertOperationsImpl extends eventemitter3.EventEmitter {
             if (!validation.success) {
                 throw new ValidationError(`Invalid collection record: ${validation.error?.message}`);
             }
-            const result = await this.agent.com.atproto.repo.putRecord({
-                repo: this.repoDid,
-                collection,
-                rkey,
-                record: recordForUpdate,
-            });
-            if (!result.success) {
-                throw new NetworkError("Failed to update collection");
-            }
-            this.emit("collectionUpdated", { uri: result.data.uri, cid: result.data.cid });
-            return { uri: result.data.uri, cid: result.data.cid };
+            const result = await this.saveRecord(collection, rkey, recordForUpdate);
+            return result;
         }
         catch (error) {
             if (error instanceof ValidationError || error instanceof NetworkError)
@@ -5796,11 +6510,7 @@ class HypercertOperationsImpl extends eventemitter3.EventEmitter {
      */
     async deleteCollection(uri) {
         try {
-            const uriMatch = uri.match(/^at:\/\/([^/]+)\/([^/]+)\/(.+)$/);
-            if (!uriMatch) {
-                throw new ValidationError(`Invalid URI format: ${uri}`);
-            }
-            const [, , collection, rkey] = uriMatch;
+            const { collection, rkey } = this.parseUri(uri);
             const result = await this.agent.com.atproto.repo.deleteRecord({
                 repo: this.repoDid,
                 collection,
@@ -5826,36 +6536,16 @@ class HypercertOperationsImpl extends eventemitter3.EventEmitter {
      */
     async attachLocationToCollection(uri, location) {
         try {
-            const uriMatch = uri.match(/^at:\/\/([^/]+)\/([^/]+)\/(.+)$/);
-            if (!uriMatch) {
-                throw new ValidationError(`Invalid URI format: ${uri}`);
-            }
-            const [, , collection, rkey] = uriMatch;
-            const existing = await this.agent.com.atproto.repo.getRecord({
-                repo: this.repoDid,
-                collection,
-                rkey,
-            });
-            if (!existing.success) {
-                throw new NetworkError(`Collection not found: ${uri}`);
-            }
+            const { record, collection, rkey } = await this.fetchRecord(uri);
             const resolvedLocation = await this.resolveLocation(location);
             if (!resolvedLocation) {
                 throw new ValidationError("attachLocationToCollection: failed to resolve location");
             }
             const recordForUpdate = {
-                ...existing.data.value,
+                ...record,
                 location: resolvedLocation,
             };
-            const updateResult = await this.agent.com.atproto.repo.putRecord({
-                repo: this.repoDid,
-                collection,
-                rkey,
-                record: recordForUpdate,
-            });
-            if (!updateResult.success) {
-                throw new NetworkError("Failed to update collection with location");
-            }
+            await this.saveRecord(collection, rkey, recordForUpdate);
             this.emit("locationAttachedToCollection", {
                 uri: resolvedLocation.uri,
                 cid: resolvedLocation.cid,
@@ -5876,30 +6566,10 @@ class HypercertOperationsImpl extends eventemitter3.EventEmitter {
      */
     async removeLocationFromCollection(uri) {
         try {
-            const uriMatch = uri.match(/^at:\/\/([^/]+)\/([^/]+)\/(.+)$/);
-            if (!uriMatch) {
-                throw new ValidationError(`Invalid URI format: ${uri}`);
-            }
-            const [, , collection, rkey] = uriMatch;
-            const existing = await this.agent.com.atproto.repo.getRecord({
-                repo: this.repoDid,
-                collection,
-                rkey,
-            });
-            if (!existing.success) {
-                throw new NetworkError(`Collection not found: ${uri}`);
-            }
-            const recordForUpdate = { ...existing.data.value };
+            const { record, collection, rkey } = await this.fetchRecord(uri);
+            const recordForUpdate = { ...record };
             delete recordForUpdate.location;
-            const result = await this.agent.com.atproto.repo.putRecord({
-                repo: this.repoDid,
-                collection,
-                rkey,
-                record: recordForUpdate,
-            });
-            if (!result.success) {
-                throw new NetworkError("Failed to remove location from collection");
-            }
+            await this.saveRecord(collection, rkey, recordForUpdate);
             this.emit("locationRemovedFromCollection", { collectionUri: uri });
         }
         catch (error) {
@@ -6701,7 +7371,7 @@ class OrganizationOperationsImpl {
  * const repo = sdk.repository(session);
  *
  * // Access user profile
- * const profile = await repo.profile.get();
+ * const bskyProfile = await repo.profile.getBskyProfile();
  *
  * // Create a hypercert
  * const result = await repo.hypercerts.create({
@@ -6725,7 +7395,7 @@ class OrganizationOperationsImpl {
  *
  * // Get another user's repo (read-only for most operations)
  * const otherRepo = myRepo.repo("did:plc:other-user-did");
- * const theirProfile = await otherRepo.profile.get();
+ * const theirProfile = await otherRepo.profile.getCertifiedProfile();
  * ```
  *
  * @example SDS operations
@@ -6836,7 +7506,7 @@ class Repository {
      * ```typescript
      * // Read another user's profile
      * const otherRepo = repo.repo("did:plc:other-user");
-     * const profile = await otherRepo.profile.get();
+     * const profile = await otherRepo.profile.getBskyProfile();
      *
      * // List their public hypercerts
      * const hypercerts = await otherRepo.hypercerts.list();
@@ -6960,21 +7630,22 @@ class Repository {
      *
      * @example
      * ```typescript
-     * // Get current profile
-     * const profile = await repo.profile.get();
-     * console.log(profile.displayName);
+     * // Get Certified profile (with hypercerts fields)
+     * const certProfile = await repo.profile.getCertifiedProfile();
+     * console.log(certProfile.displayName);
+     * console.log(certProfile.pronouns);
      *
-     * // Update profile
-     * await repo.profile.update({
+     * // Update Certified profile
+     * await repo.profile.updateCertifiedProfile({
      *   displayName: "New Name",
-     *   description: "Updated bio",
+     *   pronouns: "they/them",
      *   avatar: avatarBlob,  // Optional: update avatar image
      * });
      * ```
      */
     get profile() {
         if (!this._profile) {
-            this._profile = new ProfileOperationsImpl(this.agent, this.repoDid, this.blobs);
+            this._profile = new ProfileOperationsImpl(this.agent, this.repoDid, this.blobs, this.serverUrl);
         }
         return this._profile;
     }
@@ -7231,25 +7902,11 @@ const OAuthConfigSchema = zod.z.object({
  * Zod schema for server URL configuration.
  *
  * @remarks
- * At least one server (PDS or SDS) should be configured for the SDK to be useful.
+ * Configure SDS here for collaborative operations.
+ * PDS URLs are auto-detected from the user's OAuth session and do not need configuration.
  * For local development, HTTP loopback URLs are allowed.
  */
 const ServerConfigSchema = zod.z.object({
-    /**
-     * Personal Data Server URL - the user's own AT Protocol server.
-     * This is the primary server for user data operations.
-     *
-     * @example Production
-     * ```typescript
-     * pds: "https://bsky.social"
-     * ```
-     *
-     * @example Local development
-     * ```typescript
-     * pds: "http://localhost:2583"
-     * ```
-     */
-    pds: urlOrLoopback.optional(),
     /**
      * Shared Data Server URL - for collaborative data storage.
      * Required for collaborator and organization operations.
@@ -7294,6 +7951,19 @@ const TimeoutConfigSchema = zod.z.object({
  */
 const ATProtoSDKConfigSchema = zod.z.object({
     oauth: OAuthConfigSchema,
+    /**
+     * URL string used for resolving AT Protocol handles to DIDs
+     * during the OAuth authorization flow. This can be any server that speaks
+     * the `com.atproto.identity.resolveHandle` XRPC method.
+     *
+     * If not provided, the `@atproto` library falls back to DNS-based handle resolution.
+     *
+     * @example
+     * ```typescript
+     * handleResolver: "https://pds-eu-west4.test.certified.app"
+     * ```
+     */
+    handleResolver: urlOrLoopback.optional(),
     servers: ServerConfigSchema.optional(),
     timeouts: TimeoutConfigSchema.optional(),
 });
@@ -7318,8 +7988,8 @@ const ATProtoSDKConfigSchema = zod.z.object({
  *     jwksUri: "https://my-app.com/.well-known/jwks.json",
  *     jwkPrivate: process.env.JWK_PRIVATE_KEY!,
  *   },
+ *   handleResolver: "https://bsky.social",
  *   servers: {
- *     pds: "https://bsky.social",
  *     sds: "https://sds.hypercerts.org",
  *   },
  * });
@@ -7371,11 +8041,13 @@ class ATProtoSDK {
      *     jwksUri: "https://my-app.com/.well-known/jwks.json",
      *     jwkPrivate: privateKeyJwk,
      *   },
-     *   servers: { pds: "https://bsky.social" },
+     *   handleResolver: "https://pds-eu-west4.test.certified.app",
      * });
      * ```
      */
     constructor(config) {
+        /** Cache of session DID → PDS URL, populated during callback/restoreSession */
+        this.sessionPdsMap = new Map();
         // Validate configuration
         const validationResult = ATProtoSDKConfigSchema.safeParse(config);
         if (!validationResult.success) {
@@ -7464,7 +8136,18 @@ class ATProtoSDK {
      * ```
      */
     async callback(params) {
-        return this.oauthClient.callback(params);
+        const session = await this.oauthClient.callback(params);
+        // Cache the user's actual PDS URL from the token
+        try {
+            const tokenInfo = await session.getTokenInfo();
+            if (tokenInfo.aud) {
+                this.sessionPdsMap.set(session.did, tokenInfo.aud);
+            }
+        }
+        catch {
+            this.logger?.warn?.("Could not resolve PDS URL from session token during callback");
+        }
+        return session;
     }
     /**
      * Restores an existing OAuth session by DID.
@@ -7498,7 +8181,20 @@ class ATProtoSDK {
         if (!did || !did.trim()) {
             throw new ValidationError("DID is required");
         }
-        return this.oauthClient.restore(did.trim());
+        const session = await this.oauthClient.restore(did.trim());
+        if (session) {
+            // Cache the user's actual PDS URL from the token
+            try {
+                const tokenInfo = await session.getTokenInfo();
+                if (tokenInfo.aud) {
+                    this.sessionPdsMap.set(session.did, tokenInfo.aud);
+                }
+            }
+            catch {
+                this.logger?.warn?.("Could not resolve PDS URL from session token during restore");
+            }
+        }
+        return session;
     }
     /**
      * Revokes an OAuth session, logging the user out.
@@ -7573,13 +8269,9 @@ class ATProtoSDK {
             throw new ValidationError("Session is required");
         }
         try {
-            // Determine PDS URL from session or config
-            const pdsUrl = this.config.servers?.pds;
-            if (!pdsUrl) {
-                throw new ValidationError("PDS server URL not configured");
-            }
             // Call com.atproto.server.getSession endpoint using session's fetchHandler
-            // which automatically includes proper authorization with DPoP
+            // which automatically includes proper authorization with DPoP.
+            // The session internally routes this to the user's actual PDS via tokenSet.aud.
             const response = await session.fetchHandler("/xrpc/com.atproto.server.getSession", {
                 method: "GET",
                 headers: {
@@ -7626,7 +8318,7 @@ class ATProtoSDK {
      * @example Using default PDS
      * ```typescript
      * const repo = sdk.repository(session);
-     * const profile = await repo.profile.get();
+     * const profile = await repo.profile.getBskyProfile();
      * ```
      *
      * @example Using configured SDS
@@ -7642,7 +8334,7 @@ class ATProtoSDK {
      * });
      * ```
      */
-    repository(session, options) {
+    async repository(session, options) {
         if (!session) {
             throw new ValidationError("Session is required");
         }
@@ -7664,11 +8356,20 @@ class ATProtoSDK {
             isSDS = true;
         }
         else if (options?.server === "pds" || !options?.server) {
-            // Use configured PDS (default)
-            if (!this.config.servers?.pds) {
-                throw new ValidationError("PDS server URL not configured");
+            // Auto-detect PDS from cached session info
+            const did = session.did || session.sub;
+            let cachedPds = this.sessionPdsMap.get(did);
+            if (!cachedPds) {
+                // Try to resolve on the fly before giving up
+                try {
+                    cachedPds = await this.resolveSessionPds(session);
+                }
+                catch {
+                    throw new ValidationError("Could not determine PDS URL. Ensure the session has valid token info, " +
+                        "or was created via SDK auth methods (callback/restoreSession).");
+                }
             }
-            serverUrl = this.config.servers.pds;
+            serverUrl = cachedPds;
             isSDS = false;
         }
         else {
@@ -7709,12 +8410,52 @@ class ATProtoSDK {
         return this.lexiconRegistry;
     }
     /**
-     * The configured PDS (Personal Data Server) URL.
+     * Resolves and caches the PDS URL from a session's token info.
+     *
+     * This method is automatically called during `callback()` and `restoreSession()`.
+     * Use it manually if you have a session obtained outside the SDK's auth flow
+     * and need to enable PDS auto-detection for `repository()`.
+     *
+     * @param session - An authenticated OAuth session
+     * @returns The resolved PDS URL
+     * @throws {@link ValidationError} if the PDS URL cannot be determined from the session
+     *
+     * @example
+     * ```typescript
+     * // For sessions created outside the SDK auth flow
+     * const pdsUrl = await sdk.resolveSessionPds(session);
+     * const repo = sdk.repository(session); // Now works with auto-detected PDS
+     * ```
+     */
+    async resolveSessionPds(session) {
+        try {
+            const tokenInfo = await session.getTokenInfo();
+            if (tokenInfo.aud) {
+                this.sessionPdsMap.set(session.did, tokenInfo.aud);
+                return tokenInfo.aud;
+            }
+            throw new ValidationError("Could not determine PDS URL from session token info");
+        }
+        catch (error) {
+            if (error instanceof ValidationError) {
+                throw error;
+            }
+            throw new ValidationError("Could not determine PDS URL from session token info", error);
+        }
+    }
+    /**
+     * Gets the cached PDS URL for a specific DID, if available.
+     *
+     * @param did - The user's DID
+     * @returns The cached PDS URL, or `undefined` if not cached
      *
-     * @returns The PDS URL if configured, otherwise `undefined`
+     * @deprecated Use `resolveSessionPds()` to resolve and cache PDS URLs.
+     * This getter is provided for backward compatibility with sdk-react.
      */
     get pdsUrl() {
-        return this.config.servers?.pds;
+        // Return the first cached PDS URL for backward compat with sdk-react
+        const firstEntry = this.sessionPdsMap.values().next();
+        return firstEntry.done ? undefined : firstEntry.value;
     }
     /**
      * The configured SDS (Shared Data Server) URL.
@@ -7739,7 +8480,7 @@ class ATProtoSDK {
  *
  * const sdk = createATProtoSDK({
  *   oauth: { ... },
- *   servers: { pds: "https://bsky.social" },
+ *   handleResolver: "https://bsky.social",
  * });
  * ```
  */
@@ -8006,300 +8747,79 @@ class BaseOperations {
      * results of create or update operations.
      *
      * @param result - Result from a create or update operation
-     * @returns StrongRef object with uri and cid properties
-     *
-     * @example
-     * ```typescript
-     * // Create a project
-     * const projectResult = await this.validateAndCreate("org.myapp.project", projectRecord);
-     *
-     * // Create a task that references the project
-     * const taskRecord = {
-     *   $type: "org.myapp.task",
-     *   project: this.createStrongRefFromResult(projectResult),
-     *   title: "Implement feature",
-     *   createdAt: new Date().toISOString(),
-     * };
-     * ```
-     */
-    createStrongRefFromResult(result) {
-        return { uri: result.uri, cid: result.cid };
-    }
-    /**
-     * Parses an AT-URI to extract its components.
-     *
-     * AT-URIs follow the format: `at://{did}/{collection}/{rkey}`
-     *
-     * @param uri - AT-URI to parse
-     * @returns Object containing did, collection, and rkey
-     * @throws Error if the URI format is invalid
-     *
-     * @example
-     * ```typescript
-     * const { did, collection, rkey } = this.parseAtUri(
-     *   "at://did:plc:abc123/org.hypercerts.claim.activity/xyz789"
-     * );
-     * // did: "did:plc:abc123"
-     * // collection: "org.hypercerts.claim.activity"
-     * // rkey: "xyz789"
-     * ```
-     */
-    parseAtUri(uri) {
-        if (!uri.startsWith("at://")) {
-            throw new Error(`Invalid AT-URI format: ${uri}`);
-        }
-        const parts = uri.slice(5).split("/"); // Remove "at://" and split
-        if (parts.length !== 3) {
-            throw new Error(`Invalid AT-URI format: ${uri}`);
-        }
-        return {
-            did: parts[0],
-            collection: parts[1],
-            rkey: parts[2],
-        };
-    }
-    /**
-     * Builds an AT-URI from its components.
-     *
-     * @param did - DID of the repository
-     * @param collection - NSID of the collection
-     * @param rkey - Record key (typically a TID)
-     * @returns Complete AT-URI string
-     *
-     * @example
-     * ```typescript
-     * const uri = this.buildAtUri(
-     *   "did:plc:abc123",
-     *   "org.myapp.evaluation",
-     *   "xyz789"
-     * );
-     * // Returns: "at://did:plc:abc123/org.myapp.evaluation/xyz789"
-     * ```
-     */
-    buildAtUri(did, collection, rkey) {
-        return `at://${did}/${collection}/${rkey}`;
-    }
-}
-
-/**
- * Lexicon Development Utilities - AT-URI and StrongRef Helpers
- *
- * This module provides utilities for working with AT Protocol URIs and strongRefs
- * when building custom lexicons. These tools help developers create type-safe
- * references between records.
- *
- * @packageDocumentation
- */
-/**
- * Parse an AT-URI into its component parts.
- *
- * Extracts the DID, collection NSID, and record key from an AT-URI string.
- * AT-URIs follow the format: `at://{did}/{collection}/{rkey}`
- *
- * @param uri - The AT-URI to parse
- * @returns The components of the URI
- * @throws {Error} If the URI format is invalid
- *
- * @example
- * ```typescript
- * const components = parseAtUri("at://did:plc:abc123/org.hypercerts.claim.activity/3km2vj4kfqp2a");
- * console.log(components);
- * // {
- * //   did: "did:plc:abc123",
- * //   collection: "org.hypercerts.claim.activity",
- * //   rkey: "3km2vj4kfqp2a"
- * // }
- * ```
- */
-function parseAtUri(uri) {
-    if (!uri.startsWith("at://")) {
-        throw new Error(`Invalid AT-URI format: must start with "at://", got "${uri}"`);
-    }
-    const withoutProtocol = uri.slice(5); // Remove "at://"
-    const parts = withoutProtocol.split("/");
-    if (parts.length !== 3) {
-        throw new Error(`Invalid AT-URI format: expected "at://{did}/{collection}/{rkey}", got "${uri}"`);
-    }
-    const [did, collection, rkey] = parts;
-    if (!did || !collection || !rkey) {
-        throw new Error(`Invalid AT-URI format: all components must be non-empty, got "${uri}"`);
-    }
-    return { did, collection, rkey };
-}
-/**
- * Build an AT-URI from its component parts.
- *
- * Constructs a valid AT-URI string from a DID, collection NSID, and record key.
- * The resulting URI follows the format: `at://{did}/{collection}/{rkey}`
- *
- * @param did - The repository owner's DID
- * @param collection - The collection NSID (lexicon identifier)
- * @param rkey - The record key (TID or custom string)
- * @returns The complete AT-URI
- *
- * @example
- * ```typescript
- * const uri = buildAtUri(
- *   "did:plc:abc123",
- *   "org.hypercerts.claim.activity",
- *   "3km2vj4kfqp2a"
- * );
- * console.log(uri); // "at://did:plc:abc123/org.hypercerts.claim.activity/3km2vj4kfqp2a"
- * ```
- */
-function buildAtUri(did, collection, rkey) {
-    if (!did || !collection || !rkey) {
-        throw new Error("All AT-URI components (did, collection, rkey) must be non-empty");
-    }
-    return `at://${did}/${collection}/${rkey}`;
-}
-/**
- * Extract the record key (TID or custom key) from an AT-URI.
- *
- * Returns the last component of the AT-URI, which is the record key.
- * This is equivalent to `parseAtUri(uri).rkey` but more efficient.
- *
- * @param uri - The AT-URI to extract from
- * @returns The record key (TID or custom string)
- * @throws {Error} If the URI format is invalid
- *
- * @example
- * ```typescript
- * const rkey = extractRkeyFromUri("at://did:plc:abc123/org.hypercerts.claim.activity/3km2vj4kfqp2a");
- * console.log(rkey); // "3km2vj4kfqp2a"
- * ```
- */
-function extractRkeyFromUri(uri) {
-    const { rkey } = parseAtUri(uri);
-    return rkey;
-}
-/**
- * Check if a string is a valid AT-URI format.
- *
- * Validates that the string follows the AT-URI format without throwing errors.
- * This is useful for input validation before parsing.
- *
- * @param uri - The string to validate
- * @returns True if the string is a valid AT-URI, false otherwise
- *
- * @example
- * ```typescript
- * if (isValidAtUri(userInput)) {
- *   const components = parseAtUri(userInput);
- *   // ... use components
- * } else {
- *   console.error("Invalid AT-URI");
- * }
- * ```
- */
-function isValidAtUri(uri) {
-    try {
-        parseAtUri(uri);
-        return true;
-    }
-    catch {
-        return false;
-    }
-}
-/**
- * Create a strongRef from a URI and CID.
- *
- * StrongRefs are the canonical way to reference specific versions of records
- * in AT Protocol. They combine an AT-URI (which identifies the record) with
- * a CID (which identifies the specific version).
- *
- * @param uri - The AT-URI of the record
- * @param cid - The CID (Content Identifier) of the record version
- * @returns A strongRef object
- *
- * @example
- * ```typescript
- * const ref = createStrongRef(
- *   "at://did:plc:abc123/org.hypercerts.claim.activity/3km2vj4kfqp2a",
- *   "bafyreiabc123..."
- * );
- * console.log(ref);
- * // {
- * //   uri: "at://did:plc:abc123/org.hypercerts.claim.activity/3km2vj4kfqp2a",
- * //   cid: "bafyreiabc123..."
- * // }
- * ```
- */
-function createStrongRef(uri, cid) {
-    if (!uri || !cid) {
-        throw new Error("Both uri and cid are required to create a strongRef");
+     * @returns StrongRef object with uri and cid properties
+     *
+     * @example
+     * ```typescript
+     * // Create a project
+     * const projectResult = await this.validateAndCreate("org.myapp.project", projectRecord);
+     *
+     * // Create a task that references the project
+     * const taskRecord = {
+     *   $type: "org.myapp.task",
+     *   project: this.createStrongRefFromResult(projectResult),
+     *   title: "Implement feature",
+     *   createdAt: new Date().toISOString(),
+     * };
+     * ```
+     */
+    createStrongRefFromResult(result) {
+        return { uri: result.uri, cid: result.cid };
     }
-    return { uri, cid };
-}
-/**
- * Create a strongRef from a CreateResult or UpdateResult.
- *
- * This is a convenience function that extracts the URI and CID from
- * the result of a record creation or update operation.
- *
- * @param result - The result from creating or updating a record
- * @returns A strongRef object
- *
- * @example
- * ```typescript
- * const hypercert = await repo.hypercerts.create({
- *   title: "Climate Research",
- *   // ... other params
- * });
- *
- * const ref = createStrongRefFromResult(hypercert);
- * // Now use ref in another record to reference this hypercert
- * ```
- */
-function createStrongRefFromResult(result) {
-    return createStrongRef(result.uri, result.cid);
-}
-/**
- * Validate that an object is a valid strongRef.
- *
- * Checks that the object has the required `uri` and `cid` properties
- * and that they are non-empty strings.
- *
- * @param ref - The object to validate
- * @returns True if the object is a valid strongRef, false otherwise
- *
- * @example
- * ```typescript
- * const maybeRef = { uri: "at://...", cid: "bafyrei..." };
- * if (validateStrongRef(maybeRef)) {
- *   // Safe to use as strongRef
- *   record.subject = maybeRef;
- * }
- * ```
- */
-function validateStrongRef(ref) {
-    if (!ref || typeof ref !== "object") {
-        return false;
+    /**
+     * Parses an AT-URI to extract its components.
+     *
+     * AT-URIs follow the format: `at://{did}/{collection}/{rkey}`
+     *
+     * @param uri - AT-URI to parse
+     * @returns Object containing did, collection, and rkey
+     * @throws Error if the URI format is invalid
+     *
+     * @example
+     * ```typescript
+     * const { did, collection, rkey } = this.parseAtUri(
+     *   "at://did:plc:abc123/org.hypercerts.claim.activity/xyz789"
+     * );
+     * // did: "did:plc:abc123"
+     * // collection: "org.hypercerts.claim.activity"
+     * // rkey: "xyz789"
+     * ```
+     */
+    parseAtUri(uri) {
+        if (!uri.startsWith("at://")) {
+            throw new Error(`Invalid AT-URI format: ${uri}`);
+        }
+        const parts = uri.slice(5).split("/"); // Remove "at://" and split
+        if (parts.length !== 3) {
+            throw new Error(`Invalid AT-URI format: ${uri}`);
+        }
+        return {
+            did: parts[0],
+            collection: parts[1],
+            rkey: parts[2],
+        };
+    }
+    /**
+     * Builds an AT-URI from its components.
+     *
+     * @param did - DID of the repository
+     * @param collection - NSID of the collection
+     * @param rkey - Record key (typically a TID)
+     * @returns Complete AT-URI string
+     *
+     * @example
+     * ```typescript
+     * const uri = this.buildAtUri(
+     *   "did:plc:abc123",
+     *   "org.myapp.evaluation",
+     *   "xyz789"
+     * );
+     * // Returns: "at://did:plc:abc123/org.myapp.evaluation/xyz789"
+     * ```
+     */
+    buildAtUri(did, collection, rkey) {
+        return `at://${did}/${collection}/${rkey}`;
     }
-    const obj = ref;
-    return typeof obj.uri === "string" && obj.uri.length > 0 && typeof obj.cid === "string" && obj.cid.length > 0;
-}
-/**
- * Type guard to check if a value is a strongRef.
- *
- * This is an alias for `validateStrongRef` that provides better semantics
- * for type narrowing in TypeScript.
- *
- * @param value - The value to check
- * @returns True if the value is a strongRef, false otherwise
- *
- * @example
- * ```typescript
- * function processReference(ref: unknown) {
- *   if (isStrongRef(ref)) {
- *     // TypeScript knows ref is StrongRef here
- *     console.log(ref.uri);
- *   }
- * }
- * ```
- */
-function isStrongRef(value) {
-    return validateStrongRef(value);
 }
 
 /**
@@ -8834,121 +9354,6 @@ async function batchCreateSidecars(repo, sidecars) {
     return results;
 }
 
-/**
- * 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.
- */
-const CollaboratorPermissionsSchema = zod.z.object({
-    /**
-     * Can read/view records in the repository.
-     * This is the most basic permission level.
-     */
-    read: zod.z.boolean(),
-    /**
-     * Can create new records in the repository.
-     * Typically implies `read` permission.
-     */
-    create: zod.z.boolean(),
-    /**
-     * Can modify existing records in the repository.
-     * Typically implies `read` and `create` permissions.
-     */
-    update: zod.z.boolean(),
-    /**
-     * Can delete records from the repository.
-     * Typically implies `read`, `create`, and `update` permissions.
-     */
-    delete: zod.z.boolean(),
-    /**
-     * Can manage collaborators and their permissions.
-     * Administrative permission that allows inviting/removing collaborators.
-     */
-    admin: zod.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: zod.z.boolean(),
-});
-/**
- * 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.
- */
-const OrganizationSchema = zod.z.object({
-    /**
-     * The organization's DID - unique identifier.
-     * Format: "did:plc:..." or "did:web:..."
-     */
-    did: zod.z.string(),
-    /**
-     * The organization's handle - human-readable identifier.
-     * Format: "orgname.sds.hypercerts.org" or similar
-     */
-    handle: zod.z.string(),
-    /**
-     * Display name for the organization.
-     */
-    name: zod.z.string(),
-    /**
-     * Optional description of the organization's purpose.
-     */
-    description: zod.z.string().optional(),
-    /**
-     * ISO 8601 timestamp when the organization was created.
-     * Format: "2024-01-15T10:30:00.000Z"
-     */
-    createdAt: zod.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: zod.z.enum(["owner", "shared", "none"]),
-});
-/**
- * Zod schema for collaborator data.
- *
- * Represents a user who has been granted access to a shared repository
- * or organization with specific permissions.
- */
-const CollaboratorSchema = zod.z.object({
-    /**
-     * The collaborator's DID - their unique identifier.
-     * Format: "did:plc:..." or "did:web:..."
-     */
-    userDid: zod.z.string(),
-    /**
-     * The permissions granted to this collaborator.
-     */
-    permissions: CollaboratorPermissionsSchema,
-    /**
-     * DID of the user who granted these permissions.
-     * Useful for audit trails.
-     */
-    grantedBy: zod.z.string(),
-    /**
-     * ISO 8601 timestamp when permissions were granted.
-     * Format: "2024-01-15T10:30:00.000Z"
-     */
-    grantedAt: zod.z.string(),
-    /**
-     * ISO 8601 timestamp when permissions were revoked, if applicable.
-     * Undefined if the collaborator is still active.
-     */
-    revokedAt: zod.z.string().optional(),
-});
-
 /**
  * Rich text utilities for creating facets from plain text.
  *
@@ -9154,6 +9559,7 @@ exports.ATPROTO_SCOPE = ATPROTO_SCOPE;
 exports.ATProtoSDK = ATProtoSDK;
 exports.ATProtoSDKConfigSchema = ATProtoSDKConfigSchema;
 exports.ATProtoSDKError = ATProtoSDKError;
+exports.AT_URI_REGEX = AT_URI_REGEX;
 exports.AccountActionSchema = AccountActionSchema;
 exports.AccountAttrSchema = AccountAttrSchema;
 exports.AccountPermissionSchema = AccountPermissionSchema;
@@ -9212,12 +9618,16 @@ exports.createStrongRef = createStrongRef;
 exports.createStrongRefField = createStrongRefField;
 exports.createStrongRefFromResult = createStrongRefFromResult;
 exports.createWithSidecars = createWithSidecars;
+exports.extractCidFromImage = extractCidFromImage;
 exports.extractRkeyFromUri = extractRkeyFromUri;
+exports.getBlobUrl = getBlobUrl;
 exports.hasAllPermissions = hasAllPermissions;
 exports.hasAnyPermission = hasAnyPermission;
 exports.hasPermission = hasPermission;
 exports.isStrongRef = isStrongRef;
 exports.isValidAtUri = isValidAtUri;
+exports.isValidDid = isValidDid;
+exports.isValidUri = isValidUri;
 exports.mergeScopes = mergeScopes;
 exports.parseAtUri = parseAtUri;
 exports.parseScope = parseScope;