@pstdio/sdk 0.19.0 → 0.20.0

package/dist/extensions/define-extension-view.d.ts

@@ -12,6 +12,8 @@ export type GuestHost = {
     call: <TResult = unknown>(method: string, params?: unknown) => Promise<TResult>;
     /** Subscribe to host-pushed events for a capability scope (e.g. "terminal.session"). */
     onEvent: (scope: string, handler: (payload: unknown) => void) => () => void;
+    /** Id of the extension that owns this webview. Missing only on hosts older than the bridge that sends it. */
+    extensionId?: string;
 };
 export type PropsStore<TProps = unknown> = {
     get: () => TProps;

package/dist/extensions/define-extension.d.ts

@@ -17,7 +17,7 @@ type SettingValue<TProperty> = TProperty extends {
 } ? unknown[] : TProperty extends {
     type: "object";
 } ? Record<string, unknown> : unknown;
-type SettingsMap<TSettings> = TSettings extends {
+export type SettingsMap<TSettings> = TSettings extends {
     properties: infer TProperties;
 } ? {
     [K in keyof TProperties & string]: SettingValue<TProperties[K]>;

package/dist/extensions/index.d.ts

@@ -9,4 +9,5 @@ export { defineExtensionView, type ExtensionViewModule, type ExtensionViewRender
 export { params } from "./params";
 export { commandEvent, commandRef, eventRef } from "./refs";
 export { createTerminalSessionBridge, type TerminalSessionAdapter, type TerminalSessionBridge, type TerminalSessionExit, } from "./terminal-session-bridge";
+export { createWebviewClient, type WebviewClient, type WebviewClientOptions, type WebviewCommandsClient, type WebviewSettingsClient, } from "./webview-client";
 export { matchesResourceWhen } from "./when";

package/dist/extensions/index.js

@@ -377,6 +377,35 @@ var createTerminalSessionBridge = (host) => ({
     };
   }
 });
+// src/extensions/webview-client.ts
+var createWebviewClient = (host, options) => {
+  const extensionId = options?.extensionId ?? host.extensionId;
+  if (!extensionId) {
+    throw new Error("The host bridge did not provide an extension id. Pass { extensionId } to createWebviewClient.");
+  }
+  const runCommand = async (commandKey, params2) => {
+    const response = await host.call("commands.execute", {
+      commandId: `${extensionId}.${commandKey}`,
+      params: params2
+    });
+    return unwrapCommandOutcome(response);
+  };
+  const commands = new Proxy({}, {
+    get: (_target, commandKey) => {
+      if (typeof commandKey !== "string")
+        return;
+      return (params2) => runCommand(commandKey, params2);
+    }
+  });
+  const settings = {
+    all: async () => await host.call("extension.settings.all", {}) ?? {},
+    get: (key) => host.call("extension.settings.get", { key }),
+    set: async (key, value) => {
+      await host.call("extension.settings.set", { key, value });
+    }
+  };
+  return { commands, settings };
+};
 // src/extensions/when.ts
 var matchesResourceWhen = (when, resourceType) => {
   const resourceTypes = when?.resourceType;
@@ -416,6 +445,7 @@ export {
   defineExtensionView,
   defineExtension,
   defineCommand,
+  createWebviewClient,
   createTerminalSessionBridge,
   commandRef,
   commandEvent,

package/dist/extensions/react/index.d.ts

@@ -0,0 +1,16 @@
+import { type QueryKey } from "@tanstack/react-query";
+interface CommandQueryInput<TResult> {
+    queryKey: QueryKey;
+    command: () => Promise<TResult>;
+    enabled?: boolean;
+    staleTime?: number;
+}
+/** Reads server state via a typed client command, cached and deduped by react-query. */
+export declare const useCommandQuery: <TResult>(input: CommandQueryInput<TResult>) => import("@tanstack/react-query").UseQueryResult<import("@tanstack/react-query").NoInfer<TResult>, Error>;
+interface CommandMutationInput<TParams, TResult> {
+    command: (params: TParams) => Promise<TResult>;
+    invalidate?: QueryKey[];
+}
+/** Writes server state via a typed client command and refreshes affected queries on success. */
+export declare const useCommandMutation: <TParams, TResult>(input: CommandMutationInput<TParams, TResult>) => import("@tanstack/react-query").UseMutationResult<TResult, Error, TParams, unknown>;
+export {};

package/dist/extensions/react/index.js

@@ -0,0 +1,38 @@
+var __defProp = Object.defineProperty;
+var __returnValue = (v) => v;
+function __exportSetter(name, newValue) {
+  this[name] = __returnValue.bind(null, newValue);
+}
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, {
+      get: all[name],
+      enumerable: true,
+      configurable: true,
+      set: __exportSetter.bind(all, name)
+    });
+};
+
+// src/extensions/react/index.ts
+import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
+var useCommandQuery = (input) => {
+  const { command, enabled, queryKey, staleTime } = input;
+  return useQuery({
+    queryKey,
+    enabled,
+    staleTime,
+    queryFn: () => command()
+  });
+};
+var useCommandMutation = (input) => {
+  const { command, invalidate } = input;
+  const queryClient = useQueryClient();
+  return useMutation({
+    mutationFn: (params) => command(params),
+    onSuccess: () => invalidate?.forEach((queryKey) => void queryClient.invalidateQueries({ queryKey }))
+  });
+};
+export {
+  useCommandQuery,
+  useCommandMutation
+};

package/dist/extensions/webview-client.d.ts

@@ -0,0 +1,41 @@
+import type { CommandDefinition, ParamObjectSchema, ParamsOf } from "pstdio-api-contracts/extension-kernel";
+import type { SettingsMap } from "./define-extension";
+import type { GuestHost } from "./define-extension-view";
+type CommandFn<TDefinition> = TDefinition extends CommandDefinition<infer TSchema, infer TResult, infer _TSettings> ? TSchema extends ParamObjectSchema ? Partial<ParamsOf<TSchema>> extends ParamsOf<TSchema> ? (params?: ParamsOf<TSchema>) => Promise<TResult> : (params: ParamsOf<TSchema>) => Promise<TResult> : () => Promise<TResult> : never;
+export type WebviewCommandsClient<TCommands> = {
+    [K in keyof TCommands & string]: CommandFn<TCommands[K]>;
+};
+export type WebviewSettingsClient<TSettings> = {
+    all: () => Promise<Partial<TSettings>>;
+    get: <K extends keyof TSettings & string>(key: K) => Promise<TSettings[K] | undefined>;
+    set: <K extends keyof TSettings & string>(key: K, value: TSettings[K]) => Promise<void>;
+};
+type ClientSettingsMap<TSettings> = TSettings extends {
+    properties: unknown;
+} ? SettingsMap<TSettings> : Record<never, never>;
+export type WebviewClient<TCommands, TSettings = undefined> = {
+    commands: WebviewCommandsClient<TCommands>;
+    settings: WebviewSettingsClient<ClientSettingsMap<TSettings>>;
+};
+export interface WebviewClientOptions {
+    /** Overrides the extension id provided by the host bridge (e.g. in tests). */
+    extensionId?: string;
+}
+/**
+ * Typed guest-side client over the host bridge. Command params and results come from
+ * the extension's exported commands record (`defineCommand` values); settings come
+ * from its exported settings contribution. Command outcomes are unwrapped, so
+ * failures throw.
+ *
+ * Import both as types only, so no server code enters the webview bundle:
+ *
+ * @example
+ *   import type { commands } from "../commands";
+ *   import type { settings } from "../settings";
+ *
+ *   const client = createWebviewClient<typeof commands, typeof settings>(host);
+ *   const { statuses } = await client.commands["ticketStatus.read"]();
+ *   const enabled = await client.settings.get("counter.enabled");
+ */
+export declare const createWebviewClient: <TCommands extends object, TSettings = undefined>(host: GuestHost, options?: WebviewClientOptions) => WebviewClient<TCommands, TSettings>;
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pstdio/sdk",
-  "version": "0.19.0",
+  "version": "0.20.0",
   "repository": {
     "type": "git",
     "url": "https://github.com/pufflyai/prompt-studio"
@@ -29,6 +29,10 @@
       "types": "./dist/extensions/index.d.ts",
       "import": "./dist/extensions/index.js"
     },
+    "./extensions/react": {
+      "types": "./dist/extensions/react/index.d.ts",
+      "import": "./dist/extensions/react/index.js"
+    },
     "./prompts": {
       "types": "./dist/prompts/index.d.ts",
       "import": "./dist/prompts/index.js"
@@ -40,7 +44,7 @@
   },
   "scripts": {
     "build": "rm -rf ./dist && bun run build:js && bun run build:types",
-    "build:js": "bun build ./src/api/index.ts ./src/client/index.ts ./src/extensions/index.ts ./src/prompts/index.ts ./src/hooks/index.ts ./src/resources/index.ts --outdir ./dist --root ./src --target node --format esm --external mustache",
+    "build:js": "bun build ./src/api/index.ts ./src/client/index.ts ./src/extensions/index.ts ./src/extensions/react/index.ts ./src/prompts/index.ts ./src/hooks/index.ts ./src/resources/index.ts --outdir ./dist --root ./src --target node --format esm --external mustache --external react --external @tanstack/react-query",
     "build:types": "tsc --project ./tsconfig.build.json",
     "prepack": "bun run build",
     "typecheck": "tsc --noEmit",
@@ -52,10 +56,25 @@
   "dependencies": {
     "mustache": "^4.2.0"
   },
+  "peerDependencies": {
+    "@tanstack/react-query": "^5.0.0",
+    "react": "^19.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@tanstack/react-query": {
+      "optional": true
+    },
+    "react": {
+      "optional": true
+    }
+  },
   "devDependencies": {
+    "@tanstack/react-query": "^5.90.21",
     "@types/bun": "1.3.13",
     "@types/mustache": "^4.2.6",
+    "@types/react": "^19.2.0",
     "pstdio-api-contracts": "workspace:*",
+    "react": "^19.0.0",
     "typescript": "6.0.2"
   }
 }