@ethisyscore/plugin-ui 1.100.3 → 1.100.4

package/dist/platform-react/index.d.cts

@@ -1,7 +1,7 @@
 import * as react from 'react';
 import { ComponentType, ReactElement, ReactNode, AnchorHTMLAttributes, MouseEvent } from 'react';
 import * as _tanstack_react_query from '@tanstack/react-query';
-import { QueryClient, UseQueryResult, UseQueryOptions, QueryKey } from '@tanstack/react-query';
+import { QueryClient, QueryClientConfig, UseQueryResult, UseQueryOptions, QueryKey } from '@tanstack/react-query';
 import { PlatformReactPageProps } from '@ethisyscore/components-react';
 import { T as ToolInvoker } from '../mcpService-4h3sKDpW.cjs';
 export { B as BaseMcpService, n as notViaMcp, u as useToolInvoker, a as useToolInvokerMap } from '../mcpService-4h3sKDpW.cjs';
@@ -95,6 +95,49 @@ interface PluginPageDefinerConfig {
  */
 declare function createPluginPageDefiner(config: PluginPageDefinerConfig): (Page: ComponentType<PlatformReactPageProps>, views?: Record<string, ViewComponent>) => ComponentType<PlatformReactPageProps>;
 
+/**
+ * The `QueryClient` every PlatformReact plugin surface runs on.
+ *
+ * # Why this file exists
+ *
+ * A plugin bundle cannot see the host's app-wide `QueryClientProvider` — react-query is
+ * bundle-local, which is why each page and overlay creates its own client. The host's client
+ * carries cache-level `onError` handlers that turn a failed query or mutation into a toast, and
+ * for a long time the plugin-side client carried none. The consequence was not a degraded
+ * message: it was NO message. A command could be refused by the server, travel back through
+ * every layer intact, and land on a page that showed the operator nothing at all.
+ *
+ * That silence was invisible from inside plugin code, because plugins were written as though the
+ * handler existed — roughly 1,100 `meta.errorTitle` declarations across nine plugins, plus this
+ * SDK's own shared connector-mapping hooks, all of them dead on arrival.
+ *
+ * # What gets shown
+ *
+ * `meta.errorTitle` is the title when a call site set one — that is the contract those 1,100 sites
+ * were already written against. Otherwise the title is derived from the `[Status]` prefix the
+ * SDK's `ResultMapper` puts on every failure, so an unlabelled call still says something truer
+ * than "Error". The prefix is always stripped from the description: it is our wire format, and an
+ * operator reading "[Conflict]" is reading our plumbing rather than their problem.
+ *
+ * A page that renders its own error UI opts out with `meta.suppressErrorToast`, matching the host.
+ */
+/** The subset of react-query's `meta` this module reads. Both fields are optional by design. */
+interface PluginQueryMeta {
+    /** Toast title for a failure from this call site. */
+    errorTitle?: string;
+    /** Set when the page shows its own error UI and a toast would double-report it. */
+    suppressErrorToast?: boolean;
+}
+/**
+ * Creates a plugin-surface `QueryClient` whose failures are visible to the operator.
+ *
+ * `config` is merged shallowly over the defaults, so a plugin can tune `defaultOptions` without
+ * having to restate — or accidentally drop — the error handling. Passing an explicit `queryCache`
+ * or `mutationCache` does replace ours, which is the escape hatch for a plugin that genuinely
+ * wants different behaviour.
+ */
+declare function createPluginQueryClient(config?: QueryClientConfig): QueryClient;
+
 /**
  * Matches component types renderable via `useView`: plain function/class
  * components plus the object wrappers `React.lazy`, `React.forwardRef`, and
@@ -1386,4 +1429,4 @@ interface MenuConfigHostSidebarOptions {
  */
 declare function menuConfigToHostSidebarInput(config: HeaderMenuItem[], opts: MenuConfigHostSidebarOptions): HostSidebarHookInput;
 
-export { type AuthenticatedQueryResult, type CurrencyInfo, type CurrencySelector, DEFAULT_MAX_UPLOAD_BYTES, type DefinePlatformReactPluginOverlayOptions, type DefinePlatformReactPluginPageOptions, EHX_PLUGIN_PORTAL_ATTR, EHX_PLUGIN_PORTAL_CLASS, EHX_PLUGIN_ROOT_CLASS, HostSidebarHookInput, HostSidebarInput, type InsetLease, LIST_CURRENCIES_TOOL, type ManagedLifecycle, type McpToolArgs, type McpToolContract, type McpToolContracts, type McpToolResult, type MenuConfigHostSidebarOptions, MissingViewFallback, ORGANISATION_SETTINGS_URI, OVERLAY_HOST_CONTRACT_VERSION, type OverlayHostApi, type OverlayHostCapabilities, OverlayHostContext, type PlatformReactOverlayProps, type PluginOverlayDefinerConfig, type PluginPageDefinerConfig, PluginPortalScope, PluginStyleScope, REPORTING_CURRENCY_TOOL, type ReactRouterShimOptions, SurfaceBaseContext, type SurfaceBaseValue, TemplateContext, type TemplateManifest, type ToHostSidebarInputOptions, ToolInvoker, TypedMcpService, type UseCurrencyResult, type UseMcpUploadOptions, type UseMcpUploadResult, type UseMcpUploadTarget, type ViewComponent, buildSurfaceUrl, createPluginOverlayDefiner, createPluginPageDefiner, createReactRouterShim, createUseView, definePlatformReactPluginOverlay, definePlatformReactPluginPage, deriveHostEntityToken, injectPluginStyles, isComponent, mcpTool, menuConfigToHostSidebarInput, normaliseSlug, resolveSurfaceBase, surfacePathFor, toHostSidebarInput, useAuthenticatedQueries, useAuthenticatedQuery, useCurrency, useManagedLifecycle, useMcpUpload, useOrgFormatSync, useOverlayHost, usePluginRealtime, useReportingCurrencySync, useSurfaceUrl, useTypedToolInvokerMap, useView };
+export { type AuthenticatedQueryResult, type CurrencyInfo, type CurrencySelector, DEFAULT_MAX_UPLOAD_BYTES, type DefinePlatformReactPluginOverlayOptions, type DefinePlatformReactPluginPageOptions, EHX_PLUGIN_PORTAL_ATTR, EHX_PLUGIN_PORTAL_CLASS, EHX_PLUGIN_ROOT_CLASS, HostSidebarHookInput, HostSidebarInput, type InsetLease, LIST_CURRENCIES_TOOL, type ManagedLifecycle, type McpToolArgs, type McpToolContract, type McpToolContracts, type McpToolResult, type MenuConfigHostSidebarOptions, MissingViewFallback, ORGANISATION_SETTINGS_URI, OVERLAY_HOST_CONTRACT_VERSION, type OverlayHostApi, type OverlayHostCapabilities, OverlayHostContext, type PlatformReactOverlayProps, type PluginOverlayDefinerConfig, type PluginPageDefinerConfig, PluginPortalScope, type PluginQueryMeta, PluginStyleScope, REPORTING_CURRENCY_TOOL, type ReactRouterShimOptions, SurfaceBaseContext, type SurfaceBaseValue, TemplateContext, type TemplateManifest, type ToHostSidebarInputOptions, ToolInvoker, TypedMcpService, type UseCurrencyResult, type UseMcpUploadOptions, type UseMcpUploadResult, type UseMcpUploadTarget, type ViewComponent, buildSurfaceUrl, createPluginOverlayDefiner, createPluginPageDefiner, createPluginQueryClient, createReactRouterShim, createUseView, definePlatformReactPluginOverlay, definePlatformReactPluginPage, deriveHostEntityToken, injectPluginStyles, isComponent, mcpTool, menuConfigToHostSidebarInput, normaliseSlug, resolveSurfaceBase, surfacePathFor, toHostSidebarInput, useAuthenticatedQueries, useAuthenticatedQuery, useCurrency, useManagedLifecycle, useMcpUpload, useOrgFormatSync, useOverlayHost, usePluginRealtime, useReportingCurrencySync, useSurfaceUrl, useTypedToolInvokerMap, useView };

package/dist/platform-react/index.d.ts

@@ -1,7 +1,7 @@
 import * as react from 'react';
 import { ComponentType, ReactElement, ReactNode, AnchorHTMLAttributes, MouseEvent } from 'react';
 import * as _tanstack_react_query from '@tanstack/react-query';
-import { QueryClient, UseQueryResult, UseQueryOptions, QueryKey } from '@tanstack/react-query';
+import { QueryClient, QueryClientConfig, UseQueryResult, UseQueryOptions, QueryKey } from '@tanstack/react-query';
 import { PlatformReactPageProps } from '@ethisyscore/components-react';
 import { T as ToolInvoker } from '../mcpService-4h3sKDpW.js';
 export { B as BaseMcpService, n as notViaMcp, u as useToolInvoker, a as useToolInvokerMap } from '../mcpService-4h3sKDpW.js';
@@ -95,6 +95,49 @@ interface PluginPageDefinerConfig {
  */
 declare function createPluginPageDefiner(config: PluginPageDefinerConfig): (Page: ComponentType<PlatformReactPageProps>, views?: Record<string, ViewComponent>) => ComponentType<PlatformReactPageProps>;
 
+/**
+ * The `QueryClient` every PlatformReact plugin surface runs on.
+ *
+ * # Why this file exists
+ *
+ * A plugin bundle cannot see the host's app-wide `QueryClientProvider` — react-query is
+ * bundle-local, which is why each page and overlay creates its own client. The host's client
+ * carries cache-level `onError` handlers that turn a failed query or mutation into a toast, and
+ * for a long time the plugin-side client carried none. The consequence was not a degraded
+ * message: it was NO message. A command could be refused by the server, travel back through
+ * every layer intact, and land on a page that showed the operator nothing at all.
+ *
+ * That silence was invisible from inside plugin code, because plugins were written as though the
+ * handler existed — roughly 1,100 `meta.errorTitle` declarations across nine plugins, plus this
+ * SDK's own shared connector-mapping hooks, all of them dead on arrival.
+ *
+ * # What gets shown
+ *
+ * `meta.errorTitle` is the title when a call site set one — that is the contract those 1,100 sites
+ * were already written against. Otherwise the title is derived from the `[Status]` prefix the
+ * SDK's `ResultMapper` puts on every failure, so an unlabelled call still says something truer
+ * than "Error". The prefix is always stripped from the description: it is our wire format, and an
+ * operator reading "[Conflict]" is reading our plumbing rather than their problem.
+ *
+ * A page that renders its own error UI opts out with `meta.suppressErrorToast`, matching the host.
+ */
+/** The subset of react-query's `meta` this module reads. Both fields are optional by design. */
+interface PluginQueryMeta {
+    /** Toast title for a failure from this call site. */
+    errorTitle?: string;
+    /** Set when the page shows its own error UI and a toast would double-report it. */
+    suppressErrorToast?: boolean;
+}
+/**
+ * Creates a plugin-surface `QueryClient` whose failures are visible to the operator.
+ *
+ * `config` is merged shallowly over the defaults, so a plugin can tune `defaultOptions` without
+ * having to restate — or accidentally drop — the error handling. Passing an explicit `queryCache`
+ * or `mutationCache` does replace ours, which is the escape hatch for a plugin that genuinely
+ * wants different behaviour.
+ */
+declare function createPluginQueryClient(config?: QueryClientConfig): QueryClient;
+
 /**
  * Matches component types renderable via `useView`: plain function/class
  * components plus the object wrappers `React.lazy`, `React.forwardRef`, and
@@ -1386,4 +1429,4 @@ interface MenuConfigHostSidebarOptions {
  */
 declare function menuConfigToHostSidebarInput(config: HeaderMenuItem[], opts: MenuConfigHostSidebarOptions): HostSidebarHookInput;
 
-export { type AuthenticatedQueryResult, type CurrencyInfo, type CurrencySelector, DEFAULT_MAX_UPLOAD_BYTES, type DefinePlatformReactPluginOverlayOptions, type DefinePlatformReactPluginPageOptions, EHX_PLUGIN_PORTAL_ATTR, EHX_PLUGIN_PORTAL_CLASS, EHX_PLUGIN_ROOT_CLASS, HostSidebarHookInput, HostSidebarInput, type InsetLease, LIST_CURRENCIES_TOOL, type ManagedLifecycle, type McpToolArgs, type McpToolContract, type McpToolContracts, type McpToolResult, type MenuConfigHostSidebarOptions, MissingViewFallback, ORGANISATION_SETTINGS_URI, OVERLAY_HOST_CONTRACT_VERSION, type OverlayHostApi, type OverlayHostCapabilities, OverlayHostContext, type PlatformReactOverlayProps, type PluginOverlayDefinerConfig, type PluginPageDefinerConfig, PluginPortalScope, PluginStyleScope, REPORTING_CURRENCY_TOOL, type ReactRouterShimOptions, SurfaceBaseContext, type SurfaceBaseValue, TemplateContext, type TemplateManifest, type ToHostSidebarInputOptions, ToolInvoker, TypedMcpService, type UseCurrencyResult, type UseMcpUploadOptions, type UseMcpUploadResult, type UseMcpUploadTarget, type ViewComponent, buildSurfaceUrl, createPluginOverlayDefiner, createPluginPageDefiner, createReactRouterShim, createUseView, definePlatformReactPluginOverlay, definePlatformReactPluginPage, deriveHostEntityToken, injectPluginStyles, isComponent, mcpTool, menuConfigToHostSidebarInput, normaliseSlug, resolveSurfaceBase, surfacePathFor, toHostSidebarInput, useAuthenticatedQueries, useAuthenticatedQuery, useCurrency, useManagedLifecycle, useMcpUpload, useOrgFormatSync, useOverlayHost, usePluginRealtime, useReportingCurrencySync, useSurfaceUrl, useTypedToolInvokerMap, useView };
+export { type AuthenticatedQueryResult, type CurrencyInfo, type CurrencySelector, DEFAULT_MAX_UPLOAD_BYTES, type DefinePlatformReactPluginOverlayOptions, type DefinePlatformReactPluginPageOptions, EHX_PLUGIN_PORTAL_ATTR, EHX_PLUGIN_PORTAL_CLASS, EHX_PLUGIN_ROOT_CLASS, HostSidebarHookInput, HostSidebarInput, type InsetLease, LIST_CURRENCIES_TOOL, type ManagedLifecycle, type McpToolArgs, type McpToolContract, type McpToolContracts, type McpToolResult, type MenuConfigHostSidebarOptions, MissingViewFallback, ORGANISATION_SETTINGS_URI, OVERLAY_HOST_CONTRACT_VERSION, type OverlayHostApi, type OverlayHostCapabilities, OverlayHostContext, type PlatformReactOverlayProps, type PluginOverlayDefinerConfig, type PluginPageDefinerConfig, PluginPortalScope, type PluginQueryMeta, PluginStyleScope, REPORTING_CURRENCY_TOOL, type ReactRouterShimOptions, SurfaceBaseContext, type SurfaceBaseValue, TemplateContext, type TemplateManifest, type ToHostSidebarInputOptions, ToolInvoker, TypedMcpService, type UseCurrencyResult, type UseMcpUploadOptions, type UseMcpUploadResult, type UseMcpUploadTarget, type ViewComponent, buildSurfaceUrl, createPluginOverlayDefiner, createPluginPageDefiner, createPluginQueryClient, createReactRouterShim, createUseView, definePlatformReactPluginOverlay, definePlatformReactPluginPage, deriveHostEntityToken, injectPluginStyles, isComponent, mcpTool, menuConfigToHostSidebarInput, normaliseSlug, resolveSurfaceBase, surfacePathFor, toHostSidebarInput, useAuthenticatedQueries, useAuthenticatedQuery, useCurrency, useManagedLifecycle, useMcpUpload, useOrgFormatSync, useOverlayHost, usePluginRealtime, useReportingCurrencySync, useSurfaceUrl, useTypedToolInvokerMap, useView };

package/dist/platform-react/index.js

@@ -1,5 +1,5 @@
 import { createContext, useEffect, useContext, useState, useMemo, useRef, createElement, useCallback, useSyncExternalStore } from 'react';
-import { QueryClient, useQuery, useQueries, QueryClientProvider } from '@tanstack/react-query';
+import { QueryClient, MutationCache, QueryCache, useQuery, useQueries, QueryClientProvider } from '@tanstack/react-query';
 import { definePlatformReactPage, emitNavigation } from '@ethisyscore/components-react';
 import * as extensionRuntime from '@ethisyscore/extension-runtime/plugin';
 import { useHostIdentity, useMcpTool, useOptionalExtensionRuntimeTransport, usePluginRealtimeSource, useExtensionRuntimeTransport } from '@ethisyscore/extension-runtime/plugin';
@@ -9,6 +9,73 @@ import { setOrgFormats } from '@ethisyscore/core-utils/date/org-format';
 import { setOrgReportingCurrency, MONEY_FALLBACK_LOCALE, formatMoney } from '@ethisyscore/core-utils/money';
 
 // src/platform-react/definePlatformReactPluginPage.tsx
+
+// src/components/shared/toast.ts
+function dispatchToast(title, description, variant) {
+  if (typeof window === "undefined" || title.length === 0) {
+    return;
+  }
+  window.dispatchEvent(new CustomEvent("ethisys:toast", { detail: { title, description, variant } }));
+}
+function showErrorToast(title, description) {
+  dispatchToast(title, description, "error");
+}
+
+// src/platform-react/pluginQueryClient.ts
+var STATUS_TITLES = /* @__PURE__ */ new Map([
+  ["NotFound", "Not Found"],
+  ["Unauthorized", "Authentication Error"],
+  ["Forbidden", "Access Denied"],
+  ["Conflict", "Conflict"]
+]);
+var UNTITLED_STATUSES = /* @__PURE__ */ new Set(["Invalid", "Error", "CriticalError", "Unavailable", "Accepted"]);
+var GENERIC_TITLE = "Error";
+function isKnownStatus(status) {
+  return STATUS_TITLES.has(status) || UNTITLED_STATUSES.has(status);
+}
+function splitStatusPrefix(message) {
+  const match = /^\[([A-Za-z]+)\]\s*(.*)$/s.exec(message);
+  if (match === null) {
+    return { status: null, body: message };
+  }
+  const [, status, body] = match;
+  if (!isKnownStatus(status)) {
+    return { status: null, body: message };
+  }
+  return body.length > 0 ? { status, body } : { status: null, body: message };
+}
+function surfaceError(error, meta) {
+  if (meta?.suppressErrorToast === true) {
+    return;
+  }
+  const raw = error instanceof Error && error.message.length > 0 ? error.message : "An unexpected error occurred";
+  const { status, body } = splitStatusPrefix(raw);
+  const title = meta?.errorTitle ?? (status !== null ? STATUS_TITLES.get(status) ?? GENERIC_TITLE : GENERIC_TITLE);
+  showErrorToast(title, body);
+}
+function createPluginQueryClient(config) {
+  return new QueryClient({
+    queryCache: new QueryCache({
+      onError: (error, query) => surfaceError(error, query.meta)
+    }),
+    mutationCache: new MutationCache({
+      onError: (error, _variables, _context, mutation) => surfaceError(error, mutation.meta)
+    }),
+    ...config,
+    defaultOptions: {
+      // Spread first so `mutations`, `dehydrate`, `hydrate` and anything else react-query
+      // adds to `DefaultOptions` survive. Rebuilding this object from named keys instead
+      // silently dropped them, which contradicted the merge promised just above.
+      ...config?.defaultOptions,
+      queries: {
+        retry: 1,
+        refetchOnWindowFocus: false,
+        staleTime: 3e4,
+        ...config?.defaultOptions?.queries
+      }
+    }
+  });
+}
 var TemplateContext = createContext(null);
 function injectPluginStyles(id, css) {
   if (typeof document === "undefined") return;
@@ -228,18 +295,7 @@ function useReportingCurrencySync() {
 }
 
 // src/platform-react/definePlatformReactPluginPage.tsx
-function makeDefaultQueryClient() {
-  return new QueryClient({
-    defaultOptions: {
-      queries: {
-        retry: 1,
-        refetchOnWindowFocus: false,
-        staleTime: 3e4
-      }
-    }
-  });
-}
-var defaultQueryClient = makeDefaultQueryClient();
+var defaultQueryClient = createPluginQueryClient();
 var EHX_PLUGIN_ROOT_CLASS = "ehx-plugin-root";
 function definePlatformReactPluginPage(Page, options) {
   const {
@@ -730,18 +786,7 @@ function useOverlayHost() {
   }
   return api;
 }
-function makeDefaultQueryClient2() {
-  return new QueryClient({
-    defaultOptions: {
-      queries: {
-        retry: 1,
-        refetchOnWindowFocus: false,
-        staleTime: 3e4
-      }
-    }
-  });
-}
-var defaultQueryClient2 = makeDefaultQueryClient2();
+var defaultQueryClient2 = createPluginQueryClient();
 function definePlatformReactPluginOverlay(Overlay, options) {
   const { rootClassName, styleId, css, manifest = {}, queryClient = defaultQueryClient2, wrapOverlay } = options;
   return function MountedOverlay(props) {
@@ -1160,6 +1205,6 @@ function withActiveNavHref(input, activeNavHref) {
   return { ...input, activeNavHref };
 }
 
-export { BaseMcpService, DEFAULT_MAX_UPLOAD_BYTES, EHX_PLUGIN_PORTAL_ATTR, EHX_PLUGIN_PORTAL_CLASS, EHX_PLUGIN_ROOT_CLASS, HOST_CHROME_CONTRACT_VERSION, HostSidebarActionsContext, LIST_CURRENCIES_TOOL, MissingViewFallback, ORGANISATION_SETTINGS_URI, OVERLAY_HOST_CONTRACT_VERSION, OverlayHostContext, PluginPortalScope, PluginStyleScope, REPORTING_CURRENCY_TOOL2 as REPORTING_CURRENCY_TOOL, SIDEBAR_MODE, SurfaceBaseContext, TemplateContext, TypedMcpService, buildSurfaceUrl, createPluginOverlayDefiner, createPluginPageDefiner, createReactRouterShim, createUseView, definePlatformReactPluginOverlay, definePlatformReactPluginPage, deriveHostEntityToken, injectPluginStyles, isComponent, isHostChromeCompatible, mcpTool, menuConfigToHostSidebarInput, normaliseSlug, notViaMcp, reportHostChromeDiagnostic, resolveActiveNavHref, resolveSurfaceBase, setHostChromeDiagnosticSink, surfacePathFor, toHostSidebarInput, useAuthenticatedQueries, useAuthenticatedQuery, useCurrency, useHostSidebarActions, useManagedLifecycle, useMcpUpload, useOrgFormatSync, useOverlayHost, usePluginRealtime, useReportingCurrencySync, useSurfaceUrl, useToolInvoker, useToolInvokerMap, useTypedToolInvokerMap, useView, withActiveNavHref };
+export { BaseMcpService, DEFAULT_MAX_UPLOAD_BYTES, EHX_PLUGIN_PORTAL_ATTR, EHX_PLUGIN_PORTAL_CLASS, EHX_PLUGIN_ROOT_CLASS, HOST_CHROME_CONTRACT_VERSION, HostSidebarActionsContext, LIST_CURRENCIES_TOOL, MissingViewFallback, ORGANISATION_SETTINGS_URI, OVERLAY_HOST_CONTRACT_VERSION, OverlayHostContext, PluginPortalScope, PluginStyleScope, REPORTING_CURRENCY_TOOL2 as REPORTING_CURRENCY_TOOL, SIDEBAR_MODE, SurfaceBaseContext, TemplateContext, TypedMcpService, buildSurfaceUrl, createPluginOverlayDefiner, createPluginPageDefiner, createPluginQueryClient, createReactRouterShim, createUseView, definePlatformReactPluginOverlay, definePlatformReactPluginPage, deriveHostEntityToken, injectPluginStyles, isComponent, isHostChromeCompatible, mcpTool, menuConfigToHostSidebarInput, normaliseSlug, notViaMcp, reportHostChromeDiagnostic, resolveActiveNavHref, resolveSurfaceBase, setHostChromeDiagnosticSink, surfacePathFor, toHostSidebarInput, useAuthenticatedQueries, useAuthenticatedQuery, useCurrency, useHostSidebarActions, useManagedLifecycle, useMcpUpload, useOrgFormatSync, useOverlayHost, usePluginRealtime, useReportingCurrencySync, useSurfaceUrl, useToolInvoker, useToolInvokerMap, useTypedToolInvokerMap, useView, withActiveNavHref };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map