@marinoscar/platform-web 0.1.0-next.3 → 0.1.0-next.4

package/dist/android-app/ui/settings-page.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"settings-page.js","sourceRoot":"","sources":["../../../src/android-app/ui/settings-page.ts"],"names":[],"mappings":"AAAA,OAAO,wBAAwB,MAAM,0CAA0C,CAAC;AAGhF,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AACrD,OAAO,EAAE,uBAAuB,EAAE,gBAAgB,EAAE,2BAA2B,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAC;AAEtH;;;;;;;;;;;;;;;GAeG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAgC;IACjE,EAAE,EAAE,aAAa;IACjB,IAAI,EAAE;QACJ,KAAK,EAAE,iBAAiB;QACxB,WAAW,EAAE,uBAAuB;QACpC,IAAI,EAAE,gBAAgB;QACtB,UAAU,EAAE,2BAA2B;KACxC;IACD,IAAI,EAAE,wBAAwB;IAC9B,IAAI,EAAE,cAAc;CACrB,CAAC"}

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

@@ -41,6 +41,14 @@ export interface PlatformApiClient {
      * needs it reports its absence.
      */
     postSse?(path: string, body: unknown, options: PlatformSseOptions): Promise<void>;
+    /**
+     * `POST path` with a `multipart/form-data` body (a file upload): resolves to
+     * the response's `data`, rejects with a {@link PlatformApiError}. The
+     * transport sets the multipart boundary itself. Optional, like
+     * {@link PlatformApiClient.getBlob}; a page that needs it reports its
+     * absence.
+     */
+    postFormData?<T>(path: string, body: FormData, options?: PlatformRequestOptions): Promise<T>;
 }
 /**
  * Per-request options every {@link PlatformApiClient} method takes. All
@@ -53,6 +61,18 @@ export interface PlatformRequestOptions {
     signal?: AbortSignal;
     /** Sent as the `If-Match` header (optimistic concurrency, `docs/API.md`). */
     ifMatch?: string;
