@foxtware/mineral 0.1.27 → 0.1.29

package/api/tableau/tableauUsersGet.js

@@ -1,155 +1,67 @@
+// https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_users_and_groups.htm#query_users_on_site
 // GET /api/{api-version}/sites/{site-id}/users is paginated (default pageSize
 // is 100, max 1000), so this walks all pages and returns the full list.
 
-const { ArgsWarden, logDeep } = require('../utils');
-const { resolveCreds } = require('../pipelineSteps');
-const {
-  FetchClient,
-  appendUrlToBase,
-  fetchClientCommonSteps,
-} = require('../utils');
+const { ArgsWarden } = require('../utils');
+const { credsValidator } = require('../validators');
+const { tableauGet } = require('../tableau/tableauGet');
+const { MAX_PER_PAGE } = require('../tableau/tableau.constants');
 
-const DEFAULT_API_VERSION = '3.22';
-const PAGE_SIZE = 1000; // Tableau's max page size
-
-const tokenCache = new Map();
-
-const tableauSignIn = async ({
-  SERVER_URL,
-  PAT_NAME,
-  PAT_SECRET,
-  SITE_CONTENT_URL = '',
-}) => {
-  const cacheKey = `${ SERVER_URL }::${ SITE_CONTENT_URL }`;
-  const cached = tokenCache.get(cacheKey);
-  if (cached && cached.expiresAt > Date.now()) {
-    return cached;
-  }
-
-  const response = await fetch(`${ SERVER_URL }/api/${ DEFAULT_API_VERSION }/auth/signin`, {
-    method: 'POST',
-    headers: {
-      'Content-Type': 'application/json',
-      Accept: 'application/json',
-    },
-    body: JSON.stringify({
-      credentials: {
-        personalAccessTokenName: PAT_NAME,
-        personalAccessTokenSecret: PAT_SECRET,
-        site: { contentUrl: SITE_CONTENT_URL },
-      },
-    }),
-  });
-
-  if (!response.ok) {
-    throw new Error(`Tableau sign-in failed: ${ response.status } ${ await response.text() }`);
-  }
-
-  const { credentials } = await response.json();
-
-  const session = {
-    token: credentials.token,
-    siteId: credentials.site.id,
-    expiresAt: Date.now() + 1000 * 60 * 60 * 2,
-  };
-
-  tokenCache.set(cacheKey, session);
-  return session;
-};
-
-const useUrlAndAuthHeaders = async (state) => {
-  const { requestPayload, context } = state;
-  const { creds } = context;
-
-  const { token, siteId } = await tableauSignIn(creds);
-
-  return {
-    requestPayload: {
-      ...requestPayload,
-      url: appendUrlToBase(
-        `${ creds.SERVER_URL }/api/${ DEFAULT_API_VERSION }`,
-        requestPayload.url.replace('{siteId}', siteId),
-      ),
-      headers: {
-        'X-Tableau-Auth': token,
-        'Content-Type': 'application/json',
-        Accept: 'application/json',
-        ...requestPayload.headers,
-      },
-    },
-  };
-};
-
-const tableauClient = new FetchClient({
-  pipeline: [
-    resolveCreds,
-    useUrlAndAuthHeaders,
-    'fetch',
-    fetchClientCommonSteps.exitEarlyOnNotOk,
-  ],
-});
-
-const argsWarden = new ArgsWarden([]);
+const argsWarden = new ArgsWarden([
+  ['credsPayload', credsValidator],
+]);
 
 // Optional filter, e.g. { filter: "siteRole:eq:Explorer" } or
 // { filter: "name:has:jane" } per Tableau's filter-expression syntax.
