Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -25,7 +25,7 @@ npm run build
node examples/ding-dong-bot.ts
```

Scan the terminal QR and confirm the login on your phone. After `Ready` appears, send `ding` from another WeChat account. The example replies with `dong` and prints the received message and reply. Stop with Ctrl+C. Starting it again displays a new QR.
Scan the terminal QR and confirm the login on your phone. The example prints the account's nickname. After `Ready` appears, send `ding` from another WeChat account. The example replies with `dong` and prints the received message and reply. Signing the device out from the phone, or calling `puppet.logout()`, emits `logout` with the reason. Stop with Ctrl+C. Starting it again displays a new QR.

Node runs the TypeScript example directly. The commands above build the package and native addon from source. To use a prebuilt tarball in another project, install the tarball and copy its `examples/ding-dong-bot.ts` into that project before running it.

Expand Down
27 changes: 22 additions & 5 deletions docs/v1-spec.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,9 +15,10 @@ node examples/ding-dong-bot.ts

1. Scan the QR displayed in the terminal and confirm the login on the phone.
2. Wait for `Ready`, then send one new `ding` from the peer.
3. Check that the terminal prints the incoming message and reply, and that the peer receives exactly one `dong`.
4. Stop with Ctrl+C and run the command again. Verify that a fresh QR scan is required and repeat the exchange.
5. Install an npm tarball in a fresh project, copy its TypeScript example into that project, and repeat the test using the installed package.
3. Check that the terminal prints `Logged in as` with the account's nickname, the incoming message and the reply, and that the peer receives exactly one `dong`.
4. Sign the Puppet Neo device out from the phone. Check that the terminal prints `Logged out: WeChat ended the session`.
5. Stop with Ctrl+C and run the command again. Verify that a fresh QR scan is required and repeat the exchange.
6. Install an npm tarball in a fresh project, copy its TypeScript example into that project, and repeat the test using the installed package.

The example listens for Puppet events, retrieves messages with `messagePayload()`, and replies with `messageSendText()`. It handles direct text from other accounts. Initial sync can deliver earlier messages, so inspect the test conversation before the exchange.

Expand Down Expand Up @@ -45,17 +46,33 @@ Session state lasts for the running process. Neo neither exports nor restores au

Unhandled sync commands are silently discarded while the received cursor advances. Neo emits direct text messages with a known server message ID and keeps IDs as strings. It caches each payload before emitting its ID so callers can retrieve it.

An accepted send resolves with no Message object. An uncertain send is reported to the caller after a single submission. Polling, heartbeat or sync failures stop the session loop and emit an error. The caller can stop and start again to log in afresh.
An accepted send resolves with no Message object. An uncertain send is reported to the caller after a single submission.

## Login and logout

When the phone confirms the QR login, Neo emits `login` with the account's username at once. It also starts a background lookup of the account's own profile. `contactPayload(currentUserId)` waits for that lookup and returns the nickname as `name` and the WeChat ID, when set, as `weixin`. If the lookup fails, `name` falls back to the WeChat ID, then to the username. Login never waits for or fails because of the profile.

Each session emits `logout` once:

| Cause | `logout` reason |
| --- | --- |
| The application calls `stop()` | `puppet stop()` |
| The application calls `logout(reason)`. Neo first submits WeChat's logout request once | the given reason |
| WeChat rejects heartbeat or sync credentials (`-13`) and also rejects one automatic renewal, for example after the device is signed out from the phone | `WeChat ended the session` |
| Any other failure after login stops the session loop. An `error` event comes first | `Neo session failed` |

If the notification socket closes, Neo reconnects once and lets a heartbeat decide whether the session is still valid. Sends are never repeated after a renewal. After a logout the puppet stays started; stop and start it to log in with a new QR. The base Puppet clears `currentUserId` one event-loop turn after emitting `logout`, so listeners can still read it.

## Validation and release gates

| Gate | Evidence to collect |
| --- | --- |
| Rust behavior | Unhandled sync commands skipped and lost send acknowledgment handled once |
| Puppet API | Scripted session drives QR login, text payload lookup, reply, clean stop and a fresh login |
| Login and logout | Login before the profile, nickname and fallback names, and one logout for stop, `logout()`, a session ended by WeChat and an unexpected failure |
| Example | The actual TypeScript example runs against a scripted session and replies through PuppetNeo |
| Native boundary | Load the addon without a storage key and reject unauthenticated operations |
| Package | Install a tarball in a fresh project and run the Puppet, native and example tests |
| Live acceptance | Fresh QR login and Ding Dong with an isolated test account, then repeat after restarting |
| Live acceptance | Fresh QR login showing the nickname, Ding Dong with an isolated test account, `logout` after signing out from the phone, then repeat after restarting |

Start with an npm development release on `next` after acceptance. Follow Wechaty's odd-minor development and even-minor stable convention. Use the combined tarball after its four native package checks pass and report live acceptance separately. Review the repository, installed example and release workflow with the Wechaty maintainers before expanding scope or promoting a stable release. Automatic publication follows that review.
9 changes: 6 additions & 3 deletions examples/ding-dong-bot.ts
Original file line number Diff line number Diff line change
Expand Up @@ -10,10 +10,13 @@ puppet.on('scan', ({ qrcode, status }) => {
}
console.info(`Login status: ${types.ScanStatus[status]}`)
})
puppet.on('login', () => console.info('Logged in.'))
puppet.on('login', async ({ contactId }) => {
const self = await puppet.contactPayload(contactId)
console.info(`Logged in as ${self.name}.`)
})
puppet.on('ready', () => console.info('Ready. Send this account "ding" to receive "dong".'))
puppet.on('logout', () => console.info('Logged out.'))
puppet.on('error', ({ data }) => console.error(data))
puppet.on('logout', ({ data }) => console.info(`Logged out: ${data}`))
puppet.on('error', ({ gerror }) => console.error(gerror ? JSON.parse(gerror).message : 'Unknown error'))
puppet.on('message', async ({ messageId }) => {
try {
const message = await puppet.messagePayload(messageId)
Expand Down
1 change: 1 addition & 0 deletions native/Cargo.lock

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

1 change: 1 addition & 0 deletions native/Cargo.toml
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,7 @@ napi-derive = "3"
openssl = { version = "0.10", features = ["vendored"] }
serde = { version = "1", features = ["derive"] }
serde_json = "1"
tokio = { version = "1", features = ["rt"] }
wechat-protocol = "=2.1.0"

[build-dependencies]
Expand Down
Loading
Loading