@foxtware/mineral 0.1.40 → 1.0.1

package/README.md

@@ -1,21 +1,24 @@
 # mineral
 
-The [bedrock](https://github.com/GorgonFreeman/bedrock) middleware, refactored for compatibility with other projects and more consistent standards.
+An everything middleware, centred around easy-to-bring credentials and instantly useful curl commands. Now importable into your project.
 
-## Problems with bedrock
+## How to get mineralling
 
-- **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
+1. From your project, install mineral: `npm i @foxtware/mineral`.
+2. Set up a `.creds.yml` in your project directory, based on mineral's `.creds.yml.sample`. Add the credentials for the platform you want to use.
+3. Add the `dev` command to your project's `package.json`:
+```
+"dev": "node --watch --watch-path=./api --watch-path=./.creds.yml --watch-path=./.env --watch-path=./hosting node_modules/@foxtware/mineral/server.js --workspace . --api_dirs api"
+```
+4. Run `npm run dev` to start a server.
+5. Use an example curl command from the file whose function you want to use, with the creds path you set up.
 
-## The plan
+## Key ideas
+### The response format to rule them all
 
-- **The response format to rule them all**
-  ```typescript
+All functions should return data in this format.
+
+```typescript
   interface Response {
     ok: boolean
     data?: unknown
@@ -32,28 +35,58 @@ The [bedrock](https://github.com/GorgonFreeman/bedrock) middleware, refactored f
     }
     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. Pass `--workspace` to locate `.creds.yml` and `--api_dirs` to serve additional function directories.
+```
+- `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
+
+Each function accepts an object like this, supplying auth info for each platform it contacts:
+
+```
+{
+  credsPath,
+  credsObject,
+  credsProvider, // function that returns a credsObject
+}
+```
+
+You can set up a `.creds.yml` in your workspace directory and refer to it using `credsPath` > `platform.account`, or supply credentials inline using `credsObject`.
+
+### Monorepo context
+
+Mineral gets pushed to from a larger repo. Private functions are contained in a sibling project, which imports mineral to power all of the core functionalities, and layers certain business logic on top - e.g. known creds paths. 
+
+Mineral is strictly core functionalities, useful for anyone.
+
+Pass `--workspace` to locate `.creds.yml` and `--api_dirs` to serve additional function directories.
+
+### Hosting
+
+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`. 
+
+In the hosting YML, you can use wrappers which are additional layers to your hosted function. For instance, you may want to require an API key in requests to your middleware while it's live, or, require a hash in the headers that matches a hash of the body. 
+
+The decoupled nature of these desires to what the function actually does and their broad application is why they're implemented in the hosting config itself, rather than in a custom instance of the function.
+
+### AI use
+
+Not gonna lie, I have absolutely composed some of these platforms with AI. Some of them may not work, some may not stick closely to the core principles, some may use awkward auth methods - some error payloads are definitely not optimised. However, know that I have hand-coded precursors to this repo, that do largely the same thing, and that any additions benefit (or suffer) from the structure that is laid out in the earlier platforms.
+
+### Function arguments shape
+
+- Bound arguments, if they exist, are first
+- Mandatory inputs are passed as separate arguments
+- Optional inputs are passed in one 'options' object on the end, which falls back to `{}` if not supplied
 
-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`.
+This looks like:
+```
+const attack = (name, damage, accuracy, pp, type, { effects } = {}) => {
+```
+where 'effects' is optional and the others are mandatory.
 
-## 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.
+This documents what options are available, and allows invocations to only supply meaningful inputs.

package/api/bleckmann/bleckmann.utils.js

@@ -1,6 +1,6 @@
 const { BASE_URL } = require('../bleckmann/bleckmann.constants');
 const { resolveCreds, useBaseUrl } = require('../pipelineSteps');
-const { FetchClient } = require('../utils');
+const { FetchClient, fetchClientCommonSteps } = require('../utils');
 
 const useAuthHeaders = async (state) => {
   const { requestPayload, context } = state;
@@ -24,6 +24,9 @@ const bleckmannClient = new FetchClient({
     useAuthHeaders,
     useBaseUrl(BASE_URL),
     'fetch',
+    fetchClientCommonSteps.exitEarlyOnNotOk,
+    // Bleckmann wraps payloads in `data` — handlers opt in with context.resultPath
+    fetchClientCommonSteps.digToPath,
   ],
 });
 

package/api/bleckmann/bleckmannAsnsGet.js

@@ -42,6 +42,7 @@ const bleckmannAsnsGet = async (
     },
     context: {
       credsPayload,
+      resultPath: 'data',
     },
   });
 

