@blod-nm/user-kit 0.1.0 → 0.1.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blod-nm/user-kit",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "private": false,
   "type": "module",
   "description": "CloudBase user-center kit: auth (wechat code / unionid / password / sms / email / signup) + crm_user_detail archive on @blod-nm/base-cb.",

package/src/auth.js

@@ -36,6 +36,7 @@
 import cloudbase from '@cloudbase/node-sdk'
 import { code2Session as wxCode2Session } from './wechat.js'
 import { decodeJWT, throwGatewayError, makeGateway, uidFromToken } from './user.js'
+import { withSchemas } from './schemas.js'
 
 export { decodeJWT }   // 供消费方/测试从包主入口取（真身在 user.js）
 
@@ -115,7 +116,7 @@ export function createAuthAbilities(cfg, kit) {
     return { ...payload, uid }
   }
 
-  return [
+  return withSchemas([
     ['auth.sendVerification', { describe: '发验证码（phone/email 二选一）：POST /auth/v1/verification，网关原样（含 verification_token）', run: async (args = {}) => {
       const body = {}
       for (const k of ['phone', 'email', 'email_redirect_to']) if (args[k] !== undefined) body[k] = args[k]
@@ -203,5 +204,5 @@ export function createAuthAbilities(cfg, kit) {
       try { res = await refreshTokenRequest({ grant_type: 'refresh_token', refresh_token, client_id: cfg.envId }) } catch { throw err(502, '令牌刷新请求失败') }
       return { access_token: res.access_token, refresh_token: res.refresh_token, expires_in: res.expires_in }
     } }],
-  ]
+  ])
 }

package/src/schemas.js

