@foxtware/mineral 0.1.36 → 0.1.37

package/api/snowflake/snowflakeGet.js

@@ -0,0 +1,153 @@
+// https://docs.snowflake.com/en/developer-guide/snowflake-rest-api
+// REST list endpoints paginate with showLimit + fromName (last item name).
+
+const { ArgsWarden, Getter } = require('../utils');
+const { credsValidator } = require('../validators');
+const { snowflakeClient } = require('../snowflake/snowflake.utils');
+const {
+  DEFAULT_SHOW_LIMIT,
+  MAX_SHOW_LIMIT,
+} = require('../snowflake/snowflake.constants');
+
+const argsWarden = new ArgsWarden([
+  ['credsPayload', credsValidator],
+  ['url'],
+]);
+
+const digResults = (data) => {
+  if (Array.isArray(data)) {
+    return data;
+  }
+  if (Array.isArray(data?.data)) {
+    return data.data;
+  }
+  if (Array.isArray(data?.result)) {
+    return data.result;
+  }
+  return [];
+};
+
+const snowflakeGetPacket = async (
+  credsPayload,
+  url,
+  {
+    params,
+    showLimit = DEFAULT_SHOW_LIMIT,
+    fetchClient = snowflakeClient,
+  } = {},
+) => {
+  return fetchClient.fetch({
+    requestPayload: {
+      method: 'get',
+      url,
+      params: {
+        showLimit: Math.min(showLimit, MAX_SHOW_LIMIT),
+        ...params,
+      },
+    },
+    context: {
+      credsPayload,
+    },
+  });
+};
+
+const snowflakeGetPaginator = async (currentParams, response) => {
+  if (!response?.ok) {
+    return [true];
+  }
+
+  const { args, options } = currentParams;
+  const {
+    params = {},
+    showLimit = DEFAULT_SHOW_LIMIT,
+  } = options;
+
+  const items = digResults(response.data);
+  const limit = Number(params.showLimit ?? showLimit);
+
+  if (!items.length || items.length < limit) {
+    return [true];
+  }
+
+  const last = items[items.length - 1];
+  const lastName = last?.name;
+  if (!lastName) {
+    return [true];
+  }
+
+  return [false, {
+    args,
+    options: {
+      ...options,
+      params: {
+        ...params,
+        showLimit: limit,
+        fromName: lastName,
+      },
+    },
+  }];
+};
+
+const snowflakeGet = async (
+  returnGetter,
+
+  credsPayload,
+  url,
+  {
+    params,
+    showLimit = DEFAULT_SHOW_LIMIT,
+    fetchClient,
+    ...getterOptions
+  } = {},
+) => {
+  const rejectResponse = await argsWarden.responseIfRejectingArgs({
+    credsPayload,
+    url,
+  });
+  if (rejectResponse) {
+    return rejectResponse;
+  }
+
+  const getter = new Getter(
+    {
+      args: [credsPayload, url],
+      options: {
+        params,
+        showLimit,
+        fetchClient,
+      },
+    },
+    {
+      func: snowflakeGetPacket,
+      digester: (response) => {
+        if (!response?.ok) {
+          return [];
+        }
+        return digResults(response.data);
+      },
+      paginator: snowflakeGetPaginator,
+      ...getterOptions,
+    },
+  );
+
+  if (returnGetter) {
+    return getter;
+  }
+
+  const data = await getter.run({ returnAll: true });
+
+  return {
+    ok: true,
+    data,
+  };
+};
+
+const funcApiConfig = {
+  argsWarden,
+};
+
+module.exports = {
+  snowflakeGet: (...args) => snowflakeGet(false, ...args),
+  snowflakeGetter: (...args) => snowflakeGet(true, ...args),
+  funcApiConfig,
+};

package/api/snowflake/snowflakeIntegrationsGet.js

@@ -0,0 +1,59 @@
+// https://docs.snowflake.com/en/developer-guide/snowflake-rest-api/reference/api-integration
+// Named IntegrationsGet (not ApiIntegrations) to match bedrock / avoid awkward export names.
+
+const { ArgsWarden } = require('../utils');
+const { credsValidator } = require('../validators');
+const {
+  snowflakeGet,
+  snowflakeGetter,
+} = require('../snowflake/snowflakeGet');
+const {
+  REST_API_VERSION,
+  DEFAULT_SHOW_LIMIT,
+} = require('../snowflake/snowflake.constants');
+
+const argsWarden = new ArgsWarden([
+  ['credsPayload', credsValidator],
+]);
+
+const snowflakeIntegrationsGetImpl = async (
+  returnGetter,
+  credsPayload,
+  {
+    like,
+    showLimit = DEFAULT_SHOW_LIMIT,
+    fromName,
+    apiVersion = REST_API_VERSION,
+    fetchClient,
+    ...getterOptions
+  } = {},
+) => {
+  const rejectResponse = await argsWarden.responseIfRejectingArgs({
+    credsPayload,
+  });
+  if (rejectResponse) {
+    return rejectResponse;
+  }
+
+  const method = returnGetter ? snowflakeGetter : snowflakeGet;
+
+  return method(credsPayload, `/api/${ apiVersion }/api-integrations`, {
+    params: {
+      ...(like !== undefined && { like }),
+      ...(fromName !== undefined && { fromName }),
+    },
+    showLimit,
+    fetchClient,
+    ...getterOptions,
+  });
+};
+
+const funcApiConfig = {
+  argsWarden,
+};
+
+module.exports = {
+  snowflakeIntegrationsGet: (...args) => snowflakeIntegrationsGetImpl(false, ...args),
+  snowflakeIntegrationsGetter: (...args) => snowflakeIntegrationsGetImpl(true, ...args),
+  funcApiConfig,
+};