package/api/bleckmann/bleckmannPickticketGet.js

@@ -0,0 +1,76 @@
+// https://app.swaggerhub.com/apis-docs/Bleckmann/warehousing/1.5.2#/PICKTICKET/getPickticketForId
+
+const { credsValidator } = require('../validators');
+const { ArgsWarden, objHasAny, oneFromManyInResponse } = require('../utils');
+const { bleckmannClient } = require('../bleckmann/bleckmann.utils');
+const { bleckmannPickticketsGet } = require('../bleckmann/bleckmannPickticketsGet');
+
+const pickticketIdentifierValidator = (pickticketIdentifier) => {
+  return objHasAny(pickticketIdentifier, ['pickticketId', 'pickticketReference']);
+};
+
+const argsWarden = new ArgsWarden([
+  ['credsPayload', credsValidator],
+  ['pickticketIdentifier', pickticketIdentifierValidator],
+]);
+
+const bleckmannPickticketGet = async (
+  credsPayload,
+  pickticketIdentifier,
+  {
+    fetchClient = bleckmannClient,
+  } = {},
+) => {
+
+  const rejectResponse = await argsWarden.responseIfRejectingArgs({
+    credsPayload,
+    pickticketIdentifier,
+  });
+  if (rejectResponse) {
+    return rejectResponse;
+  }
+
+  const {
+    pickticketId,
+    pickticketReference,
+  } = pickticketIdentifier;
+
+  if (pickticketId) {
+    return fetchClient.fetch({
+      requestPayload: {
+        url: `/warehousing/picktickets/${ pickticketId }`,
+      },
+      context: {
+        credsPayload,
+      },
+    });
+  }
+
+  const response = await bleckmannPickticketsGet(
+    credsPayload,
+    {
+      reference: pickticketReference,
+      fetchClient,
+    },
+  );
+
+  return oneFromManyInResponse(response, 'reference', pickticketReference);
+};
+
+const funcApiConfig = {
+  argsWarden,
+};
+
+module.exports = {
+  bleckmannPickticketGet,
+  funcApiConfig,
+};
+
+/*
+curl -X POST "http://localhost:8000/bleckmannPickticketGet" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "credsPayload": { "credsPath": "bleckmann" },
+    "pickticketIdentifier": { "pickticketReference": "1234567890" }
+  }'
+*/

package/api/bleckmann/bleckmannPickticketsGet.js

@@ -0,0 +1,72 @@
+// https://app.swaggerhub.com/apis-docs/Bleckmann/warehousing/1.5.2#/PICKTICKET/getPicktickets
+
+const { credsValidator } = require('../validators');
+const { ArgsWarden } = require('../utils');
+const { MAX_PER_PAGE } = require('../bleckmann/bleckmann.constants');
+const { bleckmannClient } = require('../bleckmann/bleckmann.utils');
+
+const argsWarden = new ArgsWarden([
+  ['credsPayload', credsValidator],
+]);
+
+const bleckmannPickticketsGet = async (
+  credsPayload,
+  {
+    createdFrom,
+    createdTo,
+    shippedFrom,
+    shippedTo,
+    // status default is INPROGRESS in the API; use ANY unless provided
+    status = 'ANY',
+    reference,
+    customerReference,
+    perPage = MAX_PER_PAGE,
+    fetchClient = bleckmannClient,
+  } = {},
+) => {
+
+  const rejectResponse = await argsWarden.responseIfRejectingArgs({
+    credsPayload,
+  });
+  if (rejectResponse) {
+    return rejectResponse;
+  }
+
+  return fetchClient.fetch({
+    requestPayload: {
+      url: '/warehousing/picktickets',
+      params: {
+        limit: perPage,
+        ...(createdFrom && { createdFrom }),
+        ...(createdTo && { createdTo }),
+        ...(shippedFrom && { shippedFrom }),
+        ...(shippedTo && { shippedTo }),
+        ...(status && { status }),
+        ...(reference && { reference }),
+        ...(customerReference && { customerReference }),
+      },
+    },
+    context: {
+      credsPayload,
+      resultPath: 'data',
+    },
+  });
+};
+
+const funcApiConfig = {
+  argsWarden,
+};
+
+module.exports = {
+  bleckmannPickticketsGet,
+  funcApiConfig,
+};
+
+/*
+curl -X POST "http://localhost:8000/bleckmannPickticketsGet" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "credsPayload": { "credsPath": "bleckmann" },
+    "options": { "perPage": 20 }
+  }'
+*/

