@foxtware/mineral 0.1.14 → 0.1.16

package/.creds.yml.sample

@@ -69,3 +69,37 @@ threeclicks:
   API_KEY: _______________________________
   API_SECRET: ____________________________
   API_DOMAIN: g40-server.instance.3clickscloud.com
+
+printify:
+  API_KEY: _______________________________
+
+etsy:
+  API_KEY: _______________________________
+  SHARED_SECRET: _________________________
+
+clickup:
+  API_KEY: pk________________________________
+
+asana:
+  ACCESS_TOKEN: __________________________
+
+notion:
+  API_KEY: secret________________________________
+
+discord:
+  BOT_TOKEN: ______________________________
+
+telnyx:
+  API_KEY: KEY__________________________________
+
+figma:
+  API_KEY: figd________________________________
+
+pipe17:
+  API_KEY: ____________________________________
+  sandbox:
+    API_KEY: ____________________________________
+
+google:
+  SERVICE_ACCOUNT_JSON:
+    ...

package/AGENTS.md

@@ -12,6 +12,11 @@ Notes for AI assistants working in this directory. **Read this file at the start
 - If you make a new .env or .creds.yml variable, update the correlating .sample file.
 - In Shopify, don't normalise and take gids as inputs if you can just take the id - the non-gid number - instead.
 - Use trailing commas wherever possible, for future git diff readability.
+- Each platform gets its own directory, within which {platform}.constants.js holds constant values like a fixed API base URL or the max objects an API will return per page, docs.md links to documentation and briefly describes the API shape and auth, {platform}.utils.js provides a FetchClient to perform http requests, and the other files are mostly flat functions like {platform}ThingDo.js. If needed, {platform}Get.js can provide a paginated get function for reuse in e.g. {platform}ThingsGet.js.
+- Do not deviate from the project's existing patterns unless you ask the user first. This includes nested structures, use of libraries, and layout of functions.
+- Refer to _example.js files for reference on how functions are laid out, e.g. use of argsWarden.
+- If other functions in the platform use fetchClient as passed through options, support it as well.
+- skim an existing platform of the same shape before considering inventing a new pattern.
 
 ## 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.

package/_build_scripts/createNewFunction.js

@@ -11,9 +11,9 @@ const excludedDirs = new Set([
   'node_modules',
 ]);
 
-const normalizePath = (dirPath) => dirPath.replace(/\/$/, '');
+const normalisePath = (dirPath) => dirPath.replace(/\/$/, '');
 
-const isMineralCwd = () => normalizePath(process.cwd()) === normalizePath(mineralRoot);
+const isMineralCwd = () => normalisePath(process.cwd()) === normalisePath(mineralRoot);
 
 const getContext = () => {
   const inMineral = isMineralCwd();
@@ -192,7 +192,7 @@ const sortExampleFiles = (exampleFiles) => {
   });
 };
 
