@youzan-cloud/zan-saas-cli 0.0.0-stage → 0.1.0-beta.3

package/src/transport/account-api.js

@@ -0,0 +1,152 @@
+'use strict';
+
+const { requestApi } = require('./api');
+
+const paths = {
+  userInfo: 'youzan.user.info.get/1.0.0',
+  shopList: 'youzan.shop.summary.list/1.0.0',
+  cloudUser: 'youzan.cloud.user.create/1.0.0',
+  shopAppInit: 'youzan.cloud.shop.app.init/1.0.0',
+  shopAppGet: 'youzan.cloud.shop.app.get/1.0.0',
+  staffStatus: 'youzan.shop.staff.status.get/1.0.0'
+};
+// Staff status of the logged-in user in a shop: 0 正常, 3 停用.
+const staffStatuses = Object.freeze({ active: 0, disabled: 3 });
+// Shop list requires business lines. Default: 微商城 10000, 教育 20000, 酒店 30000, 餐饮 50000,
+// 美业 60000, 零售 70000.
+const defaultLineOfBusinesses = Object.freeze([10000, 20000, 30000, 50000, 60000, 70000]);
+const shopRoles = Object.freeze({
+  0: '单店', 1: '总部', 2: '门店/网店', 3: '仓库', 4: '合伙人', 5: '第三方店铺', 6: '分销供货商店铺', 7: '前置仓'
+});
+
+class AccountApiError extends Error {
+  constructor(message, { httpStatus, code, traceId } = {}) {
+    super(message);
+    this.httpStatus = httpStatus;
+    this.code = code;
+    this.traceId = traceId;
+  }
+}
+
+function parse(text) {
+  try {
+    const value = JSON.parse(text);
+    return value && typeof value === 'object' && !Array.isArray(value) ? value : null;
+  } catch {
+    return null;
+  }
+}
+
+const scalar = value => (typeof value === 'string' || Number.isFinite(value) ? String(value) : undefined);
+
+function failure(path, httpStatus, body) {
+  const source = body?.gw_err_resp && typeof body.gw_err_resp === 'object' ? body.gw_err_resp : body || {};
+  const code = scalar(source.code ?? source.err_code);
+  const message = scalar(source.message ?? source.err_msg);
+  const traceId = scalar(body?.trace_id ?? source.trace_id);
+  const parts = [`HTTP ${httpStatus}`];
+  if (code !== undefined) parts.push(`code ${code}`);
+  if (message) parts.push(message);
+  if (traceId) parts.push(`trace_id ${traceId}`);
+  let hint = '';
+  if (httpStatus === 401) hint = '请执行 zan-saas auth login 重新登录。';
+  else if (httpStatus === 404 && code === '4003') {
+    hint = '请先核对 CLI 版本、ZAN_SAAS_ACCOUNT_API_BASE_URL 和服务端路由；不要反复登录或切店。';
+  }
+  return new AccountApiError(`账号接口 ${path.split('/')[0]} 调用失败：${parts.join('，')}。${hint}`,
+    { httpStatus, code, traceId });
+}
+
+// Account APIs answer with a PlainResult envelope; anything else is reported with code and trace_id.
+async function callAccountApi(path, body, env = process.env, options = {}) {
+  const response = await requestApi({ path, body }, env, { ...options, gateway: 'account' });
+  const json = parse(response.body);
+  if (!response.ok || !json || json.success !== true) throw failure(path, response.httpStatus, json);
+  return json.data;
+}
+
+// Long IDs arrive as JSON numbers or digit strings; unsafe numbers are rejected rather than rounded.
+function idString(value) {
+  if (Number.isSafeInteger(value) && value > 0) return String(value);
+  if (typeof value === 'string' && /^[1-9]\d*$/.test(value)) return value;
+  return null;
+}
+
+function protocol(path) {
+  return new AccountApiError(`账号接口 ${path.split('/')[0]} 返回了无法识别的数据。`);
+}
+
+const textOrNull = value => (typeof value === 'string' ? value : null);
+
+// Keeps the first 3 and last 4 digits; short values are fully masked.
+function maskMobile(value) {
+  if (typeof value !== 'string' || !value) return null;
+  if (value.length < 8) return '*'.repeat(value.length);
+  return `${value.slice(0, 3)}${'*'.repeat(value.length - 7)}${value.slice(-4)}`;
+}
+
+async function whoami(env = process.env) {
+  const data = await callAccountApi(paths.userInfo, {}, env);
+  const userId = idString(data?.userId);
+  if (!userId) throw protocol(paths.userInfo);
+  return {
+    userId, nickName: textOrNull(data.nickName), mobile: maskMobile(data.mobile),
+    countryCode: scalar(data.countryCode) ?? null
+  };
+}
+
+// Only HQs and single shops can be selected as a context for now.
+function orgTypeOf(shopRole) {
+  return shopRole === 1 ? 'hq' : shopRole === 0 ? 'shop' : null;
+}
+
+function shopItem(item) {
+  const kdtId = idString(item?.kdtId);
+  if (!kdtId) return null;
+  const shopRole = Number.isSafeInteger(item.shopRole) ? item.shopRole : null;
+  const lifeCycleStatus = item.lifeCycleStatus;
+  return {
+    kdtId, shopName: textOrNull(item.shopName), shopRole, orgType: orgTypeOf(shopRole),
+    lifeCycleStatus: typeof lifeCycleStatus === 'string' || Number.isSafeInteger(lifeCycleStatus)
+      ? lifeCycleStatus : null
+  };
+}
+
+async function listShops({
+  name, pageNum = 1, pageSize = 20, lineOfBusinesses = defaultLineOfBusinesses, includeKdtIds
+} = {}, env = process.env) {
+  const body = {
+    onlyShowCdpGroupShop: false, lineOfBusinesses: [...lineOfBusinesses], pageNum, pageSize,
+    ...(name ? { shopName: name } : {}),
+    ...(includeKdtIds ? { includeKdtIds: includeKdtIds.map(Number) } : {})
+  };
+  const data = await callAccountApi(paths.shopList, body, env);
+  const list = data?.data ?? [];
+  if (!data || typeof data !== 'object' || !Array.isArray(list)) throw protocol(paths.shopList);
+  const items = list.map(shopItem);
+  if (items.includes(null)) throw protocol(paths.shopList);
+  const positiveInteger = (value, fallback) => (Number.isSafeInteger(value) && value > 0 ? value : fallback);
+  return {
+    total: Number.isSafeInteger(data.total) && data.total >= 0 ? data.total : null,
+    pageNum: positiveInteger(data.pageNum, pageNum), pageSize: positiveInteger(data.pageSize, pageSize), items
+  };
+}
+
+// The gateway injects the user from the token; null means the shop has no staff record of this user.
+async function staffStatus(kdtId, env = process.env) {
+  const data = await callAccountApi(paths.staffStatus, { kdtId: Number(kdtId) }, env);
+  if (data === undefined || data === null) return null;
+  if (typeof data !== 'object') throw protocol(paths.staffStatus);
+  return Number.isSafeInteger(data.status) ? data.status : null;
+}
+
+async function ensureCloudUser(env = process.env, { timeoutMs = 10000 } = {}) {
+  const data = await callAccountApi(paths.cloudUser, {}, env, { timeoutMs });
+  if (!data || typeof data !== 'object') throw protocol(paths.cloudUser);
+  return { userId: idString(data.userId) };
+}
+
+module.exports = {
+  AccountApiError, callAccountApi, defaultLineOfBusinesses, ensureCloudUser, listShops, maskMobile,
+  orgTypeOf, paths, shopRoles, staffStatus, staffStatuses, whoami
+};

