@nubitio/core 0.5.10 → 0.5.13

package/dist/index.d.cts

@@ -38,6 +38,11 @@ interface CoreConfig {
    * formatters that need a currency fall back to plain fixed-point output.
    */
   currency?: string;
+  /**
+   * Escape hatch for Mercure collection topic URIs when autodiscovery from
+   * Hydra `@id` cannot infer the API origin (e.g. relative IRIs only).
+   */
+  mercureTopicOrigin?: string;
 }
 /**
  * Configure core runtime values (locale, timezone, apiBaseUrl).
@@ -54,12 +59,15 @@ declare function getCoreTimezone(): string;
 declare function getCoreApiBaseUrl(): string;
 /** App-wide default currency (ISO 4217), or undefined when not configured. */
 declare function getCoreCurrency(): string | undefined;
+declare function getMercureTopicOrigin(): string | undefined;
 interface CoreConfigProviderProps {
   locale: string;
   timezone: string;
   apiBaseUrl: string;
   /** ISO 4217 app-wide default currency for money formatters (e.g. 'PEN', 'USD'). */
   currency?: string;
+  /** Mercure topic origin override — see {@link CoreConfig.mercureTopicOrigin}. */
+  mercureTopicOrigin?: string;
   children: React.ReactNode;
 }
 declare const CoreConfigProvider: ({
@@ -67,6 +75,7 @@ declare const CoreConfigProvider: ({
   timezone,
   apiBaseUrl,
   currency,
+  mercureTopicOrigin,
   children
 }: CoreConfigProviderProps) => React.JSX.Element;
 declare function useCoreConfig(): CoreConfig;
@@ -435,8 +444,11 @@ declare function CoreProvider({
 //#endregion
 //#region packages/core/mercure/MercureProvider.d.ts
 interface MercureProviderProps {
-  /** Hub URL discovered from the `Link` header, or null if unavailable. */
-  hubUrl: string | null;
+  /**
+   * Hub URL override. When omitted, the provider listens to autodiscovery
+   * from API `Link` headers via `MercureManager`.
+   */
+  hubUrl?: string | null;
   children: ReactNode;
 }
 /**
@@ -444,7 +456,7 @@ interface MercureProviderProps {
  * in sync whenever the URL changes.
  */
 declare function MercureProvider({
-  hubUrl,
+  hubUrl: hubUrlOverride,
   children
 }: MercureProviderProps): React.JSX.Element;
 //#endregion
@@ -458,7 +470,8 @@ declare function MercureProvider({
  * - Mercure is not configured in the backend.
  *
  * This hook does NOT perform any fetch or side effect — it only reads from context.
- * Hub discovery (usually from a `Link` header) must be done by the host application.
+ * Hub discovery happens automatically via `CoreHttpClient` (`Link` header parsing).
+ * Use `<MercureProvider>` without a `hubUrl` prop to expose the discovered URL.
  *
  * ## Usage
  *
@@ -482,6 +495,9 @@ declare function useMercureHub(): string | null;
  * - If `hubUrl` is null (Mercure not configured) or `enabled` is false → no-op.
  * - Subscribes to the wildcard topic `<origin>/<apiUrl>/{id}` (URI Template RFC 6570),
  *   which captures any item-level event (create / update / delete) for the collection.
+ * - `<origin>` comes from `CoreConfig.mercureTopicOrigin`, autodiscovered Hydra
+ *   `@id`, an absolute `apiBaseUrl`, or `window.location.origin`
+ *   (see `buildMercureCollectionTopic`).
  * - Cleanup: unsubscribes on unmount or when dependencies change (no memory leaks).
  *
  * ## Usage
@@ -501,6 +517,58 @@ declare function useMercureHub(): string | null;
  */
 declare function useMercureSubscription(apiUrl: string | undefined, onUpdate: () => void, enabled?: boolean): void;
 //#endregion
+//#region packages/core/mercure/mercureTopics.d.ts
+/**
+ * Resolves the origin used to build Mercure collection topic URIs.
+ *
+ * API Platform publishes item updates to IRIs such as
+ * `http://localhost:8000/api/products/42`. The SPA may run on another origin
+ * in dev (Vite on :5173, API on :8000). The origin is normally autodiscovered
+ * from absolute Hydra `@id` values on API responses. Set `mercureTopicOrigin`
+ * on CoreConfig only when autodiscovery cannot infer the correct origin.
+ */
+declare function resolveMercureTopicOrigin(apiBaseUrl?: string, configuredOrigin?: string, discoveredOrigin?: string | undefined): string;
+/**
+ * Wildcard collection topic (RFC 6570 URI Template) for a resource API path.
+ * e.g. `/api/products` → `http://localhost:8000/api/products/{id}`
+ */
+declare function buildMercureCollectionTopic(apiUrl: string, configuredOrigin?: string, apiBaseUrl?: string): string | null;
+//#endregion
+//#region packages/core/mercure/mercureDiscovery.d.ts
+/** Parsed RFC 8288 Link header entry. */
+interface ParsedLink {
+  url: string;
+  rel: string;
+}
+/**
+ * Parse a `Link` response header value into `{ url, rel }` pairs.
+ * Handles API Platform's `</.well-known/mercure>; rel="mercure"` format.
+ */
+declare function parseLinkHeader(header: string): ParsedLink[];
+/**
+ * Extract the Mercure hub URL from response headers, if present.
+ * Relative URLs are resolved against the request URL.
+ */
+declare function extractMercureHubUrl(headers: Headers, responseUrl: string): string | null;
+/**
+ * Infer the API origin from Hydra `@id` values (entrypoint or collection items).
+ * API Platform publishes absolute IRIs when `DEFAULT_URI` is configured.
+ */
+declare function extractTopicOriginFromPayload(data: unknown): string | null;
+declare function getDiscoveredMercureTopicOrigin(): string | undefined;
+/**
+ * Inspect an API response and update Mercure hub URL / topic origin when found.
+ * Called from `CoreHttpClient` on every successful response.
+ */
+declare function discoverMercureFromResponse(response: Response, data: unknown): void;
+//#endregion
+//#region packages/core/mercure/useDiscoveredMercureTopicOrigin.d.ts
+/**
+ * Returns the Mercure topic origin autodiscovered from Hydra `@id` IRIs.
+ * Re-renders when a new origin is discovered from a subsequent API response.
+ */
+declare function useDiscoveredMercureTopicOrigin(): string | undefined;
+//#endregion
 //#region packages/core/mercure/MercureManager.d.ts
 /**
  * MercureManager — Singleton that manages the lifecycle of EventSource connections.
@@ -564,4 +632,4 @@ declare class MercureManager {
 /** Singleton instance — shared across the entire application. */
 declare const mercureManager: MercureManager;
 //#endregion
-export { type CoreConfig, CoreConfigProvider, type CoreConfigProviderProps, CoreHttpClient, type CoreHttpClientConfig, type CoreHttpError, type CoreHttpErrorData, CoreHttpProvider, type CoreHttpProviderProps, type CoreHttpResponse, type CoreNotificationType, CoreProvider, type CoreProviderProps, type CoreRequestConfig, type CoreResponseType, type CoreRuntime, CoreRuntimeProvider, type CoreRuntimeProviderProps, type CoreTranslationKeys, DEFAULT_TIMEZONE, type DataGridEventNames, type DataRecord, DateUtils, type DialogEventNames, type EventSubscription, type FormEventNames, type GridData, mercureManager as MercureManager, type MercureManager as MercureManagerType, MercureProvider, type MercureProviderProps, type ScopedFormEventNames, type ToolbarButtonItem, configureCore, configureCoreDate, coreTranslationsEn, coreTranslationsEs, createCoreHttpClient, createCrudEvents, createScopedEventBus, dispatch, getCoreApiBaseUrl, getCoreCurrency, getCoreLocale, getCoreTimezone, initCoreI18n, useCoreConfig, useCoreHttpClient, useCoreRuntime, useCoreTranslation, useEvents, useMercureHub, useMercureSubscription };
+export { type CoreConfig, CoreConfigProvider, type CoreConfigProviderProps, CoreHttpClient, type CoreHttpClientConfig, type CoreHttpError, type CoreHttpErrorData, CoreHttpProvider, type CoreHttpProviderProps, type CoreHttpResponse, type CoreNotificationType, CoreProvider, type CoreProviderProps, type CoreRequestConfig, type CoreResponseType, type CoreRuntime, CoreRuntimeProvider, type CoreRuntimeProviderProps, type CoreTranslationKeys, DEFAULT_TIMEZONE, type DataGridEventNames, type DataRecord, DateUtils, type DialogEventNames, type EventSubscription, type FormEventNames, type GridData, mercureManager as MercureManager, type MercureManager as MercureManagerType, MercureProvider, type MercureProviderProps, type ScopedFormEventNames, type ToolbarButtonItem, buildMercureCollectionTopic, configureCore, configureCoreDate, coreTranslationsEn, coreTranslationsEs, createCoreHttpClient, createCrudEvents, createScopedEventBus, discoverMercureFromResponse, dispatch, extractMercureHubUrl, extractTopicOriginFromPayload, getCoreApiBaseUrl, getCoreCurrency, getCoreLocale, getCoreTimezone, getDiscoveredMercureTopicOrigin, getMercureTopicOrigin, initCoreI18n, parseLinkHeader, resolveMercureTopicOrigin, useCoreConfig, useCoreHttpClient, useCoreRuntime, useCoreTranslation, useDiscoveredMercureTopicOrigin, useEvents, useMercureHub, useMercureSubscription };

package/dist/index.d.mts

@@ -38,6 +38,11 @@ interface CoreConfig {
    * formatters that need a currency fall back to plain fixed-point output.
    */
   currency?: string;
+  /**
+   * Escape hatch for Mercure collection topic URIs when autodiscovery from
+   * Hydra `@id` cannot infer the API origin (e.g. relative IRIs only).
+   */
+  mercureTopicOrigin?: string;
 }
 /**
  * Configure core runtime values (locale, timezone, apiBaseUrl).
@@ -54,12 +59,15 @@ declare function getCoreTimezone(): string;
 declare function getCoreApiBaseUrl(): string;
 /** App-wide default currency (ISO 4217), or undefined when not configured. */
 declare function getCoreCurrency(): string | undefined;
+declare function getMercureTopicOrigin(): string | undefined;
 interface CoreConfigProviderProps {
   locale: string;
   timezone: string;
   apiBaseUrl: string;
   /** ISO 4217 app-wide default currency for money formatters (e.g. 'PEN', 'USD'). */
   currency?: string;
+  /** Mercure topic origin override — see {@link CoreConfig.mercureTopicOrigin}. */
+  mercureTopicOrigin?: string;
   children: React.ReactNode;
 }
 declare const CoreConfigProvider: ({
@@ -67,6 +75,7 @@ declare const CoreConfigProvider: ({
   timezone,
   apiBaseUrl,
   currency,
+  mercureTopicOrigin,
   children
 }: CoreConfigProviderProps) => React.JSX.Element;
 declare function useCoreConfig(): CoreConfig;
@@ -435,8 +444,11 @@ declare function CoreProvider({
 //#endregion
 //#region packages/core/mercure/MercureProvider.d.ts
 interface MercureProviderProps {
-  /** Hub URL discovered from the `Link` header, or null if unavailable. */
-  hubUrl: string | null;
+  /**
+   * Hub URL override. When omitted, the provider listens to autodiscovery
+   * from API `Link` headers via `MercureManager`.
+   */
+  hubUrl?: string | null;
   children: ReactNode;
 }
 /**
@@ -444,7 +456,7 @@ interface MercureProviderProps {
  * in sync whenever the URL changes.
  */
 declare function MercureProvider({
-  hubUrl,
+  hubUrl: hubUrlOverride,
   children
 }: MercureProviderProps): React.JSX.Element;
 //#endregion
@@ -458,7 +470,8 @@ declare function MercureProvider({
  * - Mercure is not configured in the backend.
  *
  * This hook does NOT perform any fetch or side effect — it only reads from context.
- * Hub discovery (usually from a `Link` header) must be done by the host application.
+ * Hub discovery happens automatically via `CoreHttpClient` (`Link` header parsing).
+ * Use `<MercureProvider>` without a `hubUrl` prop to expose the discovered URL.
  *
  * ## Usage
  *
@@ -482,6 +495,9 @@ declare function useMercureHub(): string | null;
  * - If `hubUrl` is null (Mercure not configured) or `enabled` is false → no-op.
  * - Subscribes to the wildcard topic `<origin>/<apiUrl>/{id}` (URI Template RFC 6570),
  *   which captures any item-level event (create / update / delete) for the collection.
+ * - `<origin>` comes from `CoreConfig.mercureTopicOrigin`, autodiscovered Hydra
+ *   `@id`, an absolute `apiBaseUrl`, or `window.location.origin`
+ *   (see `buildMercureCollectionTopic`).
  * - Cleanup: unsubscribes on unmount or when dependencies change (no memory leaks).
  *
  * ## Usage
@@ -501,6 +517,58 @@ declare function useMercureHub(): string | null;
  */
 declare function useMercureSubscription(apiUrl: string | undefined, onUpdate: () => void, enabled?: boolean): void;
 //#endregion
+//#region packages/core/mercure/mercureTopics.d.ts
+/**
+ * Resolves the origin used to build Mercure collection topic URIs.
+ *
+ * API Platform publishes item updates to IRIs such as
+ * `http://localhost:8000/api/products/42`. The SPA may run on another origin
+ * in dev (Vite on :5173, API on :8000). The origin is normally autodiscovered
+ * from absolute Hydra `@id` values on API responses. Set `mercureTopicOrigin`
+ * on CoreConfig only when autodiscovery cannot infer the correct origin.
+ */
+declare function resolveMercureTopicOrigin(apiBaseUrl?: string, configuredOrigin?: string, discoveredOrigin?: string | undefined): string;
+/**
+ * Wildcard collection topic (RFC 6570 URI Template) for a resource API path.
+ * e.g. `/api/products` → `http://localhost:8000/api/products/{id}`
+ */
+declare function buildMercureCollectionTopic(apiUrl: string, configuredOrigin?: string, apiBaseUrl?: string): string | null;
+//#endregion
+//#region packages/core/mercure/mercureDiscovery.d.ts
+/** Parsed RFC 8288 Link header entry. */
+interface ParsedLink {
+  url: string;
+  rel: string;
+}
+/**
+ * Parse a `Link` response header value into `{ url, rel }` pairs.
+ * Handles API Platform's `</.well-known/mercure>; rel="mercure"` format.
+ */
+declare function parseLinkHeader(header: string): ParsedLink[];
+/**
+ * Extract the Mercure hub URL from response headers, if present.
+ * Relative URLs are resolved against the request URL.
+ */
+declare function extractMercureHubUrl(headers: Headers, responseUrl: string): string | null;
+/**
+ * Infer the API origin from Hydra `@id` values (entrypoint or collection items).
+ * API Platform publishes absolute IRIs when `DEFAULT_URI` is configured.
+ */
+declare function extractTopicOriginFromPayload(data: unknown): string | null;
+declare function getDiscoveredMercureTopicOrigin(): string | undefined;
+/**
+ * Inspect an API response and update Mercure hub URL / topic origin when found.
+ * Called from `CoreHttpClient` on every successful response.
+ */
+declare function discoverMercureFromResponse(response: Response, data: unknown): void;
+//#endregion
+//#region packages/core/mercure/useDiscoveredMercureTopicOrigin.d.ts
+/**
+ * Returns the Mercure topic origin autodiscovered from Hydra `@id` IRIs.
+ * Re-renders when a new origin is discovered from a subsequent API response.
+ */
+declare function useDiscoveredMercureTopicOrigin(): string | undefined;
+//#endregion
 //#region packages/core/mercure/MercureManager.d.ts
 /**
  * MercureManager — Singleton that manages the lifecycle of EventSource connections.
@@ -564,4 +632,4 @@ declare class MercureManager {
 /** Singleton instance — shared across the entire application. */
 declare const mercureManager: MercureManager;
 //#endregion
-export { type CoreConfig, CoreConfigProvider, type CoreConfigProviderProps, CoreHttpClient, type CoreHttpClientConfig, type CoreHttpError, type CoreHttpErrorData, CoreHttpProvider, type CoreHttpProviderProps, type CoreHttpResponse, type CoreNotificationType, CoreProvider, type CoreProviderProps, type CoreRequestConfig, type CoreResponseType, type CoreRuntime, CoreRuntimeProvider, type CoreRuntimeProviderProps, type CoreTranslationKeys, DEFAULT_TIMEZONE, type DataGridEventNames, type DataRecord, DateUtils, type DialogEventNames, type EventSubscription, type FormEventNames, type GridData, mercureManager as MercureManager, type MercureManager as MercureManagerType, MercureProvider, type MercureProviderProps, type ScopedFormEventNames, type ToolbarButtonItem, configureCore, configureCoreDate, coreTranslationsEn, coreTranslationsEs, createCoreHttpClient, createCrudEvents, createScopedEventBus, dispatch, getCoreApiBaseUrl, getCoreCurrency, getCoreLocale, getCoreTimezone, initCoreI18n, useCoreConfig, useCoreHttpClient, useCoreRuntime, useCoreTranslation, useEvents, useMercureHub, useMercureSubscription };
+export { type CoreConfig, CoreConfigProvider, type CoreConfigProviderProps, CoreHttpClient, type CoreHttpClientConfig, type CoreHttpError, type CoreHttpErrorData, CoreHttpProvider, type CoreHttpProviderProps, type CoreHttpResponse, type CoreNotificationType, CoreProvider, type CoreProviderProps, type CoreRequestConfig, type CoreResponseType, type CoreRuntime, CoreRuntimeProvider, type CoreRuntimeProviderProps, type CoreTranslationKeys, DEFAULT_TIMEZONE, type DataGridEventNames, type DataRecord, DateUtils, type DialogEventNames, type EventSubscription, type FormEventNames, type GridData, mercureManager as MercureManager, type MercureManager as MercureManagerType, MercureProvider, type MercureProviderProps, type ScopedFormEventNames, type ToolbarButtonItem, buildMercureCollectionTopic, configureCore, configureCoreDate, coreTranslationsEn, coreTranslationsEs, createCoreHttpClient, createCrudEvents, createScopedEventBus, discoverMercureFromResponse, dispatch, extractMercureHubUrl, extractTopicOriginFromPayload, getCoreApiBaseUrl, getCoreCurrency, getCoreLocale, getCoreTimezone, getDiscoveredMercureTopicOrigin, getMercureTopicOrigin, initCoreI18n, parseLinkHeader, resolveMercureTopicOrigin, useCoreConfig, useCoreHttpClient, useCoreRuntime, useCoreTranslation, useDiscoveredMercureTopicOrigin, useEvents, useMercureHub, useMercureSubscription };