@foxtware/mineral 0.1.28 → 0.1.30

package/api/paypal/paypalTransactionsGet.js

@@ -0,0 +1,101 @@
+// https://developer.paypal.com/docs/api/transaction-search/v1/#transactions_get
+
+const { credsValidator } = require('../validators');
+const { ArgsWarden } = require('../utils');
+const { paypalClient } = require('../paypal/paypal.utils');
+const { DEFAULT_PAGE_SIZE, MAX_PAGE_SIZE } = require('../paypal/paypal.constants');
+
+const argsWarden = new ArgsWarden([
+  ['credsPayload', credsValidator],
+  ['startDate'],
+  ['endDate'],
+]);
+
+/**
+ * List transactions for the account (Transaction Search API).
+ * startDate / endDate are ISO-8601 (e.g. 2024-01-01T00:00:00Z).
+ * Date range must be ≤ 31 days per PayPal rules.
+ */
+const paypalTransactionsGet = async (
+  credsPayload,
+  startDate,
+  endDate,
+  {
+    transactionId,
+    transactionStatus,
+    transactionType,
+    paymentInstrumentType,
+    page = 1,
+    pageSize = DEFAULT_PAGE_SIZE,
+    fields,
+    balanceAffectingRecordsOnly,
+    storeId,
+    terminalId,
+    fetchClient = paypalClient,
+  } = {},
+) => {
+
+  const rejectResponse = await argsWarden.responseIfRejectingArgs({
+    credsPayload,
+    startDate,
+    endDate,
+  });
+  if (rejectResponse) {
+    return rejectResponse;
+  }
+
+  const size = Math.min(Number(pageSize) || DEFAULT_PAGE_SIZE, MAX_PAGE_SIZE);
+
+  const response = await fetchClient.fetch({
+    requestPayload: {
+      method: 'get',
+      url: '/v1/reporting/transactions',
+      params: {
+        start_date: startDate,
+        end_date: endDate,
+        page: Number(page) || 1,
+        page_size: size,
+        ...(transactionId ? { transaction_id: transactionId } : {}),
+        ...(transactionStatus ? { transaction_status: transactionStatus } : {}),
+        ...(transactionType ? { transaction_type: transactionType } : {}),
+        ...(paymentInstrumentType
+          ? { payment_instrument_type: paymentInstrumentType }
+          : {}),
+        ...(fields ? { fields } : {}),
+        ...(balanceAffectingRecordsOnly !== undefined
+          ? { balance_affecting_records_only: balanceAffectingRecordsOnly }
+          : {}),
+        ...(storeId ? { store_id: storeId } : {}),
+        ...(terminalId ? { terminal_id: terminalId } : {}),
+      },
+    },
+    context: {
+      credsPayload,
+    },
+  });
+
+  return response;
+};
+
+const funcApiConfig = {
+  argsWarden,
+};
+
+module.exports = {
+  paypalTransactionsGet,
+  funcApiConfig,
+};
+
+/*
+  curl -X POST "http://localhost:8000/paypalTransactionsGet" \
+    -H "Content-Type: application/json" \
+    -d '{
+      "credsPayload": { "credsPath": "paypal" },
+      "startDate": "2026-01-01T00:00:00Z",
+      "endDate": "2026-01-31T23:59:59Z",
+      "options": {
+        "page": 1,
+        "pageSize": 100
+      }
+    }'
+*/

package/api/paypal/paypalUserInfoGet.js