package/api/snowflake/snowflakeQuery.js

@@ -0,0 +1,227 @@
+// https://docs.snowflake.com/en/developer-guide/sql-api/handling-responses
+// Convenience: execute SQL, poll until done, optionally fetch all partitions,
+// and return rows as objects keyed by column name.
+
+const { ArgsWarden, logDeep, wait } = require('../utils');
+const { credsValidator } = require('../validators');
+const {
+  snowflakeClient,
+  mapRows,
+} = require('../snowflake/snowflake.utils');
+const {
+  DEFAULT_POLL_INTERVAL_MS,
+  DEFAULT_POLL_MAX_ATTEMPTS,
+} = require('../snowflake/snowflake.constants');
+const { snowflakeStatementExecute } = require('../snowflake/snowflakeStatementExecute');
+const { snowflakeStatementGet } = require('../snowflake/snowflakeStatementGet');
+
+const argsWarden = new ArgsWarden([
+  ['credsPayload', credsValidator],
+  ['statement'],
+]);
+
+const isRunningStatus = (payload) => {
+  // 202-style status objects expose statementHandle without resultSetMetaData.data complete.
+  if (!payload) {
+    return false;
+  }
+  if (payload.statementStatusUrl && !payload.resultSetMetaData) {
+    return true;
+  }
+  // code 090001 is success; running states use other codes with message.
+  const message = (payload.message || '').toLowerCase();
+  if (message.includes('asynchronous') || message.includes('in progress')) {
+    return true;
+  }
+  return false;
+};
+
+const collectAllPartitions = async (
+  credsPayload,
+  statementHandle,
+  firstResult,
+  {
+    fetchClient,
+  } = {},
+) => {
+  const partitionInfo = firstResult?.resultSetMetaData?.partitionInfo ?? [];
+  const allData = [...(firstResult.data || [])];
+
+  // partition 0 is already in firstResult; fetch 1..n-1
+  for (let i = 1; i < partitionInfo.length; i += 1) {
+    const partResponse = await snowflakeStatementGet(
+      credsPayload,
+      statementHandle,
+      {
+        partition: i,
+        fetchClient,
+      },
+    );
+    if (!partResponse.ok) {
+      return partResponse;
+    }
+    allData.push(...(partResponse.data?.data || []));
+  }
+
+  return {
+    ok: true,
+    data: {
+      ...firstResult,
+      data: allData,
+    },
+  };
+};
+
+const snowflakeQuery = async (
+  credsPayload,
+  statement,
+  {
+    timeout,
+    database,
+    schema,
+    warehouse,
+    role,
+    bindings,
+    parameters,
+    pollIntervalMs = DEFAULT_POLL_INTERVAL_MS,
+    pollMaxAttempts = DEFAULT_POLL_MAX_ATTEMPTS,
+    fetchAllPartitions = true,
+    asObjects = true,
+    fetchClient = snowflakeClient,
+  } = {},
+) => {
+  const rejectResponse = await argsWarden.responseIfRejectingArgs({
+    credsPayload,
+    statement,
+  });
+  if (rejectResponse) {
+    return rejectResponse;
+  }
+
+  let result = await snowflakeStatementExecute(credsPayload, statement, {
+    timeout,
+    database,
+    schema,
+    warehouse,
+    role,
+    bindings,
+    parameters,
+    fetchClient,
+  });
+
+  if (!result.ok) {
+    return result;
+  }
+
+  let payload = result.data;
+  let attempts = 0;
+
+  while (isRunningStatus(payload) && attempts < pollMaxAttempts) {
+    const handle = payload.statementHandle;
+    if (!handle) {
+      return {
+        ok: false,
+        error: {
+          code: 'MISSING_STATEMENT_HANDLE',
+          message: 'Async response missing statementHandle',
+          details: payload,
+        },
+      };
+    }
+
+    await wait(pollIntervalMs);
+    attempts += 1;
+
+    const statusResponse = await snowflakeStatementGet(
+      credsPayload,
+      handle,
+      { fetchClient },
+    );
+
+    if (!statusResponse.ok) {
+      // 202 may still come back as ok depending on status; if hard failure, return.
+      return statusResponse;
+    }
+
+    payload = statusResponse.data;
+  }
+
+  if (isRunningStatus(payload)) {
+    return {
+      ok: false,
+      error: {
+        code: 'STATEMENT_TIMEOUT',
+        message: `Statement still running after ${ pollMaxAttempts } polls`,
+        details: payload,
+      },
+    };
+  }
+
+  // Query failure bodies often arrive as HTTP 422 already handled by execute/get.
+  if (payload?.code && String(payload.code) !== '090001' && payload.sqlState && payload.sqlState !== '00000') {
+    // Some error payloads still return 200 with failure markers — rare.
+    if (payload.message && !payload.resultSetMetaData) {
+      logDeep({ payload });
+      return {
+        ok: false,
+        error: {
+          code: payload.code || 'STATEMENT_FAILED',
+          message: payload.message,
+          details: payload,
+        },
+      };
+    }
+  }
+
+  const handle = payload.statementHandle;
+  let finalPayload = payload;
+
+  if (fetchAllPartitions && handle) {
+    const collected = await collectAllPartitions(
+      credsPayload,
+      handle,
+      payload,
+      { fetchClient },
+    );
+    if (!collected.ok) {
+      return collected;
+    }
+    finalPayload = collected.data;
+  }
+
+  const rows = asObjects
+    ? mapRows(finalPayload)
+    : (finalPayload.data ?? []);
+
+  return {
+    ok: true,
+    data: rows,
+    meta: {
+      statementHandle: handle,
+      numRows: finalPayload?.resultSetMetaData?.numRows
+        ?? rows.length,
+      rowType: finalPayload?.resultSetMetaData?.rowType,
+      sqlState: finalPayload?.sqlState,
+      code: finalPayload?.code,
+      message: finalPayload?.message,
+    },
+  };
+};
+
+const funcApiConfig = {
+  argsWarden,
+};
+
+module.exports = {
+  snowflakeQuery,
+  funcApiConfig,
+};
+
+/*
+curl -X POST "http://localhost:8000/snowflakeQuery" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "credsPayload": { "credsPath": "snowflake" },
+    "statement": "select 1 as n, current_timestamp() as ts"
+  }'
+*/

