@foxtware/mineral 0.1.29 → 0.1.30

package/api/paypal/paypalRefundGet.js

@@ -0,0 +1,57 @@
+// https://developer.paypal.com/docs/api/payments/v2/#refunds_get
+
+const { credsValidator } = require('../validators');
+const { ArgsWarden } = require('../utils');
+const { paypalClient } = require('../paypal/paypal.utils');
+
+const argsWarden = new ArgsWarden([
+  ['credsPayload', credsValidator],
+  ['refundId'],
+]);
+
+const paypalRefundGet = async (
+  credsPayload,
+  refundId,
+  {
+    fetchClient = paypalClient,
+  } = {},
+) => {
+
+  const rejectResponse = await argsWarden.responseIfRejectingArgs({
+    credsPayload,
+    refundId,
+  });
+  if (rejectResponse) {
+    return rejectResponse;
+  }
+
+  const response = await fetchClient.fetch({
+    requestPayload: {
+      method: 'get',
+      url: `/v2/payments/refunds/${ encodeURIComponent(refundId) }`,
+    },
+    context: {
+      credsPayload,
+    },
+  });
+
+  return response;
+};
+
+const funcApiConfig = {
+  argsWarden,
+};
+
+module.exports = {
+  paypalRefundGet,
+  funcApiConfig,
+};
+
+/*
+  curl -X POST "http://localhost:8000/paypalRefundGet" \
+    -H "Content-Type: application/json" \
+    -d '{
+      "credsPayload": { "credsPath": "paypal" },
+      "refundId": "1JU08902781691411"
+    }'
+*/

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

@@ -236,8 +236,20 @@ const shopifyStorefrontClient = new FetchClient({
   ],
 });
 
+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/starshipit/starshipitProductUpdate.js

@@ -0,0 +1,102 @@
+// https://api-docs.starshipit.com/#9101a9d7-91b1-492c-b7ad-5f92f80bbfd7
+
+const { ArgsWarden } = require('../utils');
+const { credsValidator } = require('../validators');
+const { starshipitClient } = require('../starshipit/starshipit.utils');
+const { starshipitProductsGet } = require('../starshipit/starshipitProductsGet');
+
+const argsWarden = new ArgsWarden([
+  ['credsPayload', credsValidator],
+  ['productId'],
+  ['sku'],
+  ['updatePayload'],
+]);
+
+const starshipitProductUpdate = async (
+  credsPayload,
+  productId,
+  sku,
+  updatePayload,
+  {
+    setData = false,
+  } = {},
+) => {
+
+  const rejectResponse = await argsWarden.responseIfRejectingArgs({
+    credsPayload,
+    productId,
+    sku,
+    updatePayload,
+  });
+  if (rejectResponse) {
+    return rejectResponse;
+  }
+
+  if (!setData) {
+    const productsResponse = await starshipitProductsGet(
+      credsPayload,
+      {
+        searchTerm: sku,
+      },
+    );
+
+    if (!productsResponse?.ok) {
+      return productsResponse;
+    }
+
+    const currentProduct = productsResponse.data?.find(product => product?.sku === sku);
+    if (!currentProduct) {
+      return {
+        ok: false,
+        error: {
+          code: 'PRODUCT_NOT_FOUND',
+          message: `No Starshipit product found for SKU ${ sku }`,
+        },
+      };
+    }
+
+    updatePayload = {
+      ...currentProduct,
+      ...updatePayload,
+    };
+  }
+
+  return starshipitClient.fetch({
+    requestPayload: {
+      url: '/products/update',
+      method: 'put',
+      body: {
+        id: productId,
+        product: {
+          id: productId,
+          sku,
+          ...updatePayload,
+        },
+      },
+    },
+    context: {
+      credsPayload,
+      resultPath: 'result.product',
+    },
+  });
+};
+
+const funcApiConfig = {
+  argsWarden,
+};
+
+module.exports = {
+  starshipitProductUpdate,
+  funcApiConfig,
+};
+
+/*
+curl -X POST "http://localhost:8000/starshipitProductUpdate" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "credsPayload": { "credsPath": "starshipit.wf" },
+    "productId": 3015817,
+    "sku": "WFAL48-1-S",
+    "updatePayload": { "hs_code": "6104630011" }
+  }'
+*/

package/api/starshipit/starshipitProductsGet.js

@@ -45,7 +45,7 @@ module.exports = {
 curl -X POST "http://localhost:8000/starshipitProductsGet" \
   -H "Content-Type: application/json" \
   -d '{
-    "credsPayload": { "credsPath": "starshipit.acc" },
-    "options": { "searchTerm": "WFAL48-1-S" }
+    "credsPayload": { "credsPath": "starshipit.wf" },
+    "options": { "limit": 20 }
   }'
 */

package/api/stylearcade/stylearcadeGet.js

@@ -1,4 +1,4 @@
-const { ArgsWarden, Getter } = require('../utils');
+const { ArgsWarden, Getter, valueProvided } = require('../utils');
 const { credsValidator } = require('../validators');
 const { stylearcadeClient } = require('../stylearcade/stylearcade.utils');
 const { MAX_PER_PAGE } = require('../stylearcade/stylearcade.constants');
@@ -59,7 +59,10 @@ const stylearcadeGetDigester = (response, nodeName) => {
     return [];
   }
 
-  return response?.data?.[nodeName] ?? [];
+  const items = response?.data?.[nodeName] ?? [];
+  // Filter out items that have data property, but it's null
+  const meaningfulItems = items.filter(item => Object.hasOwn(item, 'data') && valueProvided(item.data));
+  return meaningfulItems;
 };
 
 const stylearcadeGet = async (

package/api/utils.js

@@ -1411,6 +1411,43 @@ const surveyObject = (
   );
 };
 
+const diffObjects = (
+  sourceOfTruthObject, 
+  comparisonObject,
+  {
+    propMap = {},
+  } = {},
+) => {
+  const diff = {};
+  for (const [key, value] of Object.entries(sourceOfTruthObject)) {
+    const comparisonKey = propMap[key] || key;
+    // TODO: Consider deep equality
+    if (comparisonObject[comparisonKey] !== value) {
+      diff[key] = value;
+    }
+  }
+  return diff;
+};
+
+const objectPropsTranslate = (
+  obj, 
+  propMap,
+  {
+    omitUnmappedProps = false,
+  } = {},
+) => {
+  const translatedObj = {};
+
+  for (const [key, value] of Object.entries(obj)) {
+    if (omitUnmappedProps && !propMap[key]) {
+      continue;
+    }
+    const translatedKey = propMap[key] || key;
+    translatedObj[translatedKey] = value;
+  }
+  return translatedObj;
+};
+
 module.exports = {
   wait,
   timeMs,
@@ -1452,4 +1489,6 @@ module.exports = {
   objectMatchesPartial,
   oneFromManyInResponse,
   surveyObject,
+  diffObjects,
+  objectPropsTranslate,
 };

package/package.json

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