@decaf-ts/integrations 0.10.8 → 0.12.0

package/lib/types/comms/email/mime.d.mts

@@ -0,0 +1,84 @@
+/**
+ * @description A message attachment
+ * @summary Content is base64 text by default; with `encoding: "utf8"` the
+ * builder base64-encodes the UTF-8 content itself.
+ * @category Comms
+ * @memberOf module:integrations/comms/email/mime
+ */
+export interface EmailAttachment {
+    filename: string;
+    content: string;
+    encoding?: "base64" | "utf8";
+    contentType?: string;
+}
+/**
+ * @description Input for building a raw MIME message
+ * @summary Carries the sender, recipients (single address, comma-separated
+ * string, or array), subject, optional text and HTML bodies, `Reply-To`, and
+ * attachments.
+ * @category Comms
+ * @memberOf module:integrations/comms/email/mime
+ */
+export interface EmailMessageInput {
+    from: string;
+    to: string | string[];
+    cc?: string | string[];
+    bcc?: string | string[];
+    subject: string;
+    text?: string;
+    html?: string;
+    replyTo?: string;
+    attachments?: EmailAttachment[];
+}
+/**
+ * @description The built MIME message ready for delivery
+ * @summary Carries the raw RFC 5322 text, the resolved sender, the flattened
+ * recipient list (To/Cc/Bcc), and the generated `Message-ID`.
+ * @category Comms
+ * @memberOf module:integrations/comms/email/mime
+ */
+export interface BuiltEmail {
+    raw: string;
+    from: string;
+    recipients: string[];
+    messageId: string;
+}
+/**
+ * Validates a mailbox address against the allowlist and returns it trimmed.
+ *
+ * @param value - Candidate address.
+ * @param field - Human-readable field name used in the error message.
+ * @returns The trimmed, validated mailbox address.
+ * @throws {BadRequestError} when the address contains control characters or is not a bare mailbox.
+ */
+export declare function assertEmailAddress(value: string, field?: string): string;
+/**
+ * @description Encodes a MIME header value safely
+ * @summary Pure-ASCII values pass through; anything else becomes an RFC 2047
+ * `=?UTF-8?B?...?=` encoded word.
+ * @param value - Raw header value
+ * @returns The header value safe for raw message transport
+ */
+export declare function encodeHeader(value: string): string;
+/**
+ * @description Normalizes a recipient input into an allowlisted address list
+ * @summary Splits comma-separated strings, trims entries, drops empties, and
+ * validates every remaining entry as a bare mailbox address. Values carrying
+ * CR/LF, NUL, or other control characters are rejected outright so workflow
+ * input can never inject MIME headers or SMTP envelope commands.
+ * @param value - Single address, comma-separated string, array, or `undefined`
+ * @returns The trimmed, validated list of addresses
+ * @throws {BadRequestError} when an entry is not a valid mailbox address
+ */
+export declare function parseAddressList(value: string | string[] | undefined): string[];
+/**
+ * @description Builds the complete raw MIME message
+ * @summary Generates the `Message-ID`, resolves recipients (throwing when
+ * none remain), emits the standard headers, and assembles the body entity
+ * (alternative text/HTML parts, plus attachments when present).
+ * @param input - Message input
+ * @returns The built message with raw text, sender, recipients, and `Message-ID`
+ * @throws {BadRequestError} when the message has no recipient or any address,
+ *   attachment filename, or content type fails validation
+ */
+export declare function buildEmail(input: EmailMessageInput): BuiltEmail;

package/lib/types/comms/email/smtp.d.cts

