@foxtware/mineral 0.1.27 → 0.1.29

package/api/spotify/spotifySearch.js

@@ -0,0 +1,174 @@
+// https://developer.spotify.com/documentation/web-api/reference/search
+
+const { ArgsWarden, Getter } = require('../utils');
+const { credsValidator } = require('../validators');
+const { spotifyClient } = require('../spotify/spotify.utils');
+const { MAX_SEARCH_PER_PAGE } = require('../spotify/spotify.constants');
+
+const argsWarden = new ArgsWarden([
+  ['credsPayload', credsValidator],
+  ['query'],
+  ['types'],
+]);
+
+const digSearchResults = (data, types) => {
+  const typeList = (Array.isArray(types) ? types : String(types).split(','))
+    .map((t) => t.trim())
+    .filter(Boolean);
+
+  // Flatten matches across requested types, tagging each with its type key.
+  const out = [];
+  for (const type of typeList) {
+    const key = type.endsWith('s') ? type : `${ type }s`;
+    const page = data?.[key];
+    const items = page?.items ?? [];
+    for (const item of items) {
+      out.push({ type: key, ...item });
+    }
+  }
+  return out;
+};
+
+const spotifySearchPacket = async (
+  credsPayload,
+  query,
+  types,
+  {
+    params = {},
+    perPage = MAX_SEARCH_PER_PAGE,
+    fetchClient = spotifyClient,
+  } = {},
+) => {
+  const typeParam = Array.isArray(types) ? types.join(',') : types;
+
+  return fetchClient.fetch({
+    context: { credsPayload },
+    requestPayload: {
+      method: 'get',
+      url: '/search',
+      params: {
+        q: query,
+        type: typeParam,
+        limit: Math.min(perPage, MAX_SEARCH_PER_PAGE),
+        offset: 0,
+        ...params,
+      },
+    },
+  });
+};
+
+const spotifySearchPaginator = async (currentParams, response) => {
+  if (!response?.ok) {
+    return [true];
+  }
+
+  const data = response.data ?? {};
+  // Any requested type still having a next URL means we continue.
+  const hasNext = Object.values(data).some(
+    (page) => page && typeof page === 'object' && page.next,
+  );
+  if (!hasNext) {
+    return [true];
+  }
+
+  const { args, options } = currentParams;
+  const { params = {}, perPage = MAX_SEARCH_PER_PAGE } = options;
+  const currentOffset = Number(params.offset ?? 0);
+  const pageLimit = Number(params.limit ?? perPage);
+
+  return [false, {
+    args,
+    options: {
+      ...options,
+      params: {
+        ...params,
+        offset: currentOffset + pageLimit,
+        limit: pageLimit,
+      },
+    },
+  }];
+};
+
+const spotifySearch = async (
+  returnGetter,
+
+  credsPayload,
+  query,
+  types,
+  {
+    market,
+    includeExternal,
+    perPage = MAX_SEARCH_PER_PAGE,
+    fetchClient,
+    ...getterOptions
+  } = {},
+) => {
+  const rejectResponse = await argsWarden.responseIfRejectingArgs({
+    credsPayload,
+    query,
+    types,
+  });
+  if (rejectResponse) {
+    return rejectResponse;
+  }
+
+  const typeList = Array.isArray(types) ? types : String(types).split(',');
+
+  const getter = new Getter(
+    {
+      args: [credsPayload, query, types],
+      options: {
+        params: {
+          ...(market !== undefined && { market }),
+          ...(includeExternal !== undefined && {
+            include_external: includeExternal,
+          }),
+        },
+        perPage,
+        fetchClient,
+      },
+    },
+    {
+      func: spotifySearchPacket,
+      digester: (response) => {
+        if (!response?.ok) {
+          return [];
+        }
+        return digSearchResults(response.data, typeList);
+      },
+      paginator: spotifySearchPaginator,
+      ...getterOptions,
+    },
+  );
+
+  if (returnGetter) {
+    return getter;
+  }
+
+  const data = await getter.run({ returnAll: true });
+
+  return {
+    ok: true,
+    data,
+  };
+};
+
+const funcApiConfig = {
+  argsWarden,
+};
+
+module.exports = {
+  spotifySearch: (...args) => spotifySearch(false, ...args),
+  spotifySearchGetter: (...args) => spotifySearch(true, ...args),
+  funcApiConfig,
+};
+
+/*
+curl -X POST "http://localhost:8000/spotifySearch" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "credsPayload": { "credsPath": "spotify" },
+    "query": "radiohead",
+    "types": ["artist", "album"]
+  }'
+*/

package/api/spotify/spotifyTrackGet.js

@@ -0,0 +1,76 @@
+// https://developer.spotify.com/documentation/web-api/reference/get-track
+
+const { ArgsWarden, actionSingleOrMultiple, logDeep } = require('../utils');
+const { credsValidator } = require('../validators');
+const { spotifyClient } = require('../spotify/spotify.utils');
+
+const argsWarden = new ArgsWarden([
+  ['credsPayload', credsValidator],
+  ['trackId'],
+]);
+
+const spotifyTrackGetSingle = async (
+  credsPayload,
+  trackId,
+  {
+    market,
+    fetchClient = spotifyClient,
+  } = {},
+) => {
+  const response = await fetchClient.fetch({
+    context: { credsPayload },
+    requestPayload: {
+      method: 'get',
+      url: `/tracks/${ trackId }`,
+      params: {
+        ...(market !== undefined && { market }),
+      },
+    },
+  });
+
+  const { ok, data, error } = response;
+  if (!ok) {
+    logDeep({ error });
+    return { ok: false, error };
+  }
+
+  return { ok: true, data };
+};
+
+const spotifyTrackGet = async (
+  credsPayload,
+  trackId,
+  {
+    market,
+    queueRunOptions,
+    fetchClient,
+  } = {},
+) => {
+  const rejectResponse = await argsWarden.responseIfRejectingArgs({
+    credsPayload,
+    trackId,
+  });
+  if (rejectResponse) {
+    return rejectResponse;
+  }
+
+  return actionSingleOrMultiple(
+    trackId,
+    spotifyTrackGetSingle,
+    (trackIdItem) => ({
+      args: [credsPayload, trackIdItem, { market, fetchClient }],
+    }),
+    {
+      ...(queueRunOptions ? { queueRunOptions } : {}),
+    },
+  );
+};
+
+const funcApiConfig = {
+  argsWarden,
+};
+
+module.exports = {
+  spotifyTrackGet,
+  funcApiConfig,
+};

package/api/tableau/tableau.constants.js

@@ -0,0 +1,8 @@
+const DEFAULT_API_VERSION = '3.22';
+// Tableau's max page size for list endpoints
+const MAX_PER_PAGE = 1000;
+
+module.exports = {
+  DEFAULT_API_VERSION,
+  MAX_PER_PAGE,
+};

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