-const normalizeTemplateArg = (templateArg) => {
+const normaliseTemplateArg = (templateArg) => {
   if (!templateArg) {
     return null;
   }
@@ -227,13 +227,13 @@ const findWorkspaceTemplate = (exampleFiles, templateArg) => {
     return directMatch;
   }
 
-  const normalizedFilename = normalizeTemplateArg(templateArg);
-  const filenameMatches = exampleFiles.filter(file => file.filename === normalizedFilename);
+  const normalisedFilename = normaliseTemplateArg(templateArg);
+  const filenameMatches = exampleFiles.filter(file => file.filename === normalisedFilename);
 
   if (templateArg.includes('/')) {
     const [ prefix, suffix ] = templateArg.split('/');
-    const normalizedSuffix = normalizeTemplateArg(suffix);
-    const prefixedMatch = exampleFiles.find(file => file.relativePath === `${ prefix }/${ normalizedSuffix }`);
+    const normalisedSuffix = normaliseTemplateArg(suffix);
+    const prefixedMatch = exampleFiles.find(file => file.relativePath === `${ prefix }/${ normalisedSuffix }`);
 
     if (prefixedMatch) {
       return prefixedMatch;
@@ -244,7 +244,7 @@ const findWorkspaceTemplate = (exampleFiles, templateArg) => {
     return filenameMatches[0];
   }
 
-  const suffixMatches = exampleFiles.filter(file => file.relativePath.endsWith(`/${ normalizedFilename }`));
+  const suffixMatches = exampleFiles.filter(file => file.relativePath.endsWith(`/${ normalisedFilename }`));
 
   if (suffixMatches.length === 1) {
     return suffixMatches[0];
@@ -280,24 +280,24 @@ const resolveTemplateFromArg = async ({
     return rootExampleJsPath;
   }
 
-  const normalizedFilename = normalizeTemplateArg(templateArg);
+  const normalisedFilename = normaliseTemplateArg(templateArg);
 
   const matchInDir = exampleFiles.find(file => {
-    return file.filename === normalizedFilename
+    return file.filename === normalisedFilename
       || file.displayName === templateArg
-      || file.displayName === normalizedFilename;
+      || file.displayName === normalisedFilename;
   });
 
   if (matchInDir) {
     return matchInDir.fullPath;
   }
 
-  if (normalizedFilename === '_example.js') {
+  if (normalisedFilename === '_example.js') {
     await fs.access(rootExampleJsPath);
     return rootExampleJsPath;
   }
 
-  throw new Error(`Template not found: ${ templateArg } (looked for ${ normalizedFilename } in api/${ dir })`);
+  throw new Error(`Template not found: ${ templateArg } (looked for ${ normalisedFilename } in api/${ dir })`);
 };
 
 const scriptFileContents = async (name, selectedTemplate) => {
@@ -322,7 +322,7 @@ const getDirs = async (targetApiDirectory) => {
   }
 };
 
-const normalizeDirArg = (dirArg) => {
+const normaliseDirArg = (dirArg) => {
   if (!dirArg || dirArg === '.' || dirArg === 'api') {
     return '';
   }
@@ -331,13 +331,13 @@ const normalizeDirArg = (dirArg) => {
 };
 
 const resolveDirArg = ({ dirArg, dirs, inMineral, name }) => {
-  const normalizedDir = normalizeDirArg(dirArg);
+  const normalisedDir = normaliseDirArg(dirArg);
 
-  if (dirs.includes(normalizedDir)) {
-    return normalizedDir;
+  if (dirs.includes(normalisedDir)) {
+    return normalisedDir;
   }
 
-  if (!inMineral && dirs.length === 0 && normalizedDir === '') {
+  if (!inMineral && dirs.length === 0 && normalisedDir === '') {
     return '';
   }
 
@@ -349,7 +349,7 @@ const resolveDirArg = ({ dirArg, dirs, inMineral, name }) => {
     return null;
   }
 
-  return normalizedDir;
+  return normalisedDir;
 };
 
 const buildFuncName = (dir, name) => {

package/api/_example.js

@@ -1,5 +1,5 @@
-const { credsValidator } = require('./validators');
-const { ArgsWarden } = require('./utils');
+const { credsValidator } = require('../validators');
+const { ArgsWarden } = require('../utils');
 
 const argsWarden = new ArgsWarden([
   ['credsPayload', credsValidator],
@@ -12,7 +12,10 @@ const FUNC = async (
   options = {},
 ) => {
 
-  const rejectResponse = await argsWarden.responseIfRejectingArgs({ credsPayload, arg });
+  const rejectResponse = await argsWarden.responseIfRejectingArgs({
+    credsPayload,
+    arg,
+  });
   if (rejectResponse) {
     return rejectResponse;
   }

package/api/_tools/log.js

@@ -0,0 +1,22 @@
+const { logDeep } = require('../utils');
+
+const log = async (req) => {
+  const { headers, body } = req;
+  logDeep({ headers, body });
+  return { ok: true };
+};
+
+const funcApiConfig = {
+  passThroughReq: true,
+};
+
+module.exports = {
+  log,
+  funcApiConfig,
+};
+
+/*
+curl -X POST "http://localhost:8000/log" \
+  -H "Content-Type: application/json" \
+  -d '{ "patrick": "star" }'
+*/

package/api/algolia/docs.md

@@ -0,0 +1,7 @@
+# Algolia
+
+- [REST API index](https://www.algolia.com/doc/rest-api)
+- [Search API](https://www.algolia.com/doc/rest-api/search)
+- [Search an index](https://www.algolia.com/doc/rest-api/search/search-single-index)
+
+Multi-service REST JSON under `https://{applicationId}.algolia.net` (or `-dsn` for Distributed Search Network), authenticated with `x-algolia-application-id` and `x-algolia-api-key` on every request, with `/1/` versioned paths for search, indexing, settings, and related products.

package/api/asana/asana.constants.js

@@ -0,0 +1,7 @@
+const ASANA_API_BASE_URL = 'https://app.asana.com/api/1.0';
+const MAX_PER_PAGE = 100;
+
+module.exports = {
+  ASANA_API_BASE_URL,
+  MAX_PER_PAGE,
+};

package/api/asana/asana.utils.js

@@ -0,0 +1,37 @@
+const { ASANA_API_BASE_URL } = require('../asana/asana.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: {
+        Accept: 'application/json',
+        Authorization: `Bearer ${ ACCESS_TOKEN }`,
+        ...requestPayload.headers,
+      },
+    },
+  };
+};
+
+const asanaClient = new FetchClient({
+  pipeline: [
+    resolveCreds,
+    useBaseUrl(ASANA_API_BASE_URL),
+    useAuthHeaders,
+    'fetch',
+    fetchClientCommonSteps.exitEarlyOnNotOk,
+  ],
+});
+
+module.exports = {
+  asanaClient,
+};

package/api/asana/asanaGet.js

@@ -0,0 +1,150 @@
+// https://developers.asana.com/reference/getuser
+
+const { ArgsWarden, Getter } = require('../utils');
+const { credsValidator } = require('../validators');
+const { asanaClient } = require('../asana/asana.utils');
+const { MAX_PER_PAGE } = require('../asana/asana.constants');
+
+const argsWarden = new ArgsWarden([
+  ['credsPayload', credsValidator],
+  ['url'],
+]);
+
+const digResults = (data, resultsKey) => {
+  if (resultsKey) {
+    return data?.[resultsKey] ?? [];
+  }
+
+  if (Array.isArray(data)) {
+    return data;
+  }
+
+  const arrayEntry = Object.entries(data || {}).find(([, value]) => Array.isArray(value));
+  return arrayEntry ? arrayEntry[1] : [];
+};
+
+const asanaGetPacket = async (
+  credsPayload,
+  url,
+  {
+    params,
+    perPage = MAX_PER_PAGE,
+  } = {},
+) => {
+  return asanaClient.fetch({
+    requestPayload: {
+      url,
+      params: {
+        limit: Math.min(perPage, MAX_PER_PAGE),
+        ...params,
+      },
+    },
+    context: {
+      credsPayload,
+    },
+  });
+};
+
+const asanaGetPaginator = async (currentParams, response) => {
+  const { args, options } = currentParams;
+
+  if (!response?.ok) {
+    return [true];
+  }
+
+  const nextPage = response?.data?.next_page;
+  if (!nextPage?.offset) {
+    return [true];
+  }
+
+  const { params = {} } = options;
+
+  return [false, {
+    args,
+    options: {
+      ...options,
+      params: {
+        ...params,
+        offset: nextPage.offset,
+      },
+    },
+  }];
+};
+
+const asanaGet = async (
+  returnGetter,
+
+  credsPayload,
+  url,
+  {
+    params,
+    perPage = MAX_PER_PAGE,
+    resultsKey,
+    ...getterOptions
+  } = {},
+) => {
+
+  const rejectResponse = await argsWarden.responseIfRejectingArgs({
+    credsPayload,
+    url,
+  });
+  if (rejectResponse) {
+    return rejectResponse;
+  }
+
+  const getter = new Getter(
+    {
+      args: [credsPayload, url],
+      options: {
+        params,
+        perPage,
+      },
+    },
+    {
+      func: asanaGetPacket,
+      digester: (response) => {
+        if (!response?.ok) {
+          return [];
+        }
+
+        if (Array.isArray(response.data?.data)) {
+          return response.data.data;
+        }
+
+        return digResults(response.data, resultsKey);
+      },
+      paginator: asanaGetPaginator,
+      ...getterOptions,
+    },
+  );
+
+  if (returnGetter) {
+    return getter;
+  }
+
+  const data = await getter.run({ returnAll: true });
+
+  return {
+    ok: true,
+    data,
+  };
+};
+
+const funcApiConfig = {
+  argsWarden,
+};
+
+module.exports = {
+  asanaGet: (...args) => asanaGet(false, ...args),
+  asanaGetter: (...args) => asanaGet(true, ...args),
+  funcApiConfig,
+};
+
+/*
+curl -X POST "http://localhost:8000/asanaGet" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "credsPayload": { "credsPath": "asana" },
+    "url": "/users/me"
+  }'
+*/

package/api/asana/docs.md

@@ -0,0 +1,5 @@
+# Asana
+
+- [Developer documentation](https://developers.asana.com/docs)
+
+Resource-oriented REST JSON at `https://app.asana.com/api/1.0` with cursor/offset pagination, using a personal access token or OAuth token in `Authorization: Bearer`.

package/api/athos/docs.md

@@ -0,0 +1,9 @@
+# Athos (SearchSpring)
+
+- [API overview](https://docs.athoscommerce.com/reference/overview)
+- [Search API](https://docs.athoscommerce.com/reference/get-search-results)
+- [Searchspring → Athos migration guide](https://docs.athoscommerce.com/docs/migration-guide-athos)
+
+Versioned GET-centric REST JSON on per-site hosts (`https://{siteId}.a.athoscommerce.net/v1`, plus a separate personalization base for recommendations); storefront calls use `siteId` in the subdomain (no API key on the client), while the Indexing API uses HTTP Basic Auth (`siteId` + `secretKey`).
+
+Legacy Searchspring URLs used `https://{siteId}.a.searchspring.io/api/...` — see the migration guide for 1:1 path mapping.

package/api/bleckmann/bleckmannAsnsGet.js

@@ -21,7 +21,9 @@ const bleckmannAsnsGet = async (
   } = {},
 ) => {
 
-  const rejectResponse = await argsWarden.responseIfRejectingArgs({ credsPayload });
+  const rejectResponse = await argsWarden.responseIfRejectingArgs({
+    credsPayload,
+  });
   if (rejectResponse) {
     return rejectResponse;
   }

package/api/clickup/clickup.constants.js

@@ -0,0 +1,7 @@
+const CLICKUP_API_BASE_URL = 'https://api.clickup.com/api/v2';
+const MAX_PER_PAGE = 100;
+
+module.exports = {
+  CLICKUP_API_BASE_URL,
+  MAX_PER_PAGE,
+};

package/api/clickup/clickup.utils.js

@@ -0,0 +1,36 @@
+const { CLICKUP_API_BASE_URL } = require('../clickup/clickup.constants');
+const { resolveCreds, useBaseUrl } = require('../pipelineSteps');
+const {
+  FetchClient,
+  fetchClientCommonSteps,
+} = require('../utils');
+
+const useAuthHeaders = async (state) => {
+  const { requestPayload, context } = state;
+  const { creds } = context;
+  const { API_KEY } = creds;
+
+  return {
+    requestPayload: {
+      ...requestPayload,
+      headers: {
+        Authorization: API_KEY,
+        ...requestPayload.headers,
+      },
+    },
+  };
+};
+
+const clickupClient = new FetchClient({
+  pipeline: [
+    resolveCreds,
+    useBaseUrl(CLICKUP_API_BASE_URL),
+    useAuthHeaders,
+    'fetch',
+    fetchClientCommonSteps.exitEarlyOnNotOk,
+  ],
+});
+
+module.exports = {
+  clickupClient,
+};

package/api/clickup/clickupGet.js

@@ -0,0 +1,150 @@
+// https://developer.clickup.com/reference/getauthorizeduser
+
+const { ArgsWarden, Getter } = require('../utils');
+const { credsValidator } = require('../validators');
+const { clickupClient } = require('../clickup/clickup.utils');
+const { MAX_PER_PAGE } = require('../clickup/clickup.constants');
+
+const argsWarden = new ArgsWarden([
+  ['credsPayload', credsValidator],
+  ['url'],
+]);
+
+const digResults = (data, resultsKey) => {
+  if (resultsKey) {
+    return data?.[resultsKey] ?? [];
+  }
+
+  if (Array.isArray(data)) {
+    return data;
+  }
+
+  const arrayEntry = Object.entries(data || {}).find(([, value]) => Array.isArray(value));
+  return arrayEntry ? arrayEntry[1] : [];
+};
+
+const clickupGetPacket = async (
+  credsPayload,
+  url,
+  {
+    params,
+    perPage = MAX_PER_PAGE,
+  } = {},
+) => {
+  return clickupClient.fetch({
+    requestPayload: {
+      url,
+      params: {
+        limit: Math.min(perPage, MAX_PER_PAGE),
+        ...params,
+        page: params?.page ?? 0,
+      },
+    },
+    context: {
+      credsPayload,
+    },
+  });
+};
+
+const clickupGetPaginator = async (currentParams, response) => {
+  const { args, options } = currentParams;
+
+  if (!response?.ok) {
+    return [true];
+  }
+
+  if (response.data?.last_page !== false) {
+    return [true];
+  }
+
+  const { params = {} } = options;
+  const page = params.page ?? 0;
+
+  return [false, {
+    args,
+    options: {
+      ...options,
+      params: {
+        ...params,
+        page: page + 1,
+      },
+    },
+  }];
+};
+
+const clickupGet = async (
+  returnGetter,
+
+  credsPayload,
+  url,
+  {
+    params,
+    perPage = MAX_PER_PAGE,
+    resultsKey,
+    ...getterOptions
+  } = {},
+) => {
+
+  const rejectResponse = await argsWarden.responseIfRejectingArgs({
+    credsPayload,
+    url,
+  });
+  if (rejectResponse) {
+    return rejectResponse;
+  }
+
+  const getter = new Getter(
+    {
+      args: [credsPayload, url],
+      options: {
+        params,
+        perPage,
+      },
+    },
+    {
+      func: clickupGetPacket,
+      digester: (response) => {
+        if (!response?.ok) {
+          return [];
+        }
+
+        return digResults(response.data, resultsKey);
+      },
+      paginator: clickupGetPaginator,
+      ...getterOptions,
+    },
+  );
+
+  if (returnGetter) {
+    return getter;
+  }
+
+  const data = await getter.run({ returnAll: true });
+
+  return {
+    ok: true,
+    data,
+  };
+};
+
+const funcApiConfig = {
+  argsWarden,
+};
+
+module.exports = {
+  clickupGet: (...args) => clickupGet(false, ...args),
+  clickupGetter: (...args) => clickupGet(true, ...args),
+  funcApiConfig,
+};
+
+/*
+curl -X POST "http://localhost:8000/clickupGet" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "credsPayload": { "credsPath": "clickup" },
+    "url": "/team",
+    "options": {
+      "resultsKey": "teams"
+    }
+  }'
+*/

package/api/clickup/docs.md

@@ -0,0 +1,6 @@
+# ClickUp
+
+- [Developer documentation](https://developer.clickup.com/)
+- [Authentication](https://developer.clickup.com/docs/authentication)
+
+Versioned REST JSON under `https://api.clickup.com/api/v2`, authenticated with a personal `pk_` token or OAuth access token in the `Authorization` header (personal tokens are sent raw, without a `Bearer` prefix).

package/api/discord/discord.constants.js

@@ -0,0 +1,7 @@
+const DISCORD_API_BASE_URL = 'https://discord.com/api/v10';
+const MAX_PER_PAGE = 100;
+
+module.exports = {
+  DISCORD_API_BASE_URL,
+  MAX_PER_PAGE,
+};

package/api/discord/discord.utils.js

@@ -0,0 +1,36 @@
+const { DISCORD_API_BASE_URL } = require('../discord/discord.constants');
+const { resolveCreds, useBaseUrl } = require('../pipelineSteps');
+const {
+  FetchClient,
+  fetchClientCommonSteps,
+} = require('../utils');
+
+const useAuthHeaders = async (state) => {
+  const { requestPayload, context } = state;
+  const { creds } = context;
+  const { BOT_TOKEN } = creds;
+
+  return {
+    requestPayload: {
+      ...requestPayload,
+      headers: {
+        Authorization: `Bot ${ BOT_TOKEN }`,
+        ...requestPayload.headers,
+      },
+    },
+  };
+};
+
+const discordClient = new FetchClient({
+  pipeline: [
+    resolveCreds,
+    useBaseUrl(DISCORD_API_BASE_URL),
+    useAuthHeaders,
+    'fetch',
+    fetchClientCommonSteps.exitEarlyOnNotOk,
+  ],
+});
+
+module.exports = {
+  discordClient,
+};