@stablyai/email 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,272 @@
+import * as z4 from 'zod/v4/core';
+
+/**
+ * Schema type for structured extraction. Supports Zod v4 schemas.
+ */
+type ExtractSchema = {
+    safeParseAsync(data: unknown, params?: z4.ParseContext<z4.$ZodIssue>): Promise<z4.util.SafeParseResult<z4.output<any>>>;
+} & z4.$ZodType;
+/** Output type inferred from a schema. */
+type SchemaOutput<T extends ExtractSchema> = z4.output<T>;
+/** Result from email extraction. */
+type ExtractResult<T> = {
+    data: T;
+    reason: string;
+};
+/**
+ * Error thrown when email extraction fails.
+ */
+declare class EmailExtractionError extends Error {
+    /** The reason extraction failed. */
+    readonly reason: string;
+    constructor(message: string, reason: string);
+}
+
+/** An email address with optional display name. */
+type EmailAddress = {
+    /** The email address (e.g., "user@example.com"). */
+    address: string;
+    /** Optional display name (e.g., "John Doe"). */
+    name?: string;
+};
+/** An email message. */
+type Email = {
+    /** Unique identifier for the email. */
+    id: string;
+    /** The mailbox containing this email (e.g., "INBOX"). */
+    mailbox: string;
+    /** The sender's email address. */
+    from: EmailAddress;
+    /** The recipient email addresses. */
+    to: EmailAddress[];
+    /** The email subject line. */
+    subject: string;
+    /** When the email was received. */
+    receivedAt: Date;
+    /** HTML content of the email body, if available. */
+    html?: string[];
+    /** Plain text content of the email body, if available. */
+    text?: string;
+};
+/** Options for listing emails in an inbox. */
+type ListEmailsOptions = {
+    /** Filter by sender email address. */
+    from?: string;
+    /** Filter by subject line. */
+    subject?: string;
+    /** How to match the subject: "contains" (default) or "exact". */
+    subjectMatch?: "contains" | "exact";
+    /** Maximum number of emails to return. */
+    limit?: number;
+    /** Pagination cursor from a previous response. */
+    cursor?: string;
+    /** Only return emails received after this date. Overrides the default createdAt filter. */
+    since?: Date;
+    /** Set to true to include emails received before the inbox was created. */
+    includeOlder?: boolean;
+};
+
+/** Options for waiting for an email to arrive. */
+type WaitForEmailOptions = {
+    /** Filter by sender email address. */
+    from?: string;
+    /** Filter by subject line. */
+    subject?: string;
+    /** How to match the subject: "contains" (default) or "exact". */
+    subjectMatch?: "contains" | "exact";
+    /** Maximum time to wait. @default 120000 (2 minutes) */
+    timeoutMs?: number;
+    /** Time between poll attempts. Minimum 1000ms. @default 3000 (3 seconds) */
+    pollIntervalMs?: number;
+};
+/** Error thrown when waitForEmail() times out without finding a matching email. */
+declare class EmailTimeoutError extends Error {
+    constructor(message: string);
+}
+
+/** Options for creating an inbox instance. */
+type GetInboxOptions = {
+    /** Optional suffix for test isolation (e.g., "test-123" creates "org+test-123@mail.stably.ai"). */
+    suffix?: string;
+    /** Stably API key. Defaults to STABLY_API_KEY environment variable. */
+    apiKey?: string;
+    /** Stably project ID. Defaults to STABLY_PROJECT_ID environment variable. */
+    projectId?: string;
+};
+/**
+ * An email inbox scoped to a specific address.
+ *
+ * Use {@link Inbox.build} to create an instance. All operations are automatically
+ * scoped to this inbox's address and creation time for test isolation.
+ *
+ * @example
+ * ```ts
+ * const inbox = await Inbox.build({ suffix: `test-${Date.now()}` });
+ * console.log(inbox.address); // "org+test-123@mail.stably.ai"
+ *
+ * const { emails } = await inbox.listEmails({ subject: 'verification' });
+ * ```
+ */
+declare class Inbox {
+    /** The full email address for this inbox (includes suffix if provided). */
+    readonly address: string;
+    /** The suffix used when creating this inbox, if any. */
+    readonly suffix?: string;
+    /** When this inbox instance was created. Used for filtering out older emails. */
+    readonly createdAt: Date;
+    private readonly baseAddress;
+    private readonly client;
+    private readonly projectId;
+    /** @internal Use {@link Inbox.build} to create an Inbox instance. */
+    private constructor();
+    /**
+     * Creates an inbox instance for receiving and managing test emails.
+     *
+     * @param options - Configuration options including optional suffix for test isolation.
+     * @returns An inbox instance scoped to your organization's email address.
+     * @throws Error if API key or project ID is missing and not set in environment.
+     *
+     * @example
+     * ```ts
+     * // Use environment variables (STABLY_API_KEY, STABLY_PROJECT_ID)
+     * const inbox = await Inbox.build();
+     *
+     * // With suffix for test isolation
+     * const inbox = await Inbox.build({ suffix: `test-${Date.now()}` });
+     * console.log(inbox.address); // "my-org+test-1234567890@mail.stably.ai"
+     * ```
+     */
+    static build(options?: GetInboxOptions): Promise<Inbox>;
+    /**
+     * Lists emails in this inbox.
+     *
+     * By default, only returns emails received **after this `Inbox` was created**
+     * (via `Inbox.build()`). This prevents stale emails from previous test runs
+     * from appearing in results. Use `includeOlder: true` to include older emails.
+     *
+     * @param options - Filter and pagination options.
+     * @returns The matching emails and an optional cursor for pagination.
+     *
+     * @example
+     * ```ts
+     * const { emails } = await inbox.listEmails();
+     * const { emails } = await inbox.listEmails({ includeOlder: true });
+     * ```
+     */
+    listEmails(options?: ListEmailsOptions): Promise<{
+        emails: Email[];
+        nextCursor?: string;
+    }>;
+    /**
+     * Gets a specific email by ID.
+     *
+     * @param id - The email ID to retrieve (from {@link Inbox.listEmails}).
+     * @returns The email with the given ID.
+     * @throws Error if the email is not found or API call fails.
+     *
+     * @example
+     * ```ts
+     * const { emails } = await inbox.listEmails();
+     * const email = await inbox.getEmail(emails[0].id);
+     * console.log(email.subject);
+     * ```
+     */
+    getEmail(id: string): Promise<Email>;
+    /**
+     * Deletes an email from this inbox.
+     *
+     * @param id - The unique identifier of the email to delete.
+     * @throws Error if the email doesn't exist or deletion fails.
+     *
+     * @example
+     * ```ts
+     * const { emails } = await inbox.listEmails({ subject: 'old notification' });
+     * if (emails.length > 0) {
+     *   await inbox.deleteEmail(emails[0].id);
+     * }
+     * ```
+     */
+    deleteEmail(id: string): Promise<void>;
+    /**
+     * Deletes all emails sent to this inbox's address.
+     *
+     * If the inbox was created with a suffix, only emails sent to that specific
+     * suffixed address are deleted (e.g., "org+test-123@mail.stably.ai"), not
+     * the entire org mailbox.
+     *
+     * @example
+     * ```ts
+     * const inbox = await Inbox.build({ suffix: `test-${Date.now()}` });
+     * // ... receive and process emails ...
+     * await inbox.deleteAllEmails(); // Only deletes emails sent to this suffix
+     * ```
+     */
+    deleteAllEmails(): Promise<void>;
+    /**
+     * Waits for an email matching the filters to arrive.
+     *
+     * Only returns emails received after the inbox was created, preventing
+     * stale emails from previous test runs from being matched.
+     *
+     * @param options - Filter and timeout options.
+     * @returns The first matching email.
+     * @throws {EmailTimeoutError} If no matching email arrives within the timeout.
+     *
+     * @example
+     * ```ts
+     * const email = await inbox.waitForEmail({ subject: 'Welcome' });
+     *
+     * const email = await inbox.waitForEmail({
+     *   from: 'noreply@example.com',
+     *   subject: 'verification',
+     *   timeoutMs: 60000,
+     *   pollIntervalMs: 5000,
+     * });
+     * ```
+     */
+    waitForEmail(options?: WaitForEmailOptions): Promise<Email>;
+    /**
+     * Extracts data from an email using AI.
+     *
+     * @param args - The email ID and prompt describing what to extract.
+     * @returns The extracted string.
+     * @throws {@link EmailExtractionError} if extraction fails.
+     *
+     * @example
+     * ```ts
+     * const otp = await inbox.extractFromEmail({ id: email.id, prompt: 'Extract the OTP code' });
+     * ```
+     */
+    extractFromEmail(args: {
+        id: string;
+        prompt: string;
+    }): Promise<string>;
+    /**
+     * Extracts structured data from an email using AI with a Zod schema.
+     *
+     * @param args - The email ID, prompt, and Zod v4 schema for structured output.
+     * @returns The extracted data matching the schema type.
+     * @throws {@link EmailExtractionError} if extraction fails.
+     * @throws Error if schema validation fails or Zod v4 is not installed.
+     *
+     * @example
+     * ```ts
+     * import { z } from 'zod/v4';
+     *
+     * const { code, expiresAt } = await inbox.extractFromEmail({
+     *   id: email.id,
+     *   prompt: 'Extract the verification code and expiry',
+     *   schema: z.object({ code: z.string(), expiresAt: z.string() }),
+     * });
+     * ```
+     */
+    extractFromEmail<T extends ExtractSchema>(args: {
+        id: string;
+        prompt: string;
+        schema: T;
+    }): Promise<SchemaOutput<T>>;
+}
+
+export { EmailExtractionError, EmailTimeoutError, Inbox };
+export type { Email, EmailAddress, ExtractResult, ExtractSchema, GetInboxOptions, ListEmailsOptions, SchemaOutput, WaitForEmailOptions };
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sources":["../src/extract.ts","../src/list.ts","../src/wait-for-email.ts","../src/inbox.ts"],"mappings":";;AAkBA;;;AAGM,KAAM,aAAa;2CAGZ,EAAE,CAAC,YAAY,CAAC,EAAE,CAAC,SAAS,IAEpC,OAAO,CAAC,EAAE,CAAC,IAAI,CAAC,eAAe,CAAC,EAAE,CAAC,MAAM;IAC1C,EAAE,CAAC,QAAQ;AAEf;AACM,KAAM,YAAY,WAAW,aAAa,IAAI,EAAE,CAAC,MAAM;AAE7D;AACM,KAAM,aAAa;;;;AAKzB;;;AAGA,cAAa,oBAAqB,SAAQ,KAAK;;;;;;AClC/C;AACM,KAAM,YAAY;;;;;;AAOxB;AACM,KAAM,KAAK;;;;;;UAMT,YAAY;;QAEd,YAAY;;;;gBAIJ,IAAI;;;;;;AAOlB;AACM,KAAM,iBAAiB;;;;;;;;;;;;YAYnB,IAAI;;;;;ACxCd;AACM,KAAM,mBAAmB;;;;;;;;;;;;AAa/B;AACA,cAAa,iBAAkB,SAAQ,KAAK;;;;ACH5C;AACM,KAAM,eAAe;;;;;;;;AAS3B;;;;;;;;;;;;;;AAcA,cAAa,KAAK;;;;;;wBAMI,IAAI;;;;;;;;;;;;;;;;;;;;;;;2BAqDK,eAAe,GAAG,OAAO,CAAC,KAAK;;;;;;;;;;;;;;;;;yBAqDhD,iBAAiB,GAC1B,OAAO;gBAAW,KAAK;;;;;;;;;;;;;;;;;0BAwBE,OAAO,CAAC,KAAK;;;;;;;;;;;;;;;6BAkCV,OAAO;;;;;;;;;;;;;;;uBAkCb,OAAO;;;;;;;;;;;;;;;;;;;;;;;2BAoCH,mBAAmB,GAAG,OAAO,CAAC,KAAK;;;;;;;;;;;;;;;;QAsBR,OAAO;;;;;;;;;;;;;;;;;;;;+BAoBpC,aAAa;;;;QAIpC,OAAO,CAAC,YAAY","names":[]}