@foxtware/mineral 0.1.27 → 0.1.28

package/api/tagalys/tagalys.utils.js

@@ -0,0 +1,125 @@
+// https://tagalys.notion.site/Storefront-API-v2-20eacdd38c2080d58d3fd0cf6f24e435
+
+const { resolveCreds } = require('../pipelineSteps');
+const {
+  FetchClient,
+  fetchClientCommonSteps,
+} = require('../utils');
+
+// Recursively flattens nested params into Rails/PHP-style bracket query
+// params, e.g. { filter: { color: ['red'] } } -> filter[color][]=red
+// and { filter: { price: { selected_min: 100 } } } -> filter[price][selected_min]=100
+// This also covers the search_suggestions `sections[section_id][*]` shape,
+// e.g. { sections: { products: { count: 6 } } } -> sections[products][count]=6
+const appendParams = (searchParams, key, value) => {
+  if (value === undefined || value === null) {
+    return;
+  }
+  if (Array.isArray(value)) {
+    value.forEach((item) => appendParams(searchParams, `${ key }[]`, item));
+  } else if (typeof value === 'object') {
+    Object.entries(value).forEach(([subKey, subValue]) => {
+      appendParams(searchParams, `${ key }[${ subKey }]`, subValue);
+    });
+  } else {
+    searchParams.append(key, value);
+  }
+};
+
+// Request context (country, language, segmentTag) is supported by the
+// collections, search and recommendations endpoints per the docs. Callers
+// pass these via `context` (like `apiVersion` in the shopify client),
+// rather than merging them into `query` themselves, so the shared client
+// applies them consistently across every endpoint that uses it.
+const useRequestContextParams = async (state) => {
+  const { requestPayload, context } = state;
+  const { country, language, segmentTag } = context;
+
+  if (!country && !language && !segmentTag) {
+    return {};
+  }
+
+  return {
+    requestPayload: {
+      ...requestPayload,
+      query: {
+        ...requestPayload.query,
+        ...(country ? { country } : {}),
+        ...(language ? { language } : {}),
+        ...(segmentTag ? { segment_tag: segmentTag } : {}),
+      },
+    },
+  };
+};
+
+// Base URL is region-specific per account (e.g. https://api-r1.tagalys.com),
+// so per AGENTS.md it's resolved from creds rather than tagalys.constants.js.
+const useUrlAndQuery = async (state) => {
+  const { requestPayload, context } = state;
+  const { creds } = context;
+
+  const {
+    BASE_URL,
+    STORE_HANDLE,
+    STOREFRONT_API_KEY,
+  } = creds;
+
+  const searchParams = new URLSearchParams();
+  searchParams.append('shop_id', `${ STORE_HANDLE }.myshopify.com`);
+  if (STOREFRONT_API_KEY) {
+    // NOTE: the published docs call this param `storefront_api_key`, but a
+    // live request with that name returned `api_key_invalid`. `api_key`
+    // is what actually authenticates -- trusting the working behaviour
+    // over the doc text here. Revisit if Tagalys ships the documented name.
+    searchParams.append('api_key', STOREFRONT_API_KEY);
+  }
+  Object.entries(requestPayload.query || {}).forEach(([key, value]) => {
+    appendParams(searchParams, key, value);
+  });
+
+  return {
+    requestPayload: {
+      ...requestPayload,
+      url: `${ BASE_URL }${ requestPayload.url }?${ searchParams.toString() }`,
+      headers: {
+        Accept: 'application/json',
+        ...requestPayload.headers,
+      },
+    },
+  };
+};
+
+// A configured redirect takes precedence over the rest of the response --
+// surface it plainly rather than making callers dig for it. Only /v2/search
+// and /v2/search_suggestions ever populate `redirect_url`, so this is a
+// no-op for every other endpoint on the shared client.
+const useRedirectResponse = async (state) => {
+  const { response } = state;
+
+  if (!response?.ok || !response?.data?.redirect_url) {
+    return {};
+  }
+
+  return {
+    response: {
+      redirected: true,
+      redirectUrl: response.data.redirect_url,
+    },
+  };
+};
+
+const tagalysClient = new FetchClient({
+  pipeline: [
+    resolveCreds,
+    useRequestContextParams,
+    useUrlAndQuery,
+    'fetch',
+    fetchClientCommonSteps.exitEarlyOnNotOk,
+    useRedirectResponse,
+  ],
+});
+
+module.exports = {
+  tagalysClient,
+  appendParams,
+};

