@foxtware/mineral 0.1.26 → 0.1.28

package/.creds.yml.sample

@@ -94,6 +94,8 @@ telnyx:
 
 figma:
   API_KEY: figd___________________________
+  # Or use ACCESS_TOKEN for an OAuth 2 bearer token
+  ACCESS_TOKEN: __________________________
 
 pipe17:
   API_KEY: _______________________________
@@ -115,13 +117,29 @@ google:
 
 tagalys:
   store:
-    BASE_URL: ____________________________ # Server URL
-    CLIENT_CODE: _________________________
-    API_KEY: _____________________________
-    STORE_ID: ____________________________
+    BASE_URL: ____________________________ 
+    CLIENT_CODE: _________________________ # unused but surfaced in dashboard
+    API_KEY: _____________________________ # unused but surfaced in dashboard
+    STOREFRONT_API_KEY: __________________
+    STORE_HANDLE: ________________________
 
 tableau:
   PAT_NAME: ______________________________
   PAT_SECRET: ____________________________
   SERVER_URL: ____________________________
   SITE_CONTENT_URL: ______________________
+
+salesforce:
+  # Option A — pre-issued token
+  ACCESS_TOKEN: __________________________
+  INSTANCE_URL: https://________.my.salesforce.com
+
+  # Option B — client credentials (if ACCESS_TOKEN missing)
+  CLIENT_ID: _____________________________
+  CLIENT_SECRET: _________________________
+  LOGIN_URL: https://login.salesforce.com  # or My Domain / test.salesforce.com
+
+fastsimon:
+  store:                                   # instance name of your choice
+    UUID: _______________________________  # Dashboard → Settings
+    STORE_ID: ___________________________  # Dashboard → Settings

package/AGENTS.md

@@ -25,3 +25,20 @@ Notes for AI assistants working in this directory. **Read this file at the start
 ## 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.
 - Don't explicitly set `Content-Type: application/json` on the client — `customFetch` already adds it when there is a request body.
+
+## Usual structure of a platform API client
+This is the usual structure, but it can be altered per platform, if required. If there is no good reason to deviate, this is how a platform should look.
+- Functions live in `/api/[platform]`
+- If `docs.md` exists, it is a minimal link to native API documentation and a brief description of its structure. It is not concerned with our implementation and does not need to be updated.
+- Creds are supported by path from `.creds.yml`. `.creds.yml.sample` documents the structure of the required creds.
+- A customised FetchClient called `[platform]Client` exists in `[platform].utils.js`, which handles API requests. It implements a base URL, and resolves `credsPayload` into `context.creds` for future steps.
+- All functions require a `credsPayload` argument to tell them which credentials to use. They relate per instance.
+- `[platform].constants.js` contains any max pagination limits, default API version, base url (if not changing per instance).
+- `[platform]Get.js` is a generic function which gets resources in a paginated way. It implements Getter, and all `[platform]ResourceGet.js` functions export both `platformResourceGet` and `platformResourceGetter`, using the "bind" export style.
+- Each endpoint of the platform's API is supported as a separate function within the platform directory. Functions are named `[platform]NounVerb.js`, e.g. `shopifyPageDelete`.
+- Endpoints should return the unwrapped data inside the standard response format, e.g. `data: { ...resource }`. Not e.g. `data: { product/data/result: { ...resource } }`.
+- Each function creates and exports an `ArgsWarden`. Inside, mandatory arguments are validated. At minimum, all mandatory arguments should be a singleton, which falls back to a generic "value provided" validator. Anything that is not mandatory should be an option, included in the optional "options" argument which is commonly destructured in the function definition.
+- For functions which act on a single resource, e.g. `shopifyPageGet`, `actionSingleOrMultiple` is implemented as an enhancement to allow acting on multiple items in a one-by-one fashion.
+- `fetchClient` is implemented as an option, allowing implementations outside mineral core to use their own pipeline in making requests. This may include caching auth or utilising other platforms in the pipeline.
+
+

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,
+};

package/api/figma/figmaComponentSetGet.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 figmaComponentSetGet = 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/component_sets/${ key }`,
+      
+      
+    },
+    context: {
+      credsPayload,
+    },
+  });
+};
+
+const funcApiConfig = {
+  argsWarden,
+};
+
+module.exports = {
+  figmaComponentSetGet,
+  funcApiConfig,
+};