SDK: Host

@pithyx/sdk/host ist die Seite des Desktops im Protokoll: Es bedient ein App-Fenster über ein Transportende, prüft die Parameter jedes Aufrufs und die Berechtigungen der App und sendet Ereignisse und Fragen. Apps nutzen es nicht; pithyx dev und der Desktop schon.

Beim Build aus den TSDoc-Kommentaren von @pithyx/sdk 1.0.0-rc.9 erzeugt; der Text unter den Überschriften ist der Kommentar im Quelltext und bleibt Englisch.

Schnittstellen

ServeOptions

What serveApp serves an app window with.

Eigenschaften

context

context: Omit<AppContext, 'capabilities'>;

The init context; capabilities is filled in from the handlers.

methods

methods: MethodHandlers;

The handlers of the protocol methods this host serves.

extensions?

optional extensions?: HostExtensions;

Host-only methods for the host’s own apps; see HostExtensions.

onReady?

optional onReady?: (hello) => void;

Called when the app completed the handshake.

Parameter

Parameter	Typ	Beschreibung
hello	{ protocol: number; sdk: string; }	-
hello.protocol	number	The protocol version the app speaks.
hello.sdk	string	The SDK version the app was built with.

Rückgabewert

void

---

AppConnection

The host’s side of one app window’s connection.

Methoden

emit()

emit<E>(event, data): void;

Sends an event; an event that needs a permission the app does not hold (sharesChanged) is dropped. permissionsChange also updates the permissions the host checks.

Typenparameter

Typenparameter
E extends keyof Events

Parameter

Parameter	Typ	Beschreibung
event	E	The event name.
data	Events[E]	The event’s data.

Rückgabewert

void

ask()

ask<Q>(
   query,
   data,
   timeout
): Promise<Queries[Q]["answer"] | undefined>;

Asks the app and waits; resolves undefined when it does not answer in time.

Typenparameter

Typenparameter
Q extends keyof Queries

Parameter

Parameter	Typ	Beschreibung
query	Q	The question.
data	Queries[Q]["data"]	What the question carries.
timeout	number	How long to wait in milliseconds, for example BEFORE_CLOSE_TIMEOUT.

Rückgabewert

Promise<Queries[Q]["answer"] | undefined>

The app’s answer, or undefined after the timeout or when the connection closed.

close()

close(): void;

Ends the connection; questions still waiting resolve undefined.

Rückgabewert

void

Typenaliasse

MethodHandlers

type MethodHandlers = {
  [M in MethodName]?: (
    params: Methods[M]['params'],
  ) => Methods[M]['result'] | Promise<Methods[M]['result']>;
};

The host’s handler per protocol method; a method without a handler is not in capabilities. A handler gets the checked parameters and returns the result or throws a PithyxError, which goes back to the app as a problem.

---

HostExtensions

type HostExtensions = Record<
  string,
  {
    validate: boolean;
    handle: unknown;
  }
>;

Methods outside the public protocol that a host serves to its own apps, each with its own parameter check. They are not versioned, not listed in capabilities, and a host never gives them to a third-party app.

Funktionen

keepsBrowserMenu()

function keepsBrowserMenu(target): boolean;

Text fields keep the browser’s menu, so paste and spelling suggestions still work there.

Parameter

Parameter	Typ	Beschreibung
target	EventTarget | null	The target of a contextmenu event.

Rückgabewert

boolean

Whether the target is inside an input, a text area, a select or an editable element.

---

sdkError()

function sdkError(code, params?, detail?): PithyxError;

A PithyxError with one of the SDK’s own transport codes.

Parameter

Parameter	Typ	Beschreibung
code	| "sdk.method.unknown" | "sdk.request.invalid" | "sdk.request.timeout" | "sdk.transport.closed" | "sdk.protocol.unsupported" | "sdk.transfer.cancelled" | "sdk.backend.endpoint_unknown" | "sdk.backend.unreachable"	One of sdkErrorCodes.
params	Record<string, unknown>	Values for the translated message.
detail?	string	English fallback text.

Rückgabewert

PithyxError

The error, to throw or to reject with.

---

serveApp()

function serveApp(endpoint, options): AppConnection;

Serves one app window over a transport end. Answers hello with init (or refuse with sdk.protocol.unsupported), then checks each request’s parameters (sdk.request.invalid), the permissions the host itself checks (app.permission.denied) and whether a handler exists (sdk.method.unknown) before the handler runs.

Parameter

Parameter	Typ	Beschreibung
endpoint	Endpoint	The host’s end of the transport.
options	ServeOptions	The context, the handlers and the host-only extensions.

Rückgabewert

AppConnection

The connection, to send events and questions and to close it.

Referenzen

PithyxError

Re-Exports PithyxError