@foxtware/mineral 0.1.8 → 0.1.10

package/.creds.yml.sample

@@ -25,5 +25,47 @@ yotpo:
 linear:
   API_KEY: _______________________________
 
+github:
+  ACCESS_TOKEN: ghp_______________________
+
 slack:
-  BOT_TOKEN: xoxb________________________________
+  BOT_TOKEN: xoxb_________________________
+
+workable:
+  BASE_URL: https://__.workable.com/spi/v3
+  ACCESS_TOKEN: __________________________
+
+loop:
+  au:
+    API_KEY: _____________________________
+
+upstash:
+  BASE_URL: https://___________.upstash.io
+  TOKEN: _________________________________
+
+supabase:
+  project:
+    BASE_URL: https://________.supabase.co
+    API_KEY: _____________________________
+
+stripe:
+  API_KEY: sk_____________________________
+
+starshipit:
+  acc:
+    API_KEY: _____________________________
+    SUB_KEY: _____________________________
+    WEBHOOK_SECRET: ______________________
+
+bleckmann:
+  PRIMARY_KEY: ___________________________
+  SECONDARY_KEY: _________________________
+
+stylearcade:
+  BASE_URL: https://api.stylearcade.com/range-plan/v1/tenants/________
+  API_KEY: _______________________________
+
+threeclicks:
+  API_KEY: _______________________________
+  API_SECRET: ____________________________
+  API_DOMAIN: g40-server.instance.3clickscloud.com

package/AGENTS.md

@@ -10,4 +10,9 @@ Notes for AI assistants working in this directory. **Read this file at the start
 - Use snake_case for package.json commands, with colon if appropriate.
 - Use newlines and trailing commas where appropriate to minimise future diffs, e.g. in function args.
 - 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.
+- 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.
+
+## 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.

package/README.md

