@securitydept/client 0.2.0 → 0.3.0-beta.10

package/dist/web/index.d.mts

@@ -1,52 +1,83 @@
-import { I as CancellationTokenTrait, d as Subscription, n as FetchTransportRedirectKind, r as createFetchTransport, t as FetchTransportOptions, y as ClientRuntime } from "../fetch-transport-Bd5RyWj2.mjs";
-
-//#region src/web/cancellation.d.ts
-interface AbortSignalBridge {
-  signal?: AbortSignal;
-  dispose(): void;
+import { Ct as EventStreamTrait, T as TimeTrait, ln as WithTraitDeps } from "../index-CFAJ969E.mjs";
+import { Bt as EnvironmentValidators, Er as PopupTrait, Hn as RouterTrait, Lt as CreateFoundationEnvironmentOptions, Mn as WithTraitInputValidator, Vt as FoundationEnvironment, dn as SyncStorageTrait } from "../index-CbeZ3AfB.mjs";
+import { _ as createPageResumeSource, a as NativeWebWindowLike, b as fromStorageEvent, c as WebNavigationRouter, d as createPageLifecycleForNativeWeb, f as CreatePageResumeSourceOptions, g as PageResumeWindowTarget, h as PageResumeTriggerKind, i as NativeWebRouter, l as createRouterForNativeWeb, m as PageResumeEvent, n as NativeWebLocationLike, o as RouterForNativeWebCreateOptions, p as PageResumeDocumentTarget, r as NativeWebNavigationLike, s as WebLegacyRouter, t as NativeWebHistoryLike, u as PageLifecycleForNativeWebCreateOptions, v as FromStorageEventOptions, y as StorageEventTarget } from "../index-Bo1BtjZH.mjs";
+//#region src/web/popup.d.ts
+interface PopupForNativeWebCreateOptions {
+  window?: unknown;
 }
-/**
- * Bridge a web `AbortSignal` back into the foundation cancellation contract.
- *
- * This is the canonical consumer-side path for browser hosts that receive an
- * `AbortSignal` from framework/runtime APIs (for example React Query queryFns)
- * but need to call SDK surfaces that accept `CancellationTokenTrait`.
- */
-declare function createCancellationTokenFromAbortSignal(signal?: AbortSignal): CancellationTokenTrait | undefined;
-/**
- * Bridge foundation cancellation to web `AbortSignal` without exposing
- * `AbortSignal` in core contracts.
- */
-declare function createAbortSignalBridge(token?: CancellationTokenTrait): AbortSignalBridge;
-declare function normalizeAbortError(token: CancellationTokenTrait | undefined, error: unknown): unknown;
+interface PopupFeaturesOptions {
+  width?: number;
+  height?: number;
+}
+interface NativeWebPopupWindowLike {
+  closed: boolean;
+  close(): void;
+  postMessage(message: unknown, targetOrigin: string): void;
+}
+interface NativeWebWindowLike$1 {
+  open(url: string, target?: string, features?: string): NativeWebPopupWindowLike | null;
+  addEventListener(type: "message", handler: (event: MessageEvent) => void): void;
+  removeEventListener(type: "message", handler: (event: MessageEvent) => void): void;
+  location?: {
+    href?: string;
+    origin?: string;
+  };
+  screenX?: number;
+  screenY?: number;
+  innerWidth?: number;
+  innerHeight?: number;
+  close?(): void;
+  opener?: {
+    postMessage(message: unknown, targetOrigin: string): void;
+  } | null;
+}
+declare function createPopupForNativeWeb(options: PopupForNativeWebCreateOptions & WithTraitInputValidator<Pick<EnvironmentValidators, "popup">> & WithTraitDeps<{
+  time: TimeTrait;
+}>): PopupTrait | null;
+declare function computePopupFeatures(options?: PopupFeaturesOptions, windowLike?: Pick<NativeWebWindowLike$1, "screenX" | "screenY" | "innerWidth" | "innerHeight">): string;
+//#endregion
+//#region src/web/storage.d.ts
+interface NativeWebStorageLike {
+  getItem(key: string): string | null;
+  setItem(key: string, value: string): void;
+  removeItem(key: string): void;
+}
+interface StorageForNativeWebCreateOptions {
+  storage?: NativeWebStorageLike | null;
+  storageEventTarget?: StorageEventTarget | null;
+  prefix?: string;
+  validatorKey: "persistentStorage" | "sessionStorage";
+}
+declare function createStorageForNativeWeb(options: StorageForNativeWebCreateOptions & WithTraitInputValidator<Pick<EnvironmentValidators, "persistentStorage" | "sessionStorage">>): SyncStorageTrait | null;
+declare function createPersistentStorageForNativeWeb(options: Omit<StorageForNativeWebCreateOptions, "validatorKey"> & WithTraitInputValidator<Pick<EnvironmentValidators, "persistentStorage" | "sessionStorage">>): SyncStorageTrait | null;
+declare function createSessionStorageForNativeWeb(options: Omit<StorageForNativeWebCreateOptions, "validatorKey"> & WithTraitInputValidator<Pick<EnvironmentValidators, "persistentStorage" | "sessionStorage">>): SyncStorageTrait | null;
 //#endregion
-//#region src/web/cross-tab-sync.d.ts
-/** Callback invoked when a cross-tab storage change is detected for the watched key. */
-type CrossTabSyncCallback = (event: {
-  /** The new value written by the other tab, or null if the key was removed. */newValue: string | null; /** The old value before the other tab's write. */
+//#region src/web/environment.d.ts
+interface NativeWebEnvironment extends FoundationEnvironment {
+  router: RouterTrait;
+}
+interface CreateEnvironmentForNativeWebOptions extends CreateFoundationEnvironmentOptions {
+  routerForNativeWebCreateOptions?: RouterForNativeWebCreateOptions;
+  pageLifecycleForNativeWebCreateOptions?: PageLifecycleForNativeWebCreateOptions;
+  popupForNativeWebCreateOptions?: PopupForNativeWebCreateOptions;
+  persistentStorageForNativeWebCreateOptions?: Omit<StorageForNativeWebCreateOptions, "validatorKey">;
+  sessionStorageForNativeWebCreateOptions?: Omit<StorageForNativeWebCreateOptions, "validatorKey">;
+}
+declare function createEnvironmentForNativeWeb(options: CreateEnvironmentForNativeWebOptions): NativeWebEnvironment;
+//#endregion
+//#region src/web/sync/cross-tab-sync.d.ts
+/** Event emitted when a cross-tab storage change is detected for the watched key. */
+interface CrossTabSyncEvent {
+  /** The new value written by the other tab, or null if the key was removed. */
+  newValue: string | null;
+  /** The old value before the other tab's write. */
   oldValue: string | null;
-}) => void;
+}
 /** Options for {@link createCrossTabSync}. */
 interface CreateCrossTabSyncOptions {
   /** The localStorage key to watch for cross-tab changes. */
   key: string;
-  /** Called when another tab modifies the watched key. */
-  onSync: CrossTabSyncCallback;
-  /**
-   * Override the window target (primarily for testing).
-   * Defaults to `globalThis`.
-   */
-  target?: {
-    addEventListener(type: string, listener: EventListener): void;
-    removeEventListener(type: string, listener: EventListener): void;
-  };
-}
-/** Handle returned by {@link createCrossTabSync}. */
-interface CrossTabSync {
-  /** Stop listening for cross-tab storage events. */
-  dispose(): void;
-  /** Number of times a sync event has been received. */
-  readonly syncCount: number;
+  storageEventTarget: StorageEventTarget;
 }
 /**
  * Create a cross-tab sync listener for a specific localStorage key.
@@ -56,311 +87,25 @@ interface CrossTabSync {
  *
  * @example
  * ```ts
- * const sync = createCrossTabSync({
+ * const subscription = createCrossTabSync({
  *   key: "auth:v1",
- *   onSync: ({ newValue }) => {
+ *   storageEventTarget: window,
+ * }).subscribe({
+ *   next: ({ newValue }) => {
  *     if (newValue) {
  *       // Another tab updated auth state — reconcile
- *       controller.restoreFromPersistence();
+ *       client.restorePersistedState();
  *     } else {
  *       // Another tab cleared auth state — log out
- *       controller.clearState({ clearPersisted: false });
- *     }
- *   },
- * });
- * // Later:
- * sync.dispose();
- * ```
- */
-declare function createCrossTabSync(options: CreateCrossTabSyncOptions): CrossTabSync;
-//#endregion
-//#region src/web/input-sources.d.ts
-interface AbortSignalSource {
-  aborted: boolean;
-  reason: unknown;
-  addEventListener(type: string, listener: EventListener): void;
-  removeEventListener(type: string, listener: EventListener): void;
-}
-interface FromAbortSignalOptions {
-  /** AbortSignal to observe. */
-  signal?: AbortSignalSource;
-  /** Callback invoked when the signal aborts. */
-  callback: (reason: unknown) => void;
-  /**
-   * Emit immediately when the signal is already aborted at subscribe time.
-   * Defaults to `false`.
-   */
-  emitIfAborted?: boolean;
-}
-interface StorageEventTarget {
-  addEventListener(type: string, listener: EventListener): void;
-  removeEventListener(type: string, listener: EventListener): void;
-}
-interface FromStorageEventOptions {
-  /**
-   * Storage-event target. Defaults to `globalThis`, which is appropriate for
-   * browser hosts and jsdom-based tests.
-   */
-  target?: StorageEventTarget;
-  /** Callback invoked for each browser `storage` event. */
-  callback: (event: StorageEvent) => void;
-}
-/**
- * Adapt a browser AbortSignal into the shared Subscription model.
- */
-declare function fromAbortSignal(options: FromAbortSignalOptions): Subscription;
-/**
- * Adapt browser `storage` events into the shared Subscription model.
- */
-declare function fromStorageEvent(options: FromStorageEventOptions): Subscription;
-//#endregion
-//#region src/web/page-resume-reconciler.d.ts
-declare const PageResumeTriggerKind: {
-  readonly Visibility: "visibility";
-  readonly PageShow: "pageshow";
-  readonly Focus: "focus";
-  readonly Online: "online";
-};
-type PageResumeTriggerKind = (typeof PageResumeTriggerKind)[keyof typeof PageResumeTriggerKind];
-interface PageResumeEvent {
-  trigger: PageResumeTriggerKind;
-  persisted?: boolean;
-}
-type PageResumeCallback = (event: PageResumeEvent) => void | Promise<void>;
-interface PageResumeDocumentTarget {
-  addEventListener(type: "visibilitychange", handler: EventListener): void;
-  removeEventListener(type: "visibilitychange", handler: EventListener): void;
-  visibilityState: DocumentVisibilityState;
-}
-interface PageResumeWindowTarget {
-  addEventListener(type: "pageshow" | "focus" | "online", handler: EventListener): void;
-  removeEventListener(type: "pageshow" | "focus" | "online", handler: EventListener): void;
-}
-interface CreatePageResumeReconcilerOptions {
-  onReconcile: PageResumeCallback;
-  /** Defaults to 5000ms. Use 0 in deterministic tests. */
-  throttleMs?: number;
-  document?: PageResumeDocumentTarget | null;
-  window?: PageResumeWindowTarget | null;
-  now?: () => number;
-  onError?: (error: unknown, event: PageResumeEvent) => void;
-}
-interface PageResumeReconciler {
-  dispose(): void;
-  readonly reconcileCount: number;
-}
-declare function createPageResumeReconciler(options: CreatePageResumeReconcilerOptions): PageResumeReconciler;
-//#endregion
-//#region src/web/popup.d.ts
-/** Stable error codes for popup-related failures. */
-declare const PopupErrorCode: {
-  /** The browser blocked the popup window from opening. */readonly Blocked: "popup.blocked"; /** The popup was closed by the user before completing the flow. */
-  readonly Closed: "popup.closed_by_user"; /** The relay message was not received within the timeout. */
-  readonly Timeout: "popup.relay_timeout"; /** The relay message contained an error from the callback page. */
-  readonly RelayError: "popup.relay_error"; /** An unexpected error occurred during popup lifecycle. */
-  readonly Internal: "popup.internal";
-};
-type PopupErrorCode = (typeof PopupErrorCode)[keyof typeof PopupErrorCode];
-/**
- * Options for computing the popup window features string.
- */
-interface PopupFeaturesOptions {
-  /** Width in pixels (default: 500). */
-  width?: number;
-  /** Height in pixels (default: 600). */
-  height?: number;
-}
-/**
- * Compute the `features` string for `window.open()`, centered on screen.
- */
-declare function computePopupFeatures(options?: PopupFeaturesOptions): string;
-/**
- * Result of opening a popup window.
- */
-interface PopupWindowHandle {
-  /** The opened window reference. */
-  window: Window;
-}
-/**
- * Open a popup window to the given URL.
- *
- * Throws a `ClientError` with code `popup.blocked` if the browser
- * blocks the popup.
- */
-declare function openPopupWindow(url: string, options?: PopupFeaturesOptions & {
-  target?: string;
-}): PopupWindowHandle;
-/**
- * Expected shape of a relay message from the popup callback page.
- */
-interface PopupRelayMessage {
-  /** Discriminator for the message type. */
-  type: "securitydept:popup_callback";
-  /** The callback URL or fragment received by the popup. */
-  payload: string;
-  /** Optional error from the callback page. */
-  error?: string;
-}
-/**
- * Options for waiting for a popup relay message.
- */
-interface WaitForPopupRelayOptions {
-  /** The popup window handle to monitor. */
-  popup: PopupWindowHandle;
-  /** Maximum time to wait in milliseconds (default: 120000 = 2 minutes). */
-  timeoutMs?: number;
-  /** Expected origin for the relay message (default: current origin). */
-  expectedOrigin?: string;
-  /** Poll interval for checking if the popup is closed (default: 500ms). */
-  pollIntervalMs?: number;
-}
-/**
- * Wait for a relay message from a popup callback page.
- *
- * The popup callback page should call `relayPopupCallback()` to post
- * the callback URL back to the opener.
- *
- * Resolves with the callback payload (URL or fragment string).
- * Rejects with a `ClientError` if:
- *   - the popup is closed without relaying (popup.closed_by_user)
- *   - the timeout expires (popup.relay_timeout)
- *   - the relay message contains an error (popup.relay_error)
- */
-declare function waitForPopupRelay(options: WaitForPopupRelayOptions): Promise<string>;
-/**
- * Options for relaying the callback from the popup window back to the opener.
- */
-interface RelayPopupCallbackOptions {
-  /** The callback payload (URL or fragment) to relay. */
-  payload?: string;
-  /** An error message to relay instead of a successful payload. */
-  error?: string;
-  /** Whether to close the popup after relaying (default: true). */
-  closeAfterRelay?: boolean;
-  /** Target origin for the postMessage (default: current origin). */
-  targetOrigin?: string;
-}
-/**
- * Relay the popup callback result back to the opener window.
- *
- * Call this function from the popup callback page to send the callback
- * URL/fragment back to the parent window that initiated the popup login.
- *
- * @example
- * ```html
- * <script type="module">
- *   import { relayPopupCallback } from "@securitydept/client/web";
- *   relayPopupCallback({ payload: window.location.href });
- * </script>
- * ```
- */
-declare function relayPopupCallback(options?: RelayPopupCallbackOptions): void;
-//#endregion
-//#region src/web/runtime.d.ts
-interface CreateWebRuntimeOptions extends Partial<Omit<ClientRuntime, "transport">> {
-  transport?: ClientRuntime["transport"];
-  fetchTransport?: FetchTransportOptions;
-}
-/**
- * Create a `ClientRuntime` for browser/Web-capable environments.
- */
-declare function createWebRuntime(overrides?: CreateWebRuntimeOptions): ClientRuntime;
-//#endregion
-//#region src/web/visibility.d.ts
-/** Visibility state snapshot passed to the callback. */
-declare const VisibilityState: {
-  readonly Visible: "visible";
-  readonly Hidden: "hidden";
-};
-type VisibilityState = (typeof VisibilityState)[keyof typeof VisibilityState];
-/** Options for {@link fromVisibilityChange}. */
-interface FromVisibilityChangeOptions {
-  /**
-   * Callback invoked when the document visibility state changes.
-   *
-   * The callback receives the new visibility state ("visible" or "hidden").
-   */
-  callback: (state: VisibilityState) => void;
-  /**
-   * Override the document target (primarily for testing).
-   * Defaults to `globalThis.document`.
-   */
-  document?: Pick<Document, "addEventListener" | "removeEventListener" | "visibilityState">;
-}
-/**
- * Subscribe to browser document visibility changes.
- *
- * Built on {@link fromEventPattern} so it follows the same Subscription
- * contract. Returns a {@link Subscription} handle for cleanup.
- *
- * @example
- * ```ts
- * const sub = fromVisibilityChange({
- *   callback: (state) => {
- *     if (state === VisibilityState.Visible) {
- *       scheduleRefresh();
- *     }
- *   },
- * });
- * // Cleanup:
- * sub.unsubscribe();
- * ```
- */
-declare function fromVisibilityChange(options: FromVisibilityChangeOptions): Subscription;
-//#endregion
-//#region src/web/visibility-reconciler.d.ts
-/** Callback invoked when the page becomes visible and reconciliation is needed. */
-type ReconcileCallback = () => void | Promise<void>;
-/** Options for {@link createVisibilityReconciler}. */
-interface CreateVisibilityReconcilerOptions {
-  /**
-   * Called when the document transitions from hidden → visible.
-   * The reconciler only fires on the hidden→visible edge; repeated
-   * visible→visible events are suppressed.
-   */
-  onReconcile: ReconcileCallback;
-  /**
-   * Minimum interval (ms) between reconciliation triggers.
-   * Prevents rapid-fire reconciliation when the user toggles tabs quickly.
-   * Defaults to 5000ms (5 seconds).
-   */
-  throttleMs?: number;
-  /**
-   * Override the document target (primarily for testing).
-   * Defaults to `globalThis.document`.
-   */
-  document?: FromVisibilityChangeOptions["document"];
-  /**
-   * Clock override for testing.
-   */
-  now?: () => number;
-}
-/** Handle returned by {@link createVisibilityReconciler}. */
-interface VisibilityReconciler {
-  /** Stop listening for visibility changes. */
-  dispose(): void;
-  /** Number of times reconciliation has been triggered. */
-  readonly reconcileCount: number;
-}
-/**
- * Create a visibility reconciler that triggers a callback when the page
- * transitions from hidden → visible.
- *
- * @example
- * ```ts
- * const reconciler = createVisibilityReconciler({
- *   onReconcile: () => {
- *     // Re-check token freshness or sync cross-tab state
- *     if (controller.snapshot?.tokens.accessTokenExpiresAt) {
- *       scheduleRefreshIfExpired();
+ *       controller.clearState({ persistPolicy: "skip" });
  *     }
  *   },
  * });
  * // Later:
- * reconciler.dispose();
+ * subscription.unsubscribe();
  * ```
  */
-declare function createVisibilityReconciler(options: CreateVisibilityReconcilerOptions): VisibilityReconciler;
+declare function createCrossTabSync(options: CreateCrossTabSyncOptions): EventStreamTrait<CrossTabSyncEvent>;
 //#endregion
-export { type AbortSignalBridge, type CreateCrossTabSyncOptions, type CreatePageResumeReconcilerOptions, type CreateVisibilityReconcilerOptions, type CreateWebRuntimeOptions, type CrossTabSync, type CrossTabSyncCallback, type FetchTransportOptions, FetchTransportRedirectKind, type FromAbortSignalOptions, type FromStorageEventOptions, type FromVisibilityChangeOptions, type PageResumeCallback, type PageResumeDocumentTarget, type PageResumeEvent, type PageResumeReconciler, PageResumeTriggerKind, type PageResumeWindowTarget, PopupErrorCode, type PopupFeaturesOptions, type PopupRelayMessage, type PopupWindowHandle, type ReconcileCallback, type RelayPopupCallbackOptions, type VisibilityReconciler, VisibilityState, type WaitForPopupRelayOptions, computePopupFeatures, createAbortSignalBridge, createCancellationTokenFromAbortSignal, createCrossTabSync, createFetchTransport, createPageResumeReconciler, createVisibilityReconciler, createWebRuntime, fromAbortSignal, fromStorageEvent, fromVisibilityChange, normalizeAbortError, openPopupWindow, relayPopupCallback, waitForPopupRelay };
+export { type CreateCrossTabSyncOptions, type CreateEnvironmentForNativeWebOptions, type CreatePageResumeSourceOptions, type CrossTabSyncEvent, type FoundationEnvironment, type FromStorageEventOptions, type NativeWebEnvironment, type NativeWebHistoryLike, type NativeWebLocationLike, type NativeWebNavigationLike, NativeWebRouter, type NativeWebStorageLike, type NativeWebWindowLike, type PageLifecycleForNativeWebCreateOptions, type PageResumeDocumentTarget, type PageResumeEvent, PageResumeTriggerKind, type PageResumeWindowTarget, type PopupFeaturesOptions, type PopupForNativeWebCreateOptions, type RouterForNativeWebCreateOptions, type StorageEventTarget, type StorageForNativeWebCreateOptions, WebLegacyRouter, WebNavigationRouter, computePopupFeatures, createCrossTabSync, createEnvironmentForNativeWeb, createPageLifecycleForNativeWeb, createPageResumeSource, createPersistentStorageForNativeWeb, createPopupForNativeWeb, createRouterForNativeWeb, createSessionStorageForNativeWeb, createStorageForNativeWeb, fromStorageEvent };
 //# sourceMappingURL=index.d.mts.map