package/api/tagalys/tagalysAnalyticsEventSend.js

@@ -0,0 +1,125 @@
+// https://tagalys.notion.site/Storefront-API-v2-20eacdd38c2080d58d3fd0cf6f24e435
+
+const { credsValidator } = require('../validators');
+const { ArgsWarden, actionSingleOrMultiple, everyIfArray, valueProvided, logDeep } = require('../utils');
+const { tagalysClient } = require('../tagalys/tagalys.utils');
+
+// Supported `type` values and their `payload` shape:
+//   product_viewed            { productId }
+//   product_added_to_cart     { productId, quantity }
+//   checkout_completed        { orderId, lineItems: [{ productId, quantity }] }
+//   search_results_viewed     { query, productIds, page, totalCount, queryHandling?, sortedBy?, filteredBy? }
+//   collection_viewed         { collectionId, productIds?, page?, totalCount?, sortedBy?, filteredBy? }
+//   recommendations_viewed    { id, recommendedProductIds, sourceProductIds? (required when `id` is contextual to a product) }
+const eventPayloadValidator = (eventPayload) => {
+  return valueProvided(eventPayload?.type)
+    && valueProvided(eventPayload?.payload)
+    && valueProvided(eventPayload?.context?.deviceId)
+    && valueProvided(eventPayload?.context?.visitId);
+};
+
+const argsWarden = new ArgsWarden([
+  ['credsPayload', credsValidator],
+  ['eventPayload', (eventPayload) => everyIfArray(eventPayloadValidator, eventPayload)],
+]);
+
+const tagalysAnalyticsEventSendSingle = async (
+  credsPayload,
+  eventPayload,
+) => {
+  const { type, payload, context } = eventPayload;
+  const {
+    deviceId,
+    visitId,
+    userId,
+    country,
+    language,
+    segmentTag,
+    apiClientName,
+    apiClientVersion,
+  } = context;
+
+  const response = await tagalysClient.fetch({
+    context: {
+      credsPayload,
+    },
+    requestPayload: {
+      url: '/v2/analytics/events',
+      method: 'post',
+      body: {
+        type,
+        payload,
+        context: {
+          device_id: deviceId,
+          visit_id: visitId,
+          ...(userId ? { user_id: userId } : {}),
+          ...(country ? { country } : {}),
+          ...(language ? { language } : {}),
+          ...(segmentTag ? { segment_tag: segmentTag } : {}),
+          ...((apiClientName || apiClientVersion) ? {
+            api_client: {
+              ...(apiClientName ? { name: apiClientName } : {}),
+              ...(apiClientVersion ? { version: apiClientVersion } : {}),
+            },
+          } : {}),
+        },
+      },
+    },
+  });
+
+  const { ok, error } = response;
+  if (!ok) {
+    logDeep({ error });
+  }
+
+  return response;
+};
+
+const tagalysAnalyticsEventSend = async (
+  credsPayload,
+  eventPayload,
+  {
+    queueRunOptions,
+  } = {},
+) => {
+
+  const rejectResponse = await argsWarden.responseIfRejectingArgs({
+    credsPayload,
+    eventPayload,
+  });
+  if (rejectResponse) {
+    return rejectResponse;
+  }
+
+  return actionSingleOrMultiple(
+    eventPayload,
+    tagalysAnalyticsEventSendSingle,
+    (eventPayloadItem) => ({
+      args: [credsPayload, eventPayloadItem],
+    }),
+    {
+      ...(queueRunOptions ? { queueRunOptions } : {}),
+    },
+  );
+};
+
+const funcApiConfig = {
+  argsWarden,
+};
+
+module.exports = {
+  tagalysAnalyticsEventSend,
+  funcApiConfig,
+};
+
+/*
+curl -X POST "http://localhost:8000/tagalysAnalyticsEventSend" \
+-d '{
+  "credsPayload": { "credsPath": "tagalys.au" },
+  "eventPayload": {
+    "type": "product_viewed",
+    "payload": { "productId": "7286848028804" },
+    "context": { "deviceId": "d123", "visitId": "v123" }
+  }
+}'
+*/

package/api/tagalys/tagalysCollectionGet.js

