@vaultsandbox/client 0.5.0

package/dist/email.js

@@ -0,0 +1,186 @@
+/**
+ * Email model - represents a decrypted email with convenient accessors
+ */
+/**
+ * Represents a decrypted email with convenient accessors for its content and metadata.
+ */
+import createDebug from 'debug';
+import { decryptRaw } from './crypto/decrypt.js';
+const debug = createDebug('vaultsandbox:email');
+/**
+ * Provides a summary of email authentication results (SPF, DKIM, DMARC).
+ */
+class AuthResults {
+    /** The SPF (Sender Policy Framework) validation result. */
+    spf;
+    /** An array of DKIM (DomainKeys Identified Mail) validation results. */
+    dkim;
+    /** The DMARC (Domain-based Message Authentication, Reporting, and Conformance) validation result. */
+    dmarc;
+    /** The reverse DNS validation result. */
+    reverseDns;
+    /**
+     * @internal
+     */
+    constructor(data) {
+        this.spf = data.spf;
+        this.dkim = data.dkim;
+        this.dmarc = data.dmarc;
+        this.reverseDns = data.reverseDns;
+        debug('Created AuthResults with SPF: %O, DKIM: %O, DMARC: %O, ReverseDNS: %O', this.spf, this.dkim, this.dmarc, this.reverseDns);
+    }
+    /**
+     * Validates the authentication results and provides a summary.
+     *
+     * @returns An `AuthValidation` object with the overall status and a list of failures.
+     */
+    validate() {
+        debug('Validating email authentication results');
+        const failures = [];
+        // Check SPF
+        const spfPassed = this.spf?.status === 'pass';
+        if (this.spf && !spfPassed) {
+            failures.push(`SPF check failed: ${this.spf.status}${this.spf.domain ? ` (domain: ${this.spf.domain})` : ''}`);
+        }
+        // Check DKIM (at least one signature must pass)
+        const dkimPassed = this.dkim?.some((d) => d.status === 'pass') ?? false;
+        if (this.dkim && this.dkim.length > 0 && !dkimPassed) {
+            const failedDomains = this.dkim
+                .filter((d) => d.status !== 'pass')
+                .map((d) => d.domain)
+                .filter(Boolean)
+                .join(', ');
+            failures.push(`DKIM signature failed${failedDomains ? `: ${failedDomains}` : ''}`);
+        }
+        // Check DMARC
+        const dmarcPassed = this.dmarc?.status === 'pass';
+        if (this.dmarc && !dmarcPassed) {
+            failures.push(`DMARC policy: ${this.dmarc.status}${this.dmarc.policy ? ` (policy: ${this.dmarc.policy})` : ''}`);
+        }
+        // Check Reverse DNS
+        const reverseDnsPassed = this.reverseDns?.status === 'pass';
+        if (this.reverseDns && !reverseDnsPassed) {
+            failures.push(`Reverse DNS check failed: ${this.reverseDns.status}${this.reverseDns.hostname ? ` (hostname: ${this.reverseDns.hostname})` : ''}`);
+        }
+        const validation = {
+            passed: spfPassed && dkimPassed && dmarcPassed,
+            spfPassed,
+            dkimPassed,
+            dmarcPassed,
+            reverseDnsPassed,
+            failures,
+        };
+        debug('Authentication validation result: %O', validation);
+        return validation;
+    }
+}
+/**
+ * Represents a fully decrypted email, providing access to its content,
+ * attachments, and metadata.
+ */
+export class Email {
+    /** The unique identifier for the email. */
+    id;
+    /** The sender's email address. */
+    from;
+    /** An array of recipient email addresses. */
+    to;
+    /** The subject of the email. */
+    subject;
+    /** The date and time the email was received. */
+    receivedAt;
+    /** A boolean indicating whether the email has been read. */
+    isRead;
+    /** The plain text content of the email, or `null` if not available. */
+    text;
+    /** The HTML content of the email, or `null` if not available. */
+    html;
+    /** An array of attachments found in the email. */
+    attachments;
+    /** An array of URLs extracted from the email's content. */
+    links;
+    /** An object containing the email's headers. */
+    headers;
+    /** The email's authentication results (SPF, DKIM, DMARC). */
+    authResults;
+    /** Any other metadata associated with the email. */
+    metadata;
+    emailAddress;
+    apiClient;
+    keypair;
+    /**
+     * @internal
+     * Do not construct this class directly.
+     */
+    constructor(emailData, metadata, parsed, emailAddress, apiClient, keypair) {
+        this.id = emailData.id;
+        this.from = metadata.from;
+        this.to = Array.isArray(metadata.to) ? metadata.to : [metadata.to].filter(Boolean);
+        this.subject = metadata.subject;
+        const receivedAtValue = metadata.receivedAt ?? emailData.receivedAt ?? Date.now();
+        this.receivedAt = new Date(receivedAtValue);
+        this.isRead = emailData.isRead;
+        this.emailAddress = emailAddress;
+        this.apiClient = apiClient;
+        this.keypair = keypair;
+        debug('Creating email %s from %s to %s', this.id, this.from, Array.isArray(this.to) ? this.to.join(', ') : this.to);
+        // If parsed content is available, use it
+        if (parsed) {
+            this.text = parsed.text;
+            this.html = parsed.html;
+            this.headers = parsed.headers;
+            this.attachments = parsed.attachments || [];
+            this.links = parsed.links || [];
+            this.authResults = new AuthResults(parsed.authResults || {});
+            debug('Email %s created with full parsed content (%d attachments, %d links)', this.id, this.attachments.length, this.links.length);
+        }
+        else {
+            // Metadata only (SSE notification without full fetch)
+            this.text = null;
+            this.html = null;
+            this.headers = {};
+            this.attachments = [];
+            this.links = [];
+            this.authResults = new AuthResults({});
+            debug('Email %s created with metadata only', this.id);
+        }
+        this.metadata = {};
+    }
+    /**
+     * Marks this email as read.
+     *
+     * @returns A promise that resolves when the email is marked as read.
+     */
+    async markAsRead() {
+        debug('Marking email %s as read', this.id);
+        await this.apiClient.markEmailAsRead(this.emailAddress, this.id);
+        // The isRead property is readonly for external consumers to prevent accidental modification,
+        // but we need to update it after the API call succeeds. This mapped type temporarily removes
+        // the readonly modifier to allow the internal update while maintaining the public API contract.
+        this.isRead = true;
+        debug('Successfully marked email %s as read', this.id);
+    }
+    /**
+     * Deletes this email from the inbox.
+     *
+     * @returns A promise that resolves when the email is deleted.
+     */
+    async delete() {
+        debug('Deleting email %s', this.id);
+        await this.apiClient.deleteEmail(this.emailAddress, this.id);
+        debug('Successfully deleted email %s', this.id);
+    }
+    /**
+     * Fetches the raw, decrypted source of the email.
+     *
+     * @returns A promise that resolves to the raw email data.
+     */
+    async getRaw() {
+        debug('Fetching raw content for email %s', this.id);
+        const rawEmailData = await this.apiClient.getRawEmail(this.emailAddress, this.id);
+        const raw = await decryptRaw(rawEmailData.encryptedRaw, this.keypair);
+        debug('Successfully fetched and decrypted raw content for email %s (%d characters)', this.id, raw.length);
+        return { id: rawEmailData.id, raw };
+    }
+}
+//# sourceMappingURL=email.js.map

