@foxtware/mineral 0.1.27 → 0.1.29

package/api/shopify/shopifyMetaobjectUpdate.js

@@ -0,0 +1,108 @@
+// https://shopify.dev/docs/api/admin-graphql/latest/mutations/metaobjectUpdate
+
+const { credsValidator } = require('../validators');
+const { actionSingleOrMultiple, everyIfArray, ArgsWarden, valueProvided } = require('../utils');
+const { shopifyMutationDo } = require('../shopify/shopifyMutationDo');
+
+const updatePayloadValidator = (updatePayload) => valueProvided(updatePayload)
+  && typeof updatePayload === 'object';
+
+const argsWarden = new ArgsWarden([
+  ['credsPayload', credsValidator],
+  ['metaobjectId', (i) => everyIfArray(valueProvided, i)],
+  ['updatePayload', (i) => everyIfArray(updatePayloadValidator, i)],
+]);
+
+const defaultReturnMetaobjectAttrs = 'id handle type updatedAt capabilities { publishable { status } }';
+
+const shopifyMetaobjectUpdateSingle = async (
+  credsPayload,
+  metaobjectId,
+  updatePayload,
+  {
+    apiVersion,
+    returnMetaobjectAttrs = defaultReturnMetaobjectAttrs,
+  } = {},
+) => {
+
+  return shopifyMutationDo(
+    credsPayload,
+    'metaobjectUpdate',
+    {
+      mutationVariables: {
+        id: {
+          type: 'ID!',
+          value: `gid://shopify/Metaobject/${ metaobjectId }`,
+        },
+        metaobject: {
+          type: 'MetaobjectUpdateInput!',
+          value: updatePayload,
+        },
+      },
+      returnSchema: `metaobject { ${ returnMetaobjectAttrs } }`,
+      apiVersion,
+    },
+  );
+};
+
+const shopifyMetaobjectUpdate = async (
+  credsPayload,
+  metaobjectId,
+  updatePayload,
+  {
+    queueRunOptions,
+    apiVersion,
+    returnMetaobjectAttrs = defaultReturnMetaobjectAttrs,
+  } = {},
+) => {
+
+  const rejectResponse = await argsWarden.responseIfRejectingArgs({
+    credsPayload,
+    metaobjectId,
+    updatePayload,
+  });
+  if (rejectResponse) {
+    return rejectResponse;
+  }
+
+  return actionSingleOrMultiple(
+    [metaobjectId, updatePayload],
+    shopifyMetaobjectUpdateSingle,
+    (metaobjectIdItem, updatePayloadItem) => ({
+      args: [
+        credsPayload,
+        metaobjectIdItem,
+        updatePayloadItem,
+        { apiVersion, returnMetaobjectAttrs },
+      ],
+    }),
+    {
+      ...(queueRunOptions ? { queueRunOptions } : {}),
+    },
+  );
+};
+
+const funcApiConfig = {
+  argsWarden,
+};
+
+module.exports = {
+  shopifyMetaobjectUpdate,
+  funcApiConfig,
+};
+
+/*
+curl -X POST "http://localhost:8000/shopifyMetaobjectUpdate" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "credsPayload": { "credsPath": "shopify.au" },
+    "metaobjectId": "207864102984",
+    "updatePayload": {
+      "capabilities": {
+        "publishable": {
+          "status": "ACTIVE"
+        }
+      }
+    }
+  }'
+*/

package/api/shopify/shopifyStorefrontSearch.js

