@foxtware/mineral 0.1.26 → 0.1.28

package/api/tableau/tableau.utils.js

@@ -0,0 +1,93 @@
+const { DEFAULT_API_VERSION } = require('../tableau/tableau.constants');
+const { resolveCreds } = require('../pipelineSteps');
+const {
+  FetchClient,
+  appendUrlToBase,
+  fetchClientCommonSteps,
+} = require('../utils');
+
+// Tableau sessions are token-based (sign in -> token, valid ~2hrs by default
+// server config), unlike Shopify's static API key. We cache tokens per
+// server+site so we're not re-signing-in on every single call.
+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,
+    // Refresh a bit early rather than riding right up against the server's
+    // idle/absolute timeout.
+    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,
+        Accept: 'application/json',
+        ...requestPayload.headers,
+      },
+    },
+  };
+};
+
+const tableauClient = new FetchClient({
+  pipeline: [
+    resolveCreds,
+    useUrlAndAuthHeaders,
+    'fetch',
+    fetchClientCommonSteps.exitEarlyOnNotOk,
+  ],
+});
+
+module.exports = {
+  tableauClient,
+  tableauSignIn,
+};

package/api/tableau/tableauGet.js

@@ -0,0 +1,174 @@
+// https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_paging.htm
+
+const { ArgsWarden, Getter } = require('../utils');
+const { credsValidator } = require('../validators');
+const { tableauClient } = require('../tableau/tableau.utils');
+const { MAX_PER_PAGE } = require('../tableau/tableau.constants');
+
+const argsWarden = new ArgsWarden([
+  ['credsPayload', credsValidator],
+  ['url'],
+]);
+
+// Tableau list responses nest items, e.g. data.users.user, data.workbooks.workbook.
+// resultsKey may be a dotted path such as "users.user".
+const digResults = (data, resultsKey) => {
+  if (resultsKey) {
+    const value = resultsKey.split('.').reduce(
+      (node, key) => node?.[key],
+      data,
+    );
+    if (Array.isArray(value)) {
+      return value;
+    }
+    return value != null ? [value] : [];
+  }
+
+  if (Array.isArray(data)) {
+    return data;
+  }
+
+  const arrayEntry = Object.entries(data || {}).find(([, value]) => Array.isArray(value));
+  return arrayEntry ? arrayEntry[1] : [];
+};
+
+const tableauGetPacket = async (
+  credsPayload,
+  url,
+  {
+    params,
+    perPage = MAX_PER_PAGE,
+    fetchClient = tableauClient,
+  } = {},
+) => {
+  return fetchClient.fetch({
+    requestPayload: {
+      method: 'get',
+      url,
+      params: {
+        pageSize: Math.min(perPage, MAX_PER_PAGE),
+        pageNumber: 1,
+        ...params,
+      },
+    },
+    context: {
+      credsPayload,
+    },
+  });
+};
+
+const tableauGetPaginator = async (currentParams, response) => {
+  if (!response?.ok) {
+    return [true];
+  }
+
+  const pagination = response?.data?.pagination;
+  if (!pagination) {
+    return [true];
+  }
+
+  const pageNumber = Number(pagination.pageNumber);
+  const pageSize = Number(pagination.pageSize);
+  const totalAvailable = Number(pagination.totalAvailable);
+
+  if (!pageNumber || !pageSize || Number.isNaN(totalAvailable)) {
+    return [true];
+  }
+
+  if (pageNumber * pageSize >= totalAvailable) {
+    return [true];
+  }
+
+  const { args, options } = currentParams;
+
+  return [false, {
+    args,
+    options: {
+      ...options,
+      params: {
+        ...options.params,
+        pageNumber: pageNumber + 1,
+      },
+    },
+  }];
+};
+
+const tableauGet = async (
+  returnGetter,
+
+  credsPayload,
+  url,
+  {
+    params,
+    perPage = MAX_PER_PAGE,
+    resultsKey,
+    fetchClient,
+    ...getterOptions
+  } = {},
+) => {
+
+  const rejectResponse = await argsWarden.responseIfRejectingArgs({
+    credsPayload,
+    url,
+  });
+  if (rejectResponse) {
+    return rejectResponse;
+  }
+
+  const getter = new Getter(
+    {
+      args: [credsPayload, url],
+      options: {
+        params,
+        perPage,
+        fetchClient,
+      },
+    },
+    {
+      func: tableauGetPacket,
+      digester: (response) => {
+        if (!response?.ok) {
+          return [];
+        }
+
+        return digResults(response.data, resultsKey);
+      },
+      paginator: tableauGetPaginator,
+      ...getterOptions,
+    },
+  );
+
+  if (returnGetter) {
+    return getter;
+  }
+
+  const data = await getter.run({ returnAll: true });
+
+  return {
+    ok: true,
+    data,
+  };
+};
+
+const funcApiConfig = {
+  argsWarden,
+};
+
+module.exports = {
+  tableauGet: (...args) => tableauGet(false, ...args),
+  tableauGetter: (...args) => tableauGet(true, ...args),
+  funcApiConfig,
+};
+
+/*
+curl -X POST "http://localhost:8000/tableauGet" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "credsPayload": { "credsPath": "tableau" },
+    "url": "/sites/{siteId}/users",
+    "options": {
+      "resultsKey": "users.user",
+      "perPage": 100
+    }
+  }'
+*/