@@ -56,4 +56,4 @@ For cloud deploy, workspaces use `hosting/.hosting.yml` and `npm run host` (same
 ## What the thang do
 - Server makes functions available from the api/ route, where an export matches the filename. Run `npm run serve`, and they're all curlable.
 - .creds.yml is copied into .env when deploying, so creds can be accessed while hosted. Locally, it reads from the file directly.
-- Cloud deploy reads `hosting/.hosting.yml` for per-function config — `before_wrappers` / `after_wrappers` like `requireHostedApiKey`, `max_instances`, schedules — and deploys each function to Google Cloud.
+- Cloud deploy reads `hosting/.hosting.yml` for per-function config — `before_wrappers` / `after_wrappers` like `requireHostedApiKey`, `max_instances`, schedules — and deploys each function to Google Cloud.

package/api/bleckmann/bleckmann.constants.js

@@ -0,0 +1,8 @@
+// TODO: Split out API version
+const BASE_URL = 'https://apis.bleckmann.com';
+const MAX_PER_PAGE = 1000; // The 'limit' query parameter must be an integer from 1 to 1000
+
+module.exports = {
+  BASE_URL,
+  MAX_PER_PAGE,
+};

package/api/bleckmann/bleckmann.utils.js

@@ -0,0 +1,32 @@
+const { BASE_URL } = require('../bleckmann/bleckmann.constants');
+const { resolveCreds, useBaseUrl } = require('../pipelineSteps');
+const { FetchClient } = require('../utils');
+
+const useAuthHeaders = async (state) => {
+  const { requestPayload, context } = state;
+  const { creds } = context;
+  const { PRIMARY_KEY } = creds;
+
+  return {
+    requestPayload: {
+      ...requestPayload,
+      headers: {
+        'x-api-key': PRIMARY_KEY,
+        ...requestPayload.headers,
+      },
+    },
+  };
+};
+
+const bleckmannClient = new FetchClient({
+  pipeline: [
+    resolveCreds,
+    useAuthHeaders,
+    useBaseUrl(BASE_URL),
+    'fetch',
+  ],
+});
+
+module.exports = {
+  bleckmannClient,
+};

package/api/bleckmann/bleckmannAsnGet.js

@@ -0,0 +1,52 @@
+const { credsValidator } = require('../validators');
+const { ArgsWarden } = require('../utils');
+const { bleckmannClient } = require('../bleckmann/bleckmann.utils');
+
+const argsWarden = new ArgsWarden([
+  ['credsPayload', credsValidator],
+  ['asnId'],
+]);
+
+const bleckmannAsnGet = async (
+  credsPayload,
+  asnId,
+  options = {},
+) => {
+
+  const rejectResponse = await argsWarden.responseIfRejectingArgs({
+    credsPayload,
+    asnId,
+  });
+  if (rejectResponse) {
+    return rejectResponse;
+  }
+
+  const response = await bleckmannClient.fetch({
+    requestPayload: {
+      url: `/warehousing/asns/${ asnId }`,
+    },
+    context: {
+      credsPayload,
+    },
+  });
+
+  return response;
+};
+
+const funcApiConfig = {
+  argsWarden,
+};
+
+module.exports = {
+  bleckmannAsnGet,
+  funcApiConfig,
+};
+
+/*
+curl -X POST "http://localhost:8000/bleckmannAsnGet" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "credsPayload": { "credsPath": "bleckmann" },
+    "asnId": "UK-AG002594"
+  }'
+*/

package/api/bleckmann/bleckmannAsnsGet.js

@@ -0,0 +1,65 @@
+// https://app.swaggerhub.com/apis-docs/Bleckmann/warehousing/1.5.2#/ASN/getAsns
+
+const { credsValidator } = require('../validators');
+const { ArgsWarden } = require('../utils');
+const { MAX_PER_PAGE } = require('../bleckmann/bleckmann.constants');
+const { bleckmannClient } = require('../bleckmann/bleckmann.utils');
+
+const argsWarden = new ArgsWarden([
+  ['credsPayload', credsValidator],
+]);
+
+const bleckmannAsnsGet = async (
+  credsPayload,
+  {
+    createdFrom,
+    createdTo,
+    receivedFrom,
+    receivedTo,
+    status,
+    perPage = MAX_PER_PAGE,
+  } = {},
+) => {
+
+  const rejectResponse = await argsWarden.responseIfRejectingArgs({ credsPayload });
+  if (rejectResponse) {
+    return rejectResponse;
+  }
+
+  const response = await bleckmannClient.fetch({
+    requestPayload: {
+      url: '/warehousing/asns',
+      params: {
+        limit: perPage,
+        ...(createdFrom && { createdFrom }),
+        ...(createdTo && { createdTo }),
+        ...(receivedFrom && { receivedFrom }),
+        ...(receivedTo && { receivedTo }),
+        ...(status && { status }),
+      },
+    },
+    context: {
+      credsPayload,
+    },
+  });
+
+  return response;
+};
+
+const funcApiConfig = {
+  argsWarden,
+};
+
+module.exports = {
+  bleckmannAsnsGet,
+  funcApiConfig,
+};
+
+/*
+curl -X POST "http://localhost:8000/bleckmannAsnsGet" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "credsPayload": { "credsPath": "bleckmann" },
+    "options": { "perPage": 20 }
+  }'
+*/

package/api/constants.js

@@ -1,3 +1,4 @@
 module.exports = {
   HOSTED: !!process.env.HOSTED,
-};
+  TEMP_DIR: `${ __dirname }/../_temp`,
+};

package/api/github/github.constants.js

@@ -0,0 +1,11 @@
+const BASE_URL = 'https://api.github.com';
+const DEFAULT_API_VERSION = '2022-11-28';
+const DEFAULT_USER_AGENT = 'mineral';
+const MAX_PER_PAGE = 100;
+
+module.exports = {
+  BASE_URL,
+  DEFAULT_API_VERSION,
+  DEFAULT_USER_AGENT,
+  MAX_PER_PAGE,
+};

package/api/github/github.utils.js

@@ -0,0 +1,65 @@
+const {
+  BASE_URL,
+  DEFAULT_API_VERSION,
+  DEFAULT_USER_AGENT,
+} = require('../github/github.constants');
+const { resolveCreds } = require('../pipelineSteps');
+const {
+  FetchClient,
+  appendUrlToBase,
+  fetchClientCommonSteps,
+} = require('../utils');
+
+const useGithubUrl = async (state) => {
+  const { requestPayload, context } = state;
+  const { creds } = context;
+  const baseUrl = creds?.BASE_URL ?? BASE_URL;
+
+  return {
+    requestPayload: {
+      ...requestPayload,
+      url: appendUrlToBase(baseUrl, requestPayload.url),
+    },
+  };
+};
+
+const useAuthHeaders = async (state) => {
+  const { requestPayload, context } = state;
+  const { creds } = context;
+  const {
+    ACCESS_TOKEN,
+    GITHUB_TOKEN,
+    API_VERSION,
+    USER_AGENT,
+  } = creds ?? {};
+  const token = ACCESS_TOKEN ?? GITHUB_TOKEN;
+  const apiVersion = API_VERSION ?? context.apiVersion ?? DEFAULT_API_VERSION;
+  const userAgent = USER_AGENT ?? DEFAULT_USER_AGENT;
+
+  return {
+    requestPayload: {
+      ...requestPayload,
+      headers: {
+        Accept: 'application/vnd.github+json',
+        'X-GitHub-Api-Version': apiVersion,
+        Authorization: `Bearer ${ token }`,
+        'User-Agent': userAgent,
+        ...requestPayload.headers,
+      },
+    },
+  };
+};
+
+const githubClient = new FetchClient({
+  pipeline: [
+    resolveCreds,
+    useGithubUrl,
+    useAuthHeaders,
+    'fetch',
+    fetchClientCommonSteps.exitEarlyOnNotOk,
+  ],
+});
+
+module.exports = {
+  githubClient,
+};

