@marinoscar/platform-web 0.0.0-stage → 0.1.0-next.4

package/dist/core/http/platform-api-client.d.ts

@@ -0,0 +1,61 @@
+import type { PlatformApiClient, PlatformRequestOptions, PlatformSseOptions } from '../api-client.js';
+import type { PlatformHttpClient, PlatformHttpRequestOptions } from './client.js';
+/**
+ * What {@link createPlatformApiClient} takes besides the client.
+ *
+ * @stability experimental
+ */
+export interface PlatformApiClientOptions {
+    /**
+     * `PlatformApiClient.postSse`: one POSTed request, one streamed
+     * `text/event-stream` answer, with the client's bearer token and refresh.
+     * Omit it and the adapter has no `postSse` (a page that needs it reports
+     * its absence). The reference app passes core's `postSse`.
+     * Errors it throws are mapped like every other call's.
+     */
+    postSse?(path: string, body: unknown, options: PlatformSseOptions): Promise<void>;
+}
+/**
+ * The client's {@link ApiError} as a `PlatformApiError` (a plain `Error` named
+ * `PlatformApiError` carrying `status`, `message` and, when present, `code`
+ * and `details`); anything else (a network failure, an abort) unchanged.
+ *
+ * @param error - what a {@link PlatformHttpClient} call rejected with.
+ * @returns the mapped error, or `error` itself.
+ *
+ * @stability experimental
+ */
+export declare function toPlatformApiError(error: unknown): unknown;
+/**
+ * `PlatformRequestOptions` as {@link PlatformHttpClient} request options. Extra
+ * `headers` (a link-share token's `x-link-token`, #731) go first, so
+ * `If-Match` and the client's own `Authorization` and `Content-Type` win.
+ *
+ * @param options - the packaged page's request options.
+ * @returns the client's request options, or `undefined` when none were given.
+ *
+ * @stability experimental
+ */
+export declare function toHttpRequestOptions(options: PlatformRequestOptions | undefined): PlatformHttpRequestOptions | undefined;
+/**
+ * Adapt the app's {@link PlatformHttpClient} to the `PlatformApiClient` every
+ * packaged page calls: the same token, the same refresh-and-retry, the same
+ * `onErrorResponse` hook; `ApiError` mapped by {@link toPlatformApiError};
+ * `getBlob` and `postBlob` through the client's `blobWithHeaders` response
+ * type. Build it ONCE, at module scope: packaged hooks key on its identity.
+ *
+ * @param http - the app's one HTTP client.
+ * @param options - an optional `postSse` implementation.
+ * @returns a frozen `PlatformApiClient`.
+ *
+ * @example
+ * ```ts
+ * export const api = new PlatformHttpClient({ baseUrl: '/api', refreshLockName: 'my-app-auth-refresh' });
+ * export const platformApi = createPlatformApiClient(api);
+ * ```
+ *
+ * @extensionPoint option
+ * @stability experimental
+ */
+export declare function createPlatformApiClient(http: PlatformHttpClient, options?: PlatformApiClientOptions): PlatformApiClient;
+//# sourceMappingURL=platform-api-client.d.ts.map

package/dist/core/http/platform-api-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"platform-api-client.d.ts","sourceRoot":"","sources":["../../../src/core/http/platform-api-client.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EACV,iBAAiB,EAGjB,sBAAsB,EACtB,kBAAkB,EACnB,MAAM,kBAAkB,CAAC;AAE1B,OAAO,KAAK,EAA+B,kBAAkB,EAAE,0BAA0B,EAAE,MAAM,aAAa,CAAC;AAE/G;;;;GAIG;AACH,MAAM,WAAW,wBAAwB;IACvC;;;;;;OAMG;IACH,OAAO,CAAC,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,kBAAkB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACnF;AAED;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAW1D;AAUD;;;;;;;;;GASG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,sBAAsB,GAAG,SAAS,GAAG,0BAA0B,GAAG,SAAS,CAWxH;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,uBAAuB,CACrC,IAAI,EAAE,kBAAkB,EACxB,OAAO,GAAE,wBAA6B,GACrC,iBAAiB,CA2CnB"}

package/dist/core/http/platform-api-client.js

