@mitralab.io/platform-sdk 1.1.2 → 1.2.0-beta.1

package/CHANGELOG.md

@@ -2,6 +2,62 @@
 
 All notable changes to this project are documented in this file.
 
+## 1.1.3
+
+- A chat created through `session({ create: true })` over the `auto` or `websocket` transport is
+  born on the T3 box: the create request carries `runtime: "T3"`. A chat created with
+  `transport: "http"` stays on the runner, and an explicit `runtime` is forwarded as given.
+- The box channel is asked for once. The Copilot now holds the channel request while the box
+  boots, so the 2 s polling on a 202 answer is gone; a 202 from an older Copilot means the chat
+  follows the Copilot socket.
+- Depend on `@mitralab.io/sdk-core@0.2.4`, which carries the `runtime` session option into the
+  create request, exports `AgentTaskRuntime`, and sends a prompt whose task already exists even
+  when the session was closed inside its `taskCreated` handler.
+
+## 1.2.0-beta.1
+
+- Add `signInWithEmail()`: the platform auth page collects the address and the one-time code, and
+  the single-use exchange code it returns is redeemed at IAM's `/auth/magic-link/exchange` for the
+  same app session Google and Microsoft SSO already produce.
+- Add `completeEmailSignInRedirect()`, which finishes both the mobile redirect and the tab opened
+  by the link in the message.
+- Keep the pending email request, the one-time state and the auth page URL and never a token, in
+  `localStorage` for 10 minutes, so the tab opened by the link in the message finishes the flow
+  through the same state check the redirect uses. Writing it is best effort for a popup and
+  required for a redirect.
+- Consume a fragment of the flow's own provider even when it cannot be completed, so a rejected or
+  expired redirect is reported once instead of on every reload. A fragment of another flow stays
+  untouched, and a pending request is still dropped only when it expires.
+- Name the flow in the one-time state (`google.<random>`, `microsoft.<random>`, `email.<random>`),
+  which the auth page echoes verbatim, so every `complete*SignInRedirect()` recognizes its own
+  fragment: a fragment from another method returns `null` untouched, whatever this browser has
+  pending, and an application that offers all three can call all three at startup in any order. A
+  fragment that names this flow without matching its pending request is rejected as forged.
+- Generalize the auth page handshake into `AuthPageFlow`, parameterized by provider, exchange
+  route, and where the pending request lives, instead of a second copy for email.
+- Upgrading mid-flow: a redirect started by an earlier version stored a state without the provider
+  name, so the completion after the upgrade returns `null` and the person signs in again. Nothing
+  is lost beyond that one attempt, and only for redirects in flight during the upgrade.
+- Give each provider its own popup window name.
+- Point the deprecated `signIn` and `signUp` failures at `signInWithEmail()`.
+- Add `mitra.emailLoginEnabled`, read from `/info` during `init()` next to `allowSignup`, so an
+  application only offers "sign in with email" when this app is inside the platform's rollout.
+  A Code Studio older than the field answers without it, and any value that is not a boolean is
+  read as `false`, so `init()` keeps working and an app that cannot prove it is enabled stops
+  offering the option.
+
+## 1.1.2
+
+- Move the `@mitralab.io/sdk-core` pin from `0.2.1` to `0.2.2`: same surface, published with the
+  contract corpus that consumers pin, so every SDK released that day sits on the same core.
+
+## 1.1.1
+
+- Depend on `@mitralab.io/sdk-core@0.2.1`, which replays `textChunk` and late deltas after an
+  interrupted turn.
+- Serve the Agent chat from the T3 box over the direct channel when the Copilot offers it.
+- Treat a half-open Agent session channel as a disconnect instead of a live one.
+
 ## 1.1.0-beta.2
 
 `1.1.0-beta.1` was published from `main` before this change landed, so it still depends on Core `0.2.0-beta.0`; use `1.1.0-beta.2`.

package/README.md

@@ -30,10 +30,10 @@ await mitra.init()
 ```
 
 `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`.
+`dataSourceId`, `allowSignup`, and `emailLoginEnabled`. 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` or the login screen needs `emailLoginEnabled`.
 
 ## Configuration
 
@@ -50,7 +50,7 @@ The client derives service endpoints from `apiUrl`: `/iam`, `/data-manager`, `/f
 
 The Platform SDK owns:
 
-- browser Google SSO, logout, and session refresh
+- browser Google and Microsoft SSO, browser email sign-in, logout, and session refresh
 - trusted session adoption for the embedded app preview
 - session persistence in `localStorage`
 - auth-state listeners
@@ -76,7 +76,7 @@ unsubscribe()
 
 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.
+A generated application signs people in with Google SSO, Microsoft SSO, or email. The old native `signIn` and `signUp` names fail locally with `UNSUPPORTED_AUTH_METHOD` because IAM has no email/password endpoints; `signInWithEmail()` is the email flow that replaced them. Deprecated login bindings remain available only through the legacy reexports.
 
 ### Signing in as a process
 
@@ -158,6 +158,89 @@ const mitra = createClient({
 })
 ```
 
