@zhama/tego-plugin-sdk 1.36.2 → 1.37.0

package/dist/react.cjs

@@ -0,0 +1 @@
+"use strict";var p=Object.defineProperty;var n=(e,t)=>p(e,"name",{value:t,configurable:!0});var react=require("react"),PluginApiError=class extends Error{static{n(this,"PluginApiError")}constructor(e,t,r,s={}){super(e),this.status=t,this.code=r,this.detail=s,this.name="PluginApiError"}status;code;detail};function toPluginApiError(e,t){const r=t&&typeof t=="object"?t.error:void 0;if(typeof r=="string")return new PluginApiError(r,e,void 0);if(r&&typeof r=="object"){const{code:s,message:i,detail:o}=r;return new PluginApiError(typeof i=="string"?i:`HTTP ${e}`,e,typeof s=="string"?s:void 0,o&&typeof o=="object"?o:{})}return new PluginApiError(`HTTP ${e}`,e,void 0)}n(toPluginApiError,"toPluginApiError");function createApiClient(e){const t=n(async(r,s,i)=>{const o=await e.request(s,i===void 0?{method:r}:{method:r,headers:{"content-type":"application/json"},body:JSON.stringify(i)}),u=await o.text();let c=null;try{c=u?JSON.parse(u):null}catch{c=u||null}if(!o.ok)throw toPluginApiError(o.status,c);return c},"send");return{get:n(r=>t("GET",r),"get"),post:n((r,s)=>t("POST",r,s??{}),"post"),put:n((r,s)=>t("PUT",r,s),"put"),patch:n((r,s)=>t("PATCH",r,s),"patch"),delete:n(r=>t("DELETE",r),"delete")}}n(createApiClient,"createApiClient");function withQuery(e,t){const r=new URLSearchParams;for(const[i,o]of Object.entries(t))o!==void 0&&o!==""&&r.set(i,String(o));const s=r.toString();return s?`${e}?${s}`:e}n(withQuery,"withQuery");function describeApiError(e,t){return e instanceof PluginApiError?e.code?{key:`${t}.errors.${e.code}`,message:e.message}:{message:e.message}:{message:e instanceof Error?e.message:String(e)}}n(describeApiError,"describeApiError");var HostContext=react.createContext(null);function HostProvider({value:e,children:t}){return react.createElement(HostContext.Provider,{value:e},t)}n(HostProvider,"HostProvider");function useHost(){const e=react.useContext(HostContext);if(!e)throw new Error("useHost() outside <HostProvider>");return e}n(useHost,"useHost");function usePluginRoute(){const{route:e}=useHost();return react.useSyncExternalStore(t=>e.subscribe(t),()=>e.current())}n(usePluginRoute,"usePluginRoute");function useLiveUpdates(e,t={}){const{events:r}=useHost(),s=react.useRef({onChange:e,filter:t.filter});s.current={onChange:e,filter:t.filter};const i=t.waitMs??400;react.useEffect(()=>{let o=[],u;const c=r.subscribe(a=>{s.current.filter&&!s.current.filter(a)||(o.push(a),!u&&(u=setTimeout(()=>{u=void 0;const l=o;o=[],s.current.onChange(l)},i)))});return()=>{c(),u&&clearTimeout(u)}},[r,i])}n(useLiveUpdates,"useLiveUpdates");var PluginErrorBoundary=class extends react.Component{static{n(this,"PluginErrorBoundary")}state={error:null};static getDerivedStateFromError(e){return{error:e instanceof Error?e:new Error(String(e))}}componentDidCatch(e,t){this.props.onError?.(e,t)}reset=n(()=>this.setState({error:null}),"reset");render(){return this.state.error?this.props.fallback(this.state.error,this.reset):this.props.children??null}};exports.HostProvider=HostProvider,exports.PluginApiError=PluginApiError,exports.PluginErrorBoundary=PluginErrorBoundary,exports.createApiClient=createApiClient,exports.describeApiError=describeApiError,exports.toPluginApiError=toPluginApiError,exports.useHost=useHost,exports.useLiveUpdates=useLiveUpdates,exports.usePluginRoute=usePluginRoute,exports.withQuery=withQuery;

package/dist/react.d.cts