@@ -0,0 +1,115 @@
+// =============================================================================
+// PlatformHttpClient -> PlatformApiClient (issue #868)
+// =============================================================================
+//
+// The browser HTTP client (`PlatformHttpClient`) is what the identity slice's
+// `AuthProvider` drives; the transport port (`PlatformApiClient`) is what every
+// packaged page calls. An app keeps ONE client and hands the pages this
+// adapter over it, so the bearer token, the one refresh-and-retry and the
+// app's error hook apply to every packaged call. Moved from the reference
+// app's `apps/web/src/platform/platformHost.tsx`, behaviour unchanged.
+// =============================================================================
+import { ApiError } from './client.js';
+/**
+ * The client's {@link ApiError} as a `PlatformApiError` (a plain `Error` named
+ * `PlatformApiError` carrying `status`, `message` and, when present, `code`
+ * and `details`); anything else (a network failure, an abort) unchanged.
+ *
+ * @param error - what a {@link PlatformHttpClient} call rejected with.
+ * @returns the mapped error, or `error` itself.
+ *
+ * @stability experimental
+ */
+export function toPlatformApiError(error) {
+    if (error instanceof ApiError) {
+        const mapped = Object.assign(new Error(error.message), {
+            name: 'PlatformApiError',
+            status: error.status,
+            ...(error.code === undefined ? {} : { code: error.code }),
+            ...(error.details === undefined ? {} : { details: error.details }),
+        });
+        return mapped;
+    }
+    return error;
+}
+async function mapped(call) {
+    try {
+        return await call();
+    }
+    catch (error) {
+        throw toPlatformApiError(error);
+    }
+}
+/**
+ * `PlatformRequestOptions` as {@link PlatformHttpClient} request options. Extra
+ * `headers` (a link-share token's `x-link-token`, #731) go first, so
+ * `If-Match` and the client's own `Authorization` and `Content-Type` win.
+ *
+ * @param options - the packaged page's request options.
+ * @returns the client's request options, or `undefined` when none were given.
+ *
+ * @stability experimental
+ */
+export function toHttpRequestOptions(options) {
+    if (options === undefined)
+        return undefined;
+    const headers = {
+        ...(options.headers ?? {}),
+        ...(options.ifMatch === undefined ? {} : { 'If-Match': options.ifMatch }),
+    };
+    return {
+        ...(options.signal === undefined ? {} : { signal: options.signal }),
+        ...(options.jsonBody === undefined ? {} : { body: JSON.stringify(options.jsonBody) }),
+        ...(Object.keys(headers).length === 0 ? {} : { headers }),
+    };
+}
+/**
+ * Adapt the app's {@link PlatformHttpClient} to the `PlatformApiClient` every
+ * packaged page calls: the same token, the same refresh-and-retry, the same
+ * `onErrorResponse` hook; `ApiError` mapped by {@link toPlatformApiError};
+ * `getBlob` and `postBlob` through the client's `blobWithHeaders` response
+ * type. Build it ONCE, at module scope: packaged hooks key on its identity.
+ *
+ * @param http - the app's one HTTP client.
+ * @param options - an optional `postSse` implementation.
+ * @returns a frozen `PlatformApiClient`.
+ *
+ * @example
+ * ```ts
+ * export const api = new PlatformHttpClient({ baseUrl: '/api', refreshLockName: 'my-app-auth-refresh' });
+ * export const platformApi = createPlatformApiClient(api);
+ * ```
+ *
+ * @extensionPoint option
+ * @stability experimental
+ */
+export function createPlatformApiClient(http, options = {}) {
+    const { postSse } = options;
+    const blob = (call) => mapped(call);
+    return Object.freeze({
+        // No options, no second argument: the call reaches the client exactly as
+        // an app's own code makes it.
+        get: (path, requestOptions) => mapped(() => requestOptions === undefined ? http.get(path) : http.get(path, toHttpRequestOptions(requestOptions))),
+        post: (path, body, requestOptions) => mapped(() => http.post(path, body, toHttpRequestOptions(requestOptions))),
+        put: (path, body, requestOptions) => mapped(() => http.put(path, body, toHttpRequestOptions(requestOptions))),
+        patch: (path, body, requestOptions) => mapped(() => http.patch(path, body, toHttpRequestOptions(requestOptions))),
+        delete: (path, requestOptions) => mapped(() => http.delete(path, toHttpRequestOptions(requestOptions))),
+        // A file upload: a multipart body, the boundary set by the browser.
+        postFormData: (path, body, requestOptions) => mapped(() => http.postFormData(path, body, toHttpRequestOptions(requestOptions))),
+        // Downloads: the raw body and the headers, through the same client.
+        getBlob: (path, requestOptions) => blob(() => http.get(path, {
+            ...toHttpRequestOptions(requestOptions),
+            responseType: 'blobWithHeaders',
+        })),
+        postBlob: (path, body, requestOptions) => blob(() => http.post(path, body, {
+            ...toHttpRequestOptions(requestOptions),
+            responseType: 'blobWithHeaders',
+        })),
+        ...(postSse === undefined
+            ? {}
+            : {
+                postSse: (path, body, sseOptions) => mapped(() => postSse(path, body, sseOptions)),
+            }),
+    });
+}
+//# sourceMappingURL=platform-api-client.js.map

