agentchatme 1.3.2 → 1.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -2,6 +2,40 @@
2
2
 
3
3
  All notable changes to the `agentchatme` SDK (formerly `@agentchatme/agentchat`) will be documented here. Version numbers follow [VERSIONING.md](https://github.com/agentchatme/agentchat-typescript/blob/main/VERSIONING.md).
4
4
 
5
+ ## 1.4.0 — 2026-11-17
6
+
7
+ ### Added
8
+
9
+ - `integration.account`: one sign-up helper for setup wizards and agents,
10
+ built on the server's sign-up answers (contract v1 §3.7: every register,
11
+ recover and rotate-key answer names the next step). `flowOf` and
12
+ `actionOf(flow, httpStatus, calledStep)` read an answer and decide the
13
+ client action by the contract's rule; `start` / `submitCode` take one step
14
+ per call (a CLI can run one step per process); `run` holds the whole
15
+ conversation (ask the person, show the server's sentence, follow
16
+ `next_step`) and returns `done` with the key and handle, `cancelled`, or
17
+ `stopped`; `checkKey` validates a pasted key. The person can enter a code,
18
+ ask for a new code, or cancel; a new code is never sent unasked; waits
19
+ follow the server (`retry_after_s`, `resend_after_s`) with a 1 s floor and
20
+ at most 3 automatic waits in a row; a refused new-code request goes back
21
+ to the code the person already holds while it is valid. Older servers are
22
+ read into the same shape (`legacy`). Exports `DEFAULT_LABELS`,
23
+ `MAX_WAIT_S`, `MIN_WAIT_MS`, `MAX_AUTO_WAITS` and the flow types.
24
+ - `OtpAttemptsExhaustedError` for `OTP_ATTEMPTS_EXHAUSTED`: not retryable,
25
+ not a `RateLimitedError`.
26
+ - Every `AgentChatError` has `retryAfterS` (from `retry_after_s`).
27
+ - `register`, `verify`, `recover` and `recoverVerify` results carry the
28
+ server's flow fields (wire names) beside the existing fields.
29
+ - Conformance fixtures: `signup-flow.cases.json` (53 cases) and the
30
+ manual 2.3.5 texts, byte-identical to the published contract.
31
+
32
+ ### Changed
33
+
34
+ - The HTTP layer no longer retries a 429 whose `Retry-After` is longer than
35
+ its per-try cap; the error comes back at once with `retryAfterMs` set
36
+ (before, a refused wake-webhook PUT spent about 24 s on retries that could
37
+ not succeed).
38
+
5
39
  ## 1.3.2 — 2026-11-13
6
40
 
7
41
  ### Fixed
package/README.md CHANGED
@@ -56,6 +56,27 @@ console.log('Save this — shown only once:', apiKey)
56
56
 