@@ -0,0 +1,158 @@
+// https://shopify.dev/docs/api/storefront/latest/queries/search
+
+const { credsValidator } = require('../validators');
+const { ArgsWarden } = require('../utils');
+const { shopifyStorefrontClient } = require('./shopify.utils');
+const { MAX_PER_PAGE } = require('./shopify.constants');
+
+const defaultAttrs = `
+  ... on Product {
+    id
+    handle
+    title
+  }
+  ... on Page {
+    id
+    handle
+    title
+  }
+  ... on Article {
+    id
+    handle
+    title
+  }
+`.trim();
+
+const argsWarden = new ArgsWarden([
+  ['credsPayload', credsValidator],
+  ['query'],
+]);
+
+const shopifyStorefrontSearch = async (
+  credsPayload,
+  query,
+  {
+    apiVersion,
+    attrs = defaultAttrs,
+    first = MAX_PER_PAGE,
+    cursor,
+    reverse,
+    sortKey,
+    types,
+    prefix,
+    productFilters,
+    unavailableProducts,
+    fetchClient = shopifyStorefrontClient,
+  } = {},
+) => {
+
+  const rejectResponse = await argsWarden.responseIfRejectingArgs({
+    credsPayload,
+    query,
+  });
+  if (rejectResponse) {
+    return rejectResponse;
+  }
+
+  const queryTypeDeclaration = [
+    '$query: String!',
+    '$first: Int!',
+    '$cursor: String',
+    ...reverse !== undefined ? ['$reverse: Boolean'] : [],
+    ...sortKey ? ['$sortKey: SearchSortKeys'] : [],
+    ...types ? ['$types: [SearchType!]'] : [],
+    ...prefix ? ['$prefix: SearchPrefixQueryType'] : [],
+    ...productFilters ? ['$productFilters: [ProductFilter!]'] : [],
+    ...unavailableProducts ? ['$unavailableProducts: SearchUnavailableProductsType'] : [],
+  ].join('\n');
+
+  const queryVariableDeclaration = [
+    'query: $query',
+    'first: $first',
+    'after: $cursor',
+    ...reverse !== undefined ? ['reverse: $reverse'] : [],
+    ...sortKey ? ['sortKey: $sortKey'] : [],
+    ...types ? ['types: $types'] : [],
+    ...prefix ? ['prefix: $prefix'] : [],
+    ...productFilters ? ['productFilters: $productFilters'] : [],
+    ...unavailableProducts ? ['unavailableProducts: $unavailableProducts'] : [],
+  ].join('\n');
+
+  const variables = {
+    query,
+    first,
+    cursor,
+    ...reverse !== undefined && { reverse },
+    ...sortKey && { sortKey },
+    ...types && { types },
+    ...prefix && { prefix },
+    ...productFilters && { productFilters },
+    ...unavailableProducts && { unavailableProducts },
+  };
+
+  return fetchClient.fetch({
+    requestPayload: {
+      method: 'post',
+      body: {
+        query: `
+          query StorefrontSearch (
+            ${ queryTypeDeclaration }
+          ) {
+            search(
+              ${ queryVariableDeclaration }
+            ) {
+              totalCount
+              productFilters {
+                id
+                label
+                type
+                values {
+                  id
+                  label
+                  count
+                }
+              }
+              edges {
+                node {
+                  ${ attrs }
+                }
+              }
+              pageInfo {
+                hasNextPage
+                endCursor
+              }
+            }
+          }
+        `,
+        variables,
+      },
+    },
+    context: {
+      credsPayload,
+      apiVersion,
+      resultPath: 'data.search',
+    },
+  });
+};
+
+const funcApiConfig = {
+  argsWarden,
+};
+
+module.exports = {
+  shopifyStorefrontSearch,
+  funcApiConfig,
+};
+
+/*
+curl -X POST "http://localhost:8000/shopifyStorefrontSearch" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "credsPayload": { "credsPath": "shopify.au" },
+    "query": "dress",
+    "options": {
+      "first": 5,
+      "types": ["PRODUCT"]
+    }
+  }'
+*/

package/api/spotify/docs.md