package/api/github/githubGet.js

@@ -0,0 +1,144 @@
+// https://docs.github.com/en/rest/using-the-rest-api/getting-started-with-the-rest-api
+
+const { ArgsWarden, Getter } = require('../utils');
+const { credsValidator } = require('../validators');
+const { githubClient } = require('../github/github.utils');
+const { MAX_PER_PAGE } = require('../github/github.constants');
+
+const argsWarden = new ArgsWarden([
+  ['credsPayload', credsValidator],
+  ['url'],
+]);
+
+const githubGetPacket = async (
+  credsPayload,
+  url,
+  {
+    params,
+    perPage = MAX_PER_PAGE,
+  } = {},
+) => {
+  const {
+    page = 1,
+    ...restParams
+  } = params ?? {};
+
+  return githubClient.fetch({
+    requestPayload: {
+      url,
+      params: {
+        per_page: Math.min(perPage, MAX_PER_PAGE),
+        page,
+        ...restParams,
+      },
+    },
+    context: {
+      credsPayload,
+    },
+  });
+};
+
+const githubGetPaginator = async (currentParams, response) => {
+  const { args, options } = currentParams;
+
+  if (!response?.ok) {
+    return [true];
+  }
+
+  const items = Array.isArray(response.data) ? response.data : [];
+  const { perPage = MAX_PER_PAGE, params = {} } = options;
+
+  if (items.length < Math.min(perPage, MAX_PER_PAGE)) {
+    return [true];
+  }
+
+  const { page = 1, ...restParams } = params;
+
+  return [false, {
+    args,
+    options: {
+      ...options,
+      params: {
+        ...restParams,
+        page: page + 1,
+      },
+    },
+  }];
+};
+
+const githubGet = async (
+  returnGetter,
+
+  credsPayload,
+  url,
+  {
+    params,
+    perPage = MAX_PER_PAGE,
+    ...getterOptions
+  } = {},
+) => {
+
+  const rejectResponse = await argsWarden.responseIfRejectingArgs({
+    credsPayload,
+    url,
+  });
+  if (rejectResponse) {
+    return rejectResponse;
+  }
+
+  const getter = new Getter(
+    {
+      args: [credsPayload, url],
+      options: {
+        params,
+        perPage,
+      },
+    },
+    {
+      func: githubGetPacket,
+      digester: (response) => {
+        if (!response?.ok) {
+          return [];
+        }
+
+        return Array.isArray(response.data) ? response.data : [];
+      },
+      paginator: githubGetPaginator,
+      ...getterOptions,
+    },
+  );
+
+  if (returnGetter) {
+    return getter;
+  }
+
+  const data = await getter.run({ returnAll: true });
+
+  return {
+    ok: true,
+    data,
+  };
+};
+
+const funcApiConfig = {
+  argsWarden,
+};
+
+module.exports = {
+  githubGet: (...args) => githubGet(false, ...args),
+  githubGetter: (...args) => githubGet(true, ...args),
+  funcApiConfig,
+};
+
+/*
+curl -X POST "http://localhost:8000/githubGet" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "credsPayload": { "credsPath": "github" },
+    "url": "/user/repos",
+    "options": {
+      "params": { "sort": "updated" },
+      "limit": 10
+    }
+  }'
+*/

package/api/github/githubIssueCreate.js