@@ -0,0 +1,107 @@
+/**
+ * @description SMTP connection configuration
+ * @summary Carries the server address, optional implicit-TLS/STARTTLS
+ * selection, credentials, and timeouts.
+ *
+ * `secure` selects implicit TLS: `true` opens a TLS socket from the first byte
+ * (default port 465). `false` connects in plaintext and upgrades with STARTTLS
+ * when the server advertises it (default port 587). When credentials are
+ * configured, `connect()` refuses to authenticate unless the session is
+ * encrypted; `allowPlaintextAuth` is the explicit, documented opt-out for
+ * servers that cannot offer TLS.
+ * @category Comms
+ * @memberOf module:integrations/comms/email/smtp
+ */
+export interface SmtpConfig {
+    /** @description SMTP server hostname (required) */
+    host: string;
+    /** @description Server port; defaults to `465` when `secure` is `true`, `587` otherwise */
+    port?: number;
+    /** @description `true` opens an implicit-TLS socket from the first byte; `false` (default) connects in plaintext and upgrades via STARTTLS */
+    secure?: boolean;
+    /** @description Username for `AUTH LOGIN`; when set with `password`, enables the fail-closed plaintext-AUTH check */
+    username?: string;
+    /** @description Password for `AUTH LOGIN` */
+    password?: string;
+    /** @description Connection, greeting, and socket timeout in milliseconds (default `30000`) */
+    timeout?: number;
+    /** @description Explicitly permit `AUTH LOGIN` over a plaintext session (default `false`) */
+    allowPlaintextAuth?: boolean;
+    /** @description Explicitly accept an otherwise-invalid TLS certificate (default `false`) */
+    allowUnauthorizedCerts?: boolean;
+    /** @description Client hostname announced in `EHLO` (default `as-graph`) */
+    clientHostname?: string;
+}
+/**
+ * @description SMTP client for raw MIME delivery
+ * @summary Connects and authenticates through a nodemailer SMTP transport
+ * (implicit TLS on `secure`, STARTTLS otherwise), then delivers a pre-built
+ * message with the envelope sender/recipients and the raw RFC 5322 source.
+ * Credentials are never sent over a plaintext session unless
+ * `allowPlaintextAuth` is set, and every envelope address is validated before
+ * it reaches the transport.
+ * @category Comms
+ * @memberOf module:integrations/comms/email/smtp
+ * @example
+ * ```ts
+ * import { SmtpClient, buildEmail } from "@decaf-ts/integrations/comms/email";
+ *
+ * const client = new SmtpClient({
+ *   host: "smtp.example.com",
+ *   port: 587,
+ *   username: "noreply@example.com",
+ *   password: process.env.SMTP_PASSWORD,
+ * });
+ * await client.connect();
+ * const mail = buildEmail({
+ *   from: "noreply@example.com",
+ *   to: ["ops@example.com"],
+ *   subject: "Nightly report",
+ *   text: "All systems nominal.",
+ * });
+ * await client.send(mail.from, mail.recipients, mail.raw);
+ * await client.close();
+ * ```
+ */
+export declare class SmtpClient {
+    private config;
+    private transporter?;
+    /**
+     * @description Creates an SMTP client
+     * @summary Stores the config; the nodemailer transport is only created and
+     * verified by {@link SmtpClient.connect}.
+     * @param config - Server address, optional credentials, and TLS/timeout options
+     */
+    constructor(config: SmtpConfig);
+    private transportOptions;
+    private transportError;
+    /**
+     * @description Opens the SMTP session
+     * @summary Lazily loads the optional `nodemailer` peer, builds the SMTP
+     * transport for the configured host/credentials, and verifies it
+     * (`EHLO` + TLS upgrade + `AUTH LOGIN` when credentials are configured).
+     * Authentication fails closed: with credentials configured and no encrypted
+     * session, the transport requires STARTTLS and verification fails unless
+     * `allowPlaintextAuth` was set on the config.
+     * @throws {InternalError} when `nodemailer` is not installed, or on
+     * connection, TLS, or auth failures
+     */
+    connect(): Promise<void>;
+    /**
+     * @description Delivers a raw message over the established session
+     * @summary Validates the envelope, then hands the sender, recipients, and
+     * raw RFC 5322 source to nodemailer's `sendMail` (the transport performs
+     * queueing, dot-stuffing, and CRLF normalization).
+     * @param from - Envelope sender address
+     * @param recipients - Envelope recipient addresses
+     * @param raw - Raw RFC 5322 message text
+     * @throws {InternalError} when not connected or the server rejects delivery
+     * @throws {BadRequestError} when the envelope sender or a recipient is not an allowlisted mailbox
+     */
+    send(from: string, recipients: string[], raw: string): Promise<void>;
+    /**
+     * @description Closes the session gracefully
+     * @summary Closes the nodemailer transport, ignoring shutdown failures.
+     */
+    close(): Promise<void>;
+}

