esoul-sdk 0.3.0

package/dist/manifest.d.ts

@@ -0,0 +1,359 @@
+import { z } from "zod";
+/**
+ * plugin.json — THE package contract. This file is the source of truth for
+ * the schema; the host imports it from here, and
+ * `schemas/plugin.schema.json` is generated from it at build time so
+ * non-TS tooling (and LLMs) can validate without executing anything.
+ *
+ * SECRETS NEVER LIVE IN A MANIFEST: oauth2 connections declare provider
+ * endpoints + ENV VAR NAMES; apiKey connections declare header NAMES.
+ * Value-shaped keys are rejected by `.strict()` and by the validator CLI.
+ */
+export declare const PLUGIN_MANIFEST_VERSION: 1;
+/** The plugin-contract version THIS SDK (and the matching host) speak.
+ * Manifests may pin `platformApi: {min, max?}`; the host refuses installs
+ * outside the range at sync time (fail loud at install, never at runtime).
+ * 1.1.0: fileSources consent + fileProviders contributions (additive). */
+export declare const PLATFORM_API_VERSION = "1.1.0";
+export declare const PluginConnectionSchema: z.ZodEffects<z.ZodObject<{
+    /** Stable key within the plugin, e.g. "microsoft". */
+    key: z.ZodString;
+    kind: z.ZodEnum<["oauth2", "apiKey"]>;
+    label: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+    /** oauth2: provider endpoints (authorization-code + PKCE). */
+    authorizeUrl: z.ZodOptional<z.ZodString>;
+    tokenUrl: z.ZodOptional<z.ZodString>;
+    oauthScopes: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    /** oauth2: ENV VAR NAMES holding client credentials. */
+    clientIdEnv: z.ZodOptional<z.ZodString>;
+    clientSecretEnv: z.ZodOptional<z.ZodString>;
+    /** apiKey: header NAMES the plugin will send (never values). */
+    headerNames: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+}, "strict", z.ZodTypeAny, {
+    key: string;
+    kind: "oauth2" | "apiKey";
+    label: string;
+    description?: string | undefined;
+    authorizeUrl?: string | undefined;
+    tokenUrl?: string | undefined;
+    oauthScopes?: string[] | undefined;
+    clientIdEnv?: string | undefined;
+    clientSecretEnv?: string | undefined;
+    headerNames?: string[] | undefined;
+}, {
+    key: string;
+    kind: "oauth2" | "apiKey";
+    label: string;
+    description?: string | undefined;
+    authorizeUrl?: string | undefined;
+    tokenUrl?: string | undefined;
+    oauthScopes?: string[] | undefined;
+    clientIdEnv?: string | undefined;
+    clientSecretEnv?: string | undefined;
+    headerNames?: string[] | undefined;
+}>, {
+    key: string;
+    kind: "oauth2" | "apiKey";
+    label: string;
+    description?: string | undefined;
+    authorizeUrl?: string | undefined;
+    tokenUrl?: string | undefined;
+    oauthScopes?: string[] | undefined;
+    clientIdEnv?: string | undefined;
+    clientSecretEnv?: string | undefined;
+    headerNames?: string[] | undefined;
+}, {
+    key: string;
+    kind: "oauth2" | "apiKey";
+    label: string;
+    description?: string | undefined;
+    authorizeUrl?: string | undefined;
+    tokenUrl?: string | undefined;
+    oauthScopes?: string[] | undefined;
+    clientIdEnv?: string | undefined;
+    clientSecretEnv?: string | undefined;
+    headerNames?: string[] | undefined;
+}>;
+export declare const PluginManifestSchema: z.ZodObject<{
+    manifestVersion: z.ZodLiteral<1>;
+    /** Directory name under src/plugins/. Kebab-case. */
+    id: z.ZodString;
+    name: z.ZodString;
+    version: z.ZodString;
+    description: z.ZodString;
+    /** The ApplicationSchema.applicationType the entry module declares.
+     * MUST be plugin_-namespaced: the platform uses the prefix to tell
+     * "unknown plugin type — honest card" apart from retired built-ins,
+     * and it keeps plugin types out of the built-in namespace forever. */
+    applicationType: z.ZodString;
+    /** Entry module basename (no extension) exporting `pluginSchema`. */
+    entry: z.ZodString;
+    /**
+     * Launcher icon: a lucide-react component name ("Bird", "Gamepad2") from the
+     * platform's curated set (`PLUGIN_ICON_CHOICES` in src/lib/app-icons.ts).
+     * Unknown names fall back to the generic glyph — never a broken tile. This is
+     * how a plugin gets a real icon in the picker without a platform edit.
+     */
+    icon: z.ZodOptional<z.ZodString>;
+    author: z.ZodOptional<z.ZodObject<{
+        name: z.ZodString;
+        email: z.ZodOptional<z.ZodString>;
+        url: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        name: string;
+        email?: string | undefined;
+        url?: string | undefined;
+    }, {
+        name: string;
+        email?: string | undefined;
+        url?: string | undefined;
+    }>>;
+    /** Tasks the BROWSER may kick via /api/inngest/send-event. */
+    kickableTasks: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodString, "many">>>;
+    /** Push-ingress endpoints — POST|GET /api/plugins/<id>/webhook/<name>. */
+    webhooks: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodString, "many">>>;
+    /** Server ops — POST /api/plugins/<id>/op/<name> (platform-gated). */
+    ops: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodString, "many">>>;
+    /** Poll cadences for durable tasks (the offline-safe pull lane). */
+    pollTasks: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodObject<{
+        task: z.ZodString;
+        everyMinutes: z.ZodNumber;
+    }, "strip", z.ZodTypeAny, {
+        task: string;
+        everyMinutes: number;
+    }, {
+        task: string;
+        everyMinutes: number;
+    }>, "many">>>;
+    /** Contract-version pin: refuse install outside [min, max]. */
+    platformApi: z.ZodOptional<z.ZodObject<{
+        min: z.ZodString;
+        max: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        min: string;
+        max?: string | undefined;
+    }, {
+        min: string;
+        max?: string | undefined;
+    }>>;
+    /** Reserved for the review/consent flow. */
+    scopes: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodString, "many">>>;
+    /**
+     * Tools of OTHER apps in the workspace this plugin's UI may invoke through
+     * `useWorkspaceTools()` — "<applicationType>:<tool base name>", e.g.
+     * "spreadsheet:add_row". This is the grant wall for an INSTALLED plugin:
+     * the server refuses a call the manifest does not name (the reviewed PR is
+     * the consent — plugins are reviewed code, unlike App-Maker specs, which
+     * are data and ask each user). In the Forge's live preview (dev mode) the
+     * call rides the board's own tab to the owner's workspace instead.
+     */
+    workspaceTools: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodString, "many">>>;
+    /** Third-party logins surfaced in Account settings → Plugins. */
+    connections: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodEffects<z.ZodObject<{
+        /** Stable key within the plugin, e.g. "microsoft". */
+        key: z.ZodString;
+        kind: z.ZodEnum<["oauth2", "apiKey"]>;
+        label: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
+        /** oauth2: provider endpoints (authorization-code + PKCE). */
+        authorizeUrl: z.ZodOptional<z.ZodString>;
+        tokenUrl: z.ZodOptional<z.ZodString>;
+        oauthScopes: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        /** oauth2: ENV VAR NAMES holding client credentials. */
+        clientIdEnv: z.ZodOptional<z.ZodString>;
+        clientSecretEnv: z.ZodOptional<z.ZodString>;
+        /** apiKey: header NAMES the plugin will send (never values). */
+        headerNames: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    }, "strict", z.ZodTypeAny, {
+        key: string;
+        kind: "oauth2" | "apiKey";
+        label: string;
+        description?: string | undefined;
+        authorizeUrl?: string | undefined;
+        tokenUrl?: string | undefined;
+        oauthScopes?: string[] | undefined;
+        clientIdEnv?: string | undefined;
+        clientSecretEnv?: string | undefined;
+        headerNames?: string[] | undefined;
+    }, {
+        key: string;
+        kind: "oauth2" | "apiKey";
+        label: string;
+        description?: string | undefined;
+        authorizeUrl?: string | undefined;
+        tokenUrl?: string | undefined;
+        oauthScopes?: string[] | undefined;
+        clientIdEnv?: string | undefined;
+        clientSecretEnv?: string | undefined;
+        headerNames?: string[] | undefined;
+    }>, {
+        key: string;
+        kind: "oauth2" | "apiKey";
+        label: string;
+        description?: string | undefined;
+        authorizeUrl?: string | undefined;
+        tokenUrl?: string | undefined;
+        oauthScopes?: string[] | undefined;
+        clientIdEnv?: string | undefined;
+        clientSecretEnv?: string | undefined;
+        headerNames?: string[] | undefined;
+    }, {
+        key: string;
+        kind: "oauth2" | "apiKey";
+        label: string;
+        description?: string | undefined;
+        authorizeUrl?: string | undefined;
+        tokenUrl?: string | undefined;
+        oauthScopes?: string[] | undefined;
+        clientIdEnv?: string | undefined;
+        clientSecretEnv?: string | undefined;
+        headerNames?: string[] | undefined;
+    }>, "many">>>;
+    /**
+     * File-access consent (plugin-file-sources.md §3). EXPLICIT-ONLY: absent
+     * means the plugin's server code gets NO file API at all. `workspace`
+     * grants the workspace source (read / readwrite); `providers` names the
+     * OTHER mounts it may read ("google-drive", "local", or another plugin's
+     * providerKey). A plugin's own contributed providers are implicit.
+     * Rendered verbatim in the Settings consent panel.
+     */
+    fileSources: z.ZodOptional<z.ZodObject<{
+        workspace: z.ZodOptional<z.ZodEnum<["read", "readwrite"]>>;
+        providers: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodString, "many">>>;
+    }, "strict", z.ZodTypeAny, {
+        providers: string[];
+        workspace?: "read" | "readwrite" | undefined;
+    }, {
+        workspace?: "read" | "readwrite" | undefined;
+        providers?: string[] | undefined;
+    }>>;
+    /**
+     * File providers this plugin CONTRIBUTES (plugin-file-sources.md §2):
+     * one mount per ACTIVE connection of `connectionKey`. `key` is globally
+     * unique across installed plugins (host keys workspace/google-drive/local
+     * reserved — sync refuses collisions); the implementation is
+     * `pluginServer.fileProviders[key]` in server.ts.
+     */
+    fileProviders: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodObject<{
+        key: z.ZodString;
+        connectionKey: z.ZodString;
+        label: z.ZodString;
+    }, "strict", z.ZodTypeAny, {
+        key: string;
+        label: string;
+        connectionKey: string;
+    }, {
+        key: string;
+        label: string;
+        connectionKey: string;
+    }>, "many">>>;
+}, "strip", z.ZodTypeAny, {
+    description: string;
+    manifestVersion: 1;
+    id: string;
+    name: string;
+    version: string;
+    applicationType: string;
+    entry: string;
+    kickableTasks: string[];
+    webhooks: string[];
+    ops: string[];
+    pollTasks: {
+        task: string;
+        everyMinutes: number;
+    }[];
+    scopes: string[];
+    workspaceTools: string[];
+    connections: {
+        key: string;
+        kind: "oauth2" | "apiKey";
+        label: string;
+        description?: string | undefined;
+        authorizeUrl?: string | undefined;
+        tokenUrl?: string | undefined;
+        oauthScopes?: string[] | undefined;
+        clientIdEnv?: string | undefined;
+        clientSecretEnv?: string | undefined;
+        headerNames?: string[] | undefined;
+    }[];
+    fileProviders: {
+        key: string;
+        label: string;
+        connectionKey: string;
+    }[];
+    icon?: string | undefined;
+    author?: {
+        name: string;
+        email?: string | undefined;
+        url?: string | undefined;
+    } | undefined;
+    platformApi?: {
+        min: string;
+        max?: string | undefined;
+    } | undefined;
+    fileSources?: {
+        providers: string[];
+        workspace?: "read" | "readwrite" | undefined;
+    } | undefined;
+}, {
+    description: string;
+    manifestVersion: 1;
+    id: string;
+    name: string;
+    version: string;
+    applicationType: string;
+    entry: string;
+    icon?: string | undefined;
+    author?: {
+        name: string;
+        email?: string | undefined;
+        url?: string | undefined;
+    } | undefined;
+    kickableTasks?: string[] | undefined;
+    webhooks?: string[] | undefined;
+    ops?: string[] | undefined;
+    pollTasks?: {
+        task: string;
+        everyMinutes: number;
+    }[] | undefined;
+    platformApi?: {
+        min: string;
+        max?: string | undefined;
+    } | undefined;
+    scopes?: string[] | undefined;
+    workspaceTools?: string[] | undefined;
+    connections?: {
+        key: string;
+        kind: "oauth2" | "apiKey";
+        label: string;
+        description?: string | undefined;
+        authorizeUrl?: string | undefined;
+        tokenUrl?: string | undefined;
+        oauthScopes?: string[] | undefined;
+        clientIdEnv?: string | undefined;
+        clientSecretEnv?: string | undefined;
+        headerNames?: string[] | undefined;
+    }[] | undefined;
+    fileSources?: {
+        workspace?: "read" | "readwrite" | undefined;
+        providers?: string[] | undefined;
+    } | undefined;
+    fileProviders?: {
+        key: string;
+        label: string;
+        connectionKey: string;
+    }[] | undefined;
+}>;
+export type PluginManifest = z.infer<typeof PluginManifestSchema>;
+export type PluginConnectionDecl = z.infer<typeof PluginConnectionSchema>;
+/** Data-only row the host codegen inlines into registry.gen.ts. */
+export interface InstalledPluginInfo {
+    id: string;
+    name: string;
+    version: string;
+    description: string;
+    applicationType: string;
+    /** Manifest `workspaceTools` — the installed plugin's cross-app grant wall. */
+    workspaceTools?: string[];
+}

