@archont561/qgis-sdk 0.0.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

@@ -0,0 +1,131 @@
+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: {
+		readonly code: string;
+		readonly message: string;
+	};
+}
+/** Script a failure reply with this code and message. */
+declare function fault(code: string, message: string): ScriptedFault;
+/** Return this from a handler to never answer, so the client's timeout speaks. */
+declare const SILENCE: unique symbol;
+/** A subscription the script turns down: a fault reply, or no reply at all. */
+type ScriptedRefusal = ScriptedFault | typeof SILENCE;
+/**
+* A subscribe expectation's script: emit on `stream` now or later, or return
+* a refusal instead of acknowledging.
+*/
+type SubscribeScript<Req extends object> = (payload: Req, stream: ScriptedStream) => ScriptedRefusal | void;
+/** What an invoke expectation may answer with. */
+type ScriptedReply<Res> = Res | ScriptedFault | typeof SILENCE | Promise<Res | ScriptedFault | typeof SILENCE>;
+/** A message the client sent, as the harness recorded it. */
+interface RecordedCall {
+	readonly callId: string;
+	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;
+}
+/**
+* One scripted subscription. Frames carry the sequence the kernel checks, so
+* `skip` is the one way to script a gap.
+*/
+interface ScriptedStream {
+	readonly id: string;
+	readonly operation: string;
+	/** `false` once the host ended it or the page closed it. */
+	readonly open: boolean;
+	emit(kind: StreamEventKind2, payload: unknown): void;
+	end(terminal: BridgeStreamTerminal2): void;
+	/** Advance the sequence without sending, so the next frame is a gap. */
+	skip(frames: number): void;
+}
+/** Options for a subscribe expectation. */
+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 QgisSdkError2 {
+	constructor(message: string);
+}
+/** The harness a test holds; also the transport its client is built on. */
+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`. */
+	readonly unexpected: readonly RecordedCall[];
+	/** Subscriptions neither ended by a script nor closed by the page. */
+	readonly openSubscriptions: readonly string[];
+	/** Clients currently attached. */
+	readonly listeners: number;
+	/** Answer the next `operation` call with what `handler` returns. */
+	expectInvoke<
+		Req extends object = Readonly<Record<string, unknown>>,
+		Res = unknown
+	>(operation: Op, handler: (payload: Req) => ScriptedReply<Res>): void;
+	/**
+	* Acknowledge the next `operation` subscription and hand `script` the
+	* stream; return a fault or {@link SILENCE} from it to refuse instead.
+	*/
+	expectSubscribe<Req extends object = Readonly<Record<string, unknown>>>(operation: Op, script: SubscribeScript<Req>, options?: SubscribeOptions): void;
+	/** Push any raw message, for what no expectation can script. */
+	deliver(raw: unknown): void;
+	/** Resolve once everything queued so far has been delivered. */
+	settled(): Promise<void>;
+	/** Throw unless every expectation was met and nothing leaked. */
+	assertSatisfied(): void;
+}
+/**
+* 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>(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 };