@foxtware/mineral 0.1.26 → 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

@@ -0,0 +1,82 @@
+// https://tagalys.notion.site/Storefront-API-v2-20eacdd38c2080d58d3fd0cf6f24e435
+
+const { credsValidator } = require('../validators');
+const { ArgsWarden, logDeep } = require('../utils');
+const { DEFAULT_INCLUDE } = require('../tagalys/tagalys.constants');
+const { tagalysClient } = require('../tagalys/tagalys.utils');
+
+const argsWarden = new ArgsWarden([
+  ['credsPayload', credsValidator],
+  ['query'],
+]);
+
+const tagalysSearch = async (
+  credsPayload,
+  query,
+  {
+    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,
+    country,
+    language,
+    segmentTag,
+  } = {},
+) => {
+  const rejectResponse = await argsWarden.responseIfRejectingArgs({
+    credsPayload,
+    query,
+  });
+  if (rejectResponse) {
+    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',
+      method: 'get',
+      query: {
+        query,
+        include,
+        ...(filter ? { filter } : {}),
+        ...(scope ? { scope } : {}),
+        ...(sort ? { sort } : {}),
+        ...(page ? { page } : {}),
+        ...(perPage ? { per_page: perPage } : {}),
+      },
+    },
+  });
+
+  const { ok, error } = response;
+  if (!ok) {
+    logDeep({ error });
+  }
+
+  return response;
+};
+
+const funcApiConfig = {
+  argsWarden,
+};
+
+module.exports = {
+  tagalysSearch,
+  funcApiConfig,
+};
+
+/*
+curl -X POST "http://localhost:8000/tagalysSearch" \
+-d '{ "credsPayload": { "credsPath": "tagalys.store" }, "query": "gold" }'
+*/

package/api/tagalys/tagalysSearchSuggestionsGet.js

@@ -0,0 +1,76 @@
+// https://tagalys.notion.site/Storefront-API-v2-20eacdd38c2080d58d3fd0cf6f24e435
+
+const { credsValidator } = require('../validators');
+const { ArgsWarden, logDeep, valueProvided } = require('../utils');
+const { tagalysClient } = require('../tagalys/tagalys.utils');
+
+const argsWarden = new ArgsWarden([
+  ['credsPayload', credsValidator],
+  ['query'],
+  ['sections', (sections) => valueProvided(sections) && Object.keys(sections).length > 0],
+]);
+
+// `sections` is an object keyed by section_id, e.g.:
+// {
+//   products: { count: 6, include: ['items', 'total_count'], scope: { gender: ['female'] } },
+//   collections: { count: 4 },
+//   searches: { count: 4 },
+// }
+// section_ids and their available options are configured per account by Tagalys.
+const tagalysSearchSuggestionsGet = async (
+  credsPayload,
+  query,
+  sections,
+) => {
+  const rejectResponse = await argsWarden.responseIfRejectingArgs({
+    credsPayload,
+    query,
+    sections,
+  });
+  if (rejectResponse) {
+    return rejectResponse;
+  }
+
+  // redirected/redirectUrl land on the response via tagalys.utils.js#useRedirectResponse
+  const response = await tagalysClient.fetch({
+    context: {
+      credsPayload,
+    },
+    requestPayload: {
+      url: '/v2/search_suggestions',
+      method: 'get',
+      query: {
+        query,
+        sections,
+      },
+    },
+  });
+
+  const { ok, error } = response;
+  if (!ok) {
+    logDeep({ error });
+  }
+
+  return response;
+};
+
+const funcApiConfig = {
+  argsWarden,
+};
+
+module.exports = {
+  tagalysSearchSuggestionsGet,
+  funcApiConfig,
+};
+
+/*
+curl -X POST "http://localhost:8000/tagalysSearchSuggestionsGet" \
+-d '{
+  "credsPayload": { "credsPath": "tagalys.au" },
+  "query": "shi",
+  "sections": {
+    "products": { "count": 6 },
+    "collections": { "count": 4 }
+  }
+}'
+*/

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@foxtware/mineral",
-  "version": "0.1.26",
+  "version": "0.1.28",
   "bin": {
     "mineral": "bin/mineral.js"
   },
@@ -17,6 +17,7 @@
     "spin_off": "node _build_scripts/spinOff.js",
     "serve": "PORT=8100 node server.js",
     "start": "node server.js",
+    "zip": "sh ../shell_scripts/zip.sh",
     "npm:publish": "node _build_scripts/publish.js"
   },
   "dependencies": {