-const tableauUsersGet = async ({ filter } = {}) => {
-  const rejectResponse = await argsWarden.responseIfRejectingArgs({});
+const tableauUsersGet = async (
+  credsPayload,
+  {
+    filter,
+    perPage = MAX_PER_PAGE,
+    fetchClient,
+    ...getterOptions
+  } = {},
+) => {
+  const rejectResponse = await argsWarden.responseIfRejectingArgs({
+    credsPayload,
+  });
   if (rejectResponse) {
     return rejectResponse;
   }
 
-  const users = [];
-  let pageNumber = 1;
-
-  while (true) {
-    const query = new URLSearchParams({
-      pageSize: String(PAGE_SIZE),
-      pageNumber: String(pageNumber),
+  return tableauGet(credsPayload, '/sites/{siteId}/users', {
+    params: {
       ...(filter ? { filter } : {}),
-    });
-
-    const response = await tableauClient.fetch({
-      context: {
-        credsPayload: { credsPath: ['tableau'] },
-      },
-      requestPayload: {
-        url: `/sites/{siteId}/users?${ query.toString() }`,
-        method: 'get',
-      },
-    });
-
-    const { ok, data, error } = response;
-    if (!ok) {
-      logDeep({ error });
-      return { ok: false, error };
-    }
-
-    const pageUsers = data?.users?.user ?? [];
-    users.push(...pageUsers);
-
-    const totalAvailable = Number(data?.pagination?.totalAvailable ?? pageUsers.length);
-    if (users.length >= totalAvailable || pageUsers.length === 0) {
-      break;
-    }
-
-    pageNumber += 1;
-  }
+    },
+    perPage,
+    resultsKey: 'users.user',
+    fetchClient,
+    ...getterOptions,
+  });
+};
 
-  return {
-    ok: true,
-    data: users,
-  };
+const funcApiConfig = {
+  argsWarden,
 };
 
 module.exports = {
   tableauUsersGet,
-  tableauClient,
+  funcApiConfig,
 };
 
 /*
-curl -X POST "http://localhost:8000/tableauUsersGet"
-
-curl -X POST "http://localhost:8000/tableauUsersGet"
--d '{ "filter": "siteRole:eq:Creator" }'
+curl -X POST "http://localhost:8000/tableauUsersGet" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "credsPayload": { "credsPath": "tableau" }
+  }'
+
+curl -X POST "http://localhost:8000/tableauUsersGet" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "credsPayload": { "credsPath": "tableau" },
+    "options": {
+      "filter": "siteRole:eq:Creator"
+    }
+  }'
 */

package/api/tagalys/docs.md

@@ -2,6 +2,6 @@
 
 - [Storefront API (v2)](https://tagalys.notion.site/Storefront-API-v2-20eacdd38c2080d58d3fd0cf6f24e435)
 
-Region-specific HTTPS origins (`https://api-r{n}.tagalys.com`) with REST-style JSON under `/v2`. Storefront reads use GET; analytics ingest uses `POST /v2/analytics/events` with a JSON body. Browser requests authenticate with the `shop_id` query param (the shop’s `*.myshopify.com` domain). Server-side integrations should pass `api_key`.
+Region-specific HTTPS origins (`https://api-r{n}.tagalys.com`) with REST-style JSON under `/v2`. Storefront reads use GET; analytics ingest uses `POST /v2/analytics/events` with a JSON body. Browser requests authenticate with the `shop_id` query param (the shop's `*.myshopify.com` domain). Server-side integrations should also pass an API key -- the published docs name this param `storefront_api_key`, but live testing against this account found `api_key` is what actually authenticates (see tagalys.utils.js).
 
-Endpoints: `GET /v2/collections/:collection_id`, `GET /v2/search`, `GET /v2/search_suggestions`, `GET /v2/popular_searches`, `GET /v2/recommendations/:recommendation_id`, `POST /v2/analytics/events`. Collections and search support pagination (`page`, `per_page`, capped at 10,000 products), sorting (`sort`, `include[]=sort_options`), filtering (`filter[...]`, `include[]=filters`), and scope (`scope[...]`). Use `include[]=products` or `include[]=product_ids` to control product payloads. Optional request context on collections, search, and recommendations: `country`, `language`, `segment_tag`. Errors return JSON with `error.type`, `error.code`, and `error.message`.
+Endpoints: `GET /v2/collections/:collection_id`, `GET /v2/search`, `GET /v2/search_suggestions`, `GET /v2/popular_searches`, `GET /v2/recommendations/:recommendation_id`, `POST /v2/analytics/events`. Collections and search support pagination (`page`, `per_page`, capped at 10,000 products), sorting (`sort`, `include[]=sort_options`), filtering (`filter[...]`, `include[]=filters`), and scope (`scope[...]`, a fixed server-side constraint rather than a shopper-facing facet). Collections also support `banner_positions` to reduce returned products around merchandising banners. Use `include[]=products` or `include[]=product_ids` to control product payloads. Optional request context on collections, search, and recommendations: `country`, `language`, `segment_tag`. Search and search_suggestions can return a top-level `redirect_url` for merchant-configured query redirects, which takes precedence over the rest of the response. Errors return JSON with `error.type`, `error.code`, and `error.message`.

package/api/tagalys/tagalys.constants.js

@@ -0,0 +1,17 @@
+const DEFAULT_INCLUDE = ['products', 'total_count'];
+
+// "Pagination is restricted to the top 10,000 products."
+const MAX_PAGINATION_PRODUCTS = 10000;
+
+// "up to 3 are supported" (recommendations :product_ids param)
+const MAX_RECOMMENDATION_PRODUCT_IDS = 3;
+
+// "Returns at most 10 queries" (GET /v2/popular_searches)
+const MAX_POPULAR_SEARCHES = 10;
+
+module.exports = {
+  DEFAULT_INCLUDE,
+  MAX_PAGINATION_PRODUCTS,
+  MAX_RECOMMENDATION_PRODUCT_IDS,
+  MAX_POPULAR_SEARCHES,
+};

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" } }'
+*/