@@ -0,0 +1,101 @@
+import * as react from 'react';
+import { ReactNode, Component, ErrorInfo } from 'react';
+import { PluginApiClient, PluginHostContext, PluginEvent, PluginRoute } from './frontend.cjs';
+
+/**
+ * Calls to the plugin's own backend through `ctx.api`, with errors that keep
+ * what the backend said.
+ *
+ * `ctx.api.json` throws a bare `Error('<method> <path>: <status>')` and drops
+ * the body, so a screen cannot tell "that note is locked" from "the server
+ * fell over". This keeps the code for translation and the message for the
+ * fallback. Two shapes arrive here: the plugin backend's
+ * `{ error: { code, message, detail? } }` (what `pluginErrorHandler` writes)
+ * and the gateway's `{ success: false, error: string | { message } }`.
+ */
+
+declare class PluginApiError extends Error {
+    readonly status: number;
+    readonly code: string | undefined;
+    readonly detail: Record<string, unknown>;
+    constructor(message: string, status: number, code: string | undefined, detail?: Record<string, unknown>);
+}
+/** The error a failed response carries, whichever side wrote it. */
+declare function toPluginApiError(status: number, body: unknown): PluginApiError;
+interface PluginApi {
+    get<T>(path: string): Promise<T>;
+    /** A POST without a body still sends `{}`: validators read JSON on every write. */
+    post<T>(path: string, body?: unknown): Promise<T>;
+    put<T>(path: string, body: unknown): Promise<T>;
+    patch<T>(path: string, body: unknown): Promise<T>;
+    delete<T>(path: string): Promise<T>;
+}
+declare function createApiClient(client: PluginApiClient): PluginApi;
+/** `path?a=1&b=x`, leaving out empty values. */
+declare function withQuery(path: string, params: Record<string, string | number | undefined>): string;
+/**
+ * What to tell the user about a failed call: the translation key
+ * `<namespace>.errors.<code>` when the backend sent a code, and the backend's
+ * own sentence as the fallback.
+ *
+ * ```ts
+ * const { key, message } = describeApiError(error, 'notes');
+ * return key ? t(key, { defaultValue: message }) : message;
+ * ```
+ */
+declare function describeApiError(error: unknown, namespace: string): {
+    key?: string;
+    message: string;
+};
+
+/** Makes `ctx` available to `useHost` / `usePluginRoute` below it. */
+declare function HostProvider({ value, children, }: {
+    value: PluginHostContext;
+    children?: ReactNode;
+}): react.FunctionComponentElement<react.ProviderProps<PluginHostContext | null>>;
+declare function useHost(): PluginHostContext;
+/**
+ * The in-plugin route, re-rendering on every host navigation.
+ *
+ * The shell does not remount the page when only the path below `/p/<id>`
+ * changes, so reading `ctx.route.current()` once is a stale page.
+ */
+declare function usePluginRoute(): PluginRoute;
+/**
+ * Calls `onChange` when the plugin's backend publishes events, at most once
+ * per `waitMs` (a burst of writes is one refresh). Pass a stable callback,
+ * e.g. `() => queryClient.invalidateQueries({ queryKey: ['notes'] })`.
+ *
+ * `filter` limits it to some event names. The stream may be down: keep a slow
+ * `refetchInterval` as a fallback (faster while `ctx.events.connected()` is false).
+ */
+declare function useLiveUpdates(onChange: (events: PluginEvent[]) => void, options?: {
+    waitMs?: number;
+    filter?: (event: PluginEvent) => boolean;
+}): void;
+interface BoundaryProps {
+    /** What to show instead of the crashed tree; `reset` renders the children again. */
+    fallback: (error: Error, reset: () => void) => ReactNode;
+    onError?(error: Error, info: ErrorInfo): void;
+    children?: ReactNode;
+}
+/**
+ * The plugin's own error boundary. The shell's boundary sits outside this
+ * React root and never sees an error thrown inside it: without one a render
+ * error is a blank page that reads as the platform losing the plugin.
+ */
+declare class PluginErrorBoundary extends Component<BoundaryProps, {
+    error: Error | null;
+}> {
+    state: {
+        error: Error | null;
+    };
+    static getDerivedStateFromError(error: unknown): {
+        error: Error;
+    };
+    componentDidCatch(error: Error, info: ErrorInfo): void;
+    private readonly reset;
+    render(): ReactNode;
+}
+
+export { HostProvider, type PluginApi, PluginApiError, PluginErrorBoundary, createApiClient, describeApiError, toPluginApiError, useHost, useLiveUpdates, usePluginRoute, withQuery };