package/api/linear/linearEntityExternalLinkCreate.js

@@ -0,0 +1,81 @@
+// https://linear.app/developers/graphql
+
+const { ArgsWarden } = require('../utils');
+const { credsValidator } = require('../validators');
+const { linearClient } = require('../linear/linear.utils');
+
+const inputValidator = (input) => Boolean(input?.url);
+
+const argsWarden = new ArgsWarden([
+  ['credsPayload', credsValidator],
+  ['input', inputValidator],
+]);
+
+const linearEntityExternalLinkCreate = async (
+  credsPayload,
+  input,
+  {
+    inspect = false,
+    fetchClient = linearClient,
+  } = {},
+) => {
+
+  const rejectResponse = await argsWarden.responseIfRejectingArgs({
+    credsPayload,
+    input,
+  });
+  if (rejectResponse) {
+    return rejectResponse;
+  }
+
+  return fetchClient.fetch({
+    requestPayload: {
+      body: {
+        query: `
+          mutation EntityExternalLinkCreate($input: EntityExternalLinkCreateInput!) {
+            entityExternalLinkCreate(input: $input) {
+              success
+              entityExternalLink {
+                id
+                label
+                url
+                sortOrder
+                createdAt
+              }
+            }
+          }
+        `,
+        variables: {
+          input,
+        },
+      },
+    },
+    context: {
+      credsPayload,
+      resultPath: 'data.entityExternalLinkCreate',
+    },
+    inspect,
+  });
+};
+
+const funcApiConfig = {
+  argsWarden,
+};
+
+module.exports = {
+  linearEntityExternalLinkCreate,
+  funcApiConfig,
+};
+
+/*
+curl -X POST "http://localhost:8000/linearEntityExternalLinkCreate" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "credsPayload": { "credsPath": "linear" },
+    "input": {
+      "projectId": "64e37bd2-af8c-4142-932a-66441b75311b",
+      "url": "https://example.com",
+      "label": "Example link"
+    }
+  }'
+*/

package/api/linear/linearFileUpload.js

@@ -0,0 +1,111 @@
+// https://linear.app/developers/graphql
+
+const { ArgsWarden } = require('../utils');
+const { credsValidator } = require('../validators');
+const { linearClient } = require('../linear/linear.utils');
+
+const argsWarden = new ArgsWarden([
+  ['credsPayload', credsValidator],
+  ['filename'],
+  ['contentType'],
+  ['size', (size) => Number.isInteger(size) && size > 0],
+]);
+
+const linearFileUpload = async (
+  credsPayload,
+  filename,
+  contentType,
+  size,
+  {
+    metaData,
+    makePublic,
+    inspect = false,
+    fetchClient = linearClient,
+  } = {},
+) => {
+
+  const rejectResponse = await argsWarden.responseIfRejectingArgs({
+    credsPayload,
+    filename,
+    contentType,
+    size,
+  });
+  if (rejectResponse) {
+    return rejectResponse;
+  }
+
+  return fetchClient.fetch({
+    requestPayload: {
+      body: {
+        query: `
+          mutation FileUpload(
+            $filename: String!
+            $contentType: String!
+            $size: Int!
+            $metaData: JSON
+            $makePublic: Boolean
+          ) {
+            fileUpload(
+              filename: $filename
+              contentType: $contentType
+              size: $size
+              metaData: $metaData
+              makePublic: $makePublic
+            ) {
+              success
+              uploadFile {
+                filename
+                contentType
+                size
+                uploadUrl
+                assetUrl
+                headers {
+                  key
+                  value
+                }
+              }
+            }
+          }
+        `,
+        variables: {
+          filename,
+          contentType,
+          size,
+          metaData,
+          makePublic,
+        },
+      },
+    },
+    context: {
+      credsPayload,
+      resultPath: 'data.fileUpload',
+    },
+    inspect,
+  });
+};
+
+const funcApiConfig = {
+  argsWarden,
+};
+
+module.exports = {
+  linearFileUpload,
+  funcApiConfig,
+};
+
+/*
+  Returns a pre-signed `uploadUrl` to PUT the file to, plus the `headers` that
+  the PUT must carry. `assetUrl` is the resulting Linear-hosted URL, suitable
+  for linearAttachmentCreate or embedding in comment markdown.
+*/
+
+/*
+curl -X POST "http://localhost:8000/linearFileUpload" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "credsPayload": { "credsPath": "linear" },
+    "filename": "assets.zip",
+    "contentType": "application/zip",
+    "size": 12345
+  }'
+*/