package/dist/manifest.js

@@ -0,0 +1,136 @@
+import { z } from "zod";
+/**
+ * plugin.json — THE package contract. This file is the source of truth for
+ * the schema; the host imports it from here, and
+ * `schemas/plugin.schema.json` is generated from it at build time so
+ * non-TS tooling (and LLMs) can validate without executing anything.
+ *
+ * SECRETS NEVER LIVE IN A MANIFEST: oauth2 connections declare provider
+ * endpoints + ENV VAR NAMES; apiKey connections declare header NAMES.
+ * Value-shaped keys are rejected by `.strict()` and by the validator CLI.
+ */
+export const PLUGIN_MANIFEST_VERSION = 1;
+/** The plugin-contract version THIS SDK (and the matching host) speak.
+ * Manifests may pin `platformApi: {min, max?}`; the host refuses installs
+ * outside the range at sync time (fail loud at install, never at runtime).
+ * 1.1.0: fileSources consent + fileProviders contributions (additive). */
+export const PLATFORM_API_VERSION = "1.1.0";
+export const PluginConnectionSchema = z
+    .object({
+    /** Stable key within the plugin, e.g. "microsoft". */
+    key: z.string().regex(/^[a-z][a-z0-9-]*$/),
+    kind: z.enum(["oauth2", "apiKey"]),
+    label: z.string().min(1).max(60),
+    description: z.string().max(300).optional(),
+    /** oauth2: provider endpoints (authorization-code + PKCE). */
+    authorizeUrl: z.string().url().optional(),
+    tokenUrl: z.string().url().optional(),
+    oauthScopes: z.array(z.string()).optional(),
+    /** oauth2: ENV VAR NAMES holding client credentials. */
+    clientIdEnv: z.string().regex(/^[A-Z][A-Z0-9_]*$/).optional(),
+    clientSecretEnv: z.string().regex(/^[A-Z][A-Z0-9_]*$/).optional(),
+    /** apiKey: header NAMES the plugin will send (never values). */
+    headerNames: z.array(z.string()).optional(),
+})
+    .strict()
+    .refine((c) => c.kind !== "oauth2" ||
+    (!!c.authorizeUrl && !!c.tokenUrl && !!c.clientIdEnv), { message: "oauth2 connections require authorizeUrl + tokenUrl + clientIdEnv" });
+export const PluginManifestSchema = z.object({
+    manifestVersion: z.literal(PLUGIN_MANIFEST_VERSION),
+    /** Directory name under src/plugins/. Kebab-case. */
+    id: z.string().regex(/^[a-z][a-z0-9-]*$/),
+    name: z.string().min(1).max(80),
+    version: z.string().regex(/^\d+\.\d+\.\d+$/),
+    description: z.string().min(1).max(500),
+    /** The ApplicationSchema.applicationType the entry module declares.
+     * MUST be plugin_-namespaced: the platform uses the prefix to tell
+     * "unknown plugin type — honest card" apart from retired built-ins,
+     * and it keeps plugin types out of the built-in namespace forever. */
+    applicationType: z.string().regex(/^plugin_[a-z0-9_]*$/),
+    /** Entry module basename (no extension) exporting `pluginSchema`. */
+    entry: z.string().regex(/^[a-zA-Z0-9_-]+$/),
+    /**
+     * Launcher icon: a lucide-react component name ("Bird", "Gamepad2") from the
+     * platform's curated set (`PLUGIN_ICON_CHOICES` in src/lib/app-icons.ts).
+     * Unknown names fall back to the generic glyph — never a broken tile. This is
+     * how a plugin gets a real icon in the picker without a platform edit.
+     */
+    icon: z.string().regex(/^[A-Z][A-Za-z0-9]*$/).max(40).optional(),
+    author: z
+        .object({
+        name: z.string(),
+        email: z.string().optional(),
+        url: z.string().optional(),
+    })
+        .optional(),
+    /** Tasks the BROWSER may kick via /api/inngest/send-event. */
+    kickableTasks: z.array(z.string()).optional().default([]),
+    /** Push-ingress endpoints — POST|GET /api/plugins/<id>/webhook/<name>. */
+    webhooks: z.array(z.string().regex(/^[a-z][a-z0-9-]*$/)).optional().default([]),
+    /** Server ops — POST /api/plugins/<id>/op/<name> (platform-gated). */
+    ops: z.array(z.string().regex(/^[a-z][a-z0-9_-]*$/)).optional().default([]),
+    /** Poll cadences for durable tasks (the offline-safe pull lane). */
+    pollTasks: z
+        .array(z.object({
+        task: z.string(),
+        everyMinutes: z.number().int().min(5).max(1440),
+    }))
+        .optional()
+        .default([]),
+    /** Contract-version pin: refuse install outside [min, max]. */
+    platformApi: z
+        .object({ min: z.string().regex(/^\d+\.\d+\.\d+$/), max: z.string().regex(/^\d+\.\d+\.\d+$/).optional() })
+        .optional(),
+    /** Reserved for the review/consent flow. */
+    scopes: z.array(z.string()).optional().default([]),
+    /**
+     * Tools of OTHER apps in the workspace this plugin's UI may invoke through
+     * `useWorkspaceTools()` — "<applicationType>:<tool base name>", e.g.
+     * "spreadsheet:add_row". This is the grant wall for an INSTALLED plugin:
+     * the server refuses a call the manifest does not name (the reviewed PR is
+     * the consent — plugins are reviewed code, unlike App-Maker specs, which
+     * are data and ask each user). In the Forge's live preview (dev mode) the
+     * call rides the board's own tab to the owner's workspace instead.
+     */
+    workspaceTools: z
+        .array(z.string().regex(/^[a-z][a-z0-9_]*:[a-z][a-z0-9_]*$/))
+        .optional()
+        .default([]),
+    /** Third-party logins surfaced in Account settings → Plugins. */
+    connections: z.array(PluginConnectionSchema).optional().default([]),
+    /**
+     * File-access consent (plugin-file-sources.md §3). EXPLICIT-ONLY: absent
+     * means the plugin's server code gets NO file API at all. `workspace`
+     * grants the workspace source (read / readwrite); `providers` names the
+     * OTHER mounts it may read ("google-drive", "local", or another plugin's
+     * providerKey). A plugin's own contributed providers are implicit.
+     * Rendered verbatim in the Settings consent panel.
+     */
+    fileSources: z
+        .object({
+        workspace: z.enum(["read", "readwrite"]).optional(),
+        providers: z
+            .array(z.string().regex(/^[a-z][a-z0-9-]*$/))
+            .optional()
+            .default([]),
+    })
+        .strict()
+        .optional(),
+    /**
+     * File providers this plugin CONTRIBUTES (plugin-file-sources.md §2):
+     * one mount per ACTIVE connection of `connectionKey`. `key` is globally
+     * unique across installed plugins (host keys workspace/google-drive/local
+     * reserved — sync refuses collisions); the implementation is
+     * `pluginServer.fileProviders[key]` in server.ts.
+     */
+    fileProviders: z
+        .array(z
+        .object({
+        key: z.string().regex(/^[a-z][a-z0-9-]*$/),
+        connectionKey: z.string().regex(/^[a-z][a-z0-9-]*$/),
+        label: z.string().min(1).max(60),
+    })
+        .strict())
+        .optional()
+        .default([]),
+});

