@foxtware/mineral 0.1.27 → 0.1.29

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/fastsimon/docs.md

@@ -0,0 +1,14 @@
+# Fast Simon
+
+- [API Documentation](https://docs.fastsimon.com/api/api-doc.html)
+- [Serving API – full text search](https://docs.fastsimon.com/api/api-doc.html#tag/Serving-API/operation/fulltextProducts)
+- [SDK docs](https://docs.fastsimon.com/sdk)
+
+Public Serving API over HTTPS at `https://api.fastsimon.com`. Search and collection reads are unauthenticated beyond the store identifiers: every request carries `UUID` and `store_id` as query parameters (values from the Fast Simon dashboard after install). Admin / merchandising endpoints additionally require an API key and the `X-Site-UUID` / `X-Store-ID` headers.
+
+Core serving flow:
+
+1. `GET /load` – returns site config including `cdn_cache_key` (required on subsequent product requests).
+2. `GET /full_text_search` – full-text product search with optional facets, sorting, narrowing filters, and pagination (`page_num`).
+
+Product results land under `data.items`; facets under `data.facets`. When `facets_required=1` and `data.facets_completed` is false, repeat the request with `facets_required=2` to finish facet computation. JSONP is supported via a `callback` query param; this client uses plain JSON.

package/api/fastsimon/fastsimon.constants.js

@@ -0,0 +1,18 @@
+const BASE_URL = 'https://api.fastsimon.com';
+
+// Common sort_by values documented on full_text_search
+const SORT_BY_OPTIONS = [
+  'relevency', // spelling as returned by the API docs
+  'price_min_to_max',
+  'price_max_to_min',
+  'creation_date',
+  'creation_date_oldest',
+  'reviews',
+  'a_to_z',
+  'z_to_a',
+];
+
+module.exports = {
+  BASE_URL,
+  SORT_BY_OPTIONS,
+};

package/api/fastsimon/fastsimon.utils.js

@@ -0,0 +1,246 @@
+// https://docs.fastsimon.com/api/api-doc.html
+
+const { BASE_URL } = require('../fastsimon/fastsimon.constants');
+const { resolveCreds } = require('../pipelineSteps');
+const {
+  FetchClient,
+  fetchClientCommonSteps,
+  appendUrlToBase,
+} = require('../utils');
+
+const sessionCacheKeyForCredsPayload = (credsPayload) => {
+  if (credsPayload?.credsPath) {
+    return credsPayload.credsPath;
+  }
+
+  return JSON.stringify(credsPayload);
+};
+
+// cdn_cache_key is required on product endpoints and is obtained from /load.
+// Cache per creds identity so repeated searches in the same process reuse it.
+const cdnCacheKeyByCredsKey = new Map();
+
+const normaliseLoadData = (data) => {
+  if (data == null) {
+    return {};
+  }
+  if (typeof data === 'string') {
+    try {
+      return JSON.parse(data);
+    } catch {
+      return {};
+    }
+  }
+  return data;
+};
+
+const pickCdnCacheKey = (data) => {
+  const body = normaliseLoadData(data);
+  return (
+    body.cdn_cache_key ??
+    body.cdnCacheKey ??
+    body.cache_key ??
+    body.cacheKey ??
+    null
+  );
+};
+
+const useUrlAndAuthQuery = async (state) => {
+  const { requestPayload, context } = state;
+  const { creds } = context;
+  const {
+    UUID,
+    STORE_ID,
+  } = creds ?? {};
+
+  if (!UUID || !STORE_ID) {
+    return {
+      response: {
+        ok: false,
+        error: {
+          code: 'MISSING_FASTSIMON_CREDS',
+          message: 'fastsimon creds require UUID and STORE_ID',
+        },
+      },
+      breakChain: true,
+    };
+  }
+
+  const query = {
+    UUID,
+    store_id: STORE_ID,
+    ...(requestPayload.query || {}),
+  };
+
+  // Prefer an explicitly provided cdn_cache_key (e.g. from options),
+  // otherwise inject a previously cached one if present.
+  const cacheKey = sessionCacheKeyForCredsPayload(context.credsPayload || {});
+  if (!query.cdn_cache_key && cdnCacheKeyByCredsKey.has(cacheKey)) {
+    query.cdn_cache_key = cdnCacheKeyByCredsKey.get(cacheKey);
+  }
+
+  const searchParams = new URLSearchParams();
+  Object.entries(query).forEach(([key, value]) => {
+    if (value === undefined || value === null) {
+      return;
+    }
+    // narrow is documented as a JSON-encoded list of tuples; stringify objects/arrays
+    if (typeof value === 'object') {
+      searchParams.append(key, JSON.stringify(value));
+    } else {
+      searchParams.append(key, String(value));
+    }
+  });
+
+  const path = requestPayload.url || '';
+  const url = `${ appendUrlToBase(BASE_URL, path) }?${ searchParams.toString() }`;
+
+  return {
+    requestPayload: {
+      ...requestPayload,
+      url,
+      headers: {
+        Accept: 'application/json',
+        ...requestPayload.headers,
+      },
+    },
+  };
+};
+
+const rememberCdnCacheKey = async (state) => {
+  const { response, context } = state;
+  if (!response?.ok || !response?.data) {
+    return {};
+  }
+
+  const cdnCacheKey = pickCdnCacheKey(response.data);
+  if (cdnCacheKey == null) {
+    return {};
+  }
+
+  const cacheKey = sessionCacheKeyForCredsPayload(context.credsPayload || {});
+  cdnCacheKeyByCredsKey.set(cacheKey, cdnCacheKey);
+
+  return {};
+};
+
+/**
+ * Fast Simon often returns the body as a JSON string. Parse it, then for
+ * product payloads dig `items` into `data` and move everything else to `meta`
+ * (total_results, term, facets, page info, uuid, etc.).
+ */
+const normaliseSearchResponse = async (state) => {
+  const { response } = state;
+  if (!response?.ok || response.data == null) {
+    return {};
+  }
+
+  let body = response.data;
+  if (typeof body === 'string') {
+    try {
+      body = JSON.parse(body);
+    } catch {
+      return {};
+    }
+  }
+
+  if (!body || typeof body !== 'object' || Array.isArray(body)) {
+    return {
+      response: {
+        data: body,
+      },
+    };
+  }
+
+  if (!Object.prototype.hasOwnProperty.call(body, 'items')) {
+    return {
+      response: {
+        data: body,
+      },
+    };
+  }
+
+  const { items, ...rest } = body;
+
+  return {
+    response: {
+      data: items,
+      meta: {
+        ...(response.meta || {}),
+        ...rest,
+      },
+    },
+  };
+};
+
+const fastsimonClient = new FetchClient({
+  pipeline: [
+    resolveCreds,
+    useUrlAndAuthQuery,
+    'fetch',
+    fetchClientCommonSteps.exitEarlyOnNotOk,
+    rememberCdnCacheKey,
+    normaliseSearchResponse,
+  ],
+});
+
+/**
+ * Fetch (and cache) the current CDN cache key via GET /load.
+ * Safe to call repeatedly; subsequent calls hit the in-memory cache.
+ *
+ * Some stores' /load payloads omit `cdn_cache_key` even though the OpenAPI
+ * marks it required. In that case we fall back to the current Unix epoch
+ * (the documented type of the field), which is enough for the search CDN
+ * to accept the request.
+ */
+const ensureCdnCacheKey = async (credsPayload, { fetchClient = fastsimonClient } = {}) => {
+  const cacheKey = sessionCacheKeyForCredsPayload(credsPayload);
+  if (cdnCacheKeyByCredsKey.has(cacheKey)) {
+    return {
+      ok: true,
+      data: { cdn_cache_key: cdnCacheKeyByCredsKey.get(cacheKey) },
+    };
+  }
+
+  const response = await fetchClient.fetch({
+    requestPayload: {
+      method: 'get',
+      url: '/load',
+      query: {},
+    },
+    context: {
+      credsPayload,
+    },
+  });
+
+  if (!response?.ok) {
+    return response;
+  }
+
+  let cdnCacheKey = pickCdnCacheKey(response.data);
+
+  if (cdnCacheKey == null) {
+    // Live /load responses for some stores return theme/config fields but no
+    // cdn_cache_key. The field is documented as a Unix epoch integer — using
+    // "now" is a safe cache-busting fallback that the Serving API accepts.
+    cdnCacheKey = Math.floor(Date.now() / 1000);
+  }
+
+  cdnCacheKeyByCredsKey.set(cacheKey, cdnCacheKey);
+
+  return {
+    ok: true,
+    data: {
+      cdn_cache_key: cdnCacheKey,
+      // surface whether we synthesised the key, in case callers care
+      synthesised: pickCdnCacheKey(response.data) == null,
+    },
+  };
+};
+
+module.exports = {
+  fastsimonClient,
+  ensureCdnCacheKey,
+  // exposed for tests / manual cache control
+  cdnCacheKeyByCredsKey,
+};

package/api/fastsimon/fastsimonSearch.js

@@ -0,0 +1,84 @@
+// https://docs.fastsimon.com/api/api-doc.html#tag/Serving-API/operation/fulltextProducts
+
+const { credsValidator } = require('../validators');
+const { ArgsWarden } = require('../utils');
+const { fastsimonClient, ensureCdnCacheKey } = require('../fastsimon/fastsimon.utils');
+
+const argsWarden = new ArgsWarden([
+  ['credsPayload', credsValidator],
+  ['query'],
+]);
+
+const fastsimonSearch = async (
+  credsPayload,
+  query,
+  {
+    cdnCacheKey,
+    facetsRequired,
+    sortBy,
+    narrow,
+    pageNum,
+    fetchClient = fastsimonClient,
+  } = {},
+) => {
+
+  const rejectResponse = await argsWarden.responseIfRejectingArgs({
+    credsPayload,
+    query,
+  });
+  if (rejectResponse) {
+    return rejectResponse;
+  }
+
+  let resolvedCdnCacheKey = cdnCacheKey;
+  if (!resolvedCdnCacheKey) {
+    const loadRes = await ensureCdnCacheKey(credsPayload, { fetchClient });
+    if (!loadRes.ok) {
+      return loadRes;
+    }
+    resolvedCdnCacheKey = loadRes.data.cdn_cache_key;
+  }
+
+  const response = await fetchClient.fetch({
+    requestPayload: {
+      method: 'get',
+      url: '/full_text_search',
+      query: {
+        q: query,
+        cdn_cache_key: resolvedCdnCacheKey,
+        ...(facetsRequired !== undefined ? { facets_required: facetsRequired } : {}),
+        ...(sortBy ? { sort_by: sortBy } : {}),
+        ...(narrow !== undefined ? { narrow } : {}),
+        ...(pageNum !== undefined ? { page_num: pageNum } : {}),
+      },
+    },
+    context: {
+      credsPayload,
+    },
+  });
+
+  return response;
+};
+
+const funcApiConfig = {
+  argsWarden,
+};
+
+module.exports = {
+  fastsimonSearch,
+  funcApiConfig,
+};
+
+/*
+  curl -X POST "http://localhost:8000/fastsimonSearch" \
+    -H "Content-Type: application/json" \
+    -d '{
+      "credsPayload": { "credsPath": "fastsimon.au" },
+      "query": "dress",
+      "options": {
+        "facetsRequired": 1,
+        "pageNum": 1,
+        "sortBy": "relevency"
+      }
+    }'
+*/

package/api/figma/docs.md

@@ -1,6 +1,6 @@
 # Figma
 
-- [Developer documentation](https://www.figma.com/developers/api)
-- [Authentication](https://www.figma.com/developers/api#authentication)
+- [Developer documentation](https://developers.figma.com/docs/rest-api/)
+- [Authentication](https://developers.figma.com/docs/rest-api/authentication/)
 
-REST JSON at `https://api.figma.com/v1` for files, comments, and variables, authenticated with a personal access token in the `X-Figma-Token` header.
+REST JSON at `https://api.figma.com` for files, comments, variables, components, styles, folders, dev resources, webhooks, and organization APIs. Personal and plan access tokens use the `X-Figma-Token` header; OAuth 2 access tokens use `Authorization: Bearer`.

package/api/figma/figma.constants.js

@@ -1,4 +1,4 @@
-const FIGMA_API_BASE_URL = 'https://api.figma.com/v1';
+const FIGMA_API_BASE_URL = 'https://api.figma.com';
 const MAX_PER_PAGE = 100;
 
 module.exports = {

package/api/figma/figma.utils.js

@@ -8,13 +8,24 @@ const {
 const useAuthHeaders = async (state) => {
   const { requestPayload, context } = state;
   const { creds } = context;
-  const { API_KEY } = creds;
+  const {
+    API_KEY,
+    ACCESS_TOKEN,
+  } = creds ?? {};
+
+  const authHeaders = ACCESS_TOKEN
+    ? {
+      Authorization: `Bearer ${ ACCESS_TOKEN }`,
+    }
+    : {
+      'X-Figma-Token': API_KEY,
+    };
 
   return {
     requestPayload: {
       ...requestPayload,
       headers: {
-        'X-Figma-Token': API_KEY,
+        ...authHeaders,
         ...requestPayload.headers,
       },
     },

package/api/figma/figmaActivityLogsGet.js

@@ -0,0 +1,44 @@
+// https://developers.figma.com/docs/rest-api/activity-logs-endpoints/
+
+const { ArgsWarden } = require('../utils');
+const { credsValidator } = require('../validators');
+const { figmaClient } = require('../figma/figma.utils');
+
+const argsWarden = new ArgsWarden([
+  ['credsPayload', credsValidator],
+]);
+
+const figmaActivityLogsGet = async (
+  credsPayload,
+  {
+    params,
+    fetchClient = figmaClient,
+  } = {},
+) => {
+  const rejectResponse = await argsWarden.responseIfRejectingArgs({
+    credsPayload
+  });
+  if (rejectResponse) {
+    return rejectResponse;
+  }
+
+  return fetchClient.fetch({
+    requestPayload: {
+      method: 'get',
+      url: `/v1/activity_logs`,
+      params,
+    },
+    context: {
+      credsPayload,
+    },
+  });
+};
+
+const funcApiConfig = {
+  argsWarden,
+};
+
+module.exports = {
+  figmaActivityLogsGet,
+  funcApiConfig,
+};

package/api/figma/figmaAiUsageDailyGet.js

@@ -0,0 +1,44 @@
+// https://developers.figma.com/docs/rest-api/ai-usage-endpoints/
+
+const { ArgsWarden } = require('../utils');
+const { credsValidator } = require('../validators');
+const { figmaClient } = require('../figma/figma.utils');
+
+const argsWarden = new ArgsWarden([
+  ['credsPayload', credsValidator],
+]);
+
+const figmaAiUsageDailyGet = async (
+  credsPayload,
+  {
+    params,
+    fetchClient = figmaClient,
+  } = {},
+) => {
+  const rejectResponse = await argsWarden.responseIfRejectingArgs({
+    credsPayload
+  });
+  if (rejectResponse) {
+    return rejectResponse;
+  }
+
+  return fetchClient.fetch({
+    requestPayload: {
+      method: 'get',
+      url: `/v1/ai_usage/daily`,
+      params,
+    },
+    context: {
+      credsPayload,
+    },
+  });
+};
+
+const funcApiConfig = {
+  argsWarden,
+};
+
+module.exports = {
+  figmaAiUsageDailyGet,
+  funcApiConfig,
+};

package/api/figma/figmaComponentGet.js

@@ -0,0 +1,48 @@
+// https://developers.figma.com/docs/rest-api/component-endpoints/
+
+const { ArgsWarden } = require('../utils');
+const { credsValidator } = require('../validators');
+const { figmaClient } = require('../figma/figma.utils');
+
+const argsWarden = new ArgsWarden([
+  ['credsPayload', credsValidator],
+  ['key'],
+]);
+
+const figmaComponentGet = async (
+  credsPayload,
+  key,
+  {
+    params,
+    fetchClient = figmaClient,
+  } = {},
+) => {
+  const rejectResponse = await argsWarden.responseIfRejectingArgs({
+    credsPayload,
+    key,
+  });
+  if (rejectResponse) {
+    return rejectResponse;
+  }
+
+  return fetchClient.fetch({
+    requestPayload: {
+      method: 'get',
+      url: `/v1/components/${ key }`,
+      
+      
+    },
+    context: {
+      credsPayload,
+    },
+  });
+};
+
+const funcApiConfig = {
+  argsWarden,
+};
+
+module.exports = {
+  figmaComponentGet,
+  funcApiConfig,
+};