package/dist/email.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"email.js","sourceRoot":"","sources":["../src/email.ts"],"names":[],"mappings":"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"}

package/dist/http/api-client.d.ts

@@ -0,0 +1,145 @@
+/**
+ * HTTP API client for VaultSandbox Gateway
+ */
+import type { ClientConfig, InboxData, EmailData, ServerInfo, SyncStatus, RawEmailData } from '../types/index.js';
+/**
+ * HTTP API client for interacting with the VaultSandbox Gateway server.
+ * Handles all API communication including inbox management, email operations,
+ * and server information retrieval with built-in retry logic.
+ */
+export declare class ApiClient {
+    private client;
+    private config;
+    /**
+     * Creates a new API client instance.
+     * @param config - Configuration object containing URL, API key, and retry settings
+     */
+    constructor(config: ClientConfig);
+    /**
+     * Configures automatic retry logic for failed HTTP requests.
+     * Retries are performed with exponential backoff for specific HTTP status codes.
+     * @private
+     */
+    private setupRetry;
+    /**
+     * Converts Axios errors into domain-specific error types.
+     * @param error - The Axios error to handle
+     * @returns A domain-specific error (NetworkError, InboxNotFoundError, EmailNotFoundError, or ApiError)
+     * @private
+     */
+    private handleError;
+    /**
+     * Retrieves information about the VaultSandbox Gateway server.
+     * @returns Promise resolving to server information including version and capabilities
+     * @throws {NetworkError} If network communication fails
+     * @throws {ApiError} If the server returns an error response
+     */
+    getServerInfo(): Promise<ServerInfo>;
+    /**
+     * Validates that the configured API key is valid.
+     * @returns Promise resolving to an object indicating if the key is valid
+     * @throws {NetworkError} If network communication fails
+     * @throws {ApiError} If the server returns an error response
+     */
+    checkKey(): Promise<boolean>;
+    /**
+     * Creates a new temporary inbox on the server.
+     * @param publicKey - The client's KEM public key for encrypted communication
+     * @param ttl - Optional time-to-live in seconds for the inbox
+     * @param emailAddress - Optional desired email address or domain
+     * @returns Promise resolving to the created inbox data including email address
+     * @throws {NetworkError} If network communication fails
+     * @throws {ApiError} If the server returns an error response
+     */
+    createInbox(publicKey: string, ttl?: number, emailAddress?: string): Promise<InboxData>;
+    /**
+     * Deletes a specific inbox and all its emails.
+     * @param emailAddress - The email address of the inbox to delete
+     * @returns Promise that resolves when the inbox is deleted
+     * @throws {NetworkError} If network communication fails
+     * @throws {InboxNotFoundError} If the inbox does not exist
+     * @throws {ApiError} If the server returns an error response
+     */
+    deleteInbox(emailAddress: string): Promise<void>;
+    /**
+     * Deletes all inboxes associated with the API key.
+     * @returns Promise resolving to the number of inboxes deleted
+     * @throws {NetworkError} If network communication fails
+     * @throws {ApiError} If the server returns an error response
+     */
+    deleteAllInboxes(): Promise<{
+        deleted: number;
+    }>;
+    /**
+     * Gets the email synchronization status for an inbox.
+     * @param emailAddress - The email address of the inbox
+     * @returns Promise resolving to the sync status including last sync time and email count
+     * @throws {NetworkError} If network communication fails
+     * @throws {InboxNotFoundError} If the inbox does not exist
+     * @throws {ApiError} If the server returns an error response
+     */
+    getSyncStatus(emailAddress: string): Promise<SyncStatus>;
+    /**
+     * Lists all emails in an inbox.
+     * @param emailAddress - The email address of the inbox
+     * @returns Promise resolving to an array of emails
+     * @throws {NetworkError} If network communication fails
+     * @throws {InboxNotFoundError} If the inbox does not exist
+     * @throws {ApiError} If the server returns an error response
+     */
+    listEmails(emailAddress: string): Promise<EmailData[]>;
+    /**
+     * Retrieves a specific email by ID.
+     * @param emailAddress - The email address of the inbox
+     * @param emailId - The unique identifier of the email
+     * @returns Promise resolving to the email data
+     * @throws {NetworkError} If network communication fails
+     * @throws {InboxNotFoundError} If the inbox does not exist
+     * @throws {EmailNotFoundError} If the email does not exist
+     * @throws {ApiError} If the server returns an error response
+     */
+    getEmail(emailAddress: string, emailId: string): Promise<EmailData>;
+    /**
+     * Retrieves the raw email data including full headers and body.
+     * @param emailAddress - The email address of the inbox
+     * @param emailId - The unique identifier of the email
+     * @returns Promise resolving to the raw email data
+     * @throws {NetworkError} If network communication fails
+     * @throws {InboxNotFoundError} If the inbox does not exist
+     * @throws {EmailNotFoundError} If the email does not exist
+     * @throws {ApiError} If the server returns an error response
+     */
+    getRawEmail(emailAddress: string, emailId: string): Promise<RawEmailData>;
+    /**
+     * Marks an email as read.
+     * @param emailAddress - The email address of the inbox
+     * @param emailId - The unique identifier of the email
+     * @returns Promise that resolves when the email is marked as read
+     * @throws {NetworkError} If network communication fails
+     * @throws {InboxNotFoundError} If the inbox does not exist
+     * @throws {EmailNotFoundError} If the email does not exist
+     * @throws {ApiError} If the server returns an error response
+     */
+    markEmailAsRead(emailAddress: string, emailId: string): Promise<void>;
+    /**
+     * Deletes a specific email from an inbox.
+     * @param emailAddress - The email address of the inbox
+     * @param emailId - The unique identifier of the email
+     * @returns Promise that resolves when the email is deleted
+     * @throws {NetworkError} If network communication fails
+     * @throws {InboxNotFoundError} If the inbox does not exist
+     * @throws {EmailNotFoundError} If the email does not exist
+     * @throws {ApiError} If the server returns an error response
+     */
+    deleteEmail(emailAddress: string, emailId: string): Promise<void>;
+    /**
+     * Gets the base URL of the VaultSandbox Gateway server.
+     * @returns The configured base URL
+     */
+    getBaseUrl(): string;
+    /**
+     * Gets the configured API key.
+     * @returns The API key being used for authentication
+     */
+    getApiKey(): string;
+}