package/api/tableau/tableauUserAdd.js

@@ -1,96 +1,11 @@
-const { ArgsWarden, logDeep } = require('../utils');
-const { resolveCreds } = require('../pipelineSteps');
-const {
-  FetchClient,
-  appendUrlToBase,
-  fetchClientCommonSteps,
-} = require('../utils');
-
-const DEFAULT_API_VERSION = '3.22';
-
-// Tableau sessions are token-based (sign in -> token, valid ~2hrs by default
-// server config), unlike Shopify's static API key. We cache tokens per
-// server+site so we're not re-signing-in on every single call.
-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,
-    // Refresh a bit early rather than riding right up against the server's
-    // idle/absolute timeout.
-    expiresAt: Date.now() + 1000 * 60 * 60 * 2,
-  };
-
-  tokenCache.set(cacheKey, session);
-  return session;
-};
-
-const useUrlAndAuthHeaders = async (state) => {
-  const { requestPayload, context } = state;
-  const { creds } = context;
+// https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_users_and_groups.htm#add_user_to_site
 
-  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, logDeep } = require('../utils');
+const { credsValidator } = require('../validators');
+const { tableauClient } = require('../tableau/tableau.utils');
 
 const argsWarden = new ArgsWarden([
+  ['credsPayload', credsValidator],
   ['username'],
   ['siteRole'],
 ]);
@@ -99,13 +14,16 @@ const argsWarden = new ArgsWarden([
 // role: Creator, Explorer, ExplorerCanPublish, Viewer, SiteAdministratorCreator,
 // SiteAdministratorExplorer, Unlicensed, etc.
 const tableauUserAdd = async (
+  credsPayload,
   username,
   siteRole = 'Viewer',
   {
     authSetting, // optional: 'ServerDefault' | 'SAML' | 'OpenID' | 'TableauIDWithMFA' ...
+    fetchClient = tableauClient,
   } = {},
 ) => {
   const rejectResponse = await argsWarden.responseIfRejectingArgs({
+    credsPayload,
     username,
     siteRole,
   });
@@ -113,9 +31,9 @@ const tableauUserAdd = async (
     return rejectResponse;
   }
 
-  const response = await tableauClient.fetch({
+  const response = await fetchClient.fetch({
     context: {
-      credsPayload: { credsPath: ['tableau'] },
+      credsPayload,
     },
     requestPayload: {
       url: '/sites/{siteId}/users',
@@ -148,11 +66,15 @@ const funcApiConfig = {
 
 module.exports = {
   tableauUserAdd,
-  tableauClient,
   funcApiConfig,
 };
 
 /*
 curl -X POST "http://localhost:8000/tableauUserAdd" \
--d '{ "username": "dora@example.com", "siteRole": "Explorer" }'
+  -H "Content-Type: application/json" \
+  -d '{
+    "credsPayload": { "credsPath": "tableau" },
+    "username": "dora@example.com",
+    "siteRole": "Explorer"
+  }'
 */

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 also pass `storefront_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,
+};