@oomol-lab/open-connector 1.6.5 → 1.8.0

package/src/providers/googlecalendar/trigger-on-event-changed.js

@@ -0,0 +1,233 @@
+import { eventsPollOutputs, maximumPollEventsPerPage, PermanentPollError, PollConnectionError, TransientPollError, } from "../../triggers/common/poll.js";
+import { snapshot } from "./trigger-on-event-changed.definition.js";
+const quotaReasons = new Set(["rateLimitExceeded", "userRateLimitExceeded", "quotaExceeded", "usageLimits"]);
+export const googleCalendarEventChanged = {
+    buildOutputs: eventsPollOutputs,
+    snapshot,
+    async poll(context) {
+        const config = resolveConfig(context.config);
+        if (context.checkpoint === null)
+            return seed(context, config, context.now.toISOString());
+        const checkpoint = readCheckpoint(context.checkpoint);
+        if (checkpoint.calendarId !== config.calendarId)
+            return seed(context, config, context.now.toISOString());
+        if ("seedTimeMin" in checkpoint)
+            return seed(context, config, checkpoint.seedTimeMin, checkpoint.pageToken);
+        return incremental(context, config, checkpoint);
+    },
+};
+function resolveConfig(value) {
+    return {
+        calendarId: value.calendarId,
+        changes: new Set(value.changes),
+        matchTerm: value.matchTerm.trim(),
+        maxEventsPerPoll: value.maxEventsPerPoll,
+    };
+}
+function readCheckpoint(value) {
+    const checkpoint = record(value);
+    const pageToken = typeof checkpoint?.pageToken == "string" ? checkpoint.pageToken : undefined;
+    const calendarId = typeof checkpoint?.calendarId == "string" ? checkpoint.calendarId : undefined;
+    if (typeof checkpoint?.syncToken == "string" && checkpoint.syncToken.length > 0) {
+        return {
+            calendarId,
+            ...(pageToken == null ? {} : { pageToken }),
+            syncToken: checkpoint.syncToken,
+        };
+    }
+    if (typeof checkpoint?.seedTimeMin == "string" && checkpoint.seedTimeMin.length > 0) {
+        return {
+            calendarId,
+            ...(pageToken == null ? {} : { pageToken }),
+            seedTimeMin: checkpoint.seedTimeMin,
+        };
+    }
+    throw new PermanentPollError("Google Calendar checkpoint is invalid; recreate the Trigger.");
+}
+async function seed(context, config, timeMin, startPageToken) {
+    let pageToken = startPageToken;
+    for (let page = 0; page < 2; page += 1) {
+        const result = await list(context, config.calendarId, {
+            maxResults: 2_500,
+            pageToken,
+            showDeleted: "true",
+            singleEvents: "false",
+            timeMin,
+        });
+        if (pageToken != null && stalePage(result))
+            return { checkpoint: { calendarId: config.calendarId, seedTimeMin: timeMin }, events: [] };
+        success(context, result, "seed full sync");
+        const parsed = (record(result.data) ?? {});
+        if (parsed.nextSyncToken)
+            return {
+                checkpoint: { calendarId: config.calendarId, syncToken: parsed.nextSyncToken },
+                events: [],
+            };
+        if (!parsed.nextPageToken)
+            throw new TransientPollError("Google Calendar seed response has no continuation token.");
+        pageToken = parsed.nextPageToken;
+    }
+    return {
+        checkpoint: {
+            calendarId: config.calendarId,
+            ...(pageToken == null ? {} : { pageToken }),
+            seedTimeMin: timeMin,
+        },
+        events: [],
+        hasMore: true,
+    };
+}
+async function incremental(context, config, checkpoint) {
+    const events = [];
+    let filtered = 0;
+    const result = await list(context, config.calendarId, {
+        maxResults: Math.min(config.maxEventsPerPoll, maximumPollEventsPerPage),
+        pageToken: checkpoint.pageToken,
+        showDeleted: "true",
+        singleEvents: "false",
+        syncToken: checkpoint.syncToken,
+    });
+    if (checkpoint.pageToken != null && stalePage(result)) {
+        return {
+            checkpoint: { calendarId: config.calendarId, syncToken: checkpoint.syncToken },
+            events,
+            filtered,
+        };
+    }
+    success(context, result, "incremental sync");
+    const parsed = (record(result.data) ?? {});
+    for (const item of parsed.items ?? []) {
+        if (item.id == null || item.id.length == 0)
+            continue;
+        const change = classify(item);
+        if (!config.changes.has(change) || !matches(item, config.matchTerm)) {
+            filtered += 1;
+            continue;
+        }
+        events.push(event(item, item.id, change, config.calendarId));
+    }
+    if (parsed.nextSyncToken) {
+        return {
+            checkpoint: { calendarId: config.calendarId, syncToken: parsed.nextSyncToken },
+            events,
+            filtered,
+        };
+    }
+    if (!parsed.nextPageToken)
+        throw new TransientPollError("Google Calendar sync response has no continuation token.");
+    return {
+        checkpoint: {
+            calendarId: config.calendarId,
+            pageToken: parsed.nextPageToken,
+            syncToken: checkpoint.syncToken,
+        },
+        events,
+        filtered,
+        hasMore: true,
+    };
+}
+function classify(value) {
+    if (value.status == "cancelled")
+        return "cancelled";
+    const created = epochSecond(value.created);
+    const updated = epochSecond(value.updated);
+    return created != null && created == updated ? "created" : "updated";
+}
+function matches(value, term) {
+    if (term.length == 0)
+        return true;
+    const needle = term.toLowerCase();
+    return [value.summary, value.description, value.location, ...(value.attendees ?? []).map(({ email }) => email)].some((candidate) => typeof candidate == "string" && candidate.toLowerCase().includes(needle));
+}
+function event(item, eventId, change, calendarId) {
+    return {
+        dedupeKey: `${eventId}:${item.updated ?? item.etag ?? ""}`,
+        payload: {
+            attendeeEmails: (item.attendees ?? []).flatMap(({ email }) => email == null || email.length == 0 ? [] : [email]),
+            calendarId,
+            changeType: change,
+            created: iso(item.created),
+            creatorEmail: item.creator?.email ?? null,
+            description: item.description ?? null,
+            end: item.end ?? null,
+            eventId,
+            eventType: item.eventType ?? null,
+            htmlLink: item.htmlLink ?? null,
+            isAllDay: item.start?.date != null,
+            location: item.location ?? null,
+            organizerEmail: item.organizer?.email ?? null,
+            recurringEventId: item.recurringEventId ?? null,
+            start: item.start ?? null,
+            status: item.status ?? "",
+            summary: item.summary ?? null,
+            updated: iso(item.updated),
+        },
+    };
+}
+async function list(context, calendarId, query) {
+    const endpoint = `/calendars/${encodeURIComponent(calendarId)}/events`;
+    try {
+        return await context.connector.execute({
+            endpoint,
+            method: "GET",
+            query: Object.fromEntries(Object.entries(query).filter((entry) => entry[1] != null)),
+        }, context.signal);
+    }
+    catch (cause) {
+        throw new TransientPollError(`Google Calendar proxy request to ${endpoint} failed.`, { cause });
+    }
+}
+function success(context, result, operation) {
+    if (result.status >= 200 && result.status < 300)
+        return;
+    if (result.status == 410 || (result.status == 400 && fullSyncRequired(result.data))) {
+        throw new PermanentPollError("Google Calendar sync token expired; recreate the Trigger.");
+    }
+    if (result.status == 400 || (result.status == 404 && context.checkpoint === null)) {
+        throw new PermanentPollError(`Google Calendar ${operation} rejected the configuration.`);
+    }
+    if (result.status == 401)
+        throw new PollConnectionError(`Google Calendar ${operation} rejected the Connection.`);
+    if (result.status == 403) {
+        if (reasons(result.data).some((reason) => quotaReasons.has(reason))) {
+            throw new TransientPollError(`Google Calendar ${operation} was rate limited.`);
+        }
+        throw new PollConnectionError(`Google Calendar ${operation} rejected the Connection.`);
+    }
+    throw new TransientPollError(`Google Calendar ${operation} failed with status ${result.status}.`);
+}
+function stalePage(result) {
+    return result.status == 400 && !fullSyncRequired(result.data);
+}
+function reasons(data) {
+    const errors = record(record(data)?.error)?.errors;
+    if (!Array.isArray(errors))
+        return [];
+    return errors.flatMap((value) => {
+        const reason = record(value)?.reason;
+        return typeof reason == "string" ? [reason] : [];
+    });
+}
+function fullSyncRequired(data) {
+    if (reasons(data).includes("fullSyncRequired"))
+        return true;
+    const message = record(record(data)?.error)?.message;
+    return typeof message == "string" && message.includes("fullSyncRequired");
+}
+function iso(value) {
+    if (value == null || value.length == 0)
+        return null;
+    const milliseconds = Date.parse(value);
+    return Number.isNaN(milliseconds) ? null : new Date(milliseconds).toISOString();
+}
+function epochSecond(value) {
+    if (value == null || value.length == 0)
+        return null;
+    const milliseconds = Date.parse(value);
+    return Number.isNaN(milliseconds) ? null : Math.floor(milliseconds / 1_000);
+}
+function record(value) {
+    return value != null && typeof value == "object" && !Array.isArray(value)
+        ? value
+        : undefined;
+}