package/api/pipe17/pipe17ArrivalGet.js

@@ -25,9 +25,9 @@ const resolveArrivalId = ({
   extReferenceId,
 }) => {
   return arrivalId
-    || (extArrivalId ? `ext:${ extArrivalId }` : null)
-    || (extArrivalApiId ? `api:${ extArrivalApiId }` : null)
-    || (extReferenceId ? `ref:${ extReferenceId }` : null);
+    || (extArrivalId ? `ext:${ encodeURIComponent(extArrivalId) }` : null)
+    || (extArrivalApiId ? `api:${ encodeURIComponent(extArrivalApiId) }` : null)
+    || (extReferenceId ? `ref:${ encodeURIComponent(extReferenceId) }` : null);
 };
 
 const pipe17ArrivalGet = async (
@@ -52,7 +52,7 @@ const pipe17ArrivalGet = async (
     '/arrivals',
     resolveArrivalId(arrivalIdentifier),
     {
-      resultPath: 'result.arrival',
+      resultPath: 'arrival',
       inspect,
       fetchClient,
     },
@@ -73,6 +73,13 @@ curl -X POST "http://localhost:8000/pipe17ArrivalGet" \
   -H "Content-Type: application/json" \
   -d '{
     "credsPayload": { "credsPath": "pipe17" },
-    "arrivalIdentifier": { "arrivalId": "d22afa93793be1f1" }
+    "arrivalIdentifier": { "arrivalId": "8f146f632e55fd21" }
+  }'
+
+curl -X POST "http://localhost:8000/pipe17ArrivalGet" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "credsPayload": { "credsPath": "pipe17" },
+    "arrivalIdentifier": { "extArrivalId": "US-WF-021" }
   }'
 */

package/api/pipe17/pipe17FulfillmentGet.js

@@ -18,7 +18,7 @@ const resolveFulfillmentId = ({
   extFulfillmentId,
 }) => {
   return fulfillmentId
-    || (extFulfillmentId ? `ext:${ extFulfillmentId }` : null);
+    || (extFulfillmentId ? `ext:${ encodeURIComponent(extFulfillmentId) }` : null);
 };
 
 const pipe17FulfillmentGet = async (
@@ -43,7 +43,7 @@ const pipe17FulfillmentGet = async (
     '/fulfillments',
     resolveFulfillmentId(fulfillmentIdentifier),
     {
-      resultPath: 'result.fulfillment',
+      resultPath: 'fulfillment',
       inspect,
       fetchClient,
     },
@@ -64,6 +64,13 @@ curl -X POST "http://localhost:8000/pipe17FulfillmentGet" \
   -H "Content-Type: application/json" \
   -d '{
     "credsPayload": { "credsPath": "pipe17" },
-    "fulfillmentIdentifier": { "fulfillmentId": "4ce308990d48d54f" }
+    "fulfillmentIdentifier": { "fulfillmentId": "171889ac4c86b805" }
+  }'
+
+curl -X POST "http://localhost:8000/pipe17FulfillmentGet" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "credsPayload": { "credsPath": "pipe17" },
+    "fulfillmentIdentifier": { "extFulfillmentId": "bb558b1527b95c99:1Z179A841391432104" }
   }'
 */

package/api/pipe17/pipe17InventoryItemGet.js

