@foxtware/mineral 0.1.17 → 0.1.18

package/.creds.yml.sample

@@ -78,27 +78,36 @@ etsy:
   SHARED_SECRET: _________________________
 
 clickup:
-  API_KEY: pk________________________________
+  API_KEY: pk_____________________________
 
 asana:
   ACCESS_TOKEN: __________________________
 
 notion:
-  API_KEY: secret________________________________
+  API_KEY: secret_________________________
 
 discord:
-  BOT_TOKEN: ______________________________
+  BOT_TOKEN: _____________________________
 
 telnyx:
-  API_KEY: KEY__________________________________
+  API_KEY: KEY____________________________
 
 figma:
-  API_KEY: figd________________________________
+  API_KEY: figd___________________________
 
 pipe17:
-  API_KEY: ____________________________________
+  API_KEY: _______________________________
   sandbox:
-    API_KEY: ____________________________________
+    API_KEY: _____________________________
+
+backblaze:
+  APP_ID: ________________________________
+  API_KEY: _______________________________
+
+gorgias:
+  DOMAIN: ________________________________
+  EMAIL: _________________________________
+  API_KEY: _______________________________
 
 google:
   SERVICE_ACCOUNT_JSON:

package/AGENTS.md

@@ -17,6 +17,9 @@ Notes for AI assistants working in this directory. **Read this file at the start
 - 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.
+- docs.md in each platform should not describe the details of our implementation, handlers or anything relating to Mineral. It is for describing the platform's API itself and does not change based on what we do with it. It should also be brief.
+- Usually when making a function that gets multiples of a resource, it should be implemented as a Getter, with a paginator and digester. If done in this way, export platformThingGet and platformThingGetter, using the .bind() syntax seen in other Get functions.
+- When making functions that act on single resources, consider using actionSingleOrMultiple to allow a queue of actions.
 
 ## 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/publish.js

@@ -53,7 +53,21 @@ const ensureLoggedIn = () => {
       stdio: 'pipe',
     });
   } catch {
-    throw new Error('Not logged in to npm. Run `npm login` with an account that can publish @foxtware/mineral.');
+    console.log('Not logged in to npm. Running `npm login`…');
+    execSync('npm login', {
+      cwd: mineralRoot,
+      stdio: 'inherit',
+    });
+
+    try {
+      execSync('npm whoami', {
+        cwd: mineralRoot,
+        encoding: 'utf8',
+        stdio: 'pipe',
+      });
+    } catch {
+      throw new Error('Still not logged in to npm. Use an account that can publish @foxtware/mineral.');
+    }
   }
 };
 

package/api/backblaze/backblaze.constants.js

@@ -0,0 +1,11 @@
+const BASE_URL = 'https://api.backblazeb2.com';
+
+const B2_API_VERSION_PATH = '/b2api/v2';
+
+const MAX_FILES_PER_PAGE = 1000;
+
+module.exports = {
+  BASE_URL,
+  B2_API_VERSION_PATH,
+  MAX_FILES_PER_PAGE,
+};

package/api/backblaze/backblaze.utils.js

