@foxtware/mineral 0.1.28 → 0.1.30

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"
+  }'
+*/

package/api/dropbox/dropboxFileMove.js

@@ -0,0 +1,67 @@
+// https://www.dropbox.com/developers/documentation/http/documentation#files-move_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 dropboxFileMove = 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/move_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 = {
+  dropboxFileMove,
+  funcApiConfig,
+};

package/api/dropbox/dropboxFileUpload.js

@@ -0,0 +1,129 @@
+// https://www.dropbox.com/developers/documentation/http/documentation#files-upload
+// Max 150 MB for a single /files/upload call. Larger files need upload sessions.
+
+const fs = require('fs').promises;
+const pathModule = require('path');
+
+const { ArgsWarden, valueProvided, logDeep } = require('../utils');
+const { credsValidator } = require('../validators');
+const { dropboxContentClient } = require('../dropbox/dropbox.utils');
+
+const fileDataValidator = (fileData) => {
+  if (!fileData || typeof fileData !== 'object') {
+    return false;
+  }
+  const { filePath, fileSource, contents } = fileData;
+  return valueProvided(filePath)
+    || valueProvided(fileSource)
+    || valueProvided(contents);
+};
+
+const argsWarden = new ArgsWarden([
+  ['credsPayload', credsValidator],
+  ['path'],
+  ['fileData', fileDataValidator],
+]);
+
+const dropboxFileUpload = async (
+  credsPayload,
+  path,
+  fileData,
+  {
+    mode = 'add', // 'add' | 'overwrite' | { '.tag': 'update', update: rev }
+    autorename = false,
+    mute = false,
+    strictConflict = false,
+    clientModified,
+    fetchClient = dropboxContentClient,
+  } = {},
+) => {
+  const rejectResponse = await argsWarden.responseIfRejectingArgs({
+    credsPayload,
+    path,
+    fileData,
+  });
+  if (rejectResponse) {
+    return rejectResponse;
+  }
+
+  let body;
+  if (valueProvided(fileData.filePath)) {
+    body = await fs.readFile(fileData.filePath);
+  } else if (valueProvided(fileData.fileSource)) {
+    body = Buffer.isBuffer(fileData.fileSource)
+      ? fileData.fileSource
+      : Buffer.from(fileData.fileSource, fileData.encoding || 'utf8');
+  } else if (valueProvided(fileData.contents)) {
+    body = Buffer.isBuffer(fileData.contents)
+      ? fileData.contents
+      : Buffer.from(fileData.contents, fileData.encoding || 'utf8');
+  }
+
+  if (!body) {
+    return {
+      ok: false,
+      error: {
+        code: 'INVALID_FILE_DATA',
+        message: 'Provide filePath, fileSource, or contents',
+      },
+    };
+  }
+
+  // If path ends with / or is empty folder style, append basename from filePath.
+  let uploadPath = path;
+  if (fileData.filePath && (path.endsWith('/') || path === '')) {
+    uploadPath = `${ path.replace(/\/$/, '') }/${ pathModule.basename(fileData.filePath) }`;
+  }
+
+  const arg = {
+    path: uploadPath,
+    mode,
+    autorename,
+    mute,
+    strict_conflict: strictConflict,
+    ...(clientModified !== undefined && { client_modified: clientModified }),
+  };
+
+  const response = await fetchClient.fetch({
+    context: { credsPayload },
+    requestPayload: {
+      method: 'post',
+      url: '/files/upload',
+      headers: {
+        'Dropbox-API-Arg': JSON.stringify(arg),
+        'Content-Type': 'application/octet-stream',
+      },
+      body,
+    },
+  });
+
+  const { ok, data, error } = response;
+  if (!ok) {
+    logDeep({ error });
+    return { ok: false, error };
+  }
+
+  return {
+    ok: true,
+    data,
+  };
+};
+
+const funcApiConfig = {
+  argsWarden,
+};
+
+module.exports = {
+  dropboxFileUpload,
+  funcApiConfig,
+};
+
+/*
+curl -X POST "http://localhost:8000/dropboxFileUpload" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "credsPayload": { "credsPath": "dropbox" },
+    "path": "/Homework/math/hello.txt",
+    "fileData": { "contents": "hello world" }
+  }'
+*/

package/api/dropbox/dropboxFolderCreate.js

@@ -0,0 +1,68 @@
+// https://www.dropbox.com/developers/documentation/http/documentation#files-create_folder_v2
+
+const { ArgsWarden, logDeep } = require('../utils');
+const { credsValidator } = require('../validators');
+const { dropboxClient } = require('../dropbox/dropbox.utils');
+
+const argsWarden = new ArgsWarden([
+  ['credsPayload', credsValidator],
+  ['path'],
+]);
+
+const dropboxFolderCreate = async (
+  credsPayload,
+  path,
+  {
+    autorename = false,
+    fetchClient = dropboxClient,
+  } = {},
+) => {
+  const rejectResponse = await argsWarden.responseIfRejectingArgs({
+    credsPayload,
+    path,
+  });
+  if (rejectResponse) {
+    return rejectResponse;
+  }
+
+  const response = await fetchClient.fetch({
+    context: { credsPayload },
+    requestPayload: {
+      method: 'post',
+      url: '/files/create_folder_v2',
+      body: {
+        path,
+        autorename,
+      },
+    },
+  });
+
+  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 = {
+  dropboxFolderCreate,
+  funcApiConfig,
+};
+
+/*
+curl -X POST "http://localhost:8000/dropboxFolderCreate" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "credsPayload": { "credsPath": "dropbox" },
+    "path": "/Homework/math"
+  }'
+*/

package/api/dropbox/dropboxFolderList.js

@@ -0,0 +1,66 @@
+// https://www.dropbox.com/developers/documentation/http/documentation#files-list_folder
+
+const { ArgsWarden } = require('../utils');
+const { credsValidator } = require('../validators');
+const { dropboxGet } = require('../dropbox/dropboxGet');
+const { MAX_PER_PAGE } = require('../dropbox/dropbox.constants');
+
+const argsWarden = new ArgsWarden([
+  ['credsPayload', credsValidator],
+]);
+
+// path: "" for root. recursive walks the whole subtree.
+const dropboxFolderList = async (
+  credsPayload,
+  {
+    path = '',
+    recursive = false,
+    includeDeleted = false,
+    includeMediaInfo = false,
+    includeMountedFolders = true,
+    includeNonDownloadableFiles = true,
+    perPage = MAX_PER_PAGE,
+    fetchClient,
+    ...getterOptions
+  } = {},
+) => {
+  const rejectResponse = await argsWarden.responseIfRejectingArgs({
+    credsPayload,
+  });
+  if (rejectResponse) {
+    return rejectResponse;
+  }
+
+  return dropboxGet(credsPayload, '/files/list_folder', {
+    body: {
+      path,
+      recursive,
+      include_deleted: includeDeleted,
+      include_media_info: includeMediaInfo,
+      include_mounted_folders: includeMountedFolders,
+      include_non_downloadable_files: includeNonDownloadableFiles,
+    },
+    perPage,
+    resultsKey: 'entries',
+    fetchClient,
+    ...getterOptions,
+  });
+};
+
+const funcApiConfig = {
+  argsWarden,
+};
+
+module.exports = {
+  dropboxFolderList,
+  funcApiConfig,
+};
+
+/*
+curl -X POST "http://localhost:8000/dropboxFolderList" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "credsPayload": { "credsPath": "dropbox" },
+    "options": { "path": "/Homework" }
+  }'
+*/