package/lib/types/comms/email/smtp.d.mts

@@ -0,0 +1,107 @@
+/**
+ * @description SMTP connection configuration
+ * @summary Carries the server address, optional implicit-TLS/STARTTLS
+ * selection, credentials, and timeouts.
+ *
+ * `secure` selects implicit TLS: `true` opens a TLS socket from the first byte
+ * (default port 465). `false` connects in plaintext and upgrades with STARTTLS
+ * when the server advertises it (default port 587). When credentials are
+ * configured, `connect()` refuses to authenticate unless the session is
+ * encrypted; `allowPlaintextAuth` is the explicit, documented opt-out for
+ * servers that cannot offer TLS.
+ * @category Comms
+ * @memberOf module:integrations/comms/email/smtp
+ */
+export interface SmtpConfig {
+    /** @description SMTP server hostname (required) */
+    host: string;
+    /** @description Server port; defaults to `465` when `secure` is `true`, `587` otherwise */
+    port?: number;
+    /** @description `true` opens an implicit-TLS socket from the first byte; `false` (default) connects in plaintext and upgrades via STARTTLS */
+    secure?: boolean;
+    /** @description Username for `AUTH LOGIN`; when set with `password`, enables the fail-closed plaintext-AUTH check */
+    username?: string;
+    /** @description Password for `AUTH LOGIN` */
+    password?: string;
+    /** @description Connection, greeting, and socket timeout in milliseconds (default `30000`) */
+    timeout?: number;
+    /** @description Explicitly permit `AUTH LOGIN` over a plaintext session (default `false`) */
+    allowPlaintextAuth?: boolean;
+    /** @description Explicitly accept an otherwise-invalid TLS certificate (default `false`) */
+    allowUnauthorizedCerts?: boolean;
+    /** @description Client hostname announced in `EHLO` (default `as-graph`) */
+    clientHostname?: string;
+}
+/**
+ * @description SMTP client for raw MIME delivery
+ * @summary Connects and authenticates through a nodemailer SMTP transport
+ * (implicit TLS on `secure`, STARTTLS otherwise), then delivers a pre-built
+ * message with the envelope sender/recipients and the raw RFC 5322 source.
+ * Credentials are never sent over a plaintext session unless
+ * `allowPlaintextAuth` is set, and every envelope address is validated before
+ * it reaches the transport.
+ * @category Comms
+ * @memberOf module:integrations/comms/email/smtp
+ * @example
+ * ```ts
+ * import { SmtpClient, buildEmail } from "@decaf-ts/integrations/comms/email";
+ *
+ * const client = new SmtpClient({
+ *   host: "smtp.example.com",
+ *   port: 587,
+ *   username: "noreply@example.com",
+ *   password: process.env.SMTP_PASSWORD,
+ * });
+ * await client.connect();
+ * const mail = buildEmail({
+ *   from: "noreply@example.com",
+ *   to: ["ops@example.com"],
+ *   subject: "Nightly report",
+ *   text: "All systems nominal.",
+ * });
+ * await client.send(mail.from, mail.recipients, mail.raw);
+ * await client.close();
+ * ```
+ */
+export declare class SmtpClient {
+    private config;
+    private transporter?;
+    /**
+     * @description Creates an SMTP client
+     * @summary Stores the config; the nodemailer transport is only created and
+     * verified by {@link SmtpClient.connect}.
+     * @param config - Server address, optional credentials, and TLS/timeout options
+     */
+    constructor(config: SmtpConfig);
+    private transportOptions;
+    private transportError;
+    /**
+     * @description Opens the SMTP session
+     * @summary Lazily loads the optional `nodemailer` peer, builds the SMTP
+     * transport for the configured host/credentials, and verifies it
+     * (`EHLO` + TLS upgrade + `AUTH LOGIN` when credentials are configured).
+     * Authentication fails closed: with credentials configured and no encrypted
+     * session, the transport requires STARTTLS and verification fails unless
+     * `allowPlaintextAuth` was set on the config.
+     * @throws {InternalError} when `nodemailer` is not installed, or on
+     * connection, TLS, or auth failures
+     */
+    connect(): Promise<void>;
+    /**
+     * @description Delivers a raw message over the established session
+     * @summary Validates the envelope, then hands the sender, recipients, and
+     * raw RFC 5322 source to nodemailer's `sendMail` (the transport performs
+     * queueing, dot-stuffing, and CRLF normalization).
+     * @param from - Envelope sender address
+     * @param recipients - Envelope recipient addresses
+     * @param raw - Raw RFC 5322 message text
+     * @throws {InternalError} when not connected or the server rejects delivery
+     * @throws {BadRequestError} when the envelope sender or a recipient is not an allowlisted mailbox
+     */
+    send(from: string, recipients: string[], raw: string): Promise<void>;
+    /**
+     * @description Closes the session gracefully
+     * @summary Closes the nodemailer transport, ignoring shutdown failures.
+     */
+    close(): Promise<void>;
+}