package/src/providers/googlechat/executors.d.ts

@@ -1,8 +1,6 @@
 import type { CredentialValidators, ProviderExecutors, ProviderProxyExecutor } from "../../core/types.ts";
 import type { ProviderActionHandlers } from "../provider-runtime.ts";
-import type { OAuthProviderContext } from "../provider-runtime.ts";
-export declare const googleChatApiBaseUrl = "https://chat.googleapis.com/v1";
-type GoogleChatRuntimeContext = OAuthProviderContext;
+import type { GoogleChatRuntimeContext } from "./runtime.ts";
 type GoogleChatActionHandler = (input: Record<string, unknown>, context: GoogleChatRuntimeContext) => Promise<unknown>;
 export declare const googleChatActionHandlers: ProviderActionHandlers<"googlechat", GoogleChatActionHandler>;
 export declare const executors: ProviderExecutors;

package/src/providers/googlechat/executors.js

@@ -1,27 +1,50 @@
 import { compactObject, optionalBoolean, optionalInteger, optionalRawString, optionalRecord, optionalString, } from "../../core/cast.js";
-import { defineGoogleProviderExecutors, googleBearerProxyAuth, googleServiceAccountValidator } from "../google-auth.js";
-import { googleJsonRequest } from "../google-runtime.js";
+import { defineGoogleProviderExecutors, googleBearerProxyAuth, googleServiceAccountValidator, } from "../googledrive/runtime-auth.js";
+import { googleJsonRequest } from "../googledrive/runtime-request.js";
 import { asObject } from "../googledrive/runtime-shared.js";
