@llmnative/react 2.3.0 → 3.0.0

package/dist/types/src/components/widgets/grid-core/useGridDBRecords.d.ts

@@ -1,9 +1,13 @@
-import { type DatabaseOptions, type RecordProps } from "../../../providers/data/DataProvider";
+import { type DatabaseOptions, type DataProviderError, type RecordProps } from "../../../providers/data/DataProvider";
 type UseGridDBRecordsArgs = {
     path?: string;
     where?: DatabaseOptions["where"];
     order?: DatabaseOptions["order"];
     fieldMap?: DatabaseOptions["fieldMap"];
 };
-declare function useGridDBRecords<TRecord extends RecordProps>({ path, where, order, fieldMap, }: UseGridDBRecordsArgs): TRecord[];
+/** The records of a `Grid` with `path`, live, and why they did not arrive (CR-129). */
+declare function useGridDBRecords<TRecord extends RecordProps>({ path, where, order, fieldMap, }: UseGridDBRecordsArgs): {
+    records: TRecord[];
+    error: DataProviderError | null;
+};
 export default useGridDBRecords;

package/dist/types/src/index.d.ts

@@ -3,7 +3,7 @@ export { default as App, AppProvider } from './App';
 export { useMenu } from './App';
 export type { AppProps, AppProviderProps, AppProvidersConfig, MenuConfig } from './App';
 export type { AIConfig, FirebaseConfig } from './Config';
-export type { ServicesConfig, SupabaseProviderConfig, GoogleProviderConfig, MockProviderConfig, DataDriverName, StorageDriverName, AuthDriverName, EmailDriverName, AIDriverName, } from './providers/manifest';
+export type { ServicesConfig, SupabaseProviderConfig, GoogleProviderConfig, MockProviderConfig, DataDriverName, StorageDriverName, AuthDriverName, EmailSendDriverName, AIDriverName, } from './providers/manifest';
 export type { ProxyConfig, GitHubAuthConfig } from './Config';
 export { Head, HeadProvider, DEFAULT_DOCUMENT_HEAD, DEFAULT_HEAD_APP_NAME, DEFAULT_LANGUAGE_HEAD, useAssetsHead, useDocumentHead, useHead, useHeadLinks, useLanguageHead, usePaginationHead, usePwaHead, useSchemaOrgHead, useSocialHead, } from './Head';
 export type { HeadController, AssetsHeadState, DocumentBaseHead, DocumentHeadState, DocumentHttpEquivMeta, HeadFontAsset, HeadLinkDescriptor, HeadLinksState, HeadMetaAttributes, HeadProviderProps, HeadScriptAsset, HeadStyleAsset, LanguageAlternateLink, LanguageHeadState, OpenGraphHeadState, PageMetadataState, PaginationHeadState, PwaIconLink, PwaHeadState, SchemaOrgHeadState, SchemaOrgJson, SocialHeadState, TwitterHeadState, } from './Head';
