@foxtware/mineral 0.1.27 → 0.1.29

package/.creds.yml.sample

@@ -2,6 +2,7 @@ shopify:
   au:
     STORE_HANDLE: ________________________
     API_KEY: shpat________________________
+    STOREFRONT_API_KEY: __________________
 
 peoplevox:
   CLIENT_ID: _____________________________
@@ -94,6 +95,8 @@ telnyx:
 
 figma:
   API_KEY: figd___________________________
+  # Or use ACCESS_TOKEN for an OAuth 2 bearer token
+  ACCESS_TOKEN: __________________________
 
 pipe17:
   API_KEY: _______________________________
@@ -126,3 +129,29 @@ tableau:
   PAT_SECRET: ____________________________
   SERVER_URL: ____________________________
   SITE_CONTENT_URL: ______________________
+
+salesforce:
+  # Option A — pre-issued token
+  ACCESS_TOKEN: __________________________
+  INSTANCE_URL: https://________.my.salesforce.com
+
+  # Option B — client credentials (if ACCESS_TOKEN missing)
+  CLIENT_ID: _____________________________
+  CLIENT_SECRET: _________________________
+  LOGIN_URL: https://login.salesforce.com  # or My Domain / test.salesforce.com
+
+fastsimon:
+  store:                                   # instance name of your choice
+    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: _________________________

package/AGENTS.md

@@ -25,3 +25,27 @@ Notes for AI assistants working in this directory. **Read this file at the start
 ## API clients
 - Base URLs for platform clients should live in `{platform}.constants.js`, not creds, if they are static for all users of the API.
 - Don't explicitly set `Content-Type: application/json` on the client — `customFetch` already adds it when there is a request body.
+
+## Usual structure of a platform API client
+This is the usual structure, but it can be altered per platform, if required. If there is no good reason to deviate, this is how a platform should look.
+- Functions live in `/api/[platform]`
+- If `docs.md` exists, it is a minimal link to native API documentation and a brief description of its structure. It is not concerned with our implementation and does not need to be updated.
+- Creds are supported by path from `.creds.yml`. `.creds.yml.sample` documents the structure of the required creds.
+- A customised FetchClient called `[platform]Client` exists in `[platform].utils.js`, which handles API requests. It implements a base URL, and resolves `credsPayload` into `context.creds` for future steps.
+- All functions require a `credsPayload` argument to tell them which credentials to use. They relate per instance.
+- `[platform].constants.js` contains any max pagination limits, default API version, base url (if not changing per instance).
+- `[platform]Get.js` is a generic function which gets resources in a paginated way. It implements Getter, and all `[platform]ResourceGet.js` functions export both `platformResourceGet` and `platformResourceGetter`, using the "bind" export style.
+- Each endpoint of the platform's API is supported as a separate function within the platform directory. Functions are named `[platform]NounVerb.js`, e.g. `shopifyPageDelete`.
+- Endpoints should return the unwrapped data inside the standard response format, e.g. `data: { ...resource }`. Not e.g. `data: { product/data/result: { ...resource } }`.
+- Each function creates and exports an `ArgsWarden`. Inside, mandatory arguments are validated. At minimum, all mandatory arguments should be a singleton, which falls back to a generic "value provided" validator. Anything that is not mandatory should be an option, included in the optional "options" argument which is commonly destructured in the function definition.
+- 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/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"
+  }'
+*/

package/api/dropbox/dropboxFileDownload.js

@@ -0,0 +1,139 @@
+// https://www.dropbox.com/developers/documentation/http/documentation#files-download
+// Returns file metadata plus contents as base64 (JSON-safe).
+
+const { ArgsWarden, actionSingleOrMultiple, logDeep } = require('../utils');
+const { credsValidator } = require('../validators');
+const { customFetch, appendUrlToBase, credsFromPayload } = require('../utils');
+const { DROPBOX_CONTENT_BASE_URL } = require('../dropbox/dropbox.constants');
+
+const argsWarden = new ArgsWarden([
+  ['credsPayload', credsValidator],
+  ['path'],
+]);
+
+const dropboxFileDownloadSingle = async (
+  credsPayload,
+  path,
+  {
+    rev,
+    // When true, return raw ArrayBuffer in data.contentsBuffer instead of base64
+    // (not useful over funcApi JSON; kept for in-process callers).
+    asBuffer = false,
+  } = {},
+) => {
+  const creds = await credsFromPayload(credsPayload);
+  const { ACCESS_TOKEN } = creds ?? {};
+
+  if (!ACCESS_TOKEN) {
+    return {
+      ok: false,
+      error: {
+        code: 'MISSING_DROPBOX_CREDS',
+        message: 'dropbox creds require ACCESS_TOKEN',
+      },
+    };
+  }
+
+  const arg = {
+    path,
+    ...(rev !== undefined && { rev }),
+  };
+
+  const url = appendUrlToBase(DROPBOX_CONTENT_BASE_URL, '/files/download');
+
+  // customFetch so we can read Dropbox-API-Result header + binary body.
+  const response = await customFetch(url, {
+    method: 'post',
+    headers: {
+      Authorization: `Bearer ${ ACCESS_TOKEN }`,
+      'Dropbox-API-Arg': JSON.stringify(arg),
+    },
+    // Empty body; Dropbox still expects POST.
+    body: '',
+    responseParser: async (res) => {
+      const resultHeader = res.headers.get('dropbox-api-result');
+      let metadata = null;
+      if (resultHeader) {
+        try {
+          metadata = JSON.parse(resultHeader);
+        } catch {
+          metadata = { raw: resultHeader };
+        }
+      }
+
+      const buffer = Buffer.from(await res.arrayBuffer());
+      return {
+        metadata,
+        buffer,
+      };
+    },
+  });
+
+  if (!response.ok) {
+    logDeep({ error: response.error ?? response.data });
+    return {
+      ok: false,
+      error: response.error ?? response.data,
+    };
+  }
+
+  const { metadata, buffer } = response.data;
+
+  return {
+    ok: true,
+    data: {
+      ...(metadata || {}),
+      ...(asBuffer
+        ? { contentsBuffer: buffer }
+        : { contentsBase64: buffer.toString('base64') }),
+      size: buffer.length,
+    },
+  };
+};
+
+const dropboxFileDownload = async (
+  credsPayload,
+  path,
+  {
+    rev,
+    asBuffer,
+    queueRunOptions,
+  } = {},
+) => {
+  const rejectResponse = await argsWarden.responseIfRejectingArgs({
+    credsPayload,
+    path,
+  });
+  if (rejectResponse) {
+    return rejectResponse;
+  }
+
+  return actionSingleOrMultiple(
+    path,
+    dropboxFileDownloadSingle,
+    (pathItem) => ({
+      args: [credsPayload, pathItem, { rev, asBuffer }],
+    }),
+    {
+      ...(queueRunOptions ? { queueRunOptions } : {}),
+    },
+  );
+};
+
+const funcApiConfig = {
+  argsWarden,
+};
+
+module.exports = {
+  dropboxFileDownload,
+  funcApiConfig,
+};
+
+/*
+curl -X POST "http://localhost:8000/dropboxFileDownload" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "credsPayload": { "credsPath": "dropbox" },
+    "path": "/Homework/math/Prime_Numbers.txt"
+  }'
+*/

package/api/dropbox/dropboxFileMetadataGet.js

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