-import { defineProviderProxy, ProviderRequestError } from "../provider-runtime.js";
-import { googleChatOAuthScopes } from "./scopes.js";
-export const googleChatApiBaseUrl = "https://chat.googleapis.com/v1";
+import { defineProviderProxy, ProviderRequestError, providerResponseError, requiredResponseRecord, } from "../provider-runtime.js";
+import { attachSenderProfiles, listSpaceMembersPage, maxProfilesPerLookup, resolveDirectMessagePeer, } from "./members.js";
+import { encodeResourceName, googleChatApiBaseUrl, googleChatJsonRequest, stripPrefix } from "./runtime.js";
+import { googleChatServiceAccountScopes } from "./scopes.js";
 const service = "googlechat";
+const defaultMemberPageSize = 100;
 const googleUserInfoUrl = "https://www.googleapis.com/oauth2/v3/userinfo";
 const spaceNamePattern = /^spaces\/[^/]+$/;
 const messageNamePattern = /^spaces\/[^/]+\/messages\/[^/]+$/;
+const threadNamePattern = /^spaces\/[^/]+\/threads\/[^/]+$/;
+// findDirectMessage takes the user name as a query parameter, not a path segment,
+// so it is deliberately NOT percent-encoded here: googleRequest already encodes it
+// once through URLSearchParams.set(), and encoding it again would turn a@b.com into
+// a%2540b.com, which Google reads as a literal rather than an email address.
+//
+// Both patterns are allowlists of the expected structure, not denylists, so
+// zero-width and control characters, slashes, backslashes, and inner whitespace
+// all fall outside them without being rejected one by one. Domains accept only
+// ASCII or punycode.
+const userIdPattern = /^[0-9]{1,64}$/;
+// RFC 5322 allows "/" in the local part, but it is deliberately excluded here:
+// otherwise "users/person@example.com" would pass as one valid address and be sent
+// to Google as "users/users/person@example.com". A test pins this down.
+const emailLocalPart = "[A-Za-z0-9!#$%&'*+=?^_`{|}~-]+(?:\\.[A-Za-z0-9!#$%&'*+=?^_`{|}~-]+)*";
+const emailDomainLabel = "[A-Za-z0-9](?:[A-Za-z0-9-]*[A-Za-z0-9])?";
+const userEmailPattern = new RegExp(`^${emailLocalPart}@${emailDomainLabel}(?:\\.${emailDomainLabel})+$`);
 export const googleChatActionHandlers = {
     list_spaces: listSpaces,
     get_space: getSpace,
     list_messages: listMessages,
     get_message: getMessage,
+    create_message: createMessage,
+    find_direct_message: findDirectMessage,
+    get_direct_message_peer: getDirectMessagePeer,
+    list_space_members: listSpaceMembers,
 };
 export const executors = defineGoogleProviderExecutors(service, googleChatActionHandlers, {
-    scopes: googleChatOAuthScopes,
+    scopes: googleChatServiceAccountScopes,
 });
 export const proxy = defineProviderProxy({
     service,
     baseUrl: googleChatApiBaseUrl,
-    auth: googleBearerProxyAuth(googleChatOAuthScopes),
+    auth: googleBearerProxyAuth(googleChatServiceAccountScopes),
     skipDnsValidation: true,
 });
 export const credentialValidators = {
@@ -42,7 +65,7 @@ export const credentialValidators = {
             },
         };
     },
