@mitralab.io/platform-sdk 1.0.9 → 1.1.0-beta.1

package/CHANGELOG.md

@@ -2,8 +2,40 @@
 
 All notable changes to this project are documented in this file.
 
-## Unreleased
+## 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.

package/README.md

@@ -3,9 +3,9 @@
 [![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)
 
-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, and call integrations.
+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.
 
-The browser transport uses standard Web APIs only: `fetch`, `localStorage`, `URL`, and `Proxy`. Shared contracts and API modules come from `@mitralab.io/sdk-core`, without bringing browser authentication into the Core package.
+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.
 
 ## Installation
 
@@ -29,7 +29,11 @@ export const mitra = createClient({
 await mitra.init()
 ```
 
-`init()` resolves the application's public Code Studio configuration, including `dataSourceId` and `allowSignup`. Call it during application startup before using entities, custom queries, or sign-up.
+`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
 
@@ -37,29 +41,30 @@ await mitra.init()
 |---|---|---|
 | `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`, and `/code-studio`.
+The client derives service endpoints from `apiUrl`: `/iam`, `/data-manager`, `/functions`, `/integration`, `/copilot`, and `/code-studio`.
 
 ## Boundary
 
 The Platform SDK owns:
 
-- browser login, sign-up, logout, and session refresh
+- browser Google SSO, logout, and session refresh
+- trusted session adoption for the embedded app preview
 - session persistence in `localStorage`
 - auth-state listeners
-- one retry after a successful token refresh on a `401` response
+- 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
 
-`@mitralab.io/sdk-core` owns the shared entities, custom queries, Functions, integrations, `auth.me`, safe paths, and structural response validation. Server Function code should use `@mitralab.io/functions-sdk` instead of this browser SDK.
+`@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.signIn({
-  email: "user@example.com",
-  password: "password123",
-})
+const user = await mitra.auth.signInWithGoogle({ mode: "popup" })
 
 const unsubscribe = mitra.auth.onAuthStateChange((currentUser) => {
   console.log(currentUser?.email)
@@ -69,7 +74,65 @@ mitra.auth.signOut("/login")
 unsubscribe()
 ```
 
-Authentication state is stored under `mitra_auth_{appId}`. When an API request returns `401`, the SDK attempts `refreshSession()` once and repeats the request only when refresh succeeds.
+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.
+
+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.
+
+An embedded preview can adopt the app-scoped session it receives from the platform without exchanging it:
+
+```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 fresh = await mitra.auth.ensureFreshSession(30_000)
+
+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:
+
+```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" })
+}
+```
+
+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
 
@@ -80,7 +143,7 @@ type Task = {
   status: "pending" | "done"
 }
 
-const tasks = await mitra.entities.getTable<Task>("Task").list({
+const { data: tasks } = await mitra.entities.getTable<Task>("Task").list({
   sort: "-created_at",
   limit: 10,
   fields: ["id", "title", "status"],
@@ -94,6 +157,10 @@ await mitra.entities.Task.delete(created.id)
 
 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.
+
+`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.
+
 ## Server Functions
 
 ```typescript
@@ -104,7 +171,62 @@ const execution = await mitra.functions.execute("function-id", {
 console.log(execution.id, execution.status)
 ```
 
-The Platform SDK 1.x `execute` method keeps the existing asynchronous API behavior. It does not send `X-Invocation-Type`, so the Functions service applies its default and returns the created execution, normally with `PENDING` status.
+`execute` sends `X-Invocation-Type: sync` and waits for the terminal result. `executeAsync` sends `async` and returns the initial execution for polling or cancellation.
+
+The complete native lifecycle is also available. `getExecution` is kept because the Functions producer exposes execution polling and Agent consumers use it:
+
+```typescript
+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`:
+
+```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" })
+```
+
+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.
+
+## 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 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
 
@@ -116,8 +238,20 @@ const result = await mitra.queries.execute("query-id", {
 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
@@ -139,8 +273,41 @@ const result = await mitra.integration.execute("config-id", {
 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" },
+})
+```
+
 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
+import { createClient, loginWithGoogleMitra } from "@mitralab.io/platform-sdk"
+
+export const mitra = createClient({ appId, apiUrl })
+
+await loginWithGoogleMitra()
+console.log(mitra.auth.accessToken)
+```
+
+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.
+
+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`:
@@ -157,9 +324,9 @@ try {
 }
 ```
 
-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 a successful session refresh on `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.
 
-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.
+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]`.
 
 ## Development
 
@@ -168,7 +335,7 @@ npm install
 npm run check
 ```
 
-`@mitralab.io/sdk-core@0.1.0` is resolved from the public npm registry and locked by integrity in `package-lock.json`. Do not replace it with a `file:` dependency or a local tarball.
+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.