Intellisense: doc comments and inbox (server) terminology

src/mailosaur.ts

@@ -10,34 +10,40 @@ import Request from './request.js';
 import type { HttpResponse } from './request.js';
 import MailosaurError from './models/mailosaurError.js';
 
+/**
+ * The Mailosaur client — the main entry point to the Mailosaur API. Construct an instance with
+ * your API key (or set the `MAILOSAUR_API_KEY` environment variable), then use the operations
+ * namespaces (`messages`, `servers`, `files`, `devices`, `analysis`, `previews`, `usage`) to
+ * automate email and SMS testing.
+ */
 class MailosaurClient {
   request: Request;
   /**
-   * Message analysis operations
+   * Operations for analyzing email content and deliverability, including spam scoring.
    */
   analysis: Analysis;
   /**
-   * File operations
+   * Operations for downloading attachments, EML source, and email preview screenshots.
    */
   files: Files;
   /**
-   * Message operations
+   * Operations for finding, retrieving, creating, and managing email and SMS messages.
    */
   messages: Messages;
   /**
-   * Server management operations
+   * Operations for creating and managing your Mailosaur inboxes (servers).
    */
   servers: Servers;
   /**
-   * Account usage operations
+   * Operations for inspecting account usage limits and recent transactional usage.
    */
   usage: Usage;
   /**
-   * Device management operations
+   * Operations for managing virtual security devices and retrieving their one-time passwords.
    */
   devices: Devices;
   /**
-   * Email Previews operations
+   * Operations for discovering the email clients available for generating email previews.
    */
   previews: Previews;
   models: typeof models;

src/models/message.ts

@@ -56,7 +56,7 @@ class Message {
    */
   metadata?: Metadata;
   /**
-   * Identifier for the server in which the message is located.
+   * Identifier for the inbox (server) in which the message is located.
    */
   server?: string;
 

src/models/messageSummary.ts

@@ -15,7 +15,7 @@ class MessageSummary {
    */
   type: 'Email' | 'SMS';
   /**
-   * Identifier for the server in which the message is located.
+   * Identifier for the inbox (server) in which the message is located.
    */
   server?: string;
   /**

src/models/server.ts

@@ -1,21 +1,21 @@
 /**
- * Mailosaur virtual SMTP/SMS server.
+ * A Mailosaur inbox (server) — a virtual SMTP/SMS endpoint.
  */
 class Server {
   /**
-   * Unique identifier for the server.
+   * Unique identifier for the inbox (server).
    */
   id?: string;
   /**
-   * The name of the server.
+   * The name of the inbox (server).
    */
   name?: string;
   /**
-   * Users (excluding administrators) who have access to the server (if it is restricted).
+   * Users (excluding administrators) who have access to the inbox (server) when access is restricted.
    */
   users?: string[];
   /**
-   * The number of messages currently in the server.
+   * The number of messages currently in the inbox (server).
    */
   messages?: number;
 

src/models/serverCreateOptions.ts

@@ -1,9 +1,9 @@
 /**
- * Options used to create a new Mailosaur server.
+ * Options used to create a new Mailosaur inbox (server).
  */
 class ServerCreateOptions {
   /**
-   * A name used to identify the server.
+   * A name used to identify the inbox (server).
    */
   name?: string;
 

src/models/serverListResult.ts

@@ -1,12 +1,12 @@
 import Server from './server.js';
 
 /**
- * The result of the server listing operation.
+ * The result of the inbox (server) listing operation.
  */
 class ServerListResult {
   /**
-   * The individual servers forming the result. Servers
-   * are returned sorted by creation date, with the most recently-created server
+   * The individual inboxes (servers) forming the result. Inboxes (servers)
+   * are returned sorted by creation date, with the most recently-created inbox (server)
    * appearing first.
    */
   items?: Server[];

src/models/usageAccountLimits.ts

@@ -5,7 +5,7 @@ import UsageAccountLimit from './usageAccountLimit.js';
  */
 class UsageAccountLimits {
   /**
-   * Server limits.
+   * Inbox (server) limits.
    */
   servers?: UsageAccountLimit;
   /**

src/operations/analysis.ts

@@ -4,7 +4,8 @@ import type { HttpResponse } from '../request.js';
 import type MailosaurClient from '../mailosaur.js';
 
 /**
- * Message analysis operations.
+ * Operations for analyzing the content and deliverability of an email, including SpamAssassin
+ * scoring and per-provider deliverability reports. Accessed via `client.analysis`.
  */
 class Analysis {
   client: MailosaurClient;
@@ -16,6 +17,7 @@ class Analysis {
   /**
    * Perform a spam analysis of an email.
    * @param messageId The identifier of the message to be analyzed.
+   * @returns A promise resolving to a {@link SpamAnalysisResult} containing the spam score and filter results.
    */
   async spam(messageId: string): Promise<SpamAnalysisResult> {
     const url = `api/analysis/spam/${messageId}`;
@@ -44,6 +46,7 @@ class Analysis {
   /**
    * Perform a deliverability report of an email.
    * @param messageId The identifier of the message to be analyzed.
+   * @returns A promise resolving to a {@link DeliverabilityReport} for the email.
    */
   async deliverability(messageId: string): Promise<DeliverabilityReport> {
     const url = `api/analysis/deliverability/${messageId}`;

src/operations/devices.ts

@@ -5,6 +5,11 @@ import type DeviceCreateOptions from '../models/deviceCreateOptions.js';
 import type { HttpResponse } from '../request.js';
 import type MailosaurClient from '../mailosaur.js';
 
+/**
+ * Operations for managing virtual security devices and retrieving their current one-time
+ * passwords (OTPs), used to automate testing of app-based multi-factor authentication.
+ * Accessed via `client.devices`.
+ */
 class Devices {
   client: MailosaurClient;
 
@@ -14,6 +19,7 @@ class Devices {
 
   /**
    * Returns a list of your virtual security devices.
+   * @returns A promise resolving to a {@link DeviceListResult} containing your devices.
    */
   async list(): Promise<DeviceListResult> {
     const url = `api/devices`;
@@ -42,6 +48,7 @@ class Devices {
   /**
    * Creates a new virtual security device.
    * @param options Options used to create a new Mailosaur virtual security device.
+   * @returns A promise resolving to the newly-created {@link Device}.
    */
   async create(options: DeviceCreateOptions): Promise<Device> {
     const url = `api/devices`;
@@ -70,6 +77,7 @@ class Devices {
   /**
    * Retrieves the current one-time password for a saved device, or given base32-encoded shared secret.
    * @param query Either the unique identifier of the device, or a base32-encoded shared secret.
+   * @returns A promise resolving to an {@link OtpResult} containing the current one-time password.
    */
   async otp(query: string): Promise<OtpResult> {
     if (!query || query.indexOf('-') > -1) {
@@ -121,6 +129,7 @@ class Devices {
   /**
    * Permanently delete a virtual security device. This operation cannot be undone.
    * @param deviceId The unique identifier of the device.
+   * @returns A promise resolving once the device has been deleted.
    */
   async del(deviceId: string): Promise<void> {
     const url = `api/devices/${deviceId}`;

src/operations/files.ts

@@ -9,7 +9,8 @@ interface IMailosaurClient {
 }
 
 /**
- * File operations.
+ * Operations for downloading the raw content associated with a message — file attachments,
+ * the full EML source of an email, and rendered email previews. Accessed via `client.files`.
  */
 class Files {
   client: IMailosaurClient;
@@ -21,6 +22,7 @@ class Files {
   /**
    * Downloads a single attachment.
    * @param attachmentId The identifier for the required attachment.
+   * @returns A promise resolving to a Buffer containing the attachment's binary content.
    */
   async getAttachment(attachmentId: string): Promise<Buffer> {
     const url = `api/files/attachments/${attachmentId}`;
@@ -38,6 +40,7 @@ class Files {
   /**
    * Downloads an EML file representing the specified email.
    * @param messageId The identifier for the required message.
+   * @returns A promise resolving to a Buffer containing the raw EML content of the email.
    */
   async getEmail(messageId: string): Promise<Buffer> {
     const url = `api/files/email/${messageId}`;
@@ -56,6 +59,8 @@ class Files {
    * Downloads a screenshot of your email rendered in a real email client. Simply supply
    * the unique identifier for the required preview.
    * @param previewId The identifier of the email preview to be downloaded.
+   * @returns A promise resolving to a Buffer containing the preview screenshot image.
+   * @throws {MailosaurError} With error type `preview_timeout` if the preview is not generated within the time limit.
    */
   async getPreview(previewId: string): Promise<Buffer> {
     const timeout = 120000;

src/operations/messages.ts

@@ -12,6 +12,10 @@ import type PreviewRequestOptions from '../models/previewRequestOptions.js';
 import type { HttpResponse } from '../request.js';
 import type MailosaurClient from '../mailosaur.js';
 
+/**
+ * Operations for finding, retrieving, creating, forwarding, replying to, and deleting the
+ * email and SMS messages received by your Mailosaur inboxes (servers). Accessed via `client.messages`.
+ */
 class Messages {
   client: MailosaurClient;
 
@@ -22,9 +26,11 @@ class Messages {
   /**
    * Waits for a message to be found. Returns as soon as a message matching the specified search criteria is found.
    * **Recommended:** This is the most efficient method of looking up a message, therefore we recommend using it wherever possible.
-   * @param serverId The unique identifier of the containing server.
+   * @param serverId The unique identifier of the containing inbox (server).
    * @param criteria The criteria with which to find messages during a search.
    * @param options Search options
+   * @returns A promise resolving to the first {@link Message} matching the criteria.
+   * @throws {MailosaurError} With error type `no_messages_found` if no matching message exists, or `search_timeout` if no matching message arrives before the timeout elapses.
    */
   async get(
     serverId: string,
@@ -69,6 +75,7 @@ class Messages {
    * Retrieves the detail for a single message. Must be used in conjunction with either list or
    * search in order to get the unique identifier for the required message.
    * @param messageId The unique identifier of the message to be retrieved.
+   * @returns A promise resolving to the full {@link Message}.
    */
   async getById(messageId: string): Promise<Message> {
     const url = `api/messages/${messageId}`;
@@ -97,6 +104,7 @@ class Messages {
   /**
    * Permanently deletes a message. Also deletes any attachments related to the message. This operation cannot be undone.
    * @param messageId The identifier for the message.
+   * @returns A promise resolving once the message has been deleted.
    */
   async del(messageId: string): Promise<void> {
     const url = `api/messages/${messageId}`;
@@ -124,8 +132,9 @@ class Messages {
 
   /**
    * Returns a list of your messages in summary form. The summaries are returned sorted by received date, with the most recently-received messages appearing first.
-   * @param serverId The unique identifier of the required server.
+   * @param serverId The unique identifier of the required inbox (server).
    * @param options Message listing options
+   * @returns A promise resolving to a {@link MessageListResult} containing the message summaries.
    */
   async list(
     serverId: string,
@@ -163,8 +172,9 @@ class Messages {
   }
 
   /**
-   * Permenantly delete all messages within a server.
-   * @param serverId The unique identifier of the server.
+   * Permanently delete all messages within an inbox (server). This operation cannot be undone.
+   * @param serverId The unique identifier of the inbox (server).
+   * @returns A promise resolving once all messages within the inbox (server) have been deleted.
    */
   async deleteAll(serverId: string): Promise<void> {
     const url = `api/messages`;
@@ -197,9 +207,11 @@ class Messages {
   /**
    * Returns a list of messages matching the specified search criteria, in summary form.
    * The messages are returned sorted by received date, with the most recently-received messages appearing first.
-   * @param serverId The unique identifier of the server to search.
+   * @param serverId The unique identifier of the inbox (server) to search.
    * @param criteria The criteria with which to find messages during a search.
    * @param options Search options
+   * @returns A promise resolving to a {@link MessageListResult} containing the matching message summaries.
+   * @throws {MailosaurError} With error type `search_timeout` if no matching message is found before the timeout elapses, unless `options.errorOnTimeout` is set to false.
    */
   async search(
     serverId: string,
@@ -294,8 +306,9 @@ class Messages {
   /**
    * Creates a new message that can be sent to a verified email address. This is useful
    * in scenarios where you want an email to trigger a workflow in your product.
-   * @param serverId The unique identifier of the required server.
+   * @param serverId The unique identifier of the required inbox (server).
    * @param options Options to use when creating a new message.
+   * @returns A promise resolving to the newly-created {@link Message}.
    */
   async create(
     serverId: string,
@@ -329,8 +342,10 @@ class Messages {
   }
 
   /**
+   * Forwards the specified message to a verified email address. This is useful for simulating a user forwarding one of your email messages.
    * @param messageId The unique identifier of the message to be forwarded.
    * @param options Options to use when forwarding a message.
+   * @returns A promise resolving to the forwarded {@link Message}.
    */
   async forward(
     messageId: string,
@@ -361,8 +376,9 @@ class Messages {
 
   /**
    * Sends a reply to the specified message. This is useful for when simulating a user replying to one of your email or SMS messages.
-   * @param messageId The unique identifier of the message to be forwarded.
+   * @param messageId The unique identifier of the message to be replied to.
    * @param options Options to use when replying to a message.
+   * @returns A promise resolving to the reply {@link Message}.
    */
   async reply(
     messageId: string,
@@ -395,6 +411,7 @@ class Messages {
    * Generates screenshots of an email rendered in the specified email clients.
    * @param messageId The identifier of the email to preview.
    * @param options The options with which to generate previews.
+   * @returns A promise resolving to a {@link PreviewListResult} containing the generated previews.
    */
   async generatePreviews(
     messageId: string,

src/operations/previews.ts

@@ -2,6 +2,10 @@ import EmailClientListResult from '../models/emailClientListResult.js';
 import type { HttpResponse } from '../request.js';
 import type MailosaurClient from '../mailosaur.js';
 
+/**
+ * Operations for discovering the email clients available for generating email previews
+ * (screenshots of an email rendered in real clients). Accessed via `client.previews`.
+ */
 class Previews {
   client: MailosaurClient;
 
@@ -11,6 +15,7 @@ class Previews {
 
   /**
    * List all email clients that can be used to generate email previews.
+   * @returns A promise resolving to an {@link EmailClientListResult} of available email clients.
    */
   async listEmailClients(): Promise<EmailClientListResult> {
     const url = `api/screenshots/clients`;