@private.me/xbind 1.2.0

package/dist-standalone/invitation.d.ts

@@ -0,0 +1,211 @@
+/**
+ * @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 {};

package/dist-standalone/invitation.js

@@ -0,0 +1,415 @@
+/**
+ * @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 { ok, err } from"./_deps/shared/index.js";
+/**
+ * Error codes for invitation operations.
+ */
+export var InvitationErrorCode;
+(function (InvitationErrorCode) {
+    /** Invitation token is invalid format */
+    InvitationErrorCode["INVALID_TOKEN"] = "INVITATION_INVALID_TOKEN";
+    /** Invitation token has expired */
+    InvitationErrorCode["EXPIRED_TOKEN"] = "INVITATION_EXPIRED_TOKEN";
+    /** Invitation token already redeemed */
+    InvitationErrorCode["ALREADY_REDEEMED"] = "INVITATION_ALREADY_REDEEMED";
+    /** Rate limit exceeded (10 invitations/day per DID) */
+    InvitationErrorCode["RATE_LIMIT_EXCEEDED"] = "INVITATION_RATE_LIMIT_EXCEEDED";
+    /** Server communication failed */
+    InvitationErrorCode["SERVER_ERROR"] = "INVITATION_SERVER_ERROR";
+})(InvitationErrorCode || (InvitationErrorCode = {}));
+/**
+ * Client-side invitation manager.
+ * Creates invitations after send() failures and manages their lifecycle.
+ */
+export class InvitationClient {
+    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 = {}) {
+        this.invitationApiUrl = options.invitationApiUrl || 'https://api.private.me';
+    }
+    /**
+     * 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);
+     * }
+     * ```
+     */
+    async create(senderDid, recipientContact, expiryDays = 7) {
+        try {
+            const response = await fetch(`${this.invitationApiUrl}/invitations/create`, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                },
+                body: JSON.stringify({
+                    senderDid,
+                    recipientContact,
+                    expiryDays,
+                }),
+            });
+            if (response.status === 429) {
+                return err({
+                    code: InvitationErrorCode.RATE_LIMIT_EXCEEDED,
+                    message: 'Too many invitations created. Limit: 10 per day',
+                    hint: 'Wait before creating more invitations',
+                });
+            }
+            if (!response.ok) {
+                return err({
+                    code: InvitationErrorCode.SERVER_ERROR,
+                    message: `Server error: ${response.status}`,
+                });
+            }
+            const data = await response.json();
+            return ok({
+                token: data.token,
+                expiresAt: new Date(data.expiresAt),
+                senderDid: data.senderDid,
+                recipientContact: data.recipientContact,
+                inviteUrl: data.inviteUrl,
+            });
+        }
+        catch (error) {
+            return err({
+                code: InvitationErrorCode.SERVER_ERROR,
+                message: error instanceof Error ? error.message : 'Network error',
+            });
+        }
+    }
+    /**
+     * 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);
+     * }
+     * ```
+     */
+    async redeem(token) {
+        try {
+            if (!token || typeof token !== 'string') {
+                return err({
+                    code: InvitationErrorCode.INVALID_TOKEN,
+                    message: 'Invitation token is required',
+                });
+            }
+            const response = await fetch(`${this.invitationApiUrl}/invitations/redeem`, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                },
+                body: JSON.stringify({ token }),
+            });
+            if (response.status === 400) {
+                return err({
+                    code: InvitationErrorCode.INVALID_TOKEN,
+                    message: 'Invitation token is invalid',
+                    hint: 'Check the token in your URL',
+                });
+            }
+            if (response.status === 410) {
+                const data = await response.json();
+                if (data.reason === 'expired') {
+                    return err({
+                        code: InvitationErrorCode.EXPIRED_TOKEN,
+                        message: 'Invitation has expired',
+                        hint: 'Ask the sender for a new invitation',
+                    });
+                }
+                return err({
+                    code: InvitationErrorCode.ALREADY_REDEEMED,
+                    message: 'Invitation has already been used',
+                    hint: 'Each invitation can only be used once',
+                });
+            }
+            if (!response.ok) {
+                return err({
+                    code: InvitationErrorCode.SERVER_ERROR,
+                    message: `Server error: ${response.status}`,
+                });
+            }
+            const data = await response.json();
+            return ok(data.did);
+        }
+        catch (error) {
+            return err({
+                code: InvitationErrorCode.SERVER_ERROR,
+                message: error instanceof Error ? error.message : 'Network error',
+            });
+        }
+    }
+    /**
+     * 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`);
+     * }
+     * ```
+     */
+    async get(token) {
+        try {
+            const response = await fetch(`${this.invitationApiUrl}/invitations/${encodeURIComponent(token)}`, {
+                headers: {
+                    'Accept': 'application/json',
+                },
+            });
+            if (response.status === 404) {
+                return err({
+                    code: InvitationErrorCode.INVALID_TOKEN,
+                    message: 'Invitation not found',
+                });
+            }
+            if (!response.ok) {
+                return err({
+                    code: InvitationErrorCode.SERVER_ERROR,
+                    message: `Server error: ${response.status}`,
+                });
+            }
+            const data = await response.json();
+            return ok({
+                senderDid: data.senderDid,
+                recipientContact: data.recipientContact,
+                expiresAt: new Date(data.expiresAt),
+            });
+        }
+        catch (error) {
+            return err({
+                code: InvitationErrorCode.SERVER_ERROR,
+                message: error instanceof Error ? error.message : 'Network error',
+            });
+        }
+    }
+}
+/**
+ * Server-side invitation store (in-memory with JSONL persistence).
+ * Used by /invitations/* API endpoints.
+ */
+export class InvitationStore {
+    invitations = new Map();
+    redeemedTokens = new Set();
+    /** Track invitation creation per DID for rate limiting (10/day) */
+    creationCounts = new Map();
+    /**
+     * 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, recipientContact, expiryDays = 7) {
+        // Check rate limit
+        const now = Date.now();
+        const limit = this.creationCounts.get(senderDid);
+        if (limit && limit.count >= 10 && now < limit.resetTime) {
+            return err({
+                code: InvitationErrorCode.RATE_LIMIT_EXCEEDED,
+                message: 'Rate limit exceeded. Maximum 10 invitations per day.',
+            });
+        }
+        // Reset counter if window expired
+        if (limit && now >= limit.resetTime) {
+            this.creationCounts.delete(senderDid);
+        }
+        // Generate token
+        const token = generateInvitationToken();
+        const expiresAt = now + (expiryDays * 24 * 60 * 60 * 1000);
+        const invitation = {
+            token,
+            senderDid,
+            recipientContact,
+            createdAt: now,
+            expiresAt,
+            redeemed: false,
+        };
+        this.invitations.set(token, invitation);
+        // Update rate limit counter
+        if (!limit) {
+            this.creationCounts.set(senderDid, {
+                count: 1,
+                resetTime: now + (24 * 60 * 60 * 1000), // 24-hour window
+            });
+        }
+        else {
+            limit.count += 1;
+        }
+        return ok(invitation);
+    }
+    /**
+     * Get invitation by token without marking as redeemed.
+     *
+     * @param token - Token to lookup
+     * @returns Invitation or error
+     */
+    get(token) {
+        const invitation = this.invitations.get(token);
+        if (!invitation) {
+            return err({
+                code: InvitationErrorCode.INVALID_TOKEN,
+                message: 'Invitation not found',
+            });
+        }
+        const now = Date.now();
+        if (now > invitation.expiresAt) {
+            // Clean up expired invitation
+            this.invitations.delete(token);
+            return err({
+                code: InvitationErrorCode.EXPIRED_TOKEN,
+                message: 'Invitation has expired',
+            });
+        }
+        if (invitation.redeemed) {
+            return err({
+                code: InvitationErrorCode.ALREADY_REDEEMED,
+                message: 'Invitation has already been redeemed',
+            });
+        }
+        return ok(invitation);
+    }
+    /**
+     * 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) {
+        const getResult = this.get(token);
+        if (!getResult.ok) {
+            return getResult;
+        }
+        const invitation = getResult.value;
+        invitation.redeemed = true;
+        this.redeemedTokens.add(token);
+        // Generate DID for recipient
+        const did = generateRecipientDid(invitation.senderDid, invitation.recipientContact);
+        return ok(did);
+    }
+    /**
+     * Clean up expired invitations (run daily).
+     * @returns Number of invitations deleted
+     */
+    cleanup() {
+        const now = Date.now();
+        let count = 0;
+        for (const [token, invitation] of this.invitations.entries()) {
+            if (now > invitation.expiresAt || invitation.redeemed) {
+                this.invitations.delete(token);
+                count += 1;
+            }
+        }
+        return count;
+    }
+    /** Get active invitation count */
+    get count() {
+        return this.invitations.size;
+    }
+}
+/**
+ * Generate a cryptographically secure invitation token.
+ * Format: 48-character hex string (192 bits).
+ * @returns Random token
+ */
+export function generateInvitationToken() {
+    const bytes = new Uint8Array(24);
+    crypto.getRandomValues(bytes);
+    return Array.from(bytes)
+        .map(b => b.toString(16).padStart(2, '0'))
+        .join('');
+}
+/**
+ * Generate a deterministic DID for invited recipient.
+ * Ensures consistent identity across sessions.
+ *
+ * @param senderDid - DID of sender
+ * @param recipientContact - Email or identifier
+ * @returns Generated DID for recipient
+ */
+function generateRecipientDid(senderDid, recipientContact) {
+    // Create a simple derived identifier
+    // In production: derive from email + hash(senderDid) for uniqueness
+    const hash = hashString(`${senderDid}:${recipientContact}`);
+    return `did:key:z6Mk${hash}`;
+}
+/**
+ * Simple hash function for DID generation.
+ * @param input - String to hash
+ * @returns Hex string
+ */
+function hashString(input) {
+    let hash = 0;
+    for (let i = 0; i < input.length; i += 1) {
+        hash = ((hash << 5) - hash) + input.charCodeAt(i);
+        hash = hash & hash; // Convert to 32bit integer
+    }
+    return Math.abs(hash).toString(16).padStart(8, '0');
+}