@petercjl/ecom-cli 0.3.0 → 0.3.2

package/lib/sycm.mjs

@@ -2,6 +2,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import os from 'node:os';
 import crypto from 'node:crypto';
+import {fileURLToPath} from 'node:url';
 import {fail,exists,privatePath,writeNew} from './common.mjs';
 import {discover,requestInConnection,registeredReadInConnection,openBusinessPageInConnection,callMailbox,resolveContainer} from './browser.mjs';
 import {listOperations,operationRegistry,getService,validateOperationParams} from './sycm-vendor/operation-registry.mjs';
@@ -22,8 +23,42 @@ const legacyReads=[
  ['word.related','/mc/mq/mkt/keyword/relate/analysis.json',['keyWord','dateRange'],{cycleFlag:'cycle',order:'desc',orderBy:'seIpvUvHits',rankType:'related',page:1,pageSize:10,device:'0',marketVersion:'free'}],
  ['word.category','/mc/mq/mkt/keyword/cate/analysis.json',['keyWord','dateRange'],{order:'desc',orderBy:'clickHitsRatio',page:1,pageSize:10,device:'0',marketVersion:'free'}]
 ].map(([id,path,requiredParams,defaultParams])=>({id,service:'sycm',method:'GET',path,requiredParams,defaultParams,sideEffect:'none',source:'src/sycm.mjs'}));