@@ -31,7 +31,7 @@ const pipe17InventoryItemGet = async (
     '/inventory',
     inventoryItemId,
     {
-      resultPath: 'result.inventory',
+      resultPath: 'inventory',
       inspect,
       fetchClient,
     },
@@ -48,10 +48,14 @@ module.exports = {
 };
 
 /*
-curl -X POST "http://localhost:8000/pipe17InventoryItemGet" \
+NOTE: no working call found. Pipe17 inventory records carry no id of their own — they are
+keyed by sku + locationId — and GET /inventory/{id} returns 404 "No results" for a sku or a
+locationId. Fetch by sku through pipe17InventoryItemsGet instead (one row per location):
+
+curl -X POST "http://localhost:8000/pipe17InventoryItemsGet" \
   -H "Content-Type: application/json" \
   -d '{
     "credsPayload": { "credsPath": "pipe17" },
-    "inventoryItemId": "904e7f5e7a03df4f"
+    "options": { "params": { "sku": "EXDAL2449-5-XS" } }
   }'
 */

package/api/pipe17/pipe17JobGet.js

@@ -31,7 +31,7 @@ const pipe17JobGet = async (
     '/jobs',
     jobId,
     {
-      resultPath: 'result.job',
+      resultPath: 'job',
       inspect,
       fetchClient,
     },
@@ -52,6 +52,6 @@ curl -X POST "http://localhost:8000/pipe17JobGet" \
   -H "Content-Type: application/json" \
   -d '{
     "credsPayload": { "credsPath": "pipe17" },
-    "jobId": "eb7586ac111d3afb"
+    "jobId": "94fc44fdbe6ad3ae"
   }'
 */

package/api/pipe17/pipe17JobResultsGet.js

@@ -50,6 +50,6 @@ curl -X POST "http://localhost:8000/pipe17JobResultsGet" \
   -H "Content-Type: application/json" \
   -d '{
     "credsPayload": { "credsPath": "pipe17" },
-    "jobId": "eb7586ac111d3afb"
+    "jobId": "a25261fefd836d00"
   }'
 */

package/api/pipe17/pipe17LocationGet.js

@@ -31,7 +31,7 @@ const pipe17LocationGet = async (
     '/locations',
     locationId,
     {
-      resultPath: 'result.location',
+      resultPath: 'location',
       inspect,
       fetchClient,
     },
@@ -52,6 +52,6 @@ curl -X POST "http://localhost:8000/pipe17LocationGet" \
   -H "Content-Type: application/json" \
   -d '{
     "credsPayload": { "credsPath": "pipe17" },
-    "locationId": "6d9c18617ea2d279"
+    "locationId": "727db407e94815a6"
   }'
 */

package/api/pipe17/pipe17OrderGet.js

@@ -19,8 +19,8 @@ const resolveOrderId = ({
   extOrderApiId,
 }) => {
   return orderId
-    || (extOrderId ? `ext:${ extOrderId }` : null)
-    || (extOrderApiId ? `api:${ extOrderApiId }` : null);
+    || (extOrderId ? `ext:${ encodeURIComponent(extOrderId) }` : null)
+    || (extOrderApiId ? `api:${ encodeURIComponent(extOrderApiId) }` : null);
 };
 
 const pipe17OrderGet = async (
@@ -45,7 +45,7 @@ const pipe17OrderGet = async (
     '/orders',
     resolveOrderId(orderIdentifier),
     {
-      resultPath: 'result.order',
+      resultPath: 'order',
       inspect,
       fetchClient,
     },
@@ -66,6 +66,20 @@ curl -X POST "http://localhost:8000/pipe17OrderGet" \
   -H "Content-Type: application/json" \
   -d '{
     "credsPayload": { "credsPath": "pipe17" },
-    "orderIdentifier": { "orderId": "dc120f1015760357" }
+    "orderIdentifier": { "orderId": "243acd2642101951" }
+  }'
+
+curl -X POST "http://localhost:8000/pipe17OrderGet" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "credsPayload": { "credsPath": "pipe17" },
+    "orderIdentifier": { "extOrderId": "#USA4162713" }
+  }'
+
+curl -X POST "http://localhost:8000/pipe17OrderGet" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "credsPayload": { "credsPath": "pipe17" },
+    "orderIdentifier": { "extOrderApiId": "5820180987964" }
   }'
 */

package/api/pipe17/pipe17ProductGet.js

@@ -31,7 +31,7 @@ const pipe17ProductGet = async (
     '/products',
     productId,
     {
-      resultPath: 'result.product',
+      resultPath: 'product',
       inspect,
       fetchClient,
     },
@@ -52,6 +52,6 @@ curl -X POST "http://localhost:8000/pipe17ProductGet" \
   -H "Content-Type: application/json" \
   -d '{
     "credsPayload": { "credsPath": "pipe17" },
-    "productId": "149a8a65ad5bca52"
+    "productId": "3f91e016e3d433e8"
   }'
 */

