@oomol-lab/open-connector 1.6.4 → 1.7.0

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 {};

package/src/providers/googlechat/members.js

@@ -0,0 +1,293 @@
+import { compactObject, looseArray, optionalRecord, optionalString, recordOrEmpty } from "../../core/cast.js";
+import { ProviderRequestError, providerResponseError } from "../provider-runtime.js";
+import { encodeResourceName, googleChatApiBaseUrl, googleChatJsonRequest, stripPrefix } from "./runtime.js";
+const peopleApiBaseUrl = "https://people.googleapis.com/v1";
+// A direct message has at most two members, so this only guards against a
+// pagination token that never runs out.
+const maxDirectMessageMemberPages = 20;
+/** people:batchGet accepts at most this many resource names per call. */
+export const maxProfilesPerLookup = 200;
+// google.rpc.Code values a per-person batchGet status can carry.
+const rpcNotFound = 5;
+const rpcPermissionDenied = 7;
+/**
+ * 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 async function resolveDirectMessagePeer(spaceName, context) {
+    const [selfUser, members] = await Promise.all([readSelfUserName(context), listAllMembers(spaceName, context)]);
+    const humans = members.filter((member) => member.type === "HUMAN");
+    const bots = members.filter((member) => member.type === "BOT");
+    const others = humans.filter((member) => member.name !== selfUser);
+    const self = humans.find((member) => member.name === selfUser);
+    if (others.length === 1) {
+        const [peer] = others;
+        const profiles = await lookupProfiles(missingChatProfiles(others), context);
+        return { kind: "HUMAN", user: peer.name, ...mergeProfile(peer, profiles.get(peer.name)) };
+    }
+    if (others.length > 1) {
+        return ambiguousPeer(others);
+    }
+    if (bots.length === 1) {
+        const [peer] = bots;
+        return { kind: "BOT", user: peer.name, ...mergeProfile(peer, undefined) };
+    }
+    if (bots.length === 0 && self) {
+        return { kind: "SELF", user: self.name, ...mergeProfile(self, undefined) };
+    }
+    return ambiguousPeer(bots);
+}
+/**
+ * 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 async function listSpaceMembersPage(spaceName, request, context) {
+    const [selfUser, page] = await Promise.all([readSelfUserName(context), fetchMemberPage(spaceName, request, context)]);
+    const humans = page.members.filter((member) => member.type === "HUMAN");
+    const profiles = await lookupProfiles(missingChatProfiles(humans), context);
+    return {
+        members: page.members.map((member) => ({
+            user: member.name,
+            kind: member.type,
+            role: member.role,
+            isSelf: member.name === selfUser,
+            ...mergeProfile(member, profiles.get(member.name)),
+        })),
+        nextPageToken: page.nextPageToken ?? null,
+    };
+}
+function ambiguousPeer(candidates) {
+    return {
+        kind: "AMBIGUOUS",
+        user: null,
+        displayName: null,
+        email: null,
+        candidates: candidates.map((member) => member.name),
+    };
+}
+/** The authenticated user's own `users/{id}`; People and Chat share the id. */
+async function readSelfUserName(context) {
+    let payload;
+    try {
+        payload = recordOrEmpty(await googleChatJsonRequest(`${peopleApiBaseUrl}/people/me`, {
+            context,
+            query: { personFields: "metadata" },
+        }));
+    }
+    catch (error) {
+        if (context.signal?.aborted) {
+            throw error;
+        }
+        // Only a 403 can mean the People API is not enabled for the project.
+        throw explainLookupError("could not read the authenticated user's own id from the People API, so members cannot be told apart from the caller", error, "The People API must be enabled for the OAuth client's Google Cloud project.");
+    }
+    const resourceName = optionalString(payload.resourceName);
+    if (!resourceName?.startsWith("people/")) {
+        throw new ProviderRequestError(502, "the People API returned no resource name for the authenticated user");
+    }
+    return `users/${stripPrefix(resourceName, "people/")}`;
+}
+/**
+ * Say which Chat or People lookup failed. An HTTP failure keeps its status and
+ * details and gains forbiddenHint on a 403, the only status a console or consent
+ * change can fix; a 429, a 5xx, or a timeout needs a retry instead. A failure that
+ * is not an HTTP error, such as a response that is not JSON, becomes a 502 that
+ * names the lookup instead of reaching the caller as a raw internal error.
+ */
+function explainLookupError(summary, error, forbiddenHint) {
+    if (!(error instanceof ProviderRequestError)) {
+        return providerResponseError(`${summary}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    const hint = error.status === 403 ? ` ${forbiddenHint}` : "";
+    // Google's messages usually end in a period already; drop it so the sentence ends once.
+    const detail = error.message.replace(/\.\s*$/, "");
+    return new ProviderRequestError(error.status, `${summary}: ${detail}.${hint}`, error.details);
+}
+async function listAllMembers(spaceName, context) {
+    let members = [];
+    let pageToken;
+    for (let page = 0; page < maxDirectMessageMemberPages; page += 1) {
+        let result;
+        try {
+            // Chat leaves invited members out by default. A peer who has not joined the
+            // conversation yet is still the peer; without it the caller would be the only
+            // member left and the direct message would be misreported as SELF.
+            result = await fetchMemberPage(spaceName, { pageSize: 100, pageToken, showInvited: true }, context);
+        }
+        catch (error) {
+            if (context.signal?.aborted) {
+                throw error;
+            }
+            // A 403 here is almost always the missing scope: the space itself was readable.
+            throw explainLookupError(`could not list the members of ${spaceName}, so the direct message's other participant is unknown`, error, "Listing members needs the chat.memberships.readonly scope, which service account connections never request; an OAuth connection authorized before this scope was added must be reconnected to grant it.");
+        }
+        members = [...members, ...result.members];
+        pageToken = result.nextPageToken;
+        if (!pageToken) {
+            return members;
+        }
+    }
+    throw new ProviderRequestError(502, `Google Chat kept paginating the members of ${spaceName}`);
+}
+async function fetchMemberPage(spaceName, request, context) {
+    const payload = await googleChatJsonRequest(`${googleChatApiBaseUrl}/${encodeResourceName(spaceName)}/members`, {
+        context,
+        query: compactObject({
+            pageSize: String(request.pageSize),
+            pageToken: request.pageToken,
+            showInvited: request.showInvited ? "true" : undefined,
+        }),
+    });
+    return {
+        members: looseArray(payload.memberships).flatMap((item) => toChatMember(item)),
+        nextPageToken: optionalString(payload.nextPageToken),
+    };
+}
+function toChatMember(value) {
+    const membership = recordOrEmpty(value);
+    const member = recordOrEmpty(membership.member);
+    const name = optionalString(member.name);
+    return name
+        ? [
+            {
+                name,
+                type: optionalString(member.type),
+                role: optionalString(membership.role),
+                displayName: optionalString(member.displayName),
+                email: optionalString(member.email),
+            },
+        ]
+        : [];
+}
+/**
+ * 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 async function attachSenderProfiles(messages, context) {
+    const profiles = await lookupProfiles(missingChatProfiles(messages.flatMap((message) => humanSender(message))), context);
+    return messages.map((message) => {
+        const [sender] = humanSender(message);
+        return sender
+            ? { ...message, sender: { ...recordOrEmpty(message.sender), ...mergeProfile(sender, profiles.get(sender.name)) } }
+            : message;
+    });
+}
+/** The human users/{id} sender of a normalized message, if it has one. */
+function humanSender(message) {
+    const sender = optionalRecord(message.sender);
+    const name = optionalString(sender?.name);
+    return sender?.type === "HUMAN" && name?.startsWith("users/")
+        ? [{ name, displayName: optionalString(sender.displayName), email: optionalString(sender.email) }]
+        : [];
+}
+/** The distinct users whose name or email Chat left out, which only the directory can fill in. */
+function missingChatProfiles(users) {
+    const missing = users.filter((user) => user.displayName === undefined || user.email === undefined);
+    return [...new Set(missing.map((user) => user.name))];
+}
+/**
+ * Combine what Chat reported with the directory profile. Chat's own name and email
+ * win and the directory only fills in what Chat left out, so a failed lookup never
+ * replaces a known value with null. profileUnavailableReason explains a null
+ * displayName, so it is only kept while the name is still missing.
+ */
+function mergeProfile(chat, directory) {
+    const displayName = chat.displayName ?? directory?.displayName ?? null;
+    return {
+        displayName,
+        email: chat.email ?? directory?.email ?? null,
+        profileUnavailableReason: displayName === null ? directory?.profileUnavailableReason : undefined,
+    };
+}
+/**
+ * Name `users/{id}` members through the Workspace directory, batching up to the
+ * People API limit per call. A member whose profile cannot be read keeps a null
+ * name and a reason; a failure of a whole call gives each member in it that reason.
+ */
+async function lookupProfiles(users, context) {
+    const batches = Array.from({ length: Math.ceil(users.length / maxProfilesPerLookup) }, (_, index) => users.slice(index * maxProfilesPerLookup, (index + 1) * maxProfilesPerLookup));
+    const results = await Promise.all(batches.map((batch) => lookupProfileBatch(batch, context)));
+    return new Map(results.flatMap((result) => [...result]));
+}
+async function lookupProfileBatch(users, context) {
+    let payload;
+    try {
+        payload = recordOrEmpty(await googleChatJsonRequest(`${peopleApiBaseUrl}/people:batchGet`, {
+            context,
+            query: {
+                resourceNames: users.map((user) => `people/${stripPrefix(user, "users/")}`),
+                personFields: "names,emailAddresses",
+                sources: "READ_SOURCE_TYPE_PROFILE",
+            },
+        }));
+    }
+    catch (error) {
+        // Naming is best effort, so only a cancelled request stops the action. Any
+        // other failure, including a network error or a 200 whose body is not JSON,
+        // leaves the users unnamed with a reason.
+        if (context.signal?.aborted) {
+            throw error;
+        }
+        const reason = error instanceof ProviderRequestError ? httpFailureReason(error.status) : "people_request_failed";
+        return new Map(users.map((user) => [user, unavailableProfile(reason)]));
+    }
+    const responses = new Map(looseArray(payload.responses).map((entry) => {
+        const response = recordOrEmpty(entry);
+        return [optionalString(response.requestedResourceName), response];
+    }));
+    return new Map(users.map((user) => [user, toMemberProfile(responses.get(`people/${stripPrefix(user, "users/")}`))]));
+}
+function toMemberProfile(response) {
+    // A missing entry says nothing about the person: a genuine miss comes back as its
+    // own NOT_FOUND status, so an absent or unmatched entry is a malformed response.
+    if (!response) {
+        return unavailableProfile("people_request_failed");
+    }
+    const rpcCode = optionalRecord(response.status)?.code;
+    if (typeof rpcCode === "number" && rpcCode !== 0) {
+        return unavailableProfile(rpcFailureReason(rpcCode));
+    }
+    const person = recordOrEmpty(response.person);
+    const displayName = primaryProfileValue(person.names, "displayName");
+    return {
+        displayName: displayName ?? null,
+        email: primaryProfileValue(person.emailAddresses, "value") ?? null,
+        // A 200 without a name is what a Workspace with profile sharing turned off returns.
+        profileUnavailableReason: displayName ? undefined : "profile_name_missing",
+    };
+}
+function unavailableProfile(reason) {
+    return { displayName: null, email: null, profileUnavailableReason: reason };
+}
+/** Only 403 and 404 say something about the profile; anything else is a failed request, not a hidden one. */
+function httpFailureReason(status) {
+    if (status === 403) {
+        return "people_forbidden";
+    }
+    if (status === 404) {
+        return "people_not_found";
+    }
+    return "people_request_failed";
+}
+function rpcFailureReason(code) {
+    if (code === rpcPermissionDenied) {
+        return "people_forbidden";
+    }
+    if (code === rpcNotFound) {
+        return "people_not_found";
+    }
+    return "people_request_failed";
+}
+function primaryProfileValue(value, field) {
+    const entries = looseArray(value).map((entry) => recordOrEmpty(entry));
+    const primary = entries.find((entry) => optionalRecord(entry.metadata)?.primary === true) ?? entries[0];
+    return optionalString(primary?.[field]);
+}