+    /**
+     * Extra request headers, e.g. a link-share token in `x-link-token` (#731).
+     * The transport keeps its own (`Authorization`, `Content-Type`, `If-Match`
+     * from {@link PlatformRequestOptions.ifMatch}); a transport that cannot
+     * send custom headers ignores them, so a page that needs one says so.
+     */
+    headers?: Readonly<Record<string, string>>;
+    /**
+     * A JSON body for a `DELETE` that needs one (a typed confirmation). Ignored
+     * by the other methods, which take their body as an argument.
+     */
+    jsonBody?: unknown;
 }
 /**
  * What {@link PlatformApiClient.postSse} takes besides the path and body.

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

@@ -1 +1 @@
-{"version":3,"file":"api-client.d.ts","sourceRoot":"","sources":["../../src/core/api-client.ts"],"names":[],"mappings":"AAKA;;;;;;;GAOG;AACH,MAAM,WAAW,iBAAiB;IAChC,kBAAkB;IAClB,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,sBAAsB,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IACnE,8CAA8C;IAC9C,IAAI,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,sBAAsB,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IACpF,sFAAsF;IACtF,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,sBAAsB,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IACnF,wFAAwF;IACxF,KAAK,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,sBAAsB,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IACrF,8DAA8D;IAC9D,MAAM,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,sBAAsB,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IACtE;;;;;OAKG;IACH,OAAO,CAAC,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,sBAAsB,GAAG,OAAO,CAAC,oBAAoB,CAAC,CAAC;IACxF;;;;;OAKG;IACH,QAAQ,CAAC,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,sBAAsB,GAAG,OAAO,CAAC,oBAAoB,CAAC,CAAC;IACzG;;;;;;;;OAQG;IACH,OAAO,CAAC,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,kBAAkB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACnF;AAED;;;;;GAKG;AACH,MAAM,WAAW,sBAAsB;IACrC,2DAA2D;IAC3D,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,6EAA6E;IAC7E,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;GAIG;AACH,MAAM,WAAW,kBAAkB;IACjC;;;OAGG;IACH,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,GAAG,IAAI,CAAC;IAC5C,mEAAmE;IACnE,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAED;;;;GAIG;AACH,MAAM,WAAW,oBAAoB;IACnC,yBAAyB;IACzB,IAAI,EAAE,IAAI,CAAC;IACX,mDAAmD;IACnD,OAAO,EAAE;QACP,6DAA6D;QAC7D,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;KAClC,CAAC;CACH;AAED;;;;;GAKG;AACH,MAAM,WAAW,gBAAgB;IAC/B,4CAA4C;IAC5C,MAAM,EAAE,MAAM,CAAC;IACf,uCAAuC;IACvC,OAAO,EAAE,MAAM,CAAC;IAChB,+DAA+D;IAC/D,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,iFAAiF;IACjF,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,gBAAgB,CAS5E"}
+{"version":3,"file":"api-client.d.ts","sourceRoot":"","sources":["../../src/core/api-client.ts"],"names":[],"mappings":"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"}

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

@@ -1 +1 @@
-{"version":3,"file":"api-client.js","sourceRoot":"","sources":["../../src/core/api-client.ts"],"names":[],"mappings":"AAAA,6EAA6E;AAC7E,4EAA4E;AAC5E,6EAA6E;AAC7E,8EAA8E;AA2G9E;;;;;;;;;GASG;AACH,MAAM,UAAU,kBAAkB,CAAC,KAAc;IAC/C,IAAI,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC;IAC9D,MAAM,SAAS,GAAG,KAAgE,CAAC;IACnF,OAAO,CACL,OAAO,SAAS,CAAC,MAAM,KAAK,QAAQ;QACpC,MAAM,CAAC,QAAQ,CAAC,SAAS,CAAC,MAAM,CAAC;QACjC,OAAO,SAAS,CAAC,OAAO,KAAK,QAAQ;QACrC,CAAC,SAAS,CAAC,IAAI,KAAK,SAAS,IAAI,OAAO,SAAS,CAAC,IAAI,KAAK,QAAQ,CAAC,CACrE,CAAC;AACJ,CAAC"}
+{"version":3,"file":"api-client.js","sourceRoot":"","sources":["../../src/core/api-client.ts"],"names":[],"mappings":"AAAA,6EAA6E;AAC7E,4EAA4E;AAC5E,6EAA6E;AAC7E,8EAA8E;AA+H9E;;;;;;;;;GASG;AACH,MAAM,UAAU,kBAAkB,CAAC,KAAc;IAC/C,IAAI,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC;IAC9D,MAAM,SAAS,GAAG,KAAgE,CAAC;IACnF,OAAO,CACL,OAAO,SAAS,CAAC,MAAM,KAAK,QAAQ;QACpC,MAAM,CAAC,QAAQ,CAAC,SAAS,CAAC,MAAM,CAAC;QACjC,OAAO,SAAS,CAAC,OAAO,KAAK,QAAQ;QACrC,CAAC,SAAS,CAAC,IAAI,KAAK,SAAS,IAAI,OAAO,SAAS,CAAC,IAAI,KAAK,QAAQ,CAAC,CACrE,CAAC;AACJ,CAAC"}

package/dist/core/host.d.ts

@@ -1,3 +1,4 @@
+import type { ThemePreferenceId } from '@marinoscar/platform-contract/settings';
 import type { ReactElement, ReactNode } from 'react';
 import type { PlatformApiClient } from './api-client.js';
 import type { PlatformViewer } from './viewer.js';
@@ -13,6 +14,31 @@ export interface PlatformWebHost {
     viewer: PlatformViewer;
     /** Optional formatting hooks so packaged pages match the app's conventions. */
     formatRelativeTime?(iso: string): string;
+    /**
+     * Applies a theme preference to the app's theme context: `light`, `dark` or
+     * `system`, or (PP-14.25) the id of a theme the app registered with
+     * `registerThemePreference` on the API and listed in the settings document's
+     * `themeOptions`. The Appearance page calls it when the stored preference
+     * loads or is saved; without it the preference is stored and the app's theme is
+     * left alone. The shell's `setMode` fits (it ignores an id it has no theme
+     * for). Keep its identity stable.
+     */
+    applyTheme?(theme: ThemePreferenceId): void;
+    /**
+     * Ports an installed extension package declares for itself, keyed by a string
+     * or a `Symbol.for(...)` the package exports. The app supplies them next to
+     * the platform's own ports; the package reads one with
+     * {@link usePlatformPort}. Keep the record (and each port) stable across
+     * renders.
+     *
+     * @extensionPoint option
+     * @stability experimental
+     * @example
+     * ```tsx
+     * const host = { api, viewer, extensions: { [TRANSCRIPTS_PORT]: transcriptsPort } };
+     * ```
+     */
+    extensions?: Readonly<Record<string | symbol, unknown>>;
 }
 /**
  * Makes the app's {@link PlatformWebHost} available to every packaged page
@@ -71,4 +97,42 @@ export declare function usePlatformApi(): PlatformApiClient;
  * @stability experimental
  */
 export declare function usePlatformViewer(): PlatformViewer;