@@ -0,0 +1,62 @@
+// https://developer.paypal.com/docs/api/identity/v1/#userinfo_get
+
+const { credsValidator } = require('../validators');
+const { ArgsWarden } = require('../utils');
+const { paypalClient } = require('../paypal/paypal.utils');
+
+const argsWarden = new ArgsWarden([
+  ['credsPayload', credsValidator],
+]);
+
+/**
+ * Show OpenID Connect user profile details for the token subject.
+ * Client-credentials tokens may return limited claims; user-consent
+ * tokens with openid scopes return the full profile.
+ */
+const paypalUserInfoGet = async (
+  credsPayload,
+  {
+    schema = 'openid',
+    fetchClient = paypalClient,
+  } = {},
+) => {
+
+  const rejectResponse = await argsWarden.responseIfRejectingArgs({
+    credsPayload,
+  });
+  if (rejectResponse) {
+    return rejectResponse;
+  }
+
+  const response = await fetchClient.fetch({
+    requestPayload: {
+      method: 'get',
+      url: '/v1/identity/openidconnect/userinfo',
+      params: {
+        schema,
+      },
+    },
+    context: {
+      credsPayload,
+    },
+  });
+
+  return response;
+};
+
+const funcApiConfig = {
+  argsWarden,
+};
+
+module.exports = {
+  paypalUserInfoGet,
+  funcApiConfig,
+};
+
+/*
+  curl -X POST "http://localhost:8000/paypalUserInfoGet" \
+    -H "Content-Type: application/json" \
+    -d '{
+      "credsPayload": { "credsPath": "paypal" }
+    }'
+*/

package/api/royalmail/docs.md

