Chaim Marcus
587a2a76ca
16 agent tools, event handler for auto-linking, sync job every 15m. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
120 lines
4.3 KiB
TypeScript
120 lines
4.3 KiB
TypeScript
import type { PluginDataResult, PluginActionFn, PluginHostContext, PluginStreamResult, PluginToastFn } from "./types.js";
|
|
/**
|
|
* Fetch data from the plugin worker's registered `getData` handler.
|
|
*
|
|
* Calls `ctx.data.register(key, handler)` in the worker and returns the
|
|
* result as reactive state. Re-fetches when `params` changes.
|
|
*
|
|
* @template T The expected shape of the returned data
|
|
* @param key - The data key matching the handler registered with `ctx.data.register()`
|
|
* @param params - Optional parameters forwarded to the handler
|
|
* @returns `PluginDataResult<T>` with `data`, `loading`, `error`, and `refresh`
|
|
*
|
|
* @example
|
|
* ```tsx
|
|
* function SyncWidget({ context }: PluginWidgetProps) {
|
|
* const { data, loading, error } = usePluginData<SyncHealth>("sync-health", {
|
|
* companyId: context.companyId,
|
|
* });
|
|
*
|
|
* if (loading) return <div>Loading…</div>;
|
|
* if (error) return <div>Error: {error.message}</div>;
|
|
* return <div>Synced Issues: {data!.syncedCount}</div>;
|
|
* }
|
|
* ```
|
|
*
|
|
* @see PLUGIN_SPEC.md §13.8 — `getData`
|
|
* @see PLUGIN_SPEC.md §19.7 — Error Propagation Through The Bridge
|
|
*/
|
|
export declare function usePluginData<T = unknown>(key: string, params?: Record<string, unknown>): PluginDataResult<T>;
|
|
/**
|
|
* Get a callable function that invokes the plugin worker's registered
|
|
* `performAction` handler.
|
|
*
|
|
* The returned function is async and throws a `PluginBridgeError` on failure.
|
|
*
|
|
* @param key - The action key matching the handler registered with `ctx.actions.register()`
|
|
* @returns An async function that sends the action to the worker and resolves with the result
|
|
*
|
|
* @example
|
|
* ```tsx
|
|
* function ResyncButton({ context }: PluginWidgetProps) {
|
|
* const resync = usePluginAction("resync");
|
|
* const [error, setError] = useState<string | null>(null);
|
|
*
|
|
* async function handleClick() {
|
|
* try {
|
|
* await resync({ companyId: context.companyId });
|
|
* } catch (err) {
|
|
* setError((err as PluginBridgeError).message);
|
|
* }
|
|
* }
|
|
*
|
|
* return <button onClick={handleClick}>Resync Now</button>;
|
|
* }
|
|
* ```
|
|
*
|
|
* @see PLUGIN_SPEC.md §13.9 — `performAction`
|
|
* @see PLUGIN_SPEC.md §19.7 — Error Propagation Through The Bridge
|
|
*/
|
|
export declare function usePluginAction(key: string): PluginActionFn;
|
|
/**
|
|
* Read the current host context (active company, project, entity, user).
|
|
*
|
|
* Use this to know which context the plugin component is being rendered in
|
|
* so you can scope data requests and actions accordingly.
|
|
*
|
|
* @returns The current `PluginHostContext`
|
|
*
|
|
* @example
|
|
* ```tsx
|
|
* function IssueTab() {
|
|
* const { companyId, entityId } = useHostContext();
|
|
* const { data } = usePluginData("linear-link", { issueId: entityId });
|
|
* return <div>{data?.linearIssueUrl}</div>;
|
|
* }
|
|
* ```
|
|
*
|
|
* @see PLUGIN_SPEC.md §19 — UI Extension Model
|
|
*/
|
|
export declare function useHostContext(): PluginHostContext;
|
|
/**
|
|
* Subscribe to a real-time event stream pushed from the plugin worker.
|
|
*
|
|
* Opens an SSE connection to `GET /api/plugins/:pluginId/bridge/stream/:channel`
|
|
* and accumulates events as they arrive. The worker pushes events using
|
|
* `ctx.streams.emit(channel, event)`.
|
|
*
|
|
* @template T The expected shape of each streamed event
|
|
* @param channel - The stream channel name (must match what the worker uses in `ctx.streams.emit`)
|
|
* @param options - Optional configuration for the stream
|
|
* @returns `PluginStreamResult<T>` with `events`, `lastEvent`, connection status, and `close()`
|
|
*
|
|
* @example
|
|
* ```tsx
|
|
* function ChatMessages() {
|
|
* const { events, connected, close } = usePluginStream<ChatToken>("chat-stream");
|
|
*
|
|
* return (
|
|
* <div>
|
|
* {events.map((e, i) => <span key={i}>{e.text}</span>)}
|
|
* {connected && <span className="pulse" />}
|
|
* <button onClick={close}>Stop</button>
|
|
* </div>
|
|
* );
|
|
* }
|
|
* ```
|
|
*
|
|
* @see PLUGIN_SPEC.md §19.8 — Real-Time Streaming
|
|
*/
|
|
export declare function usePluginStream<T = unknown>(channel: string, options?: {
|
|
companyId?: string;
|
|
}): PluginStreamResult<T>;
|
|
/**
|
|
* Trigger a host toast notification from plugin UI.
|
|
*
|
|
* This lets plugin pages and widgets surface user-facing feedback through the
|
|
* same toast system as the host app without reaching into host internals.
|
|
*/
|
|
export declare function usePluginToast(): PluginToastFn;
|
|
//# sourceMappingURL=hooks.d.ts.map
|