@@ -0,0 +1,8 @@
+# Spotify
+
+- [Web API](https://developer.spotify.com/documentation/web-api)
+- [API reference](https://developer.spotify.com/documentation/web-api/reference)
+- [Authorization](https://developer.spotify.com/documentation/web-api/concepts/authorization)
+- [API calls](https://developer.spotify.com/documentation/web-api/concepts/api-calls)
+
+REST JSON at `https://api.spotify.com/v1/...` with OAuth 2 bearer access tokens (`Authorization: Bearer`). Catalog and user endpoints use standard GET/POST/PUT/DELETE; many list responses are offset/limit paginated (`items`, `next`, `total`). User-scoped routes (playlists, library, player) need appropriate OAuth scopes; client-credentials tokens only cover public catalog data.

package/api/spotify/spotify.constants.js

@@ -0,0 +1,12 @@
+const SPOTIFY_API_BASE_URL = 'https://api.spotify.com/v1';
+const SPOTIFY_ACCOUNTS_BASE_URL = 'https://accounts.spotify.com';
+// Most list endpoints cap at 50; search max is lower (10 as of 2026 policy changes).
+const MAX_PER_PAGE = 50;
+const MAX_SEARCH_PER_PAGE = 10;
+
+module.exports = {
+  SPOTIFY_API_BASE_URL,
+  SPOTIFY_ACCOUNTS_BASE_URL,
+  MAX_PER_PAGE,
+  MAX_SEARCH_PER_PAGE,
+};

package/api/spotify/spotify.utils.js

@@ -0,0 +1,106 @@
+const {
+  SPOTIFY_API_BASE_URL,
+  SPOTIFY_ACCOUNTS_BASE_URL,
+} = require('../spotify/spotify.constants');
+const { resolveCreds, useBaseUrl } = require('../pipelineSteps');
+const {
+  FetchClient,
+  fetchClientCommonSteps,
+  customFetch,
+  credsFromPayload,
+} = require('../utils');
+
+// Cache client-credentials tokens per CLIENT_ID so we are not minting on every call.
+const clientCredentialsTokenCache = new Map();
+
+const getClientCredentialsToken = async ({ CLIENT_ID, CLIENT_SECRET }) => {
+  const cacheKey = CLIENT_ID;
+  const cached = clientCredentialsTokenCache.get(cacheKey);
+  if (cached && cached.expiresAt > Date.now()) {
+    return cached.accessToken;
+  }
+
+  const basic = Buffer
+    .from(`${ CLIENT_ID }:${ CLIENT_SECRET }`)
+    .toString('base64');
+
+  const response = await customFetch(
+    `${ SPOTIFY_ACCOUNTS_BASE_URL }/api/token`,
+    {
+      method: 'post',
+      headers: {
+        Authorization: `Basic ${ basic }`,
+        'Content-Type': 'application/x-www-form-urlencoded',
+      },
+      body: 'grant_type=client_credentials',
+    },
+  );
+
+  if (!response.ok) {
+    throw new Error(
+      `Spotify client_credentials failed: ${ JSON.stringify(response.error ?? response.data) }`,
+    );
+  }
+
+  const { access_token: accessToken, expires_in: expiresIn = 3600 } = response.data ?? {};
+  if (!accessToken) {
+    throw new Error('Spotify client_credentials response missing access_token');
+  }
+
+  clientCredentialsTokenCache.set(cacheKey, {
+    accessToken,
+    // Refresh a minute early.
+    expiresAt: Date.now() + (expiresIn - 60) * 1000,
+  });
+
+  return accessToken;
+};
+
+const resolveAccessToken = async (creds) => {
+  if (creds?.ACCESS_TOKEN) {
+    return creds.ACCESS_TOKEN;
+  }
+
+  const { CLIENT_ID, CLIENT_SECRET } = creds ?? {};
+  if (CLIENT_ID && CLIENT_SECRET) {
+    return getClientCredentialsToken({ CLIENT_ID, CLIENT_SECRET });
+  }
+
+  throw new Error(
+    'spotify creds require ACCESS_TOKEN or CLIENT_ID + CLIENT_SECRET',
+  );
+};
+
+const useAuthHeaders = async (state) => {
+  const { requestPayload, context } = state;
+  const { creds } = context;
+
+  const accessToken = await resolveAccessToken(creds);
+
+  return {
+    requestPayload: {
+      ...requestPayload,
+      headers: {
+        Accept: 'application/json',
+        Authorization: `Bearer ${ accessToken }`,
+        ...requestPayload.headers,
+      },
+    },
+  };
+};
+
+const spotifyClient = new FetchClient({
+  pipeline: [
+    resolveCreds,
+    useBaseUrl(SPOTIFY_API_BASE_URL),
+    useAuthHeaders,
+    'fetch',
+    fetchClientCommonSteps.exitEarlyOnNotOk,
+  ],
+});
+
+module.exports = {
+  spotifyClient,
+  resolveAccessToken,
+  getClientCredentialsToken,
+};

package/api/spotify/spotifyAlbumGet.js

@@ -0,0 +1,76 @@
+// https://developer.spotify.com/documentation/web-api/reference/get-an-album
+
+const { ArgsWarden, actionSingleOrMultiple, logDeep } = require('../utils');
+const { credsValidator } = require('../validators');
+const { spotifyClient } = require('../spotify/spotify.utils');
+
+const argsWarden = new ArgsWarden([
+  ['credsPayload', credsValidator],
+  ['albumId'],
+]);
+
+const spotifyAlbumGetSingle = async (
+  credsPayload,
+  albumId,
+  {
+    market,
+    fetchClient = spotifyClient,
+  } = {},
+) => {
+  const response = await fetchClient.fetch({
+    context: { credsPayload },
+    requestPayload: {
+      method: 'get',
+      url: `/albums/${ albumId }`,
+      params: {
+        ...(market !== undefined && { market }),
+      },
+    },
+  });
+
+  const { ok, data, error } = response;
+  if (!ok) {
+    logDeep({ error });
+    return { ok: false, error };
+  }
+
+  return { ok: true, data };
+};
+
+const spotifyAlbumGet = async (
+  credsPayload,
+  albumId,
+  {
+    market,
+    queueRunOptions,
+    fetchClient,
+  } = {},
+) => {
+  const rejectResponse = await argsWarden.responseIfRejectingArgs({
+    credsPayload,
+    albumId,
+  });
+  if (rejectResponse) {
+    return rejectResponse;
+  }
+
+  return actionSingleOrMultiple(
+    albumId,
+    spotifyAlbumGetSingle,
+    (albumIdItem) => ({
+      args: [credsPayload, albumIdItem, { market, fetchClient }],
+    }),
+    {
+      ...(queueRunOptions ? { queueRunOptions } : {}),
+    },
+  );
+};
+
+const funcApiConfig = {
+  argsWarden,
+};
+
+module.exports = {
+  spotifyAlbumGet,
+  funcApiConfig,
+};

package/api/spotify/spotifyAlbumTracksGet.js

@@ -0,0 +1,49 @@
+// https://developer.spotify.com/documentation/web-api/reference/get-an-albums-tracks
+
+const { ArgsWarden } = require('../utils');
+const { credsValidator } = require('../validators');
+const { spotifyGet } = require('../spotify/spotifyGet');
+const { MAX_PER_PAGE } = require('../spotify/spotify.constants');
+
+const argsWarden = new ArgsWarden([
+  ['credsPayload', credsValidator],
+  ['albumId'],
+]);
+
+const spotifyAlbumTracksGet = async (
+  credsPayload,
+  albumId,
+  {
+    market,
+    perPage = MAX_PER_PAGE,
+    fetchClient,
+    ...getterOptions
+  } = {},
+) => {
+  const rejectResponse = await argsWarden.responseIfRejectingArgs({
+    credsPayload,
+    albumId,
+  });
+  if (rejectResponse) {
+    return rejectResponse;
+  }
+
+  return spotifyGet(credsPayload, `/albums/${ albumId }/tracks`, {
+    params: {
+      ...(market !== undefined && { market }),
+    },
+    perPage,
+    resultsKey: 'items',
+    fetchClient,
+    ...getterOptions,
+  });
+};
+
+const funcApiConfig = {
+  argsWarden,
+};
+
+module.exports = {
+  spotifyAlbumTracksGet,
+  funcApiConfig,
+};

package/api/spotify/spotifyArtistAlbumsGet.js

@@ -0,0 +1,55 @@
+// https://developer.spotify.com/documentation/web-api/reference/get-an-artists-albums
+
+const { ArgsWarden } = require('../utils');
+const { credsValidator } = require('../validators');
+const { spotifyGet } = require('../spotify/spotifyGet');
+const { MAX_PER_PAGE } = require('../spotify/spotify.constants');
+
+const argsWarden = new ArgsWarden([
+  ['credsPayload', credsValidator],
+  ['artistId'],
+]);
+
+const spotifyArtistAlbumsGet = async (
+  credsPayload,
+  artistId,
+  {
+    includeGroups,
+    market,
+    perPage = MAX_PER_PAGE,
+    fetchClient,
+    ...getterOptions
+  } = {},
+) => {
+  const rejectResponse = await argsWarden.responseIfRejectingArgs({
+    credsPayload,
+    artistId,
+  });
+  if (rejectResponse) {
+    return rejectResponse;
+  }
+
+  return spotifyGet(credsPayload, `/artists/${ artistId }/albums`, {
+    params: {
+      ...(includeGroups !== undefined && {
+        include_groups: Array.isArray(includeGroups)
+          ? includeGroups.join(',')
+          : includeGroups,
+      }),
+      ...(market !== undefined && { market }),
+    },
+    perPage,
+    resultsKey: 'items',
+    fetchClient,
+    ...getterOptions,
+  });
+};
+
+const funcApiConfig = {
+  argsWarden,
+};
+
+module.exports = {
+  spotifyArtistAlbumsGet,
+  funcApiConfig,
+};

package/api/spotify/spotifyArtistGet.js

@@ -0,0 +1,71 @@
+// https://developer.spotify.com/documentation/web-api/reference/get-an-artist
+
+const { ArgsWarden, actionSingleOrMultiple, logDeep } = require('../utils');
+const { credsValidator } = require('../validators');
+const { spotifyClient } = require('../spotify/spotify.utils');
+
+const argsWarden = new ArgsWarden([
+  ['credsPayload', credsValidator],
+  ['artistId'],
+]);
+
+const spotifyArtistGetSingle = async (
+  credsPayload,
+  artistId,
+  {
+    fetchClient = spotifyClient,
+  } = {},
+) => {
+  const response = await fetchClient.fetch({
+    context: { credsPayload },
+    requestPayload: {
+      method: 'get',
+      url: `/artists/${ artistId }`,
+    },
+  });
+
+  const { ok, data, error } = response;
+  if (!ok) {
+    logDeep({ error });
+    return { ok: false, error };
+  }
+
+  return { ok: true, data };
+};
+
+const spotifyArtistGet = async (
+  credsPayload,
+  artistId,
+  {
+    queueRunOptions,
+    fetchClient,
+  } = {},
+) => {
+  const rejectResponse = await argsWarden.responseIfRejectingArgs({
+    credsPayload,
+    artistId,
+  });
+  if (rejectResponse) {
+    return rejectResponse;
+  }
+
+  return actionSingleOrMultiple(
+    artistId,
+    spotifyArtistGetSingle,
+    (artistIdItem) => ({
+      args: [credsPayload, artistIdItem, { fetchClient }],
+    }),
+    {
+      ...(queueRunOptions ? { queueRunOptions } : {}),
+    },
+  );
+};
+
+const funcApiConfig = {
+  argsWarden,
+};
+
+module.exports = {
+  spotifyArtistGet,
+  funcApiConfig,
+};

package/api/spotify/spotifyArtistTopTracksGet.js

@@ -0,0 +1,56 @@
+// https://developer.spotify.com/documentation/web-api/reference/get-an-artists-top-tracks
+
+const { ArgsWarden, logDeep } = require('../utils');
+const { credsValidator } = require('../validators');
+const { spotifyClient } = require('../spotify/spotify.utils');
+
+const argsWarden = new ArgsWarden([
+  ['credsPayload', credsValidator],
+  ['artistId'],
+]);
+
+const spotifyArtistTopTracksGet = async (
+  credsPayload,
+  artistId,
+  {
+    market = 'US',
+    fetchClient = spotifyClient,
+  } = {},
+) => {
+  const rejectResponse = await argsWarden.responseIfRejectingArgs({
+    credsPayload,
+    artistId,
+  });
+  if (rejectResponse) {
+    return rejectResponse;
+  }
+
+  const response = await fetchClient.fetch({
+    context: { credsPayload },
+    requestPayload: {
+      method: 'get',
+      url: `/artists/${ artistId }/top-tracks`,
+      params: { market },
+    },
+  });
+
+  const { ok, data, error } = response;
+  if (!ok) {
+    logDeep({ error });
+    return { ok: false, error };
+  }
+
+  return {
+    ok: true,
+    data: data.tracks ?? data,
+  };
+};
+
+const funcApiConfig = {
+  argsWarden,
+};
+
+module.exports = {
+  spotifyArtistTopTracksGet,
+  funcApiConfig,
+};