@@ -0,0 +1,322 @@
+const crypto = require('crypto');
+
+const { BASE_URL, B2_API_VERSION_PATH } = require('../backblaze/backblaze.constants');
+const { resolveCreds } = require('../pipelineSteps');
+const {
+  appendUrlToBase,
+  credsFromPayload,
+  customFetch,
+  FetchClient,
+  fetchClientCommonSteps,
+  objHasAny,
+} = require('../utils');
+
+const bucketIdentifierValidator = (bucketIdentifier) => {
+  return objHasAny(bucketIdentifier, [
+    'bucketId',
+    'bucketName',
+  ]);
+};
+
+const sessionCacheKeyForCredsPayload = (credsPayload) => {
+  if (credsPayload?.credsPath) {
+    return credsPayload.credsPath;
+  }
+
+  return JSON.stringify(credsPayload);
+};
+
+const backblazeSessionsByKey = new Map();
+
+const getBackblazeSession = async (credsPayload) => {
+  const cacheKey = sessionCacheKeyForCredsPayload(credsPayload);
+
+  if (backblazeSessionsByKey.has(cacheKey)) {
+    return {
+      ok: true,
+      data: backblazeSessionsByKey.get(cacheKey),
+    };
+  }
+
+  const creds = await credsFromPayload(credsPayload);
+  const { APP_ID, API_KEY } = creds ?? {};
+
+  if (!APP_ID || !API_KEY) {
+    return {
+      ok: false,
+      error: {
+        code: 'MISSING_BACKBLAZE_CREDS',
+        message: 'backblaze creds require APP_ID and API_KEY',
+      },
+    };
+  }
+
+  const basicToken = Buffer
+    .from(`${ APP_ID }:${ API_KEY }`)
+    .toString('base64');
+
+  const authorizeResponse = await customFetch(
+    `${ BASE_URL }${ B2_API_VERSION_PATH }/b2_authorize_account`,
+    {
+      method: 'get',
+      headers: {
+        Authorization: `Basic ${ basicToken }`,
+      },
+    },
+  );
+
+  if (!authorizeResponse.ok) {
+    return authorizeResponse;
+  }
+
+  const {
+    accountId,
+    authorizationToken,
+    apiUrl,
+    downloadUrl,
+  } = authorizeResponse.data ?? {};
+
+  if (!accountId || !authorizationToken || !apiUrl) {
+    return {
+      ok: false,
+      error: {
+        code: 'INVALID_AUTHORIZE_RESPONSE',
+        message: 'b2_authorize_account response missing accountId, authorizationToken, or apiUrl',
+      },
+    };
+  }
+
+  const session = {
+    accountId,
+    authorizationToken,
+    apiUrl,
+    downloadUrl,
+  };
+
+  backblazeSessionsByKey.set(cacheKey, session);
+
+  return {
+    ok: true,
+    data: session,
+  };
+};
+
+const attachBackblazeSession = async (state) => {
+  const { context } = state;
+  const { credsPayload, session } = context;
+
+  if (session) {
+    return {};
+  }
+
+  const sessionResponse = await getBackblazeSession(credsPayload);
+
+  if (!sessionResponse.ok) {
+    return {
+      breakChain: true,
+      response: sessionResponse,
+    };
+  }
+
+  return {
+    context: {
+      ...context,
+      session: sessionResponse.data,
+    },
+  };
+};
+
+const useBackblazeApiUrl = async (state) => {
+  const { requestPayload, context } = state;
+  const { session } = context;
+
+  return {
+    requestPayload: {
+      ...requestPayload,
+      url: appendUrlToBase(session.apiUrl, requestPayload.url),
+    },
+  };
+};
+
+const useBackblazeAuthorizationHeader = async (state) => {
+  const { requestPayload, context } = state;
+  const { session } = context;
+
+  return {
+    requestPayload: {
+      ...requestPayload,
+      headers: {
+        Authorization: session.authorizationToken,
+        ...requestPayload.headers,
+      },
+    },
+  };
+};
+
+const backblazeClient = new FetchClient({
+  pipeline: [
+    resolveCreds,
+    attachBackblazeSession,
+    useBackblazeAuthorizationHeader,
+    useBackblazeApiUrl,
+    'fetch',
+    fetchClientCommonSteps.exitEarlyOnNotOk,
+    fetchClientCommonSteps.digToPath,
+  ],
+});
+
+const publicFileUrlForBucketName = ({
+  downloadUrl,
+  bucketName,
+  fileName,
+}) => {
+  if (!downloadUrl || !bucketName || !fileName) {
+    return null;
+  }
+
+  const encodedFileName = encodeURIComponent(fileName)
+    .replace(/%2F/g, '/');
+
+  return `${ downloadUrl }/file/${ bucketName }/${ encodedFileName }`;
+};
+
+const sha1HexForBuffer = (buffer) => {
+  return crypto
+    .createHash('sha1')
+    .update(buffer)
+    .digest('hex');
+};
+
+const backblazeUploadFileBytes = async ({
+  credsPayload,
+  session,
+  bucketId,
+  fileName,
+  fileBytes,
+  contentType = 'b2/x-auto',
+}) => {
+  let resolvedSession = session;
+
+  if (!resolvedSession) {
+    const sessionResponse = await getBackblazeSession(credsPayload);
+
+    if (!sessionResponse.ok) {
+      return sessionResponse;
+    }
+
+    ({ data: resolvedSession } = sessionResponse);
+  }
+
+  const uploadUrlResponse = await backblazeClient.fetch({
+    requestPayload: {
+      method: 'post',
+      url: `${ B2_API_VERSION_PATH }/b2_get_upload_url`,
+      body: { bucketId },
+    },
+    context: {
+      credsPayload,
+      session: resolvedSession,
+    },
+  });
+
+  if (!uploadUrlResponse.ok) {
+    return uploadUrlResponse;
+  }
+
+  const {
+    uploadUrl,
+    authorizationToken: uploadAuthorizationToken,
+  } = uploadUrlResponse.data ?? {};
+
+  if (!uploadUrl || !uploadAuthorizationToken) {
+    return {
+      ok: false,
+      error: {
+        code: 'INVALID_UPLOAD_URL_RESPONSE',
+        message: 'b2_get_upload_url response missing uploadUrl or authorizationToken',
+      },
+    };
+  }
+
+  const contentSha1 = sha1HexForBuffer(fileBytes);
+
+  return customFetch(uploadUrl, {
+    method: 'post',
+    headers: {
+      Authorization: uploadAuthorizationToken,
+      'X-Bz-File-Name': encodeURIComponent(fileName),
+      'X-Bz-Content-Sha1': contentSha1,
+      'Content-Type': contentType,
+    },
+    body: fileBytes,
+  });
+};
+
+const resolveBucketIdFromIdentifier = async (
+  credsPayload,
+  bucketIdentifier,
+  {
+    fetchClient,
+  } = {},
+) => {
+  const {
+    bucketId,
+    bucketName,
+  } = bucketIdentifier;
+
+  if (bucketId) {
+    return {
+      ok: true,
+      data: bucketId,
+    };
+  }
+
+  if (!bucketName) {
+    return {
+      ok: false,
+      error: {
+        code: 'BUCKET_NOT_FOUND',
+        message: 'Provide bucketId or bucketName',
+      },
+    };
+  }
+
+  const { backblazeBucketsGet } = require('../backblaze/backblazeBucketsGet');
+
+  const bucketsResponse = await backblazeBucketsGet(credsPayload, {
+    bucketName,
+    fetchClient,
+  });
+
+  if (!bucketsResponse.ok) {
+    return bucketsResponse;
+  }
+
+  const bucket = bucketsResponse.data?.find(
+    (candidate) => candidate.bucketName === bucketName,
+  );
+
+  if (!bucket?.bucketId) {
+    return {
+      ok: false,
+      error: {
+        code: 'BUCKET_NOT_FOUND',
+        message: `Bucket ${ bucketName } not found`,
+      },
+    };
+  }
+
+  return {
+    ok: true,
+    data: bucket.bucketId,
+  };
+};
+
+module.exports = {
+  backblazeClient,
+  bucketIdentifierValidator,
+  getBackblazeSession,
+  publicFileUrlForBucketName,
+  backblazeUploadFileBytes,
+  resolveBucketIdFromIdentifier,
+};

