@constructor-io/constructorio-node 5.9.0 → 5.10.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@constructor-io/constructorio-node",
-  "version": "5.9.0",
+  "version": "5.10.0",
   "description": "Constructor.io Node.js client",
   "main": "src/constructorio.js",
   "types": "src/types/constructorio.d.ts",
@@ -36,6 +36,7 @@
   "devDependencies": {
     "@cspell/eslint-plugin": "^6.8.2",
     "@types/events": "^3.0.0",
+    "@types/node": "^22.19.21",
     "@typescript-eslint/eslint-plugin": "^5.46.1",
     "@typescript-eslint/parser": "^5.46.1",
     "chai": "^4.3.4",

package/src/constructorio.js

@@ -8,6 +8,7 @@ const Autocomplete = require('./modules/autocomplete');
 const Recommendations = require('./modules/recommendations');
 const Tasks = require('./modules/tasks');
 const Quizzes = require('./modules/quizzes');
+const Searchandising = require('./modules/searchandising');
 const { version: packageVersion } = require('../package.json');
 const utils = require('./utils/helpers');
 
@@ -42,6 +43,7 @@ class ConstructorIO {
    * @property {object} catalog - Interface to {@link module:catalog}
    * @property {object} tasks - Interface to {@link module:tasks}
    * @property {object} quizzes - Interface to {@link module:quizzes}
+   * @property {object} searchandising - Interface to {@link module:searchandising}
    * @returns {class}
    */
   constructor(options = {}) {
@@ -83,6 +85,7 @@ class ConstructorIO {
     this.recommendations = new Recommendations(this.options);
     this.tasks = new Tasks(this.options);
     this.quizzes = new Quizzes(this.options);
+    this.searchandising = new Searchandising(this.options);
   }
 }
 

package/src/modules/searchandising/campaigns.js

@@ -0,0 +1,428 @@
+/* eslint-disable max-len */
+/* eslint-disable camelcase, no-underscore-dangle, no-unneeded-ternary, brace-style */
+const qs = require('qs');
+const { AbortController } = require('node-abort-controller');
+const helpers = require('../../utils/helpers');
+
+// Create URL from supplied path and options
+function createCampaignsUrl(path, options, additionalQueryParams = {}, apiVersion = 'v1') {
+  const {
+    apiKey,
+    serviceUrl,
+    version,
+  } = options;
+  let queryParams = {
+    c: version,
+    ...additionalQueryParams,
+  };
+
+  // Validate path is provided
+  if (!path || typeof path !== 'string') {
+    throw new Error('path is a required parameter of type string');
+  }
+
+  queryParams.key = apiKey;
+  queryParams = helpers.cleanParams(queryParams);
+
+  const queryString = qs.stringify(queryParams, { indices: false });
+
+  const encodedPath = path.split('/').map(encodeURIComponent).join('/');
+
+  return `${serviceUrl}/${encodeURIComponent(apiVersion)}/${encodedPath}?${queryString}`;
+}
+
+/**
+ * Interface to searchandising campaign related API calls
+ *
+ * @module searchandising/campaigns
+ * @inner
+ * @returns {object}
+ */
+class Campaigns {
+  constructor(options) {
+    this.options = options || {};
+  }
+
+  /**
+   * Retrieve campaigns
+   *
+   * @function retrieveCampaigns
+   * @param {object} [parameters] - Additional parameters for retrieving campaigns
+   * @param {string} [parameters.section='Products'] - The section of the index to use
+   * @param {number|number[]} [parameters.id] - The ID(s) of campaigns to filter by
+   * @param {string[]} [parameters.refinedQueries] - A list of refined queries to filter by
+   * @param {object} [parameters.refinedFilters] - An object of refined filters to filter by
+   * @param {object} [parameters.refinedRecommendationContexts] - A filter for refined recommendation contexts
+   * @param {number} [parameters.numResultsPerPage=20] - The number of campaigns to return - maximum value 100
+   * @param {number} [parameters.page] - The page of results to return
+   * @param {number} [parameters.offset] - The number of results to skip from the beginning - cannot be used together with `page`
+   * @param {object} [networkParameters] - Parameters relevant to the network request
+   * @param {number} [networkParameters.timeout] - Request timeout (in milliseconds)
+   * @returns {Promise}
+   * @see https://docs.constructor.com/reference/v1-searchandising-retrieve-campaigns
+   * @example
+   * constructorio.searchandising.campaigns.retrieveCampaigns({
+   *     section: 'Products',
+   *     numResultsPerPage: 50,
+   *     page: 1,
+   * });
+   */
+  retrieveCampaigns(parameters = {}, networkParameters = {}) {
+    const queryParams = {};
+    let requestUrl;
+    const { fetch } = this.options;
+    const controller = new AbortController();
+    const { signal } = controller;
+    const headers = {
+      'Content-Type': 'application/json',
+    };
+
+    if (parameters) {
+      const {
+        section,
+        id,
+        refined_filters,
+        refinedFilters = refined_filters,
+        num_results_per_page,
+        numResultsPerPage = num_results_per_page,
+        page,
+        offset,
+        refined_recommendation_contexts,
+        refinedRecommendationContexts = refined_recommendation_contexts,
+        refined_queries,
+        refinedQueries = refined_queries,
+      } = parameters;
+
+      if (section) {
+        queryParams.section = section;
+      }
+
+      if (id) {
+        queryParams.id = id;
+      }
+
+      if (refinedFilters) {
+        queryParams.refined_filters = refinedFilters;
+      }
+
+      if (numResultsPerPage) {
+        queryParams.num_results_per_page = numResultsPerPage;
+      }
+
+      if (page) {
+        queryParams.page = page;
+      }
+
+      if (offset) {
+        queryParams.offset = offset;
+      }
+
+      if (refinedRecommendationContexts) {
+        queryParams.refined_recommendation_contexts = refinedRecommendationContexts;
+      }
+
+      if (refinedQueries) {
+        queryParams.refined_queries = refinedQueries;
+      }
+    }
+
+    try {
+      requestUrl = createCampaignsUrl('campaigns', this.options, queryParams);
+    } catch (e) {
+      return Promise.reject(e);
+    }
+
+    Object.assign(headers, helpers.combineCustomHeaders(this.options, networkParameters));
+
+    helpers.applyNetworkTimeout(this.options, networkParameters, controller);
+
+    return fetch(requestUrl, {
+      method: 'GET',
+      headers: {
+        ...headers,
+        ...helpers.createAuthHeader(this.options),
+      },
+      signal,
+    }).then((response) => {
+      if (response.ok) {
+        return response.json();
+      }
+
+      return helpers.throwHttpErrorFromResponse(new Error(), response);
+    }).then((json) => json);
+  }
+
+  /**
+   * Retrieve a campaign given a specific id
+   *
+   * @function retrieveCampaign
+   * @param {object} parameters - Additional parameters for retrieving a campaign
+   * @param {number} parameters.id - The ID of the campaign to be retrieved
+   * @param {string} [parameters.section='Products'] - The section of the index to use
+   * @param {object} [networkParameters] - Parameters relevant to the network request
+   * @param {number} [networkParameters.timeout] - Request timeout (in milliseconds)
+   * @returns {Promise}
+   * @see https://docs.constructor.com/reference/v1-searchandising-retrieve-campaign
+   * @example
+   * constructorio.searchandising.campaigns.retrieveCampaign({
+   *     id: 42,
+   *     section: 'Products',
+   * });
+   */
+  retrieveCampaign(parameters = {}, networkParameters = {}) {
+    const queryParams = {};
+    let requestUrl;
+    const { fetch } = this.options;
+    const controller = new AbortController();
+    const { signal } = controller;
+    const headers = {
+      'Content-Type': 'application/json',
+    };
+    const { id, section } = parameters;
+
+    if (section) {
+      queryParams.section = section;
+    }
+
+    try {
+      requestUrl = createCampaignsUrl(`campaigns/${id}`, this.options, queryParams);
+    } catch (e) {
+      return Promise.reject(e);
+    }
+
+    Object.assign(headers, helpers.combineCustomHeaders(this.options, networkParameters));
+
+    helpers.applyNetworkTimeout(this.options, networkParameters, controller);
+
+    return fetch(requestUrl, {
+      method: 'GET',
+      headers: {
+        ...headers,
+        ...helpers.createAuthHeader(this.options),
+      },
+      signal,
+    }).then((response) => {
+      if (response.ok) {
+        return response.json();
+      }
+
+      return helpers.throwHttpErrorFromResponse(new Error(), response);
+    }).then((json) => json);
+  }
+
+  /**
+   * Create a campaign
+   *
+   * @function createCampaign
+   * @param {object} parameters - Additional parameters for the campaign to be created
+   * @param {string} parameters.name - The name of the campaign
+   * @param {string} [parameters.section='Products'] - The section of the index to use
+   * @param {string} [parameters.description] - The description of the campaign
+   * @param {string} [parameters.requestTagName] - Request tag name used to activate this campaign for, used only with `request_tag_value`
+   * @param {string} [parameters.requestTagValue] - Request tag value used to activate this campaign for, used only with `request_tag_name`
+   * @param {string} [parameters.startTime] - The start time of the campaign (ISO 8601 date-time)
+   * @param {string} [parameters.endTime] - The end time of the campaign (ISO 8601 date-time)
+   * @param {object[]} [parameters.refinedQueries] - A list of refined queries
+   * @param {object[]} [parameters.refinedFilters] - A list of refined filters
+   * @param {object[]} [parameters.refinedRecommendationContexts] - A list of refined recommendation contexts
+   * @param {object[]} [parameters.boostRules] - A list of boost rules
+   * @param {object[]} [parameters.blacklistRules] - A list of blacklist rules
+   * @param {object[]} [parameters.slotRules] - A list of slot rules
+   * @param {object[]} [parameters.contentRules] - A list of content rules
+   * @param {object[]} [parameters.filtersSlotRules] - A list of filters slot rules
+   * @param {object} [parameters.whitelistRule] - A whitelist rule
+   * @param {object} [parameters.variationSlicingRule] - A variation slicing rule
+   * @param {object} [parameters.metadataJson] - Metadata related to the campaign
+   * @param {object} [networkParameters] - Parameters relevant to the network request
+   * @param {number} [networkParameters.timeout] - Request timeout (in milliseconds)
+   * @returns {Promise}
+   * @see https://docs.constructor.com/reference/v1-searchandising-create-campaign
+   * @example
+   * constructorio.searchandising.campaigns.createCampaign({
+   *     name: 'Spring Sale',
+   *     section: 'Products',
+   *     description: 'Seasonal promotion campaign',
+   *     boostRules: [
+   *         { rule_type: 'boost', rule: { boost: 5, filters: { brand: ['Nike'] } } },
+   *     ],
+   * });
+   */
+  createCampaign(parameters = {}, networkParameters = {}) {
+    const queryParams = {};
+    let requestUrl;
+    const { fetch } = this.options;
+    const controller = new AbortController();
+    const { signal } = controller;
+    const headers = {
+      'Content-Type': 'application/json',
+    };
+    const { section, ...body } = parameters;
+
+    if (section) {
+      queryParams.section = section;
+    }
+
+    try {
+      requestUrl = createCampaignsUrl('campaigns', this.options, queryParams);
+    } catch (e) {
+      return Promise.reject(e);
+    }
+
+    Object.assign(headers, helpers.combineCustomHeaders(this.options, networkParameters));
+
+    helpers.applyNetworkTimeout(this.options, networkParameters, controller);
+
+    return fetch(requestUrl, {
+      method: 'POST',
+      body: JSON.stringify(helpers.toSnakeCaseKeys(body, false)),
+      headers: {
+        ...headers,
+        ...helpers.createAuthHeader(this.options),
+      },
+      signal,
+    }).then((response) => {
+      if (response.ok) {
+        return response.json();
+      }
+
+      return helpers.throwHttpErrorFromResponse(new Error(), response);
+    }).then((json) => json);
+  }
+
+  /**
+   * Update a campaign - only the fields present in the request will be updated
+   *
+   * @function updateCampaign
+   * @param {object} parameters - Additional parameters for the campaign to be updated
+   * @param {number} parameters.id - The ID of the campaign to be updated
+   * @param {string} [parameters.section='Products'] - The section of the index to use
+   * @param {string} [parameters.name] - The name of the campaign
+   * @param {string} [parameters.description] - The description of the campaign
+   * @param {string} [parameters.requestTagName] - Request tag name used to activate this campaign for, used only with `request_tag_value`
+   * @param {string} [parameters.requestTagValue] - Request tag value used to activate this campaign for, used only with `request_tag_name`
+   * @param {string} [parameters.startTime] - The start time of the campaign (ISO 8601 date-time)
+   * @param {string} [parameters.endTime] - The end time of the campaign (ISO 8601 date-time)
+   * @param {object[]} [parameters.refinedQueries] - A list of refined queries
+   * @param {object[]} [parameters.refinedFilters] - A list of refined filters
+   * @param {object[]} [parameters.refinedRecommendationContexts] - A list of refined recommendation contexts
+   * @param {object[]} [parameters.boostRules] - A list of boost rules
+   * @param {object[]} [parameters.blacklistRules] - A list of blacklist rules
+   * @param {object[]} [parameters.slotRules] - A list of slot rules
+   * @param {object[]} [parameters.contentRules] - A list of content rules
+   * @param {object[]} [parameters.filtersSlotRules] - A list of filters slot rules
+   * @param {object} [parameters.whitelistRule] - A whitelist rule
+   * @param {object} [parameters.variationSlicingRule] - A variation slicing rule
+   * @param {object} [parameters.metadataJson] - Metadata related to the campaign
+   * @param {object} [networkParameters] - Parameters relevant to the network request
+   * @param {number} [networkParameters.timeout] - Request timeout (in milliseconds)
+   * @returns {Promise}
+   * @see https://docs.constructor.com/reference/v1-searchandising-update-campaign
+   * @example
+   * constructorio.searchandising.campaigns.updateCampaign({
+   *     id: 42,
+   *     name: 'Spring Sale - Updated',
+   *     description: 'Updated seasonal promotion campaign',
+   * });
+   */
+  updateCampaign(parameters = {}, networkParameters = {}) {
+    const queryParams = {};
+    let requestUrl;
+    const { fetch } = this.options;
+    const controller = new AbortController();
+    const { signal } = controller;
+    const headers = {
+      'Content-Type': 'application/json',
+    };
+    const { id, section, ...body } = parameters;
+
+    if (section) {
+      queryParams.section = section;
+    }
+
+    try {
+      requestUrl = createCampaignsUrl(`campaigns/${id}`, this.options, queryParams);
+    } catch (e) {
+      return Promise.reject(e);
+    }
+
+    Object.assign(headers, helpers.combineCustomHeaders(this.options, networkParameters));
+
+    helpers.applyNetworkTimeout(this.options, networkParameters, controller);
+
+    return fetch(requestUrl, {
+      method: 'PATCH',
+      body: JSON.stringify(helpers.toSnakeCaseKeys(body, false)),
+      headers: {
+        ...headers,
+        ...helpers.createAuthHeader(this.options),
+      },
+      signal,
+    }).then((response) => {
+      if (response.ok) {
+        return response.json();
+      }
+
+      return helpers.throwHttpErrorFromResponse(new Error(), response);
+    }).then((json) => json);
+  }
+
+  /**
+   * Delete a campaign given a specific id
+   *
+   * @function deleteCampaign
+   * @param {object} parameters - Additional parameters for the campaign to be deleted
+   * @param {number} parameters.id - The ID of the campaign to be deleted
+   * @param {string} [parameters.section='Products'] - The section of the index to use
+   * @param {object} [networkParameters] - Parameters relevant to the network request
+   * @param {number} [networkParameters.timeout] - Request timeout (in milliseconds)
+   * @returns {Promise}
+   * @see https://docs.constructor.com/reference/v1-searchandising-delete-campaign
+   * @example
+   * constructorio.searchandising.campaigns.deleteCampaign({
+   *     id: 42,
+   *     section: 'Products',
+   * });
+   */
+  deleteCampaign(parameters = {}, networkParameters = {}) {
+    const queryParams = {};
+    let requestUrl;
+    const { fetch } = this.options;
+    const controller = new AbortController();
+    const { signal } = controller;
+    const headers = {
+      'Content-Type': 'application/json',
+    };
+    const { id, section } = parameters;
+
+    if (section) {
+      queryParams.section = section;
+    }
+
+    try {
+      requestUrl = createCampaignsUrl(`campaigns/${id}`, this.options, queryParams);
+    } catch (e) {
+      return Promise.reject(e);
+    }
+
+    Object.assign(headers, helpers.combineCustomHeaders(this.options, networkParameters));
+
+    helpers.applyNetworkTimeout(this.options, networkParameters, controller);
+
+    return fetch(requestUrl, {
+      method: 'DELETE',
+      headers: {
+        ...headers,
+        ...helpers.createAuthHeader(this.options),
+      },
+      signal,
+    }).then((response) => {
+      if (response.ok) {
+        return Promise.resolve();
+      }
+
+      return helpers.throwHttpErrorFromResponse(new Error(), response);
+    });
+  }
+}
+
+module.exports = Campaigns;

package/src/modules/searchandising/index.js

@@ -0,0 +1,18 @@
+/* eslint-disable max-len */
+const Campaigns = require('./campaigns');
+
+/**
+ * Interface to searchandising related API calls
+ *
+ * @module searchandising
+ * @inner
+ * @returns {object}
+ */
+class Searchandising {
+  constructor(options) {
+    this.options = options || {};
+    this.campaigns = new Campaigns(this.options);
+  }
+}
+
+module.exports = Searchandising;

package/src/types/constructorio.d.ts

@@ -6,6 +6,7 @@ import Tracker from './tracker';
 import Catalog from './catalog';
 import Tasks from './tasks';
 import Quizzes from './quizzes';
+import Searchandising from './searchandising';
 
 import { ConstructorClientOptions } from '.';
 
@@ -31,4 +32,6 @@ declare class ConstructorIO {
   tasks: Tasks;
 
   quizzes: Quizzes;
+
+  searchandising: Searchandising;
 }

package/src/types/index.d.ts

@@ -6,6 +6,7 @@ export * from './recommendations';
 export * from './search';
 export * from './tasks';
 export * from './tracker';
+export * from './searchandising';
 
 export interface NetworkParameters extends Record<string, any> {
   timeout?: number;

package/src/types/searchandising.d.ts

@@ -0,0 +1,306 @@
+import { ConstructorClientOptions, NetworkParameters } from '.';
+
+export default Searchandising;
+
+export interface RetrieveCampaignsParameters {
+  section?: string;
+  id?: number | number[];
+  refinedFilters?: Record<string, string | string[]>;
+  numResultsPerPage?: number;
+  page?: number;
+  offset?: number;
+  refinedRecommendationContexts?: RefinedRecommendationContext;
+  refinedQueries?: string[];
+}
+
+export interface RefinedRecommendationContext {
+  pod_id?: string[];
+  condition_type?: ('attribute' | 'item' | 'expression')[];
+}
+
+export interface RetrieveCampaignParameters {
+  id: number;
+  section?: string;
+}
+
+/* fields shared by create and update campaign requests */
+export interface CampaignParametersBase {
+  section?: string;
+  name?: string;
+  description?: string;
+  requestTagName?: RequestTag;
+  requestTagValue?: string;
+  startTime?: string;
+  endTime?: string;
+  refinedQueries?: RefinedQuery[];
+  refinedFilters?: RefinedFilter[];
+  refinedRecommendationContexts?: RecommendationContext[];
+  boostRules?: CampaignRuleInput[];
+  blacklistRules?: CampaignRuleInput[];
+  slotRules?: CampaignRuleInput[];
+  contentRules?: CampaignRuleInput[];
+  filtersSlotRules?: CampaignRuleInput[];
+  whitelistRule?: CampaignRuleInput | null;
+  variationSlicingRule?: CampaignRuleInput | null;
+  metadataJson?: CampaignMetadata;
+}
+
+export interface CreateCampaignParameters extends CampaignParametersBase {
+  name: string;
+}
+
+export interface UpdateCampaignParameters extends CampaignParametersBase {
+  id: number;
+}
+
+export interface DeleteCampaignParameters {
+  id: number;
+  section?: string;
+}
+
+export interface Campaigns {
+  options: ConstructorClientOptions;
+
+  retrieveCampaigns(
+    parameters?: RetrieveCampaignsParameters,
+    networkParameters?: NetworkParameters
+  ): Promise<CampaignListGetResponse>;
+
+  retrieveCampaign(
+    parameters: RetrieveCampaignParameters,
+    networkParameters?: NetworkParameters
+  ): Promise<CampaignGetResponse>;
+
+  createCampaign(
+    parameters: CreateCampaignParameters,
+    networkParameters?: NetworkParameters
+  ): Promise<CampaignPostResponse>;
+
+  updateCampaign(
+    parameters: UpdateCampaignParameters,
+    networkParameters?: NetworkParameters
+  ): Promise<CampaignPatchResponse>;
+
+  deleteCampaign(
+    parameters: DeleteCampaignParameters,
+    networkParameters?: NetworkParameters
+  ): Promise<void>;
+}
+
+declare class Searchandising {
+  constructor(options: ConstructorClientOptions);
+
+  options: ConstructorClientOptions;
+
+  campaigns: Campaigns;
+}
+
+export type RequestTag =
+  | 'client_ip'
+  | 'client_version'
+  | 'geo_city'
+  | 'geo_country'
+  | 'geo_country_iso_code'
+  | 'geo_region'
+  | 'dt_weekday'
+  | 'dt_timeofday'
+  | 'user_segment'
+  | 'autogenerated_user_segment'
+  | 'dynamic_segment';
+
+export interface RefinedQuery {
+  query: string;
+}
+
+export interface RefinedFilter {
+  filter_name: string;
+  filter_value: string;
+}
+
+export interface RecommendationContext {
+  pod_id: string;
+  condition: RecommendationContextCondition;
+}
+
+export type RecommendationContextCondition =
+  | RecommendationContextItemCondition
+  | RecommendationContextAttributeCondition
+  | RecommendationContextExpressionCondition;
+
+export interface RecommendationContextItemCondition {
+  type: 'item';
+  item_id?: string;
+}
+
+export interface RecommendationContextAttributeCondition {
+  type: 'attribute';
+  filter_name?: string;
+  filter_value?: string;
+}
+
+export interface RecommendationContextExpressionCondition {
+  type: 'expression';
+  expression: Record<string, string[]>;
+}
+
+export type FiltersObj = Record<string, string[]>;
+
+export interface PositionRange {
+  start: number;
+  end: number;
+}
+
+export interface BoostRuleParameters {
+  filters?: FiltersObj;
+  item_ids?: string[];
+  boost: number;
+}
+
+export interface BlacklistRuleParameters {
+  filters?: FiltersObj;
+  item_ids?: string[];
+}
+
+export interface SlotRuleParameters {
+  item_id: string;
+  position: number;
+  variation_slice?: Record<string, string[]>;
+  fuzzy_match?: boolean;
+  labels?: Record<string, any>;
+}
+
+export interface ContentRuleParameters {
+  data: Record<string, any>;
+}
+
+export interface FiltersSlotRuleParameters {
+  position_ranges: PositionRange[];
+  filters?: FiltersObj;
+  filter_expression?: Record<string, any> | string;
+  labels?: Record<string, any>;
+}
+
+export interface WhitelistRuleParameters {
+  filters: FiltersObj;
+}
+
+export interface VariationSlicingRuleParameters {
+  facet_names: string[];
+  filter_expression?: Record<string, any> | string;
+}
+
+/* shared fields present on every campaign rule */
+export interface RuleObjBase {
+  id: number;
+  request_tag_name?: RequestTag;
+  request_tag_value?: string;
+  active?: boolean;
+  start_time?: string;
+  end_time?: string;
+  campaign_id?: number;
+  automatically_generated?: boolean;
+  created_at?: string;
+  updated_at?: string;
+}
+
+export interface BoostRule extends RuleObjBase {
+  rule_type: 'boost';
+  rule: BoostRuleParameters;
+}
+
+export interface BlacklistRule extends RuleObjBase {
+  rule_type: 'blacklist';
+  rule: BlacklistRuleParameters;
+}
+
+export interface SlotRule extends RuleObjBase {
+  rule_type: 'slot';
+  rule: SlotRuleParameters;
+  request_filters?: Record<string, string[]>;
+}
+
+export interface ContentRule extends RuleObjBase {
+  rule_type: 'content';
+  rule: ContentRuleParameters;
+}
+
+export interface FiltersSlotRule extends RuleObjBase {
+  rule_type: 'filters_slot';
+  rule: FiltersSlotRuleParameters;
+}
+
+export interface WhitelistRule extends RuleObjBase {
+  rule_type: 'whitelist';
+  rule: WhitelistRuleParameters;
+}
+
+export interface VariationSlicingRule extends RuleObjBase {
+  rule_type: 'variation_slicing';
+  rule: VariationSlicingRuleParameters;
+}
+
+export type RuleObj =
+  | BoostRule
+  | BlacklistRule
+  | SlotRule
+  | ContentRule
+  | FiltersSlotRule
+  | WhitelistRule
+  | VariationSlicingRule;
+
+/*
+ * Omit the server-assigned fields from each rule.
+ * `Omit` does not distribute over unions - applied directly to RuleObj it would merge
+ * all members into one object and decouple rule_type from rule. The `T extends unknown`
+ * conditional forces distribution so each member is omitted individually and the
+ * rule_type/rule discrimination is preserved.
+ */
+type OmitServerFields<T> = T extends unknown
+  ? Omit<T, 'id' | 'created_at' | 'updated_at'>
+  : never;
+
+/* rule definition supplied when creating or modifying a campaign - server-assigned fields are omitted */
+export type CampaignRuleInput = OmitServerFields<RuleObj>;
+
+export interface CampaignMetadata {
+  goal?: string;
+  goal_description?: string;
+}
+
+export interface Campaign extends Record<string, any> {
+  id: number;
+  created_at: string;
+  updated_at: string;
+  name?: string;
+  description?: string;
+  request_tag_name?: RequestTag;
+  request_tag_value?: string;
+  start_time?: string;
+  end_time?: string;
+  refined_queries?: RefinedQuery[];
+  refined_filters?: RefinedFilter[];
+  refined_recommendation_contexts?: RecommendationContext[];
+  boost_rules?: BoostRule[];
+  blacklist_rules?: BlacklistRule[];
+  slot_rules?: SlotRule[];
+  content_rules?: ContentRule[];
+  filters_slot_rules?: FiltersSlotRule[];
+  whitelist_rule?: WhitelistRule;
+  variation_slicing_rule?: VariationSlicingRule;
+  metadata_json?: CampaignMetadata;
+}
+
+/* campaigns results returned from server */
+export interface CampaignListGetResponse {
+  campaigns: Campaign[];
+  total_count: number;
+}
+
+/* single campaign result returned from server */
+export type CampaignGetResponse = Campaign;
+
+/* campaign result returned from server after creation */
+export type CampaignPostResponse = Campaign;
+
+/* campaign result returned from server after update */
+export type CampaignPatchResponse = Campaign;

package/src/types/tests/searchandising.test-d.ts

@@ -0,0 +1,60 @@
+import { expectAssignable } from 'tsd';
+import {
+  CampaignListGetResponse,
+  Campaign,
+  RetrieveCampaignsParameters,
+  CreateCampaignParameters,
+} from '../searchandising';
+
+expectAssignable<RetrieveCampaignsParameters>({
+  section: 'Products',
+  id: [1, 2],
+  refinedFilters: { group_id: ['123', '456'] },
+  numResultsPerPage: 50,
+  page: 1,
+  refinedRecommendationContexts: {
+    pod_id: ['pod-a'],
+    condition_type: ['item'],
+  },
+  refinedQueries: ['shoes', 'boots'],
+});
+
+expectAssignable<CreateCampaignParameters>({
+  name: 'Spring Sale',
+  section: 'Products',
+  description: 'Seasonal promotion campaign',
+  refinedQueries: [{ query: 'shoes' }],
+  boostRules: [
+    {
+      rule_type: 'boost',
+      rule: { boost: 5, filters: { brand: ['Nike'] } },
+    },
+  ],
+});
+
+expectAssignable<Campaign>({
+  id: 42,
+  created_at: '2026-01-01T00:00:00Z',
+  updated_at: '2026-01-02T00:00:00Z',
+  name: 'Spring Sale',
+  refined_queries: [{ query: 'shoes' }],
+  boost_rules: [
+    {
+      id: 1,
+      rule_type: 'boost',
+      rule: { boost: 5, filters: { brand: ['Nike'] } },
+    },
+  ],
+});
+
+expectAssignable<CampaignListGetResponse>({
+  campaigns: [
+    {
+      id: 42,
+      created_at: '2026-01-01T00:00:00Z',
+      updated_at: '2026-01-02T00:00:00Z',
+      name: 'Spring Sale',
+    },
+  ],
+  total_count: 1,
+});