package/dist/react.d.ts

@@ -0,0 +1,101 @@
+import * as react from 'react';
+import { ReactNode, Component, ErrorInfo } from 'react';
+import { PluginApiClient, PluginHostContext, PluginEvent, PluginRoute } from './frontend.js';
+
+/**
+ * Calls to the plugin's own backend through `ctx.api`, with errors that keep
+ * what the backend said.
+ *
+ * `ctx.api.json` throws a bare `Error('<method> <path>: <status>')` and drops
+ * the body, so a screen cannot tell "that note is locked" from "the server
+ * fell over". This keeps the code for translation and the message for the
+ * fallback. Two shapes arrive here: the plugin backend's
+ * `{ error: { code, message, detail? } }` (what `pluginErrorHandler` writes)
+ * and the gateway's `{ success: false, error: string | { message } }`.
+ */
+
+declare class PluginApiError extends Error {
+    readonly status: number;
+    readonly code: string | undefined;
+    readonly detail: Record<string, unknown>;
+    constructor(message: string, status: number, code: string | undefined, detail?: Record<string, unknown>);
+}
+/** The error a failed response carries, whichever side wrote it. */
+declare function toPluginApiError(status: number, body: unknown): PluginApiError;
+interface PluginApi {
+    get<T>(path: string): Promise<T>;
+    /** A POST without a body still sends `{}`: validators read JSON on every write. */
+    post<T>(path: string, body?: unknown): Promise<T>;
+    put<T>(path: string, body: unknown): Promise<T>;
+    patch<T>(path: string, body: unknown): Promise<T>;
+    delete<T>(path: string): Promise<T>;
+}
+declare function createApiClient(client: PluginApiClient): PluginApi;
+/** `path?a=1&b=x`, leaving out empty values. */
+declare function withQuery(path: string, params: Record<string, string | number | undefined>): string;
+/**
+ * What to tell the user about a failed call: the translation key
+ * `<namespace>.errors.<code>` when the backend sent a code, and the backend's
+ * own sentence as the fallback.
+ *
+ * ```ts
+ * const { key, message } = describeApiError(error, 'notes');
+ * return key ? t(key, { defaultValue: message }) : message;
+ * ```
+ */
+declare function describeApiError(error: unknown, namespace: string): {
+    key?: string;
+    message: string;
+};
+
+/** Makes `ctx` available to `useHost` / `usePluginRoute` below it. */
+declare function HostProvider({ value, children, }: {
+    value: PluginHostContext;
+    children?: ReactNode;
+}): react.FunctionComponentElement<react.ProviderProps<PluginHostContext | null>>;
+declare function useHost(): PluginHostContext;
+/**
+ * The in-plugin route, re-rendering on every host navigation.
+ *
+ * The shell does not remount the page when only the path below `/p/<id>`
+ * changes, so reading `ctx.route.current()` once is a stale page.
+ */
+declare function usePluginRoute(): PluginRoute;
+/**
+ * Calls `onChange` when the plugin's backend publishes events, at most once
+ * per `waitMs` (a burst of writes is one refresh). Pass a stable callback,
+ * e.g. `() => queryClient.invalidateQueries({ queryKey: ['notes'] })`.
+ *
+ * `filter` limits it to some event names. The stream may be down: keep a slow
+ * `refetchInterval` as a fallback (faster while `ctx.events.connected()` is false).
+ */
+declare function useLiveUpdates(onChange: (events: PluginEvent[]) => void, options?: {
+    waitMs?: number;
+    filter?: (event: PluginEvent) => boolean;
+}): void;
+interface BoundaryProps {
+    /** What to show instead of the crashed tree; `reset` renders the children again. */
+    fallback: (error: Error, reset: () => void) => ReactNode;
+    onError?(error: Error, info: ErrorInfo): void;
+    children?: ReactNode;
+}
+/**
+ * The plugin's own error boundary. The shell's boundary sits outside this
+ * React root and never sees an error thrown inside it: without one a render
+ * error is a blank page that reads as the platform losing the plugin.
+ */
+declare class PluginErrorBoundary extends Component<BoundaryProps, {
+    error: Error | null;
+}> {
+    state: {
+        error: Error | null;
+    };
+    static getDerivedStateFromError(error: unknown): {
+        error: Error;
+    };
+    componentDidCatch(error: Error, info: ErrorInfo): void;
+    private readonly reset;
+    render(): ReactNode;
+}
+
+export { HostProvider, type PluginApi, PluginApiError, PluginErrorBoundary, createApiClient, describeApiError, toPluginApiError, useHost, useLiveUpdates, usePluginRoute, withQuery };

