@mitralab.io/platform-sdk 1.0.8 → 1.1.0-beta.0

package/CHANGELOG.md

@@ -0,0 +1,49 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+## 1.1.0-beta.0
+
+- Complete native Function sync, async, polling, cancellation, and anonymous public execution.
+- Expose browser-safe Agent Tasks, restricted Agent Credentials, and model discovery through Core 0.2 contracts.
+- Compose the Core-owned Agent task session manager with Platform WebSocket and HTTP/SSE adapters.
+- Add native anonymous polling for executions created by the public async Function route.
+- Keep business-Agent administration out of the browser adapter according to the app-role permission matrix.
+- Expose app-scoped integration config listing and execution by alias from Core 0.2.
+- Document the missing producer contract for native record selection by `jdbcConnectionConfigId` instead of inventing a browser-side translation.
+- Document that entity `update` already implements the producer's partial PUT semantics, so no duplicate PATCH method is needed.
+- Derive Function execution, integration proxy input, and custom query result types directly from Core without narrowing nullable or producer-returned fields.
+- Preserve the complete Data Manager record envelope and execute Custom Queries with only
+  producer parameters, without a caller-selected Data Source or an `init()` precondition.
+
+- Refresh app sessions proactively through IAM before authenticated native requests, with a 30-second JWT expiry heuristic and one shared refresh flight.
+- Preserve sessions on transient refresh failures, clear them on definitive IAM client failures, and retain the one-time reactive `401` retry.
+- Rotate both tokens without fetching the current user or notifying public auth-state listeners, while keeping the legacy bridge synchronized.
+- Reject decodable access and refresh tokens whose app scope is missing or differs from the configured app while keeping opaque tokens server-authoritative.
+- Fence refresh responses by session generation so late success or failure cannot undo sign-out or overwrite a newer login or bridged session.
+- Bind reactive `401` handling to the token used by the rejected request so an old response cannot refresh or clear a replacement session.
+- Redact values under sensitive credential field names from recursive API error details.
+- Preserve the retained session when `auth.me()` reaches `401` after transient proactive and reactive refresh failures.
+- Add native Google SSO through popup and redirect flows with direct IAM code exchange.
+- Validate Google SSO origin, popup source, one-time state, cancellation, timeout, and token response shape.
+- Require redirect errors to bind to the stored state before exposing or consuming them.
+- Keep Google options limited to popup or redirect mode; account creation and locale remain producer concerns.
+- Leave legacy-only `returnTo` and `title` on the deprecated aliases because the old runtime did not implement them as native Google controls.
+- Preserve the email/password methods already public in Platform SDK 1.0.9 without presenting them as the new template flow.
+- Route deprecated calls and legacy authentication through `${apiUrl}/legacy`.
+- Apply the native auth page URL precedence to the deprecated SSO bridge.
+- Propagate native sign-in, refresh, token changes, and sign-out to the legacy SDK session.
+- Re-export the deprecated `mitra-interactions-sdk` surface from the package entrypoint.
+- Mark every legacy type alias as deprecated in generated declarations.
+- Share one session between this SDK and the legacy SDK in both directions.
+- Make the SonarCloud job wait for the Quality Gate result.
+- Align the public package metadata and ESM, CommonJS, and TypeScript artifacts.
+- Add package shape checks and public tarball smoke coverage.
+- Correct public imports and required configuration in documentation examples.
+- Add the MIT license.
+
+## 1.0.8
+
+- Share environment-neutral API contracts through `@mitralab.io/sdk-core`.
+- Preserve the Platform SDK 1.x browser authentication and entity facade.
+- Validate redirects, API errors, sensitive-value redaction, and package consumers.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mitra Platform
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -3,197 +3,340 @@
 [![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=mitra-platform-sdk&metric=alert_status&token=28d7be14b66d6f88d706347e2418af5ea39ab3e9)](https://sonarcloud.io/summary/new_code?id=mitra-platform-sdk)
 [![Coverage](https://sonarcloud.io/api/project_badges/measure?project=mitra-platform-sdk&metric=coverage&token=28d7be14b66d6f88d706347e2418af5ea39ab3e9)](https://sonarcloud.io/summary/new_code?id=mitra-platform-sdk)
 
-SDK JavaScript/TypeScript para apps criados na plataforma Mitra. O código gerado pelo Code Studio usa este pacote para autenticar usuários, acessar entidades do Data Manager, executar server functions, rodar custom queries e chamar integrações.
+JavaScript and TypeScript SDK for browser applications built on the Mitra Platform. Applications generated by Code Studio use this package to authenticate users, access Data Manager entities, execute Server Functions and custom queries, call integrations, and run live Agent tasks.
 
-O transporte de browser usa apenas Web APIs padrão (`fetch`, `localStorage`, `URL`, `Proxy`). Os contratos e módulos comuns vêm de `@mitralab.io/sdk-core`, sem trazer autenticação de browser para o core.
+The browser transport uses standard Web APIs only, including `fetch`, `WebSocket`, `ReadableStream`, `AbortController`, browser storage, `URL`, `Proxy`, `crypto`, and `atob`. Shared contracts and API modules come from `@mitralab.io/sdk-core`, without bringing browser authentication into the Core package.
 
-## O Que a SDK Entrega
-
-- Client único criado por `createClient`.
-- Auth com login, cadastro, refresh token, logout e estado em `localStorage`.
-- CRUD dinâmico em tabelas via `mitra.entities.<TableName>`.
-- Execução de server functions publicadas.
-- Execução de custom queries.
-- Proxy de integrações e resources com credential injection no servidor.
-- Tipos TypeScript exportados para os contratos principais.
-
-## Instalação
+## Installation
 
 ```bash
 npm install @mitralab.io/platform-sdk
 ```
 
-## Quick Start
+Node.js 18 or newer is required for development and server-side tooling. The runtime application must provide the browser Web APIs used by the SDK.
+
+## Quick start
 
 ```typescript
-import { createClient } from '@mitralab.io/platform-sdk';
+import { createClient } from "@mitralab.io/platform-sdk"
 
 export const mitra = createClient({
   appId: import.meta.env.VITE_MITRA_APP_ID,
   apiUrl: import.meta.env.VITE_MITRA_API_URL,
   onError: (error) => console.error(error.status, error.code, error.message),
-});
+})
 
-await mitra.init();
+await mitra.init()
 ```
 
-`init()` resolve a configuração pública do app no Code Studio, incluindo `dataSourceId` e `allowSignup`. Chame no boot da aplicação antes de usar `entities`, `queries` ou fluxo de cadastro.
+`init()` resolves the application's public Code Studio configuration, including nullable
+`dataSourceId` and `allowSignup`. The Data Source value remains part of the Platform 1.x
+compatibility flow; native Entities and Custom Queries resolve the current app through the
+authenticated request. Call `init()` during application startup before the compatibility sign-up
+method needs `allowSignup`.
+
+## Configuration
+
+| Field | Required | Description |
+|---|---|---|
+| `appId` | yes | ID of the published Code Studio application. |
+| `apiUrl` | yes | Base URL of the Mitra API gateway. |
+| `authPageUrl` | no | Absolute URL of `sdk-auth.html`. Falls back to `window.__mitraEnv.authPageUrl`, then `/sdk-auth.html` on the `apiUrl` origin. |
+| `onError` | no | Global callback for API errors. |
+
+The client derives service endpoints from `apiUrl`: `/iam`, `/data-manager`, `/functions`, `/integration`, `/copilot`, and `/code-studio`.
 
-## Configuração
+## Boundary
 
-| Campo     | Obrigatório | Uso                                |
-| --------- | ----------- | ---------------------------------- |
-| `appId`   | sim         | ID do app publicado no Code Studio |
-| `apiUrl`  | sim         | URL base do Kong/API da plataforma |
-| `onError` | não         | callback global para erros de API  |
+The Platform SDK owns:
 
-O client deriva os endpoints dos serviços a partir de `apiUrl`: `/iam`, `/data-manager`, `/functions`, `/integration` e `/code-studio`.
+- browser Google SSO, logout, and session refresh
+- trusted session adoption for the embedded app preview
+- session persistence in `localStorage`
+- auth-state listeners
+- proactive token refresh before authenticated native requests
+- one retry after reactive `401` recovery with the current session
+- browser HTTP transport and public application initialization
+- Agent WebSocket and HTTP/SSE live channels
 
-## Estrutura de Arquivos
+`@mitralab.io/sdk-core` owns the shared entities, custom queries, Functions, integrations, Agent task lifecycle, `auth.me`, safe paths, and structural response validation. Server Function code should use `@mitralab.io/functions-sdk` instead of this browser SDK.
+
+## Authentication
+
+```typescript
+const user = await mitra.auth.signInWithGoogle({ mode: "popup" })
+
+const unsubscribe = mitra.auth.onAuthStateChange((currentUser) => {
+  console.log(currentUser?.email)
+})
 
-```text
-src/
-├── client.ts          # createClient, composição dos módulos e init
-├── modules/           # auth de browser e fachadas compatíveis com a API 1.x
-├── utils/http-client  # fetch wrapper, auth header, retry 401 e MitraApiError
-└── index.ts           # exports públicos
+mitra.auth.signOut("/login")
+unsubscribe()
 ```
 
-`@mitralab.io/sdk-core` concentra entities, queries, Functions, integration, `auth.me`, paths seguros e validação estrutural de respostas. A Platform SDK continua responsável por login, cadastro, refresh, `localStorage`, listeners e o retry único após refresh em resposta `401`.
+Authentication state is stored under `mitra_auth_{appId}`. Before each authenticated native request, the SDK checks a JWT's `exp` claim with a 30-second safety window and refreshes directly through IAM when needed. Opaque tokens, malformed JWTs, and JWTs without a numeric `exp` remain server-authoritative and proceed to the request. A `401` still triggers reactive recovery and at most one retry. If another login or bridged session replaced the token while the request was in flight, the retry uses that current token without refreshing its session. If sign-out cleared the token, the old `401` neither refreshes nor retries.
 
-## Módulos
+The generated-application authentication flow is Google SSO. The old native `signIn` and `signUp` names fail locally with `UNSUPPORTED_AUTH_METHOD` because IAM has no email/password endpoints. Deprecated login bindings remain available only through the legacy reexports.
 
-| Módulo        | Uso                                                                                     |
-| ------------- | --------------------------------------------------------------------------------------- |
-| `auth`        | `signIn`, `signUp`, `signOut`, `refreshSession`, `me`, `checkAuth`, `onAuthStateChange` |
-| `entities`    | CRUD dinâmico por tabela, filtro, paginação, bulk create e deleteMany                   |
-| `functions`   | disparo de server function por ID com a semântica assíncrona da API 1.x                 |
-| `queries`     | execução de custom query por ID com parâmetros                                          |
-| `integration` | execução de integration resource ou proxy direto por config                             |
+An embedded preview can adopt the app-scoped session it receives from the platform without exchanging it:
 
-## Auth
+```typescript
+mitra.auth.setSession({ accessToken, refreshToken })
+await mitra.auth.checkAuth()
+```
+
+Proactive and reactive callers share one in-flight refresh. Successful refresh rotates and persists both tokens and updates the legacy session bridge without calling `auth.me()` or notifying public auth-state listeners. A refresh response that arrives after sign-out or after another login/session replacement is discarded and cannot restore or overwrite that newer state. Network failures, `408`, `429`, and `5xx` responses preserve the current session; the original HTTP request proceeds with the current token so a later `401` can use the reactive fallback. `auth.me()` also preserves that retained session when the fallback refresh is transient. Other IAM `4xx` responses are definitive and clear the session.
+
+JWT decoding is not user authentication. It schedules refresh and prevents cross-app session adoption. Every decodable access and refresh token must contain `app_id` exactly equal to the client's configured `appId`; opaque tokens are kept for rollout compatibility and remain validated by the server.
+
+Custom WebSocket or Server-Sent Events boundaries can refresh explicitly before connecting:
 
 ```typescript
-const user = await mitra.auth.signIn({
-  email: 'user@example.com',
-  password: 'password123',
-});
+const fresh = await mitra.auth.ensureFreshSession(30_000)
 
-const unsubscribe = mitra.auth.onAuthStateChange((currentUser) => {
-  console.log(currentUser?.email);
-});
+if (!fresh) {
+  // A required refresh failed. The SDK may still retain the session after a
+  // transient failure, but this boundary can choose whether to connect.
+}
+```
+
+`ensureFreshSession()` returns `true` when the token does not need refresh or refresh succeeds. It returns `false` when a required refresh fails, including a transient failure that intentionally preserves the current session.
+
+Google SSO uses a popup by default. The SDK opens `sdk-auth.html`, validates the popup source, origin, and one-time state, exchanges the returned code directly with IAM, stores both tokens, and fetches the current user:
 
-mitra.auth.signOut('/login');
-unsubscribe();
+```typescript
+const user = await mitra.auth.signInWithGoogle({ mode: "popup" })
+```
+
+The public Google options contain only `mode`. Account creation and locale are producer concerns, so the SDK does not send `create` or `language` to IAM. During rollout, the popup also accepts the older auth page token response.
+
+Deprecated `LoginOptions` still preserve `returnTo` and `title` for source compatibility. They are not copied into the new Google API: the legacy runtime never read `title`, did not pass caller `returnTo` into popup login, and hardcoded the current URL for redirect login.
+
+Redirect mode stores the one-time state and options in `sessionStorage`. Complete it during application startup before rendering authenticated routes:
+
+```typescript
+const redirectedUser = await mitra.auth.completeGoogleSignInRedirect()
+
+if (!redirectedUser) {
+  await mitra.auth.signInWithGoogle({ mode: "redirect" })
+}
 ```
 
-Estado de auth é persistido no `localStorage` com chave `mitra_auth_{appId}`. Em resposta `401`, o SDK tenta `refreshSession()` uma vez e repete a request.
+Redirect errors are accepted only when `stateMitra` matches the stored one-time state. A missing or mismatched state leaves the fragment and redirect context untouched and does not expose `errorMitra`. The current alpha `sdk-auth.html` error redirect omits `stateMitra`, so those error redirects are intentionally rejected until that producer echoes the state; popup errors already carry state and are unaffected.
+
+Configure the auth page explicitly when it is hosted outside the API gateway origin:
+
+```typescript
+const mitra = createClient({
+  appId,
+  apiUrl,
+  authPageUrl: "https://app.example.com/sdk-auth.html",
+})
+```
 
 ## Entities
 
 ```typescript
 type Task = {
-  id: string;
-  title: string;
-  status: 'pending' | 'done';
-};
+  id: string
+  title: string
+  status: "pending" | "done"
+}
 
-const tasks = await mitra.entities.getTable<Task>('Task').list({
-  sort: '-created_at',
+const { data: tasks } = await mitra.entities.getTable<Task>("Task").list({
+  sort: "-created_at",
   limit: 10,
-  fields: ['id', 'title', 'status'],
-});
+  fields: ["id", "title", "status"],
+})
 
-const pending = await mitra.entities.Task.filter({ status: 'pending' });
-const created = await mitra.entities.Task.create({ title: 'New task' });
-await mitra.entities.Task.update(created.id, { status: 'done' });
-await mitra.entities.Task.delete(created.id);
+const pending = await mitra.entities.Task.filter({ status: "pending" })
+const created = await mitra.entities.Task.create({ title: "New task" })
+await mitra.entities.Task.update(created.id, { status: "done" })
+await mitra.entities.Task.delete(created.id)
 ```
 
-Table names são case-sensitive e precisam bater com o nome da tabela no Data Manager.
+Table names are case-sensitive and must match the Data Manager table name. Record operations use `/api/v1/tables/{table}/records`. Application and tenant scope come from the authenticated context, not from a data source in the path.
+
+The native producer does not accept `jdbcConnectionConfigId` or `dataSourceId` on public record requests. The deprecated record helpers still expose their legacy arguments, but there is no native equivalent until Data Manager defines an app-safe backend contract. The SDK does not translate those arguments into query parameters or SQL.
 
-Records usam `/api/v1/tables/{table}/records`. O app e o tenant vêm do contexto autenticado, não do `dataSourceId` no path.
+`update(id, fields)` sends the Data Manager PUT contract, which applies the supplied fields as a partial record update and preserves omitted fields. A separate `patch` alias would duplicate that producer behavior, so the native surface keeps one method.
 
-## Functions
+## Server Functions
 
 ```typescript
-const execution = await mitra.functions.execute('function-id', {
-  orderId: 'order-123',
-});
+const execution = await mitra.functions.execute("function-id", {
+  orderId: "order-123",
+})
 
-console.log(execution.id, execution.status);
+console.log(execution.id, execution.status)
 ```
 
-Na API 1.x, `execute` não envia `X-Invocation-Type`. O serviço usa o default assíncrono e devolve a execução criada, normalmente com status `PENDING`; a chamada não espera a Function terminar.
+`execute` sends `X-Invocation-Type: sync` and waits for the terminal result. `executeAsync` sends `async` and returns the initial execution for polling or cancellation.
 
-## Queries
+The complete native lifecycle is also available. `getExecution` is kept because the Functions producer exposes execution polling and Agent consumers use it:
 
 ```typescript
-const result = await mitra.queries.execute('query-id', {
-  status: 'active',
-});
+const queued = await mitra.functions.executeAsync("function-id", { orderId: "order-123" })
+const current = await mitra.functions.getExecution(queued.id)
+await mitra.functions.cancelExecution(current.id)
+```
+
+Public Functions use a separate anonymous transport. It never adds `Authorization` or `X-App-Id`:
 
-console.log(result.rows, result.affectedRows);
+```typescript
+const result = await mitra.publicFunctions.execute("public-function-id", { sku: "A-1" })
+const queuedPublic = await mitra.publicFunctions.executeAsync("public-function-id", { sku: "A-1" })
 ```
 
-## Integration
+Public async execution is fire-and-forget. The public API does not expose anonymous polling or
+cancellation. Use synchronous `publicFunctions.execute` when the screen needs the result, or the
+authenticated `functions.executeAsync` plus `functions.getExecution` flow after login.
 
-Resource pré-definido:
+## Agent tasks and credentials
+
+The browser-safe Copilot modules call the native service directly. `agentTasks` provides list, read, create, rename, archive, HTTP input, history, and live sessions. These direct primitives match the Copilot producer and MCP contract. Core owns session state, queueing, recovery, and reconciliation; Platform supplies only authenticated browser WebSocket/SSE channels. `agentCredentials` provides safe credential status, model discovery, API key, OAuth, and device authorization flows. Raw credentials are write-only.
 
 ```typescript
-const result = await mitra.integration.executeResource('resource-id', {
-  descricao: 'Notebook',
+const credentials = await mitra.agentCredentials.list()
+const models = await mitra.agentCredentials.listModels()
+const chats = await mitra.agentTasks.list({ archived: false, size: 20 })
+```
+
+Create a live task lazily on the first message:
+
+```typescript
+const session = mitra.agentTasks.session({
+  create: true,
+  agentType: models[0].agentType,
+  reasoningEffort: models[0].reasoningOptions[0],
+})
+
+const unsubscribe = session.on("delta", ({ delta, kind }) => {
+  console.log(kind, delta)
+})
+
+session.send("Analyze this application")
+session.respondApproval(true)
+await session.cancel()
+unsubscribe()
+session.close()
+```
+
+Open an existing task with `session({ taskId })`. The default `auto` transport refreshes before connecting, opens `/copilot/ws/tasks/{taskId}`, and performs at most one safe recovery through persisted history plus the HTTP/SSE channel. Set `transport: "http"` when WebSockets are unavailable. Messages sent during a turn enter a FIFO queue with a maximum of 10 items; the session also exposes edit, remove, clear, approval, cancel, history, close, and typed events.
+
+API keys and removal accept `ANTHROPIC` or `OPENAI`. OAuth accepts only `ANTHROPIC`; device authorization accepts only `OPENAI`. The facade enforces those producer-supported pairs in TypeScript and at runtime.
+
+The browser token roles expose Agent tasks, credential status, and model discovery. Administrative business-Agent CRUD is intentionally not exposed by this adapter because the `USE` app role does not carry `AGENT_*` authority.
+
+## Custom queries
+
+```typescript
+const result = await mitra.queries.execute("query-id", {
+  status: "active",
+})
+
+console.log(result.rows, result.affectedRows)
+```
+
+Custom Query execution sends only `parameters`. Data Manager resolves its Data Source from the
+authenticated app, so Queries work without a caller-selected `dataSourceId` and do not depend on
+`init()`.
+
+## Integrations
+
+List the current app's saved configs without exposing the Core admin module:
+
+```typescript
+const configs = await mitra.integration.list({ page: 0, size: 20, sort: "alias,asc" })
+```
+
+The Integration producer derives the app from the authenticated token, so this list is app-scoped.
+
+Execute a predefined resource:
+
+```typescript
+const result = await mitra.integration.executeResource("resource-id", {
+  description: "Notebook",
   limit: 10,
-});
+})
+```
+
+Or execute an integration config directly:
+
+```typescript
+const result = await mitra.integration.execute("config-id", {
+  method: "GET",
+  endpoint: "/users",
+  queryParams: { limit: "10" },
+})
+
+console.log(result.status, result.body)
+```
+
+An app can also address a saved config by its app-scoped alias:
+
+```typescript
+const result = await mitra.integration.executeByAlias("billing", {
+  method: "POST",
+  endpoint: "/invoices",
+  body: { customerId: "customer-1" },
+})
 ```
 
-Proxy direto por config:
+Integration credentials are injected by the Integration service. Do not pass provider credentials through browser input.
+
+## Legacy surface
+
+The public surface of `mitra-interactions-sdk` is re-exported from this package so an application can replace the legacy dependency without rewriting its call sites. Runtime re-exports are marked `@deprecated` and name their replacement, or state that no replacement exists yet. Every legacy type is an identity-preserving alias marked as a deprecated compatibility type.
 
 ```typescript
-const result = await mitra.integration.execute('config-id', {
-  method: 'GET',
-  endpoint: '/users',
-  queryParams: { limit: '10' },
-});
+import { createClient, loginWithGoogleMitra } from "@mitralab.io/platform-sdk"
 
-console.log(result.status, result.body);
+export const mitra = createClient({ appId, apiUrl })
+
+await loginWithGoogleMitra()
+console.log(mitra.auth.accessToken)
 ```
 
-## Erros
+Google SSO is available through `mitra.auth.signInWithGoogle` and `mitra.auth.completeGoogleSignInRedirect`. Agent tasks, Agent credentials, public Functions, entities, custom queries, Function execution, and integrations now have native replacements. Microsoft SSO remains available only through the complete deprecated re-export surface.
+
+`createClient` configures the legacy SDK with both `baseURL` and `authUrl` set to `${apiUrl}/legacy`, after removing trailing slashes, plus `projectId: appId`. This keeps deprecated calls and legacy login routed through the BFF while the new modules call their native APIs directly. Its `authPageUrl` uses the same precedence as native Google SSO: explicit client config, `window.__mitraEnv.authPageUrl`, then `/sdk-auth.html` on the `apiUrl` origin. Existing query parameters are preserved.
 
-Erros de API lançam `MitraApiError`:
+The bridge shares the session in both directions. A session persisted under `mitra_auth_{appId}` is handed to the legacy SDK at startup; native sign-in, Google SSO, proactive or reactive refresh, manual token changes, and sign-out update its active configuration. Sessions produced by legacy login or refresh are persisted back under the same new storage key. The bridge only propagates sessions the two SDKs produce: it never starts a login and never triggers a refresh of its own.
+
+The legacy package exposes no sign-out API for deleting the refresh token stored in its private `mitra-session` entry. Native sign-out safely removes both credentials from the active legacy configuration, so deprecated calls cannot authenticate or refresh. A later direct call to `configureSdkMitra` can restore that private persisted refresh token; applications should keep configuration ownership in `createClient` during the migration.
+
+The legacy SDK does not return a user, so `auth.currentUser` stays empty after a legacy login. Call `mitra.auth.me()` to populate it. Calling `configureSdkMitra` directly replaces the legacy configuration and its refresh hook until the next bridged session change, so it should not be mixed with a client-managed migration.
+
+## Errors and request behavior
+
+API failures throw `MitraApiError`:
 
 ```typescript
-import { MitraApiError } from '@mitralab.io/platform-sdk';
+import { MitraApiError } from "@mitralab.io/platform-sdk"
 
 try {
-  await mitra.entities.Task.get('missing-id');
+  await mitra.entities.Task.get("missing-id")
 } catch (error) {
   if (error instanceof MitraApiError) {
-    console.error(error.status, error.code, error.message);
+    console.error(error.status, error.code, error.message)
   }
 }
 ```
 
-O transporte não segue redirects HTTP. Respostas 307, 308 ou respostas já
-marcadas como redirecionadas falham sem replay. A única repetição automática é
-a tentativa única após refresh bem-sucedido em resposta 401.
+The transport refuses HTTP redirects. Statuses `307` and `308`, opaque redirects, and responses already marked as redirected fail without replay. The only automatic replay is the single request attempted after reactive `401` recovery with either a refreshed token or a session that changed while the original request was in flight.
 
-Antes de construir `MitraApiError`, a SDK remove o token usado na tentativa e
-qualquer credencial no formato `Bearer` de `message`, `code` e `details`,
-percorrendo recursivamente valores, arrays e chaves de objetos.
+Before constructing `MitraApiError`, the SDK recursively redacts the token used by the request and credentials in `Bearer` format from the error message, code, details, arrays, values, and object keys. Values under credential fields such as `accessToken`, `refreshToken`, `apiKey`, `password`, `authorization`, `secret`, and `clientSecret` are also replaced with `[REDACTED]`.
 
-## Desenvolvimento
+## Development
 
 ```bash
 npm install
-npm run build
-npm run lint
-npm test
+npm run check
 ```
 
-`@mitralab.io/sdk-core@0.1.0` é resolvido pelo registry público do npm e fica
-travado por integridade no `package-lock.json`. Não substitua a dependência por
-`file:` ou tarball local.
+Platform `1.1.0-beta.0` targets exactly `@mitralab.io/sdk-core@0.2.0-beta.0`. Until that Core prerelease is published, local validation uses its matching tarball through `MITRA_SDK_CORE_TARBALL`. The manifest and lock keep the registry spec and the tarball's verified integrity; root `npm ci` becomes available after Core is published. Do not commit a `file:` dependency.
+
+The build produces ESM, CommonJS, `.d.ts`, and `.d.cts` artifacts. Package checks inspect the public tarball with Are The Types Wrong, install it into an isolated consumer, and validate ESM, CommonJS, and TypeScript resolution.
 
-Build gera CommonJS, ESM e tipos TypeScript em `dist/`.
+See [CHANGELOG.md](CHANGELOG.md) for release history and [LICENSE](LICENSE) for license terms.