@@ -0,0 +1,244 @@
+/**
+  schemas.js — 能力面元数据（纯数据 · 纯对象 JSON Schema，不引 zod）
+
+  职责: 23 条 user-kit 能力的 title / inputSchema / outputSchema / MCP annotations。
+        能力实现（auth.js / user.js）只负责 run；约束集中在这里，挂 MCP 时原样透传。
+
+  取用: withSchemas([[key, ability], ...])
+
+  必填约定:
+    · required 列出的字段缺一即 400（实现里已有同名校验）
+    · 二选一用 anyOf（signup: phone_number/email；sendVerification: phone/email）
+    · 可选字段在 description 里写明「可选」
+    · 本地/自定义链路 additionalProperties:false（不接受多余参数）；网关透传类保持开放
+*/
+const str = (description, extra = {}) => ({ type: 'string', description, ...extra })
+const obj = (properties = {}, { required = [], anyOf, additionalProperties = true } = {}) => ({
+  type: 'object',
+  properties,
+  ...(required.length ? { required } : {}),
+  ...(anyOf ? { anyOf } : {}),
+  additionalProperties,
+})
+const tokens = {
+  access_token: str('访问令牌（必返）'),
+  refresh_token: str('刷新令牌（必返）'),
+  expires_in: { type: 'number', description: '有效期秒数（必返）' },
+}
+const tokenOut = { type: 'object', properties: { ...tokens }, required: ['access_token', 'refresh_token', 'expires_in'] }
+const tokenIn = obj({ access_token: str('用户访问令牌（必填，Bearer）') }, { required: ['access_token'], additionalProperties: false })
+
+export const SCHEMAS = {
+  /* ---------- auth：自定义登录 ---------- */
+  'auth.loginByWxcode': {
+    title: '微信小程序登录',
+    inputSchema: obj({ code: str('wx.login 得到的 code（必填）') }, { required: ['code'], additionalProperties: false }),
+    outputSchema: obj({
+      uid: str('唯一用户 id（必返）'),
+      openid: str('微信 openid（必返）'),
+      unionid: { type: ['string', 'null'], description: '微信 unionid，可能为 null（必返）' },
+      ...tokens,
+      config: { type: 'object', description: 'prefix_config（必返，客户端强依赖）' },
+    }, { required: ['uid', 'openid', 'unionid', 'access_token', 'refresh_token', 'expires_in', 'config'], additionalProperties: false }),
+    annotations: { openWorldHint: true },
+  },
+  'auth.loginByUnionid': {
+    title: '唯一 id 登录',
+    inputSchema: obj({ unionid: str('调用方唯一用户 id（必填）') }, { required: ['unionid'], additionalProperties: false }),
+    outputSchema: obj({
+      uid: str('唯一用户 id（必返）'),
+      unionid: str('唯一用户 id（必返）'),
+      ...tokens,
+    }, { required: ['uid', 'unionid', 'access_token', 'refresh_token', 'expires_in'], additionalProperties: false }),
+    annotations: { openWorldHint: true },
+  },
+
+  /* ---------- auth：透传登录 ---------- */
+  'auth.loginByPassword': {
+    title: '账号密码登录',
+    inputSchema: obj({ username: str('用户名（必填）'), password: str('密码（必填）') }, { required: ['username', 'password'] }),
+    outputSchema: obj({ uid: str('唯一用户 id（必返）'), access_token: str('访问令牌（必返）') }, { required: ['uid', 'access_token'] }),
+    annotations: { openWorldHint: true },
+  },
+  'auth.loginBySms': {
+    title: '短信验证码登录',
+    inputSchema: obj({ verification_token: str('verifyCode 得到的令牌（必填）') }, { required: ['verification_token'] }),
+    outputSchema: obj({ uid: str('唯一用户 id（必返）'), access_token: str('访问令牌（必返）') }, { required: ['uid', 'access_token'] }),
+    annotations: { openWorldHint: true },
+  },
+  'auth.loginByEmail': {
+    title: '邮箱验证码登录',
+    inputSchema: obj({ verification_token: str('verifyCode 得到的令牌（必填）') }, { required: ['verification_token'] }),
+    outputSchema: obj({ uid: str('唯一用户 id（必返）'), access_token: str('访问令牌（必返）') }, { required: ['uid', 'access_token'] }),
+    annotations: { openWorldHint: true },
+  },
+  'auth.signup': {
+    title: '注册',
+    inputSchema: obj({
+      phone_number: str('手机号（与 email 二选一）'),
+      email: str('邮箱（与 phone_number 二选一）'),
+      verification_token: str('验证码令牌（必填）'),
+      username: str('用户名（可选）'),
+      password: str('密码（可选）'),
+    }, {
+      required: ['verification_token'],
+      anyOf: [{ required: ['phone_number'] }, { required: ['email'] }],
+    }),
+    outputSchema: obj({ uid: str('唯一用户 id（必返）'), access_token: str('访问令牌（必返）') }, { required: ['uid', 'access_token'] }),
+    annotations: { openWorldHint: true },
+  },
+
+  /* ---------- auth：验证码 ---------- */
+  'auth.sendVerification': {
+    title: '发送验证码',
+    inputSchema: obj({
+      phone: str('手机号（与 email 二选一）'),
+      email: str('邮箱（与 phone 二选一）'),
+      email_redirect_to: str('Magic Link 跳转地址（可选，仅邮箱）'),
+    }, { anyOf: [{ required: ['phone'] }, { required: ['email'] }] }),
+    outputSchema: obj({ verification_id: str('验证码会话 id（必返）') }, { required: ['verification_id'] }),
+  },
+  'auth.sendSmsCode': {
+    title: '发送短信验证码',
+    inputSchema: obj({ phone: str('手机号（必填）') }, { required: ['phone'], additionalProperties: false }),
+    outputSchema: obj({ verification_id: str('验证码会话 id（必返）') }, { required: ['verification_id'] }),
+  },
+  'auth.sendEmailCode': {
+    title: '发送邮箱验证码',
+    inputSchema: obj({ email: str('邮箱（必填）') }, { required: ['email'], additionalProperties: false }),
+    outputSchema: obj({ verification_id: str('验证码会话 id（必返）') }, { required: ['verification_id'] }),
+  },
+  'auth.verifyCode': {
+    title: '校验验证码',
+    inputSchema: obj({
+      verification_id: str('验证码会话 id（必填）'),
+      verification_code: str('用户输入的验证码（必填）'),
+    }, { required: ['verification_id', 'verification_code'], additionalProperties: false }),
+    outputSchema: obj({ verification_token: str('验证码令牌（必返）') }, { required: ['verification_token'] }),
+  },
+
+  /* ---------- auth：会话 ---------- */
+  'auth.reauthenticate': {
+    title: '敏感操作二次验证',
+    inputSchema: obj({
+      access_token: str('用户访问令牌（必填）'),
+      verify_opt: { type: 'string', enum: ['phone_code', 'email_code'], description: '验证方式（必填）' },
+    }, { required: ['access_token', 'verify_opt'], additionalProperties: false }),
+    outputSchema: obj({ verification_id: str('验证码会话 id（必返）') }),
+  },
+  'auth.introspect': {
+    title: '校验令牌',
+    inputSchema: tokenIn,
+    outputSchema: obj({ sub: str('令牌对应的用户 id'), active: { type: 'boolean', description: '是否有效' } }),
+    annotations: { readOnlyHint: true, openWorldHint: true },
+  },
+  'auth.refresh': {
+    title: '刷新令牌',
+    inputSchema: obj({ refresh_token: str('刷新令牌（必填）') }, { required: ['refresh_token'], additionalProperties: false }),
+    outputSchema: tokenOut,
+  },
+  'auth.signOut': {
+    title: '退出登录',
+    inputSchema: obj({
+      access_token: str('用户访问令牌（必填）'),
+      client_id: str('客户端 id（可选，默认环境 id）'),
+      x_device_id: str('设备 id（可选）'),
+    }, { required: ['access_token'] }),
+    outputSchema: { type: 'object', description: '网关响应（通常为空对象）' },
+    annotations: { destructiveHint: true },
+  },
+
+  /* ---------- user：本地档案 ---------- */
+  'user.upsert': {
+    title: '建档 / 合并档案',
+    inputSchema: obj({
+      uid: str('唯一用户 id（必填，≤128 字符）'),
+      profile: { type: 'object', description: '要合并进档案 profile 段的字段（可选）' },
+      env: str('建档环境标签（可选，缺省 prod）'),
+    }, { required: ['uid'], additionalProperties: false }),
+    outputSchema: obj({ id: str('档案行 id'), data: { type: 'object', description: '档案 data 段' } }, { additionalProperties: false }),
+  },
+  'user.get': {
+    title: '读取档案',
+    inputSchema: obj({ uid: str('唯一用户 id（必填）') }, { required: ['uid'], additionalProperties: false }),
+    outputSchema: {
+      type: ['object', 'null'],
+      description: '档案行；不存在时为 null',
+      properties: { id: str('档案行 id'), data: { type: 'object' }, status: str('状态'), deleted_at: { type: ['string', 'null'] } },
+    },
+    annotations: { readOnlyHint: true },
+  },
+  'user.patchProfile': {
+    title: '局部更新档案',
+    inputSchema: obj({
+      uid: str('唯一用户 id（必填）'),
+      patch: { type: 'object', description: '要浅合并进 profile 的字段（必填）' },
+    }, { required: ['uid', 'patch'], additionalProperties: false }),
+    outputSchema: obj({ section: { type: ['object', 'null'], description: '合并后的 profile 段' } }),
+  },
+  'user.schemaStatus': {
+    title: '档案表状态',
+    inputSchema: obj({}, { required: [], additionalProperties: false }),
+    outputSchema: obj({
+      table: { type: 'boolean', description: '表是否存在' },
+      primaryKey: { type: 'boolean', description: '主键是否存在' },
+      indexes: { type: 'object', description: '四个索引的存在性' },
+    }, { required: ['table', 'primaryKey', 'indexes'], additionalProperties: false }),
+    annotations: { readOnlyHint: true },
+  },
+  'user.ensureSchema': {
+    title: '初始化档案表',
+    inputSchema: obj({}, { required: [], additionalProperties: false }),
+    outputSchema: obj({
+      table: { type: 'string', enum: ['created', 'exists'], description: '本次建表结果' },
+      indexes: { type: 'object', description: '{ created: string[], existing: string[] }' },
+      status: { type: 'object', description: '执行后的探测结果' },
+    }, { required: ['table', 'indexes', 'status'], additionalProperties: false }),
+    annotations: { readOnlyHint: true, idempotentHint: true },
+  },
+
+  /* ---------- user：用户令牌面（网关透传） ---------- */
+  'user.me': {
+    title: '当前用户',
+    inputSchema: tokenIn,
+    outputSchema: { type: 'object', description: '网关用户信息（原样）' },
+    annotations: { readOnlyHint: true },
+  },
+  'user.updateBasic': {
+    title: '修改资料（含手机号/邮箱）',
+    inputSchema: obj({
+      access_token: str('用户访问令牌（必填）'),
+      nickname: str('昵称（可选）'),
+      username: str('用户名（可选）'),
+      phone: str('手机号（可选，修改需验证码）'),
+      email: str('邮箱（可选，修改需验证码）'),
+      avatar_url: str('头像 URL（可选）'),
+      gender: { type: 'string', enum: ['MALE', 'FEMALE'], description: '性别（可选）' },
+      description: str('个人简介（可选）'),
+      verification_token: str('手机号/邮箱变更的验证码令牌（可选，改手机/邮箱时需要）'),
+    }, { required: ['access_token'] }),
+    outputSchema: { type: 'object', description: '网关响应（原样）' },
+  },
+  'user.changePassword': {
+    title: '修改密码',
+    inputSchema: obj({
+      access_token: str('用户访问令牌（必填）'),
+      password: str('新密码（必填）'),
+      verification_token: str('二次验证令牌（可选，按网关要求）'),
+    }, { required: ['access_token', 'password'] }),
+    outputSchema: { type: 'object', description: '网关响应（通常为空对象）' },
+    annotations: { destructiveHint: true },
+  },
+  'user.deleteMe': {
+    title: '注销账号',
+    inputSchema: obj({
+      access_token: str('用户访问令牌（必填）'),
+      verification_token: str('二次验证令牌（可选，按网关要求）'),
+    }, { required: ['access_token'] }),
+    outputSchema: { type: 'object', description: '网关响应（通常为空对象）' },
+    annotations: { destructiveHint: true },
+  },
+}
+
+/** 把元数据合并进 [key, ability] 列表（能力对象原样保留 describe/run） */
+export const withSchemas = entries => entries.map(([key, ability]) => [key, { ...ability, ...(SCHEMAS[key] ?? {}) }])