+/**
+ * A port an extension package declared on the host's `extensions` record.
+ *
+ * Throws a clear error when the app did not supply it, so a package that needs
+ * a port fails at the first render with the key and the fix, not later with a
+ * `undefined is not a function`. Use {@link useOptionalPlatformPort} for a port
+ * that is genuinely optional.
+ *
+ * The type parameter is a promise by the caller: nothing checks the port's
+ * shape. Export the key and the type from your package, and validate in the
+ * package if the app is untrusted code.
+ *
+ * @typeParam T - the port's type, as the package declares it.
+ * @param key - the key the package exports (`'acme.transcripts'` or `Symbol.for('@acme/transcripts/port')`).
+ * @returns the port the app supplied.
+ * @throws Error outside a {@link PlatformHostProvider}, or when `host.extensions` has no entry for `key`.
+ *
+ * @extensionPoint option
+ * @stability experimental
+ * @example
+ * ```tsx
+ * export const TRANSCRIPTS_PORT = Symbol.for('@acme/transcripts/port');
+ * const port = usePlatformPort<TranscriptsPort>(TRANSCRIPTS_PORT);
+ * ```
+ */
+export declare function usePlatformPort<T>(key: string | symbol): T;
+/**
+ * Like {@link usePlatformPort}, but `undefined` when the app did not supply the
+ * port (or there is no provider), for a package whose port is optional.
+ *
+ * @typeParam T - the port's type, as the package declares it.
+ * @param key - the key the package exports.
+ * @returns the port, or `undefined`.
+ *
+ * @extensionPoint option
+ * @stability experimental
+ */
+export declare function useOptionalPlatformPort<T>(key: string | symbol): T | undefined;
 //# sourceMappingURL=host.d.ts.map

