@foxtware/mineral 0.1.14 → 0.1.16

package/api/discord/discordGet.js

@@ -0,0 +1,144 @@
+// https://discord.com/developers/docs/resources/user#get-current-user
+
+const { ArgsWarden, Getter } = require('../utils');
+const { credsValidator } = require('../validators');
+const { discordClient } = require('../discord/discord.utils');
+const { MAX_PER_PAGE } = require('../discord/discord.constants');
+
+const argsWarden = new ArgsWarden([
+  ['credsPayload', credsValidator],
+  ['url'],
+]);
+
+const discordGetPacket = async (
+  credsPayload,
+  url,
+  {
+    params,
+    perPage = MAX_PER_PAGE,
+  } = {},
+) => {
+  const {
+    limit = Math.min(perPage, MAX_PER_PAGE),
+    ...restParams
+  } = params ?? {};
+
+  return discordClient.fetch({
+    requestPayload: {
+      url,
+      params: {
+        limit,
+        ...restParams,
+      },
+    },
+    context: {
+      credsPayload,
+    },
+  });
+};
+
+const discordGetPaginator = 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;
+  const { limit = Math.min(perPage, MAX_PER_PAGE) } = params;
+
+  if (items.length < limit) {
+    return [true];
+  }
+
+  const lastItem = items[items.length - 1];
+  const before = lastItem?.id;
+  if (!before) {
+    return [true];
+  }
+
+  return [false, {
+    args,
+    options: {
+      ...options,
+      params: {
+        ...params,
+        before,
+      },
+    },
+  }];
+};
+
+const discordGet = 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: discordGetPacket,
+      digester: (response) => {
+        if (!response?.ok) {
+          return [];
+        }
+
+        return Array.isArray(response.data) ? response.data : [];
+      },
+      paginator: discordGetPaginator,
+      ...getterOptions,
+    },
+  );
+
+  if (returnGetter) {
+    return getter;
+  }
+
+  const data = await getter.run({ returnAll: true });
+
+  return {
+    ok: true,
+    data,
+  };
+};
+
+const funcApiConfig = {
+  argsWarden,
+};
+
+module.exports = {
+  discordGet: (...args) => discordGet(false, ...args),
+  discordGetter: (...args) => discordGet(true, ...args),
+  funcApiConfig,
+};
+
+/*
+curl -X POST "http://localhost:8000/discordGet" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "credsPayload": { "credsPath": "discord" },
+    "url": "/users/@me"
+  }'
+*/

package/api/discord/docs.md