package/src/user.js

@@ -26,6 +26,8 @@
  * 下期留白（不实现）：user.updateSection 旧接口（patchProfile 取代）/ user.bindPhone（crm_cache access_token）。
  */
 
+import { withSchemas } from './schemas.js'
+
 const DEFAULT_DOMAIN = 'api.tcloudbasegateway.com'
 
 /* —— 共用件：JWT 不验签解码 / token 身份硬规则 / 网关错误透传 / gateway 注入缺省 —— */
@@ -143,7 +145,7 @@ export function createUserAbilities(cfg, kit) {
     return { table: !!t[0]?.exists, indexes: Object.fromEntries(INDEX_ORDER.map(n => [n, names.has(n)])), primaryKey: k.length > 0 }
   }
 
-  return [
+  return withSchemas([
     /* 建档面（本地 pg） */
     ['user.upsert', { describe: '建档/刷 updated_at（crm_user_detail；写走 cloudbase_postgres）', run: async (args = {}) => {
       const { uid, profile, env } = args
@@ -215,5 +217,5 @@ export function createUserAbilities(cfg, kit) {
       }
       return { table: before.table ? 'exists' : 'created', indexes: { created: missing, existing: INDEX_ORDER.filter(n => !missing.includes(n)) }, status: await probe() }
     } }],
-  ]
+  ])
 }