package/dist/react.d.ts

@@ -0,0 +1,85 @@
+/**
+ * React hooks for plugin UIs. HOST-PROVIDED: inside the app,
+ * `esoul-sdk/react` is aliased to the real implementations
+ * (which read venus state through the injection bridge — never import
+ * venus-slice or client-registry yourself: module-init cycle, and a bare
+ * require() crashes browser ESM chunks; both were hit live).
+ *
+ * Outside the host these throw with a clear message; in component tests,
+ * mock this module.
+ */
+import type { EventData } from "./types.js";
+/** Dispatch a workspace event from your UI — the ONLY sanctioned path.
+ * Respects read-only viewers (no-op when the viewer cannot edit). */
+export declare function usePluginEventDispatch(): (evt: EventData<any>) => EventData<any> | null;
+/** Current open chat id, for `chatIdSource` attribution. */
+export declare function usePluginCurrentChatId(): string;
+/** True when the current viewer may mutate this workspace. */
+export declare function useAppCanEdit(): boolean;
+export interface WorkspaceToolCall {
+    /** Resolve the target by type: the workspace's oldest non-hidden app of this type. */
+    appType?: string;
+    /** Or name the exact instance (from `listApps`). */
+    targetNodeId?: string;
+    /** The tool's BASE name (no instance suffix): "add_row", "read_sheet", "add_event". */
+    tool: string;
+    args?: Record<string, unknown>;
+}
+export interface WorkspaceToolResult {
+    ok: boolean;
+    /** The tool's answer, or the refusal — always a sentence a UI can show. */
+    text: string;
+}
+export interface WorkspaceAppSummary {
+    nodeId: string;
+    applicationType: string;
+    instanceName: string;
+}
+export interface WorkspaceTools {
+    /** False when nothing can answer: a read-only viewer, or a preview outside the Forge. */
+    available: boolean;
+    /** Where calls land — the workspace's name when known. */
+    workspaceName: string | null;
+    call: (c: WorkspaceToolCall) => Promise<WorkspaceToolResult>;
+    listApps: () => Promise<WorkspaceAppSummary[]>;
+}
+/**
+ * Invoke tools of OTHER apps in the workspace (append a spreadsheet row, add a
+ * calendar event…). Declare each as "<applicationType>:<tool>" in plugin.json
+ * `workspaceTools` — that list is the grant wall once installed. In the
+ * Forge's live preview the same call rides the board's tab to the owner's
+ * real workspace, so a plugin under construction already talks to its
+ * neighbours. Pass the app's identity from its state.
+ */
+export declare function useWorkspaceTools(_identity: {
+    workspaceId: string;
+    nodeId: string;
+}): WorkspaceTools;
+import type { FileEntry, FileSource } from "./files.js";
+export interface PluginWorkspaceFile {
+    id: string;
+    name: string;
+    url: string;
+}
+export interface FileSourcesState {
+    sources: FileSource[];
+    loading: boolean;
+    error: string | null;
+    reload: () => void;
+}
+export interface FileEntriesState {
+    entries: FileEntry[];
+    next: string | null;
+    loading: boolean;
+    error: string | null;
+    errorKind: string | null;
+    reload: () => void;
+}
+/** The current workspace's file catalogue, live from the store. */
+export declare function usePluginWorkspaceFiles(): PluginWorkspaceFile[];
+/** Upload a browser File into the workspace (blob → row → live list). */
+export declare function usePluginFileUpload(_workspaceId: string): (file: File) => Promise<PluginWorkspaceFile>;
+/** All mounts the signed-in user can see for this workspace. */
+export declare function useFileSources(_workspaceId: string | null): FileSourcesState;
+/** One mount's listing; a failing source reports error/errorKind, never []. */
+export declare function useFileSourceEntries(_workspaceId: string | null, _sourceId: string | null, _folderRef?: string): FileEntriesState;

