@foxtware/mineral 1.0.4 → 1.0.7

package/.creds.yml.sample

@@ -31,6 +31,7 @@ github:
 
 slack:
   BOT_TOKEN: xoxb_________________________
+  USER_TOKEN: xoxp_________________________
 
 workable:
   BASE_URL: https://__.workable.com/spi/v3

package/_build_scripts/createNewFunction.js

@@ -2,6 +2,7 @@ const fs = require('fs').promises;
 const path = require('path');
 const { spawn } = require('child_process');
 const { askQuestion, capitaliseString } = require('../api/utils');
+const choicy = require('choicy');
 
 const mineralRoot = path.join(__dirname, '..');
 const mineralApiDirectory = path.join(mineralRoot, 'api');
@@ -366,22 +367,17 @@ const selectDirInteractive = async (dirs) => {
     return '';
   }
 
-  const dirIndex = await askQuestion(`Where does your new function live? \n${
+  const dir = await choicy(
     [
-      '[0] api/ (root)',
-      ...dirs.map((dir, index) => `[${ index + 1 }] ${ dir }`),
-    ].join('\n')
-  }\n`);
-
-  if (String(dirIndex) === '0') {
-    return '';
-  }
-
-  const dir = dirs[dirIndex - 1];
-
-  if (!dir) {
-    throw new Error(`${ dirIndex } not a valid option.`);
-  }
+      { title: 'api/ (root)', value: '' },
+      ...dirs.map((dirName) => ({ title: dirName, value: dirName })),
+    ],
+    {
+      question: 'Where does your new function live?',
+      oneChoice: true,
+      index0: true,
+    },
+  );
 
   return dir;
 };
@@ -434,32 +430,18 @@ const selectTemplateInteractive = async ({ exampleFiles, dir, inMineral }) => {
   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 }] ${ formatTemplateLabel(file, { inMineral }) }`;
-    }).join('\n')
-  }\n`);
-
-  if (!templateIndex || templateIndex.trim() === '') {
-    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: _example.js');
-    return rootExampleJsPath;
-  }
-
-  const selectedFile = exampleFiles[templateIndex - 1];
-  if (!selectedFile) {
-    throw new Error(`${ templateIndex } not a valid option.`);
-  }
-
-  return selectedFile.fullPath;
+  const selectedPath = await choicy(
+    exampleFiles.map((file) => ({
+      title: formatTemplateLabel(file, { inMineral }),
+      value: file.fullPath,
+    })),
+    {
+      question: 'Which template would you like to use?',
+      oneChoice: true,
+    },
+  );
+
+  return selectedPath;
 };
 
 const selectNameInteractive = async (dir) => {

package/api/UTILS.md

@@ -45,7 +45,7 @@ Cheat sheet for [`utils.js`](utils.js). Prefer this over cold-grepping the file.
 | `surveyObject` | Summarise / compare object fields for assess steps. |
 | `diffObjects` | Field-level diffs between source and target. |
 | `logDeep` | Deep console dump (local inspect). |
-| `askQuestion` | Interactive confirm when `!HOSTED`. |
+| `askQuestion` | Free-text prompt / inspect pause when `!HOSTED`. For discrete options, use npm `choicy` directly. |
 
 ## Small helpers often needed
 

package/api/bleckmann/bleckmannPickticketGet.js

@@ -1,7 +1,7 @@
 // https://app.swaggerhub.com/apis-docs/Bleckmann/warehousing/1.5.2#/PICKTICKET/getPickticketForId
 
 const { credsValidator } = require('../validators');
-const { ArgsWarden, objHasAny, oneFromManyInResponse } = require('../utils');
+const { ArgsWarden, objHasAny, oneFromManyResponse } = require('../utils');
 const { bleckmannClient } = require('../bleckmann/bleckmann.utils');
 const { bleckmannPickticketsGet } = require('../bleckmann/bleckmannPickticketsGet');
 
@@ -54,7 +54,9 @@ const bleckmannPickticketGet = async (
     },
   );
 
