@parity/product-sdk-terminal 0.0.0-dev.312.0

package/dist/index.d.ts

@@ -0,0 +1,262 @@
+import { T as TerminalAdapter } from './host-C3KVvc1j.js';
+export { A as AllocatableResource, a as ApAllocationOutcome, O as OnExistingAllowancePolicy, R as RequestResourceAllocationOptions, b as TerminalAdapterOptions, c as createTerminalAdapter, r as requestResourceAllocation, s as sendResourceAllocation } from './host-C3KVvc1j.js';
+import { UserSession } from '@novasamatech/host-papp';
+export { AllowanceError, AllowanceErrorReason, AllowanceService, HostMetadata, PairingStatus, PappAdapter, SS_PASEO_STABLE_STAGE_ENDPOINTS, SS_STABLE_STAGE_ENDPOINTS, SigningPayloadRequest, SigningPayloadResponse, SigningRawRequest, StoredUserSession, UserSession } from '@novasamatech/host-papp';
+import { PolkadotSigner } from 'polkadot-api';
+export { AllowanceExpiredError, SignerError } from '@parity/product-sdk-signer/errors';
+import { StatementProver } from '@novasamatech/statement-store';
+import { StorageAdapter } from '@novasamatech/storage-adapter';
+import 'neverthrow';
+
+/**
+ * Create a PolkadotSigner from a QR-paired session.
+ *
+ * Routes **transaction signing** through `session.createTransaction` — the
+ * host-papp `CreateTransactionRequest`/`CreateTransactionResponse` SSO
+ * message pair. We hand the mobile app the structured
+ * `ProductAccountTransaction` (`signer`, `genesisHash`, `callData`, the
+ * per-extension `{ extra, additionalSigned }`, and `txExtVersion`) and it
+ * **builds and signs** the full extrinsic, returning the signed bytes.
+ *
+ * Two properties fall out of this:
+ *  - The wallet can **decode and display** the transaction instead of
+ *    blind-signing an opaque hash (which is what the older
+ *    `session.signRaw({ tag: "Payload" })` route did).
+ *  - Every signed extension the chain declares — including ones PAPI's PJS
+ *    adapter doesn't know (e.g. `AsPgas` on Paseo Next v2) — is forwarded
+ *    verbatim as `{ id, extra, additionalSigned }`, so nothing is lost in
+ *    translation.
+ *
+ * **Raw-message signing** (`signBytes`) keeps the `session.signRaw` `Bytes`
+ * tag so the wallet applies the `<Bytes>...</Bytes>` anti-phishing wrap once
+ * on its side. Correct for arbitrary user data; wrong for extrinsic payloads
+ * (which is why the two paths split).
+ *
+ * @example
+ * ```ts
+ * const [session] = adapter.sessions.sessions.read();
+ *
+ * // Default account — uses [adapter.appId, 0]:
+ * const signer = createSessionSigner(session, adapter);
+ *
+ * // Non-default derivation index, or a different productId:
+ * const subSigner = createSessionSignerForAccount(session, {
+ *     productId: "my-product",
+ *     derivationIndex: 3,
+ * });
+ *
+ * await contract.publish.tx(domain, cid, { signer, origin });
+ * ```
+ */
+
+/**
+ * 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.
+ */
+interface ProductAccountRef {
+    /** The product identifier. Usually equal to the adapter's `appId`. */
+    productId: string;
+    /** Child-key derivation index. `0` is the default account. */
+    derivationIndex: number;
+    /**
+     * 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 soft-derives it from the session's root account
+     * (`mnemonic + "/product/{productId}/{derivationIndex}"`), which is correct
+     * for every product account. Supply it explicitly only to avoid the
+     * re-derivation or when you've already derived it elsewhere.
+     */
+    publicKey?: Uint8Array;
+}
+declare const INCOMPLETE_SESSION_MESSAGE = "Stored login session is missing the root account public key. Run \"logout\" and then \"login\" to pair again.";
+/**
+ * The session's handshake-time root account public key (`rootUserAccountId` =
+ * the user's bare-mnemonic keypair on current mobile builds). This is the
+ * parent key product accounts soft-derive from. host-papp's live `UserSession`
+ * doesn't surface it on the public type, so we read it structurally.
+ *
+ * @throws {@link INCOMPLETE_SESSION_MESSAGE} if the session predates the
+ *   `rootAccountId` field (a stale login that must re-pair).
+ */
+declare function sessionRootPublicKey(session: UserSession): Uint8Array;
+/**
+ * Soft-derive a product account's sr25519 public key from a paired session's
+ * root account.
+ *
+ * This is the single source of truth for product-account math. The session
+ * signer uses it to stamp the correct signer address; consumers that need the
+ * product address *without* building a signer (e.g. a login-status display
+ * triple) call it directly so the displayed address can't desync from what the
+ * signer actually signs with.
+ *
+ * sr25519 soft derivation is composable on public keys alone, so deriving from
+ * `session.rootAccountId` locally produces the SAME key the host derives
+ * privately via `mnemonic + "/product/{productId}/{derivationIndex}"`.
+ *
+ * @throws {@link INCOMPLETE_SESSION_MESSAGE} on a stale session with no root key.
+ */
+declare function deriveProductPublicKey(session: UserSession, ref: ProductAccountRef): Uint8Array;
+/**
+ * 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 {@link createSessionSignerForAccount}.
+ *
+ * @param session The paired user session.
+ * @param adapter The {@link TerminalAdapter} that loaded the session. Its `appId`
+ *   is used as the `productId` in the wire request.
+ * @param publicKey The product account's sr25519 public key for
+ *   `[adapter.appId, 0]`. Optional — when omitted it's soft-derived from the
+ *   session root. See {@link ProductAccountRef.publicKey}.
+ */
+declare function createSessionSigner(session: UserSession, adapter: TerminalAdapter, publicKey?: Uint8Array): PolkadotSigner;
+/**
+ * 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 {@link createSessionSigner}.
+ *
+ * @param session The paired user session.
+ * @param ref The product account to sign as: `{ productId, derivationIndex }`.
+ */
+declare function createSessionSignerForAccount(session: UserSession, ref: ProductAccountRef): PolkadotSigner;
+
+/**
+ * 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.
+ *
+ * @param adapter Terminal adapter.
+ * @param productId The product id the slot is allocated under. Passed to the
+ *   host as the calling product id in the allowance request.
+ * @param 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 {AllowanceError} On rejection, missing session, host-side failure,
+ *   or unexpected response shape.
+ *
+ * @example
+ * ```ts
+ * 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);
+ * ```
+ */
+declare function getBulletinSigner(adapter: TerminalAdapter, productId: string, sessionId?: string): Promise<PolkadotSigner>;
+/**
+ * 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.
+ *
+ * @param adapter Terminal adapter.
+ * @param productId The product id the slot is allocated under.
+ * @param 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 {AllowanceError} On rejection, missing session, host-side failure,
+ *   or unexpected response shape.
+ */
+declare function getStatementStoreProver(adapter: TerminalAdapter, productId: string, sessionId?: string): Promise<StatementProver>;
+/**
+ * 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 {@link getBulletinSigner} for the "check first, fetch only
+ * if needed" flow:
+ *
+ * @example
+ * ```ts
+ * 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
+ * }
+ * ```
+ */
+declare function hasBulletinAllowance(adapter: TerminalAdapter, productId: string, sessionId?: string): Promise<boolean>;
+/**
+ * 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 {@link getStatementStoreProver} for the "check first, fetch
+ * only if needed" flow.
+ */
+declare function hasStatementStoreAllowance(adapter: TerminalAdapter, productId: string, sessionId?: string): Promise<boolean>;
+
+/**
+ * Helpers for working with persisted sessions on a `TerminalAdapter`.
+ */
+
+/**
+ * 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.
+ */
+declare function waitForSessions(adapter: TerminalAdapter, timeoutMs?: number): Promise<UserSession[]>;
+
+/**
+ * Terminal QR code rendering using Unicode half-block characters.
+ *
+ * Wraps the `qrcode` npm package's UTF-8 renderer, which packs two
+ * module rows per terminal line using half-block characters.
+ */
+/** Options for QR code rendering. */
+interface QrRenderOptions {
+    /** Error correction level. Default: "M". */
+    errorCorrectionLevel?: "L" | "M" | "Q" | "H";
+    /** Quiet zone size in modules. Default: 2. */
+    margin?: number;
+}
+/**
+ * Encode a string as a QR code rendered in Unicode half-block characters.
+ *
+ * Returns a multi-line string suitable for `console.log`.
+ */
+declare function renderQrCode(data: string, options?: QrRenderOptions): Promise<string>;
+
+/**
+ * File-based StorageAdapter for Node.js environments.
+ *
+ * Implements the @novasamatech/storage-adapter interface using JSON files
+ * in ~/.polkadot-apps/. Node.js doesn't have localStorage, so this
+ * provides persistent storage for the SDK's session and secret data.
+ */
+
+/**
+ * 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/`).
+ */
+declare function createNodeStorageAdapter(appId: string, storageDir?: string): StorageAdapter;
+
+export { INCOMPLETE_SESSION_MESSAGE, type ProductAccountRef, type QrRenderOptions, TerminalAdapter, createNodeStorageAdapter, createSessionSigner, createSessionSignerForAccount, deriveProductPublicKey, getBulletinSigner, getStatementStoreProver, hasBulletinAllowance, hasStatementStoreAllowance, renderQrCode, sessionRootPublicKey, waitForSessions };