@archont561/qgis-sdk-bridge 0.1.1 → 0.2.0

package/README.md

@@ -1,42 +1,54 @@
 # @archont561/qgis-sdk-bridge
 
-**TypeScript contract, wire-limit, and error primitives for QGIS `QWebEngineView` plugin interfaces.**
+**TypeScript client for QGIS plugin interfaces hosted in `QWebEngineView`.**
 
-`@archont561/qgis-sdk-bridge` is the TypeScript companion package to [`qgis-sdk`](https://pypi.org/project/qgis-sdk/) in the [QGIS SDK workspace](https://github.com/Archont561/qgis-sdk).
+The companion to [`qgis-sdk`](https://pypi.org/project/qgis-sdk/): a correlated
+transport client with subscriptions, the curated host namespaces, and the
+contract a generated per-plugin client is built on. Every exported error begins
+with `QgisSdk` and carries a stable wire `code`.
 
-> **Status (`0.1.0` experimental):** Exposes the version 1 plugin/action declaration parser (`parsePluginDescription`, `PluginDescription`, `ActionDescription`), JavaScript-safe integer wire bounds (`MAX_SAFE_INTEGER`, `MIN_SAFE_INTEGER`, `isSafeJsonInteger`), and the `QgisSdk*`-prefixed error hierarchy (`QgisSdkError`, `QgisSdkScopeClosedError`, `QgisSdkUnsupportedCapabilityError`, `QgisSdkDeclarationError`, `QgisSdkContractValidationError`, `QgisSdkValidationIssue`). `QWebChannel` transport bindings, generated operation clients, and React hooks are scheduled for subsequent `0.x` milestones.
+> Experimental. `0.1.1` on npm carries the description parser, the safe-integer
+> wire bounds and the error hierarchy; `0.2.0`, which ships with the Python
+> `0.3.0` milestone, adds `./bridge`, `./host`, the generated clients shown
+> below, the optional `./react` bindings and the `./testing` harness.
 
 ## Installation
 
-Install from [npm](https://www.npmjs.com/package/@archont561/qgis-sdk-bridge) or [GitHub Packages](https://github.com/Archont561/qgis-sdk/pkgs/npm/qgis-sdk-bridge):
-
 ```sh
 bun add @archont561/qgis-sdk-bridge
-# or with npm:
 npm install @archont561/qgis-sdk-bridge
 ```
 
-## Exports
+## Example
 
 ```ts
-import {
-	MAX_SAFE_INTEGER,
-	MIN_SAFE_INTEGER,
-	PLUGIN_DESCRIPTION_SCHEMA_VERSION,
-	QgisSdkContractValidationError,
-	QgisSdkDeclarationError,
-	QgisSdkError,
-	QgisSdkScopeClosedError,
-	QgisSdkUnsupportedCapabilityError,
-	QgisSdkValidationIssue,
-	isSafeJsonInteger,
-	parsePluginDescription,
-} from "@archont561/qgis-sdk-bridge";
+import { BridgeClient } from "@archont561/qgis-sdk-bridge/bridge";
+import { createHost } from "@archont561/qgis-sdk-bridge/host";
+
+const client = new BridgeClient({
+	send: (message) => channel.send(JSON.stringify(message)),
+	subscribe: (listener) => {
+		channel.onmessage = (text: string) => listener(JSON.parse(text));
+		return () => {
+			channel.onmessage = null;
+		};
+	},
+});
+
+const host = createHost(client);
+const page = await host.layers.list({ limit: 20 });
 ```
 
-- **Safe integer bounds:** `MAX_SAFE_INTEGER` (`9007199254740991`), `MIN_SAFE_INTEGER` (`-9007199254740991`), and `isSafeJsonInteger(value)` mirror `qgis_sdk.models.MAX_SAFE_INTEGER` and `SafeJsonInteger`.
-- **Version 1 plugin descriptions:** `parsePluginDescription(raw)` validates and freezes `PluginDescription` payloads (`schema_version: 1`) produced by Python's `describe_plugin(cls).to_json()`.
-- **Structured SDK errors:** Every SDK exception class begins with `QgisSdk` and carries a stable wire `code` property (`"sdk_error"`, `"scope_closed"`, `"unsupported_capability"`, `"invalid_declaration"`, `"contract_validation_failed"`).
+A plugin's own operations come from the client `qgis-sdk bridge generate`
+renders from its Python declarations.
+
+## Documentation
+
+- [TypeScript bridge guide](https://github.com/Archont561/qgis-sdk/blob/main/backlog/docs/guides/doc-13%20-%20qgis-sdk-bridge-TypeScript-package-guide.md) -
+  exports, the transport client, host namespaces, generated clients, streams,
+  the React bindings and testing against a scripted host.
+- [Python package guide](https://github.com/Archont561/qgis-sdk/blob/main/backlog/docs/guides/doc-12%20-%20qgis-sdk-Python-package-guide.md) -
+  the host half of every surface above.
 
 ## License
 

package/dist/bridge.d.ts

@@ -0,0 +1,205 @@
+/**
+* Base class for expected SDK errors across the bridge boundary.
+*/
+declare class QgisSdkError extends Error {
+	readonly code: string;
+	constructor(message: string, code?: string);
+}
+declare const BRIDGE_PROTOCOL_VERSION: 1;
+declare const MAX_CALL_ID_LENGTH: number;
+/** A failure reply, as the host serialized it. */
+interface BridgeFailure {
+	readonly code: string;
+	readonly message: string;
+}
+/** A reply to one invocation: exactly one of `value` or `error` is present. */
+type InvokeReply = {
+	readonly protocol: 1;
+	readonly call_id: string;
+	readonly ok: true;
+	readonly value: unknown;
+} | {
+	readonly protocol: 1;
+	readonly call_id: string;
+	readonly ok: false;
+	readonly error: BridgeFailure;
+};
+/** The kinds of event a stream may carry; only `progress` may be coalesced. */
+type StreamEventKind2 = "data" | "progress" | "state";
+/** Why a subscription stopped. */
+type StreamTerminalKind = "complete" | "error" | "cancelled" | "gap" | "disposed";
+/** One event on a subscription. */
+interface BridgeStreamEvent {
+	readonly kind: StreamEventKind2;
+	readonly payload: unknown;
+}
+/** The end of a subscription, as the host described it. */
+interface BridgeStreamTerminal {
+	readonly kind: StreamTerminalKind;
+	readonly message?: string;
+	readonly dropped?: number;
+}
+/** A frame carrying one event. */
+interface BridgeEventFrame {
+	readonly protocol: 1;
+	readonly subscription_id: string;
+	readonly seq: number;
+	readonly event: BridgeStreamEvent;
+}
+/** The frame that ends a subscription. */
+interface BridgeTerminalFrame {
+	readonly protocol: 1;
+	readonly subscription_id: string;
+	readonly seq: number;
+	readonly terminal: BridgeStreamTerminal;
+}
+/** Anything the host may send for a subscription. */
+type BridgeStreamFrame = BridgeEventFrame | BridgeTerminalFrame;
+/** The transport a client speaks through; a QWebChannel adapter or a script. */
+interface WireTransport {
+	send(message: unknown): void;
+	subscribe(listener: (message: unknown) => void): () => void;
+}
+/** Options for {@link BridgeClient}. */
+interface BridgeClientOptions {
+	readonly timeoutMs?: number;
+}
+/** Options for one invocation. */
+interface InvokeOptions {
+	readonly signal?: AbortSignal;
+}
+/**
+* An envelope or reply does not match the versioned bridge protocol.
+*/
+declare class QgisSdkBridgeProtocolError extends QgisSdkError {
+	constructor(message: string);
+}
+/**
+* The host did not answer in time. The call may still have run, so this is an
+* unknown outcome: retrying automatically is forbidden, deciding is the caller's.
+*/
+declare class QgisSdkBridgeTimeoutError extends QgisSdkError {
+	readonly callId: string;
+	constructor(callId: string, timeoutMs: number);
+}
+/**
+* The caller aborted locally. Distinct from the host cancelling the operation,
+* which arrives as a failure reply carrying the `cancelled` code.
+*/
+declare class QgisSdkBridgeAbortedError extends QgisSdkError {
+	readonly callId: string;
+	constructor(callId: string);
+}
+/**
+* The client was closed, so pending calls can no longer be answered.
+*/
+declare class QgisSdkBridgeClosedError extends QgisSdkError {
+	constructor();
+}
+/**
+* A subscription's frames were not the sequence the host promised.
+*
+* The client does not try to reassemble: a missed frame is a fact about the
+* subscription, not something to paper over.
+*/
+declare class QgisSdkBridgeSequenceError extends QgisSdkError {
+	readonly subscriptionId: string;
+	readonly expected: number;
+	readonly received: number;
+	constructor(subscriptionId: string, expected: number, received: number);
+}
+/**
+* The subscription ended with a terminal frame the caller may want to inspect.
+*/
+declare class QgisSdkBridgeStreamEndedError extends QgisSdkError {
+	readonly subscriptionId: string;
+	readonly terminal: BridgeStreamTerminal;
+	constructor(subscriptionId: string, terminal: BridgeStreamTerminal);
+}
+/**
+* The host refused or failed the operation; `failure.code` is the contract.
+*/
+declare class QgisSdkBridgeRemoteError extends QgisSdkError {
+	readonly failure: BridgeFailure;
+	readonly callId: string;
+	constructor(callId: string, failure: BridgeFailure);
+}
+/**
+* Parse one reply, refusing anything the host could not legitimately have sent.
+*/
+declare function parseInvokeReply(raw: unknown): InvokeReply;
+/**
+* Parse one stream frame, refusing anything the host could not legitimately
+* have sent.
+*
+* Exactly one of `event` and `terminal` has to be present: a frame that carries
+* both leaves the client guessing which one wins, and a client that guesses is
+* a client that will eventually deliver an event after the end of a stream.
+*/
+declare function parseStreamFrame(raw: unknown): BridgeStreamFrame;
+/** Callbacks a subscription reports through. */
+interface SubscriptionHandlers {
+	readonly onEvent?: (event: BridgeStreamEvent) => void;
+	readonly onTerminal?: (terminal: BridgeStreamTerminal) => void;
+}
+/** A live subscription, as the caller holds it. */
+interface BridgeSubscription {
+	readonly id: string;
+	readonly closed: boolean;
+	close(): void;
+}
+/**
+* Correlate invocations with replies over an injected transport.
+*
+* The client never retries: a timeout, an abort and a closed client are three
+* different answers, and each is reported as itself.
+*/
+declare class BridgeClient {
+	private readonly transport;
+	private readonly timeoutMs;
+	private readonly pending;
+	private readonly subscriptions;
+	private readonly disposals;
+	private readonly unsubscribe;
+	private counter;
+	private closed;
+	private unmatched;
+	private breaks;
+	private lastProtocolError;
+	constructor(transport: WireTransport, options?: BridgeClientOptions);
+	/** Whether {@link close} has run; a closed client answers nothing. */
+	get isClosed(): boolean;
+	/** Replies that named no pending call: a late duplicate, or a stray message. */
+	get unmatchedReplies(): number;
+	/** Number of calls still waiting for a reply. */
+	get pendingCalls(): number;
+	/**
+	* Invoke one operation and settle with its value or with a typed failure.
+	*/
+	invoke(operation: string, payload?: Readonly<Record<string, unknown>>, options?: InvokeOptions): Promise<unknown>;
+	/**
+	* Open a subscription and resolve once the host has acknowledged it.
+	*
+	* Frames are matched to the subscription by id and by sequence; a frame that
+	* does not continue the sequence ends the subscription instead of being
+	* delivered out of order.
+	*/
+	subscribe(operation: string, payload?: Readonly<Record<string, unknown>>, handlers?: SubscriptionHandlers, options?: InvokeOptions): Promise<BridgeSubscription>;
+	/** Subscriptions still open; a leak check for callers and tests. */
+	get activeSubscriptions(): readonly string[];
+	/** Frames that did not continue their subscription's sequence. */
+	get sequenceBreaks(): number;
+	private send;
+	/**
+	* Refuse further calls, reject what is still pending, and stop listening.
+	*/
+	close(): void;
+	private settle;
+	private handle;
+	private handleFrame;
+	private endSubscription;
+	private disposeSubscription;
+	/** The last malformed message this client refused, if any. */
+	get protocolError(): Error | null;
+}
+export { BRIDGE_PROTOCOL_VERSION, BridgeClient, BridgeClientOptions, BridgeEventFrame, BridgeFailure, BridgeStreamEvent, BridgeStreamFrame, BridgeStreamTerminal, BridgeSubscription, BridgeTerminalFrame, InvokeOptions, InvokeReply, MAX_CALL_ID_LENGTH, QgisSdkBridgeAbortedError, QgisSdkBridgeClosedError, QgisSdkBridgeProtocolError, QgisSdkBridgeRemoteError, QgisSdkBridgeSequenceError, QgisSdkBridgeStreamEndedError, QgisSdkBridgeTimeoutError, StreamEventKind2 as StreamEventKind, StreamTerminalKind, SubscriptionHandlers, WireTransport, parseInvokeReply, parseStreamFrame };

package/dist/bridge.js

@@ -0,0 +1,32 @@
+import {
+  BRIDGE_PROTOCOL_VERSION2,
+  MAX_CALL_ID_LENGTH2,
+  QgisSdkBridgeProtocolError2,
+  QgisSdkBridgeTimeoutError2,
+  QgisSdkBridgeAbortedError2,
+  QgisSdkBridgeClosedError2,
+  QgisSdkBridgeSequenceError2,
+  QgisSdkBridgeStreamEndedError2,
+  QgisSdkBridgeRemoteError2,
+  parseInvokeReply2,
+  parseStreamFrame2,
+  BridgeClient2
+} from "./shared/chunk-a7bjgeve.js";
+import"./shared/chunk-0fknax6w.js";
+export {
+  BRIDGE_PROTOCOL_VERSION2 as BRIDGE_PROTOCOL_VERSION,
+  BridgeClient2 as BridgeClient,
+  MAX_CALL_ID_LENGTH2 as MAX_CALL_ID_LENGTH,
+  QgisSdkBridgeAbortedError2 as QgisSdkBridgeAbortedError,
+  QgisSdkBridgeClosedError2 as QgisSdkBridgeClosedError,
+  QgisSdkBridgeProtocolError2 as QgisSdkBridgeProtocolError,
+  QgisSdkBridgeRemoteError2 as QgisSdkBridgeRemoteError,
+  QgisSdkBridgeSequenceError2 as QgisSdkBridgeSequenceError,
+  QgisSdkBridgeStreamEndedError2 as QgisSdkBridgeStreamEndedError,
+  QgisSdkBridgeTimeoutError2 as QgisSdkBridgeTimeoutError,
+  parseInvokeReply2 as parseInvokeReply,
+  parseStreamFrame2 as parseStreamFrame
+};
+
+//# debugId=AD799C3C82BFFC4664756E2164756E21
+//# sourceMappingURL=data:application/json;base64,ewogICJ2ZXJzaW9uIjogMywKICAic291cmNlcyI6IFtdLAogICJzb3VyY2VzQ29udGVudCI6IFsKICBdLAogICJtYXBwaW5ncyI6ICIiLAogICJkZWJ1Z0lkIjogIkFENzk5QzNDODJCRkZDNDY2NDc1NkUyMTY0NzU2RTIxIiwKICAibmFtZXMiOiBbXQp9

package/dist/host.d.ts

@@ -0,0 +1,157 @@
+declare const HOST_ID = "qgis.host";
+declare const HOST_FINGERPRINT = "sha256:f96bdf1046434de3c5eae01efb34c8ad2bcd1cf241a3dc42f6c4b613dc7d7d6f";
+declare const HOST_SCHEMA_VERSION = 1;
+/** Every declared operation id, so a name can be checked, not guessed. */
+declare const HOST_OPERATIONS: readonly ["files.export", "layers.get", "layers.list", "layers.open_vector", "network.fetch", "notifications.info", "project.layer_ids", "settings.get", "styles.apply"];
+type HostOperationId = (typeof HOST_OPERATIONS)[number];
+interface HostInvokeOptions {
+	readonly signal?: AbortSignal;
+}
+/** The client this module wraps: anything with a correlated invoke. */
+interface HostClientLike {
+	invoke(operation: string, payload?: Readonly<Record<string, unknown>>, options?: HostInvokeOptions): Promise<unknown>;
+	subscribe(operation: string, payload?: Readonly<Record<string, unknown>>, handlers?: HostStreamHandlers<{
+		readonly kind: "data" | "progress" | "state";
+		readonly payload: unknown;
+	}>, options?: HostInvokeOptions): Promise<HostStreamHandle>;
+}
+/** How a stream ended; `dropped` is only present for a gap. */
+interface HostStreamTerminal {
+	readonly kind: "complete" | "error" | "cancelled" | "gap" | "disposed";
+	readonly message?: string;
+	readonly dropped?: number;
+}
+/** What a stream reports: typed events, then exactly one end. */
+interface HostStreamHandlers<E> {
+	readonly onEvent?: (event: E) => void;
+	readonly onTerminal?: (terminal: HostStreamTerminal) => void;
+}
+/** A live stream, as the caller holds it. */
+interface HostStreamHandle {
+	readonly id: string;
+	readonly closed: boolean;
+	close(): void;
+}
+/** An argument or a response that does not match its declared schema. */
+declare class HostContractError extends Error {
+	readonly operation: string;
+	constructor(operation: string, message: string);
+}
+interface ExportRequest {
+	readonly content: string;
+	readonly file: FileRef;
+}
+interface ExportResult {
+	readonly bytes_written: number;
+	readonly name: string;
+}
+interface FetchRequest {
+	readonly auth_config?: string;
+	readonly body?: string;
+	readonly headers?: readonly HttpHeader[];
+	readonly method?: "GET" | "HEAD" | "POST" | "PUT" | "PATCH" | "DELETE" | "OPTIONS";
+	readonly timeout_seconds?: number;
+	readonly url: string;
+}
+interface FileRef {
+	readonly id: string;
+	readonly kind: "file";
+	readonly name?: string;
+	readonly operations?: readonly ("read" | "write")[];
+}
+interface HttpHeader {
+	readonly name: string;
+	readonly value: string;
+}
+interface IdPage {
+	readonly items: readonly string[];
+	readonly next_cursor?: string;
+	readonly truncated: boolean;
+}
+interface LayerPage {
+	readonly items: readonly VectorLayerInfo[];
+	readonly next_cursor?: string;
+	readonly truncated: boolean;
+}
+interface LayerRequest {
+	readonly layer_id: string;
+}
+interface NetworkFetchData {
+	readonly base64: string | null;
+	readonly headers: readonly HttpHeader[];
+	readonly reason: string;
+	readonly status_code: number;
+	readonly text: string | null;
+	readonly url: string;
+}
+interface NotificationsInfoRequest {
+	readonly message: string;
+}
+interface OpenVectorRequest {
+	readonly file: FileRef;
+}
+interface PageRequest {
+	readonly cursor?: string;
+	readonly limit?: number;
+}
+interface SettingsGetRequest {
+	readonly default?: string | null;
+	readonly key: string;
+}
+interface StylesApplyRequest {
+	readonly layer_id: string;
+	readonly style: string;
+}
+interface VectorLayerInfo {
+	readonly crs: string | null;
+	readonly field_names: readonly string[];
+	readonly geometry_type: "point" | "line" | "polygon" | "none";
+	readonly id: string;
+	readonly name: string;
+}
+declare function ExportRequest(value: unknown, strict?: boolean): value is ExportRequest;
+declare function ExportResult(value: unknown, strict?: boolean): value is ExportResult;
+declare function FetchRequest(value: unknown, strict?: boolean): value is FetchRequest;
+declare function IdPage(value: unknown, strict?: boolean): value is IdPage;
+declare function LayerPage(value: unknown, strict?: boolean): value is LayerPage;
+declare function LayerRequest(value: unknown, strict?: boolean): value is LayerRequest;
+declare function NetworkFetchData(value: unknown, strict?: boolean): value is NetworkFetchData;
+declare function NotificationsInfoRequest(value: unknown, strict?: boolean): value is NotificationsInfoRequest;
+declare function OpenVectorRequest(value: unknown, strict?: boolean): value is OpenVectorRequest;
+declare function PageRequest(value: unknown, strict?: boolean): value is PageRequest;
+declare function SettingsGetRequest(value: unknown, strict?: boolean): value is SettingsGetRequest;
+declare function StylesApplyRequest(value: unknown, strict?: boolean): value is StylesApplyRequest;
+/** One event of `network.fetch`, narrowed by its kind. */
+type NetworkFetchEvent = {
+	readonly kind: "data";
+	readonly payload: NetworkFetchData;
+};
+declare function NetworkFetchEvent(value: unknown, strict?: boolean): value is NetworkFetchEvent;
+/** Every operation this surface declares, as callable methods. */
+interface HostOperations {
+	readonly files: {
+		readonly export: (input: ExportRequest, options?: HostInvokeOptions) => Promise<ExportResult>;
+	};
+	readonly layers: {
+		readonly get: (input: LayerRequest, options?: HostInvokeOptions) => Promise<VectorLayerInfo>;
+		readonly list: (input?: PageRequest, options?: HostInvokeOptions) => Promise<LayerPage>;
+		readonly open_vector: (input: OpenVectorRequest, options?: HostInvokeOptions) => Promise<VectorLayerInfo>;
+	};
+	readonly network: {
+		readonly fetch: (input: FetchRequest, handlers: HostStreamHandlers<NetworkFetchEvent>, options?: HostInvokeOptions) => Promise<HostStreamHandle>;
+	};
+	readonly notifications: {
+		readonly info: (input: NotificationsInfoRequest, options?: HostInvokeOptions) => Promise<null>;
+	};
+	readonly project: {
+		readonly layer_ids: (input?: PageRequest, options?: HostInvokeOptions) => Promise<IdPage>;
+	};
+	readonly settings: {
+		readonly get: (input: SettingsGetRequest, options?: HostInvokeOptions) => Promise<string | null>;
+	};
+	readonly styles: {
+		readonly apply: (input: StylesApplyRequest, options?: HostInvokeOptions) => Promise<null>;
+	};
+}
+declare function createHost(client: HostClientLike): HostOperations;
+export { ExportRequest, ExportResult, FetchRequest, FileRef, HOST_FINGERPRINT, HOST_ID, HOST_OPERATIONS, HOST_SCHEMA_VERSION, HostClientLike, HostContractError, HostInvokeOptions, HostOperationId, HostOperations, HostStreamHandle, HostStreamHandlers, HostStreamTerminal, HttpHeader, IdPage, LayerPage, LayerRequest, NetworkFetchData, NetworkFetchEvent, NotificationsInfoRequest, OpenVectorRequest, PageRequest, SettingsGetRequest, StylesApplyRequest, VectorLayerInfo, createHost };