@@ -0,0 +1,6 @@
+# Royal Mail
+
+- [Royal Mail APIs](https://www.royalmail.com/business/tools-services/apis)
+- [Tracking API V2](https://developer.royalmail.net/product/175625/api/76888)
+
+Royal Mail provides a REST Tracking API V2 at `https://api.royalmail.net`. Server-side tracking uses `X-IBM-Client-Id` and `X-IBM-Client-Secret` credentials issued through the Royal Mail API Developer Portal, plus the `X-Accept-RMG-Terms: yes` header. The API supports summary, history, and proof-of-delivery data for mailpieces.

package/api/royalmail/royalmail.constants.js

@@ -0,0 +1,7 @@
+const ROYALMAIL_API_BASE_URL = 'https://api.royalmail.net';
+const ROYALMAIL_TRACKING_PATH = '/mailpieces/v2';
+
+module.exports = {
+  ROYALMAIL_API_BASE_URL,
+  ROYALMAIL_TRACKING_PATH,
+};

package/api/royalmail/royalmail.utils.js

@@ -0,0 +1,55 @@
+const { resolveCreds, useBaseUrl } = require('../pipelineSteps');
+const {
+  FetchClient,
+  fetchClientCommonSteps,
+} = require('../utils');
+const { ROYALMAIL_API_BASE_URL } = require('./royalmail.constants');
+
+const useAuthHeaders = async (state) => {
+  const { requestPayload, context } = state;
+  const { creds } = context;
+  const {
+    CLIENT_ID,
+    CLIENT_SECRET,
+  } = creds || {};
+
+  if (!CLIENT_ID || !CLIENT_SECRET) {
+    return {
+      breakChain: true,
+      response: {
+        ok: false,
+        error: {
+          code: 'ROYALMAIL_AUTH_CONFIG_ERROR',
+          message: 'Royal Mail creds require CLIENT_ID and CLIENT_SECRET',
+        },
+      },
+    };
+  }
+
+  return {
+    requestPayload: {
+      ...requestPayload,
+      headers: {
+        Accept: 'application/json',
+        'X-Accept-RMG-Terms': 'yes',
+        'X-IBM-Client-Id': CLIENT_ID,
+        'X-IBM-Client-Secret': CLIENT_SECRET,
+        ...requestPayload.headers,
+      },
+    },
+  };
+};
+
+const royalmailClient = new FetchClient({
+  pipeline: [
+    resolveCreds,
+    useBaseUrl(ROYALMAIL_API_BASE_URL),
+    useAuthHeaders,
+    'fetch',
+    fetchClientCommonSteps.exitEarlyOnNotOk,
+  ],
+});
+
+module.exports = {
+  royalmailClient,
+};

package/api/royalmail/royalmailTrackingGet.js

@@ -0,0 +1,70 @@
+// https://developer.royalmail.net/product/175625/api/76888
+
+const { ArgsWarden, objHasAny } = require('../utils');
+const { credsValidator } = require('../validators');
+const { ROYALMAIL_TRACKING_PATH } = require('./royalmail.constants');
+const { royalmailClient } = require('./royalmail.utils');
+
+const trackingIdentifierValidator = (trackingIdentifier) => {
+  return objHasAny(trackingIdentifier, [
+    'trackingNumber',
+  ]);
+};
+
+const argsWarden = new ArgsWarden([
+  ['credsPayload', credsValidator],
+  ['trackingIdentifier', trackingIdentifierValidator],
+]);
+
+const royalmailTrackingGet = async (
+  credsPayload,
+  trackingIdentifier,
+  {
+    operation = 'summary',
+    fetchClient = royalmailClient,
+  } = {},
+) => {
+  const rejectResponse = await argsWarden.responseIfRejectingArgs({
+    credsPayload,
+    trackingIdentifier,
+  });
+  if (rejectResponse) {
+    return rejectResponse;
+  }
+
+  const {
+    trackingNumber,
+  } = trackingIdentifier;
+  const operationPath = operation === 'summary'
+    ? `${ ROYALMAIL_TRACKING_PATH }/summary?mailPieceId=${ encodeURIComponent(trackingNumber) }`
+    : `${ ROYALMAIL_TRACKING_PATH }/mailPieces/${ encodeURIComponent(trackingNumber) }/${ operation }`;
+
+  return fetchClient.fetch({
+    requestPayload: {
+      url: operationPath,
+    },
+    context: {
+      credsPayload,
+    },
+  });
+};
+
+const funcApiConfig = {
+  argsWarden,
+};
+
+module.exports = {
+  royalmailTrackingGet,
+  funcApiConfig,
+};
+
+/*
+curl -X POST "http://localhost:8000/royalmailTrackingGet" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "credsPayload": { "credsPath": "royalmail" },
+    "trackingIdentifier": {
+      "trackingNumber": "AA123456789GB"
+    }
+  }'
+*/

package/api/shopify/shopify.utils.js

@@ -76,6 +76,31 @@ const useUrlAndAuthHeaders = async (state) => {
   };
 };
 
+const useStorefrontUrlAndAuthHeaders = async (state) => {
+  const { requestPayload, context } = state;
+  const {
+    apiVersion = DEFAULT_API_VERSION,
+    creds,
+  } = context;
+  const {
+    STORE_HANDLE,
+    STOREFRONT_API_KEY,
+  } = creds;
+
+  const baseUrl = `https://${ STORE_HANDLE }.myshopify.com/api/${ apiVersion }/graphql.json`;
+
+  return {
+    requestPayload: {
+      ...requestPayload,
+      url: appendUrlToBase(baseUrl, requestPayload.url),
+      headers: {
+        'X-Shopify-Storefront-Access-Token': STOREFRONT_API_KEY,
+        ...requestPayload.headers,
+      },
+    },
+  };
+};
+
 const movePageInfoToMeta = async (state) => {
   const { response, context } = state;
   const { resultPath } = context ?? {};
@@ -86,15 +111,23 @@ const movePageInfoToMeta = async (state) => {
 
   const connection = objectDigNodeAtPath(response.data, pathAsArray(resultPath));
 
-  if (!connection?.pageInfo) {
+  if (!connection || typeof connection !== 'object') {
+    return {};
+  }
+
+  const meta = {
+    ...connection.pageInfo ? { pageInfo: connection.pageInfo } : {},
+    ...connection.totalCount !== undefined ? { totalCount: connection.totalCount } : {},
+    ...connection.productFilters !== undefined ? { productFilters: connection.productFilters } : {},
+  };
+
+  if (!Object.keys(meta).length) {
     return {};
   }
 
   return {
     response: {
-      meta: {
-        pageInfo: connection.pageInfo,
-      },
+      meta,
     },
   };
 };
@@ -188,7 +221,35 @@ const shopifyClient = new FetchClient({
   ],
 });
 
+const shopifyStorefrontClient = new FetchClient({
+  pipeline: [
+    resolveCreds,
+    useStorefrontUrlAndAuthHeaders,
+    'fetch',
+    movePageInfoToMeta,
+    fetchClientCommonSteps.stripEdgesAndNodes,
+    fetchClientCommonSteps.collapseDataWithOneValue,
+    fetchClientCommonSteps.exitEarlyOnNotOk,
+    fetchClientCommonSteps.exitEarlyOnGraphqlErrors,
+    fetchClientCommonSteps.digToPath,
+    handleMutationUserErrors,
+  ],
+});
+
+const shopifyProductFlattenMetafields = (product) => {
+  // If property begins with mf, try to flatten to property.value
+  const flattenedProduct = { ...product };
+  for (const [key, value] of Object.entries(product)) {
+    if (key.startsWith('mf')) {
+      flattenedProduct[key] = value?.value ?? value;
+    }
+  }
+  return flattenedProduct;
+};
+
 module.exports = {
   parseShopifyJsonl,
   shopifyClient,
+  shopifyStorefrontClient,
+  shopifyProductFlattenMetafields,
 };

package/api/shopify/shopifyMetaobjectCreate.js

@@ -11,7 +11,7 @@ const argsWarden = new ArgsWarden([
   ['metaobjectInput', metaobjectInputValidator],
 ]);
 
-const defaultReturnMetaobjectAttrs = 'id handle type updatedAt';
+const defaultReturnMetaobjectAttrs = 'id handle type updatedAt capabilities { publishable { status } }';
 
 const shopifyMetaobjectCreate = async (
   credsPayload,
@@ -59,13 +59,20 @@ module.exports = {
 curl -X POST "http://localhost:8000/shopifyMetaobjectCreate" \
   -H "Content-Type: application/json" \
   -d '{
-    "credsPayload": { "credsPath": "shopify.white-fox-us-dev-radial" },
+    "credsPayload": { "credsPath": "shopify.au" },
     "metaobjectInput": {
-      "type": "your_metaobject_type",
-      "handle": "optional-unique-handle",
+      "type": "catalog_filter_blacklist",
+      "handle": "collection-blacklist-example",
+      "capabilities": {
+        "publishable": {
+          "status": "ACTIVE"
+        }
+      },
       "fields": [
-        { "key": "title", "value": "Example" },
-        { "key": "body", "value": "Some content" }
+        { "key": "internal_name", "value": "Blacklist Category > \"Example\"" },
+        { "key": "source_filter", "value": "Category" },
+        { "key": "values", "value": "[\"Example\"]" },
+        { "key": "enabled", "value": "true" }
       ]
     }
   }'

package/api/shopify/shopifyMetaobjectDelete.js

@@ -0,0 +1,90 @@
+// https://shopify.dev/docs/api/admin-graphql/latest/mutations/metaobjectDelete
+
+const { credsValidator } = require('../validators');
+const { actionSingleOrMultiple, ArgsWarden } = require('../utils');
+const { shopifyMutationDo } = require('../shopify/shopifyMutationDo');
+
+const argsWarden = new ArgsWarden([
+  ['credsPayload', credsValidator],
+  ['metaobjectId'],
+]);
+
+const shopifyMetaobjectDeleteSingle = async (
+  credsPayload,
+  metaobjectId,
+  {
+    apiVersion,
+    returnSchema = 'deletedId',
+  } = {},
+) => {
+
+  return shopifyMutationDo(
+    credsPayload,
+    'metaobjectDelete',
+    {
+      mutationVariables: {
+        id: {
+          type: 'ID!',
+          value: `gid://shopify/Metaobject/${ metaobjectId }`,
+        },
+      },
+      returnSchema,
+      apiVersion,
+    },
+  );
+};
+
+const shopifyMetaobjectDelete = async (
+  credsPayload,
+  metaobjectId,
+  {
+    queueRunOptions,
+    apiVersion,
+    returnSchema = 'deletedId',
+  } = {},
+) => {
+
+  const rejectResponse = await argsWarden.responseIfRejectingArgs({
+    credsPayload,
+    metaobjectId,
+  });
+  if (rejectResponse) {
+    return rejectResponse;
+  }
+
+  return actionSingleOrMultiple(
+    metaobjectId,
+    shopifyMetaobjectDeleteSingle,
+    (metaobjectIdItem) => ({
+      args: [credsPayload, metaobjectIdItem, { apiVersion, returnSchema }],
+    }),
+    {
+      ...(queueRunOptions ? { queueRunOptions } : {}),
+    },
+  );
+};
+
+const funcApiConfig = {
+  argsWarden,
+};
+
+module.exports = {
+  shopifyMetaobjectDelete,
+  funcApiConfig,
+};
+
+/*
+curl -X POST "http://localhost:8000/shopifyMetaobjectDelete" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "credsPayload": { "credsPath": "shopify.au" },
+    "metaobjectId": "215094820924"
+  }'
+
+curl -X POST "http://localhost:8000/shopifyMetaobjectDelete" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "credsPayload": { "credsPath": "shopify.au" },
+    "metaobjectId": ["215094820924", "215094820925"]
+  }'
+*/

package/api/shopify/shopifyMetaobjectGet.js

@@ -0,0 +1,80 @@
+// https://shopify.dev/docs/api/admin-graphql/latest/queries/metaobject
+
+const { credsValidator } = require('../validators');
+const { actionSingleOrMultiple, ArgsWarden } = require('../utils');
+const { shopifyGetSingle } = require('../shopify/shopifyGetSingle');
+
+const defaultAttrs = 'id handle type updatedAt capabilities { publishable { status } } fields { key value type }';
+
+const argsWarden = new ArgsWarden([
+  ['credsPayload', credsValidator],
+  ['metaobjectId'],
+]);
+
+const shopifyMetaobjectGetSingle = async (
+  credsPayload,
+  metaobjectId,
+  {
+    apiVersion,
+    attrs = defaultAttrs,
+  } = {},
+) => {
+
+  return shopifyGetSingle(
+    credsPayload,
+    'metaobject',
+    metaobjectId,
+    {
+      apiVersion,
+      attrs,
+    },
+  );
+};
+
+const shopifyMetaobjectGet = async (
+  credsPayload,
+  metaobjectId,
+  {
+    queueRunOptions,
+    apiVersion,
+    attrs = defaultAttrs,
+  } = {},
+) => {
+
+  const rejectResponse = await argsWarden.responseIfRejectingArgs({
+    credsPayload,
+    metaobjectId,
+  });
+  if (rejectResponse) {
+    return rejectResponse;
+  }
+
+  return actionSingleOrMultiple(
+    metaobjectId,
+    shopifyMetaobjectGetSingle,
+    (metaobjectIdItem) => ({
+      args: [credsPayload, metaobjectIdItem, { apiVersion, attrs }],
+    }),
+    {
+      ...(queueRunOptions ? { queueRunOptions } : {}),
+    },
+  );
+};
+
+const funcApiConfig = {
+  argsWarden,
+};
+
+module.exports = {
+  shopifyMetaobjectGet,
+  funcApiConfig,
+};
+
+/*
+curl -X POST "http://localhost:8000/shopifyMetaobjectGet" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "credsPayload": { "credsPath": "shopify.au" },
+    "metaobjectId": "207864102984"
+  }'
+*/