package/api/backblaze/backblazeBucketsGet.js

@@ -0,0 +1,68 @@
+// https://www.backblaze.com/apidocs/b2-list-buckets
+
+const { ArgsWarden } = require('../utils');
+const { credsValidator } = require('../validators');
+const { B2_API_VERSION_PATH } = require('../backblaze/backblaze.constants');
+const { backblazeClient, getBackblazeSession } = require('../backblaze/backblaze.utils');
+
+const argsWarden = new ArgsWarden([
+  ['credsPayload', credsValidator],
+]);
+
+const backblazeBucketsGet = async (
+  credsPayload,
+  {
+    bucketName,
+    fetchClient = backblazeClient,
+  } = {},
+) => {
+
+  const rejectResponse = await argsWarden.responseIfRejectingArgs({
+    credsPayload,
+  });
+  if (rejectResponse) {
+    return rejectResponse;
+  }
+
+  const sessionResponse = await getBackblazeSession(credsPayload);
+
+  if (!sessionResponse.ok) {
+    return sessionResponse;
+  }
+
+  const { data: session } = sessionResponse;
+  const { accountId } = session;
+
+  return fetchClient.fetch({
+    requestPayload: {
+      method: 'post',
+      url: `${ B2_API_VERSION_PATH }/b2_list_buckets`,
+      body: {
+        accountId,
+        ...bucketName && { bucketName },
+      },
+    },
+    context: {
+      credsPayload,
+      session,
+      resultPath: 'buckets',
+    },
+  });
+};
+
+const funcApiConfig = {
+  argsWarden,
+};
+
+module.exports = {
+  backblazeBucketsGet,
+  funcApiConfig,
+};
+
+/*
+curl -X POST "http://localhost:8000/backblazeBucketsGet" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "credsPayload": { "credsPath": "backblaze" }
+  }'
+*/