@@ -0,0 +1,100 @@
+// https://tagalys.notion.site/Storefront-API-v2-20eacdd38c2080d58d3fd0cf6f24e435
+
+const { credsValidator } = require('../validators');
+const { ArgsWarden, actionSingleOrMultiple, logDeep } = require('../utils');
+const { DEFAULT_INCLUDE } = require('../tagalys/tagalys.constants');
+const { tagalysClient } = require('../tagalys/tagalys.utils');
+
+const argsWarden = new ArgsWarden([
+  ['credsPayload', credsValidator],
+  ['collectionId'],
+]);
+
+const tagalysCollectionGetSingle = async (
+  credsPayload,
+  collectionId,
+  {
+    include = DEFAULT_INCLUDE, // e.g. ['products', 'filters', 'sort_options', 'total_count']
+    filter, // e.g. { color: ['red'], price: { selected_min: 100, selected_max: 200 } }
+    scope, // e.g. { gender: ['female'] }
+    sort, // e.g. 'price-asc'
+    page,
+    perPage,
+    bannerPositions, // { source: 'dashboard' | 'custom' | 'none', fixed: [4, 6], repeating: { every: 16, at: [5] } }
+    country,
+    language,
+    segmentTag,
+  } = {},
+) => {
+  const response = await tagalysClient.fetch({
+    context: {
+      credsPayload,
+      country,
+      language,
+      segmentTag,
+    },
+    requestPayload: {
+      url: `/v2/collections/${ collectionId }`,
+      method: 'get',
+      query: {
+        include,
+        ...(filter ? { filter } : {}),
+        ...(scope ? { scope } : {}),
+        ...(sort ? { sort } : {}),
+        ...(page ? { page } : {}),
+        ...(perPage ? { per_page: perPage } : {}),
+        ...(bannerPositions ? { banner_positions: bannerPositions } : {}),
+      },
+    },
+  });
+
+  const { ok, error } = response;
+  if (!ok) {
+    logDeep({ error });
+  }
+
+  return response;
+};
+
+const tagalysCollectionGet = async (
+  credsPayload,
+  collectionId,
+  {
+    queueRunOptions,
+    ...options
+  } = {},
+) => {
+
+  const rejectResponse = await argsWarden.responseIfRejectingArgs({
+    credsPayload,
+    collectionId,
+  });
+  if (rejectResponse) {
+    return rejectResponse;
+  }
+
+  return actionSingleOrMultiple(
+    collectionId,
+    tagalysCollectionGetSingle,
+    (collectionIdItem) => ({
+      args: [credsPayload, collectionIdItem, options],
+    }),
+    {
+      ...(queueRunOptions ? { queueRunOptions } : {}),
+    },
+  );
+};
+
+const funcApiConfig = {
+  argsWarden,
+};
+
+module.exports = {
+  tagalysCollectionGet,
+  funcApiConfig,
+};
+
+/*
+curl -X POST "http://localhost:8000/tagalysCollectionGet" \
+-d '{ "credsPayload": { "credsPath": "tagalys.au" }, "collectionId": "123456789" }'
+*/

package/api/tagalys/tagalysPopularSearchesGet.js

@@ -0,0 +1,60 @@
+// https://tagalys.notion.site/Storefront-API-v2-20eacdd38c2080d58d3fd0cf6f24e435
+
+const { credsValidator } = require('../validators');
+const { ArgsWarden, logDeep } = require('../utils');
+const { tagalysClient } = require('../tagalys/tagalys.utils');
+
+const argsWarden = new ArgsWarden([
+  ['credsPayload', credsValidator],
+]);
+
+// Returns at most 10 queries. When the store is configured for country-based
+// availability, `country` filters the response (see the docs).
+const tagalysPopularSearchesGet = async (
+  credsPayload,
+  {
+    country,
+  } = {},
+) => {
+  const rejectResponse = await argsWarden.responseIfRejectingArgs({
+    credsPayload,
+  });
+  if (rejectResponse) {
+    return rejectResponse;
+  }
+
+  const response = await tagalysClient.fetch({
+    context: {
+      credsPayload,
+    },
+    requestPayload: {
+      url: '/v2/popular_searches',
+      method: 'get',
+      query: {
+        ...(country ? { country } : {}),
+      },
+    },
+  });
+
+  const { ok, data, error } = response;
+  if (!ok) {
+    logDeep({ error });
+    return { ok: false, error };
+  }
+
+  return { ok: true, data };
+};
+
+const funcApiConfig = {
+  argsWarden,
+};
+
+module.exports = {
+  tagalysPopularSearchesGet,
+  funcApiConfig,
+};
+
+/*
+curl -X POST "http://localhost:8000/tagalysPopularSearchesGet" \
+-d '{ "credsPayload": { "credsPath": "tagalys.au" } }'
+*/