package/src/transport/api.js

@@ -0,0 +1,199 @@
+'use strict';
+
+const { AsyncLocalStorage } = require('node:async_hooks');
+const { resolveAccessToken, AuthRequiredError } = require('../auth/session');
+const {
+  AuthConfigurationError, defaultAccountApiBaseUrl, defaultApiBaseUrl, insecureAllowed
+} = require('../auth/config');
+const { readContext } = require('../identity/context');
+const { contextInput } = require('../identity/context-store');
+const { runWithRequestState, beginRequest } = require('../execution/request-state');
+
+const apiPathPattern = /^\/?([a-z][a-z0-9._-]*)\/([0-9]+\.[0-9]+\.[0-9]+)$/;
+const apiSessions = new AsyncLocalStorage();
+
+function runWithApiSession(action, environment) {
+  return runWithRequestState(() =>
+    apiSessions.run({ environment, env: undefined, credential: undefined }, action));
+}
+
+function apiEnvironment() {
+  const session = apiSessions.getStore();
+  if (!session) return Object.freeze({ ...process.env });
+  session.env ||= Object.freeze({ ...(session.environment || process.env) });
+  return session.env;
+}
+
+// Business APIs select the shop per request; account APIs serve the user and send no shop.
+const gateways = {
+  business: { key: 'ZAN_SAAS_API_BASE_URL', base: defaultApiBaseUrl, label: 'API base URL', shop: true },
+  account: {
+    key: 'ZAN_SAAS_ACCOUNT_API_BASE_URL', base: defaultAccountApiBaseUrl, label: 'Account API base URL',
+    shop: false
+  }
+};
+
+class ApiConfigurationError extends Error {
+  constructor(message, reason = 'invalid_configuration') {
+    super(message);
+    this.diagnosticReason = reason;
+  }
+}
+class ApiResponseLimitError extends Error {
+  constructor(httpStatus) {
+    super('API response exceeds byte limit');
+    this.httpStatus = httpStatus;
+  }
+}
+
+async function accessToken(env) {
+  try {
+    const session = apiSessions.getStore();
+    if (session && env === session.env) {
+      session.credential ||= resolveAccessToken(env);
+      return (await session.credential).token;
+    }
+    return (await resolveAccessToken(env)).token;
+  } catch (error) {
+    if (error instanceof AuthRequiredError || error instanceof AuthConfigurationError) {
+      throw new ApiConfigurationError(error.message,
+        error instanceof AuthRequiredError ? 'missing_authentication' : 'invalid_configuration');
+    }
+    throw error;
+  }
+}
+
+// Personal tokens select the shop per request: ZAN_SAAS_KDT_ID, else the shopId of ZAN_SAAS_CONTEXT,
+// else the shop saved by `zan-saas shop use`.
+function shopHeader(env) {
+  if (env.ZAN_SAAS_KDT_ID) {
+    if (!/^[1-9]\d*$/.test(env.ZAN_SAAS_KDT_ID)) {
+      throw new ApiConfigurationError('ZAN_SAAS_KDT_ID must be a positive integer ID');
+    }
+    return env.ZAN_SAAS_KDT_ID;
+  }
+  const state = readContext(contextInput(env));
+  return state.status === 'ready' ? state.context.shopId : undefined;
+}
+
+async function endpoint(path, env, gateway = gateways.business) {
+  const base = env[gateway.key] || gateway.base;
+  const match = apiPathPattern.exec(path);
+  if (!match) throw new ApiConfigurationError('API path must be <api-name>/<version>');
+  let url;
+  try { url = new URL(base); }
+  catch { throw new ApiConfigurationError(`${gateway.label} must be a valid HTTPS URL`); }
+  const plainHttp = url.protocol === 'http:' && insecureAllowed(url, env);
+  if ((!plainHttp && url.protocol !== 'https:') || url.username ||
+      url.password || url.search || url.hash || url.origin === 'null') {
+    throw new ApiConfigurationError(`${gateway.label} must be an HTTPS URL without credentials, query or fragment`);
+  }
+  // Resolve the token last so invalid configuration never triggers a login or refresh.
+  const token = await accessToken(env);
+  const requestUrl = new URL(
+    `${url.pathname.replace(/\/$/, '')}/${match[1]}/${match[2]}`, url.origin
+  );
+  requestUrl.searchParams.set('access_token', token);
+  return { requestUrl, token };
+}
+
+async function requestApi({ path, body }, env = apiEnvironment(), options = {}) {
+  const target = gateways[options.gateway || 'business'];
+  if (!target) throw new ApiConfigurationError(`Unknown API gateway: ${options.gateway}`);
+  const kdtId = target.shop ? shopHeader(env) : undefined;
+  const send = () => sendApi(path, body, env, target, kdtId, options);
+  const response = await send();
+  if (!kdtId || env.ZAN_SAAS_SHOP_APP_INIT === '0' || options.shopApp === false) return response;
+  // Loaded lazily: shop-app calls the account gateway through this module.
+  const shopApp = require('./shop-app');
+  if (!shopApp.isNoAppResponse(response)) return response;
+  return shopApp.recoverNoApp(kdtId, env, send, response, options.shopApp);
+}
+
+async function sendApi(path, body, env, target, kdtId, { onRequest, maxResponseBytes, timeoutMs = 10000 }) {
+  const { requestUrl, token } = await endpoint(path, env, target);
+  const encodedBody = JSON.stringify(body);
+  const signal = AbortSignal.timeout(timeoutMs);
+  let response;
+  if (onRequest) onRequest();
+  const finish = beginRequest();
+  try {
+    response = await fetch(requestUrl, {
+      method: 'POST',
+      headers: {
+        'content-type': 'application/json',
+        ...(kdtId ? { 'youzanyun-kdtid': kdtId } : {})
+      },
+      body: encodedBody,
+      redirect: 'manual',
+      signal
+    });
+  } catch {
+    finish?.('unknown');
+    throw new Error('API request failed or timed out; delivery status is unknown');
+  }
+  let text;
+  let responseBytes;
+  try {
+    const result = await readResponseBody(response, maxResponseBytes);
+    text = result.text;
+    responseBytes = result.responseBytes;
+  } catch (error) {
+    finish?.(error instanceof ApiResponseLimitError ? 'sent' : 'unknown');
+    if (error instanceof ApiResponseLimitError) throw error;
+    throw new Error('API response was interrupted; request outcome is unknown');
+  }
+  finish?.('sent');
+  // Never return the credential, even if an upstream response echoes it.
+  const redacted = text.replaceAll(token, '[REDACTED]')
+    .replaceAll(encodeURIComponent(token), '[REDACTED]')
+    .replaceAll(requestUrl.searchParams.toString().slice('access_token='.length), '[REDACTED]');
+  return { httpStatus: response.status, ok: response.ok, body: redacted,
+    responseBytes: responseBytes ?? Buffer.byteLength(text, 'utf8') };
+}
+
+async function readResponseBody(response, maxResponseBytes) {
+  if (maxResponseBytes === undefined) {
+    const text = await response.text();
+    return { text, responseBytes: Buffer.byteLength(text, 'utf8') };
+  }
+  const limit = maxResponseBytes();
+  // A response with a trustworthy, uncompressed Content-Length can be
+  // rejected before reading a large body. This keeps the byte-budget failure
+  // deterministic even when the producer is slow or the body is much larger
+  // than the command limit.
+  const contentLength = response.headers?.get('content-length');
+  const contentEncoding = response.headers?.get('content-encoding');
+  if (!contentEncoding && /^\d+$/.test(contentLength || '') &&
+      Number(contentLength) > limit) {
+    throw new ApiResponseLimitError(response.status);
+  }
+  const reader = response.body?.getReader();
+  const chunks = [];
+  let bytes = 0;
+  if (reader) {
+    try {
+      while (true) {
+        const { done, value } = await reader.read();
+        if (done) break;
+        bytes += value.byteLength;
+        if (bytes > limit) {
+          try { await reader.cancel(); } catch {}
+          throw new ApiResponseLimitError(response.status);
+        }
+        chunks.push(value);
+      }
+    } finally { reader.releaseLock(); }
+  }
+  return { text: Buffer.concat(chunks, bytes).toString('utf8'), responseBytes: bytes };
+}
+
+async function snapshotApiEnvironment(env = apiEnvironment(), kdtId) {
+  const { token } = await endpoint('youzan.shop.basic.get/3.0.0', env);
+  return Object.freeze({ ...env, ZAN_SAAS_USER_ACCESS_TOKEN: token, ZAN_SAAS_KDT_ID: String(kdtId) });
+}
+
+module.exports = {
+  requestApi, snapshotApiEnvironment, runWithApiSession, ApiConfigurationError,
+  ApiResponseLimitError, readResponseBody
+};

