@foxtware/mineral 0.1.28 → 0.1.30

package/api/dropbox/dropboxGet.js

@@ -0,0 +1,158 @@
+// https://www.dropbox.com/developers/documentation/http/documentation#files-list_folder
+
+const { ArgsWarden, Getter } = require('../utils');
+const { credsValidator } = require('../validators');
+const { dropboxClient } = require('../dropbox/dropbox.utils');
+const { MAX_PER_PAGE } = require('../dropbox/dropbox.constants');
+
+const argsWarden = new ArgsWarden([
+  ['credsPayload', credsValidator],
+  ['url'],
+]);
+
+const dropboxGetPacket = async (
+  credsPayload,
+  url,
+  {
+    body = {},
+    perPage = MAX_PER_PAGE,
+    fetchClient = dropboxClient,
+  } = {},
+) => {
+  // When continuing, Dropbox wants only { cursor } on list_folder/continue.
+  const isContinue = url.includes('/continue') || body.cursor;
+
+  const requestBody = isContinue
+    ? { cursor: body.cursor }
+    : {
+        ...body,
+        ...(body.limit === undefined && {
+          limit: Math.min(perPage, MAX_PER_PAGE),
+        }),
+      };
+
+  return fetchClient.fetch({
+    requestPayload: {
+      method: 'post',
+      url,
+      body: requestBody,
+    },
+    context: {
+      credsPayload,
+    },
+  });
+};
+
+const dropboxGetPaginator = async (currentParams, response) => {
+  if (!response?.ok) {
+    return [true];
+  }
+
+  const { has_more: hasMore, cursor } = response.data ?? {};
+  if (!hasMore || !cursor) {
+    return [true];
+  }
+
+  const { args, options } = currentParams;
+  const [, initialUrl] = args;
+
+  // Switch to the matching continue endpoint when still on the initial path.
+  let continueUrl = initialUrl;
+  if (!continueUrl.includes('/continue')) {
+    continueUrl = `${ initialUrl.replace(/\/$/, '') }/continue`;
+  }
+
+  return [false, {
+    args: [args[0], continueUrl],
+    options: {
+      ...options,
+      body: {
+        cursor,
+      },
+    },
+  }];
+};
+
+const dropboxGet = async (
+  returnGetter,
+
+  credsPayload,
+  url,
+  {
+    body,
+    perPage = MAX_PER_PAGE,
+    resultsKey = 'entries',
+    fetchClient,
+    ...getterOptions
+  } = {},
+) => {
+
+  const rejectResponse = await argsWarden.responseIfRejectingArgs({
+    credsPayload,
+    url,
+  });
+  if (rejectResponse) {
+    return rejectResponse;
+  }
+
+  const getter = new Getter(
+    {
+      args: [credsPayload, url],
+      options: {
+        body,
+        perPage,
+        fetchClient,
+      },
+    },
+    {
+      func: dropboxGetPacket,
+      digester: (response) => {
+        if (!response?.ok) {
+          return [];
+        }
+
+        if (resultsKey) {
+          return response.data?.[resultsKey] ?? [];
+        }
+
+        return response.data ?? [];
+      },
+      paginator: dropboxGetPaginator,
+      ...getterOptions,
+    },
+  );
+
+  if (returnGetter) {
+    return getter;
+  }
+
+  const data = await getter.run({ returnAll: true });
+
+  return {
+    ok: true,
+    data,
+  };
+};
+
+const funcApiConfig = {
+  argsWarden,
+};
+
+module.exports = {
+  dropboxGet: (...args) => dropboxGet(false, ...args),
+  dropboxGetter: (...args) => dropboxGet(true, ...args),
+  funcApiConfig,
+};
+
+/*
+curl -X POST "http://localhost:8000/dropboxGet" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "credsPayload": { "credsPath": "dropbox" },
+    "url": "/files/list_folder",
+    "options": {
+      "body": { "path": "" },
+      "perPage": 100
+    }
+  }'
+*/

package/api/dropbox/dropboxSearch.js

