@foxtware/mineral 0.1.28 → 0.1.30

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/google/docs.md

@@ -5,3 +5,4 @@ Service account auth via `SERVICE_ACCOUNT_JSON` on the `google` creds path. Uses
 - [Sheets API](https://developers.google.com/workspace/sheets/api/reference/rest)
 - [Drive API](https://developers.google.com/workspace/drive/api/reference/rest/v3)
 - [Calendar API](https://developers.google.com/workspace/calendar/api/v3/reference)
+- [Analytics Data API](https://developers.google.com/analytics/devguides/reporting/data/v1/rest)

package/api/google/google.constants.js

@@ -2,6 +2,7 @@ const GOOGLE_SCOPES = {
   sheets: ['https://www.googleapis.com/auth/spreadsheets'],
   drive: ['https://www.googleapis.com/auth/drive'],
   calendar: ['https://www.googleapis.com/auth/calendar'],
+  analytics: ['https://www.googleapis.com/auth/analytics'],
 };
 
 module.exports = {

package/api/google/google.utils.js

@@ -108,6 +108,26 @@ const getGoogleCalendar = async (
   };
 };
 
+const getGoogleAnalyticsData = async (
+  credsPayload,
+  {
+    subject,
+  } = {},
+) => {
+  const { auth, error } = await getGoogleAuth(credsPayload, {
+    scopes: GOOGLE_SCOPES.analytics,
+    subject,
+  });
+
+  if (error) {
+    return { error };
+  }
+
+  return {
+    client: google.analyticsdata({ version: 'v1beta', auth }),
+  };
+};
+
 const googleApiCall = async (promiseFn) => {
   try {
     const response = await promiseFn();
@@ -132,6 +152,7 @@ module.exports = {
   getGoogleSheets,
   getGoogleDrive,
   getGoogleCalendar,
+  getGoogleAnalyticsData,
   googleApiCall,
   invalidCredsResponse,
 };

package/api/google/googleanalyticsMetadataGet.js

@@ -0,0 +1,62 @@
+// https://developers.google.com/analytics/devguides/reporting/data/v1/rest/v1beta/properties/getMetadata
+
+const { ArgsWarden, objHasAny } = require('../utils');
+const { credsValidator } = require('../validators');
+const { getGoogleAnalyticsData, googleApiCall } = require('../google/google.utils');
+
+const propertyIdentifierValidator = (propertyIdentifier) => {
+  return objHasAny(propertyIdentifier, ['propertyId', 'property']);
+};
+
+const argsWarden = new ArgsWarden([
+  ['credsPayload', credsValidator],
+  ['propertyIdentifier', propertyIdentifierValidator],
+]);
+
+const googleanalyticsMetadataGet = async (
+  credsPayload,
+  propertyIdentifier,
+  {
+    subject,
+  } = {},
+) => {
+
+  const rejectResponse = await argsWarden.responseIfRejectingArgs({
+    credsPayload,
+    propertyIdentifier,
+  });
+  if (rejectResponse) {
+    return rejectResponse;
+  }
+
+  const { propertyId, property } = propertyIdentifier;
+  const propertyName = property ?? `properties/${ propertyId }`;
+
+  const { client, error } = await getGoogleAnalyticsData(credsPayload, { subject });
+
+  if (error) {
+    return error;
+  }
+
+  return googleApiCall(() => client.properties.getMetadata({
+    name: `${ propertyName }/metadata`,
+  }));
+};
+
+const funcApiConfig = {
+  argsWarden,
+};
+
+module.exports = {
+  googleanalyticsMetadataGet,
+  funcApiConfig,
+};
+
+/*
+curl -X POST "http://localhost:8000/googleanalyticsMetadataGet" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "credsPayload": { "credsPath": "google" },
+    "propertyIdentifier": { "propertyId": "402247571" }
+  }'
+*/

package/api/google/googleanalyticsRealtimeReportRun.js

@@ -0,0 +1,103 @@
+// https://developers.google.com/analytics/devguides/reporting/data/v1/rest/v1beta/properties/runRealtimeReport
+
+const { ArgsWarden, objHasAny } = require('../utils');
+const { credsValidator } = require('../validators');
+const { getGoogleAnalyticsData, googleApiCall } = require('../google/google.utils');
+
+const propertyIdentifierValidator = (propertyIdentifier) => {
+  return objHasAny(propertyIdentifier, ['propertyId', 'property']);
+};
+
+const argsWarden = new ArgsWarden([
+  ['credsPayload', credsValidator],
+  ['propertyIdentifier', propertyIdentifierValidator],
+]);
+
+const formatDimensions = (dimensions) => {
+  if (!dimensions) {
+    return undefined;
+  }
+  return dimensions.map((dim) => (typeof dim === 'string' ? { name: dim } : dim));
+};
+
+const formatMetrics = (metrics) => {
+  if (!metrics) {
+    return undefined;
+  }
+  return metrics.map((metric) => (typeof metric === 'string' ? { name: metric } : metric));
+};
+
+const googleanalyticsRealtimeReportRun = async (
+  credsPayload,
+  propertyIdentifier,
+  {
+    subject,
+    dimensions,
+    metrics,
+    dimensionFilter,
+    metricFilter,
+    limit,
+    metricAggregations,
+    orderBys,
+    returnPropertyQuota,
+    minuteRanges,
+  } = {},
+) => {
+
+  const rejectResponse = await argsWarden.responseIfRejectingArgs({
+    credsPayload,
+    propertyIdentifier,
+  });
+  if (rejectResponse) {
+    return rejectResponse;
+  }
+
+  const { propertyId, property } = propertyIdentifier;
+  const propertyName = property ?? `properties/${ propertyId }`;
+
+  const { client, error } = await getGoogleAnalyticsData(credsPayload, { subject });
+
+  if (error) {
+    return error;
+  }
+
+  const formattedDimensions = formatDimensions(dimensions);
+  const formattedMetrics = formatMetrics(metrics);
+
+  return googleApiCall(() => client.properties.runRealtimeReport({
+    property: propertyName,
+    requestBody: {
+      ...formattedDimensions && { dimensions: formattedDimensions },
+      ...formattedMetrics && { metrics: formattedMetrics },
+      ...dimensionFilter && { dimensionFilter },
+      ...metricFilter && { metricFilter },
+      ...limit !== undefined && { limit },
+      ...metricAggregations && { metricAggregations },
+      ...orderBys && { orderBys },
+      ...returnPropertyQuota !== undefined && { returnPropertyQuota },
+      ...minuteRanges && { minuteRanges },
+    },
+  }));
+};
+
+const funcApiConfig = {
+  argsWarden,
+};
+
+module.exports = {
+  googleanalyticsRealtimeReportRun,
+  funcApiConfig,
+};
+
+/*
+curl -X POST "http://localhost:8000/googleanalyticsRealtimeReportRun" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "credsPayload": { "credsPath": "google" },
+    "propertyIdentifier": { "propertyId": "402247571" },
+    "options": {
+      "dimensions": ["country"],
+      "metrics": ["activeUsers"]
+    }
+  }'
+*/

package/api/google/googleanalyticsReportRun.js

@@ -0,0 +1,114 @@
+// https://developers.google.com/analytics/devguides/reporting/data/v1/rest/v1beta/properties/runReport
+
+const { ArgsWarden, objHasAny } = require('../utils');
+const { credsValidator } = require('../validators');
+const { getGoogleAnalyticsData, googleApiCall } = require('../google/google.utils');
+
+const propertyIdentifierValidator = (propertyIdentifier) => {
+  return objHasAny(propertyIdentifier, ['propertyId', 'property']);
+};
+
+const argsWarden = new ArgsWarden([
+  ['credsPayload', credsValidator],
+  ['propertyIdentifier', propertyIdentifierValidator],
+]);
+
+const formatDimensions = (dimensions) => {
+  if (!dimensions) {
+    return undefined;
+  }
+  return dimensions.map((dim) => (typeof dim === 'string' ? { name: dim } : dim));
+};
+
+const formatMetrics = (metrics) => {
+  if (!metrics) {
+    return undefined;
+  }
+  return metrics.map((metric) => (typeof metric === 'string' ? { name: metric } : metric));
+};
+
+const googleanalyticsReportRun = async (
+  credsPayload,
+  propertyIdentifier,
+  {
+    subject,
+    dateRanges,
+    dimensions,
+    metrics,
+    dimensionFilter,
+    metricFilter,
+    offset,
+    limit,
+    metricAggregations,
+    orderBys,
+    currencyCode,
+    cohortSpec,
+    keepEmptyRows,
+    returnPropertyQuota,
+    comparisons,
+  } = {},
+) => {
+
+  const rejectResponse = await argsWarden.responseIfRejectingArgs({
+    credsPayload,
+    propertyIdentifier,
+  });
+  if (rejectResponse) {
+    return rejectResponse;
+  }
+
+  const { propertyId, property } = propertyIdentifier;
+  const propertyName = property ?? `properties/${ propertyId }`;
+
+  const { client, error } = await getGoogleAnalyticsData(credsPayload, { subject });
+
+  if (error) {
+    return error;
+  }
+
+  const formattedDimensions = formatDimensions(dimensions);
+  const formattedMetrics = formatMetrics(metrics);
+
+  return googleApiCall(() => client.properties.runReport({
+    property: propertyName,
+    requestBody: {
+      ...dateRanges && { dateRanges },
+      ...formattedDimensions && { dimensions: formattedDimensions },
+      ...formattedMetrics && { metrics: formattedMetrics },
+      ...dimensionFilter && { dimensionFilter },
+      ...metricFilter && { metricFilter },
+      ...offset !== undefined && { offset },
+      ...limit !== undefined && { limit },
+      ...metricAggregations && { metricAggregations },
+      ...orderBys && { orderBys },
+      ...currencyCode && { currencyCode },
+      ...cohortSpec && { cohortSpec },
+      ...keepEmptyRows !== undefined && { keepEmptyRows },
+      ...returnPropertyQuota !== undefined && { returnPropertyQuota },
+      ...comparisons && { comparisons },
+    },
+  }));
+};
+
+const funcApiConfig = {
+  argsWarden,
+};
+
+module.exports = {
+  googleanalyticsReportRun,
+  funcApiConfig,
+};
+
+/*
+curl -X POST "http://localhost:8000/googleanalyticsReportRun" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "credsPayload": { "credsPath": "google" },
+    "propertyIdentifier": { "propertyId": "402247571" },
+    "options": {
+      "dateRanges": [{ "startDate": "30daysAgo", "endDate": "today" }],
+      "dimensions": ["date"],
+      "metrics": ["activeUsers", "sessions"]
+    }
+  }'
+*/

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,
+};

package/api/paypal/paypalAccessTokenGet.js

@@ -0,0 +1,81 @@
+// https://developer.paypal.com/api/rest/authentication/
+
+const { credsValidator } = require('../validators');
+const { ArgsWarden } = require('../utils');
+const {
+  resolveAccessToken,
+  baseUrlForCreds,
+  getClientCredentialsToken,
+} = require('../paypal/paypal.utils');
+const { resolveCreds } = require('../pipelineSteps');
+const { credsFromPayload } = require('../utils');
+
+const argsWarden = new ArgsWarden([
+  ['credsPayload', credsValidator],
+]);
+
+/**
+ * Resolve (and cache) a PayPal access token for the given creds.
+ * Useful for debugging auth or for callers that need the raw token.
+ */
+const paypalAccessTokenGet = async (
+  credsPayload,
+  {
+    forceRefresh = false,
+  } = {},
+) => {
+
+  const rejectResponse = await argsWarden.responseIfRejectingArgs({
+    credsPayload,
+  });
+  if (rejectResponse) {
+    return rejectResponse;
+  }
+
+  try {
+    const creds = await credsFromPayload(credsPayload);
+
+    if (forceRefresh && creds?.CLIENT_ID) {
+      const { clientCredentialsTokenCache } = require('../paypal/paypal.utils');
+      const env = (creds.SANDBOX === true || creds.SANDBOX === 'true'
+        || creds.ENVIRONMENT === 'sandbox' || creds.MODE === 'sandbox')
+        ? 'sandbox'
+        : 'live';
+      clientCredentialsTokenCache.delete(`${ env }:${ creds.CLIENT_ID }`);
+    }
+
+    const accessToken = await resolveAccessToken(creds);
+    return {
+      ok: true,
+      data: {
+        access_token: accessToken,
+        base_url: baseUrlForCreds(creds),
+      },
+    };
+  } catch (err) {
+    return {
+      ok: false,
+      error: {
+        code: 'PAYPAL_AUTH_FAILED',
+        message: err.message || String(err),
+      },
+    };
+  }
+};
+
+const funcApiConfig = {
+  argsWarden,
+};
+
+module.exports = {
+  paypalAccessTokenGet,
+  funcApiConfig,
+};
+
+/*
+  curl -X POST "http://localhost:8000/paypalAccessTokenGet" \
+    -H "Content-Type: application/json" \
+    -d '{
+      "credsPayload": { "credsPath": "paypal" }
+    }'
+*/