+### Signing in with email
+
+Email sign-in needs neither a password nor an SSO account. The same platform page opens, a popup
+by default, collects the address, sends a six-digit code, and IAM answers with a single-use
+exchange code that the SDK redeems at `/iam/api/v1/auth/magic-link/exchange`. What comes back is
+the app session SSO already returns, persisted and refreshed the same way:
+
+```typescript
+const user = await mitra.auth.signInWithEmail()
+```
+
+Not every app is in the rollout. `mitra.emailLoginEnabled` is this app's own verdict, read from
+`/info` during `init()`, and it is what a login screen should offer the option on:
+
+```typescript
+await mitra.init()
+
+if (mitra.emailLoginEnabled) {
+  // render "sign in with email"
+}
+```
+
+It is `false` before `init()` runs, `false` when the server answers without the field or with
+something that is not a boolean, and `false` is the safe answer: the app is outside the rollout,
+IAM answers a request neutrally without sending anything, and the person would wait for a message
+that never arrives. Calling `signInWithEmail()` anyway is not blocked by the SDK; the verdict is
+there so the application does not offer a door that does not open.
+
+Redirect mode navigates the current page instead of opening a popup, and is completed during
+startup like the SSO redirect:
+
+```typescript
+await mitra.auth.signInWithEmail({ mode: "redirect" })
+```
+
+```typescript
+const emailUser = await mitra.auth.completeEmailSignInRedirect()
+```
+
+Call `completeEmailSignInRedirect()` at startup even when sign-in was started as a popup, because
+the message carries a link as well as the code, and that link opens a **new tab**. That tab never
+saw the popup, so the pending request has to outlive the tab that opened it: the one-time state
+and the resolved auth page URL are written to `localStorage` under `mitra_email_redirect_{appId}`
+for 10 minutes, dropped when the flow completes, or discarded as stale the next time a result is read. `sessionStorage`,
+which the SSO redirect uses, is scoped to a single tab and cannot answer for another one. The link still has
+to be opened in the same browser that started the sign-in: another browser or device has no pending request,
+refuses the fragment, and the exchange code was already spent by the page. On another device, use the
+six-digit code in the popup instead.
+
+**No token is written there.** What is persisted is only the record of a request already in
+flight, which is the smallest thing that lets the other tab finish it, and it expires on its own.
+The tab opened by the link comes back with the same one-time state the flow started with, so it
+is completed by exactly the check the redirect uses; a request older than 10 minutes is discarded
+rather than completed. Writing the request is best effort for a popup: without `localStorage` the
+popup still signs in and only the completion from the link is lost, while redirect mode, which has
+nowhere else to keep it, fails at the start.
+
+When the person finishes in the tab the link opened, the `signInWithEmail()` call still waiting in
+the original tab eventually times out. Treat that rejection as a cancelled popup: the session is
+already established wherever the application called `completeEmailSignInRedirect()`.
+
+One fragment belongs to one flow, and an application that offers more than one method can call
+every completion at startup, in any order:
+
+```typescript
+const user =
+  (await mitra.auth.completeEmailSignInRedirect()) ??
+  (await mitra.auth.completeGoogleSignInRedirect()) ??
+  (await mitra.auth.completeMicrosoftSignInRedirect())
+```
+
+A chain like that propagates a rejection: an expired request or a forged fragment on the first
+completion keeps the others from running. Wrap each call in `try`/`catch` when the application
+should still try the remaining methods after one of them refuses a fragment.
+
+The one-time state each flow generates names that flow, as in `google.<random>` or
+`email.<random>`, and the auth page echoes it verbatim, so a completion recognizes its own
+fragment. A fragment from another method returns `null` and leaves the fragment and that other
+flow's pending request untouched, whatever this browser has pending. A fragment that does name
+this flow but does not match its pending request is rejected as forged, and the fragment is
+removed from the URL on the way out, so the rejection is reported once instead of on every
+reload.
+
 ## Entities
 
 ```typescript
@@ -246,7 +329,9 @@ unsubscribe()
 session.close()
 ```
 