package/dist/http/api-client.js

@@ -0,0 +1,242 @@
+/**
+ * HTTP API client for VaultSandbox Gateway
+ */
+import axios from 'axios';
+import { ApiError, NetworkError, InboxNotFoundError, EmailNotFoundError } from '../types/index.js';
+import { sleep } from '../utils/sleep.js';
+/**
+ * HTTP API client for interacting with the VaultSandbox Gateway server.
+ * Handles all API communication including inbox management, email operations,
+ * and server information retrieval with built-in retry logic.
+ */
+export class ApiClient {
+    client;
+    config;
+    /**
+     * Creates a new API client instance.
+     * @param config - Configuration object containing URL, API key, and retry settings
+     */
+    constructor(config) {
+        this.config = config;
+        this.client = axios.create({
+            baseURL: config.url,
+            headers: {
+                'X-API-Key': config.apiKey,
+                'Content-Type': 'application/json',
+            },
+            timeout: 30000,
+        });
+        // Setup retry logic
+        this.setupRetry();
+    }
+    /**
+     * Configures automatic retry logic for failed HTTP requests.
+     * Retries are performed with exponential backoff for specific HTTP status codes.
+     * @private
+     */
+    setupRetry() {
+        this.client.interceptors.response.use((response) => response, async (error) => {
+            const config = error.config;
+            const maxRetries = this.config.maxRetries ?? 3;
+            const retryDelay = this.config.retryDelay ?? 1000;
+            const retryOn = this.config.retryOn ?? [408, 429, 500, 502, 503, 504];
+            // Early return if no config
+            if (!config) {
+                throw error;
+            }
+            // Use a custom property on the config object to track retries
+            const requestConfig = config;
+            if (!requestConfig.__retryCount) {
+                requestConfig.__retryCount = 0;
+            }
+            const retryCount = requestConfig.__retryCount;
+            const shouldRetry = retryCount < maxRetries && error.response && retryOn.includes(error.response.status);
+            if (shouldRetry && config) {
+                requestConfig.__retryCount = retryCount + 1;
+                await sleep(retryDelay * Math.pow(2, retryCount));
+                return this.client.request(config);
+            }
+            throw this.handleError(error);
+        });
+    }
+    /**
+     * Converts Axios errors into domain-specific error types.
+     * @param error - The Axios error to handle
+     * @returns A domain-specific error (NetworkError, InboxNotFoundError, EmailNotFoundError, or ApiError)
+     * @private
+     */
+    handleError(error) {
+        if (!error.response) {
+            return new NetworkError(error.message || 'Network error occurred');
+        }
+        const status = error.response.status;
+        const message = error.response.data?.error || error.message;
+        if (status === 404) {
+            if (message.toLowerCase().includes('inbox')) {
+                return new InboxNotFoundError(message);
+            }
+            if (message.toLowerCase().includes('email')) {
+                return new EmailNotFoundError(message);
+            }
+        }
+        return new ApiError(status, message);
+    }
+    // ===== Server Info =====
+    /**
+     * Retrieves information about the VaultSandbox Gateway server.
+     * @returns Promise resolving to server information including version and capabilities
+     * @throws {NetworkError} If network communication fails
+     * @throws {ApiError} If the server returns an error response
+     */
+    async getServerInfo() {
+        const response = await this.client.get('/api/server-info');
+        return response.data;
+    }
+    /**
+     * Validates that the configured API key is valid.
+     * @returns Promise resolving to an object indicating if the key is valid
+     * @throws {NetworkError} If network communication fails
+     * @throws {ApiError} If the server returns an error response
+     */
+    async checkKey() {
+        const response = await this.client.get('/api/check-key');
+        return response.data.ok;
+    }
+    // ===== Inbox Management =====
+    /**
+     * Creates a new temporary inbox on the server.
+     * @param publicKey - The client's KEM public key for encrypted communication
+     * @param ttl - Optional time-to-live in seconds for the inbox
+     * @param emailAddress - Optional desired email address or domain
+     * @returns Promise resolving to the created inbox data including email address
+     * @throws {NetworkError} If network communication fails
+     * @throws {ApiError} If the server returns an error response
+     */
+    async createInbox(publicKey, ttl, emailAddress) {
+        const payload = { clientKemPk: publicKey };
+        if (ttl !== undefined && ttl !== null) {
+            payload.ttl = ttl;
+        }
+        if (emailAddress !== undefined && emailAddress !== null) {
+            payload.emailAddress = emailAddress;
+        }
+        const response = await this.client.post('/api/inboxes', payload);
+        return response.data;
+    }
+    /**
+     * Deletes a specific inbox and all its emails.
+     * @param emailAddress - The email address of the inbox to delete
+     * @returns Promise that resolves when the inbox is deleted
+     * @throws {NetworkError} If network communication fails
+     * @throws {InboxNotFoundError} If the inbox does not exist
+     * @throws {ApiError} If the server returns an error response
+     */
+    async deleteInbox(emailAddress) {
+        await this.client.delete(`/api/inboxes/${encodeURIComponent(emailAddress)}`);
+    }
+    /**
+     * Deletes all inboxes associated with the API key.
+     * @returns Promise resolving to the number of inboxes deleted
+     * @throws {NetworkError} If network communication fails
+     * @throws {ApiError} If the server returns an error response
+     */
+    async deleteAllInboxes() {
+        const response = await this.client.delete('/api/inboxes');
+        return response.data;
+    }
+    /**
+     * Gets the email synchronization status for an inbox.
+     * @param emailAddress - The email address of the inbox
+     * @returns Promise resolving to the sync status including last sync time and email count
+     * @throws {NetworkError} If network communication fails
+     * @throws {InboxNotFoundError} If the inbox does not exist
+     * @throws {ApiError} If the server returns an error response
+     */
+    async getSyncStatus(emailAddress) {
+        const response = await this.client.get(`/api/inboxes/${encodeURIComponent(emailAddress)}/sync`);
+        return response.data;
+    }
+    // ===== Email Management =====
+    /**
+     * Lists all emails in an inbox.
+     * @param emailAddress - The email address of the inbox
+     * @returns Promise resolving to an array of emails
+     * @throws {NetworkError} If network communication fails
+     * @throws {InboxNotFoundError} If the inbox does not exist
+     * @throws {ApiError} If the server returns an error response
+     */
+    async listEmails(emailAddress) {
+        const response = await this.client.get(`/api/inboxes/${encodeURIComponent(emailAddress)}/emails`);
+        return response.data;
+    }
+    /**
+     * Retrieves a specific email by ID.
+     * @param emailAddress - The email address of the inbox
+     * @param emailId - The unique identifier of the email
+     * @returns Promise resolving to the email data
+     * @throws {NetworkError} If network communication fails
+     * @throws {InboxNotFoundError} If the inbox does not exist
+     * @throws {EmailNotFoundError} If the email does not exist
+     * @throws {ApiError} If the server returns an error response
+     */
+    async getEmail(emailAddress, emailId) {
+        const response = await this.client.get(`/api/inboxes/${encodeURIComponent(emailAddress)}/emails/${emailId}`);
+        return response.data;
+    }
+    /**
+     * Retrieves the raw email data including full headers and body.
+     * @param emailAddress - The email address of the inbox
+     * @param emailId - The unique identifier of the email
+     * @returns Promise resolving to the raw email data
+     * @throws {NetworkError} If network communication fails
+     * @throws {InboxNotFoundError} If the inbox does not exist
+     * @throws {EmailNotFoundError} If the email does not exist
+     * @throws {ApiError} If the server returns an error response
+     */
+    async getRawEmail(emailAddress, emailId) {
+        const response = await this.client.get(`/api/inboxes/${encodeURIComponent(emailAddress)}/emails/${emailId}/raw`);
+        return response.data;
+    }
+    /**
+     * Marks an email as read.
+     * @param emailAddress - The email address of the inbox
+     * @param emailId - The unique identifier of the email
+     * @returns Promise that resolves when the email is marked as read
+     * @throws {NetworkError} If network communication fails
+     * @throws {InboxNotFoundError} If the inbox does not exist
+     * @throws {EmailNotFoundError} If the email does not exist
+     * @throws {ApiError} If the server returns an error response
+     */
+    async markEmailAsRead(emailAddress, emailId) {
+        await this.client.patch(`/api/inboxes/${encodeURIComponent(emailAddress)}/emails/${emailId}/read`);
+    }
+    /**
+     * Deletes a specific email from an inbox.
+     * @param emailAddress - The email address of the inbox
+     * @param emailId - The unique identifier of the email
+     * @returns Promise that resolves when the email is deleted
+     * @throws {NetworkError} If network communication fails
+     * @throws {InboxNotFoundError} If the inbox does not exist
+     * @throws {EmailNotFoundError} If the email does not exist
+     * @throws {ApiError} If the server returns an error response
+     */
+    async deleteEmail(emailAddress, emailId) {
+        await this.client.delete(`/api/inboxes/${encodeURIComponent(emailAddress)}/emails/${emailId}`);
+    }
+    // ===== Utility =====
+    /**
+     * Gets the base URL of the VaultSandbox Gateway server.
+     * @returns The configured base URL
+     */
+    getBaseUrl() {
+        return this.config.url;
+    }
+    /**
+     * Gets the configured API key.
+     * @returns The API key being used for authentication
+     */
+    getApiKey() {
+        return this.config.apiKey;
+    }
+}
+//# sourceMappingURL=api-client.js.map

package/dist/http/api-client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-client.js","sourceRoot":"","sources":["../../src/http/api-client.ts"],"names":[],"mappings":"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"}