/**
 * @module invitation
 * Growth hack: Turn recipient-not-found failures into invitation opportunities.
 *
 * When agent.send() fails because recipient is not registered, this module
 * provides an invitation mechanism to turn failures into viral growth.
 *
 * Flow:
 * 1. Sender calls agent.send({ to: 'unregistered@example.com', ... })
 * 2. send() fails with RECIPIENT_NOT_FOUND
 * 3. Error includes invitationToken and inviteUrl
 * 4. Sender shares URL with recipient
 * 5. Recipient clicks link, signs up, joins Xail
 * 6. Connection auto-establishes
 */
import { Result } from '@private.me/shared';
/**
 * Invitation token structure.
 */
export interface InvitationToken {
    /** JWT token (7-day expiry, one-time use) */
    token: string;
    /** ISO timestamp when invitation expires */
    expiresAt: Date;
    /** DID of sender who created the invitation */
    senderDid: string;
    /** Email or identifier of recipient */
    recipientContact: string;
    /** Full URL to share with recipient */
    inviteUrl: string;
}
/**
 * Error codes for invitation operations.
 */
export declare enum InvitationErrorCode {
    /** Invitation token is invalid format */
    INVALID_TOKEN = "INVITATION_INVALID_TOKEN",
    /** Invitation token has expired */
    EXPIRED_TOKEN = "INVITATION_EXPIRED_TOKEN",
    /** Invitation token already redeemed */
    ALREADY_REDEEMED = "INVITATION_ALREADY_REDEEMED",
    /** Rate limit exceeded (10 invitations/day per DID) */
    RATE_LIMIT_EXCEEDED = "INVITATION_RATE_LIMIT_EXCEEDED",
    /** Server communication failed */
    SERVER_ERROR = "INVITATION_SERVER_ERROR"
}
/**
 * Invitation error details.
 */
export interface InvitationError {
    code: InvitationErrorCode;
    message: string;
    hint?: string;
}
/**
 * In-memory store for tracking invitation creation (server-side).
 */
interface StoredInvitation {
    token: string;
    senderDid: string;
    recipientContact: string;
    createdAt: number;
    expiresAt: number;
    redeemed: boolean;
}
/**
 * Client-side invitation manager.
 * Creates invitations after send() failures and manages their lifecycle.
 */
export declare class InvitationClient {
    private invitationApiUrl;
    /**
     * Create invitation client.
     *
     * @param options - Configuration
     * @param options.invitationApiUrl - Invitation API URL (default: https://api.private.me)
     *
     * @example
     * ```ts
     * const inviteClient = new InvitationClient();
     * ```
     */
    constructor(options?: {
        invitationApiUrl?: string;
    });
    /**
     * Create an invitation for a recipient who is not yet registered.
     *
     * Called automatically when agent.send() returns RECIPIENT_NOT_FOUND.
     * Generates a time-limited invitation token that can be shared via email/SMS.
     *
     * @param senderDid - DID of the agent sending the invitation
     * @param recipientContact - Email address or identifier of recipient
     * @param expiryDays - Days until invitation expires (default: 7)
     * @returns Invitation token with shareable URL or error
     *
     * @example
     * ```ts
     * const inviteResult = await inviteClient.create(
     *   'did:key:z6Mk...',
     *   'alice@example.com',
     *   7 // 7-day expiry
     * );
     *
     * if (inviteResult.ok) {
     *   // Share inviteResult.value.inviteUrl with recipient
     *   console.log('Share this link:', inviteResult.value.inviteUrl);
     * } else {
     *   // Handle error
     *   console.error('Failed:', inviteResult.error.message);
     * }
     * ```
     */
    create(senderDid: string, recipientContact: string, expiryDays?: number): Promise<Result<InvitationToken, InvitationError>>;
    /**
     * Redeem an invitation token and create a new DID for the recipient.
     *
     * Called by recipient after clicking invitation link.
     * Returns a new DID that can be used immediately for messaging.
     *
     * @param token - Invitation token from URL query parameter
     * @returns New DID for recipient or error
     *
     * @example
     * ```ts
     * // From URL: https://private.me/invite?token=abc123
     * const urlParams = new URLSearchParams(window.location.search);
     * const token = urlParams.get('token');
     *
     * const redeemResult = await inviteClient.redeem(token);
     * if (redeemResult.ok) {
     *   // Auto-create agent with new DID
     *   const agent = await Agent.create(redeemResult.value);
     * } else {
     *   // Handle: expired, already used, invalid
     *   console.error(redeemResult.error.message);
     * }
     * ```
     */
    redeem(token: string): Promise<Result<string, InvitationError>>;
    /**
     * Get invitation details without redeeming.
     *
     * Used to preview sender name before accepting invitation.
     *
     * @param token - Invitation token
     * @returns Invitation details or error
     *
     * @example
     * ```ts
     * const detailsResult = await inviteClient.get(token);
     * if (detailsResult.ok) {
     *   console.log(`${detailsResult.value.senderDid} invited you`);
     * }
     * ```
     */
    get(token: string): Promise<Result<{
        senderDid: string;
        recipientContact: string;
        expiresAt: Date;
    }, InvitationError>>;
}
/**
 * Server-side invitation store (in-memory with JSONL persistence).
 * Used by /invitations/* API endpoints.
 */
export declare class InvitationStore {
    private invitations;
    private redeemedTokens;
    /** Track invitation creation per DID for rate limiting (10/day) */
    private creationCounts;
    /**
     * Create an invitation and return token + expiry.
     * Enforces rate limit: 10 invitations per DID per 24 hours.
     *
     * @param senderDid - DID creating the invitation
     * @param recipientContact - Email or identifier
     * @param expiryDays - Days until expiry
     * @returns Token + metadata or error
     */
    create(senderDid: string, recipientContact: string, expiryDays?: number): Result<StoredInvitation, InvitationError>;
    /**
     * Get invitation by token without marking as redeemed.
     *
     * @param token - Token to lookup
     * @returns Invitation or error
     */
    get(token: string): Result<StoredInvitation, InvitationError>;
    /**
     * Redeem an invitation (one-time use).
     * Mark as redeemed and generate new DID.
     *
     * @param token - Token to redeem
     * @returns New DID or error
     */
    redeem(token: string): Result<string, InvitationError>;
    /**
     * Clean up expired invitations (run daily).
     * @returns Number of invitations deleted
     */
    cleanup(): number;
    /** Get active invitation count */
    get count(): number;
}
/**
 * Generate a cryptographically secure invitation token.
 * Format: 48-character hex string (192 bits).
 * @returns Random token
 */
export declare function generateInvitationToken(): string;
export {};
