SDK: host

@pithyx/sdk/host is the desktop’s side of the protocol: it serves one app window over a transport end, checks every call’s parameters and the app’s permissions, and sends events and questions. Apps do not use it; pithyx dev and the desktop do.

Generated from the TSDoc comments of @pithyx/sdk 1.0.0-rc.9 at build time; the text below the headings is the comment in the source.

Interfaces

ServeOptions

What serveApp serves an app window with.

Properties

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.

Parameters

Parameter	Type	Description
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.

Returns

void

---

AppConnection

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

Methods

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.

Type Parameters

Type Parameter
E extends keyof Events

Parameters

Parameter	Type	Description
event	E	The event name.
data	Events[E]	The event’s data.

Returns

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.

Type Parameters

Type Parameter
Q extends keyof Queries

Parameters

Parameter	Type	Description
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.

Returns

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.

Returns

void

Type Aliases

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.

Functions

keepsBrowserMenu()

function keepsBrowserMenu(target): boolean;

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

Parameters

Parameter	Type	Description
target	EventTarget | null	The target of a contextmenu event.

Returns

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.

Parameters

Parameter	Type	Description
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.

Returns

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.

Parameters

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

Returns

AppConnection

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

References

PithyxError

Re-exports PithyxError