-    customCredential: googleServiceAccountValidator(service, googleChatOAuthScopes),
+    customCredential: googleServiceAccountValidator(service, googleChatServiceAccountScopes),
 };
 async function listSpaces(input, context) {
     const payload = await googleChatJsonRequest(`${googleChatApiBaseUrl}/spaces`, {
@@ -65,6 +88,129 @@ async function getSpace(input, context) {
     });
     return normalizeSpace(payload);
 }
+/**
+ * Locate the existing direct message space between the authenticated user and
+ * another user. This is the only way to address a person by identity rather than
+ * by an opaque space id: a DIRECT_MESSAGE space carries no displayName, so
+ * `list_spaces` alone can never tell you who a DM is with.
+ *
+ * Finding the space needs nothing beyond chat.spaces.readonly, which the read
+ * actions already use. Naming its peer needs more, so that part is best effort.
+ */
+async function findDirectMessage(input, context) {
+    const name = resolveUserName(input.user);
+    let payload;
+    try {
+        payload = await googleChatJsonRequest(`${googleChatApiBaseUrl}/spaces:findDirectMessage`, {
+            context,
+            query: { name },
+        });
+    }
+    catch (error) {
+        // Google answers 404 for "no such DM", but also for an address that does not
+        // resolve or is not visible to this account. Don't collapse those into
+        // "you haven't talked yet" — say what is actually known.
+        if (error instanceof ProviderRequestError && error.status === 404) {
+            throw new ProviderRequestError(404, `no existing direct message space with ${name}. Either the two of you have never started a conversation, or the identifier is invalid or not visible to this account.`, error.details);
+        }
+        // An address Google cannot resolve to an account comes back as 400
+        // "Missing or malformed user resource name ... must follow this format:
+        // users/{user}". The format was not the problem — that is Google's wording
+        // for "no such user", and taken at face value it sends the caller off to add
+        // a users/ prefix, which this action deliberately rejects. So relabel it.
+        //
+        // Deliberately matched on that specific wording rather than on "any 400":
+        // our own validation already ran, so a 400 almost always concerns the
+        // address, but "almost always" is not "always", and mislabelling some other
+        // 400 as a bad address would point debugging in the wrong direction. If
+        // Google ever rewords this, the raw error comes through unchanged — the
+        // status quo, not a regression.
+        if (error instanceof ProviderRequestError && error.status === 400 && /user resource name/i.test(error.message)) {
+            throw new ProviderRequestError(400, `Google did not accept ${name} as a user identifier. The value is well-formed here, so this usually means it does not resolve to a Google account that this connection can see — check the address. Google's own wording asks for users/{user}; do not add that prefix, this action takes the bare address or id.`, error.details);
+        }
+        throw error;
+    }
+    const space = normalizeSpace(payload);
+    const spaceName = requirePayloadString(space.name, "Google Chat returned a space without a resource name");
+    try {
+        return { ...space, peer: await resolveDirectMessagePeer(spaceName, context) };
+    }
+    catch (error) {
+        // The space was found; failing to name its other member must not hide that.
+        // Report why instead, so the caller knows the recipient is unconfirmed. Only a
+        // cancelled request stops the action. Listing the members and reading the
+        // caller's own id already say which of them failed, including a network error
+        // or a response that is not JSON as a 502; the prefix below only covers a
+        // failure neither of them anticipated.
+        if (context.signal?.aborted) {
+            throw error;
+        }
+        const failure = error instanceof ProviderRequestError
+            ? error
+            : providerResponseError(`could not resolve the direct message peer: ${error instanceof Error ? error.message : String(error)}`);
+        return { ...space, peer: null, peerError: { status: failure.status, message: failure.message } };
+    }
+}
+/**
+ * Name the other participant of a direct message space. Under user authentication
+ * Chat may report a member only as `users/{id}`, so whatever it leaves out is
+ * looked up in the Workspace directory through the People API, where the same id
+ * names the person.
+ */
+async function getDirectMessagePeer(input, context) {
+    const spaceName = resolveSpaceName(input.space, "space is required");
+    const space = requiredResponseRecord(await googleChatJsonRequest(`${googleChatApiBaseUrl}/${encodeResourceName(spaceName)}`, { context }), "Google Chat space");
+    // Google always reports the type of a space it returns, so a missing one is a
+    // malformed response rather than something wrong with the caller's input.
+    const spaceType = requirePayloadString(space.spaceType, `Google Chat returned ${spaceName} without a space type`);
+    if (spaceType !== "DIRECT_MESSAGE") {
+        // Every member of a named space would otherwise be a "peer" candidate, and
+        // calling one of them the peer would be a guess presented as a fact.
+        throw new ProviderRequestError(400, `${spaceName} is ${spaceType}, not a direct message`);
+    }
+    return { space: spaceName, peer: await resolveDirectMessagePeer(spaceName, context) };
+}
+/**
+ * List a space's members with their directory names, one page at a time. Works
+ * for any space type; unlike get_direct_message_peer it names everyone and makes
+ * no claim about who "the" other participant is.
+ */
+async function listSpaceMembers(input, context) {
+    const spaceName = resolveSpaceName(input.space, "space is required");
+    const pageSize = resolvePageSize(input.pageSize);
+    const page = await listSpaceMembersPage(spaceName, { pageSize, pageToken: optionalString(input.pageToken) }, context);
+    return { space: spaceName, ...page };
+}
+/**
+ * Chat allows up to 1000 members per page, but every human on a page is named in
+ * one People batch that takes at most 200, so larger pages are refused rather than
+ * silently split into several lookups.
+ */
+function resolvePageSize(value) {
+    if (value === undefined || value === null) {
+        return defaultMemberPageSize;
+    }
+    if (typeof value !== "number" || !Number.isInteger(value) || value < 1 || value > maxProfilesPerLookup) {
+        throw new ProviderRequestError(400, `pageSize must be an integer from 1 to ${maxProfilesPerLookup}`);
+    }
+    return value;
+}
+/**
+ * Accept a bare user id or a bare email address and build `users/{user}`.
+ *
+ * Deliberately narrow: no `users/` prefix (one input shape, no ambiguity), no
+ * `me`/`app` aliases, nothing containing a path separator or whitespace. Case is
+ * preserved and nothing is percent-decoded — the value is passed through as-is.
+ */
+function resolveUserName(value) {
+    const raw = requireString(value, "user is required");
+    const trimmed = raw.trim();
+    const wellFormed = userIdPattern.test(trimmed) || userEmailPattern.test(trimmed);
+    if (trimmed.length > 320 || !wellFormed) {
+        throw new ProviderRequestError(400, `user must be an email address or a numeric user id, received "${raw}"`);
+    }
+    return `users/${trimmed}`;
+}
 async function listMessages(input, context) {
     const spaceName = resolveSpaceName(input.space, "space is required");
     const payload = await googleChatJsonRequest(`${googleChatApiBaseUrl}/${encodeResourceName(spaceName)}/messages`, {
@@ -78,7 +224,7 @@ async function listMessages(input, context) {
         }),
     });
     return {
-        messages: Array.isArray(payload.messages) ? payload.messages.map((item) => normalizeMessage(item)) : [],
+        messages: await attachSenderProfiles(Array.isArray(payload.messages) ? payload.messages.map((item) => normalizeMessage(item)) : [], context),
         nextPageToken: optionalString(payload.nextPageToken) ?? null,
     };
 }