@@ -0,0 +1,6 @@
+# Discord
+
+- [Developer documentation](https://discord.com/developers/docs/intro)
+- [REST API reference](https://discord.com/developers/docs/reference)
+
+REST JSON at `https://discord.com/api/v10` for bots and OAuth applications, with bot requests authenticated via `Authorization: Bot <token>`.

package/api/etsy/_example.get.js

@@ -0,0 +1,68 @@
+const { ArgsWarden } = require('../utils');
+const { credsValidator } = require('../validators');
+const { etsyGet, etsyGetter } = require('./etsyGet');
+const { resolveShopId } = require('./etsy.utils');
+
+const argsWarden = new ArgsWarden([
+  ['credsPayload', credsValidator],
+]);
+
+const etsyThingsGet = async (
+  returnGetter,
+
+  credsPayload,
+  {
+    shopId,
+    params,
+    perPage,
+    ...getterOptions
+  } = {},
+) => {
+
+  const rejectResponse = await argsWarden.responseIfRejectingArgs({
+    credsPayload,
+  });
+  if (rejectResponse) {
+    return rejectResponse;
+  }
+
+  const shopIdResponse = await resolveShopId({ shopId, credsPayload });
+  if (!shopIdResponse.ok) {
+    return shopIdResponse;
+  }
+  ({ data: shopId } = shopIdResponse);
+
+  const getterArgs = [
+    credsPayload,
+    `/application/shops/${ shopId }/things`,
+    {
+      params,
+      perPage,
+      ...getterOptions,
+    },
+  ];
+
+  return returnGetter
+    ? etsyGetter(...getterArgs)
+    : etsyGet(...getterArgs);
+};
+
+const funcApiConfig = {
+  argsWarden,
+};
+
+module.exports = {
+  etsyThingsGet: (...args) => etsyThingsGet(false, ...args),
+  etsyThingsGetter: (...args) => etsyThingsGet(true, ...args),
+  funcApiConfig,
+};
+
+/*
+curl -X POST "http://localhost:8000/etsyThingsGet" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "credsPayload": {
+      "credsPath": "etsy"
+    }
+  }'
+*/

package/api/etsy/etsy.constants.js

@@ -0,0 +1,33 @@
+const BASE_URL = 'https://api.etsy.com/v3';
+const OAUTH_CONNECT_URL = 'https://www.etsy.com/oauth/connect';
+const MAX_PER_PAGE = 100;
+
+const OAUTH_ALL_SCOPES = [
+  'address_r', 
+  'address_w', 
+  'billing_r', 
+  'cart_r', 
+  'cart_w', 
+  'email_r', 
+  'favorites_r', 
+  'favorites_w', 
+  'feedback_r', 
+  'listings_d', 
+  'listings_r', 
+  'listings_w', 
+  'profile_r', 
+  'profile_w', 
+  'recommend_r', 
+  'recommend_w', 
+  'shops_r', 
+  'shops_w', 
+  'transactions_r', 
+  'transactions_w',
+];
+
+module.exports = {
+  BASE_URL,
+  OAUTH_CONNECT_URL,
+  MAX_PER_PAGE,
+  OAUTH_ALL_SCOPES,
+};

package/api/etsy/etsy.utils.js

@@ -0,0 +1,208 @@
+const { BASE_URL } = require('../etsy/etsy.constants');
+const { resolveCreds, useBaseUrl } = require('../pipelineSteps');
+const { resolveFromCreds, FetchClient, fetchClientCommonSteps } = require('../utils');
+
+const etsyAccessTokenExpired = (response) => {
+  const details = response?.error?.details;
+
+  return details?.error === 'invalid_token'
+    && details?.error_description === 'access token is expired';
+};
+
+const withEtsyAuthTokenRefresh = async (fetchPayload, next) => {
+  const { context = {} } = fetchPayload;
+
+  if (!context.withAccessToken) {
+    return next(fetchPayload);
+  }
+
+  const response = await next(fetchPayload);
+
+  if (
+    response.ok
+    || !etsyAccessTokenExpired(response)
+    || context.etsyRetriedAfterTokenRefresh
+  ) {
+    return response;
+  }
+
+  const { etsyAccessTokenRefresh } = require('./etsyAccessTokenRefresh');
+  const refreshResponse = await etsyAccessTokenRefresh(context.credsPayload);
+
+  if (!refreshResponse.ok) {
+    return refreshResponse;
+  }
+
+  const { accessToken, refreshToken } = refreshResponse.data;
+
+  return next({
+    ...fetchPayload,
+    context: {
+      ...context,
+      accessToken,
+      refreshToken,
+      etsyRetriedAfterTokenRefresh: true,
+    },
+  });
+};
+
+const useEtsyBaseUrl = async (state) => {
+  const { creds } = state.context;
+  return useBaseUrl(creds.BASE_URL ?? BASE_URL)(state);
+};
+
+const useEtsyApiKeyHeader = async (state) => {
+  const { requestPayload, context } = state;
+  const { creds } = context;
+  const {
+    API_KEY,
+    SHARED_SECRET,
+  } = creds;
+
+  if (!API_KEY || !SHARED_SECRET) {
+    return {
+      breakChain: true,
+      response: {
+        ok: false,
+        error: {
+          code: 'INVALID_CREDS',
+          message: 'API_KEY and SHARED_SECRET are required.',
+        },
+      },
+    };
+  }
+
+  return {
+    requestPayload: {
+      ...requestPayload,
+      headers: {
+        'x-api-key': `${ API_KEY }:${ SHARED_SECRET }`,
+        ...requestPayload.headers,
+      },
+    },
+  };
+};
+
+const tokensFromCredsIfNotContext = async (state) => {
+  const { context } = state;
+  const {
+    withAccessToken,
+    accessToken,
+    refreshToken,
+    creds,
+  } = context;
+
+  if (!withAccessToken) {
+    return {};
+  }
+
+  const contextPatch = {};
+
+  const {
+    ACCESS_TOKEN,
+    REFRESH_TOKEN,
+  } = creds;
+
+  if (!accessToken && ACCESS_TOKEN) {
+    contextPatch.accessToken = ACCESS_TOKEN;
+  }
+
+  if (!refreshToken && REFRESH_TOKEN) {
+    contextPatch.refreshToken = REFRESH_TOKEN;
+  }
+
+  return {
+    context: {
+      ...context,
+      ...contextPatch,
+    },
+  };
+};
+
+const useEtsyBearerFromContext = async (state) => {
+  const { requestPayload, context } = state;
+  const { withAccessToken, accessToken } = context;
+
+  if (!withAccessToken) {
+    return {};
+  }
+
+  if (!accessToken) {
+    return {
+      breakChain: true,
+      response: {
+        ok: false,
+        error: {
+          code: 'NO_ACCESS_TOKEN',
+          message: 'context.accessToken is required when withAccessToken is true.',
+        },
+      },
+    };
+  }
+
+  return {
+    requestPayload: {
+      ...requestPayload,
+      headers: {
+        Authorization: `Bearer ${ accessToken }`,
+        ...requestPayload.headers,
+      },
+    },
+  };
+};
+
+// TODO: In-memory session map for access/refresh tokens per credsPath.
+const etsyClient = new FetchClient({
+  pipeline: [
+    resolveCreds,
+    tokensFromCredsIfNotContext,
+    useEtsyBaseUrl,
+    useEtsyApiKeyHeader,
+    useEtsyBearerFromContext,
+    'fetch',
+    fetchClientCommonSteps.exitEarlyOnNotOk,
+  ],
+  layers: [withEtsyAuthTokenRefresh],
+});
+
+const resolveShopId = async ({ shopId, credsPayload }) => {
+  if (shopId) {
+    return { ok: true, data: shopId };
+  }
+
+  const shopIdFromCredsResponse = await resolveFromCreds('SHOP_ID')({ credsPayload });
+  if (shopIdFromCredsResponse.ok) {
+    return { 
+      ok: true, 
+      data: shopIdFromCredsResponse.data, 
+    };
+  }
+
+  const { etsyMeGet } = require('./etsyMeGet');
+  const meGetResponse = await etsyMeGet(credsPayload);
+  const { ok: meGetOk, data: meGetData } = meGetResponse;
+  if (meGetOk) {
+    ({ shop_id: shopId } = meGetData);
+
+    if (shopId) {
+      return { 
+        ok: true, 
+        data: shopId, 
+      };
+    }
+  }
+
+  return {
+    ok: false,
+    error: {
+      code: 'NO_SHOP_ID',
+      message: 'No shop ID found in creds or me response',
+    },
+  };
+};
+
+module.exports = {
+  etsyClient,
+  etsyAccessTokenExpired,
+  resolveShopId,
+};

package/api/etsy/etsyAccessTokenRefresh.js

@@ -0,0 +1,106 @@
+// https://developers.etsy.com/documentation/essentials/authentication#requesting-an-oauth-token
+
+const { credsValidator } = require('../validators');
+const { credsFromPayload, ArgsWarden } = require('../utils');
+const { etsyClient } = require('./etsy.utils');
+
+const argsWarden = new ArgsWarden([
+  ['credsPayload', credsValidator],
+]);
+
+const etsyAccessTokenRefresh = async (
+  credsPayload,
+  refreshToken,
+  {
+    fetchClient = etsyClient,
+  } = {},
+) => {
+
+  const rejectResponse = await argsWarden.responseIfRejectingArgs({
+    credsPayload,
+  });
+  if (rejectResponse) {
+    return rejectResponse;
+  }
+
+  const creds = await credsFromPayload(credsPayload);
+  const { API_KEY, REFRESH_TOKEN } = creds;
+  const token = refreshToken ?? REFRESH_TOKEN;
+
+  if (!API_KEY || !token) {
+    return {
+      ok: false,
+      error: {
+        code: 'INVALID_CREDS',
+        message: 'API_KEY and REFRESH_TOKEN are required.',
+      },
+    };
+  }
+
+  const response = await fetchClient.fetch({
+    requestPayload: {
+      method: 'post',
+      url: '/public/oauth/token',
+      headers: {
+        'Content-Type': 'application/x-www-form-urlencoded',
+      },
+      body: new URLSearchParams({
+        grant_type: 'refresh_token',
+        client_id: API_KEY,
+        refresh_token: token,
+      }),
+    },
+    context: { credsPayload },
+  });
+
+  if (!response.ok) {
+    return response;
+  }
+
+  const {
+    access_token: accessToken,
+    refresh_token: newRefreshToken,
+    expires_in: expiresIn,
+    token_type: tokenType,
+  } = response.data ?? {};
+
+  if (!accessToken || !newRefreshToken) {
+    return {
+      ok: false,
+      error: {
+        code: 'TOKEN_RESPONSE_INCOMPLETE',
+        message: 'Etsy did not return access_token and refresh_token.',
+        details: response.data,
+      },
+    };
+  }
+
+  return {
+    ok: true,
+    data: {
+      accessToken,
+      refreshToken: newRefreshToken,
+      expiresIn,
+      tokenType,
+    },
+  };
+};
+
+const funcApiConfig = {
+  argsWarden,
+};
+
+module.exports = {
+  etsyAccessTokenRefresh,
+  funcApiConfig,
+};
+
+/*
+curl -X POST "http://localhost:8000/etsyAccessTokenRefresh" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "credsPayload": {
+      "credsPath": "etsy"
+    }
+  }'
+*/

package/api/etsy/etsyAccessTokenRequest.js

@@ -0,0 +1,118 @@
+// https://developers.etsy.com/documentation/essentials/authentication/#step-3-request-an-access-token
+
+const { credsValidator } = require('../validators');
+const { credsFromPayload, ArgsWarden } = require('../utils');
+const { etsyClient } = require('./etsy.utils');
+
+const argsWarden = new ArgsWarden([
+  ['credsPayload', credsValidator],
+  ['code'],
+  ['redirectUri'],
+  ['codeVerifier'],
+]);
+
+const etsyAccessTokenRequest = async (
+  credsPayload,
+  code,
+  redirectUri,
+  codeVerifier,
+  {
+    fetchClient = etsyClient,
+  } = {},
+) => {
+
+  const rejectResponse = await argsWarden.responseIfRejectingArgs({
+    credsPayload,
+    code,
+    redirectUri,
+    codeVerifier,
+  });
+  if (rejectResponse) {
+    return rejectResponse;
+  }
+
+  const creds = await credsFromPayload(credsPayload);
+  const { API_KEY } = creds;
+
+  if (!API_KEY) {
+    return {
+      ok: false,
+      error: {
+        code: 'INVALID_CREDS',
+        message: 'API_KEY is required.',
+      },
+    };
+  }
+
+  const response = await fetchClient.fetch({
+    requestPayload: {
+      method: 'post',
+      url: '/public/oauth/token',
+      headers: {
+        'Content-Type': 'application/x-www-form-urlencoded',
+      },
+      body: new URLSearchParams({
+        grant_type: 'authorization_code',
+        client_id: API_KEY,
+        redirect_uri: redirectUri,
+        code,
+        code_verifier: codeVerifier,
+      }),
+    },
+    context: { credsPayload },
+  });
+
+  if (!response.ok) {
+    return response;
+  }
+
+  const {
+    access_token: accessToken,
+    refresh_token: refreshToken,
+    expires_in: expiresIn,
+    token_type: tokenType,
+  } = response.data ?? {};
+
+  if (!accessToken || !refreshToken) {
+    return {
+      ok: false,
+      error: {
+        code: 'TOKEN_RESPONSE_INCOMPLETE',
+        message: 'Etsy did not return access_token and refresh_token.',
+        details: response.data,
+      },
+    };
+  }
+
+  return {
+    ok: true,
+    data: {
+      accessToken,
+      refreshToken,
+      expiresIn,
+      tokenType,
+    },
+  };
+};
+
+const funcApiConfig = {
+  argsWarden,
+};
+
+module.exports = {
+  etsyAccessTokenRequest,
+  funcApiConfig,
+};
+
+/*
+curl -X POST "http://localhost:8000/etsyAccessTokenRequest" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "credsPayload": {
+      "credsPath": "etsy"
+    },
+    "code": "YOUR_CODE",
+    "redirectUri": "https://YOUR_NGROK/logEtsyAuthCodeResponse",
+    "codeVerifier": "YOUR_CODE_VERIFIER"
+  }'
+*/