package/api/pipe17/pipe17PurchaseGet.js

@@ -31,7 +31,7 @@ const pipe17PurchaseGet = async (
     '/purchases',
     purchaseId,
     {
-      resultPath: 'result.purchase',
+      resultPath: 'purchase',
       inspect,
       fetchClient,
     },
@@ -52,6 +52,6 @@ curl -X POST "http://localhost:8000/pipe17PurchaseGet" \
   -H "Content-Type: application/json" \
   -d '{
     "credsPayload": { "credsPath": "pipe17" },
-    "purchaseId": "REPLACE_WITH_PURCHASE_ID"
+    "purchaseId": "075e2df5318aa93e"
   }'
 */

package/api/pipe17/pipe17ReceiptGet.js

@@ -31,7 +31,7 @@ const pipe17ReceiptGet = async (
     '/receipts',
     receiptId,
     {
-      resultPath: 'result.receipt',
+      resultPath: 'receipt',
       inspect,
       fetchClient,
     },

package/api/pipe17/pipe17ReturnGet.js

@@ -31,7 +31,7 @@ const pipe17ReturnGet = async (
     '/returns',
     returnId,
     {
-      resultPath: 'result.return',
+      resultPath: 'return',
       inspect,
       fetchClient,
     },
@@ -52,6 +52,6 @@ curl -X POST "http://localhost:8000/pipe17ReturnGet" \
   -H "Content-Type: application/json" \
   -d '{
     "credsPayload": { "credsPath": "pipe17" },
-    "returnId": "969504fc181f7182"
+    "returnId": "b66396c696171143"
   }'
 */

package/api/shopify/shopifyGet.js

@@ -297,6 +297,8 @@ const funcApiConfig = {
 module.exports = {
   shopifyGet: (...args) => shopifyGet(false, ...args),
   shopifyGetter: (...args) => shopifyGet(true, ...args),
+  shopifyGetPaginator,
+  shopifyGetDigester,
   funcApiConfig,
 };
 

package/api/shopify/shopifyProductUpdateTrigger.js

@@ -6,32 +6,41 @@ const { ArgsWarden } = require('../utils');
 const { shopifyProductGet, productIdentifierValidator } = require('../shopify/shopifyProductGet');
 const { shopifyProductUpdate } = require('../shopify/shopifyProductUpdate');
 
+const productPayloadValidator = (productPayload) => {
+  const { productIdentifier, productTitle } = productPayload;
+  return productIdentifierValidator(productIdentifier);
+};
+
 const argsWarden = new ArgsWarden([
   ['credsPayload', credsValidator],
-  ['productIdentifier', productIdentifierValidator],
+  ['productPayload', productPayloadValidator],
 ]);
 
 const shopifyProductUpdateTrigger = async (
   credsPayload,
-  productIdentifier,
+  productPayload,
   {
     apiVersion,
-    productTitle,
   } = {},
 ) => {
 
   const rejectResponse = await argsWarden.responseIfRejectingArgs({
     credsPayload,
-    productIdentifier,
+    productPayload,
   });
   if (rejectResponse) {
     return rejectResponse;
   }
 
+  const { 
+    productIdentifier,
+    productTitle,
+  } = productPayload;
+
   if (!productTitle) {
     const productResponse = await shopifyProductGet(
       credsPayload,
-      productIdentifier,
+      productPayload,
       {
         attrs: 'title',
       },
@@ -83,14 +92,13 @@ module.exports = {
     -H "Content-Type: application/json" \
     -d '{
       "credsPayload": { "credsPath": "shopify.au" },
-      "productIdentifier": { "productId": "1234567890" }
+      "productPayload": { "productIdentifier": { "productId": "1234567890" } }
     }'
 
   curl -X POST "http://localhost:8000/shopifyProductUpdateTrigger" \
     -H "Content-Type: application/json" \
     -d '{
       "credsPayload": { "credsPath": "shopify.au" },
-      "productIdentifier": { "productId": "1234567890" },
-      "options": { "productTitle": "Ultra Strength Freeze Ray" }
+      "productPayload": { "productIdentifier": { "productId": "1234567890" }, "productTitle": "Ultra Strength Freeze Ray" },
     }'
 */

package/api/shopify/shopifyThemeFilesGet.js

@@ -0,0 +1,166 @@
+// https://shopify.dev/docs/api/admin-graphql/latest/objects/OnlineStoreTheme#connection-files
+
+const { ArgsWarden, Getter, ensureArray, getWithLocalCachedFile } = require('../utils');
+const { credsValidator } = require('../validators');
+const { shopifyClient } = require('./shopify.utils');
+const { shopifyGetPaginator, shopifyGetDigester } = require('./shopifyGet');
+const { MAX_PER_PAGE } = require('./shopify.constants');
+
+const defaultAttrs = 'filename';
+
+const argsWarden = new ArgsWarden([
+  ['credsPayload', credsValidator],
+  ['themeId'],
+]);
+
+const shopifyThemeFilesGetPacket = async (
+  credsPayload,
+  themeId,
+  attrs,
+  {
+    apiVersion,
+
+    perPage = MAX_PER_PAGE,
+    cursor,
+    // Supports globs, e.g. templates/page.*
+    filenames,
+  } = {},
+) => {
+
+  return await shopifyClient.fetch({
+    requestPayload: {
+      method: 'post',
+      body: {
+        query: `
+        query GetThemeFiles (
+          $themeId: ID!
+          $first: Int!
+          $cursor: String
+          ${ filenames ? '$filenames: [String!]' : '' }
+        ) {
+          theme(id: $themeId) {
+            files(
+              first: $first
+              after: $cursor
+              ${ filenames ? 'filenames: $filenames' : '' }
+            ) {
+              nodes {
+                ${ attrs }
+              }
+              pageInfo {
+                hasNextPage
+                endCursor
+              }
+            }
+          }
+        }
+      `,
+        variables: {
+          themeId: `gid://shopify/OnlineStoreTheme/${ themeId }`,
+          first: perPage,
+          cursor,
+          ...filenames && { filenames: ensureArray(filenames) },
+        },
+      },
+    },
+    context: {
+      credsPayload,
+      apiVersion,
+      resultPath: 'data.theme.files',
+    },
+  });
+};
+
+const shopifyThemeFilesGet = async (
+  returnGetter, // Always bound
+
+  credsPayload,
+  themeId,
+  {
+    apiVersion,
+
+    attrs = defaultAttrs,
+    perPage = MAX_PER_PAGE,
+    cursor,
+    filenames,
+
+    useLocalCachedFile,
+    ...getterOptions // e.g. limit
+  } = {},
+) => {
+
+  const rejectResponse = await argsWarden.responseIfRejectingArgs({
+    credsPayload,
+    themeId,
+  });
+  if (rejectResponse) {
+    return rejectResponse;
+  }
+
+  const getter = new Getter(
+    {
+      args: [
+        credsPayload,
+        themeId,
+        attrs,
+      ],
+      options: {
+        apiVersion,
+        perPage,
+        cursor,
+        filenames,
+      },
+    },
+    {
+      func: shopifyThemeFilesGetPacket,
+      digester: shopifyGetDigester,
+      paginator: shopifyGetPaginator,
+      ...getterOptions,
+    },
+  );
+
+  if (returnGetter) {
+    return getter;
+  }
+
+  return getWithLocalCachedFile(
+    useLocalCachedFile,
+    async () => {
+      const data = await getter.run({ returnAll: true });
+
+      return {
+        ok: true,
+        data,
+      };
+    },
+  );
+};
+
+const funcApiConfig = {
+  argsWarden,
+};
+
+module.exports = {
+  shopifyThemeFilesGet: (...args) => shopifyThemeFilesGet(false, ...args),
+  shopifyThemeFilesGetter: (...args) => shopifyThemeFilesGet(true, ...args),
+  funcApiConfig,
+};
+
+/*
+curl -X POST "http://localhost:8000/shopifyThemeFilesGet" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "credsPayload": { "credsPath": "shopify.au" },
+    "themeId": "130370109512"
+  }'
+
+curl -X POST "http://localhost:8000/shopifyThemeFilesGet" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "credsPayload": { "credsPath": "shopify.au" },
+    "themeId": "130370109512",
+    "options": {
+      "filenames": "templates/*"
+    }
+  }'
+*/

package/package.json

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