notte-sdk 1.9.0 → 1.9.2

package/README.md

@@ -24,6 +24,40 @@ npm pack --dry-run
 To update the generated client, run `npm run generate:staging`, review the diff,
 and commit it. `npm run check:staging` checks for drift without editing your files.
 
+### Generated resource methods
+
+The SDK generates client-bound methods for `sessions`, `agents`, `functions`,
+`vaults`, `personas`, and `profiles` from the checked-in OpenAPI-derived types
+and operations. No per-call client or `throwOnError` is needed:
+
+```ts
+const client = new NotteClient();
+await client.sessions.stop(sessionId);
+const vault = await client.vaults.create({ name: 'default' });
+const copy = await client.functions.fork(functionId);
+```
+
+Arguments are path IDs in URL order, then the request body (if any), query
+parameters (if any), and optional `{ signal }` cancellation options. For example,
+`client.sessions.stop(sessionId, { close_reason: 'manual' }, { signal })`.
+Operations with required request headers require a final options object, for
+example `client.sessions.createPayment(sessionId, body, undefined, { headers: { 'idempotency-key': key } })`.
+Keep the same idempotency key when retrying the same payment request. The SDK
+binds `x-notte-api-key` automatically; callers cannot override it through typed headers.
+Methods return the API response body and throw the client's typed API errors.
+The five existing `list()` methods still return arrays for compatibility;
+the newly added `profiles.list()` returns the API pagination response.
+
+These are API operations, not lifecycle helpers: they do not poll for completion,
+decrypt credentials, or manage cleanup. Continue using `Session().use()`,
+`Agent().run()`, `Function().run()`, and `Vault()` for those behaviors. Existing
+standalone generated exports remain supported.
+
+`npm run generate` refreshes this layer too. Use `npm run resources:generate`
+to regenerate it offline, `npm run resources:check` to detect stale output, and
+`npm run resources:test` for generator regressions. Method-name aliases live in
+the generator; request shapes and routes come from generated OpenAPI types.
+
 For the isolated live test, set `NOTTE_API_KEY` and
 `NOTTE_API_URL=https://us-staging.notte.cc`, then run:
 
@@ -884,6 +918,14 @@ try {
 
 ### Timeouts and retries
 
+CAPTCHA solving has a separate `captchaTimeoutSeconds` budget (default 180).
+`session.execute()` polls pending solves using requests of at most 10 seconds,
+then resumes an ordinary action only when the backend confirms it did not execute.
+Actions that already ran are never replayed. Navigation, closure, provider failure,
+and deadline expiry preserve the normal `raiseOnFailure` behavior. Ordinary HTTP
+transport failures are not automatically retried. Deploy backend CAPTCHA polling
+support before upgrading the SDK.
+
 The client applies a per-request timeout (`timeoutMs`, default 60 000 ms; `0`
 disables it) through response-body consumption and rejects with `NotteTimeoutError`
 when it elapses. Explicit streams use the caller's signal for body cancellation;
@@ -1100,3 +1142,54 @@ For issues and questions:
 - GitHub Issues: [Report issues](https://github.com/nottelabs/notte/issues)
 - Documentation: [docs.notte.cc](https://docs.notte.cc)
 - Python SDK: [notte-sdk](https://pypi.org/project/notte-sdk/)
+
+## Managed authentication
+
+Use existing connection IDs with a session. `start()` waits for authentication by
+default, and `.use()` always invokes its callback only after the session is ready:
+
+```typescript
+const session = client.Session({ auth_ids: ["<connection-id>"], auth_retry: 2 });
+await session.use(async (ready) => {
+  await ready.execute({ type: "goto", url: "https://example.com" });
+});
+```
+
+For a nonblocking start, wait explicitly before browser actions or CDP access:
+
+```typescript
+const abortController = new AbortController();
+const session = client.Session({ auth_ids: ["<connection-id>"] });
+await session.start({ wait_for_authentication: false });
+try {
+  await session.waitForAuth({ timeoutMs: 615_000, signal: abortController.signal });
+  await session.execute({ type: "goto", url: "https://example.com" });
+} finally {
+  await session.stop();
+}
+```
+
+Waiting polls session readiness through short requests. It never restarts the
+session or submits another login. `auth_retry` controls server-side login retries
+(0 to 2) and is omitted from requests without `auth_ids`. A failed or cancelled
+startup wait closes the created session. A standalone `waitForAuth()` leaves
+cleanup to the caller.
+
+Connection operations are available through `client.managedAuth`:
+
+```typescript
+const check = await client.managedAuth.checkConnection("<connection-id>");
+// checkConnection only verifies; refreshConnection can log in if needed.
+const operation = await client.managedAuth.refreshConnection("<connection-id>", {
+  wait: false,
+  auth_retry: 2,
+});
+const completed = await client.managedAuth.waitForAuth(operation);
+// To explicitly request a new login:
+await client.managedAuth.reauthenticateConnection("<connection-id>");
+```
+
+Refresh and reauthentication wait by default. Use `getOperation(operation.id)`
+for individual status reads. Cancelling an operation wait does not cancel the
+server operation. An HTTP 409 remains an ownership conflict and is not retried.
+These helpers require a backend with the managed-auth lifecycle endpoints.