@@ -0,0 +1,161 @@
+// https://www.dropbox.com/developers/documentation/http/documentation#files-search_v2
+
+const { ArgsWarden, Getter, logDeep } = require('../utils');
+const { credsValidator } = require('../validators');
+const { dropboxClient } = require('../dropbox/dropbox.utils');
+const { MAX_PER_PAGE } = require('../dropbox/dropbox.constants');
+
+const argsWarden = new ArgsWarden([
+  ['credsPayload', credsValidator],
+  ['query'],
+]);
+
+const dropboxSearchPacket = async (
+  credsPayload,
+  query,
+  {
+    body = {},
+    perPage = 100,
+    fetchClient = dropboxClient,
+  } = {},
+) => {
+  if (body.cursor) {
+    return fetchClient.fetch({
+      context: { credsPayload },
+      requestPayload: {
+        method: 'post',
+        url: '/files/search/continue_v2',
+        body: { cursor: body.cursor },
+      },
+    });
+  }
+
+  return fetchClient.fetch({
+    context: { credsPayload },
+    requestPayload: {
+      method: 'post',
+      url: '/files/search_v2',
+      body: {
+        query,
+        options: {
+          max_results: Math.min(perPage, MAX_PER_PAGE),
+          ...(body.options || {}),
+        },
+        ...(body.match_field_options && {
+          match_field_options: body.match_field_options,
+        }),
+      },
+    },
+  });
+};
+
+const dropboxSearchPaginator = async (currentParams, response) => {
+  if (!response?.ok) {
+    return [true];
+  }
+
+  const { has_more: hasMore, cursor } = response.data ?? {};
+  if (!hasMore || !cursor) {
+    return [true];
+  }
+
+  const { args, options } = currentParams;
+
+  return [false, {
+    args,
+    options: {
+      ...options,
+      body: {
+        cursor,
+      },
+    },
+  }];
+};
+
+const dropboxSearch = async (
+  returnGetter,
+
+  credsPayload,
+  query,
+  {
+    path,
+    fileStatus,
+    filenameOnly,
+    maxResults,
+    fileCategories,
+    accountId,
+    perPage = 100,
+    fetchClient,
+    ...getterOptions
+  } = {},
+) => {
+  const rejectResponse = await argsWarden.responseIfRejectingArgs({
+    credsPayload,
+    query,
+  });
+  if (rejectResponse) {
+    return rejectResponse;
+  }
+
+  const options = {
+    ...(path !== undefined && { path }),
+    ...(fileStatus !== undefined && { file_status: fileStatus }),
+    ...(filenameOnly !== undefined && { filename_only: filenameOnly }),
+    ...(maxResults !== undefined && { max_results: maxResults }),
+    ...(fileCategories !== undefined && { file_categories: fileCategories }),
+    ...(accountId !== undefined && { account_id: accountId }),
+  };
+
+  const getter = new Getter(
+    {
+      args: [credsPayload, query],
+      options: {
+        body: { options },
+        perPage: maxResults ?? perPage,
+        fetchClient,
+      },
+    },
+    {
+      func: dropboxSearchPacket,
+      digester: (response) => {
+        if (!response?.ok) {
+          return [];
+        }
+        return response.data?.matches ?? [];
+      },
+      paginator: dropboxSearchPaginator,
+      ...getterOptions,
+    },
+  );
+
+  if (returnGetter) {
+    return getter;
+  }
+
+  const data = await getter.run({ returnAll: true });
+
+  return {
+    ok: true,
+    data,
+  };
+};
+
+const funcApiConfig = {
+  argsWarden,
+};
+
+module.exports = {
+  dropboxSearch: (...args) => dropboxSearch(false, ...args),
+  dropboxSearchGetter: (...args) => dropboxSearch(true, ...args),
+  funcApiConfig,
+};
+
+/*
+curl -X POST "http://localhost:8000/dropboxSearch" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "credsPayload": { "credsPath": "dropbox" },
+    "query": "prime",
+    "options": { "path": "/Homework" }
+  }'
+*/

package/api/dropbox/dropboxSharedLinkCreate.js

@@ -0,0 +1,68 @@
+// https://www.dropbox.com/developers/documentation/http/documentation#sharing-create_shared_link_with_settings
+
+const { ArgsWarden, logDeep } = require('../utils');
+const { credsValidator } = require('../validators');
+const { dropboxClient } = require('../dropbox/dropbox.utils');
+
+const argsWarden = new ArgsWarden([
+  ['credsPayload', credsValidator],
+  ['path'],
+]);
+
+const dropboxSharedLinkCreate = async (
+  credsPayload,
+  path,
+  {
+    settings,
+    fetchClient = dropboxClient,
+  } = {},
+) => {
+  const rejectResponse = await argsWarden.responseIfRejectingArgs({
+    credsPayload,
+    path,
+  });
+  if (rejectResponse) {
+    return rejectResponse;
+  }
+
+  const response = await fetchClient.fetch({
+    context: { credsPayload },
+    requestPayload: {
+      method: 'post',
+      url: '/sharing/create_shared_link_with_settings',
+      body: {
+        path,
+        ...(settings !== undefined && { settings }),
+      },
+    },
+  });
+
+  const { ok, data, error } = response;
+  if (!ok) {
+    logDeep({ error });
+    return { ok: false, error };
+  }
+
+  return {
+    ok: true,
+    data,
+  };
+};
+
+const funcApiConfig = {
+  argsWarden,
+};
+
+module.exports = {
+  dropboxSharedLinkCreate,
+  funcApiConfig,
+};
+
+/*
+curl -X POST "http://localhost:8000/dropboxSharedLinkCreate" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "credsPayload": { "credsPath": "dropbox" },
+    "path": "/Homework/math/Prime_Numbers.txt"
+  }'
+*/