package/api/tagalys/tagalysRecommendationGet.js

@@ -0,0 +1,109 @@
+// https://tagalys.notion.site/Storefront-API-v2-20eacdd38c2080d58d3fd0cf6f24e435
+
+const { credsValidator } = require('../validators');
+const { ArgsWarden, actionSingleOrMultiple, ensureArray, logDeep } = require('../utils');
+const { MAX_RECOMMENDATION_PRODUCT_IDS } = require('../tagalys/tagalys.constants');
+const { tagalysClient } = require('../tagalys/tagalys.utils');
+
+// System-defined ids: bought_also_bought, viewed_also_viewed, atc_also_atc,
+// recently_viewed, personalized. Custom recommendations use a dashboard slug
+// (e.g. 8d72jc02jd719ddc6hw0).
+const argsWarden = new ArgsWarden([
+  ['credsPayload', credsValidator],
+  ['recommendationId'],
+]);
+
+const tagalysRecommendationGetSingle = async (
+  credsPayload,
+  recommendationId,
+  {
+    productIds, // up to 3, for product-contextual recommendations
+    count,
+
+    // personalized / recently_viewed: either deviceId or userId is required
+    deviceId,
+    userId,
+
+    fallbackRecommendationId, // personalized only
+    visitId, // recently_viewed only
+
+    country,
+    language,
+    segmentTag,
+  } = {},
+) => {
+  const response = await tagalysClient.fetch({
+    context: {
+      credsPayload,
+      country,
+      language,
+      segmentTag,
+    },
+    requestPayload: {
+      url: `/v2/recommendations/${ recommendationId }`,
+      method: 'get',
+      query: {
+        ...(productIds ? { product_ids: ensureArray(productIds).slice(0, MAX_RECOMMENDATION_PRODUCT_IDS) } : {}),
+        ...(count ? { count } : {}),
+        ...(deviceId ? { device_id: deviceId } : {}),
+        ...(userId ? { user_id: userId } : {}),
+        ...(fallbackRecommendationId ? { fallback_recommendation_id: fallbackRecommendationId } : {}),
+        ...(visitId ? { visit_id: visitId } : {}),
+      },
+    },
+  });
+
+  const { ok, error } = response;
+  if (!ok) {
+    logDeep({ error });
+  }
+
+  return response;
+};
+
+const tagalysRecommendationGet = async (
+  credsPayload,
+  recommendationId,
+  {
+    queueRunOptions,
+    ...options
+  } = {},
+) => {
+
+  const rejectResponse = await argsWarden.responseIfRejectingArgs({
+    credsPayload,
+    recommendationId,
+  });
+  if (rejectResponse) {
+    return rejectResponse;
+  }
+
+  return actionSingleOrMultiple(
+    recommendationId,
+    tagalysRecommendationGetSingle,
+    (recommendationIdItem) => ({
+      args: [credsPayload, recommendationIdItem, options],
+    }),
+    {
+      ...(queueRunOptions ? { queueRunOptions } : {}),
+    },
+  );
+};
+
+const funcApiConfig = {
+  argsWarden,
+};
+
+module.exports = {
+  tagalysRecommendationGet,
+  funcApiConfig,
+};
+
+/*
+curl -X POST "http://localhost:8000/tagalysRecommendationGet" \
+-d '{
+  "credsPayload": { "credsPath": "tagalys.au" },
+  "recommendationId": "bought_also_bought",
+  "options": { "productIds": ["1234567890"], "count": 10 }
+}'
+*/

package/api/tagalys/tagalysSearch.js

@@ -2,84 +2,8 @@
 
 const { credsValidator } = require('../validators');
 const { ArgsWarden, logDeep } = require('../utils');