@@ -87,6 +233,36 @@ async function getMessage(input, context) {
     const payload = await googleChatJsonRequest(`${googleChatApiBaseUrl}/${encodeResourceName(messageName)}`, {
         context,
     });
+    const [message] = await attachSenderProfiles([normalizeMessage(payload)], context);
+    return message;
+}
+async function createMessage(input, context) {
+    const spaceName = resolveSpaceName(input.space, "space is required");
+    const text = requireRawText(input.text, "text is required");
+    // Read the thread raw: optionalString() trims and then treats the result as
+    // falsy, which would turn a whitespace-only thread into "no thread given" and
+    // silently post a new message instead of the requested reply. Anything the
+    // caller actually supplied has to reach resolveThreadName and fail loudly.
+    const rawThread = optionalRawString(input.thread);
+    const threadName = rawThread === undefined ? undefined : resolveThreadName(rawThread, spaceName);
+    const replyOption = optionalString(input.messageReplyOption);
+    if (replyOption && !threadName) {
+        throw new ProviderRequestError(400, "messageReplyOption is only allowed together with thread");
+    }
+    const payload = await googleChatJsonRequest(`${googleChatApiBaseUrl}/${encodeResourceName(spaceName)}/messages`, {
+        context,
+        method: "POST",
+        query: compactObject({
+            // Google's own default silently ignores `thread` and starts a new one, so a
+            // caller that supplied a thread gets an explicit failure instead.
+            messageReplyOption: replyOption ?? (threadName ? "REPLY_MESSAGE_OR_FAIL" : undefined),
+            requestId: optionalString(input.requestId),
+        }),
+        body: compactObject({
+            text,
+            thread: threadName ? { name: threadName } : undefined,
+        }),
+    });
     return normalizeMessage(payload);
 }
 function normalizeSpace(value) {
@@ -134,6 +310,7 @@ function normalizeMessage(value) {
             ? compactObject({
                 name: optionalString(sender.name),
                 displayName: optionalString(sender.displayName),
+                email: optionalString(sender.email),
                 type: optionalString(sender.type),
                 domainId: optionalString(sender.domainId),
                 isAnonymous: optionalBoolean(sender.isAnonymous),
@@ -186,25 +363,27 @@ function resolveMessageName(input) {
     }
     return name;
 }
-function googleChatJsonRequest(url, input) {
-    return googleJsonRequest(url, {
-        accessToken: input.context.accessToken,
-        fetcher: input.context.fetcher,
-        signal: input.context.signal,
-        method: input.method,
-        query: input.query,
-        body: input.body,
-        service,
-    });
-}
-function encodeResourceName(name) {
-    return name
-        .split("/")
-        .map((segment) => encodeURIComponent(segment))
-        .join("/");
-}
-function stripPrefix(value, prefix) {
-    return value.startsWith(prefix) ? value.slice(prefix.length) : value;
+/**
+ * Accept only the full `spaces/{space}/threads/{thread}` resource name, and require
+ * it to belong to the space being posted into. The thread travels in the request
+ * body rather than the URL, so this is a contract check rather than traversal
+ * defence: it turns a cross-space or malformed thread into a local 400 instead of
+ * an opaque remote error.
+ */
+function resolveThreadName(value, parentSpaceName) {
+    const trimmed = trimSlashes(value.trim());
+    const [, spaceId, , threadId] = trimmed.split("/");
+    if (!threadNamePattern.test(trimmed) ||
+        spaceId === "." ||
+        spaceId === ".." ||
+        threadId === "." ||
+        threadId === "..") {
+        throw new ProviderRequestError(400, `thread must be spaces/{space}/threads/{thread}, received "${value}"`);
+    }
+    if (`spaces/${spaceId}` !== parentSpaceName) {
+        throw new ProviderRequestError(400, `thread must belong to ${parentSpaceName}, received "${value}"`);
+    }
+    return trimmed;
 }
 function trimSlashes(value) {
     return value.replace(/^\/+/, "").replace(/\/+$/, "");
@@ -224,6 +403,18 @@ function requireString(value, message) {
     }
     return resolved;
 }
+/**
+ * Like `requireString`, but keeps the value exactly as provided. Message bodies
+ * carry meaningful indentation, so the outgoing text must not be trimmed — while a
+ * body that is only whitespace is still rejected.
+ */
+function requireRawText(value, message) {
+    const resolved = optionalRawString(value);
+    if (resolved === undefined || resolved.trim().length === 0) {
+        throw new ProviderRequestError(400, message);
+    }
+    return resolved;
+}
 function requirePayloadString(value, message) {
     const resolved = optionalString(value);
     if (!resolved) {

package/src/providers/googlechat/members.d.ts

@@ -0,0 +1,55 @@
+import type { GoogleChatRuntimeContext } from "./runtime.ts";
+/** people:batchGet accepts at most this many resource names per call. */
+export declare const maxProfilesPerLookup = 200;
+type ProfileUnavailableReason = "profile_name_missing" | "people_forbidden" | "people_not_found" | "people_request_failed";
+interface MemberProfile {
+    displayName: string | null;
+    email: string | null;
+    profileUnavailableReason?: ProfileUnavailableReason;
+}
+type DirectMessagePeerKind = "HUMAN" | "BOT" | "SELF" | "AMBIGUOUS";
+interface DirectMessagePeer extends MemberProfile {
+    kind: DirectMessagePeerKind;
+    user: string | null;
+    candidates?: string[];
+}
+interface SpaceMember extends MemberProfile {
+    user: string;
+    kind: string | undefined;
+    role: string | undefined;
+    isSelf: boolean;
+}
+interface SpaceMembersPage {
+    members: SpaceMember[];
+    nextPageToken: string | null;
+}
+interface SpaceMembersPageRequest {
+    pageSize: number;
+    pageToken: string | undefined;
+    /** Also list members who were invited but have not joined yet. */
+    showInvited?: boolean;
+}
+/**
+ * Name the other participant of a direct message. The authenticated user and the
+ * peer are told apart by id, because a Chat membership never says which member is
+ * "me". BOT and SELF are ordinary outcomes, not failures: they keep whatever name
+ * and email Chat reports for the membership and skip the directory.
+ */
+export declare function resolveDirectMessagePeer(spaceName: string, context: GoogleChatRuntimeContext): Promise<DirectMessagePeer>;
+/**
+ * One page of a space's members. Every human Google Chat left without a name or
+ * email is looked up in a single batched directory call; the page size is capped
+ * so one call always covers the page.
+ */
+export declare function listSpaceMembersPage(spaceName: string, request: SpaceMembersPageRequest, context: GoogleChatRuntimeContext): Promise<SpaceMembersPage>;
+/**
+ * Fill in each human sender's name and email on normalized messages. Under user
+ * authentication Chat reports them itself only for members of the space and users
+ * with prior affinity to the caller, so every human sender missing either is
+ * looked up in the directory. Distinct senders are looked up together, so a page
+ * costs one extra request per 200 senders. A failed lookup leaves the message
+ * intact with a null name and a reason; bots and messages without a sender are
+ * left as they are.
+ */
+export declare function attachSenderProfiles(messages: Record<string, unknown>[], context: GoogleChatRuntimeContext): Promise<Record<string, unknown>[]>;
+export {};