-  return oneFromManyInResponse(response, 'reference', pickticketReference);
+  return oneFromManyResponse(response, { 
+    validator: i => i?.reference === pickticketReference,
+  });
 };
 
 const funcApiConfig = {

package/api/github/githubActionsSecretCreateOrUpdate.js

@@ -0,0 +1,139 @@
+// https://docs.github.com/en/rest/actions/secrets#create-or-update-a-repository-secret
+// https://docs.github.com/en/rest/actions/secrets#get-a-repository-public-key
+
+const sodium = require('libsodium-wrappers');
+const { ArgsWarden } = require('../utils');
+const { credsValidator } = require('../validators');
+const { githubClient } = require('../github/github.utils');
+const { githubActionsSecretPublicKeyGet } = require('../github/githubActionsSecretPublicKeyGet');
+
+const argsWarden = new ArgsWarden([
+  ['credsPayload', credsValidator],
+  ['owner'],
+  ['repo'],
+  ['secretName'],
+  ['secretValue'],
+]);
+
+const encryptSecretValue = async (secretValue, publicKey) => {
+  await sodium.ready;
+
+  const binaryKey = sodium.from_base64(publicKey, sodium.base64_variants.ORIGINAL);
+  const binarySecret = sodium.from_string(String(secretValue));
+  const encryptedBytes = sodium.crypto_box_seal(binarySecret, binaryKey);
+
+  return sodium.to_base64(encryptedBytes, sodium.base64_variants.ORIGINAL);
+};
+
+const githubActionsSecretCreateOrUpdate = async (
+  credsPayload,
+  owner,
+  repo,
+  secretName,
+  secretValue,
+  {
+    apiVersion,
+    keyId,
+    publicKey,
+  } = {},
+) => {
+
+  const rejectResponse = await argsWarden.responseIfRejectingArgs({
+    credsPayload,
+    owner,
+    repo,
+    secretName,
+    secretValue,
+  });
+  if (rejectResponse) {
+    return rejectResponse;
+  }
+
+  let resolvedKeyId = keyId;
+  let resolvedPublicKey = publicKey;
+
+  if (!resolvedKeyId || !resolvedPublicKey) {
+    const publicKeyResponse = await githubActionsSecretPublicKeyGet(
+      credsPayload,
+      owner,
+      repo,
+      { apiVersion },
+    );
+
+    if (!publicKeyResponse?.ok) {
+      return publicKeyResponse;
+    }
+
+    resolvedKeyId = publicKeyResponse.data.key_id;
+    resolvedPublicKey = publicKeyResponse.data.key;
+  }
+
+  const encryptedValue = await encryptSecretValue(secretValue, resolvedPublicKey);
+
+  const response = await githubClient.fetch({
+    requestPayload: {
+      method: 'put',
+      url: `/repos/${ owner }/${ repo }/actions/secrets/${ encodeURIComponent(secretName) }`,
+      body: {
+        encrypted_value: encryptedValue,
+        key_id: resolvedKeyId,
+      },
+      responseParser: async (res) => {
+        const text = await res.text();
+        if (!text) {
+          return {
+            secretName,
+            status: res.status,
+          };
+        }
+        try {
+          return JSON.parse(text);
+        } catch {
+          return {
+            secretName,
+            status: res.status,
+            body: text,
+          };
+        }
+      },
+    },
+    context: {
+      credsPayload,
+      apiVersion,
+    },
+  });
+
+  if (!response?.ok) {
+    return response;
+  }
+
+  return {
+    ok: true,
+    data: {
+      secretName,
+      ...(response.data || {}),
+    },
+  };
+};
+
+const funcApiConfig = {
+  argsWarden,
+};
+
+module.exports = {
+  githubActionsSecretCreateOrUpdate,
+  encryptSecretValue,
+  funcApiConfig,
+};
+
+/*
+curl -X POST "http://localhost:8000/githubActionsSecretCreateOrUpdate" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "credsPayload": { "credsPath": "github" },
+    "owner": "whitefoxboutique",
+    "repo": "whitefox-shopify-theme",
+    "secretName": "REGIONS",
+    "secretValue": "au,us,uk"
+  }'
+*/

package/api/github/githubActionsSecretPublicKeyGet.js

@@ -0,0 +1,59 @@
+// https://docs.github.com/en/rest/actions/secrets#get-a-repository-public-key
+
+const { ArgsWarden } = require('../utils');
+const { credsValidator } = require('../validators');
+const { githubClient } = require('../github/github.utils');
+
+const argsWarden = new ArgsWarden([
+  ['credsPayload', credsValidator],
+  ['owner'],
+  ['repo'],
+]);
+
+const githubActionsSecretPublicKeyGet = async (
+  credsPayload,
+  owner,
+  repo,
+  {
+    apiVersion,
+  } = {},
+) => {
+
+  const rejectResponse = await argsWarden.responseIfRejectingArgs({
+    credsPayload,
+    owner,
+    repo,
+  });
+  if (rejectResponse) {
+    return rejectResponse;
+  }
+
+  return githubClient.fetch({
+    requestPayload: {
+      url: `/repos/${ owner }/${ repo }/actions/secrets/public-key`,
+    },
+    context: {
+      credsPayload,
+      apiVersion,
+    },
+  });
+};
+
+const funcApiConfig = {
+  argsWarden,
+};
+
+module.exports = {
+  githubActionsSecretPublicKeyGet,
+  funcApiConfig,
+};
+
+/*
+curl -X POST "http://localhost:8000/githubActionsSecretPublicKeyGet" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "credsPayload": { "credsPath": "github" },
+    "owner": "whitefoxboutique",
+    "repo": "whitefox-shopify-theme"
+  }'
+*/

package/api/google/googlecalendarEventCreate.js

@@ -17,6 +17,7 @@ const googlecalendarEventCreate = async (
   {
     subject,
     calendarId = 'primary',
+    sendUpdates = 'all',
   } = {},
 ) => {
 
@@ -36,6 +37,7 @@ const googlecalendarEventCreate = async (
 
   return googleApiCall(() => client.events.insert({
     calendarId,
+    sendUpdates,
     requestBody: eventData,
   }));
 };

package/api/linear/linearTeamGet.js

@@ -1,6 +1,6 @@
 // https://linear.app/developers/graphql
 
-const { ArgsWarden, objHasAny, oneFromManyInResponse } = require('../utils');
+const { ArgsWarden, objHasAny, oneFromManyResponse } = require('../utils');
 const { credsValidator } = require('../validators');
 const { linearClient } = require('../linear/linear.utils');
 const { linearTeamsGet } = require('./linearTeamsGet');
@@ -52,7 +52,10 @@ const linearTeamGet = async (
     const teamIdProp = teamName ? 'name' : 'key';
     const teamIdValue = teamName ? teamName : teamKey;
 
-    const teamResponse = oneFromManyInResponse(teamsGetResponse, teamIdProp, teamIdValue);
+    const teamResponse = oneFromManyResponse(teamsGetResponse, {
+      validator: i => i[teamIdProp] === teamIdValue,
+    });
+    
     if (teamResponse.ok && teamResponse.data) {
       teamId = teamResponse.data.id;
     }
@@ -109,6 +112,6 @@ curl -X POST "http://localhost:8000/linearTeamGet" \
   -H "Content-Type: application/json" \
   -d '{
     "credsPayload": { "credsPath": "linear" },
-    "teamIdentifier": { "teamName": "Elite Four" }
+    "teamIdentifier": { "teamName": "WF Engineering" }
   }'
 */

package/api/shopify/shopify.constants.js

@@ -4,4 +4,29 @@ module.exports = {
   DEFAULT_API_VERSION,
   MAX_PER_PAGE: 250,
   MAX_METAFIELDS_PER_SET: 25,
+  MAX_INVENTORY_QUANTITIES_PER_SET: 250,
+  INVENTORY_TYPES: [
+    'available',
+    'on_hand',
+  ],
+  // https://shopify.dev/docs/apps/build/orders-fulfillment/inventory-management-apps/manage-quantities-states#set-inventory-quantities-on-hand
+  INVENTORY_REASONS: [
+    'correction',
+    'cycle_count_available',
+    'damaged',
+    'movement_created',
+    'movement_updated',
+    'movement_received',
+    'movement_canceled',
+    'other',
+    'promotion',
+    'quality_control',
+    'received',
+    'reservation_created',
+    'reservation_deleted',
+    'reservation_updated',
+    'restock',
+    'safety_stock',
+    'shrinkage',
+  ],
 };

package/api/shopify/shopify.utils.js

@@ -18,14 +18,24 @@ const handleMutationUserErrors = async (state) => {
     return {};
   }
 
-  const { userErrors, ...mutationResult } = mutationPayload;
+  const {
+    userErrors,
+    customerUserErrors,
+    ...mutationResult
+  } = mutationPayload;
+
+  // Storefront customer mutations use customerUserErrors; cart/admin use userErrors
+  const errors = [
+    ...Array.isArray(userErrors) ? userErrors : [],
+    ...Array.isArray(customerUserErrors) ? customerUserErrors : [],
+  ];
 
-  if (!Array.isArray(userErrors)) {
+  if (!Array.isArray(userErrors) && !Array.isArray(customerUserErrors)) {
     return {};
   }
 
-  if (userErrors.length) {
-    const message = userErrors
+  if (errors.length) {
+    const message = errors
       .map((userError) => userError?.message)
       .filter(Boolean)
       .join('; ');
@@ -36,7 +46,7 @@ const handleMutationUserErrors = async (state) => {
         error: {
           code: 'USER_ERROR',
           message: message || 'Mutation failed',
-          details: userErrors,
+          details: errors,
         },
         ...(Object.keys(mutationResult).length ? { data: mutationResult } : {}),
       },
@@ -51,6 +61,26 @@ const handleMutationUserErrors = async (state) => {
   };
 };
 
+const buildInContextDirective = (inContext) => {
+  if (!inContext || typeof inContext !== 'object') {
+    return '';
+  }
+
+  const parts = [];
+  if (inContext.country) {
+    parts.push(`country: ${ inContext.country }`);
+  }
+  if (inContext.language) {
+    parts.push(`language: ${ inContext.language }`);
+  }
+
+  if (!parts.length) {
+    return '';
+  }
+
+  return ` @inContext(${ parts.join(', ') })`;
+};
+
 const useUrlAndAuthHeaders = async (state) => {
   const { requestPayload, context } = state;
   const {
@@ -187,7 +217,11 @@ const parseShopifyJsonl = (jsonl) => {
         .map((word) => word[0].toUpperCase() + word.slice(1))
         .join('');
       nestedParentType = sentenceCaseString(nestedParentType);
-      parentObject = parentObject[nestedParentType];
+      // Only dig into a nested field when it exists on the parent. InventoryLevel
+      // GIDs use ?inventory_item_id= for uniqueness; __parentId is already the item.
+      if (parentObject[nestedParentType]) {
+        parentObject = parentObject[nestedParentType];
+      }
     }
 
     if (!parentObject) {
@@ -252,4 +286,5 @@ module.exports = {
   shopifyClient,
   shopifyStorefrontClient,
   shopifyProductFlattenMetafields,
+  buildInContextDirective,
 };

package/api/shopify/shopifyInventoryQuantitiesSet.js

@@ -0,0 +1,164 @@
+// https://shopify.dev/docs/api/admin-graphql/latest/mutations/inventorySetQuantities
+
+const { credsValidator } = require('../validators');
+const {
+  ArgsWarden,
+  arrayToChunks,
+  actionSingleOrMultiple,
+  objHasAll,
+  valueProvided,
+} = require('../utils');
+const { shopifyMutationDo } = require('../shopify/shopifyMutationDo');
+const {
+  MAX_INVENTORY_QUANTITIES_PER_SET,
+  INVENTORY_TYPES,
+  INVENTORY_REASONS,
+} = require('../shopify/shopify.constants');
+
+const defaultInventoryAdjustmentGroupReturnAttrs = `
+  createdAt
+  reason
+  changes {
+    name
+    delta
+    quantityAfterChange
+    item {
+      sku
+    }
+  }
+`;
+
+const inventoryQuantityInputValidator = (p) => {
+  return objHasAll(p, ['inventoryItemId', 'locationId', 'quantity']);
+};
+
+const argsWarden = new ArgsWarden([
+  ['credsPayload', credsValidator],
+  ['inventoryType', p => INVENTORY_TYPES.includes(p)],
+  ['quantities', p => Array.isArray(p) && p.length > 0 && p.every(inventoryQuantityInputValidator)],
+  ['reason', p => INVENTORY_REASONS.includes(p)],
+  ['idempotencyKey'],
+]);
+
+const shopifyInventoryQuantitiesSetChunk = async (
+  credsPayload,
+  inventoryType,
+  quantities,
+  reason,
+  idempotencyKey,
+  {
+    apiVersion,
+    inventoryAdjustmentGroupReturnAttrs = defaultInventoryAdjustmentGroupReturnAttrs,
+    referenceDocumentUri,
+  } = {},
+) => {
+
+  const quantitiesForInput = quantities.map(({
+    inventoryItemId,
+    locationId,
+    quantity,
+    changeFromQuantity = null,
+  }) => ({
+    inventoryItemId: `gid://shopify/InventoryItem/${ inventoryItemId }`,
+    locationId: `gid://shopify/Location/${ locationId }`,
+    quantity,
+    changeFromQuantity,
+  }));
+
+  return shopifyMutationDo(
+    credsPayload,
+    'inventorySetQuantities',
+    {
+      mutationVariables: {
+        input: {
+          type: 'InventorySetQuantitiesInput!',
+          value: {
+            name: inventoryType,
+            reason,
+            quantities: quantitiesForInput,
+            ...(valueProvided(referenceDocumentUri) && { referenceDocumentUri }),
+          },
+        },
+      },
+      returnSchema: `inventoryAdjustmentGroup { ${ inventoryAdjustmentGroupReturnAttrs } }`,
+      apiVersion,
+      idempotencyKey,
+    },
+  );
+};
+
+const shopifyInventoryQuantitiesSet = async (
+  credsPayload,
+  inventoryType,
+  quantities,
+  reason,
+  idempotencyKey,
+  {
+    queueRunOptions,
+    apiVersion,
+    inventoryAdjustmentGroupReturnAttrs = defaultInventoryAdjustmentGroupReturnAttrs,
+    referenceDocumentUri,
+  } = {},
+) => {
+
+  const rejectResponse = await argsWarden.responseIfRejectingArgs({
+    credsPayload,
+    inventoryType,
+    quantities,
+    reason,
+    idempotencyKey,
+  });
+  if (rejectResponse) {
+    return rejectResponse;
+  }
+
+  const chunks = arrayToChunks(quantities, MAX_INVENTORY_QUANTITIES_PER_SET);
+
+  return actionSingleOrMultiple(
+    chunks,
+    shopifyInventoryQuantitiesSetChunk,
+    (chunk) => ({
+      args: [
+        credsPayload,
+        inventoryType,
+        chunk,
+        reason,
+        chunks.length === 1 ? idempotencyKey : `${ idempotencyKey }:${ chunks.indexOf(chunk) }`,
+        {
+          apiVersion,
+          inventoryAdjustmentGroupReturnAttrs,
+          referenceDocumentUri,
+        },
+      ],
+    }),
+    {
+      ...(queueRunOptions ? { queueRunOptions } : {}),
+    },
+  );
+};
+
+const funcApiConfig = {
+  argsWarden,
+};
+
+module.exports = {
+  shopifyInventoryQuantitiesSet,
+  funcApiConfig,
+};
+
+/*
+curl -X POST "http://localhost:8000/shopifyInventoryQuantitiesSet" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "credsPayload": { "credsPath": "shopify.wakanda" },
+    "inventoryType": "on_hand",
+    "quantities": [{
+      "inventoryItemId": "1234567890",
+      "locationId": "1234567890",
+      "changeFromQuantity": 10,
+      "quantity": 5
+    }],
+    "reason": "correction",
+    "idempotencyKey": "..."
+  }'
+*/

package/api/shopify/shopifyMutationDo.js

@@ -14,6 +14,7 @@ const shopifyMutationDo = async (
     mutationVariables = {},
     returnSchema = '',
     apiVersion,
+    idempotencyKey,
     ...clientOptions
   } = {},
 ) => {
@@ -30,9 +31,15 @@ const shopifyMutationDo = async (
     returnSchema += ' userErrors { field message }';
   }
 
+  const argumentEntries = Object.entries(mutationVariables);
+  const variableEntries = [
+    ...argumentEntries,
+    ...idempotencyKey ? [['idempotencyKey', { type: 'String!', value: idempotencyKey }]] : [],
+  ];
+
   const mutation = `
-    mutation ${ mutationName }(${ Object.entries(mutationVariables).map(([name, { type }]) => `$${ name }: ${ type }`).join(', ') }) {
-      ${ mutationName }(${ Object.keys(mutationVariables).map(name => `${ name }: $${ name }`).join(', ') }) {
+    mutation ${ mutationName }(${ variableEntries.map(([name, { type }]) => `$${ name }: ${ type }`).join(', ') }) {
+      ${ mutationName }(${ argumentEntries.map(([name]) => `${ name }: $${ name }`).join(', ') })${ idempotencyKey ? ' @idempotent(key: $idempotencyKey)' : '' } {
         ${ returnSchema }
         userErrors {
           field
@@ -42,10 +49,9 @@ const shopifyMutationDo = async (
     }
   `;
 
-  const variables = {};
-  for (const [name, { value }] of Object.entries(mutationVariables)) {
-    variables[name] = value;
-  }
+  const variables = Object.fromEntries(
+    variableEntries.map(([name, { value }]) => [name, value]),
+  );
 
   const response = await shopifyClient.fetch({
     requestPayload: {