-const { resolveCreds } = require('../pipelineSteps');
-const {
-  FetchClient,
-  fetchClientCommonSteps,
-} = require('../utils');
-
-// NOTE: the Storefront API v2 docs authenticate with `shop_id` (the
-// Shopify myshopify.com domain) + an optional `storefront_api_key`, and
-// don't mention a client_code param on this endpoint at all -- that's a
-// holdover from Tagalys' older v1 API. Mapped below as best guess:
-//   BASE_URL   -> used directly (docs say it's region-specific,
-//                 e.g. https://api-r1.tagalys.com -- assumed already
-//                 resolved to the right region in the creds store)
-//   STORE_HANDLE -> expanded to the `shop_id` myshopify domain
-//   STOREFRONT_API_KEY -> sent as `api_key`
-//   CLIENT_CODE -> not used by /v2/search per the docs; left unused below.
-//                  Flag if your account actually needs it sent somewhere.
-const DEFAULT_INCLUDE = ['products', 'total_count'];
-
-// Recursively flattens nested params into Rails/PHP-style bracket query
-// params, e.g. { filter: { color: ['red'] } } -> filter[color][]=red
-// and { filter: { price: { selected_min: 100 } } } -> filter[price][selected_min]=100
-const appendParams = (searchParams, key, value) => {
-  if (value === undefined || value === null) {
-    return;
-  }
-  if (Array.isArray(value)) {
-    value.forEach((item) => appendParams(searchParams, `${ key }[]`, item));
-  } else if (typeof value === 'object') {
-    Object.entries(value).forEach(([subKey, subValue]) => {
-      appendParams(searchParams, `${ key }[${ subKey }]`, subValue);
-    });
-  } else {
-    searchParams.append(key, value);
-  }
-};
-
-const useUrlAndQuery = async (state) => {
-  const { requestPayload, context } = state;
-  const { creds } = context;
-
-  const {
-    BASE_URL,
-    STORE_HANDLE,
-    STOREFRONT_API_KEY,
-  } = creds;
-  const shopId = `${ STORE_HANDLE }.myshopify.com`;
-  const storefrontApiKey = STOREFRONT_API_KEY;
-
-  const searchParams = new URLSearchParams();
-  searchParams.append('shop_id', shopId);
-  if (storefrontApiKey) {
-    searchParams.append('api_key', storefrontApiKey);
-  }
-  Object.entries(requestPayload.query || {}).forEach(([key, value]) => {
-    appendParams(searchParams, key, value);
-  });
-
-  return {
-    requestPayload: {
-      ...requestPayload,
-      url: `${ BASE_URL }${ requestPayload.url }?${ searchParams.toString() }`,
-      headers: {
-        Accept: 'application/json',
-        ...requestPayload.headers,
-      },
-    },
-  };
-};
-
-const tagalysClient = new FetchClient({
-  pipeline: [
-    resolveCreds,
-    useUrlAndQuery,
-    'fetch',
-    fetchClientCommonSteps.exitEarlyOnNotOk,
-  ],
-});
+const { DEFAULT_INCLUDE } = require('../tagalys/tagalys.constants');
+const { tagalysClient } = require('../tagalys/tagalys.utils');
 
 const argsWarden = new ArgsWarden([
   ['credsPayload', credsValidator],
@@ -96,6 +20,9 @@ const tagalysSearch = async (
     sort, // e.g. 'price-asc'
     page,
     perPage,
+    country,
+    language,
+    segmentTag,
   } = {},
 ) => {
   const rejectResponse = await argsWarden.responseIfRejectingArgs({
@@ -106,9 +33,16 @@ const tagalysSearch = async (
     return rejectResponse;
   }
 
+  // A search can be both redirected and spelling-corrected in the same
+  // response -- redirected/redirectUrl and data (query_handling,
+  // original_query, etc.) both land on the response, see
+  // tagalys.utils.js#useRedirectResponse.
   const response = await tagalysClient.fetch({
     context: {
       credsPayload,
+      country,
+      language,
+      segmentTag,
     },
     requestPayload: {
       url: '/v2/search',
@@ -125,19 +59,12 @@ const tagalysSearch = async (
     },
   });
 
-  const { ok, data, error } = response;
+  const { ok, error } = response;
   if (!ok) {
     logDeep({ error });
-    return { ok: false, error };
-  }
-
-  // A configured redirect takes precedence over the rest of the response --
-  // surface it plainly rather than making callers dig for it.
-  if (data.redirect_url) {
-    return { ok: true, redirected: true, redirectUrl: data.redirect_url, data };
   }
 
-  return { ok: true, data };
+  return response;
 };
 
 const funcApiConfig = {
@@ -146,11 +73,10 @@ const funcApiConfig = {
 
 module.exports = {
   tagalysSearch,
-  tagalysClient,
   funcApiConfig,
 };
 
 /*
 curl -X POST "http://localhost:8000/tagalysSearch" \
--d '{ "credsPayload": { "credsPath": "tagalys.au" }, "query": "gold" }'
+-d '{ "credsPayload": { "credsPath": "tagalys.store" }, "query": "gold" }'
 */