package/api/backblaze/backblazeFileDelete.js

@@ -0,0 +1,62 @@
+// https://www.backblaze.com/apidocs/b2-delete-file-version
+
+const { ArgsWarden } = require('../utils');
+const { credsValidator } = require('../validators');
+const { B2_API_VERSION_PATH } = require('../backblaze/backblaze.constants');
+const { backblazeClient } = require('../backblaze/backblaze.utils');
+
+const argsWarden = new ArgsWarden([
+  ['credsPayload', credsValidator],
+  ['fileName'],
+  ['fileId'],
+]);
+
+const backblazeFileDelete = async (
+  credsPayload,
+  fileName,
+  fileId,
+  {
+    fetchClient = backblazeClient,
+  } = {},
+) => {
+
+  const rejectResponse = await argsWarden.responseIfRejectingArgs({
+    credsPayload,
+    fileName,
+    fileId,
+  });
+  if (rejectResponse) {
+    return rejectResponse;
+  }
+
+  return fetchClient.fetch({
+    requestPayload: {
+      method: 'post',
+      url: `${ B2_API_VERSION_PATH }/b2_delete_file_version`,
+      body: {
+        fileName,
+        fileId,
+      },
+    },
+    context: { credsPayload },
+  });
+};
+
+const funcApiConfig = {
+  argsWarden,
+};
+
+module.exports = {
+  backblazeFileDelete,
+  funcApiConfig,
+};
+
+/*
+curl -X POST "http://localhost:8000/backblazeFileDelete" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "credsPayload": { "credsPath": "backblaze" },
+    "fileName": "hello.txt",
+    "fileId": "REPLACE_FILE_ID"
+  }'
+*/

package/api/backblaze/backblazeFileHide.js

@@ -0,0 +1,62 @@
+// https://www.backblaze.com/apidocs/b2-hide-file
+
+const { ArgsWarden } = require('../utils');
+const { credsValidator } = require('../validators');
+const { B2_API_VERSION_PATH } = require('../backblaze/backblaze.constants');
+const { backblazeClient } = require('../backblaze/backblaze.utils');
+
+const argsWarden = new ArgsWarden([
+  ['credsPayload', credsValidator],
+  ['fileName'],
+  ['fileId'],
+]);
+
+const backblazeFileHide = async (
+  credsPayload,
+  fileName,
+  fileId,
+  {
+    fetchClient = backblazeClient,
+  } = {},
+) => {
+
+  const rejectResponse = await argsWarden.responseIfRejectingArgs({
+    credsPayload,
+    fileName,
+    fileId,
+  });
+  if (rejectResponse) {
+    return rejectResponse;
+  }
+
+  return fetchClient.fetch({
+    requestPayload: {
+      method: 'post',
+      url: `${ B2_API_VERSION_PATH }/b2_hide_file`,
+      body: {
+        fileName,
+        fileId,
+      },
+    },
+    context: { credsPayload },
+  });
+};
+
+const funcApiConfig = {
+  argsWarden,
+};
+
+module.exports = {
+  backblazeFileHide,
+  funcApiConfig,
+};
+
+/*
+curl -X POST "http://localhost:8000/backblazeFileHide" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "credsPayload": { "credsPath": "backblaze" },
+    "fileName": "hello.txt",
+    "fileId": "REPLACE_FILE_ID"
+  }'
+*/