@@ -15,7 +15,11 @@ export type { AppThemeProviderConfig, BuiltInThemeId, CardTheme, ColorScale, Gal
 export { AuthButton, useAccessToken, getAccessToken } from './auth';
 export * from './components/auth';
 export { useGlobalVars, getGlobalVars, setGlobalVars, removeGlobalVars } from './Global';
-export type { DataProviderAdapter, FieldValue, RecordProps, RecordArray, DatabaseOptions, DBConfig, ReadOptions, WhereClause, OrderClause, Condition } from './providers/data/DataProvider';
+export type { DataProviderAdapter, FieldValue, RecordProps, RecordArray, DatabaseOptions, DBConfig, ReadOptions, WhereClause, OrderClause, Condition, DataProviderErrorCode } from './providers/data/DataProvider';
+export { DataProviderError } from './providers/data/DataProvider';
+export { toDataProviderError } from './providers/data/query';
+export { useDataSubscription } from './providers/data/useDataSubscription';
+export type { DataSubscriptionOptions, DataSubscriptionState } from './providers/data/useDataSubscription';
 export type { OrderConfig, OrderDirection } from './libs/order';
 export { Order } from './libs/order';
 export { PromptUtils } from './libs/promptUtils';
@@ -67,9 +71,20 @@ export type { GitHubSessionProfile } from './providers/auth/github/GitHubAuthPro
 export type { CredentialsAdapter } from './providers/credentials/CredentialsProvider';
 export { useCredentialsProvider } from './providers/credentials/CredentialsProviderContext';
 export { GoogleServiceAccountProvider } from './providers/credentials/google/GoogleServiceAccountProvider';
-export type { EmailProviderAdapter, EmailSendParams } from './providers/email/EmailProvider';
-export type { EmailProviderId } from './providers/email/definitions';
-export { EMAIL_PROVIDER_DEFINITIONS } from './providers/email/definitions';
+export type { EmailSendAdapter, EmailSendParams, EmailSendResult, EmailAddress, EmailRecipient } from './providers/email/EmailSend';
+export type { EmailReadAdapter, EmailMessage, EmailReadStart, EmailReadBatch, EmailReadOptions } from './providers/email/EmailRead';
+export { EmailProviderError } from './providers/email/EmailError';
+export type { EmailProviderErrorCode } from './providers/email/EmailError';
+export type { EmailSendProviderId, EmailReadProviderId } from './providers/email/definitions';
+export { EMAIL_SEND_PROVIDER_DEFINITIONS, EMAIL_READ_PROVIDER_DEFINITIONS } from './providers/email/definitions';
+export { ResendEmailSender } from './providers/email/resend/ResendEmailSender';
+export type { ResendEmailSenderConfig } from './providers/email/resend/ResendEmailSender';
+export { BrevoEmailSender } from './providers/email/brevo/BrevoEmailSender';
+export type { BrevoEmailSenderConfig } from './providers/email/brevo/BrevoEmailSender';
+export { GmailEmailSender } from './providers/email/gmail/GmailEmailSender';
+export type { GmailEmailSenderConfig } from './providers/email/gmail/GmailEmailSender';
+export { GMAIL_SCOPES } from './providers/email/gmail/gmailApi';
+export type { GmailAuth } from './providers/email/gmail/gmailApi';
 export type { BuildManifest, BuildArtifacts, DeployOptions, DeployResult, Deployment, PublishProviderAdapter } from './providers/publish/PublishProvider';
 export type { PublishProviderId } from './providers/publish/definitions';
 export { PUBLISH_PROVIDER_DEFINITIONS } from './providers/publish/definitions';
@@ -82,15 +97,13 @@ export type { AppIconProviderConfig, IconController } from './providers/icon/Ico
 export { GoogleMapsProvider, useGoogleMapsConfig } from './providers/googleMaps/GoogleMapsProviderContext';
 export { loadGoogleMaps } from './providers/googleMaps/loadGoogleMaps';
 export type { GoogleMapsConfig } from './providers/googleMaps/loadGoogleMaps';
-export { useEmailProvider, EmailProvider } from './providers/email/EmailProviderContext';
-export { GmailEmailProvider } from './providers/email/google/GmailEmailProvider';
+export { useEmailSendProvider, useEmailReadProvider, EmailSendProvider, EmailReadProvider } from './providers/email/EmailProviderContext';
 export type { AIRequestOptions, AIReasoningLevel, AIAttachment, AIProviderAdapter, AIKeyValidationResult, AIModelDescriptor, AIModelPricing, DiscoveredAIModel, AIProviderCapabilities, AIModelCatalog, AIProviderDefinition, AICompleteRequest, AICompleteResult, AIConversationTurn, AIToolDefinition, AIToolCall, AIToolResult, CloudflareProviderOptions, ServerAIProviderConnection, ServerAIConnection, ModelIdentity, ModelIdentityEntry, ModelIdentityIndex, ResolvedModel, ModelOffer, ModelCost, } from './providers/ai';
 export { createAIProviderRegistry, getAIModelCatalog, formatAIModelRef, parseAIModelRef, isFreeAIModel, AI_PROVIDER_DEFINITIONS, AI_PROVIDER_DESCRIPTORS, OPENAI_COMPATIBLE_PROVIDER_DESCRIPTOR, CLOUDFLARE_PROVIDER_DESCRIPTOR, createCloudflareProviderDefinition, toProviderDescriptor, createServerCredentialAIRegistry, serverCredential, SERVER_CREDENTIAL_PREFIX, AI_PROVIDER_HOSTS, isAIProviderTarget, canonicalModelName, buildModelIdentityIndex, resolveModel, modelOffers, loadModelIdentityIndex } from './providers/ai';
 export type { ProviderDescriptor, ProviderCredentialField } from './providers/ProviderDescriptor';
 export { useAIProvider, useAIProviderRegistry, AIProvider } from './providers/ai/AIProviderContext';
 export { proxyFetch, useProxy, configureProxy, isProxyEnabled } from './providers/proxy';
 export { googleGetAccessToken } from './providers/auth/google/GoogleAuth';
-export { sendEmail } from './providers/email/google/email';
 export { getKeywordIdeas } from './providers/seo/google/keyword';
 export { getGoogleTrendsData, getGoogleTrendsRelated } from './providers/seo/google/trend';
 export { dropBox, useDropBoxConnect, DropBoxConnectButton } from './providers/storage/dropbox';

package/dist/types/src/libs/index.d.ts

@@ -2,7 +2,6 @@ export { default as path } from './path';
 export * from './editorHeight';
 export * from './converter';
 export * from './sanitizer';
-export * from './email';
 export * from './fetch';
 export * from './csv';
 export * from './utils';

package/dist/types/src/providers/ProviderRegistryContext.d.ts

@@ -2,18 +2,20 @@ import React from 'react';
 import type { DataProviderAdapter } from './data/DataProvider';
 import type { StorageProviderAdapter } from './storage/StorageProvider';
 import type { AuthProviderAdapter } from './auth/AuthProvider';
-import type { EmailProviderAdapter } from './email/EmailProvider';
+import type { EmailSendAdapter } from './email/EmailSend';
+import type { EmailReadAdapter } from './email/EmailRead';
 import type { AIProviderAdapter } from './ai/AIProvider';
 import type { CredentialsAdapter } from './credentials/CredentialsProvider';
 export type ProviderAdapterMap = {
     data: DataProviderAdapter;
     storage: StorageProviderAdapter;
     auth: AuthProviderAdapter;
-    email: EmailProviderAdapter;
+    emailSend: EmailSendAdapter;
+    emailRead: EmailReadAdapter;
     ai: AIProviderAdapter;
     credentials: CredentialsAdapter;
 };
-/** The 6 categories the framework ships out of the box. Any other string is a valid category too — see customCategories on <App>. */
+/** The 7 categories the framework ships out of the box. Any other string is a valid category too — see customCategories on <App>. */
 export type ProviderService = keyof ProviderAdapterMap;
 export type ProviderRegistrySnapshot = Record<string, {
     registry: Record<string, unknown>;
@@ -21,7 +23,7 @@ export type ProviderRegistrySnapshot = Record<string, {
 }>;
 /**
  * Replaces a single named adapter in a provider registry at runtime, in ANY
- * category — one of the 6 built-in ones (typed) or an arbitrary custom one a
+ * category — one of the 7 built-in ones (typed) or an arbitrary custom one a
  * vertical registered (string). Calls the previous adapter's dispose() (if
  * defined) only when the instance changes, then propagates the new registry to every
  * useXProvider()/useProvider() consumer. If `category` didn't exist yet, it's
@@ -43,7 +45,7 @@ export declare const ProviderRegistryProvider: ({ registries, setProvider, child
 export declare const useSetProvider: () => SetProviderFn;
 /**
  * Generic read access to any provider category — built-in or custom. Prefer the
- * typed useDataProvider()/useStorageProvider()/... for the 6 built-ins; reach for
+ * typed useDataProvider()/useStorageProvider()/... for the 7 built-ins; reach for
  * this when consuming a category the framework doesn't know about (registered via
  * providers.customCategories or a runtime setProvider() call).
  */

package/dist/types/src/providers/ai/server.d.ts

@@ -33,3 +33,23 @@ export type ServerCredentialResolution = {
  * placeholder can never carry a key elsewhere. A request without placeholders passes unchanged.
  */
 export declare function resolveServerCredentials(request: ServerCredentialRequest, lookup: ServerCredentialLookup): Promise<ServerCredentialResolution>;
+export { EmailProviderError } from '../email/EmailError';
+export type { EmailProviderErrorCode } from '../email/EmailError';
+export type { EmailSendAdapter, EmailSendParams, EmailSendResult, EmailAddress, EmailRecipient } from '../email/EmailSend';
+export type { EmailReadAdapter, EmailMessage, EmailReadStart, EmailReadBatch, EmailReadOptions } from '../email/EmailRead';
+export { EMAIL_SEND_PROVIDER_DEFINITIONS, EMAIL_READ_PROVIDER_DEFINITIONS } from '../email/definitions';
+export type { EmailSendProviderId, EmailReadProviderId } from '../email/definitions';
+export { ResendEmailSender } from '../email/resend/ResendEmailSender';
+export type { ResendEmailSenderConfig } from '../email/resend/ResendEmailSender';
+export { BrevoEmailSender } from '../email/brevo/BrevoEmailSender';
+export type { BrevoEmailSenderConfig } from '../email/brevo/BrevoEmailSender';
+export { GmailEmailSender } from '../email/gmail/GmailEmailSender';
+export type { GmailEmailSenderConfig } from '../email/gmail/GmailEmailSender';
+export { GmailEmailReader, decodeGmailPushNotification } from '../email/gmail/GmailEmailReader';
+export type { GmailEmailReaderConfig } from '../email/gmail/GmailEmailReader';
+export { createGmailOAuth } from '../email/gmail/gmailOAuth';
+export type { GmailOAuth, GmailOAuthConfig } from '../email/gmail/gmailOAuth';
+export { GMAIL_SCOPES } from '../email/gmail/gmailApi';
+export type { GmailAuth } from '../email/gmail/gmailApi';
+export { ImapEmailReader } from '../email/imap/ImapEmailReader';
+export type { ImapEmailReaderConfig, ImapModules } from '../email/imap/ImapEmailReader';

package/dist/types/src/providers/api/ApiProvider.d.ts

@@ -15,7 +15,7 @@ import type { ProviderConfigurable } from '../ProviderConfiguration';
  * Registered/fixed fields always win over a matching key the caller passes — same
  * authoritative-merge rule as the tenant-session handshake.
  *
- * Other category adapters (an EmailProviderAdapter for Brevo, an AIProviderAdapter for a
+ * Other category adapters (an EmailSendAdapter for an internal mail API, an AIProviderAdapter for a
  * REST-only model) call an ApiProviderAdapter internally instead of fetch()/proxyFetch()
  * directly — a vendor adapter is just a few lines of normal code, no framework-provided bridge.
  *

package/dist/types/src/providers/data/DataProvider.d.ts

@@ -28,6 +28,10 @@ export type Condition = {
     gte?: RangeValue;
     nin?: ListValue;
     in?: ListValue;
+    /** CR-129 — the field is a list that holds this value (Firestore `array-contains`, Supabase `contains`). */
+    contains?: ScalarValue;
+    /** CR-129 — the field is a list that holds at least one of these values (Firestore `array-contains-any`, Supabase `overlaps`). */
+    containsAny?: ListValue;
 };
 export type WhereClause = {
     [field: string]: Condition | OperatorValue;
@@ -35,9 +39,32 @@ export type WhereClause = {
 export type OrderClause = {
     [field: string]: "asc" | "desc";
 };
+/**
+ * CR-129 — why a read failed, the same on every provider: the rules refused it (`permission-denied`), there
+ * is no session (`unauthenticated`), the query cannot run as written, e.g. a missing index or an operator the
+ * database refuses (`invalid-query`), the database cannot be reached (`unavailable`), or anything else.
+ */
+export type DataProviderErrorCode = 'permission-denied' | 'unauthenticated' | 'invalid-query' | 'unavailable' | 'unknown';
+/** CR-129 — a failed read, normalized from the error of the database (kept in `cause`). */
+export declare class DataProviderError extends Error {
+    readonly code: DataProviderErrorCode;
+    readonly path?: string;
+    readonly cause?: unknown;
+    constructor(code: DataProviderErrorCode, message: string, options?: {
+        path?: string;
+        cause?: unknown;
+    });
+}
 export interface DatabaseOptions {
     where?: WhereClause;
     order?: OrderClause;
+    /** CR-129 — at most this many records, after `where` and `order`. */
+    limit?: number;
+    /**
+     * CR-129 — called when the database refuses or loses the subscription. Without it the provider logs the
+     * error as before; with it the page can say why the data did not arrive.
+     */
+    onError?: (error: DataProviderError) => void;
     fieldMap?: Record<string, string>;
     onLoad?: (data: RecordObject) => RecordObject;
 }
@@ -47,6 +74,8 @@ export interface DBConfig extends DatabaseOptions {
 export interface ReadOptions {
     where?: WhereClause;
     order?: OrderClause;
+    /** CR-129 — at most this many records, after `where` and `order`. */
+    limit?: number;
     toArray?: boolean;
     exception?: boolean;
 }

package/dist/types/src/providers/data/firebase.d.ts

@@ -10,13 +10,13 @@ export declare class FirebaseDataProvider implements DataProviderAdapter {
     getConfigurationState(): ProviderConfigurationState;
     isConfigured(): boolean;
     readShallow: (path: string, exception?: boolean) => Promise<string[]>;
-    read: (path: string, { where, order, toArray, exception }?: ReadOptions) => Promise<any>;
+    read: (path: string, { where, order, limit, toArray, exception }?: ReadOptions) => Promise<any>;
     update: (path: string, data: object, exception?: boolean) => Promise<void>;
     set: (path: string, data: object, exception?: boolean) => Promise<void>;
     setChunks: (path: string, data: object, { chunkSize, purge, onProgress }?: SetChunksOptions) => Promise<void>;
     remove: (path: string, exception?: boolean) => Promise<void>;
     count: (path: string) => Promise<number>;
-    subscribe: <T extends RecordProps = RecordProps>(path: string | undefined, setRecords: (records: T[]) => void, { where, order, fieldMap, onLoad }?: DatabaseOptions) => (() => void);
+    subscribe: <T extends RecordProps = RecordProps>(path: string | undefined, setRecords: (records: T[]) => void, options?: DatabaseOptions) => (() => void);
 }
 declare const _default: FirebaseDataProvider;
 export default _default;

package/dist/types/src/providers/data/firestore.d.ts

@@ -23,7 +23,7 @@ export declare class FirestoreDataProvider implements DataProviderAdapter {
     dispose: () => Promise<void>;
     getConfigurationState(): ProviderConfigurationState;
     isConfigured(): boolean;
-    read: (path: string, { where, order, toArray, exception }?: ReadOptions) => Promise<any>;
+    read: (path: string, { where, order, limit, toArray, exception }?: ReadOptions) => Promise<any>;
     set: (path: string, data: object, exception?: boolean) => Promise<void>;
     update: (path: string, data: object, exception?: boolean) => Promise<void>;
     remove: (path: string, exception?: boolean) => Promise<void>;
@@ -39,7 +39,7 @@ export declare class FirestoreDataProvider implements DataProviderAdapter {
      * Firestore inequality filters on a field require the first orderBy() to be
      * on that same field. Pass `order` accordingly to avoid SDK errors.
      */
-    subscribe: <T extends RecordProps = RecordProps>(path: string | undefined, setRecords: (records: T[]) => void, { where, order, fieldMap, onLoad }?: DatabaseOptions) => (() => void);
+    subscribe: <T extends RecordProps = RecordProps>(path: string | undefined, setRecords: (records: T[]) => void, options?: DatabaseOptions) => (() => void);
     /**
      * Returns the list of document IDs in a collection without loading document
      * data - the Firestore equivalent of RTDB's ?shallow=true REST endpoint.

package/dist/types/src/providers/data/query.d.ts

@@ -0,0 +1,14 @@
+import { DataProviderError, type Condition, type DatabaseOptions, type OperatorValue } from './DataProvider';
+/** A `where` value as a `Condition`: a list is `in`, a scalar is `eq`. */
+export declare function toCondition(raw: Condition | OperatorValue): Condition;
+/** Whether `value` (the field of a record) satisfies a condition of `where`. Unknown operators never match. */
+export declare function matchCondition(value: unknown, raw: Condition | OperatorValue): boolean;
+/** The first `limit` items (all of them without a valid limit). */
+export declare function applyLimit<T>(items: T[], limit?: number): T[];
+/** Any error of a database as a `DataProviderError` (an existing one is returned as it is). */
+export declare function toDataProviderError(error: unknown, path?: string): DataProviderError;
+/**
+ * Tells the page that a subscription failed: `options.onError` when it is given, else the console as the
+ * providers did before CR-129. Returns the normalized error.
+ */
+export declare function reportSubscribeError(options: Pick<DatabaseOptions, 'onError'> | undefined, error: unknown, path?: string): DataProviderError;

package/dist/types/src/providers/data/useDataSubscription.d.ts

@@ -0,0 +1,20 @@
+import type { DataProviderError, DatabaseOptions, RecordArray } from './DataProvider';
+export type DataSubscriptionOptions = Pick<DatabaseOptions, 'where' | 'order' | 'limit' | 'fieldMap'> & {
+    /** Read nothing (a page still waiting for an id): `loading` false, no records. */
+    skip?: boolean;
+    /** The name of a provider registered in `providers` (the default one without it). */
+    provider?: string;
+};
+export type DataSubscriptionState = {
+    records: RecordArray;
+    loading: boolean;
+    /** Why the data did not arrive (rules, session, query, network), the same on every provider. */
+    error: DataProviderError | null;
+};
+/**
+ * CR-129 — the records at `path`, live, from the data provider: `{ records, loading, error }`. `loading` is
+ * true until the first answer; a subscription the database refuses gives `error` instead of a list that never
+ * arrives. `where`, `order` and `limit` are compared by value, so a new object with the same content does not
+ * subscribe again.
+ */
+export declare function useDataSubscription(path: string | null | undefined, options?: DataSubscriptionOptions): DataSubscriptionState;

package/dist/types/src/providers/email/EmailError.d.ts

@@ -0,0 +1,27 @@
+export type EmailProviderErrorCode = 
+/** The adapter misses a setting (key, sender, client, library). */
+'not-configured'
+/** The message itself is not valid: no recipient, no body. */
+ | 'invalid-message'
+/** The provider refused the credentials (401/403, revoked token). */
+ | 'unauthorized'
+/** The provider refused the message (400/422: sender not verified, address not valid). */
+ | 'rejected' | 'rate-limited'
+/** The provider or the network did not answer. */
+ | 'unavailable' | 'unknown';
+export declare class EmailProviderError extends Error {
+    readonly code: EmailProviderErrorCode;
+    readonly provider: string;
+    readonly status?: number;
+    constructor(code: EmailProviderErrorCode, provider: string, message: string, options?: {
+        status?: number;
+        cause?: unknown;
+    });
+}
+/** The code of an HTTP status of a provider. */
+export declare const emailErrorCode: (status: number) => EmailProviderErrorCode;
+/**
+ * A JSON call to a provider: the answer, or an `EmailProviderError` with the status and the path only.
+ * A network failure is `unavailable`.
+ */
+export declare function callEmailApi<T>(provider: string, http: typeof fetch, url: string, init: RequestInit): Promise<T>;

package/dist/types/src/providers/email/EmailProviderContext.d.ts

@@ -1,12 +1,18 @@
 import React from 'react';
-import type { EmailProviderAdapter } from './EmailProvider';
-type EmailProviderContextValue = {
-    registry: Record<string, EmailProviderAdapter>;
+import type { EmailSendAdapter } from './EmailSend';
+import type { EmailReadAdapter } from './EmailRead';
+type Registry<T> = {
+    registry: Record<string, T>;
     defaultKey: string;
 };
-declare const EmailProviderContext: React.Context<EmailProviderContextValue | null>;
-export declare const EmailProvider: ({ registry, defaultKey, children, }: EmailProviderContextValue & {
+export declare const EmailSendProvider: ({ registry, defaultKey, children }: Registry<EmailSendAdapter> & {
     children: React.ReactNode;
 }) => React.JSX.Element;
-export declare const useEmailProvider: (name?: string) => EmailProviderAdapter | null;
-export default EmailProviderContext;
+export declare const EmailReadProvider: ({ registry, defaultKey, children }: Registry<EmailReadAdapter> & {
+    children: React.ReactNode;
+}) => React.JSX.Element;
+/** The adapter that sends (the default one, or `name`), or `null` when none is registered. */
+export declare const useEmailSendProvider: (name?: string) => EmailSendAdapter | null;
+/** The adapter that reads (the default one, or `name`), or `null` when none is registered. */
+export declare const useEmailReadProvider: (name?: string) => EmailReadAdapter | null;
+export {};

package/dist/types/src/providers/email/EmailRead.d.ts

@@ -0,0 +1,48 @@
+import type { ProviderConfigurable } from '../ProviderConfiguration';
+export interface EmailMessage {
+    /** The id of the message in its mailbox. */
+    id: string;
+    /** The conversation: Gmail's thread, the Message-ID of the first message elsewhere. */
+    threadId: string;
+    /** The headers as text (`Ada <ada@example.com>`). */
+    from: string;
+    to: string;
+    subject: string;
+    /** When it arrived, ISO 8601. */
+    date: string;
+    /** The plain text: the text part, else the HTML without tags. */
+    text: string;
+    /** `outbound` for a message the mailbox sent itself (Gmail's SENT). */
+    direction: 'inbound' | 'outbound';
+    /**
+     * Where to read on from once this message is handled: when the app stops at a message (its handler
+     * failed), it keeps the `cursor` of the last one handled and the next reading starts with the rest.
+     * With Gmail the next reading may give again the messages of the same history record handled before it.
+     */
+    cursor: string;
+}
+export interface EmailReadStart {
+    /** Where reading goes on from: opaque, the app keeps it as it is. */
+    cursor: string;
+    /** Gmail: when its push to Pub/Sub ends; call `start()` again before. */
+    expiresAt?: string;
+}
+export interface EmailReadBatch {
+    messages: EmailMessage[];
+    /** The cursor to read on from next time. */
+    cursor: string;
+}
+export interface EmailReadOptions {
+    /** At most this many messages (default 50): the returned cursor goes on from the last one. */
+    limit?: number;
+}
+export interface EmailReadAdapter extends ProviderConfigurable {
+    /** Reading starts now: the mails already in the mailbox stay out. */
+    start(): Promise<EmailReadStart>;
+    /**
+     * The new mails since `cursor`, oldest first, and the cursor after them. A cursor the mailbox no longer
+     * knows (Gmail's history expired, IMAP's UIDVALIDITY changed) starts again from now, reading nothing old.
+     */
+    read(cursor: string, options?: EmailReadOptions): Promise<EmailReadBatch>;
+}
+export declare const DEFAULT_EMAIL_READ_LIMIT = 50;

package/dist/types/src/providers/email/EmailSend.d.ts

@@ -0,0 +1,54 @@
+import type { ProviderConfigurable } from '../ProviderConfiguration';
+/** An address, with the name shown to who reads it. */
+export type EmailAddress = {
+    email: string;
+    name?: string;
+};
+/** An address as text (`ada@example.com`) or with its name. */
+export type EmailRecipient = string | EmailAddress;
+export interface EmailSendParams {
+    /** The sender; without it, the adapter's own `from`. */
+    from?: EmailRecipient;
+    to: EmailRecipient | EmailRecipient[];
+    cc?: EmailRecipient | EmailRecipient[];
+    bcc?: EmailRecipient | EmailRecipient[];
+    replyTo?: EmailRecipient;
+    subject: string;
+    /** The body as HTML, as text, or both (the reader's client picks). At least one. */
+    html?: string;
+    text?: string;
+    /** Gmail: the conversation the message joins. The other providers ignore it. */
+    threadId?: string;
+}
+export interface EmailSendResult {
+    /** The id the provider gave the message. */
+    id: string;
+    threadId?: string;
+}
+export interface EmailSendAdapter extends ProviderConfigurable {
+    send(params: EmailSendParams): Promise<EmailSendResult>;
+}
+/** An address as `{ email, name? }`. */
+export declare const toEmailAddress: (recipient: EmailRecipient) => EmailAddress;
+/** One or more addresses as a list, without the empty ones. */
+export declare const toEmailAddresses: (recipients: EmailRecipient | EmailRecipient[] | undefined) => EmailAddress[];
+/** An address as a header shows it: `Ada <ada@example.com>`, or the bare address. */
+export declare const formatEmailAddress: ({ email, name }: EmailAddress) => string;
+/**
+ * The message an adapter sends: sender and recipients as addresses, at least one recipient and one body.
+ * Throws `invalid-message` or (no sender, when the provider needs one) `not-configured`.
+ */
+export declare function prepareEmail(provider: string, params: EmailSendParams, defaultFrom: EmailRecipient | undefined, { fromRequired }?: {
+    fromRequired?: boolean | undefined;
+}): {
+    from: EmailAddress | undefined;
+    to: EmailAddress[];
+    cc: EmailAddress[];
+    bcc: EmailAddress[];
+    replyTo: EmailAddress | undefined;
+    subject: string;
+    html: string | undefined;
+    text: string | undefined;
+    threadId: string | undefined;
+};
+export type PreparedEmail = ReturnType<typeof prepareEmail>;

package/dist/types/src/providers/email/brevo/BrevoEmailSender.d.ts

@@ -0,0 +1,21 @@
+import { type ProviderConfigurationState } from '../../ProviderConfiguration';
+import { type EmailRecipient, type EmailSendAdapter, type EmailSendParams, type EmailSendResult } from '../EmailSend';
+export declare const BREVO_EMAIL_URL = "https://api.brevo.com/v3/smtp/email";
+export type BrevoEmailSenderConfig = {
+    apiKey: string;
+    /** The default sender, a sender or domain verified in Brevo. */
+    from?: EmailRecipient;
+    /** The `fetch` to use (a proxy, a test). */
+    fetch?: typeof fetch;
+};
+/**
+ * Sends with Brevo's transactional API (CR-130). The key is a secret: use it on a server, not in a
+ * browser bundle.
+ */
+export declare class BrevoEmailSender implements EmailSendAdapter {
+    private readonly config;
+    constructor(config: BrevoEmailSenderConfig);
+    getConfigurationState(): ProviderConfigurationState;
+    isConfigured(): boolean;
+    send(params: EmailSendParams): Promise<EmailSendResult>;
+}

package/dist/types/src/providers/email/definitions.d.ts

@@ -1,3 +1,5 @@
 import type { ProviderDescriptor } from '../ProviderDescriptor';
-export type EmailProviderId = 'resend' | 'sendgrid' | 'mailgun' | 'postmark' | 'ses' | 'smtp';
-export declare const EMAIL_PROVIDER_DEFINITIONS: ProviderDescriptor[];
+export type EmailSendProviderId = 'resend' | 'brevo' | 'gmail' | 'sendgrid' | 'mailgun' | 'postmark' | 'ses' | 'smtp';
+export type EmailReadProviderId = 'gmail' | 'imap';
+export declare const EMAIL_SEND_PROVIDER_DEFINITIONS: ProviderDescriptor[];
+export declare const EMAIL_READ_PROVIDER_DEFINITIONS: ProviderDescriptor[];

package/dist/types/src/providers/email/gmail/GmailEmailReader.d.ts

@@ -0,0 +1,37 @@
+import type { ProviderConfigurationState } from '../../ProviderConfiguration';
+import { type EmailReadAdapter, type EmailReadBatch, type EmailReadOptions, type EmailReadStart } from '../EmailRead';
+import { type GmailAuth } from './gmailApi';
+export type GmailEmailReaderConfig = {
+    auth: GmailAuth;
+    /**
+     * The Pub/Sub topic Gmail notifies (`projects/<project>/topics/<name>`, with `roles/pubsub.publisher` to
+     * `gmail-api-push@system.gserviceaccount.com`). Without it `start()` registers no push: the app reads by polling.
+     */
+    topic?: string;
+    /** The label read (default `INBOX`). */
+    labelId?: string;
+    fetch?: typeof fetch;
+};
+/**
+ * Reads a Gmail mailbox (CR-130) by its history: the cursor is a `historyId`. With a `topic`, `start()` also
+ * asks Gmail to notify the topic of every change (the push lasts 7 days: call `start()` again before
+ * `expiresAt`); a notification (`decodeGmailPushNotification`) tells the app when to `read()`.
+ * Scope `GMAIL_SCOPES.read`.
+ */
+export declare class GmailEmailReader implements EmailReadAdapter {
+    private readonly config;
+    constructor(config: GmailEmailReaderConfig);
+    getConfigurationState(): ProviderConfigurationState;
+    isConfigured(): boolean;
+    private session;
+    start(): Promise<EmailReadStart>;
+    read(cursor: string, { limit }?: EmailReadOptions): Promise<EmailReadBatch>;
+}
+/**
+ * The notification Gmail publishes on the topic: the `data` of the Pub/Sub message (base64 JSON) as
+ * `{ emailAddress, historyId }`, or `null` when it is not one.
+ */
+export declare function decodeGmailPushNotification(data: string | undefined | null): {
+    emailAddress: string;
+    historyId: string;
+} | null;

package/dist/types/src/providers/email/gmail/GmailEmailSender.d.ts

@@ -0,0 +1,21 @@
+import type { ProviderConfigurationState } from '../../ProviderConfiguration';
+import { type EmailRecipient, type EmailSendAdapter, type EmailSendParams, type EmailSendResult } from '../EmailSend';
+import { type GmailAuth } from './gmailApi';
+export type GmailEmailSenderConfig = {
+    auth: GmailAuth;
+    /** The sender shown; without it Gmail uses the address of the account (an alias must be set in Gmail). */
+    from?: EmailRecipient;
+    fetch?: typeof fetch;
+};
+/**
+ * Sends from a Gmail mailbox (CR-130): with the browser's Google sign-in (`auth.accessToken`), or on a server
+ * with the app's OAuth client and the mailbox's refresh token (scope `GMAIL_SCOPES.send`). `threadId` keeps a
+ * reply in its conversation.
+ */
+export declare class GmailEmailSender implements EmailSendAdapter {
+    protected readonly config: GmailEmailSenderConfig;
+    constructor(config: GmailEmailSenderConfig);
+    getConfigurationState(): ProviderConfigurationState;
+    isConfigured(): boolean;
+    send(params: EmailSendParams): Promise<EmailSendResult>;
+}

package/dist/types/src/providers/email/gmail/browser.d.ts

@@ -0,0 +1,10 @@
+import { type ProviderConfigurationState } from '../../ProviderConfiguration';
+import { GmailEmailSender } from './GmailEmailSender';
+/**
+ * The `gmail` driver of the `google` provider (CR-130): sends as the user signed in with Google in the
+ * browser, so it is configured when `google.oAuth2.clientId` is.
+ */
+export declare class BrowserGmailEmailSender extends GmailEmailSender {
+    constructor();
+    getConfigurationState(): ProviderConfigurationState;
+}

package/dist/types/src/providers/email/gmail/gmailApi.d.ts

@@ -0,0 +1,53 @@
+import { type ProviderConfigurationState } from '../../ProviderConfiguration';
+import { type PreparedEmail } from '../EmailSend';
+import type { EmailMessage } from '../EmailRead';
+export declare const GMAIL_API = "https://gmail.googleapis.com/gmail/v1/users/me";
+export declare const GOOGLE_TOKEN_URL = "https://oauth2.googleapis.com/token";
+/** The scopes of Gmail: read the mailbox, send from it. */
+export declare const GMAIL_SCOPES: {
+    readonly read: "https://www.googleapis.com/auth/gmail.readonly";
+    readonly send: "https://www.googleapis.com/auth/gmail.send";
+};
+/**
+ * How a Gmail adapter gets its access token: a function (the browser's Google sign-in), or the OAuth client
+ * of the app and the refresh token of the mailbox (a server).
+ */
+export type GmailAuth = {
+    accessToken: () => Promise<string>;
+} | {
+    clientId: string;
+    clientSecret: string;
+    refreshToken: string;
+};
+export declare const PROVIDER = "Gmail";
+/** Whether the auth has what it needs. */
+export declare function gmailConfigurationState(name: string, auth: GmailAuth | undefined): ProviderConfigurationState;
+/** A fresh access token: from the function, or exchanging the refresh token. */
+export declare function gmailAccessToken(auth: GmailAuth, http: typeof fetch): Promise<string>;
+export declare const base64Url: (text: string) => string;
+export declare const fromBase64Url: (data: string) => string;
+/** The raw message (RFC 2822) in base64url, as `messages.send` takes it. */
+export declare function gmailRawMessage(mail: PreparedEmail): string;
+type GmailPart = {
+    mimeType?: string;
+    body?: {
+        data?: string;
+    };
+    parts?: GmailPart[];
+};
+export type GmailApiMessage = {
+    id: string;
+    threadId?: string;
+    labelIds?: string[];
+    snippet?: string;
+    internalDate?: string;
+    payload?: GmailPart & {
+        headers?: {
+            name: string;
+            value: string;
+        }[];
+    };
+};
+/** A message of the API (`format=full`) as an `EmailMessage`, with the cursor after it. */
+export declare function toEmailMessage(message: GmailApiMessage, cursor: string): EmailMessage;
+export {};