package/api/dropbox/dropboxSpaceUsageGet.js

@@ -0,0 +1,55 @@
+// https://www.dropbox.com/developers/documentation/http/documentation#users-get_space_usage
+
+const { ArgsWarden, logDeep } = require('../utils');
+const { credsValidator } = require('../validators');
+const { dropboxClient } = require('../dropbox/dropbox.utils');
+
+const argsWarden = new ArgsWarden([
+  ['credsPayload', credsValidator],
+]);
+
+const dropboxSpaceUsageGet = 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_space_usage',
+      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 = {
+  dropboxSpaceUsageGet,
+  funcApiConfig,
+};

package/api/dropbox/dropboxTemporaryLinkGet.js

@@ -0,0 +1,75 @@
+// https://www.dropbox.com/developers/documentation/http/documentation#files-get_temporary_link
+
+const { ArgsWarden, actionSingleOrMultiple, logDeep } = require('../utils');
+const { credsValidator } = require('../validators');
+const { dropboxClient } = require('../dropbox/dropbox.utils');
+
+const argsWarden = new ArgsWarden([
+  ['credsPayload', credsValidator],
+  ['path'],
+]);
+
+const dropboxTemporaryLinkGetSingle = async (
+  credsPayload,
+  path,
+  {
+    fetchClient = dropboxClient,
+  } = {},
+) => {
+  const response = await fetchClient.fetch({
+    context: { credsPayload },
+    requestPayload: {
+      method: 'post',
+      url: '/files/get_temporary_link',
+      body: { path },
+    },
+  });
+
+  const { ok, data, error } = response;
+  if (!ok) {
+    logDeep({ error });
+    return { ok: false, error };
+  }
+
+  return {
+    ok: true,
+    data,
+  };
+};
+
+const dropboxTemporaryLinkGet = async (
+  credsPayload,
+  path,
+  {
+    queueRunOptions,
+    fetchClient,
+  } = {},
+) => {
+  const rejectResponse = await argsWarden.responseIfRejectingArgs({
+    credsPayload,
+    path,
+  });
+  if (rejectResponse) {
+    return rejectResponse;
+  }
+
+  return actionSingleOrMultiple(
+    path,
+    dropboxTemporaryLinkGetSingle,
+    (pathItem) => ({
+      args: [credsPayload, pathItem, { fetchClient }],
+    }),
+    {
+      ...(queueRunOptions ? { queueRunOptions } : {}),
+    },
+  );
+};
+
+const funcApiConfig = {
+  argsWarden,
+};
+
+module.exports = {
+  dropboxTemporaryLinkGet,
+  funcApiConfig,
+};

package/api/fedex/docs.md