package/dist/core/host.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"host.d.ts","sourceRoot":"","sources":["../../src/core/host.tsx"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAErD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AACzD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAElD;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC9B,oEAAoE;IACpE,GAAG,EAAE,iBAAiB,CAAC;IACvB,sBAAsB;IACtB,MAAM,EAAE,cAAc,CAAC;IACvB,+EAA+E;IAC/E,kBAAkB,CAAC,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAAC;CAC1C;AAKD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE;IAAE,IAAI,EAAE,eAAe,CAAC;IAAC,QAAQ,EAAE,SAAS,CAAA;CAAE,GAAG,YAAY,CAExG;AAED;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,IAAI,eAAe,GAAG,IAAI,CAEhE;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,IAAI,eAAe,CASjD;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,IAAI,iBAAiB,CAElD;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,IAAI,cAAc,CAElD"}
+{"version":3,"file":"host.d.ts","sourceRoot":"","sources":["../../src/core/host.tsx"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,wCAAwC,CAAC;AAEhF,OAAO,KAAK,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAErD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AACzD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAElD;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC9B,oEAAoE;IACpE,GAAG,EAAE,iBAAiB,CAAC;IACvB,sBAAsB;IACtB,MAAM,EAAE,cAAc,CAAC;IACvB,+EAA+E;IAC/E,kBAAkB,CAAC,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAAC;IACzC;;;;;;;;OAQG;IACH,UAAU,CAAC,CAAC,KAAK,EAAE,iBAAiB,GAAG,IAAI,CAAC;IAC5C;;;;;;;;;;;;;OAaG;IACH,UAAU,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,GAAG,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CACzD;AAKD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE;IAAE,IAAI,EAAE,eAAe,CAAC;IAAC,QAAQ,EAAE,SAAS,CAAA;CAAE,GAAG,YAAY,CAExG;AAED;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,IAAI,eAAe,GAAG,IAAI,CAEhE;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,IAAI,eAAe,CASjD;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,IAAI,iBAAiB,CAElD;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,IAAI,cAAc,CAElD;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,CAAC,CAS1D;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,uBAAuB,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,CAAC,GAAG,SAAS,CAI9E"}

package/dist/core/host.js

@@ -1,14 +1,4 @@
 import { jsx as _jsx } from "react/jsx-runtime";
-// =============================================================================
-// The web host ports (issue #696, PP-2.7)
-// =============================================================================
-//
-// Every packaged page reaches the app through ONE context: the app's
-// transport, the signed-in viewer and optional formatting hooks. The app
-// builds the host once (`apps/web/src/platform/platformHost.tsx`) and mounts
-// `PlatformHostProvider` inside its auth provider; a packaged page never
-// imports app context, layout or navigation.
-// =============================================================================
 import { createContext, useContext } from 'react';
 const PlatformHostContext = createContext(null);
 PlatformHostContext.displayName = 'PlatformHostContext';
@@ -81,4 +71,54 @@ export function usePlatformApi() {
 export function usePlatformViewer() {
     return usePlatformHost().viewer;
 }
+/**
+ * A port an extension package declared on the host's `extensions` record.
+ *
+ * Throws a clear error when the app did not supply it, so a package that needs
+ * a port fails at the first render with the key and the fix, not later with a
+ * `undefined is not a function`. Use {@link useOptionalPlatformPort} for a port
+ * that is genuinely optional.
+ *
+ * The type parameter is a promise by the caller: nothing checks the port's
+ * shape. Export the key and the type from your package, and validate in the
+ * package if the app is untrusted code.
+ *
+ * @typeParam T - the port's type, as the package declares it.
+ * @param key - the key the package exports (`'acme.transcripts'` or `Symbol.for('@acme/transcripts/port')`).
+ * @returns the port the app supplied.
+ * @throws Error outside a {@link PlatformHostProvider}, or when `host.extensions` has no entry for `key`.
+ *
+ * @extensionPoint option
+ * @stability experimental
+ * @example
+ * ```tsx
+ * export const TRANSCRIPTS_PORT = Symbol.for('@acme/transcripts/port');
+ * const port = usePlatformPort<TranscriptsPort>(TRANSCRIPTS_PORT);
+ * ```
+ */
+export function usePlatformPort(key) {
+    const extensions = usePlatformHost().extensions;
+    if (extensions === undefined || !Object.prototype.hasOwnProperty.call(extensions, key) || extensions[key] === undefined) {
+        throw new Error(`usePlatformPort: the host has no extension port ${String(key)}. Supply it in the app's PlatformWebHost ` +
+            `(host.extensions[${typeof key === 'symbol' ? String(key) : JSON.stringify(key)}] = ...) before mounting the package that needs it.`);
+    }
+    return extensions[key];
+}
+/**
+ * Like {@link usePlatformPort}, but `undefined` when the app did not supply the
+ * port (or there is no provider), for a package whose port is optional.
+ *
+ * @typeParam T - the port's type, as the package declares it.
+ * @param key - the key the package exports.
+ * @returns the port, or `undefined`.
+ *
+ * @extensionPoint option
+ * @stability experimental
+ */
+export function useOptionalPlatformPort(key) {
+    const extensions = useOptionalPlatformHost()?.extensions;
+    if (extensions === undefined || !Object.prototype.hasOwnProperty.call(extensions, key))
+        return undefined;
+    return extensions[key];
+}
 //# sourceMappingURL=host.js.map

package/dist/core/host.js.map

@@ -1 +1 @@
-{"version":3,"file":"host.js","sourceRoot":"","sources":["../../src/core/host.tsx"],"names":[],"mappings":";AAAA,gFAAgF;AAChF,0CAA0C;AAC1C,gFAAgF;AAChF,EAAE;AACF,qEAAqE;AACrE,yEAAyE;AACzE,6EAA6E;AAC7E,yEAAyE;AACzE,6CAA6C;AAC7C,gFAAgF;AAEhF,OAAO,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,OAAO,CAAC;AAoBlD,MAAM,mBAAmB,GAAG,aAAa,CAAyB,IAAI,CAAC,CAAC;AACxE,mBAAmB,CAAC,WAAW,GAAG,qBAAqB,CAAC;AAExD;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,oBAAoB,CAAC,KAAqD;IACxF,OAAO,KAAC,mBAAmB,CAAC,QAAQ,IAAC,KAAK,EAAE,KAAK,CAAC,IAAI,YAAG,KAAK,CAAC,QAAQ,GAAgC,CAAC;AAC1G,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,uBAAuB;IACrC,OAAO,UAAU,CAAC,mBAAmB,CAAC,CAAC;AACzC,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,eAAe;IAC7B,MAAM,IAAI,GAAG,UAAU,CAAC,mBAAmB,CAAC,CAAC;IAC7C,IAAI,IAAI,KAAK,IAAI,EAAE,CAAC;QAClB,MAAM,IAAI,KAAK,CACb,6FAA6F;YAC3F,wGAAwG,CAC3G,CAAC;IACJ,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,cAAc;IAC5B,OAAO,eAAe,EAAE,CAAC,GAAG,CAAC;AAC/B,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,iBAAiB;IAC/B,OAAO,eAAe,EAAE,CAAC,MAAM,CAAC;AAClC,CAAC"}
+{"version":3,"file":"host.js","sourceRoot":"","sources":["../../src/core/host.tsx"],"names":[],"mappings":";AAYA,OAAO,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,OAAO,CAAC;AA6ClD,MAAM,mBAAmB,GAAG,aAAa,CAAyB,IAAI,CAAC,CAAC;AACxE,mBAAmB,CAAC,WAAW,GAAG,qBAAqB,CAAC;AAExD;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,oBAAoB,CAAC,KAAqD;IACxF,OAAO,KAAC,mBAAmB,CAAC,QAAQ,IAAC,KAAK,EAAE,KAAK,CAAC,IAAI,YAAG,KAAK,CAAC,QAAQ,GAAgC,CAAC;AAC1G,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,uBAAuB;IACrC,OAAO,UAAU,CAAC,mBAAmB,CAAC,CAAC;AACzC,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,eAAe;IAC7B,MAAM,IAAI,GAAG,UAAU,CAAC,mBAAmB,CAAC,CAAC;IAC7C,IAAI,IAAI,KAAK,IAAI,EAAE,CAAC;QAClB,MAAM,IAAI,KAAK,CACb,6FAA6F;YAC3F,wGAAwG,CAC3G,CAAC;IACJ,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,cAAc;IAC5B,OAAO,eAAe,EAAE,CAAC,GAAG,CAAC;AAC/B,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,iBAAiB;IAC/B,OAAO,eAAe,EAAE,CAAC,MAAM,CAAC;AAClC,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,UAAU,eAAe,CAAI,GAAoB;IACrD,MAAM,UAAU,GAAG,eAAe,EAAE,CAAC,UAAU,CAAC;IAChD,IAAI,UAAU,KAAK,SAAS,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,cAAc,CAAC,IAAI,CAAC,UAAU,EAAE,GAAG,CAAC,IAAI,UAAU,CAAC,GAAG,CAAC,KAAK,SAAS,EAAE,CAAC;QACxH,MAAM,IAAI,KAAK,CACb,mDAAmD,MAAM,CAAC,GAAG,CAAC,2CAA2C;YACvG,oBAAoB,OAAO,GAAG,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,qDAAqD,CACvI,CAAC;IACJ,CAAC;IACD,OAAO,UAAU,CAAC,GAAG,CAAM,CAAC;AAC9B,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,uBAAuB,CAAI,GAAoB;IAC7D,MAAM,UAAU,GAAG,uBAAuB,EAAE,EAAE,UAAU,CAAC;IACzD,IAAI,UAAU,KAAK,SAAS,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,cAAc,CAAC,IAAI,CAAC,UAAU,EAAE,GAAG,CAAC;QAAE,OAAO,SAAS,CAAC;IACzG,OAAO,UAAU,CAAC,GAAG,CAAkB,CAAC;AAC1C,CAAC"}

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

@@ -0,0 +1,259 @@
+/**
+ * Per-request options of {@link PlatformHttpClient}: the browser's `RequestInit`
+ * plus the client's own switches.
+ *
+ * @stability experimental
+ */
+export interface PlatformHttpRequestOptions extends RequestInit {
+    /** Send no `Authorization` header and never refresh on a 401 (public routes). */
+    skipAuth?: boolean;
+    /**
+     * How to read a successful body. `'json'` (the default) parses and unwraps
+     * the `{ data }` envelope; `'blob'` returns the raw bytes (e.g. an image);
+     * `'blobWithHeaders'` returns `{ blob, headers }` for a download whose
+     * filename or metadata travel in response headers.
+     */
+    responseType?: 'json' | 'blob' | 'blobWithHeaders';
+}
+/**
+ * What `responseType: 'blobWithHeaders'` resolves with.
+ *
+ * @stability experimental
+ */
+export interface PlatformHttpBlobWithHeaders {
+    /** The response body. */
+    blob: Blob;
+    /** The response headers. */
+    headers: Headers;
+}
+/**
+ * Called when the server definitively refused to refresh a live session.
+ *
+ * @stability experimental
+ */
+export type SessionExpiredListener = () => void;
+/**
+ * The error body fields the client reads from a failed response.
+ *
+ * @stability experimental
+ */
+export interface PlatformHttpErrorBody {
+    /** The API's message. */
+    message?: string;
+    /** The API's machine-readable error code. */
+    code?: string;
+    /** The error envelope's `details`. */
+    details?: unknown;
+}
+/**
+ * What {@link PlatformHttpClient} takes. Everything app-specific about the
+ * transport is here, so the client itself carries no app identity.
+ *
+ * @example
+ * ```ts
+ * export const api = new PlatformHttpClient({
+ *   baseUrl: import.meta.env.VITE_API_BASE_URL || '/api',
+ *   refreshLockName: `${APP_SLUG}-auth-refresh`,
+ *   onErrorResponse: (status, body) => noticeMaintenance(status, body),
+ * });
+ * ```
+ *
+ * @extensionPoint option
+ * @stability experimental
+ */
+export interface PlatformHttpClientOptions {
+    /** Where the API lives, prefixed to every path (`'/api'` same-origin). */
+    baseUrl: string;
+    /**
+     * The Web Lock every page of the app on one origin takes around
+     * `POST /auth/refresh`. Name it after the app so two apps on one origin
+     * never contend for each other's lock.
+     */
+    refreshLockName: string;
+    /**
+     * Called with every error response before the {@link ApiError} is built and
+     * thrown (the error is thrown either way). The reference app notices a
+     * maintenance window here.
+     */
+    onErrorResponse?(status: number, body: PlatformHttpErrorBody): void;
+}
+/**
+ * An error status from the API: the message, status, code and details of the
+ * error envelope (`docs/API.md`). Satisfies `PlatformApiError`.
+ *
+ * @stability stable
+ */
+export declare class ApiError extends Error {
+    /** The HTTP status (403, 409, 500, ...). */
+    status: number;
+    /** The API's machine-readable error code, when it sent one. */
+    code?: string | undefined;
+    /** The error envelope's `details`, when the API sent any. */
+    details?: unknown | undefined;
+    /**
+     * @param message - the API's message, or `'Request failed'`.
+     * @param status - the HTTP status.
+     * @param code - the API's machine-readable error code, when it sent one.
+     * @param details - the error envelope's `details`, when it sent any.
+     */
+    constructor(message: string, 
+    /** The HTTP status (403, 409, 500, ...). */
+    status: number, 
+    /** The API's machine-readable error code, when it sent one. */
+    code?: string | undefined, 
+    /** The error envelope's `details`, when the API sent any. */
+    details?: unknown | undefined);
+}
+/**
+ * The browser transport: holds the access token, sends it as
+ * `Authorization: Bearer`, refreshes once on a 401 (the HttpOnly
+ * `refresh_token` cookie, rotated on use) and retries, and serialises refreshes
+ * across every page of the origin with a Web Lock. Each call resolves to the
+ * response's `data` and rejects with an {@link ApiError} on an error status.
+ *
+ * @stability experimental
+ */
+export declare class PlatformHttpClient {
+    private readonly options;
+    private accessToken;
+    private refreshPromise;
+    private sessionExpiredListeners;
+    /**
+     * @param options - where the API lives, the refresh lock name and the error hook.
+     */
+    constructor(options: PlatformHttpClientOptions);
+    /**
+     * Replace the held access token (`null` signs this page out).
+     *
+     * @param token - the new access token, or `null`.
+     */
+    setAccessToken(token: string | null): void;
+    /**
+     * The held access token.
+     *
+     * @returns the token, or `null` when this page holds none.
+     */
+    getAccessToken(): string | null;
+    /**
+     * Subscribe to "the session is gone": a refresh attempted while this page
+     * HELD an access token was answered 401/403 by the server. Never fired for
+     * a page that was not signed in (the boot-time probe on the login page or
+     * any public page holds no token), nor for a network failure, so a listener
+     * can safely send the user to sign in.
+     *
+     * @param listener - called once per refused refresh.
+     * @returns the unsubscribe function.
+     */
+    onSessionExpired(listener: SessionExpiredListener): () => void;
+    private request;
+    /**
+     * Turn a settled response into the caller's value, or throw. Shared by the
+     * first attempt and the post-refresh retry so both read bodies identically.
+     * Error bodies are always JSON, whatever `responseType` the caller asked for.
+     */
+    private readResponse;
+    /**
+     * Build the `ApiError` every call site catches, after handing the response
+     * to the app's `onErrorResponse` hook (the reference app's maintenance
+     * recogniser lives there: every request goes through this one error path,
+     * so every caller inherits it). The error is still THROWN: the hook is a
+     * side channel, never a replacement for the rejection a caller awaits.
+     */
+    private toError;
+    /**
+     * Refresh the access token from the HttpOnly refresh cookie. Deduped within
+     * this page, serialised across pages (see the class summary).
+     *
+     * @returns `true` when a new access token is held.
+     */
+    refreshToken(): Promise<boolean>;
+    /**
+     * Run the refresh under an exclusive Web Lock shared by every page of this
+     * origin.
+     *
+     * WHY: the `refresh_token` cookie is HttpOnly, rotated on every use, and
+     * shared by every page in the browser profile. Two pages refreshing at once
+     * would present the SAME cookie twice; the server treats a second
+     * presentation of a rotated token as theft and revokes every refresh token
+     * the user holds (reuse detection), signing out all of them. Serialised, the
+     * page that waited presents the NEWER cookie the first page's rotation left
+     * in the shared jar, so there is no reuse.
+     *
+     * Without `navigator.locks` (older browsers, jsdom) this is the plain
+     * in-page refresh.
+     */
+    private refreshAcrossPages;
+    private doRefreshToken;
+    private notifySessionExpired;
+    /**
+     * `GET endpoint`.
+     *
+     * @param endpoint - the path relative to `baseUrl`, query string included.
+     * @param options - request options.
+     * @returns the response's `data`.
+     * @throws {@link ApiError} on an error status.
+     */
+    get<T>(endpoint: string, options?: PlatformHttpRequestOptions): Promise<T>;
+    /**
+     * GET a binary body (an image, a file) as a `Blob`. Same bearer token,
+     * 401, refresh and retry and error handling as every JSON call.
+     *
+     * @param endpoint - the path relative to `baseUrl`.
+     * @param options - request options.
+     * @returns the body.
+     * @throws {@link ApiError} on an error status.
+     */
+    getBlob(endpoint: string, options?: PlatformHttpRequestOptions): Promise<Blob>;
+    /**
+     * `POST endpoint` with an optional JSON body.
+     *
+     * @param endpoint - the path relative to `baseUrl`.
+     * @param body - serialised as JSON when present.
+     * @param options - request options.
+     * @returns the response's `data`.
+     * @throws {@link ApiError} on an error status.
+     */
+    post<T>(endpoint: string, body?: unknown, options?: PlatformHttpRequestOptions): Promise<T>;
+    /**
+     * POST a `multipart/form-data` body. The same bearer token, one-shot
+     * 401, refresh and retry and error hook apply; the FormData is sent as-is
+     * (never JSON-stringified) and can be re-sent on that retry.
+     *
+     * @param endpoint - the path relative to `baseUrl`.
+     * @param formData - the parts.
+     * @param options - request options.
+     * @returns the response's `data`.
+     * @throws {@link ApiError} on an error status.
+     */
+    postFormData<T>(endpoint: string, formData: FormData, options?: PlatformHttpRequestOptions): Promise<T>;
+    /**
+     * `PUT endpoint` with an optional JSON body.
+     *
+     * @param endpoint - the path relative to `baseUrl`.
+     * @param body - serialised as JSON when present.
+     * @param options - request options (`headers: { 'If-Match': ... }` for optimistic concurrency).
+     * @returns the response's `data`.
+     * @throws {@link ApiError} on an error status.
+     */
+    put<T>(endpoint: string, body?: unknown, options?: PlatformHttpRequestOptions): Promise<T>;
+    /**
+     * `PATCH endpoint` with an optional JSON body.
+     *
+     * @param endpoint - the path relative to `baseUrl`.
+     * @param body - serialised as JSON when present.
+     * @param options - request options.
+     * @returns the response's `data`.
+     * @throws {@link ApiError} on an error status.
+     */
+    patch<T>(endpoint: string, body?: unknown, options?: PlatformHttpRequestOptions): Promise<T>;
+    /**
+     * `DELETE endpoint`.
+     *
+     * @param endpoint - the path relative to `baseUrl`.
+     * @param options - request options (a JSON `body` is allowed).
+     * @returns the response's `data` (`undefined` for a 204).
+     * @throws {@link ApiError} on an error status.
+     */
+    delete<T>(endpoint: string, options?: PlatformHttpRequestOptions): Promise<T>;
+}
+//# sourceMappingURL=client.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../../src/core/http/client.ts"],"names":[],"mappings":"AAgBA;;;;;GAKG;AACH,MAAM,WAAW,0BAA2B,SAAQ,WAAW;IAC7D,iFAAiF;IACjF,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB;;;;;OAKG;IACH,YAAY,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,iBAAiB,CAAC;CACpD;AAED;;;;GAIG;AACH,MAAM,WAAW,2BAA2B;IAC1C,yBAAyB;IACzB,IAAI,EAAE,IAAI,CAAC;IACX,4BAA4B;IAC5B,OAAO,EAAE,OAAO,CAAC;CAClB;AAED;;;;GAIG;AACH,MAAM,MAAM,sBAAsB,GAAG,MAAM,IAAI,CAAC;AAEhD;;;;GAIG;AACH,MAAM,WAAW,qBAAqB;IACpC,yBAAyB;IACzB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,6CAA6C;IAC7C,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,sCAAsC;IACtC,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,WAAW,yBAAyB;IACxC,0EAA0E;IAC1E,OAAO,EAAE,MAAM,CAAC;IAChB;;;;OAIG;IACH,eAAe,EAAE,MAAM,CAAC;IACxB;;;;OAIG;IACH,eAAe,CAAC,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,qBAAqB,GAAG,IAAI,CAAC;CACrE;AAED;;;;;GAKG;AACH,qBAAa,QAAS,SAAQ,KAAK;IAS/B,4CAA4C;IACrC,MAAM,EAAE,MAAM;IACrB,+DAA+D;IACxD,IAAI,CAAC,EAAE,MAAM;IACpB,6DAA6D;IACtD,OAAO,CAAC,EAAE,OAAO;IAb1B;;;;;OAKG;gBAED,OAAO,EAAE,MAAM;IACf,4CAA4C;IACrC,MAAM,EAAE,MAAM;IACrB,+DAA+D;IACxD,IAAI,CAAC,EAAE,MAAM,YAAA;IACpB,6DAA6D;IACtD,OAAO,CAAC,EAAE,OAAO,YAAA;CAK3B;AAMD;;;;;;;;GAQG;AACH,qBAAa,kBAAkB;IAQjB,OAAO,CAAC,QAAQ,CAAC,OAAO;IAPpC,OAAO,CAAC,WAAW,CAAuB;IAC1C,OAAO,CAAC,cAAc,CAAiC;IACvD,OAAO,CAAC,uBAAuB,CAAqC;IAEpE;;OAEG;gBAC0B,OAAO,EAAE,yBAAyB;IAE/D;;;;OAIG;IACH,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI;IAI1C;;;;OAIG;IACH,cAAc,IAAI,MAAM,GAAG,IAAI;IAI/B;;;;;;;;;OASG;IACH,gBAAgB,CAAC,QAAQ,EAAE,sBAAsB,GAAG,MAAM,IAAI;YAOhD,OAAO;IAsDrB;;;;OAIG;YACW,YAAY;IAuB1B;;;;;;OAMG;IACH,OAAO,CAAC,OAAO;IAKf;;;;;OAKG;IACG,YAAY,IAAI,OAAO,CAAC,OAAO,CAAC;IAiBtC;;;;;;;;;;;;;;OAcG;IACH,OAAO,CAAC,kBAAkB;YASZ,cAAc;IAoC5B,OAAO,CAAC,oBAAoB;IAU5B;;;;;;;OAOG;IACH,GAAG,CAAC,CAAC,EAAE,QAAQ,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,0BAA0B,GAAG,OAAO,CAAC,CAAC,CAAC;IAI1E;;;;;;;;OAQG;IACH,OAAO,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,0BAA0B,GAAG,OAAO,CAAC,IAAI,CAAC;IAQ9E;;;;;;;;OAQG;IACH,IAAI,CAAC,CAAC,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,0BAA0B,GAAG,OAAO,CAAC,CAAC,CAAC;IAQ3F;;;;;;;;;;OAUG;IACH,YAAY,CAAC,CAAC,EAAE,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,QAAQ,EAAE,OAAO,CAAC,EAAE,0BAA0B,GAAG,OAAO,CAAC,CAAC,CAAC;IAQvG;;;;;;;;OAQG;IACH,GAAG,CAAC,CAAC,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,0BAA0B,GAAG,OAAO,CAAC,CAAC,CAAC;IAQ1F;;;;;;;;OAQG;IACH,KAAK,CAAC,CAAC,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,0BAA0B,GAAG,OAAO,CAAC,CAAC,CAAC;IAQ5F;;;;;;;OAOG;IACH,MAAM,CAAC,CAAC,EAAE,QAAQ,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,0BAA0B,GAAG,OAAO,CAAC,CAAC,CAAC;CAG9E"}