package/dist/react.js

@@ -0,0 +1 @@
+var h=Object.defineProperty;var s=(e,t)=>h(e,"name",{value:t,configurable:!0});import{createContext as E,createElement as m,useContext as v,useSyncExternalStore as P,useRef as w,useEffect as y,Component as S}from"react";var a=class extends Error{static{s(this,"PluginApiError")}constructor(e,t,r,n={}){super(e),this.status=t,this.code=r,this.detail=n,this.name="PluginApiError"}status;code;detail};function d(e,t){const r=t&&typeof t=="object"?t.error:void 0;if(typeof r=="string")return new a(r,e,void 0);if(r&&typeof r=="object"){const{code:n,message:i,detail:o}=r;return new a(typeof i=="string"?i:`HTTP ${e}`,e,typeof n=="string"?n:void 0,o&&typeof o=="object"?o:{})}return new a(`HTTP ${e}`,e,void 0)}s(d,"toPluginApiError");function b(e){const t=s(async(r,n,i)=>{const o=await e.request(n,i===void 0?{method:r}:{method:r,headers:{"content-type":"application/json"},body:JSON.stringify(i)}),c=await o.text();let u=null;try{u=c?JSON.parse(c):null}catch{u=c||null}if(!o.ok)throw d(o.status,u);return u},"send");return{get:s(r=>t("GET",r),"get"),post:s((r,n)=>t("POST",r,n??{}),"post"),put:s((r,n)=>t("PUT",r,n),"put"),patch:s((r,n)=>t("PATCH",r,n),"patch"),delete:s(r=>t("DELETE",r),"delete")}}s(b,"createApiClient");function T(e,t){const r=new URLSearchParams;for(const[i,o]of Object.entries(t))o!==void 0&&o!==""&&r.set(i,String(o));const n=r.toString();return n?`${e}?${n}`:e}s(T,"withQuery");function x(e,t){return e instanceof a?e.code?{key:`${t}.errors.${e.code}`,message:e.message}:{message:e.message}:{message:e instanceof Error?e.message:String(e)}}s(x,"describeApiError");var p=E(null);function H({value:e,children:t}){return m(p.Provider,{value:e},t)}s(H,"HostProvider");function l(){const e=v(p);if(!e)throw new Error("useHost() outside <HostProvider>");return e}s(l,"useHost");function C(){const{route:e}=l();return P(t=>e.subscribe(t),()=>e.current())}s(C,"usePluginRoute");function A(e,t={}){const{events:r}=l(),n=w({onChange:e,filter:t.filter});n.current={onChange:e,filter:t.filter};const i=t.waitMs??400;y(()=>{let o=[],c;const u=r.subscribe(f=>{n.current.filter&&!n.current.filter(f)||(o.push(f),!c&&(c=setTimeout(()=>{c=void 0;const g=o;o=[],n.current.onChange(g)},i)))});return()=>{u(),c&&clearTimeout(c)}},[r,i])}s(A,"useLiveUpdates");var $=class extends S{static{s(this,"PluginErrorBoundary")}state={error:null};static getDerivedStateFromError(e){return{error:e instanceof Error?e:new Error(String(e))}}componentDidCatch(e,t){this.props.onError?.(e,t)}reset=s(()=>this.setState({error:null}),"reset");render(){return this.state.error?this.props.fallback(this.state.error,this.reset):this.props.children??null}};export{H as HostProvider,a as PluginApiError,$ as PluginErrorBoundary,b as createApiClient,x as describeApiError,d as toPluginApiError,l as useHost,A as useLiveUpdates,C as usePluginRoute,T as withQuery};