package/src/transport/shop-app.js

@@ -0,0 +1,63 @@
+'use strict';
+
+const { callAccountApi, paths } = require('./account-api');
+
+// The business gateway answers 1106 when the selected shop has no usable app. The request never
+// reached the API, so it is safe to send again once the app is ready.
+const noAppCode = '1106';
+// CloudAppStateEnums: only 2 is ready; 4, 5 and 6 never become ready without a person stepping in.
+const appStates = Object.freeze({ 1: '审核中', 2: '已创建', 3: '初始化中', 4: '初始化失败', 5: '审核驳回', 6: '已删除' });
+const readyState = 2;
+const finalStates = new Set([4, 5, 6]);
+const defaultPolicy = Object.freeze({ attempts: 10, intervalMs: 3000, initTimeoutMs: 20000, queryTimeoutMs: 10000 });
+
+function isNoAppResponse(response) {
+  let json;
+  try { json = JSON.parse(response.body); } catch { return false; }
+  if (!json || typeof json !== 'object') return false;
+  const source = json.gw_err_resp && typeof json.gw_err_resp === 'object' ? json.gw_err_resp : json;
+  return String(source.code ?? source.err_code) === noAppCode;
+}
+
+const stateText = app => (app ? `应用 ${app.appId} ${appStates[app.appState] || `状态 ${app.appState}`}` : '应用尚未生成');
+const sleepFor = ms => new Promise(resolve => setTimeout(resolve, ms));
+
+// Initializes the shop app once, polls until it is ready and resends the request. Any failure returns
+// the last 1106 response so callers report it as usual; the reason goes to stderr.
+async function recoverNoApp(kdtId, env, resend, firstResponse, {
+  attempts = defaultPolicy.attempts, intervalMs = defaultPolicy.intervalMs,
+  initTimeoutMs = defaultPolicy.initTimeoutMs, queryTimeoutMs = defaultPolicy.queryTimeoutMs,
+  notify = message => process.stderr.write(`${message}\n`), sleep = sleepFor
+} = {}) {
+  notify(`店铺 ${kdtId} 下没有可用的应用，正在初始化。`);
+  try {
+    await callAccountApi(paths.shopAppInit, { kdtId: Number(kdtId) }, env, { timeoutMs: initTimeoutMs });
+  } catch (error) {
+    notify(`应用初始化失败：${error.message}`);
+    return firstResponse;
+  }
+  let last = firstResponse;
+  let app = null;
+  for (let attempt = 1; attempt <= attempts; attempt += 1) {
+    await sleep(intervalMs);
+    try {
+      app = await callAccountApi(paths.shopAppGet, { kdtId: Number(kdtId) }, env, { timeoutMs: queryTimeoutMs });
+    } catch (error) {
+      notify(`查询应用状态失败：${error.message}`);
+      return last;
+    }
+    if (app && finalStates.has(app.appState)) {
+      notify(`店铺 ${kdtId} 的${stateText(app)}，需要到有赞云控制台处理后重试。`);
+      return last;
+    }
+    if (app && app.appState === readyState) {
+      last = await resend();
+      if (!isNoAppResponse(last)) return last;
+    }
+  }
+  notify(`店铺 ${kdtId} 的应用还没生效：已查询 ${attempts} 次（约 ${Math.round(attempts * intervalMs / 1000)} 秒），` +
+    `${stateText(app)}。稍后重试；有容器应用要等审核通过。`);
+  return last;
+}
+
+module.exports = { appStates, defaultPolicy, isNoAppResponse, noAppCode, recoverNoApp };