@happyvertical/smrt-profiles 0.51.31 → 0.51.33

package/dist/utils.d.ts

@@ -1,823 +1,58 @@
-import { Asset } from '@happyvertical/smrt-assets';
-import { SmrtObject } from '@happyvertical/smrt-core';
-import { SmrtObjectOptions } from '@happyvertical/smrt-core';
-
-declare class ApiKey extends SmrtObject {
-    /**
-     * Link to the Profile (Person, Organization, Bot)
-     */
-    profileId?: string;
-    /**
-     * SHA-256 hash of the API key.
-     *
-     * Indexed: `verify()` looks keys up by this hash on every authenticated
-     * request (#2364, epic #2382 finding A3).
-     */
-    keyHash: string;
-    /**
-     * First 8 characters of the key for identification (e.g., "sk_live_a1b2...")
-     */
-    keyPrefix: string;
-    /**
-     * Human-readable name for the key (e.g., "CI Bot", "Local CLI")
-     */
-    name: string;
-    /**
-     * Scopes/permissions for this key
-     */
-    scopes: string[];
-    /**
-     * Last time this key was used
-     */
-    lastUsedAt: Date | null;
-    /**
-     * When this key expires (null = never)
-     */
-    expiresAt: Date | null;
-    /**
-     * When this key was revoked (null = active)
-     */
-    revokedAt: Date | null;
-    constructor(options?: ApiKeyOptions);
-    /**
-     * Get the linked Profile
-     */
-    getProfile(): Promise<Profile | null>;
-    /**
-     * Check if this key is valid (not expired, not revoked)
-     */
-    isValid(): boolean;
-    /**
-     * Check if this key has a specific scope
-     */
-    hasScope(scope: string): boolean;
-    /**
-     * Revoke this key
-     */
-    revoke(): Promise<void>;
-    /**
-     * Record usage of this key
-     */
-    recordUsage(): Promise<void>;
-    /**
-     * Hash an API key
-     */
-    static hashKey(key: string): string;
-    /**
-     * Generate a new API key for a profile
-     */
-    static generate(profile: Profile, options: {
-        name: string;
-        scopes?: string[];
-        expiresAt?: Date | null;
-        db?: SmrtObjectOptions['db'];
-    }): Promise<GenerateKeyResult>;
-    /**
-     * Verify an API key and return the ApiKey record if valid
-     */
-    static verify(key: string, options?: SmrtObjectOptions): Promise<ApiKey | null>;
-}
-
-declare interface ApiKeyOptions extends SmrtObjectOptions {
-    profileId?: string;
-    name?: string;
-    scopes?: string[];
-    expiresAt?: Date | null;
-}
-
-declare class AuditLog extends SmrtObject {
-    tenantId: string | null;
-    /**
-     * The profile who performed the action
-     */
-    profileId?: string;
-    /**
-     * Action performed (e.g., 'issue.update', 'feedback.incorporate')
-     */
-    action: string;
-    /**
-     * Type of resource affected (e.g., 'Issue', 'Repository')
-     */
-    resourceType: string;
-    /**
-     * ID of the affected resource
-     */
-    resourceId: string;
-    /**
-     * Source of the action
-     */
-    source: AuditSource;
-    /**
-     * Additional context (CI run ID, request ID, etc.)
-     */
-    metadata: Record<string, unknown>;
-    /**
-     * For pass-through identity in CI - the actual person who triggered
-     */
-    onBehalfOfId?: string | null;
-    constructor(options?: AuditLogOptions);
-    /**
-     * Get the profile who performed the action
-     */
-    getProfile(): Promise<Profile | null>;
-    /**
-     * Get the profile on whose behalf the action was performed (if any)
-     */
-    getOnBehalfOf(): Promise<Profile | null>;
-    /**
-     * Get the effective actor (onBehalfOf if set, otherwise profile)
-     */
-    getEffectiveActor(): Promise<Profile | null>;
-    /**
-     * Create an audit log entry
-     */
-    static record(options: AuditLogOptions & {
-        profile: Profile;
-        onBehalfOf?: Profile | null;
-    }): Promise<AuditLog>;
-}
-
-declare interface AuditLogOptions extends SmrtObjectOptions {
-    profileId?: string;
-    action?: string;
-    resourceType?: string;
-    resourceId?: string;
-    source?: AuditSource;
-    metadata?: Record<string, unknown>;
-    onBehalfOfId?: string | null;
-    tenantId?: string | null;
-}
-
-declare type AuditSource = 'web' | 'cli' | 'ci' | 'webhook' | 'mcp';
-
-/**
- * Create a reciprocal relationship between two profiles
- *
- * This is a convenience function that creates a relationship and automatically
- * handles the reciprocal relationship based on the relationship type configuration.
- *
- * @param fromProfile - The initiating profile
- * @param toProfile - The target profile
- * @param relationshipSlug - The type of relationship
- * @param contextProfile - Optional context profile for tertiary relationships
- */
-export declare function createReciprocalRelationship(fromProfile: Profile, toProfile: Profile, relationshipSlug: string, contextProfile?: Profile): Promise<void>;
-
-/**
- * Find profiles with a specific metadata key-value pair
- *
- * @param metafieldSlug - The slug of the metafield to search
- * @param value - The value to match
- * @param options - Database and configuration options
- * @returns Array of matching profile IDs
- */
-export declare function findProfilesByMeta(metafieldSlug: string, value: unknown, options?: SmrtObjectOptions): Promise<string[]>;
-
-declare interface GenerateKeyResult {
-    key: string;
-    apiKey: ApiKey;
-}
-
-/**
- * Retrieve all metadata for a profile as a key-value object
- *
- * @param profileId - The UUID of the profile
- * @param options - Database and configuration options
- * @returns Object with metafield slugs as keys and values as values
- */
-export declare function getProfileMetadata(profileId: string, options?: SmrtObjectOptions): Promise<Record<string, string>>;
-
-declare class NostrIdentity extends SmrtObject {
-    /**
-     * Link to the Profile (Person, Organization, Bot)
-     */
-    profileId?: string;
-    /**
-     * Hex-encoded secp256k1 public key (64 characters).
-     *
-     * Indexed: `findByPubkey()` looks identities up by this column (#2364,
-     * epic #2382 finding A3).
-     */
-    pubkey: string;
-    /**
-     * AES-256-GCM encrypted private key (base64-encoded ciphertext)
-     */
-    encryptedPrivkey: string;
-    /**
-     * Initialization vector for AES-GCM decryption (base64)
-     */
-    encryptionIv: string;
-    /**
-     * Authentication tag from AES-GCM (base64)
-     */
-    encryptionTag: string;
-    /**
-     * Email address associated with this identity
-     */
-    email: string;
-    /**
-     * Username for NIP-05 verification (e.g., "alice" for alice@domain.com)
-     */
-    nip05Username: string;
-    /**
-     * Last time this identity was used for authentication
-     */
-    lastUsedAt: Date | null;
-    /**
-     * When this identity was verified via magic link
-     */
-    verifiedAt: Date | null;
-    constructor(options?: NostrIdentityOptions);
-    /**
-     * Get the linked Profile
-     */
-    getProfile(): Promise<Profile | null>;
-    /**
-     * Find identity by public key
-     */
-    static findByPubkey(pubkey: string, options?: SmrtObjectOptions): Promise<NostrIdentity | null>;
-    /**
-     * Find identity by email
-     */
-    static findByEmail(email: string, options?: SmrtObjectOptions): Promise<NostrIdentity | null>;
-    /**
-     * Find identity by NIP-05 username
-     */
-    static findByNip05(username: string, options?: SmrtObjectOptions): Promise<NostrIdentity | null>;
-    /**
-     * Decrypt the private key using the server master secret
-     * @param masterSecret - SERVER_MASTER_SECRET from environment
-     * @returns Hex-encoded private key
-     */
-    decryptPrivkey(masterSecret: string): string;
-    /**
-     * Get the full keypair (requires master secret)
-     * @param masterSecret - SERVER_MASTER_SECRET from environment
-     */
-    getKeypair(masterSecret: string): {
-        pubkey: string;
-        privkey: string;
-        npub: string;
-        nsec: string;
-    };
-    /**
-     * Record usage of this identity
-     */
-    recordUsage(): Promise<void>;
-    /**
-     * Mark this identity as verified
-     */
-    markVerified(): Promise<void>;
-    /**
-     * Check if this identity is verified
-     */
-    isVerified(): boolean;
-    /**
-     * Get the NIP-05 identifier (username@domain)
-     * Note: Domain must be provided by the application
-     */
-    getNip05Identifier(domain: string): string;
-}
-
-declare interface NostrIdentityOptions extends SmrtObjectOptions {
-    profileId?: string;
-    pubkey?: string;
-    encryptedPrivkey?: string;
-    encryptionIv?: string;
-    encryptionTag?: string;
-    email?: string;
-    nip05Username?: string;
-    lastUsedAt?: Date | null;
-    verifiedAt?: Date | null;
-}
-
-declare class OidcIdentity extends SmrtObject {
-    /**
-     * Link to the Profile (Person, Organization, Bot)
-     */
-    profileId?: string;
-    /**
-     * Provider name (e.g., 'keycloak', 'google', 'github')
-     */
-    provider: string;
-    /**
-     * OIDC issuer URL (e.g., https://keycloak.example.com/realms/bmp)
-     */
-    issuer: string;
-    /**
-     * OIDC subject claim - unique identifier from the provider
-     */
-    subject: string;
-    /**
-     * Stable issuer+subject key used as the database race arbiter.
-     *
-     * Nullable for legacy rows; every newly linked or reused identity backfills
-     * it. A separate unique constraint makes concurrent first login fail with a
-     * retryable conflict instead of creating two identities.
-     */
-    identityKey: string | null;
-    /**
-     * Cached email from the IdP (for display/lookup)
-     */
-    email: string;
-    /**
-     * Last time this identity was used for authentication
-     */
-    lastUsedAt: Date | null;
-    constructor(options?: OidcIdentityOptions);
-    /**
-     * Get the linked Profile
-     */
-    getProfile(): Promise<Profile | null>;
-    /**
-     * Find identity by issuer and subject
-     */
-    static findBySubject(issuer: string, subject: string, options?: SmrtObjectOptions): Promise<OidcIdentity | null>;
-    /** Build the collision-free natural key for one OIDC issuer subject. */
-    static buildIdentityKey(issuer: string, subject: string): string;
-    /** Keep the durable key derived from its natural-key source fields. */
-    save(): Promise<this>;
-    /**
-     * Reuse an existing exact identity for its unchanged Profile.
-     *
-     * @deprecated Authentication links must be created through transactional
-     * provisioning. This compatibility method only refreshes a unique mapping
-     * that already belongs to the supplied Profile, including legacy Profile
-     * types, and deliberately refuses to create or rebind authority.
-     */
-    static findOrCreate(profile: Profile, oidcData: {
-        provider: string;
-        issuer: string;
-        subject: string;
-        email?: string;
-    }, options?: SmrtObjectOptions): Promise<OidcIdentity>;
-    /**
-     * Record usage of this identity
-     */
-    recordUsage(): Promise<void>;
-}
-
-declare interface OidcIdentityOptions extends SmrtObjectOptions {
-    profileId?: string;
-    provider?: string;
-    issuer?: string;
-    subject?: string;
-    email?: string;
-    lastUsedAt?: Date | null;
-}
-
-declare class Profile extends SmrtObject {
-    tenantId: string | null;
-    typeId?: string;
-    email?: string;
-    /** Adapter-independent identity lookup key derived from email on save. */
-    emailKey: string | null;
-    name: string;
-    description?: string;
-    metadata: ProfileMetadata[];
-    relationshipsFrom: ProfileRelationship[];
-    relationshipsTo: ProfileRelationship[];
-    constructor(options?: ProfileOptions);
-    /** Keep the durable identity key derived from the public email field. */
-    save(): Promise<this>;
-    /**
-     * Get the profile type slug for this profile
-     *
-     * @returns The slug of the profile type
-     */
-    getTypeSlug(): Promise<string>;
-    /**
-     * Set the profile type by slug
-     *
-     * @param slug - The slug of the profile type
-     * @throws Error if profile type not found
-     */
-    setTypeBySlug(slug: string): Promise<void>;
-    /**
-     * Add metadata to this profile
-     *
-     * @param metafieldSlug - The slug of the metafield
-     * @param value - The value to set
-     */
-    addMetadata(metafieldSlug: string, value: unknown): Promise<void>;
-    /**
-     * Get all metadata for this profile as key-value object
-     *
-     * @returns Object with metafield slugs as keys
-     */
-    getMetadata(): Promise<Record<string, string>>;
-    /**
-     * Update multiple metadata values
-     *
-     * @param metadata - Object with metafield slugs as keys and values
-     */
-    updateMetadata(metadata: Record<string, unknown>): Promise<void>;
-    /**
-     * Remove metadata by metafield slug
-     *
-     * @param metafieldSlug - The slug of the metafield to remove
-     */
-    removeMetadata(metafieldSlug: string): Promise<void>;
-    private getProfileAssetCollection;
-    getAssets(relationship?: string): Promise<Asset[]>;
-    addAsset(asset: Asset, relationship?: string, sortOrder?: number): Promise<void>;
-    removeAsset(assetId: string, relationship?: string): Promise<void>;
-    /**
-     * Add a relationship to another profile
-     *
-     * @param toProfile - The target profile
-     * @param relationshipSlug - The type of relationship
-     * @param contextProfile - Optional context profile for tertiary relationships
-     */
-    addRelationship(toProfile: Profile, relationshipSlug: string, contextProfile?: Profile): Promise<void>;
-    /**
-     * Get all relationships for this profile
-     *
-     * @param options - Filter options (typeSlug, direction)
-     * @returns Array of ProfileRelationship instances
-     */
-    getRelationships(options?: {
-        typeSlug?: string;
-        direction?: 'from' | 'to' | 'all';
-    }): Promise<ProfileRelationship[]>;
-    /**
-     * Get related profiles
-     *
-     * @param relationshipSlug - Optional filter by relationship type slug
-     * @returns Array of related Profile instances
-     */
-    getRelatedProfiles(relationshipSlug?: string): Promise<Profile[]>;
-    /**
-     * Remove a relationship to another profile
-     *
-     * @param toProfile - The target profile
-     * @param relationshipSlug - The type of relationship to remove
-     */
-    removeRelationship(toProfile: Profile, relationshipSlug: string): Promise<void>;
-    /**
-     * AI-powered: Generate a professional bio for this profile
-     *
-     * Uses the `smrtProfiles.profile.generateBio` prompt registered via
-     * `@happyvertical/smrt-prompts`, allowing tenant- or instance-level
-     * overrides of the template, model, and parameters at runtime.
-     *
-     * @returns Generated bio text
-     */
-    generateBio(): Promise<string>;
-    /**
-     * AI-powered: Check if profile matches criteria
-     *
-     * @param criteria - Criteria to match against
-     * @returns True if matches criteria
-     */
-    matches(criteria: string): Promise<boolean>;
-    /**
-     * Find profiles by metadata key-value pair
-     *
-     * @param metafieldSlug - The metafield slug to search
-     * @param value - The value to match
-     * @returns Array of matching profiles
-     */
-    static findByMetadata(_metafieldSlug: string, _value: unknown): Promise<Profile[]>;
-    /**
-     * Find profiles by type slug
-     *
-     * @param typeSlug - The profile type slug
-     * @returns Array of matching profiles
-     */
-    static findByType(_typeSlug: string): Promise<Profile[]>;
-    /**
-     * Find related profiles for a given profile
-     *
-     * @param profileId - The profile UUID
-     * @param relationshipSlug - Optional filter by relationship type
-     * @returns Array of related profiles
-     */
-    static findRelated(_profileId: string, _relationshipSlug?: string): Promise<Profile[]>;
-    /**
-     * Search profiles by email
-     *
-     * @param email - The email to search for
-     * @returns Profile or null if not found
-     */
-    static searchByEmail(_email: string): Promise<Profile | null>;
-    /**
-     * Get all API keys for this profile
-     *
-     * @returns Array of API keys
-     */
-    getApiKeys(): Promise<ApiKey[]>;
-    /**
-     * Get active (non-revoked, non-expired) API keys for this profile
-     *
-     * @returns Array of active API keys
-     */
-    getActiveApiKeys(): Promise<ApiKey[]>;
-    /**
-     * Generate a new API key for this profile
-     *
-     * @param options - Key options (name, scopes, expiration)
-     * @returns The generated key (plaintext) and ApiKey record
-     */
-    generateApiKey(options: {
-        name: string;
-        scopes?: string[];
-        expiresAt?: Date | null;
-    }): Promise<GenerateKeyResult>;
-    /**
-     * Get all OIDC identities linked to this profile
-     *
-     * @returns Array of OIDC identity records
-     */
-    getOidcIdentities(): Promise<OidcIdentity[]>;
-    /**
-     * Reuse an existing exact OIDC identity for this unchanged Profile.
-     *
-     * @param oidcData - OIDC provider data
-     * @returns The linked OIDC identity record
-     * @deprecated New authentication links require owner-aware transactional
-     * provisioning. This compatibility helper may refresh a legacy Profile
-     * type, but refuses to create or rebind authority.
-     */
-    linkOidcIdentity(oidcData: {
-        provider: string;
-        issuer: string;
-        subject: string;
-        email?: string;
-    }): Promise<OidcIdentity>;
-    /**
-     * Get all Nostr identities linked to this profile
-     *
-     * @returns Array of Nostr identity records
-     */
-    getNostrIdentities(): Promise<NostrIdentity[]>;
-    /**
-     * Link a new Nostr identity to this profile
-     *
-     * @param nostrData - Nostr identity data (encrypted keypair)
-     * @returns The linked Nostr identity record
-     */
-    linkNostrIdentity(nostrData: {
-        pubkey: string;
-        encryptedPrivkey: string;
-        encryptionIv: string;
-        encryptionTag: string;
-        email: string;
-        nip05Username?: string;
-    }): Promise<NostrIdentity>;
-    /**
-     * Get audit logs for actions performed by this profile
-     *
-     * @param limit - Maximum number of logs to return
-     * @returns Array of audit log entries
-     */
-    getAuditLogs(limit?: number): Promise<AuditLog[]>;
-    /**
-     * Record an audit log entry for an action by this profile
-     *
-     * @param options - Audit log options
-     * @returns The created audit log entry
-     */
-    recordAction(options: {
-        action: string;
-        resourceType: string;
-        resourceId: string;
-        source?: 'web' | 'cli' | 'ci' | 'webhook' | 'mcp';
-        metadata?: Record<string, unknown>;
-        onBehalfOf?: Profile | null;
-    }): Promise<AuditLog>;
-}
-
-declare class ProfileMetadata extends SmrtObject {
-    tenantId: string | null;
-    profileId?: string;
-    metafieldId?: string;
-    value: string;
-    constructor(options?: ProfileMetadataOptions);
-    /**
-     * Validate this metadata value against the metafield's validation schema
-     *
-     * @returns True if valid, throws error if invalid
-     */
-    validate(): Promise<boolean>;
-    /**
-     * Get the metafield slug for this metadata
-     *
-     * @returns The slug of the metafield
-     */
-    getMetafieldSlug(): Promise<string>;
-}
-
-declare interface ProfileMetadataOptions extends SmrtObjectOptions {
-    profileId?: string;
-    metafieldId?: string;
-    value?: string;
-    tenantId?: string | null;
-}
-
-declare class ProfileMetafield extends SmrtObject {
-    tenantId: string | null;
-    name: string;
-    description?: string;
-    validation?: ValidationSchema;
-    constructor(options?: ProfileMetafieldOptions);
-    /**
-     * Convenience method for slug-based lookup
-     *
-     * @param slug - The slug to search for
-     * @returns ProfileMetafield instance or null if not found
-     */
-    static getBySlug(_slug: string): Promise<ProfileMetafield | null>;
-    /**
-     * Register a custom validator function
-     *
-     * @param name - Name of the validator (used in validation.custom field)
-     * @param validator - The validator function
-     */
-    static registerValidator(name: string, validator: ValidatorFunction): void;
-    /**
-     * Get a registered custom validator
-     *
-     * @param name - Name of the validator
-     * @returns The validator function or undefined
-     */
-    static getValidator(name: string): ValidatorFunction | undefined;
-    /**
-     * Validate a value against this metafield's validation schema
-     *
-     * @param value - The value to validate
-     * @returns True if valid, throws ValidationError if invalid
-     */
-    validateValue(value: unknown): Promise<boolean>;
-}
-
-declare interface ProfileMetafieldOptions extends SmrtObjectOptions {
-    slug?: string;
-    name?: string;
-    description?: string;
-    validation?: ValidationSchema;
-    tenantId?: string | null;
-}
-
-declare interface ProfileOptions extends SmrtObjectOptions {
-    typeId?: string;
-    email?: string;
-    name?: string;
-    description?: string;
-    tenantId?: string | null;
-}
-
-declare class ProfileRelationship extends SmrtObject {
-    tenantId: string | null;
-    fromProfileId?: string;
-    toProfileId?: string;
-    typeId?: string;
-    contextProfileId?: string;
-    terms: ProfileRelationshipTerm[];
-    constructor(options?: ProfileRelationshipOptions);
-    /**
-     * Get the relationship type slug
-     *
-     * @returns The slug of the relationship type
-     */
-    getTypeSlug(): Promise<string>;
-    /**
-     * Add a term (time period) to this relationship
-     *
-     * @param startedAt - Start date of the term
-     * @param endedAt - Optional end date of the term
-     */
-    addTerm(startedAt: Date, endedAt?: Date): Promise<void>;
-    /**
-     * End the current active term
-     *
-     * @param endedAt - End date for the term
-     */
-    endCurrentTerm(endedAt: Date): Promise<void>;
-    /**
-     * Get all terms for this relationship
-     *
-     * @returns Array of ProfileRelationshipTerm instances
-     */
-    getTerms(): Promise<ProfileRelationshipTerm[]>;
-    /**
-     * Get the active term (no end date)
-     *
-     * @returns Current term or null if none active
-     */
-    getActiveTerm(): Promise<ProfileRelationshipTerm | null>;
-}
-
-declare interface ProfileRelationshipOptions extends SmrtObjectOptions {
-    fromProfileId?: string;
-    toProfileId?: string;
-    typeId?: string;
-    contextProfileId?: string;
-    tenantId?: string | null;
-}
-
-declare class ProfileRelationshipTerm extends SmrtObject {
-    relationshipId?: string;
-    startedAt: Date;
-    endedAt?: Date;
-    constructor(options?: ProfileRelationshipTermOptions);
-    /**
-     * Check if this term is currently active
-     *
-     * @returns True if active (no end date or end date in future)
-     */
-    isActive(): boolean;
-    /**
-     * End this term
-     *
-     * @param endedAt - End date for the term (defaults to now)
-     */
-    end(endedAt?: Date): Promise<void>;
-    /**
-     * Get the duration of this term in days
-     *
-     * @returns Duration in days
-     */
-    getDurationDays(): number;
-}
-
-declare interface ProfileRelationshipTermOptions extends SmrtObjectOptions {
-    relationshipId?: string;
-    startedAt?: Date;
-    endedAt?: Date;
-}
-
-/**
- * Set a single metadata value for a profile
- *
- * @param profileId - The UUID of the profile
- * @param metafieldSlug - The slug of the metafield
- * @param value - The value to set
- * @param options - Database and configuration options
- */
-export declare function setProfileMetadata(profileId: string, metafieldSlug: string, value: unknown, options?: SmrtObjectOptions): Promise<void>;
-
-/**
- * Validate a metadata value against a metafield's validation schema
- *
- * @param metafield - The metafield with validation rules
- * @param value - The value to validate
- * @returns True if valid, throws error if invalid
- */
-export declare function validateMetadataValue(metafield: ProfileMetafield, value: unknown): Promise<boolean>;
-
-/**
- * Validation schema structure for profile metadata fields
- */
-declare interface ValidationSchema {
-    /** Type constraint */
-    type?: 'string' | 'number' | 'boolean' | 'date' | 'json';
-    /** Regex pattern for string validation */
-    pattern?: string;
-    /** Minimum string length */
-    minLength?: number;
-    /** Maximum string length */
-    maxLength?: number;
-    /** Minimum numeric value */
-    min?: number;
-    /** Maximum numeric value */
-    max?: number;
-    /** Custom validator function name */
-    custom?: string;
-    /** Custom validation error message */
-    message?: string;
-}
-
-/**
- * Custom validator function type
- */
-declare type ValidatorFunction = (value: unknown) => boolean | Promise<boolean>;
-
-export { }
-
-
 /**
- * Extend globalThis to include custom validators registry.
- * Using globalThis ensures all module instances share the same validators,
- * which is critical in monorepos where the same package can be loaded
- * from different paths (e.g., pnpm store vs workspace symlink).
+ * Utility functions for profile operations
  *
- * @see https://github.com/happyvertical/smrt/issues/543
+ * Provides standalone helper functions for metadata management,
+ * relationship operations, and validation.
+ *
+ * @packageDocumentation
+ */
+import type { SmrtObjectOptions } from '@happyvertical/smrt-core';
+import type { Profile } from './models/Profile';
+import type { ProfileMetafield } from './models/ProfileMetafield';
+/**
+ * Retrieve all metadata for a profile as a key-value object
+ *
+ * @param profileId - The UUID of the profile
+ * @param options - Database and configuration options
+ * @returns Object with metafield slugs as keys and values as values
+ */
+export declare function getProfileMetadata(profileId: string, options?: SmrtObjectOptions): Promise<Record<string, string>>;
+/**
+ * Set a single metadata value for a profile
+ *
+ * @param profileId - The UUID of the profile
+ * @param metafieldSlug - The slug of the metafield
+ * @param value - The value to set
+ * @param options - Database and configuration options
+ */
+export declare function setProfileMetadata(profileId: string, metafieldSlug: string, value: unknown, options?: SmrtObjectOptions): Promise<void>;
+/**
+ * Find profiles with a specific metadata key-value pair
+ *
+ * @param metafieldSlug - The slug of the metafield to search
+ * @param value - The value to match
+ * @param options - Database and configuration options
+ * @returns Array of matching profile IDs
+ */
+export declare function findProfilesByMeta(metafieldSlug: string, value: unknown, options?: SmrtObjectOptions): Promise<string[]>;
+/**
+ * Create a reciprocal relationship between two profiles
+ *
+ * This is a convenience function that creates a relationship and automatically
+ * handles the reciprocal relationship based on the relationship type configuration.
+ *
+ * @param fromProfile - The initiating profile
+ * @param toProfile - The target profile
+ * @param relationshipSlug - The type of relationship
+ * @param contextProfile - Optional context profile for tertiary relationships
  */
-declare global {
-    var __smrtProfileMetafieldValidators: Map<string, ValidatorFunction> | undefined;
-}
-
-
+export declare function createReciprocalRelationship(fromProfile: Profile, toProfile: Profile, relationshipSlug: string, contextProfile?: Profile): Promise<void>;
 /**
- * Extend globalThis to include reciprocal handlers registry.
- * Using globalThis ensures all module instances share the same handlers,
- * which is critical in monorepos where the same package can be loaded
- * from different paths (e.g., pnpm store vs workspace symlink).
+ * Validate a metadata value against a metafield's validation schema
  *
- * @see https://github.com/happyvertical/smrt/issues/543
+ * @param metafield - The metafield with validation rules
+ * @param value - The value to validate
+ * @returns True if valid, throws error if invalid
  */
-declare global {
-    var __smrtProfileRelationshipHandlers: Map<string, ReciprocalHandler> | undefined;
-    var __smrtProfileRelationshipHandlersInitialized: boolean | undefined;
-}
+export declare function validateMetadataValue(metafield: ProfileMetafield, value: unknown): Promise<boolean>;
+//# sourceMappingURL=utils.d.ts.map