@framers/agentos-ext-gmail-source 0.3.0 → 0.5.0

package/dist/gmail.d.ts

@@ -0,0 +1,203 @@
+import { type SourceQuota, type SourceRevocations, type SourceSyncHandle, type SourceSyncScanPage, type SourceSyncHistoryPage, type SourceSyncReadResult, type SourceCachePermission, type SourceCacheDecision } from '@framers/agentos-ext-account-sources';
+import type { GmailOAuthClient, GmailOAuthEndpoints } from './types.js';
+import { type GmailMappingBounds } from './mime.js';
+/**
+ * The client's defensive transport limits, each a positive safe integer no greater than the value in brackets. They
+ * are library choices, not Google maxima: a control page past one fails without a partial page.
+ */
+export interface GmailApiLimits {
+    /** Milliseconds one call and the reading of its body may take (15,000). */
+    readonly timeoutMs: number;
+    /** Labels one labels response may hold (1,000). */
+    readonly maxLabels: number;
+    /** Message references one history page may hold across its five event fields (10,000). */
+    readonly maxHistoryReferences: number;
+    /** Characters of one page token, given or returned (4,096). */
+    readonly maxPageTokenCharacters: number;
+}
+/**
+ * What a `GmailApi` is built from. Every value comes from trusted server configuration and the host's released
+ * account-source services; none comes from a browser request.
+ *
+ * @typeParam Prepared - The host's prepared-document type of its `SourceRevocations`.
+ */
+export interface GmailApiOptions<Prepared = unknown> {
+    /** The dedicated OAuth client the grant was issued to. */
+    readonly client: GmailOAuthClient;
+    /** The host's revocation service; its `withGrant` serializes every refresh under the durable grant lease. */
+    readonly revocations: Pick<SourceRevocations<Prepared>, 'withGrant'>;
+    /** Answers the sync handle current for this connection at each call, so a superseded handle is refused. */
+    readonly currentHandle: () => SourceSyncHandle;
+    /** The shared quota: each token refresh and each HTTP dispatch is one `run`, and provider waits go to `defer`. */
+    readonly quota: Pick<SourceQuota, 'run' | 'defer'>;
+    /** The opaque quota key of the project, 1 to 512 letters, digits, `:`, `_` or `-`. */
+    readonly projectKey: string;
+    /** Stable host HMAC key, never an address or a rotating connection id. */
+    readonly mailboxKey: string;
+    /** The thread mapper's bounds; `maxResponseBytes` also caps every API response before decoding. */
+    readonly bounds: GmailMappingBounds;
+    /** The transport and control-page limits. */
+    readonly limits: GmailApiLimits;
+    /** The fetch every token and API call goes through; the global fetch by default. */
+    readonly fetchImpl?: typeof fetch;
+    /**
+     * Epoch milliseconds; `Date.now` unless given. Give it the clock the host's sync store reads: a retry time this
+     * client hands back is always at least one millisecond after it, whichever clock produced the time.
+     */
+    readonly clock?: () => number;
+    /** CI-only transport endpoints. No request-supplied origin or client value. */
+    readonly apiOrigin?: string;
+    /** CI-only OAuth stand-in endpoints, checked as `GmailOAuthFlow` checks them. */
+    readonly oauthEndpoints?: GmailOAuthEndpoints;
+    /**
+     * Reuse of one access token for one sync lease, shared by every client given the same holder. A held token is used
+     * only while `currentHandle` answers the lease it was obtained under (the same connection, generation and lease
+     * token) and that lease has not expired by `clock`; a 401 drops it, and the repeat refreshes as before. Without a
+     * holder every operation refreshes the grant.
+     */
+    readonly tokenHolder?: GmailTokenHolder;
+}
+/**
+ * A memory-only slot for one access token and the sync lease it was obtained under, given to the clients built for
+ * one lease so that a cycle refreshes the grant once. Create it as `{ current: null }` for each lease and drop it when
+ * the lease ends; never persist, log or serialize it.
+ */
+export interface GmailTokenHolder {
+    /** The held token and the key of its lease, written and cleared by the clients; null when none is held. */
+    current: {
+        readonly lease: string;
+        readonly value: string;
+    } | null;
+}
+/** Server-memory identity result. Never serialize it into a source or telemetry. */
+export interface GmailProfile {
+    /** The mailbox address, for the host's private comparison only. */
+    readonly emailAddress: string;
+    /** The mailbox's current history id as a decimal string. */
+    readonly historyId: string;
+}
+/** Sanitized label names and the labels response's own cache decision; a refused decision holds no names. */
+export interface GmailLabels {
+    /** Sanitized names by label id. */
+    readonly names: Readonly<Record<string, string>>;
+    /** The decision for the labels response, independent of any thread response. */
+    readonly cache: SourceCacheDecision;
+}
+/** The per-read values of one `readThread` call, passed to the thread mapper with the response's times and headers. */
+export interface GmailReadOptions {
+    /** The selection cutoff in epoch milliseconds. */
+    readonly cutoff: number;
+    /** The message window in milliseconds. */
+    readonly windowMs: number;
+    /** The host's authenticated relative source-detail path; never a Gmail link. */
+    readonly sourceDetailUrl: string;
+    /** The host's evidenced cache permission; null refuses durable content. */
+    readonly permission: SourceCachePermission | null;
+    /** The cycle's label snapshot from `labels`, or null to keep label ids without names. */
+    readonly labels: GmailLabels | null;
+    /** Cancels the read. */
+    readonly signal?: AbortSignal;
+}
+/**
+ * A client's fixed refusal; its message is `gmail_api_<reason>`. `configuration` is thrown by the constructor;
+ * `response_too_large` stays inside the client, which answers it as a skipped thread or an invalid control page.
+ */
+export declare class GmailApiFault extends Error {
+    readonly reason: 'configuration' | 'response_too_large';
+    /** @param reason Why the client refused. */
+    constructor(reason: 'configuration' | 'response_too_large');
+}
+/**
+ * The capped, read-only Gmail API client. Each provider operation makes one attempt: one OAuth refresh inside the
+ * host's grant operation, or the access token a `tokenHolder` holds for the current lease, then one HTTP dispatch, each
+ * admitted by the shared quota with a new attempt id; a 401 drops a held token and earns one fresh token and one
+ * repeat of the same call. Provider waits are recorded through the quota's `defer` and thrown as `rate_limited` or
+ * `provider_unavailable` with their time; the durable coordinator owns retry episodes, backoff and exhaustion. Every
+ * failure is a fixed `SourceSyncFault`.
+ *
+ * @typeParam Prepared - The host's prepared-document type of its `SourceRevocations`.
+ */
+export declare class GmailApi<Prepared = unknown> {
+    private readonly options;
+    private readonly origin;
+    private readonly send;
+    private readonly bounds;
+    private readonly limits;
+    private readonly mapper;
+    /**
+     * @param options The client, the host's grant and quota services, the quota keys, the bounds and limits, and the
+     * optional fetch, clock and CI-only endpoints.
+     * @throws {GmailApiFault} `configuration` for an origin override outside CI or not a loopback or `.invalid` origin,
+     * a limit outside its ceiling, or a malformed quota key.
+     * @throws {GmailMappingFault} `configuration` for invalid bounds.
+     */
+    constructor(options: GmailApiOptions<Prepared>);
+    private now;
+    private later;
+    private pageToken;
+    private pageSize;
+    private quotaValue;
+    private reserve;
+    private defer;
+    private accessToken;
+    private dropToken;
+    /** Consume/cancel the whole body within the quota callback, before releasing its slot. */
+    private wire;
+    private request;
+    private control;
+    /**
+     * The mailbox address and current history id, for the host's private account binding and its history anchor. The
+     * answer's other fields are dropped.
+     *
+     * @param signal Cancels the call.
+     * @throws {SourceSyncFault} A fixed failure, `invalid_response` for a malformed answer.
+     */
+    profile(signal?: AbortSignal): Promise<GmailProfile>;
+    /**
+     * The mailbox's labels: sanitized names by id under the labels response's own cache decision. A refused decision
+     * keeps no names.
+     *
+     * @param permission The host's evidenced cache permission; null refuses the names.
+     * @param signal Cancels the call.
+     * @throws {SourceSyncFault} A fixed failure, `invalid_response` for a malformed or oversized list.
+     */
+    labels(permission: SourceCachePermission | null, signal?: AbortSignal): Promise<GmailLabels>;
+    /**
+     * One page of candidate thread ids between `cutoff - windowMs` and `cutoff`, outside spam, trash and drafts. The
+     * query's whole-second bounds are widened by a second each way; the mapper enforces the exact window. Snippets and
+     * estimates are dropped, and no mailbox-wide completeness is claimed.
+     *
+     * @param cutoff The selection cutoff in epoch milliseconds.
+     * @param windowMs The window, from 1 millisecond to 90 days.
+     * @param pageSize Candidates per page, from 1 to 100.
+     * @param pageToken The resume token from the previous page, or null for the first.
+     * @param signal Cancels the call.
+     * @throws {SourceSyncFault} A fixed failure, `invalid_response` for bad arguments, a malformed page or a repeated
+     * page token.
+     */
+    list(cutoff: number, windowMs: number, pageSize: number, pageToken: string | null, signal?: AbortSignal): Promise<SourceSyncScanPage>;
+    /**
+     * One page of history after `fromCursor`: the thread ids of every message addition, deletion and label change, and
+     * of generic message entries, deduplicated and sorted, with the page's decimal-string cursor. The host persists the
+     * pending work and commits a terminal cursor only once every item is terminal.
+     *
+     * @param fromCursor The committed history id, a decimal string.
+     * @param pageSize Records per page, from 1 to 100.
+     * @param pageToken The resume token from the previous page, or null for the first.
+     * @param signal Cancels the call.
+     * @throws {SourceSyncFault} `history_expired` when Google no longer holds the anchor; `invalid_response` for bad
+     * arguments, a malformed or out-of-order page, too many references or a repeated page token; another fixed failure.
+     */
+    history(fromCursor: string, pageSize: number, pageToken: string | null, signal?: AbortSignal): Promise<SourceSyncHistoryPage>;
+    /**
+     * Reads one thread in the `full` format and maps it with its own read times and cache headers and the separate
+     * label snapshot. A 404 is `gone`; an oversized successful answer is skipped as `response_too_large`; any other
+     * result is the mapper's. The raw response never leaves the client.
+     *
+     * @param sourceId The thread id, 1 to 64 hexadecimal characters.
+     * @param options The cutoff, window, detail path, cache permission, label snapshot and signal.
+     * @throws {SourceSyncFault} A fixed failure, `invalid_response` for a malformed id.
+     */
+    readThread(sourceId: string, options: GmailReadOptions): Promise<SourceSyncReadResult>;
+}
+//# sourceMappingURL=gmail.d.ts.map

package/dist/gmail.d.ts.map

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