@foxtware/mineral 0.1.25 → 0.1.26

package/.creds.yml.sample

@@ -119,3 +119,9 @@ tagalys:
     CLIENT_CODE: _________________________
     API_KEY: _____________________________
     STORE_ID: ____________________________
+
+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/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.26",
   "bin": {
     "mineral": "bin/mineral.js"
   },