@foxtware/mineral 0.1.0

package/.creds.yml.sample

@@ -0,0 +1,21 @@
+shopify:
+  au:
+    STORE_HANDLE: ________________________
+    API_KEY: shpat________________________
+
+peoplevox:
+  CLIENT_ID: _____________________________
+  USERNAME: ______________________________
+  PASSWORD: ______________________________
+
+youtube:
+  API_KEY: _______________________________
+
+yotpo:
+  au:
+    API_KEY: _____________________________
+    GUID: ________________________________
+    MERCHANT_ID: _________________________
+
+linear:
+  API_KEY: _______________________________

package/AGENTS.md

@@ -0,0 +1,13 @@
+# Mineral — agent instructions
+
+Notes for AI assistants working in this directory. **Read this file at the start of mineral tasks** and follow anything here that isn't overridden by the user in chat.
+
+## Misc
+- When working in shopify, refer to gids (gid://shopify/Page/12345678) explicitly as "gids", and use "id" to refer to the number itself (12345678). "id" may still be required for use of the GraphQL API but semantically we should make this distinction.
+- funcApiConfig should not list `options` in `argNames` — it is optional. When present on the request body, `funcApi` appends it after the named args.
+- When implementing API functions that mirror official functions, include a link to the documentation at the top of the file as a comment.
+- Don't add to this file unless asked.
+- Use snake_case for package.json commands, with colon if appropriate.
+- Use newlines and trailing commas where appropriate to minimise future diffs, e.g. in function args.
+- If you make a new .env or .creds.yml variable, update the correlating .sample file.
+- In Shopify, don't normalise and take gids as inputs if you can just take the id - the non-gid number - instead.

package/README.md

@@ -0,0 +1,52 @@
+# mineral
+
+The [bedrock](https://github.com/GorgonFreeman/bedrock) middleware, refactored for compatibility with other projects and more consistent standards.
+
+## Problems with bedrock
+
+- **Inconsistent response format**
+  - `success: true` vs `success: false` for calls that succeed but return no data
+  - No distinction between technical failures and valid business errors
+  - Mixed use of `error` vs `errors` in responses
+- **Portability** — `.creds.yml` and related structures resist reuse outside the repo
+- **Auth** — helpers can fail without retrying, especially when using creds from Upstash
+- **Architecture** — boundaries between core and private functions could be firmer
+
+## The plan
+
+- **The response format to rule them all**
+  ```typescript
+  interface Response {
+    ok: boolean
+    data?: unknown
+    error?: {
+      code: string
+      message: string
+      details?: unknown
+    }
+    meta?: {
+      page?: number
+      pageSize?: number
+      total?: number
+      [key: string]: unknown
+    }
+    results?: Response[]
+  }
+  ```
+  - `ok` — `true` if the intent executed; `false` otherwise
+  - `data` — any info returned
+  - `error` — when present, multiple errors go in `error.details`
+  - `meta` — pagination, total items, etc.
+  - `results` — array of responses from a queue or batch of calls
+  - [Examples](_docs/standard_response_examples.md)
+- **BYO Creds**
+  ```
+  {
+    credsPath,
+    shopifyCredsPath,
+    credsObject,
+    credsProvider, // function that returns a credsObject
+  }
+  ```
+- **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. In the serve functions, allow it to operate from a different directory, finding .hosting.yml, .creds.yml, etc. within it.

package/_build_scripts/copyCredsToEnv.js

@@ -0,0 +1,45 @@
+const fs = require('fs').promises;
+const path = require('path');
+const yaml = require('yaml');
+
+const mineralRoot = path.join(__dirname, '..');
+const credsYmlPath = path.join(mineralRoot, '.creds.yml');
+const envPath = path.join(mineralRoot, '.env');
+
+(async () => {
+  const credsText = await fs.readFile(credsYmlPath, 'utf8');
+  const credsFromYml = yaml.parse(credsText);
+  const credsJsonString = JSON.stringify(credsFromYml);
+  const newCredsLine = `CREDS=${ credsJsonString }`;
+
+  let envFileContents = '';
+  try {
+    envFileContents = await fs.readFile(envPath, 'utf8');
+  } catch (err) {
+    if (err.code !== 'ENOENT') {
+      throw err;
+    }
+  }
+
+  if (!envFileContents) {
+    await fs.writeFile(envPath, `${ newCredsLine }\n`);
+    console.log('Created .env with CREDS');
+    return;
+  }
+
+  if (/^CREDS=/m.test(envFileContents)) {
+    const updatedFileContents = envFileContents.replace(/^CREDS=.*$/m, newCredsLine);
+
+    if (updatedFileContents === envFileContents) {
+      console.log('CREDS already up to date');
+      return;
+    }
+
+    await fs.writeFile(envPath, updatedFileContents);
+    console.log('Updated CREDS in .env');
+    return;
+  }
+
+  await fs.appendFile(envPath, `\n\n${ newCredsLine }\n`);
+  console.log('Appended CREDS to .env');
+})();

package/_build_scripts/createNewFunction.js

@@ -0,0 +1,361 @@
+const fs = require('fs').promises;
+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 excludedDirs = new Set([
+  'node_modules',
+]);
+
+const printHelp = () => {
+  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)
+  --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
+  --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
+`);
+};
+
+const parseCliArgs = (argv) => {
+  const args = {
+    dir: null,
+    name: null,
+    template: null,
+    commit: false,
+    help: false,
+  };
+
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+
+    if (arg === 'commit') {
+      args.commit = true;
+      continue;
+    }
+
+    if (arg === '--help' || arg === '-h') {
+      args.help = true;
+      continue;
+    }
+
+    if (arg === '--commit') {
+      args.commit = true;
+      continue;
+    }
+
+    if (arg === '--dir' || arg === '-d') {
+      args.dir = argv[++i];
+      continue;
+    }
+
+    if (arg === '--name' || arg === '-n') {
+      args.name = argv[++i];
+      continue;
+    }
+
+    if (arg === '--template' || arg === '-t') {
+      args.template = argv[++i];
+      continue;
+    }
+
+    if (arg.startsWith('--dir=')) {
+      args.dir = arg.slice('--dir='.length);
+      continue;
+    }
+
+    if (arg.startsWith('--name=')) {
+      args.name = arg.slice('--name='.length);
+      continue;
+    }
+
+    if (arg.startsWith('--template=')) {
+      args.template = arg.slice('--template='.length);
+      continue;
+    }
+  }
+
+  return args;
+};
+
+const gitCommitAll = (message) => {
+  console.log('Committing in background (2 second delay)...');
+
+  const commitProcess = spawn('sh', ['-c', `sleep 2 && git add . && git commit -m '${ message }'`], {
+    detached: true,
+    stdio: 'ignore',
+  });
+
+  commitProcess.unref();
+};
+
+const findExampleFiles = async (dirPath) => {
+  try {
+    const files = await fs.readdir(dirPath);
+    const exampleFiles = files.filter(file => file.startsWith('_example'));
+
+    return exampleFiles.map(file => {
+      const match = file.match(/^_example(?:\.(.+))?\.js$/);
+      if (match) {
+        return {
+          filename: file,
+          displayName: match[1] || '_example.js',
+          fullPath: path.join(dirPath, file),
+        };
+      }
+      return null;
+    }).filter(Boolean);
+  } catch (err) {
+    return [];
+  }
+};
+
+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 normalizeTemplateArg = (templateArg) => {
+  if (!templateArg) {
+    return null;
+  }
+
+  if (templateArg.endsWith('.js')) {
+    return templateArg;
+  }
+
+  if (templateArg.startsWith('_example')) {
+    return `${ templateArg }.js`;
+  }
+
+  return `_example.${ templateArg }.js`;
+};
+
+const resolveTemplateFromArg = async (exampleFiles, templateArg, dir) => {
+  if (!templateArg) {
+    const defaultInDir = exampleFiles.find(file => file.displayName === '_example.js');
+    if (defaultInDir) {
+      return defaultInDir.fullPath;
+    }
+
+    await fs.access(rootExampleJsPath);
+    return rootExampleJsPath;
+  }
+
+  const normalizedFilename = normalizeTemplateArg(templateArg);
+
+  const matchInDir = exampleFiles.find(file => {
+    return file.filename === normalizedFilename
+      || file.displayName === templateArg
+      || file.displayName === normalizedFilename;
+  });
+
+  if (matchInDir) {
+    return matchInDir.fullPath;
+  }
+
+  if (normalizedFilename === '_example.js') {
+    await fs.access(rootExampleJsPath);
+    return rootExampleJsPath;
+  }
+
+  throw new Error(`Template not found: ${ templateArg } (looked for ${ normalizedFilename } in api/${ dir })`);
+};
+
+const scriptFileContents = async (name, selectedTemplate) => {
+  const exampleFileContents = await fs.readFile(selectedTemplate, 'utf-8');
+  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 buildFuncName = (dir, name) => {
+  const hasUnderscore = dir?.includes('_');
+  const separator = hasUnderscore ? '_' : '';
+  const formattedName = hasUnderscore ? name : capitaliseString(name);
+  return dir ? `${ dir }${ separator }${ formattedName }` : name;
+};
+
+const selectDirInteractive = async (dirs) => {
+  const dirIndex = await askQuestion(`Where does your new function live? \n${
+    dirs.map((dir, index) => {
+      return `[${ index + 1 }] ${ dir }`;
+    }).join('\n')
+  }\n`);
+
+  const dir = dirs[dirIndex - 1];
+
+  if (!dir) {
+    throw new Error(`${ dirIndex } not a valid option.`);
+  }
+
+  return dir;
+};
+
+const selectTemplateInteractive = async (exampleFiles, dir) => {
+  if (exampleFiles.length === 0) {
+    await fs.access(rootExampleJsPath);
+    console.log('\nUsing template: api/_example.js');
+    return rootExampleJsPath;
+  }
+
+  if (exampleFiles.length === 1) {
+    console.log(`\nUsing template: ${ exampleFiles[0].displayName }`);
+    return exampleFiles[0].fullPath;
+  }
+
+  console.log(`\nFound ${ exampleFiles.length } template(s) in api/${ dir }:`);
+  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 }`;
+    }).join('\n')
+  }\n`);
+
+  if (!templateIndex || templateIndex.trim() === '') {
+    const defaultFile = exampleFiles.find(file => file.displayName === '_example.js');
+    if (defaultFile) {
+      return defaultFile.fullPath;
+    }
+
+    await fs.access(rootExampleJsPath);
+    console.log('\nUsing template: api/_example.js');
+    return rootExampleJsPath;
+  }
+
+  const selectedFile = exampleFiles[templateIndex - 1];
+  if (!selectedFile) {
+    throw new Error(`${ templateIndex } not a valid option.`);
+  }
+
+  return selectedFile.fullPath;
+};
+
+const selectNameInteractive = async (dir) => {
+  const promptSuffix = dir?.includes('_') ? `${ dir }_` : dir;
+  const name = await askQuestion(`What do you want to call it? ${ promptSuffix }`);
+
+  if (!name) {
+    throw new Error('Error getting script name');
+  }
+
+  return name;
+};
+
+const writeNewFunction = async ({
+  dir,
+  name,
+  selectedTemplate,
+  shouldAutoCommit,
+}) => {
+  const funcName = buildFuncName(dir, name);
+  const outputPath = path.join(apiDirectory, dir, `${ funcName }.js`);
+
+  try {
+    await fs.access(outputPath);
+    throw new Error(`File already exists: ${ outputPath }`);
+  } catch (err) {
+    if (err.code !== 'ENOENT') {
+      throw err;
+    }
+  }
+
+  const script = await scriptFileContents(funcName, selectedTemplate);
+  await fs.writeFile(outputPath, script);
+
+  console.log(`\nCreated ${ outputPath }`);
+
+  if (shouldAutoCommit) {
+    gitCommitAll(`${ funcName } stub`);
+  }
+
+  return outputPath;
+};
+
+const createNewFunction = async () => {
+  const cliArgs = parseCliArgs(process.argv.slice(2));
+
+  if (cliArgs.help) {
+    printHelp();
+    return;
+  }
+
+  const dirs = await getDirs();
+  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();
+      process.exitCode = 1;
+      return;
+    }
+
+    if (!dirs.includes(cliArgs.dir)) {
+      console.error(`Invalid --dir "${ cliArgs.dir }". Available: ${ dirs.join(', ') }`);
+      process.exitCode = 1;
+      return;
+    }
+
+    const exampleFiles = sortExampleFiles(await findExampleFiles(path.join(apiDirectory, cliArgs.dir)));
+
+    try {
+      const selectedTemplate = await resolveTemplateFromArg(exampleFiles, cliArgs.template, cliArgs.dir);
+      console.log(`Using template: ${ path.relative(path.join(__dirname, '..'), selectedTemplate) }`);
+
+      await writeNewFunction({
+        dir: cliArgs.dir,
+        name: cliArgs.name,
+        selectedTemplate,
+        shouldAutoCommit: process.env.AUTO_COMMIT_STUBS === 'true' || cliArgs.commit,
+      });
+    } catch (err) {
+      console.error(err.message || err);
+      process.exitCode = 1;
+    }
+
+    return;
+  }
+
+  try {
+    const dir = await selectDirInteractive(dirs);
+    const exampleFiles = sortExampleFiles(await findExampleFiles(path.join(apiDirectory, dir)));
+    const selectedTemplate = await selectTemplateInteractive(exampleFiles, dir);
+    const name = await selectNameInteractive(dir);
+
+    await writeNewFunction({
+      dir,
+      name,
+      selectedTemplate,
+      shouldAutoCommit: process.env.AUTO_COMMIT_STUBS === 'true' || cliArgs.commit,
+    });
+  } catch (err) {
+    console.error(err.message || err);
+    process.exitCode = 1;
+  }
+};
+
+createNewFunction();

package/_docs/standard_response_examples.md

@@ -0,0 +1,67 @@
+# Response examples
+
+Examples of the [mineral response format](../README.md#the-plan).
+
+```typescript
+// Fetch product by ID — found
+{ ok: true, data: { id: ... } }
+
+// Fetch product by ID — not found
+{
+  ok: false,
+  error: {
+    code: "NOT_FOUND",
+    message: "Product sku-999 does not exist",
+  },
+}
+
+// Fetch collection — results
+{
+  ok: true,
+  data: [ { id: "sku-001" }, { id: "sku-002" } ],
+  meta: { total: 2 },
+}
+
+// Fetch collection — none found
+{
+  ok: true,
+  data: [],
+  meta: { total: 0 },
+}
+
+// Delete product — success
+{
+  ok: true,
+}
+
+// Mutate single product — validation failure
+{
+  ok: false,
+  error: {
+    code: "INVALID_PRICE",
+    message: "Price cannot be negative",
+    field: "price",
+  },
+}
+
+// Batch mutate — mixed results
+{
+  ok: false,
+  results: [
+    {
+      ok: true,
+      data: { id: "sku-001", price: "49.95" },
+    },
+    {
+      ok: false,
+      meta: { id: "sku-002" },
+      error: {
+        code: "INVALID_PRICE", 
+        message: "Price cannot be negative", 
+        field: "price",
+      },
+    },
+  ],
+  meta: { total: 2, succeeded: 1, failed: 1 },
+}
+```

package/api/_example.js

@@ -0,0 +1,45 @@
+const { credsValidator } = require('./validators');
+const { ArgsWarden } = require('./utils');
+
+const argsWarden = new ArgsWarden([
+  ['credsPayload', credsValidator],
+  ['arg'],
+]);
+
+const FUNC = async (
+  credsPayload,
+  arg,
+  options = {},
+) => {
+
+  const rejectResponse = await argsWarden.responseIfRejectingArgs({ credsPayload, arg });
+  if (rejectResponse) {
+    return rejectResponse;
+  }
+
+  return {
+    ok: true,
+    data: {
+      arg,
+      options,
+    },
+  };
+};
+
+const funcApiConfig = {
+  argsWarden,
+};
+
+module.exports = {
+  FUNC,
+  funcApiConfig,
+};
+
+/*
+curl -X POST "http://localhost:8000/FUNC" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "credsPayload": { "credsPath": "shopify.au" },
+    "arg": "1234"
+  }'
+*/

package/api/constants.js

@@ -0,0 +1,3 @@
+module.exports = {
+  HOSTED: !!process.env.HOSTED,
+};

package/api/linear/linear.constants.js

@@ -0,0 +1,5 @@
+const LINEAR_GRAPHQL_URL = 'https://api.linear.app/graphql';
+
+module.exports = {
+  LINEAR_GRAPHQL_URL,
+};

package/api/linear/linear.utils.js

@@ -0,0 +1,43 @@
+const { LINEAR_GRAPHQL_URL } = require('../linear/linear.constants');
+const {
+  FetchClient,
+  Chain,
+  fetchClientCommonSteps,
+} = require('../utils');
+
+const addUrlAndAuthHeaders = async (state) => {
+  const { requestPayload, context } = state;
+  const { creds } = context;
+  const { API_KEY } = creds;
+
+  return {
+    requestPayload: {
+      ...requestPayload,
+      url: requestPayload.url || LINEAR_GRAPHQL_URL,
+      method: requestPayload.method || 'post',
+      headers: {
+        'Content-Type': 'application/json',
+        Authorization: API_KEY,
+        ...requestPayload.headers,
+      },
+    },
+  };
+};
+
+const linearClientRequestPreparer = new Chain([
+  addUrlAndAuthHeaders,
+]);
+
+const linearClientResponseInterpreter = new Chain([
+  fetchClientCommonSteps.exitEarlyOnNotOk,
+  fetchClientCommonSteps.exitEarlyOnGraphqlErrors,
+]);
+
+const linearClient = new FetchClient({
+  requestPreparer: linearClientRequestPreparer,
+  responseInterpreter: linearClientResponseInterpreter,
+});
+
+module.exports = {
+  linearClient,
+};