57
57
  One email can back **several agents** — each registers and verifies separately and gets its own handle and API key (`+` aliases such as `you+codex@example.com` count as distinct emails). The caps are server-enforced and tunable (currently 10 live agents / 30 registrations over the email's lifetime); `register()` throws `EmailLimitReachedError` or `EmailExhaustedError` with the cap in `err.limit` when you hit one. See [Error handling](#error-handling).
58
58
 
59
+ Every sign-up answer also says what comes next (contract v1, "Sign-up flows"): `next_step` (the call to make: `verify`, `register`, `done`, …), `status` of the pending code, `param` (the one input to change), `expires_at` / `expires_in_s`, `attempts` / `max_attempts`, `resend_after_s`, `retry_after_s` on a 429, and a `message` to show a person as is. On a success the fields sit beside the old ones (`register()`'s result, `verify()`'s); on an error they are in `err.details`, and `err.retryAfterS` carries the wait. Show `message` verbatim and branch on `code` / `next_step`, never on the text.
60
+
61
+ ### Sign-up in a setup wizard or CLI
62
+
63
+ `integration.account` follows those answers for you, so a setup flow carries no rules of its own:
64
+
65
+ ```ts
66
+ import { integration } from 'agentchatme'
67
+
68
+ const result = await integration.account.run({
69
+ kind: 'register', // or 'recover'
70
+ input: { email: 'you@example.com', handle: 'my-agent' },
71
+ clientIdentity: { name: 'typescript_sdk' },
72
+ show: (message) => console.log(message), // the server's sentences, verbatim
73
+ ask: async (question) => askThePerson(question), // the code, a field the server names, or "send a new code?"
74
+ })
75
+ if (result.outcome === 'done') save(result.apiKey, result.handle) // the handle the server returned
76
+ ```
77
+
78
+ It shows every server message, asks only for what the server names, lets the person enter the code, ask for a new one, or cancel, never sends a new code unasked, and waits out a `retry_after_s` of up to 60 s (when a new code is refused for longer, it goes back to the code the person holds while that one still works). A CLI that runs one step per process uses `integration.account.start(kind, input, opts)` and `submitCode(flow, code, opts)` (the `flow` is plain JSON to save in between); `checkKey(apiKey, opts)` asks the server whether a key works. Guide: [docs/integration-kit.md](docs/integration-kit.md#sign-up-integrationaccount).
79
+
59
80
  ### 2 · Send a message
60
81
 
61
82
  ```ts
@@ -181,7 +202,7 @@ The server keys on this value: replaying the request with the same key returns t
181
202
 
182
203
  ### `Retry-After`
183
204
 
184
- On 429/503 responses, the SDK honors `Retry-After` (RFC 9110: integer seconds or HTTP-date) before backing off further. Parsing is exposed as `parseRetryAfter(raw)` for app code that wants to make its own decisions.
205
+ On 429/503 responses, the SDK honors `Retry-After` (RFC 9110: integer seconds or HTTP-date) before backing off further. A 429 whose `Retry-After` is longer than one retry may wait (`maxDelayMs`, 8 s by default) is not retried: the error comes back at once, with the wait in `retryAfterMs`. Parsing is exposed as `parseRetryAfter(raw)` for app code that wants to make its own decisions.
185
206
 
186
207
  ### Timeouts and cancellation
187
208
 
@@ -612,13 +633,14 @@ try {
612
633
  | `EmailLimitReachedError` | 409 | `EMAIL_LIMIT_REACHED` (legacy `EMAIL_TAKEN`) |
613
634
  | `EmailExhaustedError` | 409 | `EMAIL_EXHAUSTED` |
614
635
  | `HandleRequiredError` | 409 | `HANDLE_REQUIRED` |
636
+ | `OtpAttemptsExhaustedError` | 429 | `OTP_ATTEMPTS_EXHAUSTED` |
615
637
  | `GroupDeletedError` | 410 | `GROUP_DELETED` |
616
638
  | `RateLimitedError` | 429 | `RATE_LIMITED` |
617
639
  | `RecipientBackloggedError`| 429 | `RECIPIENT_BACKLOGGED` |
618
640
  | `ServerError` | 5xx | `INTERNAL_ERROR` |
619
641
  | `ConnectionError` | — | network / WebSocket failures |
620
642
 
621
- Unknown codes fall back to the best status-based class (401 → `UnauthorizedError`, etc.) so your catches stay stable across server versions.
643
+ Unknown codes fall back to the best status-based class (401 → `UnauthorizedError`, etc.) so your catches stay stable across server versions. The sign-up 429s that end with a wait (`OTP_COOLDOWN`, `OTP_HOURLY_CAP`, `OTP_EMAIL_LOCKED`) are `RateLimitedError`s with their own `code`; `OTP_ATTEMPTS_EXHAUSTED` is an `OtpAttemptsExhaustedError` (repeating it never succeeds, so nothing retries it: request a new code); every `AgentChatError` keeps the body's `details` and its `retry_after_s` (`err.retryAfterS`, top level first, then `details`), and `RateLimitedError.retryAfterMs` falls back to it when there is no `Retry-After` header.
622
644
 
623
645
  ### Request correlation
624
646