@mparticle/web-sdk 2.66.0 → 2.68.0

package/dist/types/src/identity/search.d.ts

@@ -0,0 +1,64 @@
+import { SDKLoggerApi } from '../sdkRuntimeModels';
+import { Environment } from '../utils';
+import { AsyncUploader } from '../uploaders';
+import { IErrorReportingService } from '../reporting/types';
+import { UserIdentities } from '@mparticle/web-sdk';
+/**
+ * Body payload returned by the `/v1/search` endpoint, as parsed JSON.
+ *
+ * The shape mirrors `/v1/identify` responses. All fields are optional because
+ * non-200 responses (e.g. 404 NOT_FOUND_ERROR) may include partial or
+ * error-shaped bodies, and the consumer should only rely on body fields when
+ * `httpCode === 200`.
+ */
+export interface IIdentitySearchResponseBody {
+    context?: string | null;
+    mpid?: string;
+    matched_identities?: Record<string, string>;
+    is_ephemeral?: boolean;
+    is_logged_in?: boolean;
+}
+/**
+ * Result delivered to the consumer's callback. `httpCode` is always present;
+ * `body` is present whenever the response had a parseable JSON body.
+ *
+ * For non-network errors (missing API key, validation failures, JSON parse
+ * errors) `httpCode` will be `HTTPCodes.noHttpCoverage` (-1) and `body` will
+ * be omitted. The consumer is expected to gate behaviour on
+ * `httpCode === 200`.
+ */
+export interface IIdentitySearchResult {
+    httpCode: number;
+    body?: IIdentitySearchResponseBody;
+}
+export type IdentitySearchCallback = (result: IIdentitySearchResult) => void;
+/**
+ * Body posted to `/v1/search`. Mirrors the `/v1/identify` request envelope so
+ * that the IDSync service can correlate requests across endpoints.
+ */
+export interface IIdentitySearchRequestBody {
+    client_sdk: {
+        platform: string;
+        sdk_vendor: string;
+        sdk_version: string;
+    };
+    environment: Environment;
+    request_id: string;
+    request_timestamp_ms: number;
+    known_identities: UserIdentities;
+}
+/**
+ * Sends a POST to mParticle's IDSync Search endpoint and invokes `callback`
+ * with the HTTP status and parsed body.
+ *
+ * Defensive contract:
+ *  - No identifier with a non-empty string value -> callback with
+ *    `{ httpCode: noHttpCoverage }`, no network call.
+ *  - Missing `apiKey` -> callback with `{ httpCode: noHttpCoverage }`,
+ *    no network call.
+ *  - Network/JSON-parse errors are caught and surfaced via the callback,
+ *    never thrown. Network errors are also reported through the optional
+ *    `errorReporter` so any registered IErrorReportingService can observe
+ *    them (matches the pattern used by identifyRequest in identityApiClient).
+ */
+export declare const sendSearchRequest: (knownIdentities: UserIdentities, apiKey: string, requestBuilder: () => Omit<IIdentitySearchRequestBody, 'known_identities'>, searchUrl: string, callback: IdentitySearchCallback, logger: SDKLoggerApi, uploader?: AsyncUploader, errorReporter?: IErrorReportingService) => Promise<void>;

package/dist/types/src/identity-utils.d.ts

@@ -1,9 +1,11 @@
-import { Dictionary } from './utils';
+import { Dictionary, Environment } from './utils';
 import { BaseVault } from './vault';
 import { IdentityApiData, UserIdentities, IdentityCallback } from '@mparticle/web-sdk';
 import { IdentityAPIMethod } from './identity.interfaces';
 import { IIdentityResponse, IMParticleUser } from './identity-user-interfaces';
 import { IStore } from './store';
+import type { IMParticleWebSDKInstance } from './mp-instance';
+import { IIdentitySearchRequestBody, IdentitySearchCallback } from './identity/search';
 export declare const CACHE_HEADER: "x-mp-max-age";
 export type IdentityCache = BaseVault<Dictionary<ICachedIdentityCall>>;
 export type IParseCachedIdentityResponse = (cachedIdentity: IIdentityResponse, mpid: string, callback: IdentityCallback, identityApiData: IdentityApiData, identityMethod: string, knownIdentities: IKnownIdentities, fromCachedIdentity: boolean) => void;
