@archont561/qgis-sdk 0.3.0 → 0.4.0

package/dist/shared/chunk-wtv4vt4q.d.ts

@@ -0,0 +1,280 @@
+import { QgisSdkError2 } from "./chunk-pdj2fxjb.js";
+declare const MAX_SAFE_INTEGER2: number;
+declare const MIN_SAFE_INTEGER2: number;
+declare const PLUGIN_DESCRIPTION_SCHEMA_VERSION2: 1;
+type ValidationDirection2 = "request" | "result";
+interface SerializedValidationIssue2 {
+	readonly path: (string | number)[];
+	readonly code: string;
+}
+interface SerializedContractValidationError2 {
+	readonly code: string;
+	readonly direction: ValidationDirection2;
+	readonly issues: SerializedValidationIssue2[];
+}
+interface ActionDescription2 {
+	readonly id: string;
+	readonly title: string;
+	readonly handler: string;
+	readonly request: Readonly<Record<string, unknown>>;
+	readonly result: Readonly<Record<string, unknown>>;
+}
+/** The event kinds a stream may declare; the frame carries the same three. */
+type StreamEventKind2 = "data" | "progress" | "state";
+/**
+* A declared stream (decision-28): a request in, one payload schema per
+* declared event kind out. There is no `result`: the reply to a subscription is
+* the protocol's acknowledgement, not something an author declares.
+*/
+interface StreamDescription2 {
+	readonly id: string;
+	readonly title: string;
+	readonly handler: string;
+	readonly request: Readonly<Record<string, unknown>>;
+	readonly events: Readonly<Partial<Record<StreamEventKind2, Readonly<Record<string, unknown>>>>>;
+}
+interface PluginDescription2 {
+	readonly schema_version: 1;
+	readonly id: string;
+	readonly title: string;
+	readonly actions: readonly ActionDescription2[];
+	/** Declared streams; a description from a host that predates them is empty. */
+	readonly streams: readonly StreamDescription2[];
+}
+/**
+* Return whether `value` is a finite integer within the JavaScript-safe wire range.
+*/
+declare function isSafeJsonInteger2(value: unknown): value is number;
+/**
+* A declaration cannot be represented or parsed in the versioned contract.
+*/
+declare class QgisSdkDeclarationError2 extends QgisSdkError2 {
+	constructor(message: string);
+}
+/**
+* Safe, structured location and category for a rejected contract value.
+*/
+declare class QgisSdkValidationIssue2 {
+	readonly path: readonly (string | number)[];
+	readonly code: string;
+	constructor(path: readonly (string | number)[], code: string);
+	toJSON(): SerializedValidationIssue2;
+}
+/**
+* A request or result did not satisfy its declared wire contract.
+*/
+declare class QgisSdkContractValidationError2 extends QgisSdkError2 {
+	readonly direction: ValidationDirection2;
+	readonly issues: readonly QgisSdkValidationIssue2[];
+	constructor(direction: ValidationDirection2, issues: readonly QgisSdkValidationIssue2[]);
+	toJSON(): SerializedContractValidationError2;
+}
+/**
+* Parse and validate a version 1 `PluginDescription` emitted by `describe_plugin`.
+*/
+declare function parsePluginDescription2(input: string | Readonly<Record<string, unknown>>): PluginDescription2;
+declare const BRIDGE_PROTOCOL_VERSION2: 1;
+declare const MAX_CALL_ID_LENGTH2: number;
+/** A failure reply, as the host serialized it. */
+interface BridgeFailure2 {
+	readonly code: string;
+	readonly message: string;
+}
+/** A reply to one invocation: exactly one of `value` or `error` is present. */
+type InvokeReply2 = {
+	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: BridgeFailure2;
+};
+/** Why a subscription stopped. */
+type StreamTerminalKind2 = "complete" | "error" | "cancelled" | "gap" | "disposed";
+/** One event on a subscription. */
+interface BridgeStreamEvent2 {
+	readonly kind: StreamEventKind2;
+	readonly payload: unknown;
+}
+/** The end of a subscription, as the host described it. */
+interface BridgeStreamTerminal2 {
+	readonly kind: StreamTerminalKind2;
+	readonly message?: string;
+	readonly dropped?: number;
+}
+/** A frame carrying one event. */
+interface BridgeEventFrame2 {
+	readonly protocol: 1;
+	readonly subscription_id: string;
+	readonly seq: number;
+	readonly event: BridgeStreamEvent2;
+}
+/** The frame that ends a subscription. */
+interface BridgeTerminalFrame2 {
+	readonly protocol: 1;
+	readonly subscription_id: string;
+	readonly seq: number;
+	readonly terminal: BridgeStreamTerminal2;
+}
+/** Anything the host may send for a subscription. */
+type BridgeStreamFrame2 = BridgeEventFrame2 | BridgeTerminalFrame2;
+/** The transport a client speaks through; a QWebChannel adapter or a script. */
+interface WireTransport2 {
+	send(message: unknown): void;
+	subscribe(listener: (message: unknown) => void): () => void;
+}
+/** Options for {@link BridgeClient}. */
+interface BridgeClientOptions2 {
+	readonly timeoutMs?: number;
+}
+/** Options for one invocation. */
+interface InvokeOptions2 {
+	readonly signal?: AbortSignal;
+}
+/**
+* An envelope or reply does not match the versioned bridge protocol.
+*/
+declare class QgisSdkBridgeProtocolError2 extends QgisSdkError2 {
+	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 QgisSdkBridgeTimeoutError2 extends QgisSdkError2 {
+	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 QgisSdkBridgeAbortedError2 extends QgisSdkError2 {
+	readonly callId: string;
+	constructor(callId: string);
+}
+/**
+* The client was closed, so pending calls can no longer be answered.
+*/
+declare class QgisSdkBridgeClosedError2 extends QgisSdkError2 {
+	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 QgisSdkBridgeSequenceError2 extends QgisSdkError2 {
+	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 QgisSdkBridgeStreamEndedError2 extends QgisSdkError2 {
+	readonly subscriptionId: string;
+	readonly terminal: BridgeStreamTerminal2;
+	constructor(subscriptionId: string, terminal: BridgeStreamTerminal2);
+}
+/**
+* The host refused or failed the operation; `failure.code` is the contract.
+*/
+declare class QgisSdkBridgeRemoteError2 extends QgisSdkError2 {
+	readonly failure: BridgeFailure2;
+	readonly callId: string;
+	constructor(callId: string, failure: BridgeFailure2);
+}
+/**
+* Parse one reply, refusing anything the host could not legitimately have sent.
+*/
+declare function parseInvokeReply2(raw: unknown): InvokeReply2;
+/**
+* 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 parseStreamFrame2(raw: unknown): BridgeStreamFrame2;
+/** Callbacks a subscription reports through. */
+interface SubscriptionHandlers2 {
+	readonly onEvent?: (event: BridgeStreamEvent2) => void;
+	readonly onTerminal?: (terminal: BridgeStreamTerminal2) => void;
+}
+/** A live subscription, as the caller holds it. */
+interface BridgeSubscription2 {
+	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 BridgeClient2 {
+	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: WireTransport2, options?: BridgeClientOptions2);
+	/** 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?: InvokeOptions2): 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?: SubscriptionHandlers2, options?: InvokeOptions2): Promise<BridgeSubscription2>;
+	/**
+	* Ask the host for the handshake: the contract this view may use.
+	*
+	* The host bound the view before its first message, so this is a call, not
+	* a binding. The value is what `Dispatcher.handshake` builds - protocol,
+	* generation, the plugin description, the host schema version and the
+	* operations this view is authorized for.
+	*/
+	handshake(options?: InvokeOptions2): Promise<unknown>;
+	/** 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 { MAX_SAFE_INTEGER2, MIN_SAFE_INTEGER2, PLUGIN_DESCRIPTION_SCHEMA_VERSION2, ValidationDirection2, SerializedValidationIssue2, SerializedContractValidationError2, ActionDescription2, StreamEventKind2, StreamDescription2, PluginDescription2, isSafeJsonInteger2, QgisSdkDeclarationError2, QgisSdkValidationIssue2, QgisSdkContractValidationError2, parsePluginDescription2, BRIDGE_PROTOCOL_VERSION2, MAX_CALL_ID_LENGTH2, BridgeFailure2, InvokeReply2, StreamTerminalKind2, BridgeStreamEvent2, BridgeStreamTerminal2, BridgeEventFrame2, BridgeTerminalFrame2, BridgeStreamFrame2, WireTransport2, BridgeClientOptions2, InvokeOptions2, QgisSdkBridgeProtocolError2, QgisSdkBridgeTimeoutError2, QgisSdkBridgeAbortedError2, QgisSdkBridgeClosedError2, QgisSdkBridgeSequenceError2, QgisSdkBridgeStreamEndedError2, QgisSdkBridgeRemoteError2, parseInvokeReply2, parseStreamFrame2, SubscriptionHandlers2, BridgeSubscription2, BridgeClient2 };

package/dist/testing.d.ts

@@ -1,25 +1,7 @@
-/**
-* Base class for expected SDK errors across the bridge boundary.
-*/
-declare class QgisSdkError extends Error {
-	readonly code: string;
-	constructor(message: string, code?: string);
-}
-/** 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";
-/** The end of a subscription, as the host described it. */
-interface BridgeStreamTerminal {
-	readonly kind: StreamTerminalKind;
-	readonly message?: string;
-	readonly dropped?: number;
-}
-/** The transport a client speaks through; a QWebChannel adapter or a script. */
-interface WireTransport {
-	send(message: unknown): void;
-	subscribe(listener: (message: unknown) => void): () => void;
-}
+import { StreamEventKind2, BridgeStreamTerminal2, WireTransport2 } from "./shared/chunk-wtv4vt4q.js";
+import { HostOperationId2 } from "./shared/chunk-khemhx86.js";
+import { OperationShape2, StreamShape2, BridgeSchema2 } from "./shared/chunk-jjx14tgd.js";
+import { QgisSdkError2 } from "./shared/chunk-pdj2fxjb.js";
 /** A scripted host failure, returned from an expectation's handler. */
 interface ScriptedFault {
 	readonly fault: {
@@ -43,7 +25,8 @@ type ScriptedReply<Res> = Res | ScriptedFault | typeof SILENCE | Promise<Res | S
 /** A message the client sent, as the harness recorded it. */
 interface RecordedCall {
 	readonly callId: string;
-	readonly kind: "invoke" | "subscribe" | "unsubscribe";
+	readonly kind: "invoke" | "subscribe" | "unsubscribe" | "handshake";
+	/** Empty for a handshake, which names no operation. */
 	readonly operation: string;
 	readonly payload?: Readonly<Record<string, unknown>>;
 	readonly subscriptionId?: string;
@@ -58,7 +41,7 @@ interface ScriptedStream {
 	/** `false` once the host ended it or the page closed it. */
 	readonly open: boolean;
 	emit(kind: StreamEventKind2, payload: unknown): void;
-	end(terminal: BridgeStreamTerminal): void;
+	end(terminal: BridgeStreamTerminal2): void;
 	/** Advance the sequence without sending, so the next frame is a gap. */
 	skip(frames: number): void;
 }
@@ -67,15 +50,26 @@ interface SubscribeOptions {
 	/** Delay the acknowledgement until this promise settles. */
 	readonly ack?: () => Promise<void>;
 }
+/** Options for {@link createBridgeHarness}. */
+interface HarnessOptions {
+	/**
+	* The host operation ids the scripted handshake advertises; every curated
+	* id by default. A narrowed list is how a test proves a page respects
+	* `qgis.host.granted` (TASK-66 AC #5). A call outside it is still answered
+	* by whatever the test scripted - typically `fault("not_authorized", ...)` -
+	* because that refusal is the host's, not the harness's.
+	*/
+	readonly granted?: readonly HostOperationId2[];
+}
 /**
 * A test's script went wrong: an unmet or unexpected call, a leaked
 * subscription, a handler that threw, or an envelope that is not protocol 1.
 */
-declare class QgisSdkBridgeHarnessError extends QgisSdkError {
+declare class QgisSdkBridgeHarnessError extends QgisSdkError2 {
 	constructor(message: string);
 }
 /** The harness a test holds; also the transport its client is built on. */
-interface BridgeHarness<Op extends string = string> extends WireTransport {
+interface BridgeHarness<Op extends string = string> extends WireTransport2 {
 	/** Every message the client sent, in order. */
 	readonly calls: readonly RecordedCall[];
 	/** Calls no expectation covered; each was answered `unexpected_call`. */
@@ -102,8 +96,36 @@ interface BridgeHarness<Op extends string = string> extends WireTransport {
 	assertSatisfied(): void;
 }
 /**
-* Create a harness; `Op` narrows the operations a test may expect, typically
-* the generated module's `OperationId`.
+* The harness {@link createBridgeHarness} returns for a schema: the same
+* harness, with `expectInvoke` and `expectSubscribe` typed by the schema's
+* `Operations` and `Streams` - a payload is the declared request, a reply the
+* declared result - and by the curated host ids, whose shapes the host module
+* owns.
+*/
+interface SchemaBridgeHarness<
+	O,
+	S
+> extends Omit<BridgeHarness<Extract<keyof O | keyof S, string> | HostOperationId2>, "expectInvoke" | "expectSubscribe"> {
+	expectInvoke<K extends Extract<keyof O, string>>(operation: K, handler: (payload: O[K] extends OperationShape2 ? O[K]["request"] : never) => ScriptedReply<O[K] extends OperationShape2 ? O[K]["result"] : never>): void;
+	expectInvoke<
+		Req extends object = Readonly<Record<string, unknown>>,
+		Res = unknown
+	>(operation: HostOperationId2, handler: (payload: Req) => ScriptedReply<Res>): void;
+	expectSubscribe<K extends Extract<keyof S, string>>(operation: K, script: SubscribeScript<S[K] extends StreamShape2 ? S[K]["request"] : never>, options?: SubscribeOptions): void;
+	expectSubscribe<Req extends object = Readonly<Record<string, unknown>>>(operation: HostOperationId2, script: SubscribeScript<Req>, options?: SubscribeOptions): void;
+}
+/**
+* Create a harness.
+*
+* Given the generated `bridge.schema.ts` default export, the harness is typed
+* by it: `expectInvoke("sites.summary", (payload) => ...)` sees the declared
+* request and must answer with the declared result, and the handshake it
+* answers advertises the schema's operations. Without one, `Op` narrows the
+* operations a test may expect, typically a generated `OperationId`.
 */
-declare function createBridgeHarness<Op extends string = string>(): BridgeHarness<Op>;
-export { BridgeHarness, QgisSdkBridgeHarnessError, RecordedCall, SILENCE, ScriptedFault, ScriptedRefusal, ScriptedReply, ScriptedStream, SubscribeOptions, SubscribeScript, createBridgeHarness, fault };
+declare function createBridgeHarness<Op extends string = string>(options?: HarnessOptions): BridgeHarness<Op>;
+declare function createBridgeHarness<
+	O,
+	S
+>(schema: BridgeSchema2<O, S>, options?: HarnessOptions): SchemaBridgeHarness<O, S>;
+export { BridgeHarness, HarnessOptions, QgisSdkBridgeHarnessError, RecordedCall, SILENCE, SchemaBridgeHarness, ScriptedFault, ScriptedRefusal, ScriptedReply, ScriptedStream, SubscribeOptions, SubscribeScript, createBridgeHarness, fault };