package/api/snowflake/snowflakeSchemasGet.js

@@ -0,0 +1,69 @@
+// https://docs.snowflake.com/en/developer-guide/snowflake-rest-api/reference/schema
+
+const { ArgsWarden } = require('../utils');
+const { credsValidator } = require('../validators');
+const {
+  snowflakeGet,
+  snowflakeGetter,
+} = require('../snowflake/snowflakeGet');
+const {
+  REST_API_VERSION,
+  DEFAULT_SHOW_LIMIT,
+} = require('../snowflake/snowflake.constants');
+
+const argsWarden = new ArgsWarden([
+  ['credsPayload', credsValidator],
+  ['databaseName'],
+]);
+
+const snowflakeSchemasGetImpl = async (
+  returnGetter,
+  credsPayload,
+  databaseName,
+  {
+    like,
+    startsWith,
+    history,
+    showLimit = DEFAULT_SHOW_LIMIT,
+    fromName,
+    apiVersion = REST_API_VERSION,
+    fetchClient,
+    ...getterOptions
+  } = {},
+) => {
+  const rejectResponse = await argsWarden.responseIfRejectingArgs({
+    credsPayload,
+    databaseName,
+  });
+  if (rejectResponse) {
+    return rejectResponse;
+  }
+
+  const method = returnGetter ? snowflakeGetter : snowflakeGet;
+
+  return method(
+    credsPayload,
+    `/api/${ apiVersion }/databases/${ databaseName }/schemas`,
+    {
+      params: {
+        ...(like !== undefined && { like }),
+        ...(startsWith !== undefined && { startsWith }),
+        ...(history !== undefined && { history }),
+        ...(fromName !== undefined && { fromName }),
+      },
+      showLimit,
+      fetchClient,
+      ...getterOptions,
+    },
+  );
+};
+
+const funcApiConfig = {
+  argsWarden,
+};
+
+module.exports = {
+  snowflakeSchemasGet: (...args) => snowflakeSchemasGetImpl(false, ...args),
+  snowflakeSchemasGetter: (...args) => snowflakeSchemasGetImpl(true, ...args),
+  funcApiConfig,
+};

package/api/snowflake/snowflakeStatementCancel.js