@@ -23,6 +25,9 @@ export declare const getCachedIdentity: (method: IdentityAPIMethod, proposedUser
 export declare const createKnownIdentities: (identityApiData: IdentityApiData, deviceId: string) => IKnownIdentities;
 export declare const removeExpiredIdentityCacheDates: (idCache: BaseVault<Dictionary<ICachedIdentityCall>>) => void;
 export declare const tryCacheIdentity: (knownIdentities: IKnownIdentities, idCache: IdentityCache, parseIdentityResponse: IParseCachedIdentityResponse, mpid: string, callback: IdentityCallback, identityApiData: IdentityApiData, identityMethod: IdentityAPIMethod) => boolean;
+type Sha256IdentityAlias = 'email_sha256' | 'mobile_sha256';
+type UserIdentitiesWithAliases = UserIdentities & Partial<Record<Sha256IdentityAlias, string | null>>;
+export declare const normalizeUserIdentityKeys: (userIdentities: UserIdentitiesWithAliases) => UserIdentities;
 export declare const hasIdentityRequestChanged: (currentUser: IMParticleUser, newIdentityRequest: IdentityApiData) => boolean;
 /**
  * Checks if deviceId or other user identifiers (like email) were explicitly provided
@@ -34,3 +39,18 @@ export declare const hasIdentityRequestChanged: (currentUser: IMParticleUser, ne
  * @returns true if deviceId or other identifiers were explicitly provided in config, false otherwise
  */
 export declare const hasExplicitIdentifier: (store: IStore | undefined | null) => boolean;
+/**
+ * Builds the /v1/identify-style envelope (client_sdk, environment,
+ * request_id, request_timestamp_ms) used to correlate IDSync requests
+ * across endpoints. `known_identities` is omitted so the caller can
+ * fold in the search-specific identifiers alongside the envelope.
+ */
+export declare const buildIdentitySearchEnvelope: (environment: Environment) => Omit<IIdentitySearchRequestBody, 'known_identities'>;
+/**
+ * Wires the SDK instance into `sendSearchRequest`: gates on `canLog`,
+ * builds the `/v1/search` URL and request envelope, and dispatches.
+ * Lives here so the SDK glue (URL building, opt-out gate, dispatcher
+ * plumbing) is type-checked instead of being expressed in plain JS.
+ */
+export declare const executeSearchRequest: (mpInstance: IMParticleWebSDKInstance, workspaceApiKey: string, knownIdentities: UserIdentities, callback: IdentitySearchCallback) => void;
+export {};

package/dist/types/src/identity.interfaces.d.ts

@@ -5,6 +5,7 @@ import { BaseVault } from './vault';
 import { Dictionary, Environment, valueof } from './utils';
 import Constants from './constants';
 import { IdentityCallback, IUserAttributeChangeEvent, IUserIdentityChangeEvent, IMParticleUser, mParticleUserCart, IIdentityResponse } from './identity-user-interfaces';
+import { IdentitySearchCallback } from './identity/search';
 declare const platform: "web", sdkVendor: "mparticle", sdkVersion: string, HTTPCodes: {
     readonly noHttpCoverage: -1;
     readonly activeIdentityRequest: -2;
@@ -97,6 +98,42 @@ export interface SDKIdentityApi {
     getUsers?(): IMParticleUser[];
     aliasUsers?(aliasRequest?: IAliasRequest, callback?: IdentityCallback): void;
     createAliasRequest?(sourceUser: IMParticleUser, destinationUser: IMParticleUser, scope?: AliasRequestScope): IAliasRequest;
+    /**
+     * Sends a request to mParticle's IDSync `/v1/search` endpoint to look up
+     * a workspace identity without affecting the current user. The callback
+     * receives `httpCode` (always) and an optional `body` containing the
+     * parsed JSON response. Consumers should gate behaviour on
+     * `httpCode === 200`.
+     *
+     * `workspaceApiKey` is a workspace-specific API key supplied by the
+     * caller (from a kit's settings). It is sent as the `x-mp-key` header.
+     * The SDK's own workspace token is intentionally not used.
+     */
+    search?(workspaceApiKey: string, knownIdentities: UserIdentities, callback: IdentitySearchCallback): void;
+}
+export type { IIdentitySearchResult, IIdentitySearchResponseBody, IdentitySearchCallback, } from './identity/search';
+export interface IUserIdentities {
+    customerid?: string;
+    email?: string;
+    other?: string;
+    other2?: string;
+    other3?: string;
+    other4?: string;
+    other5?: string;
+    other6?: string;
+    other7?: string;
+    other8?: string;
+    other9?: string;
+    other10?: string;
+    mobile_number?: string;
+    phone_number_2?: string;
+    phone_number_3?: string;
+    facebook?: string;
+    facebookcustomaudienceid?: string;
+    google?: string;
+    twitter?: string;
+    microsoft?: string;
+    yahoo?: string;
 }
 export interface IIdentity {
     audienceManager: AudienceManager;
@@ -114,4 +151,3 @@ export interface IIdentity {
      */
     mParticleUserCart(): mParticleUserCart;
 }
-export {};

package/dist/types/src/public-types.d.ts

@@ -16,7 +16,7 @@ export type { Batch, } from '@mparticle/event-models';
 export type { EventType, CommerceEventType, IdentityType, ProductActionType, PromotionActionType, MessageType, } from './types';
 export type { SDKInitConfig, DataPlanConfig, BaseEvent, SDKEventCustomFlags, LogLevelType, MParticleWebSDK, } from './sdkRuntimeModels';
 export type { IMParticleUser, IdentityCallback, IdentityResult, IdentityResultBody, IdentityModifyResultBody, ISDKUserIdentity, ISDKUserAttributes, } from './identity-user-interfaces';
-export type { SDKIdentityApi, IAliasRequest, IAliasCallback, IAliasResult, SDKIdentityTypeEnum, } from './identity.interfaces';
+export type { SDKIdentityApi, IAliasRequest, IAliasCallback, IAliasResult, SDKIdentityTypeEnum, IIdentitySearchResult, IIdentitySearchResponseBody, IdentitySearchCallback, IUserIdentities } from './identity.interfaces';
 export type { SDKECommerceAPI, SDKCart, } from './ecommerce.interfaces';
 export type { SDKProduct, SDKPromotion, SDKImpression, SDKProductImpression, } from './sdkRuntimeModels';
 export type { SDKConsentApi, SDKConsentState, SDKConsentStateData, SDKGDPRConsentState, SDKCCPAConsentState, } from './consent';

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

@@ -118,9 +118,9 @@ export interface SDKProductAction {
     TaxAmount?: number;
 }
 export interface SDKProduct {
-    Sku?: string;
-    Name?: string;
-    Price?: number;
+    Sku: string;
+    Name: string;
+    Price: number;
     Quantity?: number;
     Brand?: string;
     Variant?: string;
@@ -128,7 +128,7 @@ export interface SDKProduct {
     Position?: number;
     CouponCode?: string;
     TotalAmount?: number;
-    Attributes?: Record<string, unknown> | null;
+    Attributes?: Record<string, unknown>;
 }
 export interface MParticleWebSDK {
     addForwarder(forwarder: UnregisteredKit): void;
@@ -203,7 +203,7 @@ export declare const LogLevelType: {
     readonly Warning: "warning";
     readonly Error: "error";
 };
-export interface SDKInitConfig extends Omit<MPConfiguration, 'dataPlan' | 'logLevel'> {
+export interface SDKInitConfig extends Omit<MPConfiguration, 'dataPlan' | 'logLevel' | 'identityCallback'> {
     dataPlan?: DataPlanConfig | KitBlockerDataPlan;
     logLevel?: LogLevelType;
     kitConfigs?: IKitConfigs[];

package/dist/types/src/stub/mparticle.stub.d.ts

@@ -57,6 +57,7 @@ declare namespace mParticle {
         export { voidFunction as login };
         export { voidFunction as logout };
         export { voidFunction as modify };
+        export { voidFunction as search };
     }
 }
 declare function voidFunction(): void;

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@mparticle/web-sdk",
-    "version": "2.66.0",
+    "version": "2.68.0",
     "description": "mParticle core SDK for web applications",
     "license": "Apache-2.0",
     "keywords": [
@@ -118,7 +118,7 @@
         "@types/jest": "^29.5.1",
         "@types/jest-expect-message": "^1.1.0",
         "@types/mocha": "^9.0.0",
-        "@types/mparticle__web-sdk": "^2.16.1",
+        "@types/mparticle__web-sdk": "^2.66.0",
         "@types/node": "^20.1.0",
         "babel-preset-minify": "^0.5.1",
         "browser-sync": "^2.26.3",

package/src/identity/search.ts

@@ -0,0 +1,233 @@
+import Constants, { HTTP_OK, HTTP_NOT_FOUND } from '../constants';
+import { SDKLoggerApi } from '../sdkRuntimeModels';
+import { Environment, isFunction } from '../utils';
+import {
+    AsyncUploader,
+    FetchUploader,
+    IFetchPayload,
+    XHRUploader,
+} from '../uploaders';
+import {
+    ErrorCodes,
+    IErrorReportingService,
+    WSDKErrorSeverity,
+} from '../reporting/types';
+import { IdentityApiData, UserIdentities } from '@mparticle/web-sdk';
+import Validators from '../validators';
+
+const { HTTPCodes } = Constants;
+
+/**
+ * Body payload returned by the `/v1/search` endpoint, as parsed JSON.
+ *
+ * The shape mirrors `/v1/identify` responses. All fields are optional because
+ * non-200 responses (e.g. 404 NOT_FOUND_ERROR) may include partial or
+ * error-shaped bodies, and the consumer should only rely on body fields when
+ * `httpCode === 200`.
+ */
+export interface IIdentitySearchResponseBody {
+    context?: string | null;
+    mpid?: string;
+    matched_identities?: Record<string, string>;
+    is_ephemeral?: boolean;
+    is_logged_in?: boolean;
+}
+
+/**
+ * Result delivered to the consumer's callback. `httpCode` is always present;
+ * `body` is present whenever the response had a parseable JSON body.
+ *
+ * For non-network errors (missing API key, validation failures, JSON parse
+ * errors) `httpCode` will be `HTTPCodes.noHttpCoverage` (-1) and `body` will
+ * be omitted. The consumer is expected to gate behaviour on
+ * `httpCode === 200`.
+ */
+export interface IIdentitySearchResult {
+    httpCode: number;
+    body?: IIdentitySearchResponseBody;
+}
+
+export type IdentitySearchCallback = (result: IIdentitySearchResult) => void;
+
+/**
+ * Body posted to `/v1/search`. Mirrors the `/v1/identify` request envelope so
+ * that the IDSync service can correlate requests across endpoints.
+ */
+export interface IIdentitySearchRequestBody {
+    client_sdk: {
+        platform: string;
+        sdk_vendor: string;
+        sdk_version: string;
+    };
+    environment: Environment;
+    request_id: string;
+    request_timestamp_ms: number;
+    known_identities: UserIdentities;
+}
+
+interface IIdentitySearchPayload extends IFetchPayload {
+    headers: {
+        Accept: string;
+        'Content-Type': string;
+        'x-mp-key': string;
+    };
+}
+
+/**
+ * Sends a POST to mParticle's IDSync Search endpoint and invokes `callback`
+ * with the HTTP status and parsed body.
+ *
+ * Defensive contract:
+ *  - No identifier with a non-empty string value -> callback with
+ *    `{ httpCode: noHttpCoverage }`, no network call.
+ *  - Missing `apiKey` -> callback with `{ httpCode: noHttpCoverage }`,
+ *    no network call.
+ *  - Network/JSON-parse errors are caught and surfaced via the callback,
+ *    never thrown. Network errors are also reported through the optional
+ *    `errorReporter` so any registered IErrorReportingService can observe
+ *    them (matches the pattern used by identifyRequest in identityApiClient).
+ */
+export const sendSearchRequest = async (
+    knownIdentities: UserIdentities,
+    apiKey: string,
+    requestBuilder: () => Omit<IIdentitySearchRequestBody, 'known_identities'>,
+    searchUrl: string,
+    callback: IdentitySearchCallback,
+    logger: SDKLoggerApi,
+    uploader?: AsyncUploader,
+    errorReporter?: IErrorReportingService,
+): Promise<void> => {
+    // Validate the callback up front. If it isn't a function we have nowhere
+    // to deliver a result to, so log and bail out without invoking anything.
+    if (!isFunction(callback)) {
+        logger.error(
+            'search called without a callback function; skipping request.',
+        );
+        return;
+    }
+
+    const safeInvoke = (result: IIdentitySearchResult): void => {
+        try {
+            callback(result);
+        } catch (e) {
+            logger.error(
+                'Error invoking search callback: ' +
+                    ((e as Error)?.message || String(e)),
+            );
+        }
+    };
+
+    const cleanedKnownIdentities: UserIdentities = Validators.removeFalsyIdentityValues(
+        { userIdentities: knownIdentities ?? {} } as IdentityApiData,
+        logger,
+    ).userIdentities;
+
+    // No usable identifier -> deliver httpCode: noHttpCoverage so callers
+    // waiting on the callback (e.g. to clear a loading state) don't hang.
+    if (
+        !Object.values(cleanedKnownIdentities ?? {}).some(
+            (v) => typeof v === 'string' && v.length > 0,
+        )
+    ) {
+        logger.verbose(
+            'Identity search called with empty identifiers; skipping request.',
+        );
+        safeInvoke({ httpCode: HTTPCodes.noHttpCoverage });
+        return;
+    }
+
+    // No API key -> same: deliver noHttpCoverage rather than hanging.
+    if (!apiKey) {
+        logger.verbose(
+            'search called without a workspace API key; skipping request.',
+        );
+        safeInvoke({ httpCode: HTTPCodes.noHttpCoverage });
+        return;
+    }
+
+    // Wrap request setup AND the network call in the try/catch so any throw
+    // — from requestBuilder, JSON.stringify (e.g. circular refs), or
+    // uploader construction — flows into the catch below and the consumer's
+    // callback fires with noHttpCoverage rather than the async function
+    // rejecting and the caller hanging on a never-fired callback.
+    try {
+        const requestEnvelope = requestBuilder();
+
+        const requestBody: IIdentitySearchRequestBody = {
+            ...requestEnvelope,
+            known_identities: { ...cleanedKnownIdentities },
+        };
+
+        const fetchPayload: IIdentitySearchPayload = {
+            method: 'post',
+            headers: {
+                Accept: 'application/json',
+                'Content-Type': 'application/json',
+                'x-mp-key': apiKey,
+            },
+            body: JSON.stringify(requestBody),
+        };
+
+        const api: AsyncUploader =
+            uploader ||
+            (window.fetch
+                ? new FetchUploader(searchUrl)
+                : new XHRUploader(searchUrl));
+
+        logger.verbose('Sending search request to ' + searchUrl);
+        const response: Response = await api.upload(fetchPayload, searchUrl);
+
+        let body: IIdentitySearchResponseBody | undefined;
+
+        // FetchUploader returns a real Response with .json(); XHRUploader
+        // returns an XHR-shaped object with `responseText`. We tolerate both.
+        if (isFunction(response.json)) {
+            try {
+                body = (await response.json()) as IIdentitySearchResponseBody;
+            } catch (e) {
+                logger.verbose(
+                    'search response had no parseable JSON body.',
+                );
+            }
+        } else {
+            const xhrLike = (response as unknown) as XMLHttpRequest;
+            if (xhrLike?.responseText) {
+                try {
+                    body = JSON.parse(xhrLike.responseText) as IIdentitySearchResponseBody;
+                } catch (e) {
+                    logger.verbose(
+                        'search XHR response was not valid JSON.',
+                    );
+                }
+            }
+        }
+
+        if (response.status === HTTP_OK) {
+            logger.verbose('search received 200 OK.');
+        } else if (response.status === HTTP_NOT_FOUND) {
+            // 404 NOT_FOUND_ERROR is an expected steady-state outcome and is
+            // intentionally not logged as an error.
+            logger.verbose('search received 404 (no match).');
+        } else {
+            logger.verbose(
+                'search received non-success status ' + response.status,
+            );
+        }
+
+        safeInvoke({ httpCode: response.status, body });
+    } catch (e) {
+        const message = (e as Error)?.message || String(e);
+        const reportMessage = 'Error sending search request: ' + message;
+        logger.error(reportMessage);
+        // Mirror the identity-route pattern in identityApiClient.ts: log to
+        // console AND push a structured report through the dispatcher so any
+        // registered IErrorReportingService (e.g. the Rokt kit's) can observe
+        // the failure.
+        errorReporter?.report({
+            message: reportMessage,
+            code: ErrorCodes.IDENTITY_REQUEST,
+            severity: WSDKErrorSeverity.ERROR,
+        });
+        safeInvoke({ httpCode: HTTPCodes.noHttpCoverage });
+    }
+};

package/src/identity-utils.ts

@@ -1,5 +1,5 @@
 import Constants, { ONE_DAY_IN_SECONDS, MILLIS_IN_ONE_SEC } from './constants';
-import { Dictionary, parseNumber, isObject, generateHash, isEmpty } from './utils';
+import { Dictionary, Environment, parseNumber, isObject, generateHash, generateUniqueId, isEmpty, isFunction } from './utils';
 import { BaseVault } from './vault';
 import Types from './types';
 import {
@@ -14,8 +14,15 @@ import {
     IMParticleUser,
 } from './identity-user-interfaces';
 import { IStore } from './store';
+import type { IMParticleWebSDKInstance } from './mp-instance';
+import {
+    IIdentitySearchRequestBody,
+    IdentitySearchCallback,
+    sendSearchRequest,
+} from './identity/search';
 
 const { Identify, Modify, Login, Logout } = Constants.IdentityMethods;
+const { HTTPCodes, Messages } = Constants;
 export const CACHE_HEADER = 'x-mp-max-age' as const;
 
 export type IdentityCache = BaseVault<Dictionary<ICachedIdentityCall>>;
@@ -282,6 +289,48 @@ const getExpireTimestamp = (maxAge: number = ONE_DAY_IN_SECONDS): number =>
 const parseIdentityResponse = (responseText: string): IdentityResultBody =>
     responseText ? JSON.parse(responseText) : ({} as IdentityResultBody);
 
+type Sha256IdentityAlias = 'email_sha256' | 'mobile_sha256';
+
+const SHA256_IDENTITY_ALIASES: Readonly<
+    Record<Sha256IdentityAlias, keyof UserIdentities>
+> = {
+    email_sha256: 'other',
+    mobile_sha256: 'other2',
+};
+
+type UserIdentitiesWithAliases = UserIdentities &
+    Partial<Record<Sha256IdentityAlias, string | null>>;
+
+export const normalizeUserIdentityKeys = (
+    userIdentities: UserIdentitiesWithAliases
+): UserIdentities => {
+    const normalized: UserIdentitiesWithAliases = { ...userIdentities };
+    (Object.keys(SHA256_IDENTITY_ALIASES) as Sha256IdentityAlias[]).forEach(
+        (alias) => {
+            if (alias in normalized) {
+                const value = normalized[alias];
+                delete normalized[alias];
+                normalized[SHA256_IDENTITY_ALIASES[alias]] = value;
+            }
+        }
+    );
+    return normalized;
+};
+
+// Compare two identity objects by key and value, independent of
+// object key insertion order. The two sides come from different sources
+// (numeric IdentityType iteration vs. partner-provided / alias-normalized
+// order)
+const identitiesEqual = (
+    a?: UserIdentities,
+    b?: UserIdentities
+): boolean => {
+    const aKeys = Object.keys(a ?? {});
+    const bKeys = Object.keys(b ?? {});
+    if (aKeys.length !== bKeys.length) return false;
+    return aKeys.every((key) => a[key] === b[key]);
+};
+
 export const hasIdentityRequestChanged = (
     currentUser: IMParticleUser,
     newIdentityRequest: IdentityApiData
@@ -293,11 +342,11 @@ export const hasIdentityRequestChanged = (
     const currentUserIdentities =
         currentUser.getUserIdentities().userIdentities;
 
-    const newIdentities = newIdentityRequest.userIdentities;
-
-    return (
-        JSON.stringify(currentUserIdentities) !== JSON.stringify(newIdentities)
+    const newIdentities = normalizeUserIdentityKeys(
+        newIdentityRequest.userIdentities
     );
+
+    return !identitiesEqual(currentUserIdentities, newIdentities);
 };
 
 /**
@@ -321,3 +370,76 @@ export const hasExplicitIdentifier = (store: IStore | undefined | null): boolean
     }
     return !!store?.SDKConfig?.deviceId;
 };
+
+/**
+ * Builds the /v1/identify-style envelope (client_sdk, environment,
+ * request_id, request_timestamp_ms) used to correlate IDSync requests
+ * across endpoints. `known_identities` is omitted so the caller can
+ * fold in the search-specific identifiers alongside the envelope.
+ */
+export const buildIdentitySearchEnvelope = (
+    environment: Environment,
+): Omit<IIdentitySearchRequestBody, 'known_identities'> => ({
+    client_sdk: {
+        platform: Constants.platform,
+        sdk_vendor: Constants.sdkVendor,
+        sdk_version: Constants.sdkVersion,
+    },
+    environment,
+    request_id: generateUniqueId(),
+    request_timestamp_ms: Date.now(),
+});
+
+/**
+ * Wires the SDK instance into `sendSearchRequest`: gates on `canLog`,
+ * builds the `/v1/search` URL and request envelope, and dispatches.
+ * Lives here so the SDK glue (URL building, opt-out gate, dispatcher
+ * plumbing) is type-checked instead of being expressed in plain JS.
+ */
+export const executeSearchRequest = (
+    mpInstance: IMParticleWebSDKInstance,
+    workspaceApiKey: string,
+    knownIdentities: UserIdentities,
+    callback: IdentitySearchCallback,
+): void => {
+    const { _Helpers, _Store, Logger, _ErrorReportingDispatcher } = mpInstance;
+    const { identityUrl, isDevelopmentMode } = _Store.SDKConfig;
+
+    if (!_Helpers.canLog()) {
+        Logger.verbose(Messages.InformationMessages.AbandonLogEvent);
+        if (isFunction(callback)) {
+            try {
+                callback({
+                    httpCode: HTTPCodes.loggingDisabledOrMissingAPIKey,
+                });
+            } catch (e) {
+                Logger.error(
+                    'Error invoking search callback: ' +
+                        ((e as Error)?.message || String(e)),
+                );
+            }
+        }
+        return;
+    }
+
+    // The Search endpoint is colocated with /v1/identify under
+    // identityUrl, so we reuse the same service URL builder. We do
+    // NOT append the apiKey to the URL — auth is done via x-mp-key.
+    const serviceUrl: string = _Helpers.createServiceUrl(identityUrl);
+    const searchUrl: string = serviceUrl + 'search?cb=1';
+
+    const environment: Environment = isDevelopmentMode
+        ? 'development'
+        : 'production';
+
+    sendSearchRequest(
+        knownIdentities,
+        workspaceApiKey,
+        () => buildIdentitySearchEnvelope(environment),
+        searchUrl,
+        callback,
+        Logger,
+        undefined,
+        _ErrorReportingDispatcher,
+    );
+};