m365connector 0.3.6 → 0.3.8

package/src/lib/search-api.js

@@ -0,0 +1,989 @@
+import { TOKEN_AUDIENCES } from "../token-providers.js";
+
+const CLIENT_APP_OVERRIDE_USERP = "4765445b-32c6-49b0-83e6-1d93765276ca";
+
+const SEARCH_ENDPOINT = `https://substrate.office.com/searchservice/api/v3/query?clientappoverride=${CLIENT_APP_OVERRIDE_USERP}&setFlight=EnableAggregationHelper,EnableM365CopilotAggregationV2`;
+
+const MIN_FLIGHTS = "EnableAggregationHelper,EnableM365CopilotAggregationV2";
+
+const FILE_FIELDS = [
+  ".callerStack",
+  ".correlationId",
+  ".mediaBaseUrl",
+  ".spResourceUrl",
+  ".thumbnailUrl",
+  "AuthorOWSUSER",
+  "ContainerTypeId",
+  "ContentClass",
+  "ContentTypeId",
+  "DefaultEncodingURL",
+  "Description",
+  "DocId",
+  "EditorOWSUSER",
+  "FileExtension",
+  "Filename",
+  "GeoLocationSource",
+  "HitHighlightedSummary",
+  "IsContainer",
+  "LastModifiedTime",
+  "LinkingUrl",
+  "ListID",
+  "ModifiedBy",
+  "ParentLink",
+  "Path",
+  "PiSearchResultId",
+  "PictureThumbnailURL",
+  "ProgID",
+  "PromotedState",
+  "SPWebUrl",
+  "SecondaryFileExtension",
+  "SensitivityLabel",
+  "ServerRedirectedPreviewURL",
+  "ServerRedirectedUrl",
+  "ShortcutUrl",
+  "SiteId",
+  "SiteTemplateId",
+  "SiteTitle",
+  "Title",
+  "UniqueID",
+  "UniqueId",
+  "ViewCount",
+  "ViewsLifeTimeUniqueUsers",
+  "WebId",
+  "filetype",
+  "isDocument",
+  "isexternalcontent",
+  "Created",
+  "PrivacyIndicator",
+  "MediaDuration",
+  "ColorHex",
+  "ModifierUPNs",
+  "InformationProtectionLabelId",
+  "SiteSensitivityLabelID",
+  "Summary",
+  "People",
+  "DisplayAuthor",
+  "GroupId",
+  "SiteLogo",
+  "SiteName",
+  "WebUrl",
+  "WebLink",
+];
+
+const EMAIL_FIELDS = [
+  "Id",
+  "ParentFolderHexId",
+  "ParentFolderId",
+  "ParentFolderRestId",
+  "SortOrderSource",
+  "ItemId",
+  "ImmutableId",
+  "ClientConversationId",
+  "ClientThreadId",
+  "ConversationTopic",
+  "ConversationIndex",
+  "DateTimeCreated",
+  "DateTimeReceived",
+  "DateTimeSent",
+  "DisplayBcc",
+  "DisplayTo",
+  "HasAttachments",
+  "IconIndex",
+  "ImmutableEntryId",
+  "Importance",
+  "InferenceClassification",
+  "InternetMessageId",
+  "IsDraft",
+  "IsRead",
+  "ItemClass",
+  "NormalizedSubject",
+  "ParentFolderDisplayName",
+  "Preview",
+  "ReceivedOrRenewTime",
+  "Sender",
+  "Sensitivity",
+  "Size",
+  "Subject",
+  "ConversationHexId",
+  "From",
+  "ConversationId",
+  "ConversationRestId",
+  "ConversationThreadId",
+  "ItemHexId",
+  "ItemRestId",
+  "MailboxGuids",
+  "MentionsPreview",
+  "SortKey",
+  "Extensions",
+  "Extension_SkypeSpaces_ConversationPost_Extension_FromSkypeInternalId_String",
+  "Extension_SkypeSpaces_ConversationPost_Extension_ThreadType_String",
+  "ChannelName",
+  "HitHighlightedSummary",
+  "RawContent",
+  "InformationProtectionLabelId",
+  "HasIRM",
+  "ExtractRightsDisabled",
+  "DrmRights",
+  "AttachmentMetadata",
+  "MailboxOwnerUPN",
+  "MailboxOwnerId",
+  "MailboxOwnerEmailAddress",
+];
+
+const CHAT_FIELDS = [
+  "Id",
+  "ParentFolderHexId",
+  "ParentFolderId",
+  "ParentFolderRestId",
+  "SortOrderSource",
+  "ItemId",
+  "ImmutableId",
+  "ClientConversationId",
+  "ClientThreadId",
+  "ConversationTopic",
+  "ConversationIndex",
+  "DateTimeCreated",
+  "DateTimeReceived",
+  "DateTimeSent",
+  "DisplayBcc",
+  "DisplayTo",
+  "HasAttachments",
+  "IconIndex",
+  "ImmutableEntryId",
+  "Importance",
+  "InferenceClassification",
+  "InternetMessageId",
+  "IsDraft",
+  "IsRead",
+  "ItemClass",
+  "ParentFolderDisplayName",
+  "Preview",
+  "ReceivedOrRenewTime",
+  "Sender",
+  "Size",
+  "Subject",
+  "ConversationHexId",
+  "From",
+  "ConversationId",
+  "ConversationRestId",
+  "ConversationThreadId",
+  "ItemHexId",
+  "ItemRestId",
+  "MailboxGuids",
+  "MentionsPreview",
+  "SortKey",
+  "Extensions",
+  "Extension_SkypeSpaces_ConversationPost_Extension_FromSkypeInternalId_String",
+  "Extension_SkypeSpaces_ConversationPost_Extension_ThreadType_String",
+  "Extension_SkypeSpaces_ConversationPost_Extension_Topic_String",
+  "Extension_SkypeSpaces_ConversationPost_Extension_ParentMessageId_String",
+  "ChannelName",
+  "TeamName",
+  "GroupId",
+  "HitHighlightedSummary",
+  "WebLink",
+];
+
+const EXTERNAL_FIELDS = [
+  "label_Title",
+  "label_URL",
+  "label_LastModifiedBy",
+  "label_LastModifiedDateTime",
+  "Label_ItemPath",
+  "Label_State",
+  "Label_ContainerName",
+  "Label_Tags",
+  "BestAnswerAuthorName",
+  "Author",
+  "Url",
+  "AccessUrl",
+  "IconUrl",
+  "Summary",
+  "FileID",
+  "HitHighlightedSummary",
+];
+
+const EVENT_FIELDS = [];
+
+const PEOPLE_FIELDS = [
+  "FieldsWithMatch",
+  "Topics",
+  "Skills",
+  "Confidence",
+  "Department",
+  "DisplayName",
+  "EmailAddresses",
+  "Id",
+  "JobTitle",
+  "OfficeLocation",
+  "Phones",
+  "PropertyHits",
+  "Score",
+  "Text",
+  "UserPrincipalName",
+  "ImAddress",
+  "GivenName",
+];
+
+const BOOKMARK_FIELDS = [];
+
+const ACRONYM_FIELDS = [];
+
+const COPILOT_CHAT_FIELDS = [
+  "Id",
+  "ParentFolderHexId",
+  "ParentFolderId",
+  "ParentFolderRestId",
+  "SortOrderSource",
+  "ItemId",
+  "ImmutableId",
+  "ClientConversationId",
+  "ClientThreadId",
+  "ConversationIndex",
+  "DateTimeCreated",
+  "DateTimeLastModified",
+  "DateTimeReceived",
+  "DateTimeSent",
+  "DisplayBcc",
+  "DisplayTo",
+  "HasAttachments",
+  "IconIndex",
+  "Importance",
+  "InferenceClassification",
+  "InternetMessageId",
+  "IsDraft",
+  "IsRead",
+  "ItemClass",
+  "ParentFolderDisplayName",
+  "Preview",
+  "ReceivedOrRenewTime",
+  "Sender",
+  "Size",
+  "ConversationHexId",
+  "From",
+  "ItemHexId",
+  "ItemRestId",
+  "MailboxGuids",
+  "MentionsPreview",
+  "SortKey",
+  "Extensions",
+  "Extension_SkypeSpaces_ConversationPost_Extension_FromSkypeInternalId_String",
+  "Extension_SkypeSpaces_ConversationPost_Extension_ThreadType_String",
+  "Extension_SkypeSpaces_ConversationPost_Extension_Topic_String",
+  "Extension_SkypeSpaces_ConversationPost_Extension_UpdatedTopic_String",
+  "Extension_SkypeSpaces_ConversationPost_Extension_CopilotAgentIdentifier_String",
+  "ImmutableEntryId",
+  "Subject",
+  "ConversationId",
+  "ConversationRestId",
+  "ConversationThreadId",
+  "IsLegacyWebChat",
+  "BigFunnelConversationGroupIndex",
+  "BigFunnelConversationItemCount",
+  "Sensitivity",
+  "WebLink",
+];
+
+function cryptoUuid() {
+  return crypto.randomUUID();
+}
+
+function stripTags(value) {
+  if (!value || typeof value !== "string") {
+    return "";
+  }
+  return value
+    .replace(/<c\d+>/g, "")
+    .replace(/<\/c\d+>/g, "")
+    .replace(/<[^>]*>/g, "")
+    .replace(/\s+/g, " ")
+    .trim();
+}
+
+function textOrEmpty(value) {
+  if (value == null) {
+    return "";
+  }
+  return String(value).trim();
+}
+
+function pickFirst(...values) {
+  for (const value of values) {
+    if (value !== undefined && value !== null && value !== "") {
+      return value;
+    }
+  }
+  return "";
+}
+
+function getTimeZoneInfo() {
+  const now = new Date();
+  return {
+    timeZone: Intl.DateTimeFormat().resolvedOptions().timeZone || "UTC",
+    offset: -now.getTimezoneOffset(),
+  };
+}
+
+function buildAggregationRequests(source, connector) {
+  if (connector) {
+    return [
+      { DataSource: { Name: "All", Composition: [] }, Filters: [] },
+      { DataSource: { Name: connector, Composition: [] }, Filters: [] },
+    ];
+  }
+
+  if (source === "all") {
+    return [
+      {
+        DataSource: { Name: "All", Composition: [] },
+        Filters: [],
+        Aggregations: [
+          {
+            $type: "Histogram",
+            Field: "Label_Source",
+            From: 0,
+            Size: 50,
+            BucketDefinition: {
+              SortBy: "Count",
+              IsDescending: true,
+              MinimumCount: 1,
+            },
+          },
+          {
+            $type: "Histogram",
+            Field: "Label_Type",
+            From: 0,
+            Size: 50,
+            BucketDefinition: {
+              SortBy: "Count",
+              IsDescending: true,
+              MinimumCount: 1,
+            },
+          },
+        ],
+      },
+    ];
+  }
+
+  return [{ DataSource: { Name: "All", Composition: [] }, Filters: [] }];
+}
+
+function buildEntityRequests(source, connector) {
+  const fileReq = {
+    EntityType: "File",
+    SearchMechanisms: ["Lexical", "Semantic"],
+    Fields: FILE_FIELDS,
+    FilterExpression:
+      '(({searchterms}) (NOT FileExtension:vtt AND NOT FileExtension:pod AND NOT (Title:OneNote_DeletedPages OR Title:OneNote_RecycleBin) AND NOT SecondaryFileExtension:onetoc2 AND NOT (ContentClass:STS_List_544 OR ContentClass:STS_ListItem_544) AND NOT WebTemplate:SPSPERS AND NOT (ContentClass:STS_List_DocumentLibrary AND SiteTemplateId:21) AND NOT (ContentClass:STS_List_DocumentLibrary AND Author:"system account")) AND (SPTranslationLanguage:en-us OR (NOT SPTranslatedLanguages:en-us AND NOT SPIsTranslation:true))) AND NOT FileType:pod',
+    Sort: { Field: "PersonalScore", SortDirection: "Desc" },
+    IdFormat: "EwsId",
+  };
+
+  const externalReq = {
+    EntityType: "External",
+    IdFormat: "EwsId",
+    Fields: EXTERNAL_FIELDS,
+    Connections: ["Connectors"],
+    SearchMechanisms: ["Lexical", "Semantic"],
+    AggregationFilters: [],
+  };
+
+  const emailReq = {
+    EntityType: "Email",
+    FilterExpression:
+      "DistinguishedFolderName:msgfolderroot OR DistinguishedFolderName:deleteditems",
+    Sort: { Field: "Score", SortDirection: "Desc" },
+    TopResultsCount: 7,
+    IdFormat: "EwsId",
+    Fields: EMAIL_FIELDS,
+    SearchMechanisms: ["Lexical", "Semantic"],
+  };
+
+  const chatReq = {
+    EntityType: "Chat",
+    FilterExpression: "",
+    Sort: { Field: "Score", SortDirection: "Desc" },
+    IdFormat: "EwsId",
+    Fields: CHAT_FIELDS,
+  };
+
+  const bookmarkReq = {
+    EntityType: "Bookmark",
+    IdFormat: "EwsId",
+    Fields: BOOKMARK_FIELDS,
+  };
+
+  const peoplePrecisionReq = {
+    EntityType: "People",
+    RequestIntent: "Precision",
+    IdFormat: "EwsId",
+    Fields: PEOPLE_FIELDS,
+  };
+
+  const acronymReq = {
+    EntityType: "Acronym",
+    IdFormat: "EwsId",
+    Fields: ACRONYM_FIELDS,
+  };
+
+  const peopleRecallReq = {
+    EntityType: "People",
+    RequestIntent: "Recall",
+    IdFormat: "EwsId",
+    Fields: PEOPLE_FIELDS,
+    FilterExpression:
+      "{searchterms} (PeopleType:Person AND PeopleSubtype:OrganizationUser)",
+  };
+
+  const eventReq = {
+    EntityType: "Event",
+    FilterExpression: "",
+    Sort: { Field: "Score", SortDirection: "Desc" },
+    IdFormat: "EwsId",
+    Fields: EVENT_FIELDS,
+    RequestIntent: "Recall",
+  };
+
+  const copilotChatReq = {
+    EntityType: "CopilotChat",
+    FilterExpression: "",
+    Sort: { Field: "Time", SortDirection: "Desc" },
+    IdFormat: "EwsId",
+    Fields: COPILOT_CHAT_FIELDS,
+  };
+
+  switch (source) {
+    case "email":
+      return [emailReq];
+    case "files":
+      return [fileReq];
+    case "chat":
+      return [chatReq];
+    case "events":
+      return [eventReq];
+    case "external":
+      return [externalReq];
+    case "all":
+    default:
+      return [
+        fileReq,
+        externalReq,
+        emailReq,
+        chatReq,
+        bookmarkReq,
+        peoplePrecisionReq,
+        acronymReq,
+        peopleRecallReq,
+        eventReq,
+        copilotChatReq,
+      ];
+  }
+}
+
+function safeEmailAddress(value) {
+  return (
+    value?.EmailAddress?.Address ||
+    value?.EmailAddress?.Name ||
+    value?.Address ||
+    value?.Name ||
+    ""
+  );
+}
+
+function ownerIdentity(resource, type) {
+  if (!resource || typeof resource !== "object") {
+    return "";
+  }
+
+  if (type === "email") {
+    return textOrEmpty(
+      pickFirst(
+        resource?.MailboxOwnerId,
+        resource?.MailboxOwnerUPN,
+        resource?.MailboxOwnerEmailAddress,
+        resource?.OwnerId,
+        resource?.OwnerEmailAddress,
+      ),
+    );
+  }
+
+  if (type === "event") {
+    return textOrEmpty(
+      pickFirst(
+        resource?.CalendarOwnerId,
+        resource?.CalendarOwnerUPN,
+        resource?.CalendarOwnerEmailAddress,
+        resource?.MailboxOwnerId,
+        resource?.MailboxOwnerUPN,
+        resource?.OwnerId,
+        resource?.OwnerEmailAddress,
+      ),
+    );
+  }
+
+  return "";
+}
+
+function normalizeResult(result, entityType, index) {
+  const resource = result?.Resource || {};
+  const normalizedType = String(
+    entityType || result?.EntityType || "",
+  ).toLowerCase();
+  const snippet = stripTags(
+    result?.Computations?.HitHighlightedSummary?.Value ||
+      resource?.HitHighlightedSummary ||
+      "",
+  );
+
+  const common = {
+    index,
+    type: normalizedType,
+    title: textOrEmpty(
+      pickFirst(
+        result?.Title,
+        resource?.Title,
+        resource?.Subject,
+        resource?.DisplayName,
+        resource?.label_Title,
+      ),
+    ),
+    url: textOrEmpty(
+      pickFirst(
+        result?.Url,
+        resource?.WebLink,
+        resource?.Url,
+        resource?.AccessUrl,
+        resource?.Path,
+        resource?.ServerRedirectedUrl,
+        resource?.DefaultEncodingURL,
+      ),
+    ),
+    contentSource: textOrEmpty(result?.ContentSource || ""),
+    snippet,
+    date: textOrEmpty(
+      pickFirst(
+        resource?.DateTimeReceived,
+        resource?.DateTimeSent,
+        resource?.LastModifiedTime,
+        resource?.Created,
+        resource?.DateTimeCreated,
+      ),
+    ),
+  };
+
+  if (normalizedType === "email") {
+    const id = textOrEmpty(
+      pickFirst(resource?.ItemRestId, resource?.Id, result?.Id),
+    );
+    const mailboxOwnerId = ownerIdentity(resource, "email");
+    return {
+      ...common,
+      from: textOrEmpty(safeEmailAddress(resource?.From || resource?.Sender)),
+      to: textOrEmpty(resource?.DisplayTo || ""),
+      subject: textOrEmpty(
+        resource?.Subject || resource?.NormalizedSubject || common.title,
+      ),
+      _readContext: {
+        type: "email",
+        id,
+        mailboxOwnerId,
+        title: common.title,
+        url: common.url,
+        snippet: common.snippet,
+      },
+    };
+  }
+
+  if (normalizedType === "file") {
+    const id = textOrEmpty(
+      pickFirst(
+        resource?.UniqueId,
+        resource?.UniqueID,
+        resource?.DocId,
+        result?.Id,
+      ),
+    );
+    const summary = textOrEmpty(resource?.Summary || "");
+    const webUrl = textOrEmpty(
+      pickFirst(
+        resource?.WebUrl,
+        resource?.WebLink,
+        resource?.ServerRedirectedUrl,
+        resource?.DefaultEncodingURL,
+        common.url,
+      ),
+    );
+    const parsedSize = Number(resource?.Size);
+    const size =
+      Number.isFinite(parsedSize) && parsedSize > 0 ? parsedSize : undefined;
+    return {
+      ...common,
+      author: textOrEmpty(
+        resource?.ModifiedBy || resource?.DisplayAuthor || "",
+      ),
+      fileType: textOrEmpty(
+        resource?.FileType || resource?.FileExtension || "",
+      ),
+      preview: summary.slice(0, 2300),
+      _readContext: {
+        type: "file",
+        id,
+        webUrl,
+        size,
+        title: common.title,
+        url: common.url,
+        snippet: common.snippet,
+        // TODO(v0.2): avoid returning large summaries by introducing a server-side context cache key.
+        summary: summary.slice(0, 12000),
+        metadata: {
+          author: textOrEmpty(
+            resource?.ModifiedBy || resource?.DisplayAuthor || "",
+          ),
+          fileType: textOrEmpty(
+            resource?.FileType || resource?.FileExtension || "",
+          ),
+          path: textOrEmpty(resource?.Path || ""),
+          size: size || null,
+        },
+      },
+    };
+  }
+
+  if (normalizedType === "external") {
+    const id = textOrEmpty(
+      pickFirst(result?.Id, resource?.FileID, resource?.Url),
+    );
+    const summary = textOrEmpty(resource?.Summary || "");
+    return {
+      ...common,
+      author: textOrEmpty(
+        resource?.label_LastModifiedBy || resource?.Author || "",
+      ),
+      preview: summary.slice(0, 2300),
+      _readContext: {
+        type: "external",
+        id,
+        title: common.title,
+        url: common.url,
+        snippet: common.snippet,
+        // TODO(v0.2): avoid returning large summaries by introducing a server-side context cache key.
+        summary: summary.slice(0, 12000),
+        metadata: {
+          state: textOrEmpty(resource?.Label_State || ""),
+          container: textOrEmpty(resource?.Label_ContainerName || ""),
+          author: textOrEmpty(
+            resource?.label_LastModifiedBy || resource?.Author || "",
+          ),
+        },
+      },
+    };
+  }
+
+  if (normalizedType === "chat") {
+    const fromAddress = safeEmailAddress(resource?.From || resource?.Sender);
+    const preview = textOrEmpty(resource?.Preview || "");
+    const id = textOrEmpty(pickFirst(resource?.ItemRestId, result?.Id));
+    return {
+      ...common,
+      from: textOrEmpty(fromAddress),
+      teamName: textOrEmpty(resource?.TeamName || ""),
+      channelName: textOrEmpty(resource?.ChannelName || ""),
+      preview,
+      _readContext: {
+        type: "chat",
+        id,
+        title: common.title,
+        url: common.url,
+        snippet: common.snippet,
+        preview,
+        metadata: {
+          from: textOrEmpty(fromAddress),
+          teamName: textOrEmpty(resource?.TeamName || ""),
+          channelName: textOrEmpty(resource?.ChannelName || ""),
+        },
+      },
+    };
+  }
+
+  if (normalizedType === "event") {
+    // Substrate returns flat fields for events: Start/End as ISO strings,
+    // OrganizerName/OrganizerAddress as flat strings, NumberOfAttendees as a count.
+    const id = textOrEmpty(
+      pickFirst(
+        resource?.EventId?.Id,
+        resource?.OriginalId,
+        resource?.ImmutableId,
+        resource?.Id,
+        result?.Id,
+      ),
+    );
+    const calendarOwnerId = ownerIdentity(resource, "event");
+    const organizer = textOrEmpty(
+      resource?.OrganizerAddress || resource?.OrganizerName || "",
+    );
+    // Substrate returns Start/End as plain ISO strings, not { DateTime: "..." } objects.
+    const startTime = textOrEmpty(
+      typeof resource?.Start === "string"
+        ? resource.Start
+        : resource?.Start?.DateTime || "",
+    );
+    const endTime = textOrEmpty(
+      typeof resource?.End === "string"
+        ? resource.End
+        : resource?.End?.DateTime || "",
+    );
+    const meetingUrl = textOrEmpty(
+      resource?.SkypeTeamsMeetingUrl ||
+        resource?.MeetingUrl ||
+        resource?.OnlineMeetingUrl ||
+        "",
+    );
+
+    return {
+      ...common,
+      date: textOrEmpty(pickFirst(startTime, common.date)),
+      subject: textOrEmpty(resource?.Subject || common.title),
+      location: textOrEmpty(
+        resource?.Location?.DisplayName || resource?.Location || "",
+      ),
+      startTime,
+      endTime,
+      organizer,
+      organizerName: textOrEmpty(resource?.OrganizerName || ""),
+      isAllDay: Boolean(resource?.IsAllDay),
+      isCancelled: Boolean(resource?.IsCancelled),
+      showAs: textOrEmpty(resource?.ShowAs || ""),
+      _readContext: {
+        type: "event",
+        id,
+        calendarOwnerId,
+        title: common.title,
+        url: common.url,
+        snippet: common.snippet,
+        metadata: {
+          subject: textOrEmpty(resource?.Subject || ""),
+          location: textOrEmpty(
+            resource?.Location?.DisplayName || resource?.Location || "",
+          ),
+          startTime,
+          endTime,
+          organizer,
+          organizerName: textOrEmpty(resource?.OrganizerName || ""),
+          meetingUrl,
+          isAllDay: Boolean(resource?.IsAllDay),
+          isCancelled: Boolean(resource?.IsCancelled),
+          showAs: textOrEmpty(resource?.ShowAs || ""),
+          numberOfAttendees: Number(resource?.NumberOfAttendees) || 0,
+          importance: textOrEmpty(resource?.Importance || ""),
+        },
+      },
+    };
+  }
+
+  // Unknown types are ignored by the tool surface.
+  return null;
+}
+
+function buildSearchHeaders(tokenEntry) {
+  const mailbox = `Oid:${tokenEntry.oid}@${tokenEntry.tid}`;
+  return {
+    Authorization: `Bearer ${tokenEntry.token}`,
+    "Content-Type": "application/system.text.json",
+    "X-Anchormailbox": mailbox,
+    "X-Routingparameter-Sessionkey": mailbox,
+    "x-scenario": "aihub.search",
+    "X-Client-Flights": MIN_FLIGHTS,
+    "X-Client-LocalTime": new Date().toISOString(),
+    "X-CallingContext": "SERPSearchbox",
+    "X-CafeLatencyHeaderEnabled": "1",
+    "Client-Request-id": cryptoUuid(),
+  };
+}
+
+export class SearchApi {
+  /**
+   * @param {import("./token-manager.js").TokenManager} tokenManager
+   * @param {{ onAuthError?: (() => void | Promise<void>) | null }} [options]
+   */
+  constructor(tokenManager, options = {}) {
+    this.tokenManager = tokenManager;
+    this.onAuthError = options.onAuthError || null;
+  }
+
+  async search(params = {}) {
+    const query = String(params.query || "").trim();
+    if (!query) {
+      throw new Error("query is required");
+    }
+
+    const connector = params.connector ? String(params.connector).trim() : "";
+    const source = connector
+      ? "external"
+      : String(params.source || "all")
+          .trim()
+          .toLowerCase();
+    const size = Number.isInteger(params.size) ? params.size : 10;
+    const from = Number.isInteger(params.from) ? params.from : 0;
+
+    const tokenEntry = this.tokenManager.getTokenEntry(
+      TOKEN_AUDIENCES.SUBSTRATE,
+    );
+    if (!tokenEntry) {
+      throw new Error("Substrate token missing or expired");
+    }
+
+    const tz = getTimeZoneInfo();
+    const entityRequests = buildEntityRequests(source, connector);
+    const body = {
+      ResponseMetadata: ["SearchTerms", "WholePageRankings"],
+      EntityRequests: entityRequests,
+      RequestOptions: {
+        Query: { QueryString: query },
+        Sort: { Field: "Relevance", SortDirection: "Desc" },
+        From: from,
+        Size: size,
+        ComputedFields: [
+          {
+            ComputationType: "ContentExtraction",
+            ExtractionType: "Caption",
+            MaxExtractLength: 200,
+            OutputFieldName: "HitHighlightedSummary",
+          },
+        ],
+        SemanticLabels: [
+          "Label_Source",
+          "Label_Title",
+          "Label_Url",
+          "Label_LastModifiedBy",
+          "Label_LastModifiedDateTime",
+          "Label_Authors",
+          "Label_Type",
+          "Label_Id",
+          "Label_CreatedDateTime",
+          "Label_CreatedBy",
+          "Label_SubTypes",
+        ],
+      },
+      DebugOptions: "Full",
+      Cvid: cryptoUuid(),
+      LogicalId: cryptoUuid(),
+      WholePageRankingOptions: {
+        SupportedRankingVersion: "V3",
+        MultiEntityMerge: [
+          {
+            EntityTypes: ["File", "External", "Email", "Chat", "Event"],
+            MergeInline: true,
+            From: from,
+            Size: size,
+          },
+        ],
+        EnableEnrichedRanking: true,
+        EnableLayoutHints: true,
+        SupportedSerpRegions: ["ContextRegion"],
+        EntityResultTypeRankingOptions: [
+          {
+            ResultType: "Answer",
+            MaxEntitySetCount: 6,
+          },
+        ],
+      },
+      QueryAlterationOptions: {
+        EnableSuggestion: true,
+        EnableAlteration: true,
+        SupportedRecourseDisplayTypes: [
+          "Suggestion",
+          "Modification",
+          "NoRequeryModification",
+          "ServiceSideRecourseLink",
+        ],
+      },
+      AggregationRequests: buildAggregationRequests(source, connector),
+      TimeZone: tz.timeZone,
+      TimeZoneOffsetInMinutes: tz.offset,
+    };
+
+    const headers = buildSearchHeaders(tokenEntry);
+
+    const response = await fetch(SEARCH_ENDPOINT, {
+      method: "POST",
+      headers,
+      body: JSON.stringify(body),
+    });
+
+    if (!response.ok) {
+      const text = await response.text();
+      const err = new Error(
+        `Substrate search failed (${response.status}): ${text.slice(0, 500)}`,
+      );
+      err.status = response.status;
+
+      // When the server rejects the token, evict it so the UI shows the real
+      // state ("Missing" instead of "Valid") and notify the caller for auto-refresh.
+      if (response.status === 401) {
+        await this.tokenManager.evictToken(
+          TOKEN_AUDIENCES.SUBSTRATE,
+          tokenEntry.token,
+        );
+        if (this.onAuthError) {
+          try {
+            await this.onAuthError();
+          } catch (_e) {
+            // Best-effort; preserve the original search failure.
+          }
+        }
+      }
+
+      throw err;
+    }
+
+    const payload = await response.json();
+    return this.normalizeSearchResponse(payload, from, size);
+  }
+
+  normalizeSearchResponse(payload, from, size) {
+    const groups = Array.isArray(payload?.ResultSetGroups)
+      ? payload.ResultSetGroups
+      : [];
+    const results = [];
+
+    let totalEstimatedMatches = 0;
+    let moreAvailable = false;
+
+    for (const group of groups) {
+      const resultSets = Array.isArray(group?.ResultSets)
+        ? group.ResultSets
+        : [];
+      const entityType = Array.isArray(group?.Types)
+        ? group.Types[0]
+        : resultSets[0]?.Types?.[0];
+
+      for (const set of resultSets) {
+        totalEstimatedMatches += Number(set?.TotalEstimatedMatches || 0);
+        moreAvailable = moreAvailable || Boolean(set?.MoreResultsAvailable);
+
+        const rawResults = Array.isArray(set?.Results) ? set.Results : [];
+        for (const raw of rawResults) {
+          const normalized = normalizeResult(raw, entityType, results.length);
+          if (normalized) {
+            results.push(normalized);
+          }
+        }
+      }
+    }
+
+    return {
+      results,
+      totalEstimatedMatches,
+      moreAvailable,
+      nextFrom: from + Math.max(size, results.length),
+      warnings: [],
+    };
+  }
+}
+
+export const _testable = {
+  stripTags,
+  normalizeResult,
+  ownerIdentity,
+  safeEmailAddress,
+};