@foxtware/mineral 0.1.18 → 0.1.19

package/AGENTS.md

@@ -20,6 +20,7 @@ Notes for AI assistants working in this directory. **Read this file at the start
 - docs.md in each platform should not describe the details of our implementation, handlers or anything relating to Mineral. It is for describing the platform's API itself and does not change based on what we do with it. It should also be brief.
 - Usually when making a function that gets multiples of a resource, it should be implemented as a Getter, with a paginator and digester. If done in this way, export platformThingGet and platformThingGetter, using the .bind() syntax seen in other Get functions.
 - When making functions that act on single resources, consider using actionSingleOrMultiple to allow a queue of actions.
+- When altering .yml files, preserve whitespace formatting.
 
 ## API clients
 - Base URLs for platform clients should live in `{platform}.constants.js`, not creds, if they are static for all users of the API.

package/_build_scripts/createNewFunction.js

@@ -366,11 +366,16 @@ 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')
+    [
+      '[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) {
@@ -510,8 +515,8 @@ const createNewFunction = async () => {
       name: cliArgs.name,
     });
 
-    if (dir === null || (!dirs.includes(dir) && !(dir === '' && dirs.length === 0 && !context.inMineral))) {
-      const availableDirs = dirs.length ? dirs.join(', ') : 'api/ (flat)';
+    if (dir === null || (dir !== '' && !dirs.includes(dir))) {
+      const availableDirs = dirs.length ? `api/ (root), ${ dirs.join(', ') }` : 'api/ (flat)';
       console.error(`Invalid --dir "${ cliArgs.dir }". Available: ${ availableDirs }`);
       process.exitCode = 1;
       return;

package/api/peoplevox/peoplevox.utils.js

@@ -100,6 +100,30 @@ const stripEnvelope = (state) => {
   };
 };
 
+// Peoplevox returns HTTP 200 with ResponseId -1 on failure; Detail holds the message.
+const rejectNegativeResponseId = (state) => {
+  const { response } = state;
+  const { data } = response || {};
+
+  if (!response?.ok || data == null || typeof data !== 'object') {
+    return {};
+  }
+
+  if (Number(data.ResponseId) !== -1) {
+    return {};
+  }
+
+  return {
+    response: {
+      ok: false,
+      data,
+      error: {
+        detail: data.Detail,
+      },
+    },
+  };
+};
+
 const tryToParseDetailAsCsv = async (state) => {
   const { response } = state;
 
@@ -179,6 +203,7 @@ const peoplevoxClient = new FetchClient({
     useSoapEnvelope,
     'fetch',
     stripEnvelope,
+    rejectNegativeResponseId,
     tryToParseDetailAsCsv,
     unwrapSingleDetail,
     hoistDetail,

package/api/shopify/shopifyFulfillmentCreate.js

@@ -0,0 +1,180 @@
+// https://shopify.dev/docs/api/admin-graphql/latest/mutations/fulfillmentCreate
+
+const { credsValidator } = require('../validators');
+const { actionSingleOrMultiple, everyIfArray, ArgsWarden, valueProvided } = require('../utils');
+const { shopifyMutationDo } = require('../shopify/shopifyMutationDo');
+
+const fulfillmentInputValidator = (fulfillmentInput) => {
+  const { lineItemsByFulfillmentOrder } = fulfillmentInput || {};
+  if (!Array.isArray(lineItemsByFulfillmentOrder) || lineItemsByFulfillmentOrder.length === 0) {
+    return false;
+  }
+
+  return lineItemsByFulfillmentOrder.every((item) => {
+    if (!item?.fulfillmentOrderId) {
+      return false;
+    }
+
+    if (item.fulfillmentOrderLineItems) {
+      return item.fulfillmentOrderLineItems.every((lineItem) => {
+        return lineItem?.id && valueProvided(lineItem?.quantity);
+      });
+    }
+
+    return true;
+  });
+};
+
+const argsWarden = new ArgsWarden([
+  ['credsPayload', credsValidator],
+  ['fulfillmentInput', (i) => everyIfArray(fulfillmentInputValidator, i)],
+]);
+
+const defaultReturnFulfillmentAttrs = `
+  id
+  status
+  trackingInfo {
+    number
+    company
+    url
+  }
+`.trim();
+
+const shopifyFulfillmentCreateSingle = async (
+  credsPayload,
+  fulfillmentInput,
+  {
+    apiVersion,
+    message,
+    returnFulfillmentAttrs = defaultReturnFulfillmentAttrs,
+  } = {},
+) => {
+
+  return shopifyMutationDo(
+    credsPayload,
+    'fulfillmentCreate',
+    {
+      mutationVariables: {
+        fulfillment: {
+          type: 'FulfillmentInput!',
+          value: fulfillmentInput,
+        },
+        ...(valueProvided(message) && {
+          message: {
+            type: 'String',
+            value: message,
+          },
+        }),
+      },
+      returnSchema: `
+        fulfillment { ${ returnFulfillmentAttrs } }
+      `.trim(),
+      apiVersion,
+    },
+  );
+};
+
+const shopifyFulfillmentCreate = async (
+  credsPayload,
+  fulfillmentInput,
+  {
+    queueRunOptions,
+    apiVersion,
+    message,
+    returnFulfillmentAttrs = defaultReturnFulfillmentAttrs,
+  } = {},
+) => {
+
+  const rejectResponse = await argsWarden.responseIfRejectingArgs({
+    credsPayload,
+    fulfillmentInput,
+  });
+  if (rejectResponse) {
+    return rejectResponse;
+  }
+
+  return actionSingleOrMultiple(
+    fulfillmentInput,
+    shopifyFulfillmentCreateSingle,
+    (fulfillmentInputItem) => ({
+      args: [
+        credsPayload,
+        fulfillmentInputItem,
+        { apiVersion, message, returnFulfillmentAttrs },
+      ],
+    }),
+    {
+      ...(queueRunOptions ? { queueRunOptions } : {}),
+    },
+  );
+};
+
+const funcApiConfig = {
+  argsWarden,
+};
+
+module.exports = {
+  shopifyFulfillmentCreate,
+  funcApiConfig,
+};
+
+/*
+curl -X POST "http://localhost:8000/shopifyFulfillmentCreate" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "credsPayload": { "credsPath": "shopify.au" },
+    "fulfillmentInput": {
+      "lineItemsByFulfillmentOrder": [
+        {
+          "fulfillmentOrderId": "gid://shopify/FulfillmentOrder/1234567890"
+        }
+      ],
+      "notifyCustomer": true,
+      "trackingInfo": {
+        "number": "1234567890",
+        "company": "Australia Post",
+        "url": "https://auspost.com.au/mypost/track/details/1234567890"
+      }
+    }
+  }'
+
+curl -X POST "http://localhost:8000/shopifyFulfillmentCreate" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "credsPayload": { "credsPath": "shopify.au" },
+    "fulfillmentInput": [
+      {
+        "lineItemsByFulfillmentOrder": [
+          {
+            "fulfillmentOrderId": "gid://shopify/FulfillmentOrder/1234567890"
+          }
+        ],
+        "notifyCustomer": true,
+        "trackingInfo": {
+          "number": "1234567890",
+          "company": "Australia Post"
+        }
+      },
+      {
+        "lineItemsByFulfillmentOrder": [
+          {
+            "fulfillmentOrderId": "gid://shopify/FulfillmentOrder/0987654321",
+            "fulfillmentOrderLineItems": [
+              {
+                "id": "gid://shopify/FulfillmentOrderLineItem/9876543210",
+                "quantity": 1
+              }
+            ]
+          }
+        ],
+        "notifyCustomer": false,
+        "originAddress": {
+          "countryCode": "AU"
+        }
+      }
+    ],
+    "options": {
+      "message": "Partial fulfillment"
+    }
+  }'
+*/

package/api/shopify/shopifyFulfillmentTrackingInfoUpdate.js

@@ -0,0 +1,92 @@
+// https://shopify.dev/docs/api/admin-graphql/latest/mutations/fulfillmentTrackingInfoUpdate
+
+const { credsValidator } = require('../validators');
+const { ArgsWarden } = require('../utils');
+const { shopifyMutationDo } = require('../shopify/shopifyMutationDo');
+
+const defaultReturnSchema = `
+  fulfillment {
+    id
+    status
+    trackingInfo {
+      company
+      number
+      url
+    }
+  }
+`;
+
+const argsWarden = new ArgsWarden([
+  ['credsPayload', credsValidator],
+  ['fulfillmentId'],
+  ['trackingInfoPayload'],
+]);
+
+const shopifyFulfillmentTrackingInfoUpdate = async (
+  credsPayload,
+  fulfillmentId,
+  trackingInfoPayload,
+  {
+    apiVersion,
+    returnSchema = defaultReturnSchema,
+    notifyCustomer = false,
+  } = {},
+) => {
+
+  const rejectResponse = await argsWarden.responseIfRejectingArgs({
+    credsPayload,
+    fulfillmentId,
+    trackingInfoPayload,
+  });
+  if (rejectResponse) {
+    return rejectResponse;
+  }
+
+  return shopifyMutationDo(
+    credsPayload,
+    'fulfillmentTrackingInfoUpdate',
+    {
+      mutationVariables: {
+        fulfillmentId: {
+          type: 'ID!',
+          value: `gid://shopify/Fulfillment/${ fulfillmentId }`,
+        },
+        trackingInfoInput: {
+          type: 'FulfillmentTrackingInput!',
+          value: trackingInfoPayload,
+        },
+        ...notifyCustomer && {
+          notifyCustomer: {
+            type: 'Boolean',
+            value: notifyCustomer,
+          },
+        },
+      },
+      returnSchema,
+      apiVersion,
+    },
+  );
+};
+
+const funcApiConfig = {
+  argsWarden,
+};
+
+module.exports = {
+  shopifyFulfillmentTrackingInfoUpdate,
+  funcApiConfig,
+};
+
+/*
+curl -X POST "http://localhost:8000/shopifyFulfillmentTrackingInfoUpdate" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "credsPayload": { "credsPath": "shopify.au" },
+    "fulfillmentId": "104188477512",
+    "trackingInfoPayload": {
+      "company": "FastEx",
+      "number": "123456789",
+      "url": "https://track.example.com/123456789"
+    }
+  }'
+*/

package/api/shopify/shopifyMetafieldDefinitionPropagate.js

@@ -2,7 +2,7 @@
 // https://shopify.dev/docs/api/admin-graphql/latest/queries/metafieldDefinition
 
 const { credsValidator } = require('../validators');
-const { ArgsWarden, objHasAny } = require('../utils');
+const { ArgsWarden, actionSingleOrMultiple, everyIfArray, objHasAny } = require('../utils');
 const { shopifyMetafieldDefinitionGet } = require('./shopifyMetafieldDefinitionGet');
 const { shopifyMetafieldDefinitionCreate } = require('./shopifyMetafieldDefinitionCreate');
 
@@ -18,8 +18,8 @@ const metafieldDefinitionIdentifierValidator = (metafieldDefinitionIdentifier) =
 
 const argsWarden = new ArgsWarden([
   ['fromStoreCredsPayload', credsValidator],
-  ['toStoreCredsPayload', credsValidator],
-  ['metafieldDefinitionIdentifier', metafieldDefinitionIdentifierValidator],
+  ['toStoreCredsPayload', (i) => everyIfArray(credsValidator, i)],
+  ['metafieldDefinitionIdentifier', (i) => everyIfArray(metafieldDefinitionIdentifierValidator, i)],
 ]);
 
 const metafieldDefinitionInputFromDefinition = (sourceDefinition) => {
@@ -69,7 +69,7 @@ const metafieldDefinitionInputFromDefinition = (sourceDefinition) => {
   return definitionInput;
 };
 
-const shopifyMetafieldDefinitionPropagate = async (
+const shopifyMetafieldDefinitionPropagateSingle = async (
   fromStoreCredsPayload,
   toStoreCredsPayload,
   metafieldDefinitionIdentifier,
@@ -79,15 +79,6 @@ const shopifyMetafieldDefinitionPropagate = async (
   } = {},
 ) => {
 
-  const rejectResponse = await argsWarden.responseIfRejectingArgs({
-    fromStoreCredsPayload,
-    toStoreCredsPayload,
-    metafieldDefinitionIdentifier,
-  });
-  if (rejectResponse) {
-    return rejectResponse;
-  }
-
   const sourceResponse = await shopifyMetafieldDefinitionGet(
     fromStoreCredsPayload,
     metafieldDefinitionIdentifier,
@@ -109,6 +100,29 @@ const shopifyMetafieldDefinitionPropagate = async (
     };
   }
 
+  const existingResponse = await shopifyMetafieldDefinitionGet(
+    toStoreCredsPayload,
+    metafieldDefinitionIdentifier,
+    {
+      apiVersion,
+      attrs: returnCreatedDefinitionAttrs,
+    },
+  );
+
+  if (!existingResponse.ok) {
+    return existingResponse;
+  }
+
+  if (existingResponse.data) {
+    return {
+      ok: true,
+      data: existingResponse.data,
+      meta: {
+        alreadyExisted: true,
+      },
+    };
+  }
+
   const definitionInput = metafieldDefinitionInputFromDefinition(sourceResponse.data);
 
   const {
@@ -143,6 +157,43 @@ const shopifyMetafieldDefinitionPropagate = async (
   );
 };
 
+const shopifyMetafieldDefinitionPropagate = async (
+  fromStoreCredsPayload,
+  toStoreCredsPayload,
+  metafieldDefinitionIdentifier,
+  {
+    queueRunOptions,
+    apiVersion,
+    returnCreatedDefinitionAttrs = defaultReturnCreatedDefinitionAttrs,
+  } = {},
+) => {
+
+  const rejectResponse = await argsWarden.responseIfRejectingArgs({
+    fromStoreCredsPayload,
+    toStoreCredsPayload,
+    metafieldDefinitionIdentifier,
+  });
+  if (rejectResponse) {
+    return rejectResponse;
+  }
+
+  return actionSingleOrMultiple(
+    [toStoreCredsPayload, metafieldDefinitionIdentifier],
+    shopifyMetafieldDefinitionPropagateSingle,
+    (toStoreCredsPayloadItem, metafieldDefinitionIdentifierItem) => ({
+      args: [
+        fromStoreCredsPayload,
+        toStoreCredsPayloadItem,
+        metafieldDefinitionIdentifierItem,
+        { apiVersion, returnCreatedDefinitionAttrs },
+      ],
+    }),
+    {
+      ...(queueRunOptions ? { queueRunOptions } : {}),
+    },
+  );
+};
+
 const funcApiConfig = {
   argsWarden,
 };
@@ -157,11 +208,11 @@ curl -X POST "http://localhost:8000/shopifyMetafieldDefinitionPropagate" \
   -H "Content-Type: application/json" \
   -d '{
     "fromStoreCredsPayload": { "credsPath": "shopify.au" },
-    "toStoreCredsPayload": { "credsPath": "shopify.us" },
+    "toStoreCredsPayload": [{ "credsPath": "shopify.us" }, { "credsPath": "shopify.uk" }],
     "metafieldDefinitionIdentifier": {
       "ownerType": "PRODUCT",
-      "namespace": "custom",
-      "key": "outfit_builder_image"
+      "namespace": "merch",
+      "key": "associations"
     }
   }'
 */

package/api/shopify/shopifyOrderFulfill.js

@@ -0,0 +1,322 @@
+const { credsValidator } = require('../validators');
+const { ArgsWarden, operationQueueRunner, logDeep, askQuestion } = require('../utils');
+const { objHasAny } = require('../utils');
+const { shopifyOrderGet } = require('../shopify/shopifyOrderGet');
+const { shopifyFulfillmentCreate } = require('../shopify/shopifyFulfillmentCreate');
+
+const orderIdentifierValidator = (orderIdentifier) => {
+  return objHasAny(orderIdentifier, [
+    'orderId', 
+    'orderName',
+  ]);
+};
+
+const fulfillmentPayloadValidator = (fulfillmentPayload) => {
+
+  const { 
+    fulfillAll, 
+    itemsBySku,
+    // TODO: Support fulfilling items by line item id
+    
+  } = fulfillmentPayload;
+
+  if (fulfillAll === true) {
+    return true;
+  }
+
+  if (itemsBySku) {
+    const quantities = Object.values(itemsBySku);
+    return quantities.length > 0 && quantities.every(quantity => typeof quantity === 'number');
+  }
+
+  return false;
+};
+
+const argsWarden = new ArgsWarden([
+  ['credsPayload', credsValidator],
+  ['orderIdentifier', orderIdentifierValidator],
+  ['fulfillmentPayload', fulfillmentPayloadValidator],
+]);
+
+const shopifyOrderFulfill = async (
+  credsPayload,
+  orderIdentifier,
+  fulfillmentPayload,
+  {
+    apiVersion,
+    // TODO: Support return schema
+    // returnSchema = 'deletedThingId',
+  } = {},
+) => {
+
+  const rejectResponse = await argsWarden.responseIfRejectingArgs({
+    credsPayload,
+    orderIdentifier,
+    fulfillmentPayload,
+  });
+  if (rejectResponse) {
+    return rejectResponse;
+  }
+
+  const {
+    fulfillAll = false,
+    itemsBySku,
+    notifyCustomer = false,
+    originAddress,
+    trackingInfo,
+  } = fulfillmentPayload;
+
+  const fetchFulfillmentOrdersLimit = 10;
+  const fetchFulfillmentsLimit = 10;
+  const fetchTrackingInfoLimit = 10;
+  const fetchLineItemsLimit = 250;
+
+  const openFulfillmentOrdersQuery = `displayable:true AND (request_status:UNSUBMITTED OR request_status:ACCEPTED)`;
+
+  const ORDER_ATTRS = `
+    fulfillable
+    fulfillments(first: ${ fetchFulfillmentsLimit }) {
+      trackingInfo(first: ${ fetchTrackingInfoLimit }) {
+        number
+      }
+    }
+    fulfillmentOrders(first: ${ fetchFulfillmentOrdersLimit }, query: "${ openFulfillmentOrdersQuery }") {
+      edges {
+        node {
+          id
+          requestStatus
+          ${ itemsBySku ? `
+            lineItems (first: ${ fetchLineItemsLimit }) {
+              edges {
+                node {
+                  id
+                  sku
+                  remainingQuantity
+                  requiresShipping
+                }
+              }
+            }
+          ` : '' }
+        }
+      }
+    }
+  `;
+
+  // Get open fulfillment orders
+  const orderResponse = await shopifyOrderGet(
+    credsPayload,
+    orderIdentifier,
+    {
+      apiVersion,
+      attrs: ORDER_ATTRS,
+    },
+  );
+
+  const { ok: orderOk, data: order } = orderResponse;
+  if (!orderOk || !order) {
+    return orderResponse;
+  }
+
+  const {
+    fulfillable,
+    fulfillments,
+    fulfillmentOrders,
+  } = order;
+
+  if (fulfillments.length >= fetchFulfillmentsLimit) {
+    return {
+      ok: false,
+      error: {
+        code: 'LIMIT_REACHED',
+        message: `We retrieved ${ fetchFulfillmentsLimit } fulfillments, so there may be more. Please adjust the function.`,
+      },
+      data: order,
+    };
+  }
+
+  if (fulfillments.some(f => f?.trackingInfo?.length > fetchTrackingInfoLimit)) {
+    return {
+      ok: false,
+      error: {
+        code: 'LIMIT_REACHED',
+        message: `We retrieved ${ fetchTrackingInfoLimit } tracking info, so there may be more. Please adjust the function.`,
+      },
+      data: order,
+    };
+  }
+
+  if (fulfillmentOrders.length >= fetchFulfillmentOrdersLimit) {
+    return {
+      ok: false,
+      error: {
+        code: 'LIMIT_REACHED',
+        message: `We retrieved ${ fetchFulfillmentOrdersLimit } open fulfillment orders, so there may be more. Please adjust the function.`,
+      },
+      data: order,
+    };
+  }
+
+  if (!fulfillable) {
+    return {
+      ok: false,
+      error: 'Order is not fulfillable',
+      data: order,
+    };
+  }
+
+  const seenTrackingNumbers = fulfillments.map(f => f?.trackingInfo?.map(t => t.number)).flat().filter(Boolean);
+
+  if (trackingInfo?.number && seenTrackingNumbers.includes(trackingInfo.number)) {
+    return {
+      ok: true,
+      meta: {
+        alreadyFulfilled: true,
+        trackingNumber: trackingInfo.number,
+      },
+    };
+  }
+  
+  // if using fulfillAll, fulfill them
+  if (fulfillAll === true) {
+    return shopifyFulfillmentCreate(
+      credsPayload,
+      fulfillmentOrders.map(fulfillmentOrder => {
+        const {
+          id: fulfillmentOrderGid,
+        } = fulfillmentOrder;
+
+        return {
+          lineItemsByFulfillmentOrder: [{
+            fulfillmentOrderId: fulfillmentOrderGid,
+          }],
+          notifyCustomer,
+          originAddress,
+          trackingInfo,
+        };
+      }),
+      {
+        apiVersion,
+      },
+    );
+  }
+  
+  // if using itemsBySku, iterate over unfulfilled line items and decrement until complete, making a queue of fulfillments to action
+  if (itemsBySku) {
+    const depletableItemsBySku = { ...itemsBySku };
+    const shopifyFulfillmentCreatePayloads = [];
+
+    for (const fulfillmentOrder of fulfillmentOrders) {
+      const {
+        id: fulfillmentOrderGid,
+        lineItems = [],
+      } = fulfillmentOrder;
+
+      if (lineItems.length >= fetchLineItemsLimit) {
+        return {
+          ok: false,
+          error: {
+            code: 'LIMIT_REACHED',
+            message: `We retrieved ${ fetchLineItemsLimit } line items on a fulfillment order, so there may be more. Please adjust the function.`,
+          },
+          data: order,
+        };
+      }
+
+      const fulfillmentOrderLineItems = [];
+
+      for (const lineItem of lineItems) {
+        const {
+          id: lineItemGid,
+          sku,
+          remainingQuantity,
+          requiresShipping,
+        } = lineItem;
+
+        if (!requiresShipping || remainingQuantity <= 0) {
+          continue;
+        }
+
+        const depletableQuantity = depletableItemsBySku[sku];
+        if (!depletableQuantity) {
+          continue;
+        }
+
+        const quantity = Math.min(remainingQuantity, depletableQuantity);
+        fulfillmentOrderLineItems.push({
+          id: lineItemGid,
+          quantity,
+        });
+        depletableItemsBySku[sku] -= quantity;
+      }
+
+      if (fulfillmentOrderLineItems.length > 0) {
+        shopifyFulfillmentCreatePayloads.push([
+          credsPayload,
+          {
+            lineItemsByFulfillmentOrder: [{
+              fulfillmentOrderId: fulfillmentOrderGid,
+              fulfillmentOrderLineItems,
+            }],
+            notifyCustomer,
+            originAddress,
+            trackingInfo,
+          },
+          {
+            apiVersion,
+          },
+        ]);
+      }
+    }
+
+    if (shopifyFulfillmentCreatePayloads.length === 0) {
+      return {
+        ok: false,
+        error: {
+          message: 'No fulfillable line items found',
+        },
+        data: order,
+      };
+    }
+
+    logDeep({ depletableItemsBySku, shopifyFulfillmentCreatePayloads });
+    await askQuestion('Continue?');
+
+    return operationQueueRunner(
+      shopifyFulfillmentCreate,
+      shopifyFulfillmentCreatePayloads,
+    );
+  }
+
+  return {
+    ok: false,
+    error: `I guess we don't do that yet`,
+  };
+};
+
+const funcApiConfig = {
+  argsWarden,
+};
+
+module.exports = {
+  shopifyOrderFulfill,
+  funcApiConfig,
+};
+
+/*
+curl -X POST "http://localhost:8000/shopifyOrderFulfill" \
+  -H "Content-Type: application/json" \
+  -d `{
+    "credsPayload": { "credsPath": "shopify.au" },
+    "orderIdentifier": { "orderId": "104188477512" },
+    "fulfillmentPayload": { 
+      "fulfillAll": true,
+      "notifyCustomer": true,
+      "originAddress": { "countryCode": "AU" },
+      "trackingInfo": { 
+        "number": "1234567890", 
+        "company": "Kiki's Delivery Service", 
+        "url": "https://www.studioghibli.com.au/kikisdeliveryservice" 
+      }
+    }
+  }`
+*/

package/api/starshipit/starshipit.utils.js

@@ -8,9 +8,19 @@ const {
 const interpretStarshipitResponse = async (state) => {
   const { response } = state;
 
-  const { success, results, errors } = response.data;
+  const responseData = response.data || {};
+  const {
+    success,
+    succeeded,
+    results,
+    errors,
+    data: nestedData,
+    ...rest
+  } = responseData;
+
+  const ok = success === true || succeeded === true;
 
-  if (!success) {
+  if (!ok) {
     const firstError = errors?.[0];
 
     // TODO: Consider removing data if errors
@@ -27,10 +37,25 @@ const interpretStarshipitResponse = async (state) => {
     };
   }
 
+  let data;
+  if (results !== undefined) {
+    data = results;
+  } else if (nestedData && typeof nestedData === 'object' && !Array.isArray(nestedData)) {
+    // List endpoints return { page_*, data: { orders|products }, succeeded }
+    data = {
+      ...rest,
+      ...nestedData,
+      ...success !== undefined && { success },
+      ...succeeded !== undefined && { succeeded },
+    };
+  } else {
+    data = responseData;
+  }
+
   return {
     response: {
       ...response,
-      data: results ?? response.data,
+      data,
     },
   };
 };

package/api/starshipit/starshipitOrdersGet.js

@@ -0,0 +1,96 @@
+// https://api-docs.starshipit.com/#0aef707f-e2f5-493a-a382-8235c00c9c18
+
+const { ArgsWarden } = require('../utils');
+const { credsValidator } = require('../validators');
+const { starshipitGet, starshipitGetter } = require('../starshipit/starshipitGet');
+
+const ORDERS_MAX_PER_PAGE = 500;
+
+const argsWarden = new ArgsWarden([
+  ['credsPayload', credsValidator],
+]);
+
+const starshipitOrdersGet = async (
+  returnGetter,
+
+  credsPayload,
+  {
+    orderId,
+    orderNumber,
+    status,
+    filter,
+    include,
+    sortColumn,
+    sortDirection,
+    perPage = ORDERS_MAX_PER_PAGE,
+    ...getterOptions
+  } = {},
+) => {
+
+  const rejectResponse = await argsWarden.responseIfRejectingArgs({
+    credsPayload,
+  });
+  if (rejectResponse) {
+    return rejectResponse;
+  }
+
+  const getterArgs = [
+    credsPayload,
+    '/orders',
+    {
+      nodeName: 'orders',
+      perPage,
+      params: {
+        ...orderId && { order_id: orderId },
+        ...orderNumber && { order_number: orderNumber },
+        ...status && { status },
+        ...filter && { filter },
+        ...include && { include },
+        ...sortColumn && { sort_column: sortColumn },
+        ...sortDirection && { sort_direction: sortDirection },
+      },
+      digester: (response) => {
+        if (!response?.ok) {
+          return [];
+        }
+        const { orders, order } = response.data || {};
+        if (Array.isArray(orders)) {
+          return orders;
+        }
+        if (order) {
+          return [order];
+        }
+        return [];
+      },
+      ...getterOptions,
+    },
+  ];
+
+  return returnGetter
+    ? starshipitGetter(...getterArgs)
+    : starshipitGet(...getterArgs);
+};
+
+const funcApiConfig = {
+  argsWarden,
+};
+
+module.exports = {
+  starshipitOrdersGet: (...args) => starshipitOrdersGet(false, ...args),
+  starshipitOrdersGetter: (...args) => starshipitOrdersGet(true, ...args),
+  funcApiConfig,
+};
+
+/*
+curl -X POST "http://localhost:8000/starshipitOrdersGet" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "credsPayload": { "credsPath": "starshipit.wf" },
+    "options": {
+      "status": "Shipped",
+      "include": ["Items", "Packages"],
+      "perPage": 2,
+      "limit": 2
+    }
+  }'
+*/

package/api/utils.js

@@ -17,6 +17,14 @@ const objHasAny = (obj, keys) => {
   return keys.some((key) => obj[key] !== undefined);
 };
 
+const objHasAll = (obj, keys) => {
+  if (obj == null || typeof obj !== 'object') {
+    return false;
+  }
+
+  return keys.every((key) => obj[key] !== undefined);
+};
+
 const capitaliseString = (string) => `${ string[0].toUpperCase() }${ string.slice(1) }`;
 const sentenceCaseString = (string) => `${ string[0].toLowerCase() }${ string.slice(1) }`;
 
@@ -199,7 +207,19 @@ const customFetch = async (url, {
   }
 
   if (params) {
-    const search = new URLSearchParams(params);
+    const search = new URLSearchParams();
+    for (const [key, value] of Object.entries(params)) {
+      if (value === undefined || value === null) {
+        continue;
+      }
+      if (Array.isArray(value)) {
+        for (const entry of value) {
+          search.append(key, entry);
+        }
+      } else {
+        search.append(key, value);
+      }
+    }
     url += (url.includes('?') ? '&' : '?') + search.toString();
   }
 
@@ -790,6 +810,7 @@ class OperationQueue {
   async run({
     interval = false,
     verbose = true,
+    inspect = false,
   } = {}) {
 
     // Run at interval
@@ -825,7 +846,18 @@ class OperationQueue {
     // Run in sequence
     const results = [];
     for (const op of this.queue) {
+      
       const result = await op.run();
+
+      if (inspect !== false && (
+        inspect === true
+        || (typeof inspect === 'function' ? inspect(result) : objectMatchesPartial(result, inspect))
+      )) {
+        inspect && logDeep({ op });
+        inspect && logDeep({ result });
+        inspect && await askQuestion('Continue?');
+      }
+      
       results.push(result);
       if (verbose) {
         console.log(`${ results.length } / ${ this.queue.length }`);
@@ -837,6 +869,16 @@ class OperationQueue {
   }
 }
 
+const operationQueueRunner = async (func, payloads, { queueRunOptions = {} } = {}) => {
+  const queue = new OperationQueue(payloads.map(payload => new Operation(
+    func,
+    { args: payload },
+  )));
+
+  const queueResponses = await queue.run(queueRunOptions);
+  return responseArrayToResponse(queueResponses);
+};
+
 const simpleSort = (arr, prop, { reverse } = {}) => {
   return [...arr].sort((a, b) =>
     reverse ? b[prop] - a[prop] : a[prop] - b[prop],
@@ -1236,10 +1278,48 @@ const gidToId = (gid) => {
   return gid.split('/').pop();
 };
 
+const objectToArray = (object, { keyProp } = {}) => {
+  if (!keyProp) {
+    return Object.values(object);
+  }
+
+  return Object.entries(object).map(([key, value]) => ({
+    [keyProp]: key,
+    ...value,
+  }));
+};
+
+const objectMatchesPartial = (object, partial) => {
+  if (object === partial) {
+    return true;
+  }
+
+  if (
+    partial === null
+    || typeof partial !== 'object'
+    || object === null
+    || typeof object !== 'object'
+  ) {
+    return false;
+  }
+
+  if (Array.isArray(partial)) {
+    if (!Array.isArray(object)) {
+      return false;
+    }
+    return partial.every((item, i) => objectMatchesPartial(object[i], item));
+  }
+
+  return Object.entries(partial).every(([key, value]) => (
+    objectMatchesPartial(object[key], value)
+  ));
+};
+
 module.exports = {
   wait,
   timeMs,
   objHasAny,
+  objHasAll,
   capitaliseString,
   normalise,
   credsFromPayload,
@@ -1264,6 +1344,7 @@ module.exports = {
   responseResultsByOutcome,
   Operation,
   OperationQueue,
+  operationQueueRunner,
   actionSingleOrMultiple,
   Processor,
   Getter,
@@ -1271,4 +1352,6 @@ module.exports = {
   ArgsWarden,
   gidToId,
   valueProvided,
+  objectToArray,
+  objectMatchesPartial,
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@foxtware/mineral",
-  "version": "0.1.18",
+  "version": "0.1.19",
   "bin": {
     "mineral": "bin/mineral.js"
   },