package/lib/types/comms/environment.d.cts

@@ -0,0 +1,84 @@
+/**
+ * @module integrations/comms/environment
+ * @summary Environment contract and accumulated environment for the comms integration services.
+ * @description Declares the `CommsEnvironmentShape` consumed by the Slack,
+ * Telegram, Teams, and Gmail services' `configFromEnvironment()` implementations and the
+ * `CommsEnvironment` singleton created via `LoggedEnvironment.accumulate`.
+ * Services read their credentials and defaults from the matching
+ * `comms.<provider>` slice, using the `envString`/`envNumber` helpers from
+ * `shared/environmentValue` to reject unset-leaf proxies.
+ */
+/**
+ * @description Environment shape for the comms integration services
+ * @summary Defines the `comms` root with one slice per provider (`slack`,
+ * `telegram`, `teams`, `email`, `gmail`). Each slice carries the provider's
+ * required credentials (e.g. `token`, `webhookUrl`) plus optional `baseUrl`
+ * override and `timeout`. Fields are typed as required here so
+ * `LoggedEnvironment.accumulate` registers them; absent values resolve to
+ * proxy placeholders at runtime and must pass through `envString`/`envNumber`.
+ * @memberOf module:integrations/comms/environment
+ */
+export interface CommsEnvironmentShape {
+    comms: {
+        slack: {
+            token: string;
+            baseUrl: string;
+            timeout?: number;
+        };
+        telegram: {
+            token: string;
+            baseUrl: string;
+            timeout?: number;
+        };
+        teams: {
+            token: string;
+            webhookUrl: string;
+            baseUrl: string;
+            timeout?: number;
+        };
+        email: {
+            provider: string;
+            host: string;
+            port?: number;
+            secure?: boolean;
+            username: string;
+            password: string;
+            from: string;
+            token: string;
+            graphBaseUrl: string;
+            /** Explicit opt-in for SMTP AUTH over a plaintext session (default false). */
+            allowPlaintextAuth?: boolean;
+            timeout?: number;
+        };
+        gmail: {
+            token: string;
+            userId: string;
+            baseUrl: string;
+            timeout?: number;
+        };
+    };
+}
+/**
+ * @description Accumulated comms environment singleton
+ * @summary The `LoggedEnvironment.accumulate`-registered instance backing the
+ * `CommsEnvironmentShape` contract. Comms services read their provider slice
+ * (e.g. `CommsEnvironment.comms.slack`) inside `configFromEnvironment()` and
+ * translate it into an `HttpApiServiceConfig`-derived config. Credentials come
+ * from environment variables; for as-graph node usage those are provided as
+ * `GRAPH_CREDENTIAL_*` values (placeholders in this example).
+ * @example
+ * ```ts
+ * import { SlackService } from "@decaf-ts/integrations/comms/slack";
+ *
+ * // with comms.slack.token / comms.slack.baseUrl configured in the environment
+ * const slack = new SlackService();
+ * await slack.initialize();
+ * ```
+ * @constant {LoggedEnvironment} CommsEnvironment
+ * @memberOf module:integrations/comms/environment
+ */
+export declare const CommsEnvironment: import("@decaf-ts/logging").AccumulatedEnvironment<{
+    app: string | undefined;
+} & import("@decaf-ts/logging").LoggingConfig<object> & {
+    env: any;
+} & CommsEnvironmentShape>;

package/lib/types/comms/environment.d.mts

