@foxtware/mineral 0.1.28 → 0.1.30

package/.creds.yml.sample

@@ -2,6 +2,7 @@ shopify:
   au:
     STORE_HANDLE: ________________________
     API_KEY: shpat________________________
+    STOREFRONT_API_KEY: __________________
 
 peoplevox:
   CLIENT_ID: _____________________________
@@ -141,5 +142,37 @@ salesforce:
 
 fastsimon:
   store:                                   # instance name of your choice
-    UUID: _______________________________  # Dashboard → Settings
-    STORE_ID: ___________________________  # Dashboard → Settings
+    UUID: ________________________________ # Dashboard → Settings
+    STORE_ID: ____________________________ # Dashboard → Settings
+
+dropbox:
+  ACCESS_TOKEN: __________________________
+
+spotify:
+  # Option A — pre-issued user or client-credentials access token
+  ACCESS_TOKEN: __________________________
+
+  # 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/AGENTS.md

@@ -41,4 +41,11 @@ This is the usual structure, but it can be altered per platform, if required. If
 - For functions which act on a single resource, e.g. `shopifyPageGet`, `actionSingleOrMultiple` is implemented as an enhancement to allow acting on multiple items in a one-by-one fashion.
 - `fetchClient` is implemented as an option, allowing implementations outside mineral core to use their own pipeline in making requests. This may include caching auth or utilising other platforms in the pipeline.
 
+## Doing things
+- If you are being asked to do something that involves using a platform, use this repo's functionality as your first option.
+  - Try using curl commands based on the example curl commands documented in comments on the function files.
+  - If the server is not running, start one with `npm run dev` or `npm run serve`.
+- Where an API functionality is not currently implemented, but fits this repo's mission, create functions for yourself to use, then use those.
 
+## .yml formatting
+When you edit a YAML file, restore whitespaces afterwards.

package/_build_scripts/createNewFunction.js

@@ -22,6 +22,7 @@ const getContext = () => {
     inMineral,
     apiDirectory: inMineral ? mineralApiDirectory : path.join(process.cwd(), 'api'),
     mineralApiDirectory,
+    workspaceName: path.basename(process.cwd()),
   };
 };
 
@@ -390,7 +391,24 @@ const getExampleFilesForContext = async ({ context, dir }) => {
     return sortExampleFiles(await findExampleFiles(path.join(context.apiDirectory, dir)));
   }
 
-  return sortExampleFiles(await collectMineralExampleFiles(context.mineralApiDirectory));
+  const localExampleFiles = (await findExampleFiles(path.join(context.apiDirectory, dir))).map(file => ({
+    ...file,
+    relativePath: file.filename,
+    displayName: file.filename,
+    sourceName: context.workspaceName,
+  }));
+  const mineralExampleFiles = (await collectMineralExampleFiles(context.mineralApiDirectory))
+    .map(file => ({
+      ...file,
+      sourceName: path.basename(mineralRoot),
+    }));
+  const exampleFilesByPath = new Map();
+
+  for (const file of [ ...mineralExampleFiles, ...localExampleFiles ]) {
+    exampleFilesByPath.set(file.relativePath, file);
+  }
+
+  return sortExampleFiles([ ...exampleFilesByPath.values() ]);
 };
 
 const formatTemplateLabel = (file, { inMineral }) => {
@@ -398,7 +416,7 @@ const formatTemplateLabel = (file, { inMineral }) => {
     return file.displayName;
   }
 
-  return file.relativePath;
+  return `${ file.sourceName } > ${ file.relativePath }`;
 };
 
 const selectTemplateInteractive = async ({ exampleFiles, dir, inMineral }) => {
@@ -532,7 +550,12 @@ const createNewFunction = async () => {
         inMineral: context.inMineral,
       });
 
