@parity/product-sdk-terminal

Exports

Classes

Functions

Interfaces

Type Aliases

Variables

Classes

class AllowanceError

Extends: Error

Constructors

constructor

new AllowanceError(reason: AllowanceErrorReason, message?: string): AllowanceError

Properties

reason

Functions

createNodeStorageAdapter()

Create a file-based StorageAdapter for use with the host-papp SDK in Node.js.

Data is stored as individual JSON files in the given directory (defaults to ~/.polkadot-apps/).

createNodeStorageAdapter(appId: string, storageDir?: string): StorageAdapter

createSessionSigner()

Create a PolkadotSigner backed by a QR-paired mobile wallet session, using the session’s default account (derivationIndex: 0).

For non-default sub-accounts, use createSessionSignerForAccount.

createSessionSigner(session: UserSession, adapter: TerminalAdapter, publicKey?: Uint8Array<ArrayBufferLike>): PolkadotSigner

Parameters

• session: The paired user session.
• adapter: The TerminalAdapter that loaded the session. Its appId is used as the productId in the wire request.
• publicKey: The product account’s sr25519 public key for [adapter.appId, 0], as derived by the host. See ProductAccountRef.publicKey; omit only when the product account is the session’s selected account.

createSessionSignerForAccount()

Create a PolkadotSigner for a specific sub-account of a paired session.

Use this when you need a derivation index other than 0, or a productId different from the adapter’s appId. For the common default-account case, prefer createSessionSigner.

createSessionSignerForAccount(session: UserSession, ref: ProductAccountRef): PolkadotSigner

Parameters

• session: The paired user session.
• ref: The product account to sign as: \{ productId, derivationIndex \}.

createTerminalAdapter()

createTerminalAdapter(options: TerminalAdapterOptions): TerminalAdapter

getBulletinSigner()

Get a PolkadotSigner for a Bulletin allowance slot.

Allocates an allowance slot via the paired wallet (or returns the cached one), derives the slot-account keypair, and returns a PolkadotSigner that signs Bulletin extrinsics with it. Replaces the manual requestResourceAllocation + createSlotAccountSigner two-step for the common case.

getBulletinSigner(adapter: TerminalAdapter, productId: string, sessionId?: string): Promise<PolkadotSigner>

Parameters

• adapter: Terminal adapter.
• productId: The product id the slot is allocated under. Passed to the host as the calling product id in the allowance request.
• sessionId: Paired session to allocate against. Defaults to the only paired session; throws AllowanceError('NoSession') when zero or more than one sessions are paired and no explicit id is supplied.

Throws

• On rejection, missing session, host-side failure, or unexpected response shape.

Examples

import { createTerminalAdapter, getBulletinSigner } from "@parity/product-sdk-terminal";
 
const adapter = createTerminalAdapter({ appId: "my-cli" });
// ... QR pair, wait for session ...
const signer = await getBulletinSigner(adapter, "my-cli.dot");
await client.bulletin.tx.TransactionStorage.store({ data }).signAndSubmit(signer);

getStatementStoreProver()

Get a StatementProver for a statement-store allowance slot.

Allocates an allowance slot via the paired wallet (or returns the cached one) and returns the upstream StatementProver for the slot. Use when publishing statements through @novasamatech/statement-store without holding a long-lived key yourself.

getStatementStoreProver(adapter: TerminalAdapter, productId: string, sessionId?: string): Promise<StatementProver>

Parameters

• adapter: Terminal adapter.
• productId: The product id the slot is allocated under.
• sessionId: Paired session to allocate against. Defaults to the only paired session; throws AllowanceError('NoSession') when zero or more than one sessions are paired and no explicit id is supplied.

Throws

• On rejection, missing session, host-side failure, or unexpected response shape.

hasBulletinAllowance()

Cache-only probe for a Bulletin allowance slot. Resolves true when a slot key for (sessionId, productId, bulletin) is already cached on disk; false when it is not. Never prompts the paired wallet.

Pair with getBulletinSigner for the “check first, fetch only if needed” flow:

hasBulletinAllowance(adapter: TerminalAdapter, productId: string, sessionId?: string): Promise<boolean>

Examples

if (await hasBulletinAllowance(adapter, "my-cli.dot")) {
    // happy path — fetch the signer without risking a wallet prompt
    const signer = await getBulletinSigner(adapter, "my-cli.dot");
} else {
    // tell the user a wallet prompt will fire, then call getBulletinSigner
}