@@ -0,0 +1,71 @@
+// https://docs.github.com/en/rest/issues/issues#create-an-issue
+
+const { ArgsWarden } = require('../utils');
+const { credsValidator } = require('../validators');
+const { githubClient } = require('../github/github.utils');
+
+const issuePayloadValidator = (issuePayload) => Boolean(issuePayload?.title);
+
+const argsWarden = new ArgsWarden([
+  ['credsPayload', credsValidator],
+  ['owner'],
+  ['repo'],
+  ['issuePayload', issuePayloadValidator],
+]);
+
+const githubIssueCreate = async (
+  credsPayload,
+  owner,
+  repo,
+  issuePayload,
+  {
+    apiVersion,
+  } = {},
+) => {
+
+  const rejectResponse = await argsWarden.responseIfRejectingArgs({
+    credsPayload,
+    owner,
+    repo,
+    issuePayload,
+  });
+  if (rejectResponse) {
+    return rejectResponse;
+  }
+
+  return githubClient.fetch({
+    requestPayload: {
+      method: 'post',
+      url: `/repos/${ owner }/${ repo }/issues`,
+      body: issuePayload,
+    },
+    context: {
+      credsPayload,
+      apiVersion,
+    },
+  });
+};
+
+const funcApiConfig = {
+  argsWarden,
+};
+
+module.exports = {
+  githubIssueCreate,
+  funcApiConfig,
+};
+
+/*
+curl -X POST "http://localhost:8000/githubIssueCreate" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "credsPayload": { "credsPath": "github" },
+    "owner": "GorgonFreeman",
+    "repo": "mineral",
+    "issuePayload": {
+      "title": "Found a bug",
+      "body": "Details here",
+      "labels": ["bug"]
+    }
+  }'
+*/

package/api/github/githubIssueGet.js

@@ -0,0 +1,65 @@
+// https://docs.github.com/en/rest/issues/issues#get-an-issue
+
+const { ArgsWarden } = require('../utils');
+const { credsValidator } = require('../validators');
+const { githubClient } = require('../github/github.utils');
+
+const argsWarden = new ArgsWarden([
+  ['credsPayload', credsValidator],
+  ['owner'],
+  ['repo'],
+  ['issueNumber'],
+]);
+
+const githubIssueGet = async (
+  credsPayload,
+  owner,
+  repo,
+  issueNumber,
+  {
+    params,
+    apiVersion,
+  } = {},
+) => {
+
+  const rejectResponse = await argsWarden.responseIfRejectingArgs({
+    credsPayload,
+    owner,
+    repo,
+    issueNumber,
+  });
+  if (rejectResponse) {
+    return rejectResponse;
+  }
+
+  return githubClient.fetch({
+    requestPayload: {
+      url: `/repos/${ owner }/${ repo }/issues/${ issueNumber }`,
+      params,
+    },
+    context: {
+      credsPayload,
+      apiVersion,
+    },
+  });
+};
+
+const funcApiConfig = {
+  argsWarden,
+};
+
+module.exports = {
+  githubIssueGet,
+  funcApiConfig,
+};
+
+/*
+curl -X POST "http://localhost:8000/githubIssueGet" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "credsPayload": { "credsPath": "github" },
+    "owner": "GorgonFreeman",
+    "repo": "mineral",
+    "issueNumber": 1
+  }'
+*/

package/api/github/githubIssueUpdate.js

@@ -0,0 +1,71 @@
+// https://docs.github.com/en/rest/issues/issues#update-an-issue
+
+const { ArgsWarden } = require('../utils');
+const { credsValidator } = require('../validators');
+const { githubClient } = require('../github/github.utils');
+
+const argsWarden = new ArgsWarden([
+  ['credsPayload', credsValidator],
+  ['owner'],
+  ['repo'],
+  ['issueNumber'],
+  ['updatePayload', Boolean],
+]);
+
+const githubIssueUpdate = async (
+  credsPayload,
+  owner,
+  repo,
+  issueNumber,
+  updatePayload,
+  {
+    apiVersion,
+  } = {},
+) => {
+
+  const rejectResponse = await argsWarden.responseIfRejectingArgs({
+    credsPayload,
+    owner,
+    repo,
+    issueNumber,
+    updatePayload,
+  });
+  if (rejectResponse) {
+    return rejectResponse;
+  }
+
+  return githubClient.fetch({
+    requestPayload: {
+      method: 'patch',
+      url: `/repos/${ owner }/${ repo }/issues/${ issueNumber }`,
+      body: updatePayload,
+    },
+    context: {
+      credsPayload,
+      apiVersion,
+    },
+  });
+};
+
+const funcApiConfig = {
+  argsWarden,
+};
+
+module.exports = {
+  githubIssueUpdate,
+  funcApiConfig,
+};
+
+/*
+curl -X POST "http://localhost:8000/githubIssueUpdate" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "credsPayload": { "credsPath": "github" },
+    "owner": "GorgonFreeman",
+    "repo": "mineral",
+    "issueNumber": 1,
+    "updatePayload": {
+      "state": "closed"
+    }
+  }'
+*/