@@ -0,0 +1,6 @@
+# FedEx
+
+- [FedEx Developer Portal](https://developer.fedex.com/)
+- [FedEx Track API](https://developer.fedex.com/api/en-us/catalog/track.html)
+
+FedEx tracking uses OAuth 2.0 client credentials. Create a project with the Track API enabled, obtain a bearer token from `https://apis.fedex.com/oauth/token`, and submit tracking requests to `https://apis.fedex.com/track/v1/trackingnumbers`. Sandbox requests use `https://apis-sandbox.fedex.com`.

package/api/fedex/fedex.constants.js

@@ -0,0 +1,11 @@
+const FEDEX_LIVE_BASE_URL = 'https://apis.fedex.com';
+const FEDEX_SANDBOX_BASE_URL = 'https://apis-sandbox.fedex.com';
+const FEDEX_OAUTH_PATH = '/oauth/token';
+const FEDEX_TRACKING_PATH = '/track/v1/trackingnumbers';
+
+module.exports = {
+  FEDEX_LIVE_BASE_URL,
+  FEDEX_SANDBOX_BASE_URL,
+  FEDEX_OAUTH_PATH,
+  FEDEX_TRACKING_PATH,
+};

package/api/fedex/fedex.utils.js

@@ -0,0 +1,151 @@
+const { resolveCreds } = require('../pipelineSteps');
+const {
+  FetchClient,
+  appendUrlToBase,
+  customFetch,
+  fetchClientCommonSteps,
+} = require('../utils');
+const {
+  FEDEX_LIVE_BASE_URL,
+  FEDEX_OAUTH_PATH,
+  FEDEX_SANDBOX_BASE_URL,
+} = require('./fedex.constants');
+
+const accessTokenCache = new Map();
+
+const isSandboxCreds = (creds) => {
+  return creds?.SANDBOX === true
+    || creds?.SANDBOX === 'true'
+    || creds?.ENVIRONMENT === 'sandbox';
+};
+
+const baseUrlForCreds = (creds) => {
+  return (creds?.BASE_URL || (
+    isSandboxCreds(creds)
+      ? FEDEX_SANDBOX_BASE_URL
+      : FEDEX_LIVE_BASE_URL
+  )).replace(/\/$/, '');
+};
+
+const getAccessToken = async (creds) => {
+  if (creds?.ACCESS_TOKEN) {
+    return creds.ACCESS_TOKEN;
+  }
+
+  const {
+    CLIENT_ID,
+    CLIENT_SECRET,
+  } = creds || {};
+  if (!CLIENT_ID || !CLIENT_SECRET) {
+    throw new Error(
+      'FedEx creds require ACCESS_TOKEN or CLIENT_ID and CLIENT_SECRET',
+    );
+  }
+
+  const cacheKey = `${ baseUrlForCreds(creds) }:${ CLIENT_ID }`;
+  const cachedToken = accessTokenCache.get(cacheKey);
+  if (cachedToken && cachedToken.expiresAt > Date.now()) {
+    return cachedToken.accessToken;
+  }
+
+  const basicAuth = Buffer
+    .from(`${ CLIENT_ID }:${ CLIENT_SECRET }`)
+    .toString('base64');
+  const response = await customFetch(
+    appendUrlToBase(baseUrlForCreds(creds), FEDEX_OAUTH_PATH),
+    {
+      method: 'post',
+      headers: {
+        Accept: 'application/json',
+        Authorization: `Basic ${ basicAuth }`,
+        'Content-Type': 'application/x-www-form-urlencoded',
+      },
+      body: 'grant_type=client_credentials',
+    },
+  );
+
+  if (!response.ok) {
+    throw new Error(
+      `FedEx authentication failed: ${ JSON.stringify(response.error || response.data) }`,
+    );
+  }
+
+  const {
+    access_token: accessToken,
+    expires_in: expiresIn = 3600,
+  } = response.data || {};
+  if (!accessToken) {
+    throw new Error('FedEx authentication response missing access_token');
+  }
+
+  accessTokenCache.set(cacheKey, {
+    accessToken,
+    expiresAt: Date.now() + (Math.max(expiresIn - 60, 60) * 1000),
+  });
+
+  return accessToken;
+};
+
+const useBaseUrlFromCreds = async (state) => {
+  const { requestPayload, context } = state;
+  const { creds } = context;
+
+  return {
+    requestPayload: {
+      ...requestPayload,
+      url: appendUrlToBase(
+        baseUrlForCreds(creds),
+        requestPayload.url || '',
+      ),
+    },
+  };
+};
+
+const useAuthHeaders = async (state) => {
+  const { requestPayload, context } = state;
+  const { creds } = context;
+
+  let accessToken;
+  try {
+    accessToken = await getAccessToken(creds);
+  } catch (error) {
+    return {
+      breakChain: true,
+      response: {
+        ok: false,
+        error: {
+          code: 'FEDEX_AUTH_ERROR',
+          message: error.message,
+        },
+      },
+    };
+  }
+
+  return {
+    requestPayload: {
+      ...requestPayload,
+      headers: {
+        Accept: 'application/json',
+        Authorization: `Bearer ${ accessToken }`,
+        ...requestPayload.headers,
+      },
+    },
+  };
+};
+
+const fedexClient = new FetchClient({
+  pipeline: [
+    resolveCreds,
+    useBaseUrlFromCreds,
+    useAuthHeaders,
+    'fetch',
+    fetchClientCommonSteps.exitEarlyOnNotOk,
+  ],
+});
+
+module.exports = {
+  accessTokenCache,
+  baseUrlForCreds,
+  fedexClient,
+  getAccessToken,
+};