@@ -0,0 +1,75 @@
+// https://docs.snowflake.com/en/developer-guide/sql-api/cancelling-requests
+
+const { ArgsWarden, actionSingleOrMultiple, logDeep } = require('../utils');
+const { credsValidator } = require('../validators');
+const { snowflakeClient } = require('../snowflake/snowflake.utils');
+const { SQL_API_PATH } = require('../snowflake/snowflake.constants');
+
+const argsWarden = new ArgsWarden([
+  ['credsPayload', credsValidator],
+  ['statementHandle'],
+]);
+
+const snowflakeStatementCancelSingle = async (
+  credsPayload,
+  statementHandle,
+  {
+    fetchClient = snowflakeClient,
+  } = {},
+) => {
+  const response = await fetchClient.fetch({
+    context: { credsPayload },
+    requestPayload: {
+      method: 'post',
+      url: `${ SQL_API_PATH }/${ statementHandle }/cancel`,
+    },
+  });
+
+  const { ok, data, error } = response;
+  if (!ok) {
+    logDeep({ error });
+    return { ok: false, error };
+  }
+
+  return {
+    ok: true,
+    data: data ?? null,
+  };
+};
+
+const snowflakeStatementCancel = async (
+  credsPayload,
+  statementHandle,
+  {
+    queueRunOptions,
+    fetchClient,
+  } = {},
+) => {
+  const rejectResponse = await argsWarden.responseIfRejectingArgs({
+    credsPayload,
+    statementHandle,
+  });
+  if (rejectResponse) {
+    return rejectResponse;
+  }
+
+  return actionSingleOrMultiple(
+    statementHandle,
+    snowflakeStatementCancelSingle,
+    (handleItem) => ({
+      args: [credsPayload, handleItem, { fetchClient }],
+    }),
+    {
+      ...(queueRunOptions ? { queueRunOptions } : {}),
+    },
+  );
+};
+
+const funcApiConfig = {
+  argsWarden,
+};
+
+module.exports = {
+  snowflakeStatementCancel,
+  funcApiConfig,
+};

package/api/snowflake/snowflakeStatementExecute.js

@@ -0,0 +1,105 @@
+// https://docs.snowflake.com/en/developer-guide/sql-api/submitting-requests
+
+const { randomUUID } = require('crypto');
+
+const { ArgsWarden, logDeep } = require('../utils');
+const { credsValidator } = require('../validators');
+const {
+  snowflakeClient,
+  sessionContextFromCreds,
+} = require('../snowflake/snowflake.utils');
+const {
+  SQL_API_PATH,
+  DEFAULT_STATEMENT_TIMEOUT_SECONDS,
+} = require('../snowflake/snowflake.constants');
+
+const argsWarden = new ArgsWarden([
+  ['credsPayload', credsValidator],
+  ['statement'],
+]);
+
+const snowflakeStatementExecute = async (
+  credsPayload,
+  statement,
+  {
+    timeout = DEFAULT_STATEMENT_TIMEOUT_SECONDS,
+    database,
+    schema,
+    warehouse,
+    role,
+    bindings,
+    parameters,
+    async: asAsync = false,
+    nullable,
+    requestId,
+    fetchClient = snowflakeClient,
+  } = {},
+) => {
+  const rejectResponse = await argsWarden.responseIfRejectingArgs({
+    credsPayload,
+    statement,
+  });
+  if (rejectResponse) {
+    return rejectResponse;
+  }
+
+  // resolveCreds runs in the client; session defaults come from creds when present.
+  const { credsFromPayload } = require('../utils');
+  const creds = await credsFromPayload(credsPayload);
+
+  const body = {
+    statement,
+    timeout,
+    ...sessionContextFromCreds(creds, {
+      database,
+      schema,
+      warehouse,
+      role,
+    }),
+    ...(bindings !== undefined && { bindings }),
+    ...(parameters !== undefined && { parameters }),
+  };
+
+  const response = await fetchClient.fetch({
+    context: { credsPayload },
+    requestPayload: {
+      method: 'post',
+      url: SQL_API_PATH,
+      params: {
+        requestId: requestId || randomUUID(),
+        ...(asAsync ? { async: true } : {}),
+        ...(nullable !== undefined && { nullable }),
+      },
+      body,
+    },
+  });
+
+  const { ok, data, error } = response;
+  if (!ok) {
+    logDeep({ error });
+    return { ok: false, error };
+  }
+
+  return {
+    ok: true,
+    data,
+  };
+};
+
+const funcApiConfig = {
+  argsWarden,
+};
+
+module.exports = {
+  snowflakeStatementExecute,
+  funcApiConfig,
+};
+
+/*
+curl -X POST "http://localhost:8000/snowflakeStatementExecute" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "credsPayload": { "credsPath": "snowflake" },
+    "statement": "select current_version() as version"
+  }'
+*/