-      const templateLabel = path.relative(mineralRoot, selectedTemplate);
+      const selectedTemplateFile = exampleFiles.find(file => file.fullPath === selectedTemplate);
+      const templateLabel = context.inMineral
+        ? path.relative(mineralRoot, selectedTemplate)
+        : selectedTemplateFile
+          ? formatTemplateLabel(selectedTemplateFile, { inMineral: false })
+          : path.relative(mineralRoot, selectedTemplate);
       console.log(`Using template: ${ templateLabel }`);
 
       await writeNewFunction({

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

@@ -0,0 +1,7 @@
+# Dropbox
+
+- [HTTP documentation](https://www.dropbox.com/developers/documentation/http/documentation)
+- [OAuth guide](https://www.dropbox.com/developers/reference/oauth-guide)
+- [API explorer](https://www.dropbox.com/developers/explorer)
+
+RPC JSON over HTTPS at `https://api.dropboxapi.com/2/...` (most methods are POST with a JSON body). Content upload/download uses `https://content.dropboxapi.com/2/...` with arguments in the `Dropbox-API-Arg` header and binary body or response. Auth is OAuth 2 bearer access token (`Authorization: Bearer`). Paths are rooted at `""` (app or full Dropbox root depending on app permission); folder listing uses cursor pagination via `list_folder` / `list_folder/continue`.

package/api/dropbox/dropbox.constants.js

@@ -0,0 +1,10 @@
+const DROPBOX_API_BASE_URL = 'https://api.dropboxapi.com/2';
+const DROPBOX_CONTENT_BASE_URL = 'https://content.dropboxapi.com/2';
+// list_folder limit max is 2000
+const MAX_PER_PAGE = 2000;
+
+module.exports = {
+  DROPBOX_API_BASE_URL,
+  DROPBOX_CONTENT_BASE_URL,
+  MAX_PER_PAGE,
+};

package/api/dropbox/dropbox.utils.js

@@ -0,0 +1,67 @@
+const {
+  DROPBOX_API_BASE_URL,
+  DROPBOX_CONTENT_BASE_URL,
+} = require('../dropbox/dropbox.constants');
+const { resolveCreds, useBaseUrl } = require('../pipelineSteps');
+const {
+  FetchClient,
+  fetchClientCommonSteps,
+} = require('../utils');
+
+const useAuthHeaders = async (state) => {
+  const { requestPayload, context } = state;
+  const { creds } = context;
+  const { ACCESS_TOKEN } = creds;
+
+  return {
+    requestPayload: {
+      ...requestPayload,
+      headers: {
+        Authorization: `Bearer ${ ACCESS_TOKEN }`,
+        ...requestPayload.headers,
+      },
+    },
+  };
+};
+
+// Dropbox RPC endpoints are almost always POST with a JSON body.
+const defaultPostMethod = async (state) => {
+  const { requestPayload } = state;
+  if (requestPayload.method) {
+    return {};
+  }
+
+  return {
+    requestPayload: {
+      ...requestPayload,
+      method: 'post',
+    },
+  };
+};
+
+const dropboxClient = new FetchClient({
+  pipeline: [
+    resolveCreds,
+    useBaseUrl(DROPBOX_API_BASE_URL),
+    useAuthHeaders,
+    defaultPostMethod,
+    'fetch',
+    fetchClientCommonSteps.exitEarlyOnNotOk,
+  ],
+});
+
+const dropboxContentClient = new FetchClient({
+  pipeline: [
+    resolveCreds,
+    useBaseUrl(DROPBOX_CONTENT_BASE_URL),
+    useAuthHeaders,
+    defaultPostMethod,
+    'fetch',
+    fetchClientCommonSteps.exitEarlyOnNotOk,
+  ],
+});
+
+module.exports = {
+  dropboxClient,
+  dropboxContentClient,
+};

package/api/dropbox/dropboxAccountGet.js

@@ -0,0 +1,64 @@
+// https://www.dropbox.com/developers/documentation/http/documentation#users-get_current_account
+
+const { ArgsWarden, logDeep } = require('../utils');
+const { credsValidator } = require('../validators');
+const { dropboxClient } = require('../dropbox/dropbox.utils');
+
+const argsWarden = new ArgsWarden([
+  ['credsPayload', credsValidator],
+]);
+
+const dropboxAccountGet = async (
+  credsPayload,
+  {
+    fetchClient = dropboxClient,
+  } = {},
+) => {
+  const rejectResponse = await argsWarden.responseIfRejectingArgs({
+    credsPayload,
+  });
+  if (rejectResponse) {
+    return rejectResponse;
+  }
+
+  const response = await fetchClient.fetch({
+    context: { credsPayload },
+    requestPayload: {
+      method: 'post',
+      url: '/users/get_current_account',
+      // Dropbox expects the literal JSON null for no-arg endpoints.
+      headers: {
+        'Content-Type': 'application/json',
+      },
+      body: 'null',
+    },
+  });
+
+  const { ok, data, error } = response;
+  if (!ok) {
+    logDeep({ error });
+    return { ok: false, error };
+  }
+
+  return {
+    ok: true,
+    data,
+  };
+};
+
+const funcApiConfig = {
+  argsWarden,
+};
+
+module.exports = {
+  dropboxAccountGet,
+  funcApiConfig,
+};
+
+/*
+curl -X POST "http://localhost:8000/dropboxAccountGet" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "credsPayload": { "credsPath": "dropbox" }
+  }'
+*/

package/api/dropbox/dropboxFileCopy.js

@@ -0,0 +1,67 @@
+// https://www.dropbox.com/developers/documentation/http/documentation#files-copy_v2
+
+const { ArgsWarden, logDeep } = require('../utils');
+const { credsValidator } = require('../validators');
+const { dropboxClient } = require('../dropbox/dropbox.utils');
+
+const argsWarden = new ArgsWarden([
+  ['credsPayload', credsValidator],
+  ['fromPath'],
+  ['toPath'],
+]);
+
+const dropboxFileCopy = async (
+  credsPayload,
+  fromPath,
+  toPath,
+  {
+    allowSharedFolder = false,
+    autorename = false,
+    allowOwnershipTransfer = false,
+    fetchClient = dropboxClient,
+  } = {},
+) => {
+  const rejectResponse = await argsWarden.responseIfRejectingArgs({
+    credsPayload,
+    fromPath,
+    toPath,
+  });
+  if (rejectResponse) {
+    return rejectResponse;
+  }
+
+  const response = await fetchClient.fetch({
+    context: { credsPayload },
+    requestPayload: {
+      method: 'post',
+      url: '/files/copy_v2',
+      body: {
+        from_path: fromPath,
+        to_path: toPath,
+        allow_shared_folder: allowSharedFolder,
+        autorename,
+        allow_ownership_transfer: allowOwnershipTransfer,
+      },
+    },
+  });
+
+  const { ok, data, error } = response;
+  if (!ok) {
+    logDeep({ error });
+    return { ok: false, error };
+  }
+
+  return {
+    ok: true,
+    data: data.metadata ?? data,
+  };
+};
+
+const funcApiConfig = {
+  argsWarden,
+};
+
+module.exports = {
+  dropboxFileCopy,
+  funcApiConfig,
+};

package/api/dropbox/dropboxFileDelete.js

@@ -0,0 +1,89 @@
+// https://www.dropbox.com/developers/documentation/http/documentation#files-delete_v2
+
+const { ArgsWarden, actionSingleOrMultiple, logDeep } = require('../utils');
+const { credsValidator } = require('../validators');
+const { dropboxClient } = require('../dropbox/dropbox.utils');
+
+const argsWarden = new ArgsWarden([
+  ['credsPayload', credsValidator],
+  ['path'],
+]);
+
+const dropboxFileDeleteSingle = async (
+  credsPayload,
+  path,
+  {
+    parentRev,
+    fetchClient = dropboxClient,
+  } = {},
+) => {
+  const response = await fetchClient.fetch({
+    context: { credsPayload },
+    requestPayload: {
+      method: 'post',
+      url: '/files/delete_v2',
+      body: {
+        path,
+        ...(parentRev !== undefined && { parent_rev: parentRev }),
+      },
+    },
+  });
+
+  const { ok, data, error } = response;
+  if (!ok) {
+    logDeep({ error });
+    return { ok: false, error };
+  }
+
+  return {
+    ok: true,
+    data: data.metadata ?? data,
+  };
+};
+
+const dropboxFileDelete = async (
+  credsPayload,
+  path,
+  {
+    parentRev,
+    queueRunOptions,
+    fetchClient,
+  } = {},
+) => {
+  const rejectResponse = await argsWarden.responseIfRejectingArgs({
+    credsPayload,
+    path,
+  });
+  if (rejectResponse) {
+    return rejectResponse;
+  }
+
+  return actionSingleOrMultiple(
+    path,
+    dropboxFileDeleteSingle,
+    (pathItem) => ({
+      args: [credsPayload, pathItem, { parentRev, fetchClient }],
+    }),
+    {
+      ...(queueRunOptions ? { queueRunOptions } : {}),
+    },
+  );
+};
+
+const funcApiConfig = {
+  argsWarden,
+};
+
+module.exports = {
+  dropboxFileDelete,
+  funcApiConfig,
+};
+
+/*
+curl -X POST "http://localhost:8000/dropboxFileDelete" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "credsPayload": { "credsPath": "dropbox" },
+    "path": "/Homework/math/Prime_Numbers.txt"
+  }'
+*/