@qoniai/qoni 0.8.0 → 0.9.1

package/CHANGELOG.md

@@ -1,6 +1,168 @@
 # Changelog
 
-## 0.8.0 - Unreleased
+## Unreleased — GenAuth communication
+
+- Add 111 Agent Mail/Phone runtime and administration methods with typed inputs/results.
+- Add native GenAuth credential exchange, bounded polling, idempotency and revision headers, and nested communication error codes.
+- Add bilingual SDK reference content and read-only live acceptance checks; current hosted Phone routes remain unavailable.
+
+
+## Unreleased
+
+- Add 591 GenAuth / Authing v3 management methods across 35 namespaces, aligned with all 496 JSON management methods in the official Authing Node SDK 4.0.2 plus GenAuth extensions and compatibility names. Include typed inputs/results, domain shortcuts and the flat `genauth.management` migration entry.
+- Preserve official SDK defaults and method names; support management PUT operations and safely interpolate DELETE path identifiers. Pin the upstream contract and include its MIT notice.
+- Add `genauth.users.iterate` for streaming paginated user lists and management request cancellation.
+- Coalesce concurrent management-token exchanges, honor JWT expiry and refresh once after automatic-token auth rejection.
+- Surface HTTP-200 GenAuth business errors even with `data`, preserving numeric Authing API codes and request IDs.
+- Preserve the existing user helpers; add generated contract/catalog maintenance, isolated live management acceptance and integration documentation.
+
+## Unreleased — next version: 0.10.0
+
+These public API changes require **0.10.0**, not a 0.9.x patch. This work does
+not bump the packaged version, publish, or release it.
+
+### Breaking
+
+- `track.create` requires an explicit schedule. Migrate to an integer
+  `{ kind: "interval", intervalSeconds: 600..2592000 }` or an explicit
+  `{ kind: "daily", at: "HH:MM", tz }`; daily starts up to 30 minutes early.
+  Cron is locally unsupported and is never automatically converted.
+- Interval `tz` and old targetUrls/extractionSchema/triggerDsl/
+  stopConditionDsl/notifyChannel/url fields have no wire equivalent. Remove
+  them; put watched URLs explicitly in prompt instructions. Optional undefined
+  fields are still omitted; defined unsupported fields raise typed local errors.
+- `refine` accepts title/schedule only. Create a new Track to change the original
+  prompt/intent; the raw updateMonitor wire API supports explicit instructions.
+- `runNow` returns only `{ trackId, sessionId, runId }`, a 202 acceptance
+  reference. TrackTaskRef is a type alias and remains assignable to JsonObject.
+  Read the exact recent check for its real `done/failed/expired/canceled`
+  status; this differs from RunResult's `succeeded`. Create already starts a
+  first look: wait for the original lastTaskId before one explicit runNow.
+- `runs` and `run(id)` search only the newest 50 checks; no extracted/diffs/
+  snapshot fields are synthesized. Replace old tick/snapshot consumers with
+  the actual check fields; a missing run raises local not_found with its range.
+- Track events/interactionHandle/api.events/api.intervene and DoAnything
+  readArtifacts now raise local QoniUnsupportedError with zero HTTP. Their
+  deprecated exports remain; use Track checks, separately authorized DoAnything
+  interactions, real file artifacts(), or captured screenshot events instead.
+- Pause/delete stop future scheduling and keep an in-flight check running.
+
+### Changed
+
+- Track now maps supported operations to `/track/tracks`: prompt → instructions,
+  explicit integer intervals of 600–2592000 seconds or daily at/tz (starts
+  0–30 minutes before target), real status PATCH, empty DELETE204, recent 50
+  checks with local pagination, and runNow task references. Refine is limited
+  to title/schedule. Deletion does not cancel a running task.
+- Cron, old extraction/DSL/URL/channel options, Track events/intervene and
+  interactionHandle fail locally. Deprecated methods/types remain exported.
+- `doAnything.api.readArtifacts` and snapshot types are deprecated with local
+  `QoniUnsupportedError` (`unsupported.operation`), zero HTTP. Use actual file
+  artifacts or captured screenshot events. File APIs are unchanged.
+- Live coverage metadata retires old monitor/snapshot success claims; current
+  Track mapping is locally verified, with live acceptance pending.
+
+## 0.9.0 - 2026-10-07
+
+DoAnything interactions are now typed by what the user has to do, never by
+business: `site_login`, `take_control`, `ask_user`, `confirmation`, plus the
+system `wait`.
+
+### Changed
+
+- `Interaction` is a union distributed over `type`: `switch (interaction.type)`
+  narrows `payload` in each branch, including `handle.interaction` inside
+  `onInteraction`. `Interaction<"site_login">` still picks one member.
+  `TypedInteraction` names the union. Because it is now a type alias, not an
+  interface, `interface X extends Interaction` no longer compiles (TS2312):
+  use `type X = Interaction & { ... }`. Code that builds an `Interaction` from a
+  separate `type` and `payload` must narrow them together or cast the object.
+- The wire's `clarification` is presented as `ask_user`, with payload
+  `{ question, answerType, options? }`. `answerType` is `text`, `number`,
+  `boolean`, `single_choice` or `multiple_choice`, and options are
+  `{ value, label }`. A clarification with choices becomes `single_choice`; one
+  without choices is `text`. A native `ask_user` keeps the `answer_type` it
+  sends, and every string option value is kept, including `""`.
+  Migration: compare `type` with `"ask_user"` instead of `"clarification"`
+  (TypeScript no longer compiles the old comparison); read
+  `payload.answerType` / `payload.options` instead of `payload.inputType`
+  (removed) or the answer action's `inputSchema` enum.
+  `InteractionTypes.Clarification` is deprecated and now equals
+  `InteractionTypes.AskUser`: it still matches interactions the SDK hands out,
+  but not a raw wire `type` or a `"clarification"` string you stored.
+  `ClarificationPayload` is a deprecated alias of `AskUserPayload`, which
+  requires `answerType`.
+- `InteractionHandle.answer(value)` accepts the structured value its
+  `answerType` names (string, number, boolean, one option value, or an array of
+  option values) and throws `QoniValidationError` before sending a value that
+  does not fit.
+- `InteractionHandle.confirmSignedIn()` saves the login opened by `openLogin()`
+  on the same interaction (`POST /profiles/{profileId}/confirm`, scope
+  `webagent.site_login:confirm`), then tells the agent to recheck. Sign-in is
+  `openLogin()` → `confirmSignedIn()`:
+  - It saves once and rechecks once per login session, however many handles
+    or concurrent calls ask; the deprecated `OpenLoginResult.confirm()` shares
+    the same save.
+  - A user who is not signed in yet, or 409 `no_pending_login`, still gets a
+    recheck: the agent raises a new `site_login` when needed.
+  - When the backend keeps the session but could not save it
+    (`probeResult: "release_failed"`), it throws a retryable `QoniError` coded
+    `site_login.save_failed` and does not tell the agent to go on; calling it
+    again saves again. Any other save failure is thrown as well.
+  - When `openLogin()` calls overlap, the latest call that succeeds owns the
+    session, whichever response arrives last.
+  - Reopening that returns the same backend session shares its save; when a
+    newer backend session replaces it, `confirm()` on the old result throws
+    `QoniValidationError` instead of saving. If the login is reopened while a
+    `confirmSignedIn()` is still saving, that call throws a retryable
+    `QoniError` coded `site_login.session_replaced` without telling the agent
+    to go on; call it again to save the newer login.
+  - Handles from the same `RunHandle` or `MonitorHandle` share the login
+    session, so a handle from a later callback saves it too. A RunHandle from
+    another `attach()` or process does not.
+- `connectControl()` and `refreshControl()` resolve to a `ControlSession`
+  (`{ liveUrl, expiresAt?, status?, raw }`, the signed URL of the browser the
+  user now controls) instead of `void`. `await handle.connectControl()` is
+  unaffected; code that returns the call where `Promise<void>` is expected,
+  such as `const cb: () => Promise<void> = () => handle.connectControl()`, no
+  longer compiles (TS2322) — wrap it: `async () => { await handle.connectControl(); }`.
+- `run.events()`, `wait({ onInteraction })` and `monitor.events()` keep an
+  interaction's type and content when the backend settles it with an empty
+  shell (a resolve labelled `clarification` with an empty question, or a
+  `site_login` with one empty site): only `status`, `resolvedAt` and `actions`
+  change. A settled update with content of its own, such as an expired
+  take-over with its reason, replaces the card as before. Run and monitor
+  handles keep about 256 interactions, forgetting settled cards first, and
+  logins once they are saved or their interaction ended; a pending card or a
+  login still in progress is never dropped.
+
+### Added
+
+- `QoniScopes.USER_PROFILE_READ` (`user.profile:read`), `USER_PROFILE_WRITE`
+  (`user.profile:write`), `USER_PAYMENT_USE` (`user.payment:use`),
+  `AGENT_MAIL_READ` (`agent.mail:read`) and `AGENT_MAIL_SEND`
+  (`agent.mail:send`). They belong to no product bundle: request them
+  explicitly, and allow them in the AccessKey policy. The constants only name
+  the scopes; requesting them does not by itself enable Profile, payment or
+  mailbox access in a run.
+- Exported types `AskUserPayload`, `AskUserOption`, `AskUserAnswer`,
+  `AskUserAnswerType`, `InteractionBase`, `TypedInteraction` and
+  `ControlSession`.
+
+### Fixed
+
+- A scope written without its service prefix names every matching scope:
+  `profile:read` suggests both `gumem.profile:read` and `user.profile:read`.
+
+### Deprecated
+
+- `user` / `userId` on interactive delegation input: the authorization page
+  identifies the signed-in user, and the delegation service ignores them.
+- `DelegateTokenResponse.grantedScopes`: the delegation service does not return
+  it. Read `qoni.genauth.introspectDelegationToken({ token }).data.scope`.
+- `OpenLoginResult.confirm()`: `confirmSignedIn()` saves the login itself.
+
+## 0.8.0 - 2026-10-04
 
 ### Added
 
@@ -150,7 +312,7 @@ compatible fixes.
 - Optional abort signals on product run-detail and artifact-list wire reads;
   existing calls without a signal remain compatible.
 
-## Unreleased
+## Earlier changes
 
 ### Breaking