package/dist/core/http/platform-api-client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"platform-api-client.js","sourceRoot":"","sources":["../../../src/core/http/platform-api-client.ts"],"names":[],"mappings":"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"}

package/dist/core/http/sse.d.ts

@@ -0,0 +1,284 @@
+/**
+ * A fetch-based Server-Sent Events client.
+ *
+ * Issue #127, epic #109.
+ *
+ * =============================================================================
+ * WHY THIS FILE EXISTS AT ALL — `EventSource` CANNOT SEND AN AUTHORIZATION HEADER
+ * =============================================================================
+ *
+ * `GET /api/notifications/stream` is guarded by the ordinary bearer `@Auth()`,
+ * exactly like every other endpoint. The native `EventSource` constructor takes
+ * a URL and `withCredentials`, and NOTHING ELSE — there is no headers argument
+ * and no way to add one. So the browser's built-in SSE client cannot
+ * authenticate against that route.
+ *
+ * The two ways out, and why this is the one taken:
+ *
+ *   1. REJECTED — `?token=…` on the stream URL. The API refused this
+ *      deliberately (see the long note on `NotificationsController.stream`), and
+ *      the refusal is right: a URL query string is written verbatim into the
+ *      nginx access log, kept in browser history, and forwarded in `Referer` to
+ *      any third party the page later touches. That turns a live bearer
+ *      credential into something replayable out of a log file retained for
+ *      months and readable by people who are not supposed to hold sessions.
+ *      Cheap transport is not worth credentials in logs.
+ *
+ *   2. CHOSEN — `fetch()` with a real `Authorization` header, reading
+ *      `response.body` as a `ReadableStream` and parsing the SSE framing here.
+ *      `fetch` takes arbitrary headers; the cost is that everything
+ *      `EventSource` does for free — framing, reconnection, backoff — has to be
+ *      written, which is what the rest of this file is.
+ *
+ * WHY HAND-ROLLED RATHER THAN A DEPENDENCY (`@microsoft/fetch-event-source`).
+ * This worktree cannot take a new dependency, and on inspection it does not
+ * need one: the whole client is the parser below plus a retry loop, both of
+ * which are small, fully testable without a network, and — unlike a
+ * dependency — able to reuse the `PlatformHttpClient` token and refresh
+ * machinery directly rather than through a callback shim. A library would also
+ * bring its own opinions about 401 handling, which is precisely the part that
+ * has to match `core/http/client.ts` exactly.
+ *
+ * =============================================================================
+ * WHAT THIS CLIENT DOES NOT DO, AND MUST NOT BE MADE TO DO
+ * =============================================================================
+ *
+ * IT DOES NOT GUARANTEE DELIVERY. Anything the server publishes while this
+ * connection is down is GONE: the API holds no buffer, honours no
+ * `Last-Event-ID`, and has no replay log (`NotificationStreamService`'s header
+ * says so in as many words). This client therefore reports every (re)connection
+ * through `onOpen`, and ITS CALLER IS REQUIRED TO REFETCH on that signal. Do
+ * not add replay here; the `notifications` table is the source of truth and one
+ * indexed query after a gap is strictly more reliable than any cursor built on
+ * top of a stream.
+ *
+ * `lastEventId` is parsed and tracked because the SSE grammar has the field and
+ * a parser that silently dropped it would be wrong — but it is NOT sent back as
+ * `Last-Event-ID` on reconnect, because the server does not implement it and a
+ * header that looks like resumption but resumes nothing is worse than no header
+ * at all.
+ */
+/**
+ * One dispatched SSE event.
+ *
+ * @stability experimental
+ */
+export interface SseFrame {
+    /**
+     * The `event:` name, or `'message'` when the frame declared none.
+     *
+     * Defaulted here rather than left `undefined` so a consumer switching on the
+     * name never has to spell the default itself. The API always names its
+     * frames (`notification`), so a `'message'` arriving is a signal that
+     * something upstream changed.
+     */
+    event: string;
+    /**
+     * The `data:` payload, with multiple `data:` lines joined by `\n` and the
+     * trailing newline removed, per the SSE grammar.
+     */
+    data: string;
+    /** The `id:` field of this frame, or `null`. Tracked, never sent back. */
+    id: string | null;
+}
+/**
+ * An incremental SSE stream parser.
+ *
+ * Fed decoded text in arbitrary chunks — a network read boundary can land
+ * anywhere, including in the middle of a UTF-8 sequence, in the middle of a
+ * field name, or between the CR and LF of one line terminator — and emits whole
+ * frames only. Every one of those splits is a real thing that happens under
+ * load and each has its own comment below.
+ *
+ * Deliberately a plain class with no I/O so the framing rules can be tested by
+ * calling a method with a string.
+ *
+ * @stability experimental
+ */
+export declare class SseParser {
+    /** Bytes seen but not yet terminated by a line ending. */
+    private buffer;
+    /** The event-type buffer, per spec: reset to '' after every dispatch. */
+    private eventType;
+    /** The data buffer, per spec: accumulated across `data:` lines. */
+    private data;
+    /** This frame's `id:`, distinct from `lastEventId` below. */
+    private frameId;
+    /**
+     * The last non-null `id:` seen on the stream.
+     *
+     * Public because it is genuinely part of the stream's state, and read by
+     * nothing today — see the header on why it is not sent back.
+     */
+    lastEventId: string | null;
+    /**
+     * The server's most recent `retry:` directive, in milliseconds, or `null`.
+     *
+     * A STREAM-LEVEL directive, not a per-frame one: it sets the reconnection
+     * delay for every subsequent reconnect until the server says otherwise, which
+     * is why it lives on the parser rather than on `SseFrame`. This API never
+     * sends one; it is honoured anyway because ignoring a server that asks to be
+     * reconnected to more slowly is how a client turns a struggling backend into
+     * a hammered one.
+     */
+    retryMs: number | null;
+    /**
+     * Feed one decoded chunk; get back every frame it completed.
+     *
+     * @param chunk - decoded text. MUST come from a streaming decoder — see
+     *        `TextDecoder({ stream: true })` at the call site. Decoding each
+     *        network chunk independently corrupts any multi-byte character that
+     *        straddles a chunk boundary, which for this API means a notification
+     *        body with an accent or an emoji in it arrives mangled roughly
+     *        whenever it is unlucky about packet size.
+     */
+    push(chunk: string): SseFrame[];
+    private handleLine;
+    private dispatch;
+}
+/**
+ * What the connection is doing right now, for the UI to render honestly.
+ *
+ * `'reconnecting'` is deliberately distinct from `'connecting'`: the first
+ * connection attempt and a recovery after a drop look identical to the network
+ * stack but not to a user, who has already seen the feature working once.
+ *
+ * @stability experimental
+ */
+export type SseState = 'connecting' | 'open' | 'reconnecting' | 'closed';
+/**
+ * Options for {@link connectSse}.
+ *
+ * @stability experimental
+ */
+export interface SseOptions {
+    /** Absolute or root-relative URL of the event stream. */
+    url: string;
+    /**
+     * The `Authorization` header value for the NEXT attempt, or `null` for none.
+     *
+     * A FUNCTION, called fresh on every attempt, not a captured string. Access
+     * tokens are 15 minutes and this connection is meant to outlive many of them;
+     * a value read once at setup would be stale on exactly the reconnect that
+     * follows a long sleep — the moment reconnection matters most.
+     */
+    authorization: () => string | null;
+    /**
+     * The stream returned 401. Renew credentials and return whether it worked.
+     *
+     * Returning `false` STOPS the loop permanently — the session is gone, and a
+     * client that kept retrying would spend the rest of the tab's life issuing
+     * 401s at a logged-out backend.
+     */
+    reauthenticate: () => Promise<boolean>;
+    /**
+     * The stream is open and its headers have arrived.
+     *
+     * ⚠️ FIRES ON EVERY CONNECTION, INCLUDING EVERY RECONNECT, AND THE CALLER MUST
+     * REFETCH ON IT. See this file's header: nothing published during the gap is
+     * replayed, so this callback is the only thing standing between a dropped
+     * connection and a permanently stale unread count.
+     */
+    onOpen: () => void;
+    /** One dispatched frame. Heartbeat comments never reach here. */
+    onFrame: (frame: SseFrame) => void;
+    /** Connection state transitions, for rendering. Optional. */
+    onStateChange?: (state: SseState) => void;
+}
+/**
+ * A live connection. Idempotent `close()`.
+ *
+ * @stability experimental
+ */
+export interface SseConnection {
+    /** Close the connection for good; safe to call more than once. */
+    close: () => void;
+}
+/**
+ * Open an SSE connection and keep it open, reconnecting with backoff until
+ * `close()` is called.
+ *
+ * Returns synchronously; the connection is established in the background. The
+ * returned `close()` aborts an in-flight request, cancels a pending retry, and
+ * detaches every listener — it is what an effect cleanup calls, and it must
+ * remain safe to call at any point in the lifecycle, including before the first
+ * fetch has resolved.
+ *
+ * @stability experimental
+ */
+export declare function connectSse(options: SseOptions): SseConnection;
+/**
+ * Options for {@link postSse}.
+ *
+ * @stability experimental
+ */
+export interface PostSseOptions<T> {
+    /** Absolute or base-relative URL — resolve it against `API_BASE_URL`. */
+    url: string;
+    /** JSON-serialised as the request body. */
+    body: unknown;
+    /** The full `Authorization` header value (`Bearer …`), or null for none. */
+    authorization: () => string | null;
+    /** Renew the access token after a 401. Called at most once per request. */
+    reauthenticate: () => Promise<unknown>;
+    /**
+     * One parsed frame: its `event:` name and its `data:` parsed as JSON (the raw
+     * string when it is not JSON). Comment lines (`: ping`) never arrive here.
+     */
+    onFrame: (event: string, data: T) => void;
+    /** Aborting resolves the promise quietly — cancelling is not an error. */
+    signal?: AbortSignal;
+    /**
+     * Called with every non-2xx response's status and parsed JSON error body,
+     * before the {@link ApiError} is thrown (the error is thrown either way). The
+     * same side channel as `PlatformHttpClientOptions.onErrorResponse`: the
+     * reference app notices a maintenance window here.
+     */
+    onErrorResponse?: (status: number, body: PostSseErrorBody) => void;
+}
+/**
+ * The JSON error envelope `postSse` parses off a non-2xx response.
+ *
+ * @stability experimental
+ */
+export interface PostSseErrorBody {
+    /** The API's message. */
+    message?: string;
+    /** The API's machine-readable error code. */
+    code?: string;
+    /** The error envelope's `details`. */
+    details?: unknown;
+}
+/**
+ * POST a JSON body and stream the `text/event-stream` answer, frame by frame.
+ *
+ * `connectSse` above is the wrong tool for a request/response stream and is
+ * deliberately left alone: it is GET-only, and it RECONNECTS — right for a
+ * notification feed that should live as long as the tab, exactly wrong for
+ * "generate one answer to this prompt", where a reconnect would re-submit the
+ * prompt and bill the user twice. So this is the other shape:
+ *
+ * - ONE request. No reconnect, ever. The promise resolves when the server ends
+ *   the stream.
+ * - ONE 401 retry, through `reauthenticate` — the same single refresh-and-retry
+ *   `PlatformHttpClient.request` does, so an access token that expired just before the
+ *   click does not surface as an error. A second 401 rejects.
+ * - A NON-2xx REJECTS WITH `ApiError`, the error every other call site already
+ *   catches, with `code`/`details` parsed from the JSON error body. The server
+ *   runs every gate (AI disabled, no key, model not enabled) BEFORE the first
+ *   byte precisely so those failures arrive here as ordinary JSON errors; a
+ *   failure AFTER streaming began arrives as a frame (`event: error`) instead,
+ *   and is the caller's to handle. Every non-2xx is handed to `onErrorResponse` on the
+ *   way past (the app's maintenance recogniser), exactly as the HTTP
+ *   client's `toError` does.
+ * - ABORT RESOLVES. A caller that aborts (a Stop button, an unmount) asked for
+ *   the stream to end; rejecting would make every such caller write a catch
+ *   that ignores `AbortError`.
+ *
+ * Same parser as `connectSse` (`SseParser`), same credential posture (a real
+ * `Authorization` header, never a token in the URL — see this file's header).
+ *
+ * @stability experimental
+ */
+export declare function postSse<T>(options: PostSseOptions<T>): Promise<void>;
+//# sourceMappingURL=sse.d.ts.map

package/dist/core/http/sse.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sse.d.ts","sourceRoot":"","sources":["../../../src/core/http/sse.ts"],"names":[],"mappings":"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"}