-const allOperations=()=>[...listOperations(),...legacyReads];
+const browserOperations=()=>[...listOperations(),...legacyReads];
+const dailyTrade={
+  ...operationRegistry['shop.trade-summary'],
+  id:'shop.trade-daily',
+  browserOperation:'shop.trade-summary',
+  requiredParams:['date'],
+  defaultParams:{...operationRegistry['shop.trade-summary'].defaultParams,dateType:'recent1'},
+};
+const audienceEnvelope=JSON.parse(fs.readFileSync(fileURLToPath(new URL('./dmp-audience-dev.json',import.meta.url)),'utf8'));
+const audienceManifest=JSON.parse(audienceEnvelope.payload);
+const competitorAudience={
+  id:audienceManifest.id,service:'dmp',method:audienceManifest.method,path:audienceManifest.path,
+  requiredParams:['itemId'],defaultParams:{days:30,audienceType:'purchase',dimension:'gender'},
+  signedDevRoute:true,sideEffect:'none',
+};
+const audienceTypes={browse:['1','浏览'],favorite:['2','收藏'],cart:['3','加购'],purchase:['4','购买'],search:['5','搜索']};
+const audienceDimensions={gender:114554,age:114555,consumption:163535,city:213510,segments:266238};
+function audienceRequest(params) {
+  const {itemId,days=30,audienceType='purchase',dimension='gender'}=params;
+  if(Object.keys(params).some(key=>!['itemId','days','audienceType','dimension'].includes(key))||
+      typeof itemId!=='string'||!/^[1-9]\d{0,29}$/.test(itemId)||
+      ![7,15,30,90].includes(days)||!Object.hasOwn(audienceTypes,audienceType)||
+      !Object.hasOwn(audienceDimensions,dimension)) {
+    throw fail('INVALID_ARGUMENT','Specify itemId as digits; use days 7/15/30/90, a known audienceType and dimension');
+  }
+  const [behavior,label]=audienceTypes[audienceType];
+  const select=(optionGroupId,values,names)=>({tagId:'283736',optionGroupId,tagName:'同行宝贝行为人群',values,names});
+  return {appCode:'dmpInsight',needUnknown:true,tagId:audienceDimensions[dimension],
+    selectTagOptionSetDTO:{operator:1,selectTagOptionSetDTO:[{operator:1,selects:[
+      select(303279,itemId,itemId),select(303280,behavior,label),select(303281,String(days),'最近'+days+'天'),
+    ]}]}};
+}
+const allOperations=()=>[...browserOperations(),dailyTrade,competitorAudience];
 const resolveOperation=id=>{
+  if(id===dailyTrade.id)return dailyTrade;
+  if(id===competitorAudience.id)return competitorAudience;
   const found=legacyReads.find(x=>x.id===id)??(Object.hasOwn(operationRegistry,id)?operationRegistry[id]:null);
   if(!found)throw fail('UNKNOWN_OPERATION','Choose a registered operation from sycm operations');
   return found;
@@ -55,16 +90,20 @@ const transportFor=op=>op.method==='GET'&&getService(op.service).origin===ORIGIN
 export function operationSchema(id) {
   const op=resolveOperation(id), service=getService(op.service);
   return {...op,origin:service.origin,entryUrl:service.entryUrl,tokenStrategy:service.tokenStrategy,transport:'native-business-read',legacyTransport:transportFor(op),runtimeVerified:false,
-    minimumBrowserCapability:'businessReadProtocol=1 with matching registry hash',limits:'Credentials remain native. Per-endpoint permissions, CSRF, date semantics and service login require real validation.'};
+    minimumBrowserCapability:op.signedDevRoute?'signedBusinessRouteProtocol=1 (Ecom Dev)':'businessReadProtocol=1 with businessRouteProtocol=1 or matching legacy registry hash',limits:'Credentials remain native. Per-endpoint permissions, CSRF, date semantics and service login require real validation.'};
 }
 export function nativeRegistry() {
-  return Object.fromEntries(inventory().operations.map(op=>[op.id,{
+  return Object.fromEntries(browserOperations().map(({id})=>operationSchema(id)).map(op=>[op.id,{
     id:op.id,service:op.service,method:op.method,path:op.path,origin:op.origin,
     entryUrl:op.entryUrl,tokenStrategy:op.tokenStrategy,requiredParams:op.requiredParams,
     defaultParams:op.defaultParams??{},...(op.encoding?{encoding:op.encoding}:{}),
     ...(op.requestShape?{requestShape:op.requestShape,moduleId:op.moduleId,bizCode:op.bizCode,accessBizCode:op.accessBizCode}:{})
   }]));
 }
+function browserRoute(id) {
+  const {id: routeId, defaultParams, ...route}=nativeRegistry()[id];
+  return route;
+}
 export const nativeRegistryHash=()=>crypto.createHash('sha256').update(JSON.stringify(nativeRegistry())).digest('hex');
 export function inventory() {
   return {ok:true,schemaVersion:1,source:{package:'@petercjl/sycmcli',version:'0.4.0',license:'MIT'},
@@ -131,26 +170,59 @@ export function resolveModuleResponse(response,flows) {
 }
 export async function runRead(options,deps={}) {
   const params=paramsObject(options['params-json']),op=resolveOperation(options.operation);
-  assertPublicParams(params);validateOperationParams(op,params);
+  const browserOperation=op.browserOperation??op.id;
+  if(op.id===dailyTrade.id) {
+    const date=params.date;
+    if(typeof date!=='string'||!/^\d{4}-\d{2}-\d{2}$/.test(date)||
+        new Date(date).toJSON()?.slice(0,10)!==date||Object.hasOwn(params,'dateRange')) {
+      throw fail('INVALID_ARGUMENT','Specify one valid YYYY-MM-DD date for shop.trade-daily');
+    }
+    delete params.date;
+    params.dateRange=date+'|'+date;
+    params.dateType='recent1';
+  }
+  assertPublicParams(params);validateOperationParams(resolveOperation(browserOperation),params);
+  const signedParams=op.signedDevRoute?audienceRequest(params):null;
   if(Buffer.byteLength(JSON.stringify(params))>24576)throw fail('INVALID_ARGUMENT','Read parameters exceed the native 24 KiB limit');
   const connection=(deps.discover??discover)(options);
   let result;
-  if(connection.endpoint.businessReadProtocol===1)result=await (deps.registeredRequest??registeredReadInConnection)(connection,options,op.id,params,nativeRegistryHash());
+  if(signedParams) {
+    result=await (deps.registeredRequest??registeredReadInConnection)(
+      connection,options,op.id,signedParams,undefined,undefined,audienceEnvelope);
+  } else if(connection.endpoint.businessReadProtocol===1) {
+    const supportsRoute=connection.endpoint.businessRouteProtocol===1;
+    const effective=supportsRoute?{...op.defaultParams,...params}:params;
+    assertPublicParams(effective);
+    if(Buffer.byteLength(JSON.stringify(effective))>24576)throw fail('INVALID_ARGUMENT','Read parameters exceed the native 24 KiB limit');
+    result=await (deps.registeredRequest??registeredReadInConnection)(
+      connection,options,browserOperation,effective,supportsRoute?undefined:nativeRegistryHash(),
+      supportsRoute?browserRoute(browserOperation):undefined);
+  }
   else {
     if(transportFor(op)!=='native-session-get')throw fail('BROWSER_UPGRADE_REQUIRED','Upgrade Ecom to native business read protocol 1 for this registered service; keep the existing container login');
-    const built=buildRead(options.operation,params);
+    const built=buildRead(browserOperation,params);
     result=await (deps.request??requestInConnection)(connection,{...options,url:built.url,method:'GET'});
   }
   try {
     const data=businessResponse(result.data),flows=result.dataFlows??[];
     const expanded=op.requestShape==='alimama-dynamic-module'&&hasTemplate(data)?resolveModuleResponse(data,flows):undefined;
+    if(signedParams&&(data.info?.ok!==true||
+        !Array.isArray(data.data?.result?.chartDataFull??data.data?.chartDataFull))) {
+      throw fail('BUSINESS_RESPONSE_INVALID','DMP did not return a verified audience chart',{executed:true});
+    }
     const partial=Boolean(expanded&&hasTemplate(expanded));
     return {...result,...(flows.length?{dataFlows:sanitized(flows)}:{}),...(expanded?{resolvedResponse:expanded,completeness:{complete:!partial,scope:'registered-module-response',...(partial?{reason:'Platform data flows returned successfully but some template references have no returned value; inspect resolvedResponse and do not infer missing values.'}:{})}}:{}),operation:op.id,service:op.service,data,businessStatus:partial?'partial':'success',fetchedAt:new Date().toISOString(),dataDateVerification:'caller-must-check-requested-period-and-platform-update-time'};
   }catch(error){error.operationId=result.operationId;throw error;}
 }
 export async function openOperation(options,deps={}) {
-  const op=operationSchema(options.operation),connection=(deps.discover??discover)(options);
-  return (deps.open??openBusinessPageInConnection)(connection,options,op.id,op.entryUrl,nativeRegistryHash());
+  const op=operationSchema(options.operation);
+  if(op.signedDevRoute)throw fail('BUSINESS_PAGE_UNSUPPORTED','Signed routes support reads only');
+  const connection=(deps.discover??discover)(options);
+  const supportsRoute=connection.endpoint.businessRouteProtocol===1;
+  const browserOperation=op.browserOperation??op.id;
+  const result=await (deps.open??openBusinessPageInConnection)(connection,options,browserOperation,op.entryUrl,
+    supportsRoute?undefined:nativeRegistryHash(),supportsRoute?browserRoute(browserOperation):undefined);
+  return {...result,operation:op.id};
 }
 async function account(connection,selector) {
   const list=await callMailbox(connection,{method:'shops.list'});

package/lib/xhs-note.mjs

@@ -0,0 +1,322 @@
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import {setTimeout as pause} from 'node:timers/promises';
+import {fail, privatePath, writeNew} from './common.mjs';
+import {discover, inspectInConnection, callMailbox} from './browser.mjs';
+
+const maxImage = 10 * 1024 * 1024;
+const maxTotal = 24 * 1024 * 1024;
+const uuid = /^[0-9a-f]{8}(?:-[0-9a-f]{4}){3}-[0-9a-f]{12}$/;
+const accountPattern = /^[0-9a-f]{24}$/;
+const states = new Set(['opening','login-required','verification-required','page-changed',
+  'account-unverified','account-ready','account-mismatch','unsupported-form',
+  'uploading','upload-incomplete','form-readback-mismatch','form-not-empty','form-changed','form-ready',
+  'images-ready','review-incomplete','review-ready',
+  'submission-checking','submission-unknown','not-submitted','submitted','published']);
+export function validateNoteOptions(action, options) {
+  if (['preflight','prepare','upload','fill'].includes(action) && !options.manifest)
+    throw fail('INVALID_ARGUMENT','Specify --manifest');
+  if (action === 'preflight') return;
+  if (!options.container) throw fail('INVALID_ARGUMENT','Specify --container');
+  if (options['fixture-port'] !== undefined && (!/^\d{4,5}$/.test(options['fixture-port']) ||
+      Number(options['fixture-port']) < 1024 || Number(options['fixture-port']) > 65535))
+    throw fail('INVALID_ARGUMENT','Specify a loopback fixture port from 1024 to 65535');
+  if (['status','verify','prepare','submit','upload','fill'].includes(action) && !uuid.test(options.preparation??''))
+    throw fail('INVALID_ARGUMENT','Specify --preparation with the ID returned by open');
+  if (['prepare','submit','upload','fill'].includes(action) &&
+      (!uuid.test(options.instance??'') || !accountPattern.test(options['account-id']??'')))
+    throw fail('INVALID_ARGUMENT','Pin --instance and the verified --account-id');
+  if (['prepare','upload','fill'].includes(action)&&!/^[0-9a-f]{64}$/.test(options.digest??''))
+    throw fail('INVALID_ARGUMENT','Specify --digest from the reviewed preflight');
+  if (action==='submit'&&(!options.confirm?.startsWith(options.preparation+':') ||
+      !/^[0-9a-f]{64}$/.test(options.confirm.slice(37))))
+    throw fail('INVALID_ARGUMENT','Specify --confirm from the reviewed ready form');
+}
+const creatorUrl = 'https://creator.xiaohongshu.com/publish/publish';
+const hash = bytes => crypto.createHash('sha256').update(bytes).digest('hex');
+const invalid = message => fail('INVALID_NOTE', message, {executed:false});
+
+function writeAttempt(file, value) {
+  const fd = fs.openSync(file,'wx',0o600);
+  try {
+    fs.writeFileSync(fd,JSON.stringify(value)+'\n');
+    fs.fsyncSync(fd);
+  } finally { fs.closeSync(fd); }
+}
+
+function readBounded(file, limit) {
+  let fd;
+  try {
+    fd = fs.openSync(file, fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW | fs.constants.O_NONBLOCK);
+    const stat = fs.fstatSync(fd);
+    if (!stat.isFile() || !stat.size || stat.size > limit) throw Error();
+    const bytes = Buffer.alloc(stat.size + 1);
+    let n = 0;
+    while (n < bytes.length) {
+      const got = fs.readSync(fd, bytes, n, bytes.length - n, null);
+      if (!got) break;
+      n += got;
+    }
+    if (n !== stat.size) throw Error();
+    return bytes.subarray(0,n);
+  } catch {
+    throw invalid('Input must be a readable regular file within the size limit');
+  } finally {
+    if (fd !== undefined) fs.closeSync(fd);
+  }
+}
+
+function imageType(bytes) {
+  if (bytes.length >= 33 && bytes.subarray(0,8).equals(Buffer.from('89504e470d0a1a0a','hex')) &&
+      bytes.subarray(8,16).equals(Buffer.from('0000000d49484452','hex')) &&
+      bytes.readUInt32BE(16) > 0 && bytes.readUInt32BE(20) > 0 &&
+      bytes.subarray(-12).equals(Buffer.from('0000000049454e44ae426082','hex'))) return 'image/png';
+  if (bytes.length >= 20 && bytes[0] === 255 && bytes[1] === 216 &&
+      bytes[2] === 255 && bytes.at(-2) === 255 && bytes.at(-1) === 217) return 'image/jpeg';
+  throw invalid('Images must have PNG or JPEG signatures');
+}
+
+export function readNote(file, keepBytes = false) {
+  if (!file) throw invalid('Specify --manifest with a JSON note manifest');
+  const manifest = path.resolve(file);
+  let doc;
+  try { doc = JSON.parse(new TextDecoder('utf-8',{fatal:true}).decode(readBounded(manifest,16384))); }
+  catch { throw invalid('Expected a readable UTF-8 JSON manifest of at most 16 KiB'); }
+  if (!doc || Array.isArray(doc) || typeof doc !== 'object' ||
+      Object.keys(doc).some(k=>!['title','body','topics','images'].includes(k)))
+    throw invalid('Manifest accepts title, body, topics and ordered images');
+  const {title,body,topics=[],images} = doc;
+  if (typeof title !== 'string' || !title.trim() || title !== title.trim() || title.length > 20 || /[\r\n\x00-\x1f]/.test(title))
+    throw invalid('Title must be a single trimmed line of 1 to 20 UTF-16 units');
+  if (typeof body !== 'string' || !body.trim() || /[\x00-\x08\x0b-\x1f]/.test(body))
+    throw invalid('Body must contain text; use LF for line breaks');
+  if (!Array.isArray(topics) || topics.length > 10 || new Set(topics).size !== topics.length ||
+      topics.some(t=>typeof t !== 'string' || !/^[\p{L}\p{M}\p{N}_-]{1,30}$/u.test(t)))
+    throw invalid('Topics must be up to 10 unique plain names without # or spaces');
+  const text = body + (topics.length ? '\n\n' + topics.map(t=>'#'+t).join(' ') : '');
+  if (text.length > 1000) throw invalid('Body including topic text must fit 1000 UTF-16 units');
+  if (!Array.isArray(images) || !images.length || images.length > 18)
+    throw invalid('Provide 1 to 18 ordered images');
+  let total = 0;
+  const media = images.map((name,index)=>{
+    if (typeof name !== 'string' || !name.trim() || name.includes('\0'))
+      throw invalid('Each image must be a local file path');
+    const bytes = readBounded(path.resolve(path.dirname(manifest),name),maxImage);
+    total += bytes.length;
+    if (total > maxTotal) throw invalid('Combined images exceed the Ecom limit of 24 MiB');
+    return {index:index+1,name:path.basename(name),type:imageType(bytes),size:bytes.length,sha256:hash(bytes),...(keepBytes?{bytes}:{})};
+  });
+  if (new Set(media.map(m=>m.sha256)).size !== media.length)
+    throw invalid('Image bytes must be unique');
+  const summary = {title,body,topics,images:media.map(({bytes,...m})=>m)};
+  return {summary,text,digest:hash(JSON.stringify({title,text,images:media.map(m=>m.sha256)})),media};
+}
+
+export async function noteCommand(action, options, deps={}) {
+  if (action === 'preflight') {
+    const note = readNote(options.manifest);
+    return {ok:true,schemaVersion:1,state:'preflight-passed',manifestDigest:note.digest,
+      note:note.summary,topicMode:'literal-text',submitted:false};
+  }
+  if (!options.container) throw fail('INVALID_ARGUMENT','Specify --container');
+  const connection = (deps.discover??discover)(options);
+  const fixture = options.fixture === true || options['fixture-port'] !== undefined;
+  if (fixture && connection.channel !== 'dev')
+    throw fail('XHS_FIXTURE_DEV_REQUIRED','Loopback fixtures require an explicitly selected Ecom Dev instance');
+  const {container} = await (deps.inspect??inspectInConnection)(connection,options.container);
+  if (container.platform !== 'xiaohongshu')
+    throw fail('XHS_CONTAINER_REQUIRED','Select a Xiaohongshu account container');
+  const preparation = options.preparation;
+  const instance = {id:connection.endpoint.instanceId,channel:connection.channel};
+  const receiptPath = preparation && uuid.test(preparation)
+    ? path.join(connection.folder,preparation+'.xhs-attempt.json') : null;
+  const resultPath = receiptPath?.replace('.xhs-attempt.json','.xhs-result.json');
+  const receipt = () => {
+    if (!receiptPath) return null;
+    try {
+      privatePath(receiptPath);
+      const item = JSON.parse(fs.readFileSync(receiptPath,'utf8'));
+      if (item.containerId !== container.id || item.fixture !== fixture ||
+          item.preparationId !== preparation)
+        throw fail('XHS_PREPARATION_NOT_FOUND','Attempt belongs to a different container or fixture');
+      return item;
+    } catch (error) { if (error.code === 'ENOENT') return null; throw error; }
+  };
+  const claimPath = (accountId,digest) => path.join(connection.folder,
+    hash(JSON.stringify([container.id,fixture,accountId,digest]))+'.xhs-claim.json');
+  const alreadyClaimed = file => {
+    try {
+      privatePath(file);
+      const previous = JSON.parse(fs.readFileSync(file,'utf8'));
+      throw fail('XHS_SAME_NOTE_ATTEMPTED','This account already has a submission attempt for the same material',
+        {executed:'unknown',recovery:'xhs note status --preparation '+previous.preparationId});
+    } catch (error) { if (error.code !== 'ENOENT') throw error; }
+  };
+  const prior = action === 'status' || action === 'submit' ? receipt() : null;
+  const settled = () => {
+    if (!prior) return null;
+    try {
+      privatePath(resultPath);
+      const item = JSON.parse(fs.readFileSync(resultPath,'utf8'));
+      if (item.preparationId === preparation && item.container?.id === container.id &&
+          item.instance?.id === prior.instance.id && item.fixture === fixture) return item;
+    } catch (error) { if (error.code !== 'ENOENT') throw error; }
+    return null;
+  };
+  const recovered = () => settled() ?? ({
+    ok:true,schemaVersion:1,state:'submission-unknown',instance:prior.instance,
+    container:{id:container.id,name:container.name},preparationId:preparation,fixture,
+    accountId:prior.accountId,manifestDigest:prior.manifestDigest,
+    recovery:'Inspect the creator account’s note management page before considering another submission'
+  });
+  if (prior && action === 'submit')
+    throw fail('XHS_SUBMISSION_ALREADY_ATTEMPTED','This preparation has a saved submission attempt; use xhs note status',{executed:'unknown'});
+  if (prior && (prior.instance.id !== instance.id || settled())) return recovered();
+  const settle = (result, attempt) => {
+    if (!['published','not-submitted'].includes(result.state)) return;
+    try { writeNew(resultPath,result); } catch (error) { if (error.code !== 'EEXIST') throw error; }
+    if (result.state === 'not-submitted') {
+      const claim = claimPath(attempt.accountId,attempt.manifestDigest);
+      try {
+        privatePath(claim);
+        if (JSON.parse(fs.readFileSync(claim,'utf8')).preparationId === preparation)
+          fs.unlinkSync(claim);
+      } catch (error) { if (error.code !== 'ENOENT') throw error; }
+    }
+  };
+  if (connection.endpoint.xhsNoteProtocol !== 1)
+    throw fail('BROWSER_UPGRADE_REQUIRED','Xiaohongshu note actions require Ecom with xhsNoteProtocol 1');
+  if (['upload','fill','verify'].includes(action) && connection.endpoint.xhsNoteReviewProtocol !== 1)
+    throw fail('BROWSER_UPGRADE_REQUIRED','Split note preparation requires xhsNoteReviewProtocol 1');
+  const call = deps.call??callMailbox;
+  const native = async (verb, extra={}) => {
+    const result = await call(connection,{method:'xhs.note.'+verb,containerId:container.id,
+      ...(preparation?{preparationId:preparation}:{}),...extra},15000);
+    const data = result.noteState;
+    if (result.containerId !== container.id || result.fixture !== fixture ||
+        !uuid.test(result.preparationId??'') ||
+        (verb !== 'open' && result.preparationId !== (extra.preparationId??preparation)) ||
+        !data || !states.has(data.state) ||
+        (data.accountId !== undefined && !accountPattern.test(data.accountId)) ||
+        (data.state === 'review-ready' && (!Number.isInteger(data.imageCount) ||
+          data.imageCount < 1 || data.imageCount > 18 ||
+          data.fields?.imageCount !== data.imageCount || data.fields?.imagesMatch !== true ||
+          data.fields?.title !== 'matched' || data.fields?.body !== 'matched' ||
+          data.fields?.publishEnabled !== true)) ||
+        (data.state === 'published' && !accountPattern.test(data.noteId??'')) ||
+        (data.state === 'form-ready' && (!data.confirmation ||
+          data.confirmation !== result.preparationId+':'+data.manifestDigest ||
+          !/^[0-9a-f]{64}$/.test(data.manifestDigest??'') ||
+          !Number.isInteger(data.imageCount) || data.imageCount<1 || data.imageCount>18)))
+      throw fail('PROTOCOL_MISMATCH','Native note response did not match the selected preparation',{executed:'unknown',operationId:result.operationId});
+    return {ok:true,schemaVersion:1,...data,operationId:result.operationId,instance,
+      container:{id:container.id,name:container.name},preparationId:result.preparationId,fixture,
+      creatorUrl:fixture?null:creatorUrl,
+      ...(data.state==='published'&&!fixture?{noteUrl:'https://www.xiaohongshu.com/explore/'+data.noteId}:{})};
+  };
+  const until = async (current, waiting, ms) => {
+    const end = Date.now()+ms;
+    while (waiting.includes(current.state) && Date.now()<end) {
+      await (deps.pause??pause)(500);
+      current = await native('status',{preparationId:current.preparationId});
+    }
+    return current;
+  };
+  if (action === 'open') {
+    // Creator identity can arrive before the upload controls render.
+    return until(await native('open',fixture?{fixturePort:Number(options['fixture-port'])}:{}),['opening','unsupported-form'],15000);
+  }
+  if (action === 'verify') {
+    const result = await until(await native('status'),['opening'],9000);
+    const fields = result.fields;
+    if (!['images-ready','review-incomplete','review-ready'].includes(result.state) || !fields)
+      return result;
+    const contentVerified = fields.title === 'matched' && fields.body === 'matched' &&
+      fields.imagesMatch === true && fields.imageCount === result.imageCount &&
+      Number.isInteger(result.imageCount) && result.imageCount >= 1 && result.imageCount <= 18;
+    return {...result,state:contentVerified?'content-verified':'review-incomplete',
+      contentVerified,publishControl:fields.publishEnabled?'enabled':'unconfirmed'};
+  }
+  if (action === 'status') {
+    try {
+      const result = await native('status');
+      if (prior) settle(result,prior);
+      return prior && !['published','submitted','not-submitted','submission-checking','submission-unknown'].includes(result.state) ? recovered() : result;
+    } catch (error) {
+      if (prior && ['XHS_PREPARATION_NOT_FOUND','XHS_PREPARATION_EXPIRED','OPERATION_TIMEOUT','INSTANCE_CHANGED'].includes(error.code))
+        return recovered();
+      throw error;
+    }
+  }
+  const state = await until(await native('status'),['opening'],9000);
+  const accountId = options['account-id'];
+  if (state.accountId !== accountId)
+    throw fail('XHS_ACCOUNT_NOT_VERIFIED','The current creator account did not match --account-id: '+state.state);
+  if (action === 'fill') {
+    const note = readNote(options.manifest);
+    if (note.digest !== options.digest || state.manifestDigest !== note.digest)
+      throw fail('XHS_MANIFEST_CHANGED','The manifest does not match the uploaded images and text');
+    if (!['images-ready','review-incomplete','review-ready'].includes(state.state))
+      throw fail('XHS_FORM_UNAVAILABLE','Check image upload status before filling: '+state.state);
+    return native('fill',{accountId,manifestDigest:note.digest});
+  }
+  if (action === 'prepare' || action === 'upload') {
+    if (state.state !== 'account-ready')
+      throw fail('XHS_FORM_UNAVAILABLE','Open a fresh creator preparation and inspect the account: '+state.state);
+    const note = readNote(options.manifest,true);
+    if (note.digest !== options.digest)
+      throw fail('XHS_MANIFEST_CHANGED','Repeat preflight and review the current manifest digest');
+    alreadyClaimed(claimPath(accountId,note.digest));
+    const staged = [];
+    try {
+      privatePath(connection.folder,true);
+      const media = note.media.map(({bytes,type,sha256})=>{
+        const stage = crypto.randomUUID();
+        const file = path.join(connection.folder,stage+'.xhs-media');
+        const fd = fs.openSync(file,'wx',0o600);
+        staged.push(file);
+        try { fs.writeFileSync(fd,bytes); } finally { fs.closeSync(fd); }
+        return {stage,type,sha256};
+      });
+      return await until(await native(action,{accountId,manifestDigest:note.digest,
+        title:note.summary.title,text:note.text,media}),['uploading','opening'],95000);
+    } finally {
+      for (const file of staged) {
+        try { fs.unlinkSync(file); } catch (error) { if (error.code !== 'ENOENT') throw error; }
+      }
+    }
+  }
+  if (action === 'submit') {
+    if (state.state !== 'form-ready' || state.confirmation !== options.confirm)
+      throw fail('XHS_CONFIRMATION_MISMATCH','Use the confirmation returned by this ready preparation');
+    const attempt = {preparationId:preparation,containerId:container.id,instance,fixture,accountId,manifestDigest:state.manifestDigest};
+    const claim = claimPath(accountId,state.manifestDigest);
+    alreadyClaimed(claim);
+    try { writeAttempt(receiptPath,attempt); }
+    catch (error) {
+      if (error.code === 'EEXIST') throw fail('XHS_SUBMISSION_ALREADY_ATTEMPTED','Inspect xhs note status; the preparation already has a submission attempt',{executed:'unknown'});
+      throw error;
+    }
+    try { writeAttempt(claim,attempt); }
+    catch (error) {
+      settle({...state,state:'not-submitted',reason:'local-attempt-claim-failed'},attempt);
+      if (error.code === 'EEXIST') alreadyClaimed(claim);
+      throw error;
+    }
+    let result;
+    try {
+      result = await until(await native('submit',{accountId,confirm:options.confirm}),['submission-checking','submission-unknown'],12000);
+    } catch (error) {
+      throw fail(error.code??'XHS_SUBMISSION_UNKNOWN','Submission outcome is uncertain; inspect xhs note status before any new attempt',
+        {executed:'unknown',operationId:error.operationId,recovery:'xhs note status --preparation '+preparation});
+    }
+    settle(result,attempt);
+    if (result.state === 'submission-checking') {
+      return {...result,state:'submission-unknown',
+        recovery:'Inspect xhs note status before considering another submission'};
+    }
+    return result;
+  }
+  throw fail('INVALID_ARGUMENT','Unknown note command');
+}

package/lib/xhs.mjs

@@ -0,0 +1,36 @@
+import crypto from 'node:crypto';
+import {fail} from './common.mjs';
+import {discover,inspectInConnection,callMailbox} from './browser.mjs';
+
+export function validateSearchResult(body, keyword) {
+  if(body?.success!==true||body.transport!=='background-page-dom'||body.keyword!==keyword||body.data?.keyword!==keyword||body.data?.state!=='ready'||!Array.isArray(body.data.items)||!body.data.items.length||body.data.items.length>20)
+    throw fail('XHS_SEARCH_REJECTED','Xiaohongshu did not return the requested search list',{executed:true});
+  const seen=new Set();
+  const items=body.data.items.map(item=>{
+    if(!item||typeof item.id!=='string'||!/^[a-f0-9]{24}$/.test(item.id)||seen.has(item.id)||typeof item.title!=='string'||item.title.length>500||typeof item.author!=='string'||item.author.length>100||typeof item.likes!=='string'||item.likes.length>30||item.url!=='https://www.xiaohongshu.com/explore/'+item.id)
+      throw fail('PROTOCOL_MISMATCH','Invalid Xiaohongshu note projection',{executed:true});
+    seen.add(item.id);
+    return {id:item.id,title:item.title,author:item.author,likes:item.likes,url:item.url};
+  });
+  return {transport:body.transport,pageClosed:body.pageClosed===true,keyword,count:items.length,items};
+}
+export async function searchXhs(options, dependencies={}) {
+  const keyword=options.keyword?.trim();
+  if(!options.container||!keyword||Buffer.byteLength(keyword)>180||options.via!=='page')
+    throw fail('INVALID_ARGUMENT','Specify --container, --keyword and --via page');
+  const connect=dependencies.discover??discover;
+  const inspect=dependencies.inspect??inspectInConnection;
+  const call=dependencies.call??callMailbox;
+  const connection=connect(options);
+  if(connection.endpoint.xhsPageSearchProtocol!==1)
+    throw fail('BROWSER_UPGRADE_REQUIRED','This search requires a compatible Ecom Dev with xhsPageSearchProtocol 1');
+  const {container}=await inspect(connection,options.container);
+  if(container.platform!=='xiaohongshu')throw fail('XHS_CONTAINER_REQUIRED','Select a Xiaohongshu account container');
+  const searchId=((BigInt(Date.now())<<64n)+BigInt(crypto.randomInt(2147483647))).toString(36).toUpperCase();
+  const result=await call(connection,{method:'business.read',operation:'xhs.search-page',containerId:container.id,params:{keyword,search_id:searchId}},30000);
+  if(result.containerId!==container.id||result.businessOperation!=='xhs.search-page')
+    throw fail('PROTOCOL_MISMATCH','Search response does not match the pinned container',{executed:'unknown',operationId:result.operationId});
+  return {ok:true,schemaVersion:1,operationId:result.operationId,
+    instance:{id:connection.endpoint.instanceId,channel:connection.channel},
+    container:{id:container.id,name:container.name},...validateSearchResult(result.data,keyword)};
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@petercjl/ecom-cli",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "description": "Agent CLI and portable Skill for Ecom browser containers",
   "type": "module",
   "license": "MPL-2.0",