@@ -0,0 +1,84 @@
+/**
+ * @module integrations/comms/environment
+ * @summary Environment contract and accumulated environment for the comms integration services.
+ * @description Declares the `CommsEnvironmentShape` consumed by the Slack,
+ * Telegram, Teams, and Gmail services' `configFromEnvironment()` implementations and the
+ * `CommsEnvironment` singleton created via `LoggedEnvironment.accumulate`.
+ * Services read their credentials and defaults from the matching
+ * `comms.<provider>` slice, using the `envString`/`envNumber` helpers from
+ * `shared/environmentValue` to reject unset-leaf proxies.
+ */
+/**
+ * @description Environment shape for the comms integration services
+ * @summary Defines the `comms` root with one slice per provider (`slack`,
+ * `telegram`, `teams`, `email`, `gmail`). Each slice carries the provider's
+ * required credentials (e.g. `token`, `webhookUrl`) plus optional `baseUrl`
+ * override and `timeout`. Fields are typed as required here so
+ * `LoggedEnvironment.accumulate` registers them; absent values resolve to
+ * proxy placeholders at runtime and must pass through `envString`/`envNumber`.
+ * @memberOf module:integrations/comms/environment
+ */
+export interface CommsEnvironmentShape {
+    comms: {
+        slack: {
+            token: string;
+            baseUrl: string;
+            timeout?: number;
+        };
+        telegram: {
+            token: string;
+            baseUrl: string;
+            timeout?: number;
+        };
+        teams: {
+            token: string;
+            webhookUrl: string;
+            baseUrl: string;
+            timeout?: number;
+        };
+        email: {
+            provider: string;
+            host: string;
+            port?: number;
+            secure?: boolean;
+            username: string;
+            password: string;
+            from: string;
+            token: string;
+            graphBaseUrl: string;
+            /** Explicit opt-in for SMTP AUTH over a plaintext session (default false). */
+            allowPlaintextAuth?: boolean;
+            timeout?: number;
+        };
+        gmail: {
+            token: string;
+            userId: string;
+            baseUrl: string;
+            timeout?: number;
+        };
+    };
+}
+/**
+ * @description Accumulated comms environment singleton
+ * @summary The `LoggedEnvironment.accumulate`-registered instance backing the
+ * `CommsEnvironmentShape` contract. Comms services read their provider slice
+ * (e.g. `CommsEnvironment.comms.slack`) inside `configFromEnvironment()` and
+ * translate it into an `HttpApiServiceConfig`-derived config. Credentials come
+ * from environment variables; for as-graph node usage those are provided as
+ * `GRAPH_CREDENTIAL_*` values (placeholders in this example).
+ * @example
+ * ```ts
+ * import { SlackService } from "@decaf-ts/integrations/comms/slack";
+ *
+ * // with comms.slack.token / comms.slack.baseUrl configured in the environment
+ * const slack = new SlackService();
+ * await slack.initialize();
+ * ```
+ * @constant {LoggedEnvironment} CommsEnvironment
+ * @memberOf module:integrations/comms/environment
+ */
+export declare const CommsEnvironment: import("@decaf-ts/logging").AccumulatedEnvironment<{
+    app: string | undefined;
+} & import("@decaf-ts/logging").LoggingConfig<object> & {
+    env: any;
+} & CommsEnvironmentShape>;

package/lib/types/comms/gmail/GmailService.d.cts

