@happyvertical/smrt-profiles 0.35.1 → 0.35.3

package/dist/utils.d.ts

@@ -1,11 +1,151 @@
-/**
- * Utility functions for profile operations
- *
- * Provides standalone helper functions for metadata management,
- * relationship operations, and validation.
- *
- * @packageDocumentation
- */
+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
+     */
+    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
@@ -18,7 +158,7 @@
  * @param relationshipSlug - The type of relationship
  * @param contextProfile - Optional context profile for tertiary relationships
  */
-export declare function createReciprocalRelationship(fromProfile: any, toProfile: any, relationshipSlug: string, contextProfile?: any): Promise<void>;
+export declare function createReciprocalRelationship(fromProfile: Profile, toProfile: Profile, relationshipSlug: string, contextProfile?: Profile): Promise<void>;
 
 /**
  * Find profiles with a specific metadata key-value pair
@@ -28,7 +168,12 @@ export declare function createReciprocalRelationship(fromProfile: any, toProfile
  * @param options - Database and configuration options
  * @returns Array of matching profile IDs
  */
-export declare function findProfilesByMeta(metafieldSlug: string, value: any, options?: any): Promise<string[]>;
+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
@@ -37,7 +182,540 @@ export declare function findProfilesByMeta(metafieldSlug: string, value: any, op
  * @param options - Database and configuration options
  * @returns Object with metafield slugs as keys and values as values
  */
-export declare function getProfileMetadata(profileId: string, options?: any): Promise<Record<string, any>>;
+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)
+     */
+    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;
+    /**
+     * 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>;
+    /**
+     * Find or create identity for a profile
+     */
+    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;
+    name: string;
+    description?: string;
+    metadata: ProfileMetadata[];
+    relationshipsFrom: ProfileRelationship[];
+    relationshipsTo: ProfileRelationship[];
+    constructor(options?: ProfileOptions);
+    /**
+     * 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[]>;
+    /**
+     * Link a new OIDC identity to this profile
+     *
+     * @param oidcData - OIDC provider data
+     * @returns The linked OIDC identity record
+     */
+    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
@@ -47,7 +725,7 @@ export declare function getProfileMetadata(profileId: string, options?: any): Pr
  * @param value - The value to set
  * @param options - Database and configuration options
  */
-export declare function setProfileMetadata(profileId: string, metafieldSlug: string, value: any, options?: any): Promise<void>;
+export declare function setProfileMetadata(profileId: string, metafieldSlug: string, value: unknown, options?: SmrtObjectOptions): Promise<void>;
 
 /**
  * Validate a metadata value against a metafield's validation schema
@@ -56,6 +734,33 @@ export declare function setProfileMetadata(profileId: string, metafieldSlug: str
  * @param value - The value to validate
  * @returns True if valid, throws error if invalid
  */
-export declare function validateMetadataValue(metafield: any, value: any): Promise<boolean>;
+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 { }