@ps-generator-bridge/sdk 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,210 @@
+import { S as ServerInfo, M as MethodName, P as ProtocolMethods, E as EventName, a as ProtocolEvents, b as PhotoshopEventName, c as PhotoshopEventMap, d as PsJsxRunner, e as PsPhotoshopProxy, f as PluginInfo, g as ProtocolMethod, h as PsLayer, i as PsDocument } from './PsPhotoshopProxy-BjnvziWn.js';
+export { B as Bounds, j as ErrorCode, k as EventEnvelope, I as ImageChangedEvent, l as ImageChangedLayer, L as LayerSpec, m as PROTOCOL_VERSION, n as ProtocolError, o as PsBounds, p as PsRect, R as RequestEnvelope, q as ResponseEnvelope, W as WsImageResult, r as isEvent, s as isRequest, t as isResponse, u as parseFrame, v as serializeFrame } from './PsPhotoshopProxy-BjnvziWn.js';
+
+/**
+ * Transport seam (ADR 0002). The client only knows this interface; the default
+ * implementation uses the global `WebSocket`. Callers on Node 18-21 (which lack a
+ * global WebSocket) or in tests inject their own implementation.
+ */
+interface Transport {
+    /** Resolves once the transport is open and ready to send. */
+    ready(): Promise<void>;
+    send(data: string): void;
+    onMessage(listener: (data: string) => void): void;
+    /** Fired when the underlying connection drops (used by Connection to reconnect). */
+    onClose(listener: () => void): void;
+    close(): void;
+}
+/**
+ * Build a Transport from a WebSocket constructor + url. If none is injected,
+ * falls back to the global `WebSocket`, throwing an actionable error when it is
+ * absent (Node 18-21) rather than a cryptic `WebSocket is not defined`.
+ *
+ * The upgrade path (ADR 0002) — auto-resolving `ws` on Node < 22 — would slot in
+ * at `resolveGlobalWebSocket` without changing this signature.
+ */
+declare function createWebSocketTransport(url: string, WebSocketImpl?: typeof WebSocket): Transport;
+
+interface RawConnectionOptions {
+    /**
+     * ws:// URL to connect to. Use `ws://<host>:<port>/ws` for the public root
+     * endpoint, or `ws://<host>:<port>/ws/{pluginId}` for a plugin-scoped raw
+     * connection that can invoke that plugin's private methods.
+     */
+    url: string;
+    /** Inject a WebSocket implementation for Node 18-21 (e.g. the `ws` package). */
+    WebSocket?: typeof WebSocket;
+    /** Override transport creation (primary test seam); receives the per-attempt URL. */
+    transportFactory?: (url: string) => Transport;
+    /** Per-request timeout in ms (default 10000). */
+    timeoutMs?: number;
+    /** Max reconnect attempts after a drop before failing (default 5). */
+    maxRetries?: number;
+    /** Delay between reconnect attempts in ms (default 5000). */
+    retryDelayMs?: number;
+    /** Optional initial clientId to request via ?id= on first connect. */
+    clientId?: string;
+}
+type EventListener = (data: unknown) => void;
+/**
+ * Stateful SDK entry point (ADR 0005/0007). Owns a Transport factory and:
+ * reconnects on drop (up to maxRetries), remembers and re-sends its clientId,
+ * resolves `ready()` only once the server's `connected` handshake arrives,
+ * correlates `invoke` requests to responses, and dispatches subscribed Events.
+ *
+ * Readiness is a state machine, not a single promise: a transient drop moves it
+ * back to "connecting" so new and queued `invoke`s wait for the next handshake;
+ * exhausting the retry budget moves it to "failed" and rejects everything.
+ */
+declare class RawConnection {
+    private readonly options;
+    private readonly maxRetries;
+    private readonly retryDelayMs;
+    private readonly requests;
+    private readonly listeners;
+    private transport;
+    private clientId;
+    private attempts;
+    private state;
+    private failError;
+    private readyWaiters;
+    private retryTimer;
+    constructor(options: RawConnectionOptions);
+    /** The clientId assigned by the server (undefined until the first handshake). */
+    get id(): string | undefined;
+    /** Resolves once connected (handshake received); rejects if retries are exhausted. */
+    ready(): Promise<void>;
+    /** Fetch the server's identity + (when connected to PS) its Photoshop version. */
+    getServerInfo(): Promise<ServerInfo>;
+    /** Send a Request and await its correlated response. Queues during reconnect. */
+    invoke<M extends MethodName>(method: M, params: ProtocolMethods[M]["params"]): Promise<ProtocolMethods[M]["result"]>;
+    invoke(method: string, params?: unknown): Promise<unknown>;
+    /** Subscribe to a server-pushed Event. */
+    on<E extends EventName>(type: E, listener: (data: ProtocolEvents[E]) => void): void;
+    on(type: string, listener: (data: unknown) => void): void;
+    /** Unsubscribe a previously registered Event listener. */
+    off(type: string, listener: EventListener): void;
+    /** Close the connection: stop reconnecting and reject all in-flight work. */
+    close(): void;
+    private connect;
+    private buildUrl;
+    private handleMessage;
+    private handleDrop;
+    private markReady;
+    private fail;
+    private dispatchEvent;
+}
+
+declare const DEFAULT_CONNECTION_URL = "ws://127.0.0.1:7700/ws";
+interface ConnectionOptions extends Omit<RawConnectionOptions, "url"> {
+    /** Root ws:// URL. Defaults to ws://127.0.0.1:7700/ws. */
+    url?: string;
+}
+type PublicListener<K extends PhotoshopEventName> = (data: PhotoshopEventMap[K]) => void;
+type Invoker = <M extends MethodName>(method: M, params: ProtocolMethods[M]["params"]) => Promise<ProtocolMethods[M]["result"]>;
+declare class PublicEventClient {
+    private readonly invoke;
+    private readonly listeners;
+    private readonly wrappers;
+    private readonly activeSubscriptions;
+    private readonly pendingSubscriptions;
+    constructor(invoke: Invoker);
+    on<K extends PhotoshopEventName>(type: K, listener: PublicListener<K>): void;
+    once<K extends PhotoshopEventName>(type: K, listener: PublicListener<K>): void;
+    off<K extends PhotoshopEventName>(type: K, listener: PublicListener<K>): void;
+    dispatch(type: string, data: unknown): void;
+    replay(): void;
+    private add;
+    private remove;
+    private listenerCount;
+    private subscribe;
+    private unsubscribe;
+}
+declare class PublicJsxRunner implements PsJsxRunner {
+    private readonly invoke;
+    constructor(invoke: Invoker);
+    run<T = unknown>(script: string): Promise<T>;
+    execute<T = unknown>(name: string, params?: Record<string, unknown>): Promise<T>;
+}
+declare class PublicPluginClient {
+    private readonly getServerInfo;
+    constructor(getServerInfo: () => Promise<ServerInfo>);
+    list(): Promise<PluginInfo[]>;
+    has(id: string): Promise<boolean>;
+}
+declare class PublicModules {
+    private readonly invoke;
+    readonly layer: {
+        getLayerInfo: (params?: ProtocolMethods[typeof ProtocolMethod.LayerGetInfo]["params"]) => Promise<PsLayer>;
+        getLayerInfoByID: (layerID: number, options?: {
+            getChildren: boolean;
+        }) => Promise<PsLayer>;
+        getLayerInfoByIndex: (layerIndex: number, options?: {
+            getChildren: boolean;
+        }) => Promise<PsLayer>;
+    };
+    readonly document: {
+        getCurrentDocument: () => Promise<PsDocument>;
+        exportDocument: (params: ProtocolMethods[typeof ProtocolMethod.DocumentExport]["params"]) => Promise<unknown>;
+        saveDocument: (params: ProtocolMethods[typeof ProtocolMethod.DocumentSave]["params"]) => Promise<unknown>;
+    };
+    readonly action: {
+        autoCutout: () => Promise<boolean>;
+        removeBackground: () => Promise<{
+            success: boolean;
+        }>;
+    };
+    constructor(invoke: Invoker);
+}
+/**
+ * Public root /ws facade. It exposes framework-owned surfaces only: Photoshop
+ * events, jsx, Photoshop DOM proxy, plugin discovery, and built-in modules.
+ */
+declare class Connection {
+    private readonly raw;
+    private readonly call;
+    private readonly eventClient;
+    private readonly jsxClient;
+    readonly event: Pick<PublicEventClient, "on" | "once" | "off">;
+    readonly jsx: Pick<PublicJsxRunner, "run" | "execute">;
+    readonly photoshop: PsPhotoshopProxy;
+    readonly plugin: PublicPluginClient;
+    readonly modules: PublicModules;
+    constructor(options?: ConnectionOptions);
+    get id(): string | undefined;
+    ready(): Promise<void>;
+    close(): void;
+    getServerInfo(): Promise<ServerInfo>;
+}
+
+interface PsBridgeClientOptions {
+    /** ws:// URL of the server. Required unless a custom `transport` is given. */
+    url?: string;
+    /** Inject a transport (primary seam; tests pass a FakeTransport). */
+    transport?: Transport;
+    /** Inject a WebSocket implementation for Node 18-21 (e.g. the `ws` package). */
+    WebSocket?: typeof WebSocket;
+    /** Per-request timeout in ms (default 10000). */
+    timeoutMs?: number;
+}
+/**
+ * Typed client over a {@link Transport}. Correlates each request to its response
+ * by id; rejects on protocol errors, timeouts, or close.
+ *
+ * @deprecated Use {@link Connection}, which adds reconnect, a stable clientId, and
+ * Event subscription. Retained until existing callers migrate.
+ */
+declare class PsBridgeClient {
+    private readonly transport;
+    private readonly requests;
+    constructor(options: PsBridgeClientOptions);
+    /** Fetch the server's identity + (when connected to PS) its Photoshop version. */
+    getServerInfo(): Promise<ServerInfo>;
+    /** Send a typed request and await its correlated response. */
+    request<M extends MethodName>(method: M, params: ProtocolMethods[M]["params"]): Promise<ProtocolMethods[M]["result"]>;
+    /** Reject all in-flight requests and close the transport. */
+    close(): void;
+    private handleMessage;
+}
+
+export { Connection, type ConnectionOptions, DEFAULT_CONNECTION_URL, EventName, MethodName, PhotoshopEventMap, PhotoshopEventName, PluginInfo, ProtocolEvents, ProtocolMethod, ProtocolMethod as ProtocolMethodName, ProtocolMethods, PsBridgeClient, type PsBridgeClientOptions, PsDocument, PsLayer, RawConnection, type RawConnectionOptions, ServerInfo, type Transport, createWebSocketTransport };