@foxtware/mineral 0.1.25 → 0.1.27

package/.creds.yml.sample

@@ -115,7 +115,14 @@ google:
 
 tagalys:
   store:
-    BASE_URL: ____________________________ # Server URL
-    CLIENT_CODE: _________________________
-    API_KEY: _____________________________
-    STORE_ID: ____________________________
+    BASE_URL: ____________________________ 
+    CLIENT_CODE: _________________________ # unused but surfaced in dashboard
+    API_KEY: _____________________________ # unused but surfaced in dashboard
+    STOREFRONT_API_KEY: __________________
+    STORE_HANDLE: ________________________
+
+tableau:
+  PAT_NAME: ______________________________
+  PAT_SECRET: ____________________________
+  SERVER_URL: ____________________________
+  SITE_CONTENT_URL: ______________________

package/api/linear/linearTeamGet.js

@@ -1,17 +1,24 @@
 // https://linear.app/developers/graphql
 
-const { ArgsWarden } = require('../utils');
+const { ArgsWarden, objHasAny, oneFromManyInResponse } = require('../utils');
 const { credsValidator } = require('../validators');
 const { linearClient } = require('../linear/linear.utils');
+const { linearTeamsGet } = require('./linearTeamsGet');
+
+const teamIdentifierValidator = (teamIdentifier) => objHasAny(teamIdentifier, [
+  'teamId', 
+  'teamName', 
+  'teamKey',
+]);
 
 const argsWarden = new ArgsWarden([
   ['credsPayload', credsValidator],
-  ['id'],
+  ['teamIdentifier', teamIdentifierValidator],
 ]);
 
 const linearTeamGet = async (
   credsPayload,
-  id,
+  teamIdentifier,
   {
     inspect = false,
     fetchClient = linearClient,
@@ -20,18 +27,54 @@ const linearTeamGet = async (
 
   const rejectResponse = await argsWarden.responseIfRejectingArgs({
     credsPayload,
-    id,
+    teamIdentifier,
   });
   if (rejectResponse) {
     return rejectResponse;
   }
 
+  let {
+    teamId,
+    teamName,
+    teamKey,
+  } = teamIdentifier;
+  
+  // TODO: Return straight from the multiple teams get, if using a non-id identifier
+  if (!teamId) {
+
+    let teamFilter =
+      teamName ? { name: { eq: teamName } } 
+      : teamKey ? { key: { eq: teamKey } } 
+      : null;
+
+    const teamsGetResponse = await linearTeamsGet(credsPayload, { filter: teamFilter });
+
+    const teamIdProp = teamName ? 'name' : 'key';
+    const teamIdValue = teamName ? teamName : teamKey;
+
+    const teamResponse = oneFromManyInResponse(teamsGetResponse, teamIdProp, teamIdValue);
+    if (teamResponse.ok && teamResponse.data) {
+      teamId = teamResponse.data.id;
+    }
+  }
+  
+  // TODO: This should be ok: true, probably
+  if (!teamId) {
+    return {
+      ok: false,
+      data: null,
+      meta: {
+        message: `No team found with identifier ${ JSON.stringify(teamIdentifier) }`,
+      },
+    };
+  }
+
   return fetchClient.fetch({
     requestPayload: {
       body: {
         query: `
-          query TeamGet($id: String!) {
-            team(id: $id) {
+          query TeamGet($teamId: String!) {
+            team(id: $teamId) {
               id
               name
               key
@@ -40,7 +83,7 @@ const linearTeamGet = async (
           }
         `,
         variables: {
-          id,
+          teamId,
         },
       },
     },
@@ -66,6 +109,6 @@ curl -X POST "http://localhost:8000/linearTeamGet" \
   -H "Content-Type: application/json" \
   -d '{
     "credsPayload": { "credsPath": "linear" },
-    "id": "f2387dcd-61ac-49aa-8d7a-7f62a0b5cca0"
+    "teamIdentifier": { "teamName": "Elite Four" }
   }'
 */

package/api/linear/linearTeamsGet.js

@@ -63,4 +63,17 @@ curl -X POST "http://localhost:8000/linearTeamsGet" \
       "limit": 10
     }
   }'
+
+curl -X POST "http://localhost:8000/linearTeamsGet" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "credsPayload": { "credsPath": "linear" },
+    "options": {
+      "filter": {
+        "name": {
+          "eq": "WF Engineering"
+        }
+      }
+    }
+  }'
 */

package/api/tableau/docs.md

@@ -0,0 +1,8 @@
+# Tableau
+
+- [Developer documentation](https://www.tableau.com/developer/learning/tableau-rest-api)
+- [REST API](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_fundamentals.htm)
+- [REST API reference](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref.htm)
+- [Authentication](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_auth.htm)
+
+Server/site-scoped HTTPS JSON (or XML) API at `https://{server}/api/{api-version}/sites/{site-id}/...` for managing users, groups, workbooks, data sources, and other resources, authenticated via a short-lived session token obtained by signing in with a personal access token, username/password, or JWT rather than a single static API key.

package/api/tableau/tableauUserAdd.js

@@ -0,0 +1,158 @@
+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;
+
+  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([
+  ['username'],
+  ['siteRole'],
+]);
+
+// siteRole is the "whatever permissions" lever -> any valid Tableau site
+// role: Creator, Explorer, ExplorerCanPublish, Viewer, SiteAdministratorCreator,
+// SiteAdministratorExplorer, Unlicensed, etc.
+const tableauUserAdd = async (
+  username,
+  siteRole = 'Viewer',
+  {
+    authSetting, // optional: 'ServerDefault' | 'SAML' | 'OpenID' | 'TableauIDWithMFA' ...
+  } = {},
+) => {
+  const rejectResponse = await argsWarden.responseIfRejectingArgs({
+    username,
+    siteRole,
+  });
+  if (rejectResponse) {
+    return rejectResponse;
+  }
+
+  const response = await tableauClient.fetch({
+    context: {
+      credsPayload: { credsPath: ['tableau'] },
+    },
+    requestPayload: {
+      url: '/sites/{siteId}/users',
+      method: 'post',
+      body: {
+        user: {
+          name: username,
+          siteRole,
+          ...(authSetting ? { authSetting } : {}),
+        },
+      },
+    },
+  });
+
+  const { ok, data, error } = response;
+  if (!ok) {
+    logDeep({ error });
+    return { ok: false, error };
+  }
+
+  return {
+    ok: true,
+    data: data.user ?? data,
+  };
+};
+
+const funcApiConfig = {
+  argsWarden,
+};
+
+module.exports = {
+  tableauUserAdd,
+  tableauClient,
+  funcApiConfig,
+};
+
+/*
+curl -X POST "http://localhost:8000/tableauUserAdd" \
+-d '{ "username": "dora@example.com", "siteRole": "Explorer" }'
+*/

package/api/tableau/tableauUsersGet.js

@@ -0,0 +1,155 @@
+// 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 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([]);
+
+// 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({});
+  if (rejectResponse) {
+    return rejectResponse;
+  }
+
+  const users = [];
+  let pageNumber = 1;
+
+  while (true) {
+    const query = new URLSearchParams({
+      pageSize: String(PAGE_SIZE),
+      pageNumber: String(pageNumber),
+      ...(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;
+  }
+
+  return {
+    ok: true,
+    data: users,
+  };
+};
+
+module.exports = {
+  tableauUsersGet,
+  tableauClient,
+};
+
+/*
+curl -X POST "http://localhost:8000/tableauUsersGet"
+
+curl -X POST "http://localhost:8000/tableauUsersGet"
+-d '{ "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 pass `api_key`.
 
 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`.

package/api/tagalys/tagalysSearch.js

@@ -0,0 +1,156 @@
+// https://tagalys.notion.site/Storefront-API-v2-20eacdd38c2080d58d3fd0cf6f24e435
+
+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 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,
+  } = {},
+) => {
+  const rejectResponse = await argsWarden.responseIfRejectingArgs({
+    credsPayload,
+    query,
+  });
+  if (rejectResponse) {
+    return rejectResponse;
+  }
+
+  const response = await tagalysClient.fetch({
+    context: {
+      credsPayload,
+    },
+    requestPayload: {
+      url: '/v2/search',
+      method: 'get',
+      query: {
+        query,
+        include,
+        ...(filter ? { filter } : {}),
+        ...(scope ? { scope } : {}),
+        ...(sort ? { sort } : {}),
+        ...(page ? { page } : {}),
+        ...(perPage ? { per_page: perPage } : {}),
+      },
+    },
+  });
+
+  const { ok, data, 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 };
+};
+
+const funcApiConfig = {
+  argsWarden,
+};
+
+module.exports = {
+  tagalysSearch,
+  tagalysClient,
+  funcApiConfig,
+};
+
+/*
+curl -X POST "http://localhost:8000/tagalysSearch" \
+-d '{ "credsPayload": { "credsPath": "tagalys.au" }, "query": "gold" }'
+*/

package/api/utils.js

@@ -1319,6 +1319,98 @@ const objectMatchesPartial = (object, partial) => {
   ));
 };
 
+const oneFromManyInResponse = (
+  response, 
+  idProp, 
+  idValue,
+) => {
+  const {
+    ok,
+    data,
+  } = response;
+
+  if (!ok || !data) {
+    return response;
+  }
+
+  const candidates = data.filter(item => item[idProp] === idValue);
+
+  if (candidates.length === 0) {
+    return {
+      ok: true,
+      data: null,
+      meta: {
+        message: `No item found with ${ idProp } ${ idValue }`,
+      },
+    };
+  }
+  
+  // TODO: Consider whether to return ok: false as the user's id is not sufficient
+  if (candidates.length > 1) {
+    return {
+      ok: true,
+      data: null,
+      meta: {
+        message: `Multiple items found with ${ idProp } ${ idValue }`,
+      },
+    };
+  }
+
+  return {
+    ok: true,
+    data: candidates[0],
+  };
+};
+
+const surveyObject = (
+  object,
+  options = {},
+) => {
+
+  const {
+    includeSamples,
+  } = options;
+  
+  return Object.fromEntries(
+    Object.entries(object).map(([key, value]) => {
+
+      // Arrays
+      if (Array.isArray(value)) {
+        
+        if (includeSamples) {
+          return [key, {
+            samples: value.slice(0, 5),
+            length: value.length,
+          }];
+        }
+
+        return [key, value.length];
+      }
+      
+      // Sets
+      if (value instanceof Set) {
+
+        if (includeSamples) {
+          return [key, {
+            samples: new Set(Array.from(value).slice(0, 5)),
+            size: value.size,
+          }];
+        }
+
+        return [key, value.size];
+      }
+      
+      // Objects
+      if (isObject(value)) {
+        return [key, surveyObject(value, options)];
+      }
+      
+      // Anything else
+      return [key, value];
+    })
+  );
+};
+
 module.exports = {
   wait,
   timeMs,
@@ -1358,4 +1450,6 @@ module.exports = {
   valueProvided,
   objectToArray,
   objectMatchesPartial,
+  oneFromManyInResponse,
+  surveyObject,
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@foxtware/mineral",
-  "version": "0.1.25",
+  "version": "0.1.27",
   "bin": {
     "mineral": "bin/mineral.js"
   },