-Open an existing task with `session({ taskId })`. The default `auto` transport refreshes before connecting, asks the Copilot where the chat is served, and opens whichever channel it names: the box that runs the agent when one is offered, `/copilot/ws/tasks/{taskId}` otherwise. The choice belongs to the server, never to application configuration, so a Copilot that stops offering the box leaves every application on the Copilot socket without a republish. Opening the box never asks it to replay, whether the conversation is new to the session or is being opened again after an idle close: what an idle conversation missed is history, which the application loads over REST. A box socket that drops in the middle of a turn is redialed by the SDK itself, with a bounded backoff (1, 2, 4, 8 and 16 seconds) and the replay from the last position seen on that socket, so the answer keeps streaming; a position taken on one box is forgotten when the Copilot points the conversation to another box; replayed `textChunk` frames reach the `delta` event like live text. While that happens the session emits `raw` events of type `channelReconnecting` (payload `attempt`, `maxAttempts`, `reason`) and `channelConnected` (payload `attempt`); the session `status` stays `streaming`, because Core has no reconnecting status. The disconnect reaches Core, and with it the `error` event, only when the attempts run out or the Copilot no longer offers the box. A drop with no turn in flight, a channel taken over by another tab (close code 4409), and any close of the Copilot socket the session did not ask for are reported at once, whatever the code, so the next send reopens the channel instead of waiting on a socket that is gone. Recovery through persisted history plus the HTTP/SSE channel is unchanged. 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.
+A chat created with `create: true` over the `auto` or `websocket` transport is born on the T3 box (`runtime: "T3"` in the create request), so the first open does not wait for the box to adopt it; a chat created with `transport: "http"` stays on the Copilot runner. Pass `runtime: "RUNNER"` or `runtime: "T3"` to decide explicitly.
+
+Open an existing task with `session({ taskId })`. The default `auto` transport refreshes before connecting, asks the Copilot once where the chat is served, and opens whichever channel it names: the box that runs the agent when one is offered, `/copilot/ws/tasks/{taskId}` otherwise. The Copilot holds that request while the box boots and answers only once the box is ready or cannot be had; the SDK does not poll. The choice belongs to the server, never to application configuration, so a Copilot that stops offering the box leaves every application on the Copilot socket without a republish. Opening the box never asks it to replay, whether the conversation is new to the session or is being opened again after an idle close: what an idle conversation missed is history, which the application loads over REST. A box socket that drops in the middle of a turn is redialed by the SDK itself, with a bounded backoff (1, 2, 4, 8 and 16 seconds) and the replay from the last position seen on that socket, so the answer keeps streaming; a position taken on one box is forgotten when the Copilot points the conversation to another box; replayed `textChunk` frames reach the `delta` event like live text. While that happens the session emits `raw` events of type `channelReconnecting` (payload `attempt`, `maxAttempts`, `reason`) and `channelConnected` (payload `attempt`); the session `status` stays `streaming`, because Core has no reconnecting status. The disconnect reaches Core, and with it the `error` event, only when the attempts run out or the Copilot no longer offers the box. A drop with no turn in flight, a channel taken over by another tab (close code 4409), and any close of the Copilot socket the session did not ask for are reported at once, whatever the code, so the next send reopens the channel instead of waiting on a socket that is gone. Recovery through persisted history plus the HTTP/SSE channel is unchanged. 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.
 
 A prompt sent while the browser says it is offline (`navigator.onLine === false`) does not enter Core at all, because Core opens the channel and reads the turn baseline before the prompt goes out and every one of those requests would fail first: the session keeps the prompt in an outbox, emits a `raw` event of type `inputUnsent` (payload `attempt` 0, `reason`, `waitingForOnline` true) and hands it to Core, in order, when the browser fires `online`; the turn starts then. A prompt whose `POST /inputs` went out but got no response at all is kept the same way: the session sends the same request again when the browser fires `online` or on a bounded backoff (2, 5, 10, 20 and 40 seconds), while the turn stays `streaming`, with `inputUnsent` events (payload `attempt`, `reason`, `waitingForOnline`, `retryInMs` when a timer is armed) and, once it goes through, `inputSent` (payload `attempts`). A response from the server, an error included, is never retried: the prompt fails through the `error` event as before. A session closed with a prompt still waiting emits `error` with code `INPUT_UNSENT` before it goes quiet, and `sendAndWait` rejects. The retry cannot tell a request the server never received from one whose response was lost on the way back, so a prompt may reach the server twice in that case; the Copilot's `/inputs` accepts no client message id yet. The public `agentTasks.sendInput` primitive is not held back: it fails immediately, as it always did.
 
@@ -324,7 +409,7 @@ 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.
+Google, Microsoft and e-mail sign-in have native replacements: `mitra.auth.signInWithGoogle`, `mitra.auth.signInWithMicrosoft` and `mitra.auth.signInWithEmail`, each with its `complete...SignInRedirect` counterpart. Agent tasks, Agent credentials, public Functions, entities, custom queries, Function execution, and integrations also have native replacements. Only `loginMitra('mitra')` still has no native equivalent and remains available through the 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.