@@ -0,0 +1,190 @@
+import { HttpApiService, type HttpApiServiceConfig } from "../../shared/http/index.d.cts";
+import { type EmailMessageInput } from "../email/mime.d.cts";
+/**
+ * @description Configuration for the Gmail service
+ * @summary Extends {@link HttpApiServiceConfig} with the OAuth access token
+ * (sent as a bearer token) and the mailbox `userId` used in the API path
+ * (defaults to `"me"`). When omitted, the `comms.gmail` environment slice
+ * supplies the token (and optional `userId`, `baseUrl`, `timeout`).
+ * @category Comms
+ * @memberOf module:integrations/comms/gmail/service
+ */
+export interface GmailServiceConfig extends HttpApiServiceConfig {
+    /**
+     * @description Gmail API OAuth access token
+     * @summary Sent as `Authorization: Bearer <token>` with every API call.
+     */
+    token?: string;
+    /**
+     * @description Mailbox user identifier
+     * @summary The special value `"me"` (the default) refers to the authenticated user.
+     */
+    userId?: string;
+}
+/**
+ * @description Result of a sent Gmail message
+ * @summary Echoes Gmail's identifiers for the sent message: the message `id`,
+ * its `threadId` when Gmail assigned one, and the applied `labelIds`.
+ * @category Comms
+ * @memberOf module:integrations/comms/gmail/service
+ */
+export interface GmailSendResult {
+    id: string;
+    threadId?: string;
+    labelIds?: string[];
+}
+/**
+ * @description Result of a Gmail message list call
+ * @summary Carries one page of message references (`messages` with `id` and
+ * optional `threadId`), the `nextPageToken` to pass back as `pageToken` for
+ * the next page, and Gmail's `resultSizeEstimate`.
+ * @category Comms
+ * @memberOf module:integrations/comms/gmail/service
+ */
+export interface GmailListResult {
+    messages: Array<{
+        id: string;
+        threadId?: string;
+    }>;
+    nextPageToken?: string;
+    resultSizeEstimate?: number;
+}
+/**
+ * @description Gmail API integration service
+ * @summary An undecorated HTTP service for sending MIME-built
+ * emails, listing messages with Gmail query syntax and page tokens, fetching
+ * a single message in a chosen format, and listing labels. All operations
+ * require an OAuth token (`requireToken()`) and operate on the configured
+ * `userId` mailbox (default `"me"`); transport failures are mapped to decaf
+ * errors via {@link httpError}.
+ * @class GmailService
+ * @category Comms
+ * @example
+ * ```ts
+ * import { GmailService } from "@decaf-ts/integrations/comms/gmail";
+ *
+ * const gmail = new GmailService();
+ * await gmail.initialize({
+ *   token: process.env.GRAPH_CREDENTIAL_GMAIL_TOKEN,
+ * });
+ * await gmail.send({
+ *   from: "bot@example.com",
+ *   to: "ops@example.com",
+ *   subject: "Deploy",
+ *   text: "Release 1.2.0 is live",
+ * });
+ * ```
+ * @memberOf module:integrations/comms/gmail/service
+ */
+export declare class GmailService extends HttpApiService<GmailServiceConfig> {
+    /**
+     * @description The provider name used in error messages
+     */
+    protected readonly serviceName = "Gmail";
+    /**
+     * @description The Gmail REST API base URL
+     * @summary Used when the resolved config carries no `baseUrl`.
+     * @returns {string} `"https://gmail.googleapis.com/gmail/v1"`.
+     */
+    protected defaultBaseUrl(): string;
+    /**
+     * @description Builds the Gmail OAuth bearer authorization headers
+     * @summary Returns the `Authorization: Bearer <token>` header when the
+     * config carries a token, and no headers otherwise.
+     * @param {GmailServiceConfig} config - The resolved service configuration.
+     * @returns {Record<string, string>} The authorization headers (empty without a token).
+     */
+    protected authHeaders(config: GmailServiceConfig): Record<string, string>;
+    /**
+     * @description Reads the Gmail credentials and defaults from the environment
+     * @summary Reads the `comms.gmail` environment slice and returns a partial
+     * config when a token is configured, `undefined` otherwise. Values pass
+     * through `envString`/`envNumber` to reject unset-leaf proxies.
+     * @returns {Partial<GmailServiceConfig> | undefined} A partial config, or `undefined` when no Gmail token is configured.
+     */
+    protected configFromEnvironment(): Partial<GmailServiceConfig> | undefined;
+    /**
+     * @description Builds the mailbox-scoped API path
+     * @summary Returns `/users/<userId>` with the configured `userId` (or
+     * `"me"` when unset) URL-encoded; all message and label operations are
+     * relative to this path.
+     * @returns {string} The URL-encoded mailbox path.
+     */
+    protected userPath(): string;
+    /**
+     * @description Sends an email through the Gmail API
+     * @summary Builds a raw MIME message from the input with the shared email
+     * MIME builder (`buildEmail`), base64url-encodes it, and `POST`s it to
+     * `users.messages.send`. Requires a token and a `from` sender address.
+     * @param {EmailMessageInput} input - The message envelope and body (`from`, `to`, `subject`, and optional `cc`/`bcc`/`text`/`html`/`replyTo`/`attachments`).
+     * @returns {Promise<GmailSendResult>} Gmail's identifiers for the sent message.
+     * @throws {InternalError} When no token is configured or the sender address is missing.
+     * @throws {NotFoundError} When the endpoint answers with HTTP 404.
+     * @throws {ConflictError} When Gmail answers with HTTP 409.
+     * @throws {BadRequestError} When Gmail answers with any other HTTP error status (e.g. invalid recipients).
+     */
+    send(input: EmailMessageInput): Promise<GmailSendResult>;
+    /**
+     * @description Lists mailbox messages with Gmail query paging
+     * @summary `GET`s `users.messages.list` with an optional Gmail `query`
+     * (`q` parameter, e.g. `"from:user@example.com is:unread"`), a page size
+     * (default `25`), a `pageToken` from the previous page, and `labelIds`
+     * filtering. Returns the message references and the `nextPageToken` to pass
+     * back as `pageToken` for the next page.
+     * @param {object} [options] - Query and paging options.
+     * @param {string} [options.query] - Gmail search query (`q` parameter).
+     * @param {number} [options.maxResults] - Page size; defaults to `25`.
+     * @param {string} [options.pageToken] - The `nextPageToken` from the previous page.
+     * @param {string[]} [options.labelIds] - Label IDs the messages must carry.
+     * @returns {Promise<GmailListResult>} One page of message references with the next page token when more pages exist.
+     * @throws {InternalError} When no token is configured.
+     * @throws {NotFoundError} When the endpoint answers with HTTP 404.
+     * @throws {ConflictError} When Gmail answers with HTTP 409.
+     * @throws {BadRequestError} When Gmail answers with any other HTTP error status (e.g. invalid query).
+     * @example
+     * ```ts
+     * let pageToken: string | undefined;
+     * do {
+     *   const page = await gmail.listMessages({
+     *     query: "is:unread",
+     *     maxResults: 100,
+     *     pageToken,
+     *   });
+     *   console.log(page.messages);
+     *   pageToken = page.nextPageToken;
+     * } while (pageToken);
+     * ```
+     */
+    listMessages(options?: {
+        query?: string;
+        maxResults?: number;
+        pageToken?: string;
+        labelIds?: string[];
+    }): Promise<GmailListResult>;
+    /**
+     * @description Fetches a single Gmail message
+     * @summary `GET`s `users.messages.get` for the given message ID with the
+     * requested `format`. With `"full"` (the default) the payload includes the
+     * parsed body parts; `"metadata"` limits it to headers and labels,
+     * `"minimal"` to identifiers only, and `"raw"` returns the raw MIME string.
+     * @param {string} id - The Gmail message ID.
+     * @param {"full" | "metadata" | "minimal" | "raw"} [format] - The message format to request; defaults to `"full"`.
+     * @returns {Promise<Record<string, unknown>>} The raw Gmail message payload in the requested format.
+     * @throws {InternalError} When no token is configured or the message ID is empty.
+     * @throws {NotFoundError} When the message does not exist (HTTP 404).
+     * @throws {ConflictError} When Gmail answers with HTTP 409.
+     * @throws {BadRequestError} When Gmail answers with any other HTTP error status.
+     */
+    getMessage(id: string, format?: "full" | "metadata" | "minimal" | "raw"): Promise<Record<string, unknown>>;
+    /**
+     * @description Lists the mailbox's Gmail labels
+     * @summary `GET`s `users.labels.list` and returns the raw label payloads
+     * (including `id`, `name`, and `type`).
+     * @returns {Promise<Array<Record<string, unknown>>>} The raw Gmail label payloads.
+     * @throws {InternalError} When no token is configured.
+     * @throws {NotFoundError} When the endpoint answers with HTTP 404.
+     * @throws {ConflictError} When Gmail answers with HTTP 409.
+     * @throws {BadRequestError} When Gmail answers with any other HTTP error status.
+     */
+    listLabels(): Promise<Array<Record<string, unknown>>>;
+}