hasStatementStoreAllowance()

Cache-only probe for a Statement Store allowance slot. Resolves true when a slot key for (sessionId, productId, statementStore) is already cached on disk; false when it is not. Never prompts the paired wallet.

Pair with getStatementStoreProver for the “check first, fetch only if needed” flow.

hasStatementStoreAllowance(adapter: TerminalAdapter, productId: string, sessionId?: string): Promise<boolean>

renderQrCode()

Encode a string as a QR code rendered in Unicode half-block characters.

Returns a multi-line string suitable for console.log.

renderQrCode(data: string, options?: QrRenderOptions): Promise<string>

waitForSessions()

Wait for the adapter to load at least one persisted session, or resolve with an empty array after timeoutMs.

The session manager loads sessions from storage asynchronously, so a synchronous adapter.sessions.sessions.read() immediately after createTerminalAdapter() may return [] even when sessions exist on disk. Use this helper to give the loader a chance to populate before deciding whether the user is logged in.

waitForSessions(adapter: TerminalAdapter, timeoutMs: number = 3000): Promise<UserSession[]>

Interfaces

interface ProductAccountRef

Identifies which sub-account of a paired session should sign.

Mirrors the host-papp wire format productAccountId: [productId, derivationIndex]: productId is the dotNS-style identifier for the requesting product (matches the adapter’s appId in normal usage); derivationIndex is the BIP32-style child-key index, where 0 is the session’s default account.

Properties

derivationIndex

Child-key derivation index. 0 is the default account.

productId

The product identifier. Usually equal to the adapter’s appId.

publicKey

The product account’s sr25519 public key (32 bytes), as derived by the host for [productId, derivationIndex].

PAPI stamps this into the extrinsic’s signer address and verifies the signature against it, so it must be the product account’s key — not the wallet’s selected/root account (session.remoteAccount.accountId). A mismatch produces an invalid signature.

When omitted, the signer falls back to the session’s selected account, which is only correct when the product account is the selected account.

interface QrRenderOptions

Options for QR code rendering.

Properties

errorCorrectionLevel

Error correction level. Default: “M”.

margin

Quiet zone size in modules. Default: 2.

interface TerminalAdapterOptions

Options for creating a terminal adapter.

Properties

appId

Unique app identifier. Used as the storage namespace.

endpoints

Statement store WebSocket endpoints. Defaults to Paseo stable endpoints.

hostMetadata

Optional host metadata for the Sign-In screen.

storageDir

Directory where session files are persisted. Defaults to ~/.polkadot-apps/. Override in tests to point at a temporary directory populated with createTestSession from @parity/product-sdk-terminal/testing.

Type Aliases

type AllowanceErrorReason

type AllowanceErrorReason = "NoSession" | "Rejected" | "NotAvailable" | "UnexpectedResponse"

type AllowanceService

type AllowanceService = unknown

type HostMetadata

type HostMetadata = HandshakeMetadata

type PairingStatus

type PairingStatus = { step: "none" } | { step: "initial" } | { payload: string; step: "pairing" } | { stage: string; step: "pending" } | { message: string; step: "pairingError" } | { session: StoredUserSession; step: "finished" }

type PappAdapter

type PappAdapter = unknown

type SigningPayloadRequest

type SigningPayloadRequest = CodecType<typeof SigningPayloadRequestCodec>

type SigningPayloadResponse

type SigningPayloadResponse = CodecType<typeof SigningResponseCodec>

type SigningRawRequest

type SigningRawRequest = CodecType<typeof SigningRawRequestCodec>

type StoredUserSession

type StoredUserSession = CodecType<typeof storedUserSessionCodec>

type TerminalAdapter

A PappAdapter with the appId it was created with and a destroy method for cleanup.

type TerminalAdapter = PappAdapter & { readonly appId: string; readonly storageDir?: string; destroy: unknown }

type UserSession

type UserSession = StoredUserSession & { abortPendingRequests: unknown; createTransaction: unknown; dispose: unknown; getRingVrfAlias: unknown; requestResourceAllocation: unknown; sendDisconnectMessage: unknown; signPayload: unknown; signRaw: unknown; subscribe: unknown }

Variables

SS_PASEO_STABLE_STAGE_ENDPOINTS

let SS_PASEO_STABLE_STAGE_ENDPOINTS: string[]

SS_STABLE_STAGE_ENDPOINTS

let SS_STABLE_STAGE_ENDPOINTS: string[]