@litelens/core 1.7.6 → 1.7.11

package/README.md

@@ -16,10 +16,13 @@ This package is a **type/documentation surface only** — every export in `src/i
 
 So this package exists to give plugin authors real types, JSDoc, and editor autocomplete during development, while the host controls the actual behavior. If a hook's signature changes on the host side (`frontend/src/expose/hooks/`), update the matching declaration here to keep them in sync — there is no automated check that they match.
 
+The one exception is `createPluginBridge` (see "Using `createPluginBridge`" below): it is a real, self-contained implementation that lives in this package, not a stub. `frontend/src/expose/index.tsx` still wires it onto `window.__LITELENS_VENDOR__.core` like everything else here, but only as a straight pass-through — there is no separate host-side implementation for it to substitute.
+
 ## Contents
 
-- **`src/clusterWideAPI.ts`** (exported as `clusterWideAPI`) — capabilities scoped to the single-cluster view. See "Using `clusterWideAPI`" below.
-- **`src/appWideAPI.ts`** (exported as `appWideAPI`) — capabilities with no single-cluster-view constraint. See "Using `appWideAPI`" below.
+- **`src/api/clusterWideAPI.ts`** (exported as `clusterWideAPI`) — capabilities scoped to the single-cluster view. See "Using `clusterWideAPI`" below.
+- **`src/api/appWideAPI.ts`** (exported as `appWideAPI`) — capabilities with no single-cluster-view constraint. See "Using `appWideAPI`" below.
+- **`src/api/frontendBridgeAPI.ts`** (exported as `createPluginBridge`) — factory for a plugin's HTTP bridge to its own backend. See "Using `createPluginBridge`" below.
 - **`src/types/`** — shared TypeScript types re-exported alongside the API namespaces above (`api`, `nav`, `resources`, `tray`).
 - **`src/build/tsupPreset.ts`** (exported as `@litelens/core/tsup-preset`) — shared tsup build config for plugin frontends: Node-only build tooling, kept out of the `.` export above so it never ships in the browser bundle the vendor shim substitutes for. See "Shared plugin build config" below.
 
@@ -69,6 +72,21 @@ function HelmChartListView() {
 - **`registerStylesheets(pluginId, stylesheets)`** — registers your plugin's global stylesheet(s) (e.g. compiled Tailwind output), loaded once at the app level regardless of which of your views is active. Call this once at module scope, alongside the `clusterWideAPI` registration calls above — don't use per-view `stylesheet` on `registerViews` for CSS that should apply across all of your views.
 - **`getQueryClient()`** — returns the host's singleton `QueryClient`. Use this from code that isn't a mounted React component (e.g. the module-scope `registerEvents` handler above) and therefore can't call `useQueryClient()`.
 
+## Using `createPluginBridge`
+
+Business calls (`listCharts`, `installChart`, etc.) go straight from a plugin's frontend to its own backend over localhost HTTP, bypassing the host — see `litelens-plugins`' architecture notes for the full call-path rationale. `createPluginBridge(pluginID)` builds the fetch machinery for that path: it resolves the plugin's backend address via `window.go.app.App.GetPluginBackendAddr`, caches it, and retries once against a freshly-resolved address if a call fails with a network-level `TypeError` (the address went stale, e.g. the backend process restarted) — a `PluginError` response body from a reachable backend is not retried.
+
+Each plugin calls this once and wraps the returned `fetchWithRetry` in its own typed, per-endpoint exports, since payload shapes differ per plugin:
+
+```ts
+const { fetchWithRetry } = createPluginBridge("helm");
+
+export const ListHelmCharts = (): Promise<HelmChart[]> =>
+  fetchWithRetry<HelmChart[]>("listCharts", {});
+```
+
+`invalidateBackendAddrCache()` is exposed for callers that learn independently that the cached address is stale (e.g. a "plugin restarted" event) and want to force a fresh lookup on the next call.
+
 ## Shared plugin build config
 
 `@litelens/core/tsup-preset` exports `createPluginTsupConfig({ pluginRoot })`, the tsup config every plugin frontend needs: externalizes the host-shared runtime deps (`PLUGIN_SHARED_EXTERNALS`), inlines Tailwind-compiled CSS as text via a local Tailwind CLI pass, and optionally emits a bundle-analysis report to `dist/stats/` when `ANALYZE=true`. A plugin's own `tsup.config.ts` becomes:

package/dist/index.d.ts

@@ -1084,4 +1084,37 @@ declare const appWideAPI: {
     getQueryClient: typeof getQueryClient;
 };
 
-export { type CRBSubject, type ClusterRole, type ClusterRoleBinding, type ConfigMap, type CronJob, type CronJobSummary, type DaemonSet, type DaemonSetSummary, type Deployment, type DeploymentCondition, type DeploymentSummary, type Endpoint, type EndpointAddress, type EndpointPort, type EndpointSlice, type EndpointSliceEndpoint, type EndpointSlicePort, type EndpointSubset, type Event, type HPA, type HPADetail, type HPAMetric, type Ingress, type IngressClass, type IngressDetail, type IngressPath, type IngressRule, type Job, type JobCondition, type JobSummary, type Lease, type LimitRange, type LimitRangeDetail, type ManagedField, type Namespace, type NavEntry, type NavGroup, type NavItem, type NetworkPolicy, type NetworkPolicyDetail, type NetworkPolicyEgressRule, type NetworkPolicyIngressRule, type NetworkPolicyPeer, type Node, type NodeAddress, type NodeCondition, type PersistentVolume, type PersistentVolumeClaim, type PersistentVolumeClaimDetail, type PersistentVolumeDetail, type Pod, type PodCondition, type PodContainerDetail, type PodContainerLastStatus, type PodContainerMount, type PodContainerPort, type PodDisruptionBudget, type PodDisruptionBudgetDetail, type PodSummary, type PodVolume, type PodVolumeSource, type PolicyRule, type PortForward, type PriorityClass, type RBSubject, type ReplicaSet, type ReplicaSetSummary, type ResourceQuota, type ResourceQuotaDetail, type Role, type RoleBinding, type ScaleTargetRef, type Secret, type SecretDetail, type Service, type ServiceAccount, type ServicePort, type SharedNamespaceContext, type SharedUnifiedTrayContentProps, type SharedUnifiedTrayContext, type SharedUnifiedTrayOpenParams, type SharedUnifiedTrayTab, type StatefulSet, type StatefulSetSummary, type StorageClass, type TolerationDetail, type UnifiedTrayAllFamily, type UnifiedTrayCoreFamily, type UseQueryCallback, type ValidatingWebhookConfig, type ValidatingWebhookConfigDetail, type WebhookDetail, appWideAPI, clusterWideAPI };
+declare global {
+    interface Window {
+        go: {
+            app: {
+                App: {
+                    GetPluginBackendAddr(pluginID: string): Promise<string>;
+                };
+            };
+        };
+    }
+}
+type PluginError = {
+    code: string;
+    message: string;
+};
+type PluginBridge = {
+    fetchWithRetry: <T>(method: string, payload: unknown) => Promise<T>;
+    invalidateBackendAddrCache: () => void;
+};
+/**
+ * Builds the fetch/retry/address-caching machinery for one plugin. Each
+ * plugin's frontend calls this once with its own plugin ID and API path
+ * segment, then wraps the returned `fetchWithRetry` in its own typed,
+ * per-endpoint exports (payload shapes differ per plugin, so those stay in
+ * the plugin's own bridge module).
+ *
+ * Example:
+ *   const { fetchWithRetry } = createPluginBridge("helm");
+ *   export const ListHelmCharts = (): Promise<HelmChart[]> =>
+ *     fetchWithRetry<HelmChart[]>("listCharts", {});
+ */
+declare function createPluginBridge(pluginID: string): PluginBridge;
+
+export { type CRBSubject, type ClusterRole, type ClusterRoleBinding, type ConfigMap, type CronJob, type CronJobSummary, type DaemonSet, type DaemonSetSummary, type Deployment, type DeploymentCondition, type DeploymentSummary, type Endpoint, type EndpointAddress, type EndpointPort, type EndpointSlice, type EndpointSliceEndpoint, type EndpointSlicePort, type EndpointSubset, type Event, type HPA, type HPADetail, type HPAMetric, type Ingress, type IngressClass, type IngressDetail, type IngressPath, type IngressRule, type Job, type JobCondition, type JobSummary, type Lease, type LimitRange, type LimitRangeDetail, type ManagedField, type Namespace, type NavEntry, type NavGroup, type NavItem, type NetworkPolicy, type NetworkPolicyDetail, type NetworkPolicyEgressRule, type NetworkPolicyIngressRule, type NetworkPolicyPeer, type Node, type NodeAddress, type NodeCondition, type PersistentVolume, type PersistentVolumeClaim, type PersistentVolumeClaimDetail, type PersistentVolumeDetail, type PluginBridge, type PluginError, type Pod, type PodCondition, type PodContainerDetail, type PodContainerLastStatus, type PodContainerMount, type PodContainerPort, type PodDisruptionBudget, type PodDisruptionBudgetDetail, type PodSummary, type PodVolume, type PodVolumeSource, type PolicyRule, type PortForward, type PriorityClass, type RBSubject, type ReplicaSet, type ReplicaSetSummary, type ResourceQuota, type ResourceQuotaDetail, type Role, type RoleBinding, type ScaleTargetRef, type Secret, type SecretDetail, type Service, type ServiceAccount, type ServicePort, type SharedNamespaceContext, type SharedUnifiedTrayContentProps, type SharedUnifiedTrayContext, type SharedUnifiedTrayOpenParams, type SharedUnifiedTrayTab, type StatefulSet, type StatefulSetSummary, type StorageClass, type TolerationDetail, type UnifiedTrayAllFamily, type UnifiedTrayCoreFamily, type UseQueryCallback, type ValidatingWebhookConfig, type ValidatingWebhookConfigDetail, type WebhookDetail, appWideAPI, clusterWideAPI, createPluginBridge };

package/dist/index.js

@@ -1,4 +1,4 @@
-// src/clusterWideAPI.ts
+// src/api/clusterWideAPI.ts
 function useExposeProperties() {
   throw new Error(
     "clusterWideAPI.useExposeProperties is not available. This hook must be imported from '@litelens/core' within a plugin bundle loaded by the litelens host."
@@ -38,7 +38,7 @@ var clusterWideAPI = {
   registerEvents
 };
 
-// src/appWideAPI.ts
+// src/api/appWideAPI.ts
 function registerStylesheets(pluginId, stylesheets) {
   throw new Error(
     "appWideAPI.registerStylesheets is not available. This function must be imported from '@litelens/core' within a plugin bundle loaded by the litelens host."
@@ -54,4 +54,60 @@ var appWideAPI = {
   getQueryClient
 };
 
-export { appWideAPI, clusterWideAPI };
+// src/api/frontendBridgeAPI.ts
+function createPluginBridge(pluginID) {
+  let backendAddr = null;
+  let addressFetchPromise = null;
+  function invalidateBackendAddrCache() {
+    backendAddr = null;
+    addressFetchPromise = null;
+  }
+  async function getBackendAddr() {
+    if (backendAddr) return backendAddr;
+    if (addressFetchPromise) return addressFetchPromise;
+    addressFetchPromise = window.go.app.App.GetPluginBackendAddr(pluginID).then((addr) => {
+      backendAddr = addr;
+      addressFetchPromise = null;
+      return addr;
+    }).catch((err) => {
+      addressFetchPromise = null;
+      throw err;
+    });
+    return addressFetchPromise;
+  }
+  async function doFetch(method, payload, addr) {
+    const response = await fetch(`http://${addr}/api/${pluginID}/${method}`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(payload)
+    });
+    if (!response.ok) {
+      const errBody = await response.json();
+      throw errBody;
+    }
+    return await response.json();
+  }
+  async function fetchWithRetry(method, payload) {
+    const addr = await getBackendAddr();
+    try {
+      return await doFetch(method, payload, addr);
+    } catch (err) {
+      if (err instanceof TypeError) {
+        invalidateBackendAddrCache();
+        try {
+          const freshAddr = await getBackendAddr();
+          return await doFetch(method, payload, freshAddr);
+        } catch {
+          throw {
+            code: "PLUGIN_UNAVAILABLE",
+            message: "Plugin backend unreachable"
+          };
+        }
+      }
+      throw err;
+    }
+  }
+  return { fetchWithRetry, invalidateBackendAddrCache };
+}
+
+export { appWideAPI, clusterWideAPI, createPluginBridge };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@litelens/core",
-  "version": "1.7.6",
+  "version": "1.7.11",
   "description": "React hooks and utilities for litelens plugin development",
   "private": false,
   "repository": {