@foxtware/mineral 0.1.29 → 0.1.31

package/.creds.yml.sample

@@ -155,3 +155,24 @@ spotify:
   # Option B — app client credentials (catalog-only; auto-minted token)
   CLIENT_ID: _____________________________
   CLIENT_SECRET: _________________________
+
+paypal:
+  CLIENT_ID: _____________________________
+  CLIENT_SECRET: _________________________
+  # SANDBOX: true   # only if using sandbox credentials
+
+royalmail:
+  CLIENT_ID: _____________________________
+  CLIENT_SECRET: _________________________
+
+dpd:
+  ACCOUNT_NUMBER: _________________________
+  USERNAME: ______________________________
+  PASSWORD: ______________________________
+  # BASE_URL: https://api.dpdlocal.co.uk  # only for DPD Local accounts
+
+fedex:
+  CLIENT_ID: _____________________________
+  CLIENT_SECRET: _________________________
+  # SANDBOX: true   # only if using sandbox credentials
+  

package/api/dpd/docs.md

@@ -0,0 +1,6 @@
+# DPD
+
+- [DPD UK technology and API information](https://dpd.co.uk/content/about_dpd/technology.jsp)
+- [DPD API documentation](https://www.dpd.com/wp-content/uploads/sites/235/2023/04/DPD-API-documentation-v1-2-1.pdf)
+
+DPD API access is account-managed. DPD UK credentials authenticate against `https://api.dpd.co.uk/user/?action=login`, returning a `geoSession` token. The tracking client uses that session with the DPD network tracking endpoint. DPD Local accounts can use the same client with their account-specific `BASE_URL`.

package/api/dpd/dpd.constants.js

@@ -0,0 +1,9 @@
+const DPD_API_BASE_URL = 'https://api.dpd.co.uk';
+const DPD_AUTH_PATH = '/user/?action=login';
+const DPD_TRACKING_PATH = '/shipping/network';
+
+module.exports = {
+  DPD_API_BASE_URL,
+  DPD_AUTH_PATH,
+  DPD_TRACKING_PATH,
+};

package/api/dpd/dpd.utils.js

@@ -0,0 +1,145 @@
+const { resolveCreds } = require('../pipelineSteps');
+const {
+  FetchClient,
+  appendUrlToBase,
+  customFetch,
+  fetchClientCommonSteps,
+} = require('../utils');
+const {
+  DPD_API_BASE_URL,
+  DPD_AUTH_PATH,
+} = require('./dpd.constants');
+
+const geoSessionCache = new Map();
+
+const baseUrlForCreds = (creds) => {
+  return (creds?.BASE_URL || DPD_API_BASE_URL).replace(/\/$/, '');
+};
+
+const geoClientForCreds = (creds) => {
+  return creds?.GEO_CLIENT || `account/${ creds?.ACCOUNT_NUMBER || '' }`;
+};
+
+const cacheKeyForCreds = (creds) => {
+  return [
+    baseUrlForCreds(creds),
+    creds?.USERNAME || '',
+    creds?.ACCOUNT_NUMBER || '',
+  ].join(':');
+};
+
+const getGeoSession = async (creds) => {
+  const {
+    USERNAME,
+    PASSWORD,
+  } = creds || {};
+
+  if (!USERNAME || !PASSWORD || !geoClientForCreds(creds).split('/').pop()) {
+    throw new Error(
+      'DPD creds require USERNAME, PASSWORD, and ACCOUNT_NUMBER or GEO_CLIENT',
+    );
+  }
+
+  const cacheKey = cacheKeyForCreds(creds);
+  const cachedSession = geoSessionCache.get(cacheKey);
+  if (cachedSession && cachedSession.expiresAt > Date.now()) {
+    return cachedSession.geoSession;
+  }
+
+  const basicAuth = Buffer
+    .from(`${ USERNAME }:${ PASSWORD }`)
+    .toString('base64');
+  const response = await customFetch(
+    appendUrlToBase(baseUrlForCreds(creds), DPD_AUTH_PATH),
+    {
+      method: 'post',
+      headers: {
+        Accept: 'application/json',
+        Authorization: `Basic ${ basicAuth }`,
+        GEOClient: geoClientForCreds(creds),
+      },
+    },
+  );
+
+  if (!response.ok) {
+    throw new Error(
+      `DPD authentication failed: ${ JSON.stringify(response.error || response.data) }`,
+    );
+  }
+
+  const geoSession = response.data?.geoSession || response.data?.data?.geoSession;
+  if (!geoSession) {
+    throw new Error('DPD authentication response missing geoSession');
+  }
+
+  geoSessionCache.set(cacheKey, {
+    geoSession,
+    expiresAt: Date.now() + (60 * 60 * 1000),
+  });
+
+  return geoSession;
+};
+
+const useBaseUrlFromCreds = async (state) => {
+  const { requestPayload, context } = state;
+  const { creds } = context;
+
+  return {
+    requestPayload: {
+      ...requestPayload,
+      url: appendUrlToBase(
+        baseUrlForCreds(creds),
+        requestPayload.url || '',
+      ),
+    },
+  };
+};
+
+const useAuthHeaders = async (state) => {
+  const { requestPayload, context } = state;
+  const { creds } = context;
+
+  let geoSession;
+  try {
+    geoSession = await getGeoSession(creds);
+  } catch (error) {
+    return {
+      breakChain: true,
+      response: {
+        ok: false,
+        error: {
+          code: 'DPD_AUTH_ERROR',
+          message: error.message,
+        },
+      },
+    };
+  }
+
+  return {
+    requestPayload: {
+      ...requestPayload,
+      headers: {
+        Accept: 'application/json',
+        GEOClient: geoClientForCreds(creds),
+        GEOSession: geoSession,
+        ...requestPayload.headers,
+      },
+    },
+  };
+};
+
+const dpdClient = new FetchClient({
+  pipeline: [
+    resolveCreds,
+    useBaseUrlFromCreds,
+    useAuthHeaders,
+    'fetch',
+    fetchClientCommonSteps.exitEarlyOnNotOk,
+  ],
+});
+
+module.exports = {
+  dpdClient,
+  geoSessionCache,
+  getGeoSession,
+};

package/api/dpd/dpdTrackingGet.js

@@ -0,0 +1,64 @@
+// https://www.dpd.com/wp-content/uploads/sites/235/2023/04/DPD-API-documentation-v1-2-1.pdf
+
+const { ArgsWarden } = require('../utils');
+const { credsValidator } = require('../validators');
+const { DPD_TRACKING_PATH } = require('./dpd.constants');
+const { dpdClient } = require('./dpd.utils');
+
+const trackingIdentifierValidator = (trackingIdentifier) => {
+  return Boolean(trackingIdentifier?.trackingNumber);
+};
+
+const argsWarden = new ArgsWarden([
+  ['credsPayload', credsValidator],
+  ['trackingIdentifier', trackingIdentifierValidator],
+]);
+
+const dpdTrackingGet = async (
+  credsPayload,
+  trackingIdentifier,
+  {
+    fetchClient = dpdClient,
+  } = {},
+) => {
+  const rejectResponse = await argsWarden.responseIfRejectingArgs({
+    credsPayload,
+    trackingIdentifier,
+  });
+  if (rejectResponse) {
+    return rejectResponse;
+  }
+
+  const {
+    trackingNumber,
+  } = trackingIdentifier;
+
+  return fetchClient.fetch({
+    requestPayload: {
+      url: `${ DPD_TRACKING_PATH }/${ encodeURIComponent(trackingNumber) }`,
+    },
+    context: {
+      credsPayload,
+    },
+  });
+};
+
+const funcApiConfig = {
+  argsWarden,
+};
+
+module.exports = {
+  dpdTrackingGet,
+  funcApiConfig,
+};
+
+/*
+curl -X POST "http://localhost:8000/dpdTrackingGet" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "credsPayload": { "credsPath": "dpd" },
+    "trackingIdentifier": {
+      "trackingNumber": "15509742315259"
+    }
+  }'
+*/

package/api/fedex/docs.md

@@ -0,0 +1,6 @@
+# FedEx
+
+- [FedEx Developer Portal](https://developer.fedex.com/)
+- [FedEx Track API](https://developer.fedex.com/api/en-us/catalog/track.html)
+
+FedEx tracking uses OAuth 2.0 client credentials. Create a project with the Track API enabled, obtain a bearer token from `https://apis.fedex.com/oauth/token`, and submit tracking requests to `https://apis.fedex.com/track/v1/trackingnumbers`. Sandbox requests use `https://apis-sandbox.fedex.com`.

package/api/fedex/fedex.constants.js

@@ -0,0 +1,11 @@
+const FEDEX_LIVE_BASE_URL = 'https://apis.fedex.com';
+const FEDEX_SANDBOX_BASE_URL = 'https://apis-sandbox.fedex.com';
+const FEDEX_OAUTH_PATH = '/oauth/token';
+const FEDEX_TRACKING_PATH = '/track/v1/trackingnumbers';
+
+module.exports = {
+  FEDEX_LIVE_BASE_URL,
+  FEDEX_SANDBOX_BASE_URL,
+  FEDEX_OAUTH_PATH,
+  FEDEX_TRACKING_PATH,
+};

package/api/fedex/fedex.utils.js

@@ -0,0 +1,151 @@
+const { resolveCreds } = require('../pipelineSteps');
+const {
+  FetchClient,
+  appendUrlToBase,
+  customFetch,
+  fetchClientCommonSteps,
+} = require('../utils');
+const {
+  FEDEX_LIVE_BASE_URL,
+  FEDEX_OAUTH_PATH,
+  FEDEX_SANDBOX_BASE_URL,
+} = require('./fedex.constants');
+
+const accessTokenCache = new Map();
+
+const isSandboxCreds = (creds) => {
+  return creds?.SANDBOX === true
+    || creds?.SANDBOX === 'true'
+    || creds?.ENVIRONMENT === 'sandbox';
+};
+
+const baseUrlForCreds = (creds) => {
+  return (creds?.BASE_URL || (
+    isSandboxCreds(creds)
+      ? FEDEX_SANDBOX_BASE_URL
+      : FEDEX_LIVE_BASE_URL
+  )).replace(/\/$/, '');
+};
+
+const getAccessToken = async (creds) => {
+  if (creds?.ACCESS_TOKEN) {
+    return creds.ACCESS_TOKEN;
+  }
+
+  const {
+    CLIENT_ID,
+    CLIENT_SECRET,
+  } = creds || {};
+  if (!CLIENT_ID || !CLIENT_SECRET) {
+    throw new Error(
+      'FedEx creds require ACCESS_TOKEN or CLIENT_ID and CLIENT_SECRET',
+    );
+  }
+
+  const cacheKey = `${ baseUrlForCreds(creds) }:${ CLIENT_ID }`;
+  const cachedToken = accessTokenCache.get(cacheKey);
+  if (cachedToken && cachedToken.expiresAt > Date.now()) {
+    return cachedToken.accessToken;
+  }
+
+  const basicAuth = Buffer
+    .from(`${ CLIENT_ID }:${ CLIENT_SECRET }`)
+    .toString('base64');
+  const response = await customFetch(
+    appendUrlToBase(baseUrlForCreds(creds), FEDEX_OAUTH_PATH),
+    {
+      method: 'post',
+      headers: {
+        Accept: 'application/json',
+        Authorization: `Basic ${ basicAuth }`,
+        'Content-Type': 'application/x-www-form-urlencoded',
+      },
+      body: 'grant_type=client_credentials',
+    },
+  );
+
+  if (!response.ok) {
+    throw new Error(
+      `FedEx authentication failed: ${ JSON.stringify(response.error || response.data) }`,
+    );
+  }
+
+  const {
+    access_token: accessToken,
+    expires_in: expiresIn = 3600,
+  } = response.data || {};
+  if (!accessToken) {
+    throw new Error('FedEx authentication response missing access_token');
+  }
+
+  accessTokenCache.set(cacheKey, {
+    accessToken,
+    expiresAt: Date.now() + (Math.max(expiresIn - 60, 60) * 1000),
+  });
+
+  return accessToken;
+};
+
+const useBaseUrlFromCreds = async (state) => {
+  const { requestPayload, context } = state;
+  const { creds } = context;
+
+  return {
+    requestPayload: {
+      ...requestPayload,
+      url: appendUrlToBase(
+        baseUrlForCreds(creds),
+        requestPayload.url || '',
+      ),
+    },
+  };
+};
+
+const useAuthHeaders = async (state) => {
+  const { requestPayload, context } = state;
+  const { creds } = context;
+
+  let accessToken;
+  try {
+    accessToken = await getAccessToken(creds);
+  } catch (error) {
+    return {
+      breakChain: true,
+      response: {
+        ok: false,
+        error: {
+          code: 'FEDEX_AUTH_ERROR',
+          message: error.message,
+        },
+      },
+    };
+  }
+
+  return {
+    requestPayload: {
+      ...requestPayload,
+      headers: {
+        Accept: 'application/json',
+        Authorization: `Bearer ${ accessToken }`,
+        ...requestPayload.headers,
+      },
+    },
+  };
+};
+
+const fedexClient = new FetchClient({
+  pipeline: [
+    resolveCreds,
+    useBaseUrlFromCreds,
+    useAuthHeaders,
+    'fetch',
+    fetchClientCommonSteps.exitEarlyOnNotOk,
+  ],
+});
+
+module.exports = {
+  accessTokenCache,
+  baseUrlForCreds,
+  fedexClient,
+  getAccessToken,
+};

package/api/fedex/fedexTrackingGet.js

@@ -0,0 +1,76 @@
+// https://developer.fedex.com/api/en-us/catalog/track.html
+
+const { ArgsWarden } = require('../utils');
+const { credsValidator } = require('../validators');
+const { FEDEX_TRACKING_PATH } = require('./fedex.constants');
+const { fedexClient } = require('./fedex.utils');
+
+const trackingIdentifierValidator = (trackingIdentifier) => {
+  return Boolean(trackingIdentifier?.trackingNumber);
+};
+
+const argsWarden = new ArgsWarden([
+  ['credsPayload', credsValidator],
+  ['trackingIdentifier', trackingIdentifierValidator],
+]);
+
+const fedexTrackingGet = async (
+  credsPayload,
+  trackingIdentifier,
+  {
+    includeDetailedScans = true,
+    fetchClient = fedexClient,
+  } = {},
+) => {
+  const rejectResponse = await argsWarden.responseIfRejectingArgs({
+    credsPayload,
+    trackingIdentifier,
+  });
+  if (rejectResponse) {
+    return rejectResponse;
+  }
+
+  const {
+    trackingNumber,
+  } = trackingIdentifier;
+
+  return fetchClient.fetch({
+    requestPayload: {
+      method: 'post',
+      url: FEDEX_TRACKING_PATH,
+      body: {
+        includeDetailedScans,
+        trackingInfo: [
+          {
+            trackingNumberInfo: {
+              trackingNumber,
+            },
+          },
+        ],
+      },
+    },
+    context: {
+      credsPayload,
+    },
+  });
+};
+
+const funcApiConfig = {
+  argsWarden,
+};
+
+module.exports = {
+  fedexTrackingGet,
+  funcApiConfig,
+};
+
+/*
+curl -X POST "http://localhost:8000/fedexTrackingGet" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "credsPayload": { "credsPath": "fedex" },
+    "trackingIdentifier": {
+      "trackingNumber": "872442694112"
+    }
+  }'
+*/

package/api/paypal/docs.md

@@ -0,0 +1,14 @@
+# PayPal
+
+- [REST API overview](https://developer.paypal.com/api/rest/)
+- [Authentication](https://developer.paypal.com/api/rest/authentication/)
+- [Orders v2](https://developer.paypal.com/docs/api/orders/v2/)
+- [Payments v2](https://developer.paypal.com/docs/api/payments/v2/)
+- [Transaction Search](https://developer.paypal.com/docs/api/transaction-search/v1/)
+- [Identity / userinfo](https://developer.paypal.com/docs/api/identity/v1/)
+
+REST JSON under `https://api-m.paypal.com` (live) or `https://api-m.sandbox.paypal.com` (sandbox). OAuth 2.0 client-credentials: exchange `CLIENT_ID` + `CLIENT_SECRET` for a short-lived bearer token via `POST /v1/oauth2/token`, then send `Authorization: Bearer <token>` on every call.
+
+Create a REST app under [Developer Dashboard → Apps & Credentials](https://developer.paypal.com/dashboard/applications). Toggle Sandbox vs Live for the matching client id/secret. Personal (first-party) apps can call Orders, Payments, Transaction Search, and Balances for the account that owns the app; some identity scopes need additional app configuration.
+
+Transaction Search and Balances typically need the reporting scopes enabled on the app. Tokens expire (~hours); this client caches and refreshes them automatically.

package/api/paypal/paypal.constants.js

@@ -0,0 +1,13 @@
+const LIVE_BASE_URL = 'https://api-m.paypal.com';
+const SANDBOX_BASE_URL = 'https://api-m.sandbox.paypal.com';
+
+// Default page size for list-style reporting endpoints
+const DEFAULT_PAGE_SIZE = 100;
+const MAX_PAGE_SIZE = 500;
+
+module.exports = {
+  LIVE_BASE_URL,
+  SANDBOX_BASE_URL,
+  DEFAULT_PAGE_SIZE,
+  MAX_PAGE_SIZE,
+};

package/api/paypal/paypal.utils.js

@@ -0,0 +1,166 @@
+// https://developer.paypal.com/api/rest/authentication/
+
+const {
+  LIVE_BASE_URL,
+  SANDBOX_BASE_URL,
+} = require('../paypal/paypal.constants');
+const { resolveCreds } = require('../pipelineSteps');
+const {
+  FetchClient,
+  fetchClientCommonSteps,
+  customFetch,
+  appendUrlToBase,
+} = require('../utils');
+
+// Cache client-credentials tokens per CLIENT_ID + environment.
+const clientCredentialsTokenCache = new Map();
+
+const isSandboxCreds = (creds) => {
+  if (creds?.SANDBOX === true || creds?.SANDBOX === 'true') {
+    return true;
+  }
+  if (creds?.ENVIRONMENT === 'sandbox' || creds?.MODE === 'sandbox') {
+    return true;
+  }
+  return false;
+};
+
+const baseUrlForCreds = (creds) => {
+  if (creds?.BASE_URL) {
+    return creds.BASE_URL.replace(/\/$/, '');
+  }
+  return isSandboxCreds(creds) ? SANDBOX_BASE_URL : LIVE_BASE_URL;
+};
+
+const tokenCacheKey = (creds) => {
+  const env = isSandboxCreds(creds) ? 'sandbox' : 'live';
+  return `${ env }:${ creds?.CLIENT_ID || '' }`;
+};
+
+const getClientCredentialsToken = async (creds) => {
+  const { CLIENT_ID, CLIENT_SECRET } = creds ?? {};
+  if (!CLIENT_ID || !CLIENT_SECRET) {
+    throw new Error('paypal client_credentials require CLIENT_ID and CLIENT_SECRET');
+  }
+
+  const cacheKey = tokenCacheKey(creds);
+  const cached = clientCredentialsTokenCache.get(cacheKey);
+  if (cached && cached.expiresAt > Date.now()) {
+    return cached.accessToken;
+  }
+
+  const baseUrl = baseUrlForCreds(creds);
+  const basic = Buffer
+    .from(`${ CLIENT_ID }:${ CLIENT_SECRET }`)
+    .toString('base64');
+
+  const response = await customFetch(
+    `${ baseUrl }/v1/oauth2/token`,
+    {
+      method: 'post',
+      headers: {
+        Authorization: `Basic ${ basic }`,
+        'Content-Type': 'application/x-www-form-urlencoded',
+        Accept: 'application/json',
+      },
+      body: 'grant_type=client_credentials',
+    },
+  );
+
+  if (!response.ok) {
+    throw new Error(
+      `PayPal client_credentials failed: ${ JSON.stringify(response.error ?? response.data) }`,
+    );
+  }
+
+  const { access_token: accessToken, expires_in: expiresIn = 32400 } = response.data ?? {};
+  if (!accessToken) {
+    throw new Error('PayPal client_credentials response missing access_token');
+  }
+
+  clientCredentialsTokenCache.set(cacheKey, {
+    accessToken,
+    // Refresh a minute early.
+    expiresAt: Date.now() + (Math.max(expiresIn - 60, 60) * 1000),
+  });
+
+  return accessToken;
+};
+
+const resolveAccessToken = async (creds) => {
+  if (creds?.ACCESS_TOKEN) {
+    return creds.ACCESS_TOKEN;
+  }
+
+  const { CLIENT_ID, CLIENT_SECRET } = creds ?? {};
+  if (CLIENT_ID && CLIENT_SECRET) {
+    return getClientCredentialsToken(creds);
+  }
+
+  throw new Error(
+    'paypal creds require ACCESS_TOKEN or CLIENT_ID + CLIENT_SECRET',
+  );
+};
+
+const useBaseUrlFromCreds = async (state) => {
+  const { requestPayload, context } = state;
+  const { creds } = context;
+  const baseUrl = baseUrlForCreds(creds);
+
+  return {
+    requestPayload: {
+      ...requestPayload,
+      url: appendUrlToBase(baseUrl, requestPayload.url || ''),
+    },
+  };
+};
+
+const useAuthHeaders = async (state) => {
+  const { requestPayload, context } = state;
+  const { creds } = context;
+
+  let accessToken;
+  try {
+    accessToken = await resolveAccessToken(creds);
+  } catch (err) {
+    return {
+      response: {
+        ok: false,
+        error: {
+          code: 'PAYPAL_AUTH_FAILED',
+          message: err.message || String(err),
+        },
+      },
+      breakChain: true,
+    };
+  }
+
+  return {
+    requestPayload: {
+      ...requestPayload,
+      headers: {
+        Accept: 'application/json',
+        Authorization: `Bearer ${ accessToken }`,
+        ...requestPayload.headers,
+      },
+    },
+  };
+};
+
+const paypalClient = new FetchClient({
+  pipeline: [
+    resolveCreds,
+    useBaseUrlFromCreds,
+    useAuthHeaders,
+    'fetch',
+    fetchClientCommonSteps.exitEarlyOnNotOk,
+  ],
+});
+
+module.exports = {
+  paypalClient,
+  resolveAccessToken,
+  getClientCredentialsToken,
+  baseUrlForCreds,
+  clientCredentialsTokenCache,
+};