feat: Add Identity.search for IDSync Search

snippet.js

@@ -44,7 +44,7 @@
         'stopTrackingLocation',
     ];
     var ecommerceMethods = ['setCurrencyCode', 'logCheckout'];
-    var identityMethods = ['identify', 'login', 'logout', 'modify'];
+    var identityMethods = ['identify', 'login', 'logout', 'modify', 'search'];
     var roktMethods = [
         'selectPlacements',
         'hashAttributes',

snippet.rokt.js

@@ -44,7 +44,7 @@
         'stopTrackingLocation',
     ];
     var ecommerceMethods = ['setCurrencyCode', 'logCheckout'];
-    var identityMethods = ['identify', 'login', 'logout', 'modify'];
+    var identityMethods = ['identify', 'login', 'logout', 'modify', 'search'];
     var roktMethods = [
         'selectPlacements',
         'hashAttributes',

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,16 @@ import {
     IMParticleUser,
 } from './identity-user-interfaces';
 import { IStore } from './store';
+import type { IMParticleWebSDKInstance } from './mp-instance';
+import {
+    IIdentitySearchKnownIdentities,
+    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>>;
@@ -321,3 +329,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: IIdentitySearchKnownIdentities,
+    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,
+    );
+};

src/identity.interfaces.ts

@@ -12,6 +12,10 @@ import {
     mParticleUserCart,
     IIdentityResponse,
 } from './identity-user-interfaces';
+import {
+    IIdentitySearchKnownIdentities,
+    IdentitySearchCallback,
+} from './identity/search';
 const { platform, sdkVendor, sdkVersion, HTTPCodes } = Constants;
 
 export type IdentityPreProcessResult = {
@@ -156,8 +160,31 @@ export interface SDKIdentityApi {
         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: IIdentitySearchKnownIdentities,
+        callback: IdentitySearchCallback
+    ): void;
 }
 
+export type {
+    IIdentitySearchKnownIdentities,
+    IIdentitySearchResult,
+    IIdentitySearchResponseBody,
+    IdentitySearchCallback,
+} from './identity/search';
+
 export interface IIdentity {
     audienceManager: AudienceManager;
     idCache: BaseVault<Dictionary<ICachedIdentityCall>>;

src/identity.js

@@ -1,8 +1,9 @@
 import Constants, { HTTP_OK } from './constants';
 import Types, { IdentityType } from './types';
 import {
     cacheOrClearIdCache,
     createKnownIdentities,
+    executeSearchRequest,
     tryCacheIdentity,
 } from './identity-utils';
 import AudienceManager from './audienceManager';
@@ -730,6 +731,32 @@
             }
         },
 
+        /**
+         * Search the IDSync Workspace endpoint for a known identity.
+         *
+         * POSTs to mParticle's `/v1/search` endpoint and invokes `callback`
+         * with `{ httpCode, body? }`.
+         *
+         * The `workspaceApiKey` is a workspace-specific API key supplied by
+         * the caller (passed in from a kit's settings). It is intentionally
+         * NOT read from the SDK's own workspace token, so that workspace
+         * searches can be authorised independently of the host SDK's
+         * workspace.
+         *
+         * @method search
+         * @param {String} workspaceApiKey Workspace API key (sent as x-mp-key).
+         * @param {Object} knownIdentities `{ email: string }`
+         * @param {Function} callback Invoked with the `IIdentitySearchResult`.
+         */
+        search: function(workspaceApiKey, knownIdentities, callback) {
+            executeSearchRequest(
+                mpInstance,
+                workspaceApiKey,
+                knownIdentities,
+                callback
+            );
+        },
+
         /**
          Create a default AliasRequest for 2 MParticleUsers. This will construct the request
         using the sourceUser's firstSeenTime as the startTime, and its lastSeenTime as the endTime.