package/dist/react.js

@@ -0,0 +1,43 @@
+const hostOnly = (name) => {
+    throw new Error(`${name} runs only inside the ExternalSoul host. In tests, mock esoul-sdk/react.`);
+};
+/** Dispatch a workspace event from your UI — the ONLY sanctioned path.
+ * Respects read-only viewers (no-op when the viewer cannot edit). */
+export function usePluginEventDispatch() {
+    return hostOnly("usePluginEventDispatch");
+}
+/** Current open chat id, for `chatIdSource` attribution. */
+export function usePluginCurrentChatId() {
+    return hostOnly("usePluginCurrentChatId");
+}
+/** True when the current viewer may mutate this workspace. */
+export function useAppCanEdit() {
+    return hostOnly("useAppCanEdit");
+}
+/**
+ * Invoke tools of OTHER apps in the workspace (append a spreadsheet row, add a
+ * calendar event…). Declare each as "<applicationType>:<tool>" in plugin.json
+ * `workspaceTools` — that list is the grant wall once installed. In the
+ * Forge's live preview the same call rides the board's tab to the owner's
+ * real workspace, so a plugin under construction already talks to its
+ * neighbours. Pass the app's identity from its state.
+ */
+export function useWorkspaceTools(_identity) {
+    return hostOnly("useWorkspaceTools");
+}
+/** The current workspace's file catalogue, live from the store. */
+export function usePluginWorkspaceFiles() {
+    return hostOnly("usePluginWorkspaceFiles");
+}
+/** Upload a browser File into the workspace (blob → row → live list). */
+export function usePluginFileUpload(_workspaceId) {
+    return hostOnly("usePluginFileUpload");
+}
+/** All mounts the signed-in user can see for this workspace. */
+export function useFileSources(_workspaceId) {
+    return hostOnly("useFileSources");
+}
+/** One mount's listing; a failing source reports error/errorKind, never []. */
+export function useFileSourceEntries(_workspaceId, _sourceId, _folderRef) {
+    return hostOnly("useFileSourceEntries");
+}