@mparticle/web-sdk 2.66.0 → 2.67.0

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/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.67.0",
     "description": "mParticle core SDK for web applications",
     "license": "Apache-2.0",
     "keywords": [

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>>;
@@ -321,3 +328,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,
+    );
+};

package/src/identity.interfaces.ts

@@ -12,6 +12,7 @@ import {
     mParticleUserCart,
     IIdentityResponse,
 } from './identity-user-interfaces';
+import { IdentitySearchCallback } from './identity/search';
 const { platform, sdkVendor, sdkVersion, HTTPCodes } = Constants;
 
 export type IdentityPreProcessResult = {
@@ -156,8 +157,53 @@ 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: 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;
     idCache: BaseVault<Dictionary<ICachedIdentityCall>>;

package/src/identity.js

@@ -3,6 +3,7 @@ import Types, { IdentityType } from './types';
 import {
     cacheOrClearIdCache,
     createKnownIdentities,
+    executeSearchRequest,
     tryCacheIdentity,
 } from './identity-utils';
 import AudienceManager from './audienceManager';
@@ -730,6 +731,32 @@ export default function Identity(mpInstance) {
             }
         },
 
+        /**
+         * 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 A `UserIdentities` map.
+         * @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.

package/src/mparticle-instance-manager.ts

@@ -394,6 +394,13 @@ function mParticleInstanceManager(this: IMParticleInstanceManager) {
         modify: function(identityApiData, callback) {
             self.getInstance().Identity.modify(identityApiData, callback);
         },
+        search: function(workspaceApiKey, knownIdentities, callback) {
+            self.getInstance().Identity.search(
+                workspaceApiKey,
+                knownIdentities,
+                callback
+            );
+        },
     };
 
     this.sessionManager = {

package/src/public-types.ts

@@ -56,6 +56,10 @@ export type {
     IAliasCallback,
     IAliasResult,
     SDKIdentityTypeEnum,
+    IIdentitySearchResult,
+    IIdentitySearchResponseBody,
+    IdentitySearchCallback,
+    IUserIdentities
 } from './identity.interfaces';
 
 // eCommerce

package/src/stub/mparticle.stub.js

@@ -56,6 +56,7 @@ let mParticle = {
         login: voidFunction,
         logout: voidFunction,
         modify: voidFunction,
+        search: voidFunction,
     },
 };