@foxtware/mineral 0.1.5 → 0.1.7

package/.creds.yml.sample

@@ -23,4 +23,7 @@ yotpo:
     MERCHANT_ID: _________________________
 
 linear:
-  API_KEY: _______________________________
+  API_KEY: _______________________________
+
+slack:
+  BOT_TOKEN: xoxb________________________________

package/.env.sample

@@ -0,0 +1,2 @@
+# Required by the requireHostedApiKey wrapper — requests must send this as the x-api-key header.
+HOSTED_API_KEY=________________________________

package/.gcloudignore

@@ -7,11 +7,8 @@
 #   $ gcloud topic gcloudignore
 #
 .gcloudignore
-# If you would like to upload your .git directory, .gitignore file or files
-# from your .gitignore file, remove the corresponding line
-# below:
 .git
 .gitignore
 
 node_modules
-#!include:.gitignore
+.creds.yml

package/README.md

@@ -51,4 +51,9 @@ The [bedrock](https://github.com/GorgonFreeman/bedrock) middleware, refactored f
 - **Monorepo structure**
 Mineral gets pushed to from a larger repo that can also contain private functions. Mineral should be strictly useful stuff for the public, and can be used standalone, but needs to be instantiated for serving, setting stuff like which creds file to use. This allows it to be used as part of another repo in the same HTTP/curl way as by itself. Pass `--workspace` to locate `.creds.yml` and `--api_dirs` to serve additional function directories.
 
-For cloud deploy, workspaces use `.hosting.yml` and `npm run host` (same `--workspace` / `--api_dirs` flags as dev/serve). See `.hosting.yml.sample`.
+For cloud deploy, workspaces use `hosting/.hosting.yml` and `npm run host` (same `--workspace` / `--api_dirs` flags as dev/serve). See `hosting/.hosting.yml.sample`.
+
+## What the thang do
+- Server makes functions available from the api/ route, where an export matches the filename. Run `npm run serve`, and they're all curlable.
+- .creds.yml is copied into .env when deploying, so creds can be accessed while hosted. Locally, it reads from the file directly.
+- Cloud deploy reads `hosting/.hosting.yml` for per-function config — `before_wrappers` / `after_wrappers` like `requireHostedApiKey`, `max_instances`, schedules — and deploys each function to Google Cloud.

package/_build_scripts/createNewFunction.js

@@ -3,31 +3,51 @@ const path = require('path');
 const { spawn } = require('child_process');
 const { askQuestion, capitaliseString } = require('../api/utils');
 
-const apiDirectory = path.join(__dirname, '../api');
-const rootExampleJsPath = path.join(apiDirectory, '_example.js');
+const mineralRoot = path.join(__dirname, '..');
+const mineralApiDirectory = path.join(mineralRoot, 'api');
+const rootExampleJsPath = path.join(mineralApiDirectory, '_example.js');
 
 const excludedDirs = new Set([
   'node_modules',
 ]);
 
-const printHelp = () => {
+const normalizePath = (dirPath) => dirPath.replace(/\/$/, '');
+
+const isMineralCwd = () => normalizePath(process.cwd()) === normalizePath(mineralRoot);
+
+const getContext = () => {
+  const inMineral = isMineralCwd();
+
+  return {
+    inMineral,
+    apiDirectory: inMineral ? mineralApiDirectory : path.join(process.cwd(), 'api'),
+    mineralApiDirectory,
+  };
+};
+
+const printHelp = (context) => {
+  const templateHelp = context.inMineral
+    ? `example template to copy (default: _example.js in dir, else api/_example.js)
+                  examples: _example.js, getsingle, _example.getsingle.js`
+    : `mineral example template to copy (default: _example.js)
+                  examples: _example.js, shopify/_example.js, shopify/getsingle`;
+
   console.log(`
 Usage:
   npm run new
   npm run new -- --dir <apiSubdir> --name <name> [--template <exampleTemplate>] [--commit]
 
 Options:
-  --dir, -d       api subdirectory (e.g. peoplevox, shopify)
+  --dir, -d       api subdirectory (e.g. peoplevox, shopify). Omit for flat api/ dirs.
   --name, -n      function name suffix (e.g. orderGet → peoplevoxOrderGet)
-  --template, -t  example template to copy (default: _example.js in dir, else api/_example.js)
-                  examples: _example.js, getsingle, _example.getsingle.js
+  --template, -t  ${ templateHelp }
   --commit        auto-commit the stub after creation
   --help, -h      show this help
 
 Examples:
   npm run new -- --dir peoplevox --name orderGet
-  npm run new -- --dir peoplevox --name orderGet --template _example.js
   npm run new -- --dir shopify --name pageGet --template getsingle
+  npm run new -- --name geodeBye --template shopify/_example.js
 `);
 };
 
@@ -124,11 +144,51 @@ const findExampleFiles = async (dirPath) => {
   }
 };
 
+const collectMineralExampleFiles = async (dirPath, relativePrefix = '') => {
+  const results = [];
+  const localExamples = await findExampleFiles(dirPath);
+
+  for (const file of localExamples) {
+    const relativePath = relativePrefix ? `${ relativePrefix }/${ file.filename }` : file.filename;
+
+    results.push({
+      ...file,
+      relativePath,
+      displayName: relativePath,
+    });
+  }
+
+  let childDirs = [];
+
+  try {
+    const dirents = await fs.readdir(dirPath, { withFileTypes: true });
+    childDirs = dirents
+      .filter(dirent => dirent.isDirectory())
+      .map(dirent => dirent.name)
+      .filter(name => name[0] !== '_' && name[0] !== '.')
+      .filter(name => !excludedDirs.has(name));
+  } catch (err) {
+    return results;
+  }
+
+  for (const childDir of childDirs) {
+    const childPrefix = relativePrefix ? `${ relativePrefix }/${ childDir }` : childDir;
+    const childResults = await collectMineralExampleFiles(path.join(dirPath, childDir), childPrefix);
+    results.push(...childResults);
+  }
+
+  return results;
+};
+
 const sortExampleFiles = (exampleFiles) => {
   return [...exampleFiles].sort((a, b) => {
-    if (a.displayName === '_example.js') return -1;
-    if (b.displayName === '_example.js') return 1;
-    return a.displayName.localeCompare(b.displayName);
+    const aKey = a.relativePath || a.displayName;
+    const bKey = b.relativePath || b.displayName;
+
+    if (aKey === '_example.js') return -1;
+    if (bKey === '_example.js') return 1;
+
+    return aKey.localeCompare(bKey);
   });
 };
 
@@ -148,7 +208,68 @@ const normalizeTemplateArg = (templateArg) => {
   return `_example.${ templateArg }.js`;
 };
 
-const resolveTemplateFromArg = async (exampleFiles, templateArg, dir) => {
+const findWorkspaceTemplate = (exampleFiles, templateArg) => {
+  if (!templateArg) {
+    const defaultTemplate = exampleFiles.find(file => file.relativePath === '_example.js');
+    if (defaultTemplate) {
+      return defaultTemplate;
+    }
+
+    if (exampleFiles.length === 0) {
+      throw new Error('No mineral example templates found');
+    }
+
+    return exampleFiles[0];
+  }
+
+  const directMatch = exampleFiles.find(file => file.relativePath === templateArg);
+  if (directMatch) {
+    return directMatch;
+  }
+
+  const normalizedFilename = normalizeTemplateArg(templateArg);
+  const filenameMatches = exampleFiles.filter(file => file.filename === normalizedFilename);
+
+  if (templateArg.includes('/')) {
+    const [ prefix, suffix ] = templateArg.split('/');
+    const normalizedSuffix = normalizeTemplateArg(suffix);
+    const prefixedMatch = exampleFiles.find(file => file.relativePath === `${ prefix }/${ normalizedSuffix }`);
+
+    if (prefixedMatch) {
+      return prefixedMatch;
+    }
+  }
+
+  if (filenameMatches.length === 1) {
+    return filenameMatches[0];
+  }
+
+  const suffixMatches = exampleFiles.filter(file => file.relativePath.endsWith(`/${ normalizedFilename }`));
+
+  if (suffixMatches.length === 1) {
+    return suffixMatches[0];
+  }
+
+  if (suffixMatches.length > 1) {
+    throw new Error(
+      `Ambiguous template "${ templateArg }". Use one of: ${ suffixMatches.map(file => file.relativePath).join(', ') }`,
+    );
+  }
+
+  throw new Error(`Template not found: ${ templateArg }`);
+};
+
+const resolveTemplateFromArg = async ({
+  exampleFiles,
+  templateArg,
+  dir,
+  inMineral,
+}) => {
+  if (!inMineral) {
+    const selectedTemplate = findWorkspaceTemplate(exampleFiles, templateArg);
+    return selectedTemplate.fullPath;
+  }
+
   if (!templateArg) {
     const defaultInDir = exampleFiles.find(file => file.displayName === '_example.js');
     if (defaultInDir) {
@@ -184,13 +305,51 @@ const scriptFileContents = async (name, selectedTemplate) => {
   return exampleFileContents.replace(/FUNC/g, name);
 };
 
-const getDirs = async () => {
-  const dirents = await fs.readdir(apiDirectory, { withFileTypes: true });
-  return dirents
-    .filter(dirent => dirent.isDirectory())
-    .map(dirent => dirent.name)
-    .filter(name => name[0] !== '_' && name[0] !== '.')
-    .filter(name => !excludedDirs.has(name));
+const getDirs = async (targetApiDirectory) => {
+  try {
+    const dirents = await fs.readdir(targetApiDirectory, { withFileTypes: true });
+    return dirents
+      .filter(dirent => dirent.isDirectory())
+      .map(dirent => dirent.name)
+      .filter(name => name[0] !== '_' && name[0] !== '.')
+      .filter(name => !excludedDirs.has(name));
+  } catch (err) {
+    if (err.code === 'ENOENT') {
+      return [];
+    }
+
+    throw err;
+  }
+};
+
+const normalizeDirArg = (dirArg) => {
+  if (!dirArg || dirArg === '.' || dirArg === 'api') {
+    return '';
+  }
+
+  return dirArg;
+};
+
+const resolveDirArg = ({ dirArg, dirs, inMineral, name }) => {
+  const normalizedDir = normalizeDirArg(dirArg);
+
+  if (dirs.includes(normalizedDir)) {
+    return normalizedDir;
+  }
+
+  if (!inMineral && dirs.length === 0 && normalizedDir === '') {
+    return '';
+  }
+
+  if (!inMineral && !dirArg && name) {
+    return '';
+  }
+
+  if (inMineral && !dirArg) {
+    return null;
+  }
+
+  return normalizedDir;
 };
 
 const buildFuncName = (dir, name) => {
@@ -201,6 +360,11 @@ const buildFuncName = (dir, name) => {
 };
 
 const selectDirInteractive = async (dirs) => {
+  if (dirs.length === 0) {
+    console.log('\nCreating in api/');
+    return '';
+  }
+
   const dirIndex = await askQuestion(`Where does your new function live? \n${
     dirs.map((dir, index) => {
       return `[${ index + 1 }] ${ dir }`;
@@ -216,33 +380,54 @@ const selectDirInteractive = async (dirs) => {
   return dir;
 };
 
-const selectTemplateInteractive = async (exampleFiles, dir) => {
+const getExampleFilesForContext = async ({ context, dir }) => {
+  if (context.inMineral) {
+    return sortExampleFiles(await findExampleFiles(path.join(context.apiDirectory, dir)));
+  }
+
+  return sortExampleFiles(await collectMineralExampleFiles(context.mineralApiDirectory));
+};
+
+const formatTemplateLabel = (file, { inMineral }) => {
+  if (inMineral) {
+    return file.displayName;
+  }
+
+  return file.relativePath;
+};
+
+const selectTemplateInteractive = async ({ exampleFiles, dir, inMineral }) => {
   if (exampleFiles.length === 0) {
     await fs.access(rootExampleJsPath);
-    console.log('\nUsing template: api/_example.js');
+    console.log('\nUsing template: _example.js');
     return rootExampleJsPath;
   }
 
   if (exampleFiles.length === 1) {
-    console.log(`\nUsing template: ${ exampleFiles[0].displayName }`);
+    console.log(`\nUsing template: ${ formatTemplateLabel(exampleFiles[0], { inMineral }) }`);
     return exampleFiles[0].fullPath;
   }
 
-  console.log(`\nFound ${ exampleFiles.length } template(s) in api/${ dir }:`);
+  const templateScope = inMineral ? `in api/${ dir }` : 'from mineral';
+  console.log(`\nFound ${ exampleFiles.length } template(s) ${ templateScope }:`);
+
   const templateIndex = await askQuestion(`Which template would you like to use? (press enter for _example.js) \n${
     exampleFiles.map((file, index) => {
-      return `[${ index + 1 }] ${ file.displayName }`;
+      return `[${ index + 1 }] ${ formatTemplateLabel(file, { inMineral }) }`;
     }).join('\n')
   }\n`);
 
   if (!templateIndex || templateIndex.trim() === '') {
-    const defaultFile = exampleFiles.find(file => file.displayName === '_example.js');
+    const defaultFile = exampleFiles.find(file => (
+      file.relativePath === '_example.js' || file.displayName === '_example.js'
+    ));
+
     if (defaultFile) {
       return defaultFile.fullPath;
     }
 
     await fs.access(rootExampleJsPath);
-    console.log('\nUsing template: api/_example.js');
+    console.log('\nUsing template: _example.js');
     return rootExampleJsPath;
   }
 
@@ -266,6 +451,7 @@ const selectNameInteractive = async (dir) => {
 };
 
 const writeNewFunction = async ({
+  apiDirectory,
   dir,
   name,
   selectedTemplate,
@@ -283,6 +469,8 @@ const writeNewFunction = async ({
     }
   }
 
+  await fs.mkdir(path.dirname(outputPath), { recursive: true });
+
   const script = await scriptFileContents(funcName, selectedTemplate);
   await fs.writeFile(outputPath, script);
 
@@ -296,38 +484,55 @@ const writeNewFunction = async ({
 };
 
 const createNewFunction = async () => {
+  const context = getContext();
   const cliArgs = parseCliArgs(process.argv.slice(2));
 
   if (cliArgs.help) {
-    printHelp();
+    printHelp(context);
     return;
   }
 
-  const dirs = await getDirs();
+  const dirs = await getDirs(context.apiDirectory);
   const nonInteractive = Boolean(cliArgs.dir || cliArgs.name);
 
   if (nonInteractive) {
-    if (!cliArgs.dir || !cliArgs.name) {
-      console.error('Non-interactive mode requires both --dir and --name.');
-      printHelp();
+    if (!cliArgs.name) {
+      console.error('Non-interactive mode requires --name.');
+      printHelp(context);
       process.exitCode = 1;
       return;
     }
 
-    if (!dirs.includes(cliArgs.dir)) {
-      console.error(`Invalid --dir "${ cliArgs.dir }". Available: ${ dirs.join(', ') }`);
+    const dir = resolveDirArg({
+      dirArg: cliArgs.dir,
+      dirs,
+      inMineral: context.inMineral,
+      name: cliArgs.name,
+    });
+
+    if (dir === null || (!dirs.includes(dir) && !(dir === '' && dirs.length === 0 && !context.inMineral))) {
+      const availableDirs = dirs.length ? dirs.join(', ') : 'api/ (flat)';
+      console.error(`Invalid --dir "${ cliArgs.dir }". Available: ${ availableDirs }`);
       process.exitCode = 1;
       return;
     }
 
-    const exampleFiles = sortExampleFiles(await findExampleFiles(path.join(apiDirectory, cliArgs.dir)));
+    const exampleFiles = await getExampleFilesForContext({ context, dir });
 
     try {
-      const selectedTemplate = await resolveTemplateFromArg(exampleFiles, cliArgs.template, cliArgs.dir);
-      console.log(`Using template: ${ path.relative(path.join(__dirname, '..'), selectedTemplate) }`);
+      const selectedTemplate = await resolveTemplateFromArg({
+        exampleFiles,
+        templateArg: cliArgs.template,
+        dir,
+        inMineral: context.inMineral,
+      });
+
+      const templateLabel = path.relative(mineralRoot, selectedTemplate);
+      console.log(`Using template: ${ templateLabel }`);
 
       await writeNewFunction({
-        dir: cliArgs.dir,
+        apiDirectory: context.apiDirectory,
+        dir,
         name: cliArgs.name,
         selectedTemplate,
         shouldAutoCommit: process.env.AUTO_COMMIT_STUBS === 'true' || cliArgs.commit,
@@ -342,11 +547,16 @@ const createNewFunction = async () => {
 
   try {
     const dir = await selectDirInteractive(dirs);
-    const exampleFiles = sortExampleFiles(await findExampleFiles(path.join(apiDirectory, dir)));
-    const selectedTemplate = await selectTemplateInteractive(exampleFiles, dir);
+    const exampleFiles = await getExampleFilesForContext({ context, dir });
+    const selectedTemplate = await selectTemplateInteractive({
+      exampleFiles,
+      dir,
+      inMineral: context.inMineral,
+    });
     const name = await selectNameInteractive(dir);
 
     await writeNewFunction({
+      apiDirectory: context.apiDirectory,
       dir,
       name,
       selectedTemplate,

package/api/shopify/shopifyDecodeSessionToken.js

@@ -0,0 +1,206 @@
+// https://shopify.dev/docs/apps/build/authentication-authorization/session-tokens/set-up-session-tokens
+
+const crypto = require('crypto');
+const { credsFromPayload, ArgsWarden } = require('../utils');
+const { credsValidator } = require('../validators');
+
+const sessionTokenValidator = (sessionToken) => {
+  return typeof sessionToken === 'string' && Boolean(sessionToken.trim());
+};
+
+const argsWarden = new ArgsWarden([
+  ['credsPayload', credsValidator],
+  ['sessionToken', sessionTokenValidator],
+]);
+
+const base64UrlDecodeJson = (input) => {
+  const base64 = input.replace(/-/g, '+').replace(/_/g, '/');
+  const padding = '='.repeat((4 - base64.length % 4) % 4);
+
+  return JSON.parse(Buffer.from(`${ base64 }${ padding }`, 'base64').toString('utf8'));
+};
+
+const normalizeSessionToken = (sessionToken) => {
+  const trimmedToken = sessionToken.trim();
+
+  if (trimmedToken.toLowerCase().startsWith('bearer ')) {
+    return trimmedToken.slice(7).trim();
+  }
+
+  return trimmedToken;
+};
+
+const verifySessionTokenSignature = (token, apiSecret) => {
+  const [encodedHeader, encodedPayload, signature] = token.split('.');
+
+  if (!encodedHeader || !encodedPayload || !signature) {
+    return false;
+  }
+
+  const message = `${ encodedHeader }.${ encodedPayload }`;
+  const computedSignature = crypto
+    .createHmac('sha256', apiSecret)
+    .update(message)
+    .digest('base64url');
+
+  return computedSignature === signature;
+};
+
+const validateSessionTokenClaims = (
+  decoded,
+  {
+    checkAudience = true,
+    clientId,
+  } = {},
+) => {
+  const {
+    iss,
+    dest,
+    aud,
+    exp,
+    nbf,
+  } = decoded;
+
+  const currentTime = Math.floor(Date.now() / 1000);
+  const expValid = exp > currentTime;
+  const nbfValid = nbf <= currentTime;
+  const domainsValid = dest?.includes('myshopify.com') && iss?.includes('myshopify.com');
+  const audValid = !checkAudience || aud === clientId;
+
+  return expValid && nbfValid && domainsValid && audValid;
+};
+
+const decodeSessionTokenPayload = (token) => {
+  const encodedPayload = token.split('.')[1];
+
+  if (!encodedPayload) {
+    return null;
+  }
+
+  try {
+    return base64UrlDecodeJson(encodedPayload);
+  } catch (error) {
+    return null;
+  }
+};
+
+const shopifyDecodeSessionToken = async (
+  credsPayload,
+  sessionToken,
+  {
+    checkAudience = true,
+  } = {},
+) => {
+
+  const rejectResponse = await argsWarden.responseIfRejectingArgs({
+    credsPayload,
+    sessionToken,
+  });
+  if (rejectResponse) {
+    return rejectResponse;
+  }
+
+  const creds = await credsFromPayload(credsPayload);
+  const {
+    API_SECRET,
+    CLIENT_ID,
+  } = creds;
+
+  if (!API_SECRET || !CLIENT_ID) {
+    return {
+      ok: false,
+      error: {
+        code: 'INVALID_CREDS',
+        message: 'API_SECRET and CLIENT_ID are required.',
+      },
+    };
+  }
+
+  const token = normalizeSessionToken(sessionToken);
+  const decoded = decodeSessionTokenPayload(token);
+
+  if (!decoded) {
+    return {
+      ok: false,
+      error: {
+        code: 'INVALID_SESSION_TOKEN',
+        message: 'Session token could not be decoded.',
+      },
+    };
+  }
+
+  if (!verifySessionTokenSignature(token, API_SECRET)) {
+    return {
+      ok: false,
+      error: {
+        code: 'INVALID_SESSION_TOKEN',
+        message: 'Session token signature is invalid.',
+      },
+    };
+  }
+
+  if (!validateSessionTokenClaims(decoded, {
+    checkAudience,
+    clientId: CLIENT_ID,
+  })) {
+    return {
+      ok: false,
+      error: {
+        code: 'INVALID_SESSION_TOKEN',
+        message: 'Session token claims are invalid.',
+        details: decoded,
+      },
+    };
+  }
+
+  return {
+    ok: true,
+    data: decoded,
+  };
+};
+
+const funcApiConfig = {
+  argsWarden,
+};
+
+module.exports = {
+  shopifyDecodeSessionToken,
+  funcApiConfig,
+};
+
+/*
+curl -X POST "http://localhost:8000/shopifyDecodeSessionToken" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "credsPayload": { "credsPath": "tender.prod" },
+    "sessionToken": "<jwt>"
+  }'
+*/
+
+/*
+  Legacy usage:
+  const whichApp = req.headers['x-wf-app'];
+
+  const sessionToken = req?.headers?.authorization?.split(' ')?.pop();
+  if (!sessionToken) {
+    return respond(res, 401, {
+      error: 'Unauthorized: No session token',
+    });
+  }
+
+  const sessionTokenData = shopifyDecodeSessionToken(sessionToken, {
+    ...whichApp && { credsPath: whichApp },
+  });
+
+  const {
+    dest,
+    sub: customerGid,
+  } = sessionTokenData;
+
+  const config = domainToConfig(dest);
+  if (!config) {
+    return respond(res, 401, {
+      error: 'No config found for domain',
+    });
+  }
+*/

package/api/slack/slack.constants.js

@@ -0,0 +1,5 @@
+const SLACK_API_BASE_URL = 'https://slack.com/api';
+
+module.exports = {
+  SLACK_API_BASE_URL,
+};