@joeywallet/wallet-sdk 0.2.0

package/dist/types.d.ts

@@ -0,0 +1,391 @@
+/**
+ * Public types for `@joeywallet/wallet-sdk`.
+ *
+ * These mirror the injected provider's surface field for field
+ * (`apps/extension/src/provider/`). Where the two could drift, the provider
+ * wins: this package is a convenience layer, not a second definition of the
+ * protocol.
+ *
+ * Nothing here imports from `xrpl`. A published `.d.ts` that did would fail to
+ * resolve for the (many) dapps that talk to a wallet without depending on
+ * xrpl.js, and `skipLibCheck` only hides that, it does not fix it. Instead the
+ * transaction argument of every signing method is generic over
+ * {@link TransactionLike}, so a caller who *does* have xrpl.js can pass a
+ * `Payment` / `TrustSet` / `SubmittableTransaction` and keep full checking on
+ * their own side. `test/xrpl-types.test.ts` pins that assignability against the
+ * real xrpl.js types.
+ */
+/** CAIP-2 chain ids, as XLS-72d defines them. Mainnet 0, testnet 1, devnet 2. */
+export declare const JOEY_CHAINS: readonly ["xrpl:0", "xrpl:1", "xrpl:2"];
+export type JoeyChain = (typeof JOEY_CHAINS)[number];
+export interface JoeyNetwork {
+    chain: JoeyChain;
+    /** The XRPL `NetworkID`. Same number as the chain id suffix. */
+    networkId: number;
+    /** The wallet's own name for the network, e.g. `mainnet`. */
+    name: string;
+}
+export declare function isJoeyChain(value: unknown): value is JoeyChain;
+/** `xrpl:0` for network id 0, and so on. Throws for anything else. */
+export declare function chainForNetworkId(networkId: number): JoeyChain;
+/** The `NetworkID` a chain id refers to, or `null` when it is not an XRPL chain. */
+export declare function networkIdForChain(chain: string): number | null;
+/** An account as the wallet reports it. Never carries secret material. */
+export interface JoeyAccount {
+    /** Classic `r...` address. */
+    address: string;
+    /** Hex-encoded public key. Absent for a watch-only account, which cannot sign. */
+    publicKey?: string;
+    /** The nickname the user gave the account, when they chose to share it. */
+    label?: string;
+}
+export interface IssuedCurrencyAmount {
+    /** Three-character code or 40-character hex. */
+    currency: string;
+    issuer: string;
+    /** Decimal string. Never a JS number — XRPL values exceed float64 precision. */
+    value: string;
+}
+export interface MPTAmount {
+    mpt_issuance_id: string;
+    value: string;
+}
+/** A bare string is drops of XRP. */
+export type Amount = string | IssuedCurrencyAmount | MPTAmount;
+export interface Memo {
+    Memo: {
+        /** Hex-encoded. */
+        MemoData?: string;
+        MemoType?: string;
+        MemoFormat?: string;
+    };
+}
+export interface Signer {
+    Signer: {
+        Account: string;
+        TxnSignature: string;
+        SigningPubKey: string;
+    };
+}
+export interface PathStep {
+    account?: string;
+    currency?: string;
+    issuer?: string;
+    type?: number;
+    type_hex?: string;
+}
+export type Path = PathStep[];
+/**
+ * The common fields of every XRPL transaction, used only as a generic
+ * constraint.
+ *
+ * `Flags` is deliberately `number | object` rather than a flags interface:
+ * xrpl.js models per-transaction flags as separate interfaces, and a TypeScript
+ * interface is not assignable to an index-signature type, so anything narrower
+ * here would reject a real `Payment`.
+ */
+export interface TransactionLike {
+    TransactionType: string;
+    Account?: string;
+    Fee?: string;
+    Sequence?: number;
+    AccountTxnID?: string;
+    Flags?: number | object;
+    LastLedgerSequence?: number;
+    Memos?: Memo[];
+    NetworkID?: number;
+    Signers?: Signer[];
+    SourceTag?: number;
+    SigningPubKey?: string;
+    TicketSequence?: number;
+    TxnSignature?: string;
+}
+/**
+ * A transaction written inline, with no xrpl.js types to hand. The index
+ * signature is what lets an object literal carry `Destination`, `Amount` and
+ * the rest without an excess-property error.
+ */
+export interface AnyTransaction extends TransactionLike {
+    [field: string]: unknown;
+}
+export interface ConnectParams {
+    /** Chain the dapp wants. Rejected with 4902 when it is not an XRPL chain. */
+    chain?: JoeyChain;
+    /**
+     * Only return accounts this origin has already been granted, with no prompt.
+     * Resolves with an empty `accounts` array rather than an error, so it says
+     * nothing about whether a wallet is installed, locked, or in use.
+     */
+    silent?: boolean;
+    /** Your dapp's name, shown on the approval screen. Up to 128 characters. */
+    name?: string;
+    /**
+     * An `https:` or `data:` URL for your dapp's icon, shown beside the name.
+     * Anything else is ignored rather than rendered.
+     */
+    icon?: string;
+}
+/**
+ * The fields every signing method accepts on top of its own.
+ *
+ * Both are optional and both are worth sending. Omitting `account` is only safe
+ * for an origin the user granted exactly one address; omitting `chain` means
+ * you are signing whatever network the wallet happens to be on.
+ */
+export interface SigningContextParams {
+    /**
+     * Which granted address signs. Defaults to the first the user granted.
+     *
+     * A user may grant several, so send this whenever your transaction carries an
+     * `Account`. The wallet refuses to sign a transaction whose `Account` is not
+     * the signing address — `INVALID_PARAMS` (-32602), before the user is
+     * prompted — rather than producing a valid signature over somebody else's
+     * transaction and resolving as if it had worked.
+     *
+     * `signTransactionFor` is the exception, and there `tx_signer` says who
+     * signs: a multisign entry is by definition a signature over a transaction
+     * belonging to another account.
+     */
+    account?: string;
+    /**
+     * The chain you believe you are on.
+     *
+     * When it is not the chain the wallet is on, the request is refused with
+     * `CHAIN_DISCONNECTED` (4901) rather than signed. Joey has no
+     * `switchNetwork`: a page-driven, wallet-wide network switch is a phishing
+     * surface, so the user changes network in the wallet and the dapp is told
+     * through `networkChanged`.
+     */
+    chain?: JoeyChain;
+}
+export interface ConnectResult {
+    accounts: JoeyAccount[];
+    /** `null` when the wallet granted no accounts, so there is no chain to report. */
+    chain: JoeyChain | null;
+    networkId: number | null;
+}
+export interface SignTransactionParams<TTx extends TransactionLike = AnyTransaction> extends SigningContextParams {
+    tx_json: TTx;
+    /** Let the wallet fill Fee / Sequence / LastLedgerSequence. Default true. */
+    autofill?: boolean;
+}
+export interface SignTransactionResult {
+    /**
+     * The transaction as signed — decoded back out of `tx_blob`, not echoed from
+     * what you sent.
+     *
+     * That is the point of it: it carries the `Fee`, `Sequence` and
+     * `LastLedgerSequence` the wallet filled in, the `SigningPubKey` and
+     * `TxnSignature` it produced, and any normalisation the serialiser applied.
+     * If it does not say what you expected, the bytes are what it says and not
+     * what you sent.
+     */
+    tx_json: Record<string, unknown>;
+    /** Hex-encoded signed transaction blob, ready to submit. */
+    tx_blob: string;
+    /** Hash of the signed blob. Not a confirmation on its own. */
+    hash: string;
+}
+export interface SignAndSubmitTransactionResult extends SignTransactionResult {
+    /** Preliminary engine result, e.g. `tesSUCCESS`. Not final until validated. */
+    engine_result?: string;
+    engine_result_message?: string;
+}
+export interface SignTransactionForParams<TTx extends TransactionLike = AnyTransaction> extends SigningContextParams {
+    /**
+     * The address whose signature is being produced, which is *not* the
+     * transaction's `Account` — that stays the multisigned account.
+     *
+     * It must be one of the addresses the user granted this origin; the wallet
+     * answers `UNAUTHORIZED` (4100) rather than substituting one of its own.
+     */
+    tx_signer: string;
+    tx_json: TTx;
+    /**
+     * **Ignored on this method.** Joey never autofills a multisign entry, and
+     * passing `true` does not make it.
+     *
+     * The field is here because the parameter shape is shared with the other
+     * signing methods, not because it does anything. Your `tx_json` is signed
+     * exactly as you sent it, so it must already carry `Fee`, `Sequence` and
+     * `LastLedgerSequence` — otherwise you get a real signature over a
+     * transaction `rippled` will not accept, and no error until you submit it.
+     *
+     * The reason is that a multisign signature is one of several over *identical
+     * bytes*. All three fields are inside the signed bytes, so two signers who
+     * approve a few seconds apart would read two different `LastLedgerSequence`
+     * values and the assembled transaction would validate at most one of their
+     * signatures. The `Fee` is worse: the rule is `base_fee x (1 + signatures)`,
+     * a wallet contributes one signature and cannot know how many others the
+     * signer list requires, and a coordinator cannot raise a `Fee` afterwards
+     * without discarding every signature it has already collected. The one party
+     * who can choose these is the coordinator assembling the transaction — you.
+     */
+    autofill?: boolean;
+}
+/**
+ * N independent transactions, one approval, signed in order.
+ *
+ * **This is not XLS-56 `Batch`, and the two must not be confused.** A `Batch`
+ * is a single transaction that carries others inside `RawTransactions` and
+ * commits them atomically on-ledger; Joey refuses to sign one for a website
+ * (see {@link JOEY_DAPP_FORBIDDEN_TRANSACTION_TYPES}) because its approval
+ * screen renders the outer transaction and a user cannot consent to inner ones
+ * they were never shown. `signTransactionBulk` is the opposite arrangement:
+ * ordinary, separate transactions, each rendered on its own page of the
+ * approval, each signed on its own, with no on-ledger atomicity at all. If
+ * transaction 3 fails, 1 and 2 have still happened.
+ */
+export interface SignTransactionBulkParams<TTx extends TransactionLike = AnyTransaction> extends SigningContextParams {
+    /** At most `MAX_BULK_TRANSACTIONS` entries; the wallet rejects a longer list. */
+    tx_list: Array<{
+        tx_json: TTx;
+    }>;
+    autofill?: boolean;
+    /**
+     * Whether the wallet broadcasts each transaction after signing it, or hands
+     * the signed blobs back for you to submit.
+     *
+     * Required, with no default, because the two are not interchangeable and a
+     * dapp that guesses wrong either double-spends or never spends. Joey mobile
+     * defaults this to `true` over WalletConnect and the extension defaults it to
+     * `false`; state your intent and neither default applies to you.
+     */
+    submit: boolean;
+}
+/**
+ * What became of one transaction of a bulk request that failed part way.
+ *
+ * The five values divide on two questions only the wallet can answer: did this
+ * transaction get a definite answer, and is the replay protection it holds —
+ * its sequence number, or its ticket — still reachable?
+ *
+ *  - `submitted` — validated `tesSUCCESS`. It happened; `hash` is on the ledger.
+ *  - `failed` — a definite answer that is not success. `engine_result` says
+ *    which. Resubmitting this blob is pointless.
+ *  - `unknown` — **do not treat this as `failed`.** Either the submission got
+ *    no answer at all, or it sits behind one that did not. It may yet be
+ *    validated, so resubmitting is not safe. Resolve it by its `hash` first.
+ *  - `signed` — signed, never broadcast, and still submittable exactly as it
+ *    stands: it spends a ticket nothing touched, or it holds the sequence
+ *    number the account is now at. Submit the `signed` entries in the order
+ *    they appear — they are a chain.
+ *  - `stranded` — signed, never broadcast, and dead. The sequence it holds is
+ *    either already consumed or sits behind a gap this batch will never fill,
+ *    so it can never apply. Discard it and ask the user again.
+ *
+ * The last two are decided per entry against the account's actual sequence, not
+ * per batch off the failing transaction's code — the code alone is right only
+ * for a contiguous run the wallet numbered itself, and both a ticket and a
+ * `Sequence` you set yourself break that assumption, in opposite directions.
+ */
+export type BulkEntryStatus = 'submitted' | 'failed' | 'unknown' | 'signed' | 'stranded';
+/** One entry of {@link SignTransactionBulkFailure.results}. */
+export interface BulkEntryResult extends SignTransactionResult {
+    status: BulkEntryStatus;
+    /** The ledger's own token for this transaction, when it produced one. */
+    engine_result?: string;
+    engine_result_message?: string;
+}
+/**
+ * The `data` on the error a partially-executed `signTransactionBulk` rejects
+ * with.
+ *
+ * A bulk request with `submit: true` signs every transaction before it
+ * broadcasts any of them, so the blobs exist whatever happens at index 3 and
+ * you get all of them back. Resume from `failedIndex` rather than asking the
+ * user to approve the whole batch again.
+ *
+ * ```ts
+ * try {
+ *   await joey.signTransactionBulk({ tx_list, submit: true })
+ * } catch (error) {
+ *   const data = (error as JoeyRpcError).data as SignTransactionBulkFailure | undefined
+ *   if (data) {
+ *     // data.results[i].status tells you what to do with entry i.
+ *   }
+ * }
+ * ```
+ *
+ * Joey mobile rejects a bulk request over WalletConnect with the same
+ * `failedIndex` — zero-based, every earlier transaction succeeded, and the one
+ * thing that transfers between the two wallets unchanged. The record carrying
+ * it does not: mobile's `data` is a JSON *string* (WalletConnect types error
+ * `data` as one) holding `{failedIndex, signedTxs}`, where `signedTxs` is bare
+ * `tx_json` with no `status` on it, and its `message` is the engine token
+ * alone. Branch on the container and the array name; do not write one handler
+ * for both and expect it to parse.
+ */
+export interface SignTransactionBulkFailure {
+    /**
+     * Zero-based index of the first entry that did not succeed.
+     *
+     * The error's `message` names the same number the same way — "transaction at
+     * index 2 of 5 did not succeed: tecUNFUNDED_PAYMENT" — so the sentence and
+     * the field cannot be read as disagreeing. It said "transaction 2 of 5" for
+     * that case until this was written, which is the third transaction and the
+     * one wording that can be read two ways.
+     */
+    failedIndex: number;
+    /** Every transaction in the batch, in the order you sent them. */
+    results: BulkEntryResult[];
+}
+/**
+ * Sign-in modes.
+ *
+ * One, and it is the safe one: `caip122` signs a human-readable CAIP-122 /
+ * EIP-4361 string under a non-transaction domain separator, so the signature is
+ * cryptographically incapable of being a transaction signature.
+ *
+ * **`xaman` has been removed.** It signed the `{TransactionType:'SignIn'}`
+ * pseudo-transaction, and the property that made it safe — `rippled` has no
+ * such type, so the blob is unsubmittable — is exactly why it could not be
+ * produced: `ripple-binary-codec` has no `SignIn` either, so serialising one
+ * threw, every time, *after* the user had approved. The wallet refuses
+ * `mode: 'xaman'` by name rather than silently signing a CAIP-122 message in
+ * its place, so an existing Xaman integration gets one clear error instead of a
+ * result with no `tx_blob` in it.
+ */
+export type SignInMode = 'caip122';
+export interface SignInParams {
+    /** Default, and the only value. */
+    mode?: SignInMode;
+    /** Human-readable line the wallet shows. At most 512 characters. */
+    statement?: string;
+    /** The wallet generates one when omitted. At most 128 characters. */
+    nonce?: string;
+    /**
+     * Up to 16 URI strings naming the scope you are asking for.
+     *
+     * Shown on the approval screen and written into the message's `Resources:`
+     * section, so they are part of what the signature covers: rebuild the message
+     * with the same list, in the same order, to verify one.
+     */
+    resources?: string[];
+}
+export interface SignInResult {
+    address: string;
+    publicKey: string;
+    /** Hex-encoded signature. */
+    signature: string;
+    /** The exact string that was signed. Rebuild it to verify the signature. */
+    message: string;
+}
+export interface JoeyEventMap {
+    /** The origin became authorised. */
+    connect: {
+        accounts: JoeyAccount[];
+        chain: JoeyChain | null;
+    };
+    /** The origin lost authorisation, or the wallet locked. */
+    disconnect: {
+        reason?: string;
+    };
+    /** The granted account set changed. Empty means the grant was revoked. */
+    accountsChanged: JoeyAccount[];
+    /** `null` when the wallet reported a chain this SDK does not recognise. */
+    networkChanged: JoeyNetwork | null;
+}
+export type JoeyEventName = keyof JoeyEventMap;
+export type JoeyEventListener<K extends JoeyEventName> = (payload: JoeyEventMap[K]) => void;
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types.js

@@ -0,0 +1,38 @@
+/**
+ * Public types for `@joeywallet/wallet-sdk`.
+ *
+ * These mirror the injected provider's surface field for field
+ * (`apps/extension/src/provider/`). Where the two could drift, the provider
+ * wins: this package is a convenience layer, not a second definition of the
+ * protocol.
+ *
+ * Nothing here imports from `xrpl`. A published `.d.ts` that did would fail to
+ * resolve for the (many) dapps that talk to a wallet without depending on
+ * xrpl.js, and `skipLibCheck` only hides that, it does not fix it. Instead the
+ * transaction argument of every signing method is generic over
+ * {@link TransactionLike}, so a caller who *does* have xrpl.js can pass a
+ * `Payment` / `TrustSet` / `SubmittableTransaction` and keep full checking on
+ * their own side. `test/xrpl-types.test.ts` pins that assignability against the
+ * real xrpl.js types.
+ */
+/* ------------------------------------------------------------------- chains */
+/** CAIP-2 chain ids, as XLS-72d defines them. Mainnet 0, testnet 1, devnet 2. */
+export const JOEY_CHAINS = ['xrpl:0', 'xrpl:1', 'xrpl:2'];
+export function isJoeyChain(value) {
+    return typeof value === 'string' && JOEY_CHAINS.includes(value);
+}
+/** `xrpl:0` for network id 0, and so on. Throws for anything else. */
+export function chainForNetworkId(networkId) {
+    const chain = `xrpl:${networkId}`;
+    if (!isJoeyChain(chain)) {
+        throw new RangeError(`Unrecognised XRPL network id: ${networkId}`);
+    }
+    return chain;
+}
+/** The `NetworkID` a chain id refers to, or `null` when it is not an XRPL chain. */
+export function networkIdForChain(chain) {
+    if (!isJoeyChain(chain))
+        return null;
+    return Number(chain.slice('xrpl:'.length));
+}
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,gFAAgF;AAEhF,iFAAiF;AACjF,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,QAAQ,EAAE,QAAQ,EAAE,QAAQ,CAAU,CAAA;AAYlE,MAAM,UAAU,WAAW,CAAC,KAAc;IACxC,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAK,WAAiC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAA;AACxF,CAAC;AAED,sEAAsE;AACtE,MAAM,UAAU,iBAAiB,CAAC,SAAiB;IACjD,MAAM,KAAK,GAAG,QAAQ,SAAS,EAAE,CAAA;IACjC,IAAI,CAAC,WAAW,CAAC,KAAK,CAAC,EAAE,CAAC;QACxB,MAAM,IAAI,UAAU,CAAC,iCAAiC,SAAS,EAAE,CAAC,CAAA;IACpE,CAAC;IACD,OAAO,KAAK,CAAA;AACd,CAAC;AAED,oFAAoF;AACpF,MAAM,UAAU,iBAAiB,CAAC,KAAa;IAC7C,IAAI,CAAC,WAAW,CAAC,KAAK,CAAC;QAAE,OAAO,IAAI,CAAA;IACpC,OAAO,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAA;AAC5C,CAAC"}

package/dist/vanilla.d.ts

@@ -0,0 +1,58 @@
+/**
+ * `@joeywallet/wallet-sdk/vanilla`.
+ *
+ * A connection session with a subscribe/getState store, for pages that have no
+ * framework. It holds the two pieces of state every dapp ends up re-writing by
+ * hand — the connected account and the current network — and keeps them correct
+ * when the user switches account or network in the wallet.
+ */
+import type { Joey } from './client.js';
+import { JoeyRpcError } from './errors.js';
+import type { ConnectParams, JoeyNetwork } from './types.js';
+export interface JoeySessionState {
+    /** `null` while detection is still running, and if it never finds a provider. */
+    joey: Joey | null;
+    isAvailable: boolean;
+    isReady: boolean;
+    isConnecting: boolean;
+    accounts: string[];
+    /** The first granted address. `null` when this origin has no grant. */
+    account: string | null;
+    network: JoeyNetwork | null;
+    error: JoeyRpcError | null;
+}
+export interface JoeySession {
+    getState(): JoeySessionState;
+    /** Called immediately with the current state, then on every change. */
+    subscribe(listener: (state: JoeySessionState) => void): () => void;
+    connect(params?: ConnectParams): Promise<string | null>;
+    disconnect(): Promise<void>;
+    /** Removes every listener this session registered. */
+    destroy(): void;
+}
+export interface CreateJoeySessionOptions {
+    /** Try a silent reconnect once the provider is found. Default true. */
+    autoConnect?: boolean;
+    /** How long to wait for a late-injected provider. Default 3000ms. */
+    detectTimeoutMs?: number;
+}
+export declare function createJoeySession(options?: CreateJoeySessionOptions): JoeySession;
+export interface BindConnectButtonOptions {
+    /** Text while disconnected. Default "Connect Joey". */
+    connectLabel?: string;
+    /** Rendered with the connected address. Default is a truncated address. */
+    connectedLabel?(address: string): string;
+    /** Text when no provider was found. Default "Install Joey". */
+    notInstalledLabel?: string;
+    /** Where to send a user with no wallet. Opened in a new tab when clicked. */
+    installUrl?: string;
+    onError?(error: JoeyRpcError): void;
+}
+/**
+ * Wire a `<button>` to a session: label, disabled state and click handler.
+ *
+ * The whole point of the vanilla entry point — this is the twenty lines every
+ * script-tag dapp writes, and gets subtly wrong around the not-installed case.
+ */
+export declare function bindConnectButton(button: HTMLButtonElement, session: JoeySession, options?: BindConnectButtonOptions): () => void;
+//# sourceMappingURL=vanilla.d.ts.map

package/dist/vanilla.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vanilla.d.ts","sourceRoot":"","sources":["../src/vanilla.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,aAAa,CAAA;AAEvC,OAAO,EAAoB,YAAY,EAAE,MAAM,aAAa,CAAA;AAC5D,OAAO,KAAK,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA;AAE5D,MAAM,WAAW,gBAAgB;IAC/B,iFAAiF;IACjF,IAAI,EAAE,IAAI,GAAG,IAAI,CAAA;IACjB,WAAW,EAAE,OAAO,CAAA;IACpB,OAAO,EAAE,OAAO,CAAA;IAChB,YAAY,EAAE,OAAO,CAAA;IACrB,QAAQ,EAAE,MAAM,EAAE,CAAA;IAClB,uEAAuE;IACvE,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;IACtB,OAAO,EAAE,WAAW,GAAG,IAAI,CAAA;IAC3B,KAAK,EAAE,YAAY,GAAG,IAAI,CAAA;CAC3B;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,IAAI,gBAAgB,CAAA;IAC5B,uEAAuE;IACvE,SAAS,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,gBAAgB,KAAK,IAAI,GAAG,MAAM,IAAI,CAAA;IAClE,OAAO,CAAC,MAAM,CAAC,EAAE,aAAa,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAA;IACvD,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;IAC3B,sDAAsD;IACtD,OAAO,IAAI,IAAI,CAAA;CAChB;AAED,MAAM,WAAW,wBAAwB;IACvC,uEAAuE;IACvE,WAAW,CAAC,EAAE,OAAO,CAAA;IACrB,qEAAqE;IACrE,eAAe,CAAC,EAAE,MAAM,CAAA;CACzB;AAED,wBAAgB,iBAAiB,CAAC,OAAO,GAAE,wBAA6B,GAAG,WAAW,CA+HrF;AAED,MAAM,WAAW,wBAAwB;IACvC,uDAAuD;IACvD,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,2EAA2E;IAC3E,cAAc,CAAC,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAAA;IACxC,+DAA+D;IAC/D,iBAAiB,CAAC,EAAE,MAAM,CAAA;IAC1B,6EAA6E;IAC7E,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,OAAO,CAAC,CAAC,KAAK,EAAE,YAAY,GAAG,IAAI,CAAA;CACpC;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,iBAAiB,EACzB,OAAO,EAAE,WAAW,EACpB,OAAO,GAAE,wBAA6B,GACrC,MAAM,IAAI,CA4CZ"}

package/dist/vanilla.js

@@ -0,0 +1,161 @@
+import { getJoey, waitForJoey } from './detect.js';
+import { JOEY_ERROR_CODES, JoeyRpcError } from './errors.js';
+export function createJoeySession(options = {}) {
+    const { autoConnect = true, detectTimeoutMs = 3000 } = options;
+    const initial = getJoey();
+    let state = {
+        joey: initial,
+        isAvailable: initial !== null,
+        isReady: initial !== null,
+        isConnecting: false,
+        accounts: [],
+        account: null,
+        network: null,
+        error: null,
+    };
+    const listeners = new Set();
+    const teardown = [];
+    let destroyed = false;
+    const set = (patch) => {
+        const next = { ...state, ...patch };
+        // `account` is always derived, never set directly, so the two can't drift.
+        next.account = next.accounts[0] ?? null;
+        state = next;
+        for (const listener of listeners)
+            listener(state);
+    };
+    const attach = (joey) => {
+        teardown.push(joey.on('accountsChanged', (accounts) => set({ accounts: accounts.map((account) => account.address) })));
+        teardown.push(joey.on('networkChanged', (network) => set({ network })));
+        teardown.push(joey.on('connect', (result) => set({ accounts: result.accounts.map((account) => account.address) })));
+        teardown.push(joey.on('disconnect', () => set({ accounts: [] })));
+    };
+    const hydrate = async (joey) => {
+        const [accounts, network] = await Promise.all([
+            joey.getAccounts().catch(() => []),
+            joey.getNetwork().catch(() => null),
+        ]);
+        if (!destroyed)
+            set({ accounts, network });
+    };
+    const adopt = async (joey) => {
+        if (destroyed)
+            return;
+        set({ joey, isAvailable: true, isReady: true });
+        attach(joey);
+        if (autoConnect) {
+            try {
+                const result = await joey.connect({ silent: true });
+                if (destroyed)
+                    return;
+                if (result.accounts.length > 0) {
+                    set({ accounts: result.accounts.map((account) => account.address) });
+                    const network = await joey.getNetwork().catch(() => null);
+                    if (!destroyed)
+                        set({ network });
+                    return;
+                }
+            }
+            catch {
+                // Not yet authorised. Expected on a first visit.
+            }
+        }
+        await hydrate(joey);
+    };
+    if (initial !== null) {
+        void adopt(initial);
+    }
+    else {
+        void waitForJoey({ timeoutMs: detectTimeoutMs })
+            .then(adopt)
+            .catch(() => {
+            if (!destroyed)
+                set({ isReady: true });
+        });
+    }
+    return {
+        getState: () => state,
+        subscribe(listener) {
+            listeners.add(listener);
+            listener(state);
+            return () => listeners.delete(listener);
+        },
+        async connect(params) {
+            const joey = state.joey ?? getJoey();
+            if (joey === null) {
+                const error = new JoeyRpcError(JOEY_ERROR_CODES.DISCONNECTED, 'Joey Wallet is not installed, or its provider has not been injected into this page.');
+                set({ error });
+                throw error;
+            }
+            set({ isConnecting: true, error: null });
+            try {
+                const result = await joey.connect(params);
+                const accounts = result.accounts.map((account) => account.address);
+                const network = await joey.getNetwork().catch(() => state.network);
+                set({ accounts, network, isConnecting: false });
+                return accounts[0] ?? null;
+            }
+            catch (cause) {
+                const error = JoeyRpcError.from(cause);
+                set({ isConnecting: false, error });
+                throw error;
+            }
+        },
+        async disconnect() {
+            const joey = state.joey;
+            if (joey === null)
+                return;
+            await joey.disconnect();
+            set({ accounts: [] });
+        },
+        destroy() {
+            destroyed = true;
+            for (const off of teardown.splice(0))
+                off();
+            listeners.clear();
+        },
+    };
+}
+/**
+ * Wire a `<button>` to a session: label, disabled state and click handler.
+ *
+ * The whole point of the vanilla entry point — this is the twenty lines every
+ * script-tag dapp writes, and gets subtly wrong around the not-installed case.
+ */
+export function bindConnectButton(button, session, options = {}) {
+    const { connectLabel = 'Connect Joey', connectedLabel = (address) => `${address.slice(0, 6)}…${address.slice(-4)}`, notInstalledLabel = 'Install Joey', installUrl, onError, } = options;
+    const render = (state) => {
+        if (!state.isReady) {
+            button.disabled = true;
+            button.textContent = connectLabel;
+            return;
+        }
+        if (!state.isAvailable) {
+            button.disabled = installUrl === undefined;
+            button.textContent = notInstalledLabel;
+            return;
+        }
+        button.disabled = state.isConnecting;
+        button.textContent = state.account !== null ? connectedLabel(state.account) : connectLabel;
+    };
+    const onClick = () => {
+        const state = session.getState();
+        if (!state.isAvailable) {
+            if (installUrl !== undefined)
+                window.open(installUrl, '_blank', 'noopener,noreferrer');
+            return;
+        }
+        // `session.connect` already stored the error in state; this catch only
+        // exists so the rejection is not unhandled.
+        void session.connect().catch((error) => {
+            onError?.(JoeyRpcError.from(error));
+        });
+    };
+    button.addEventListener('click', onClick);
+    const unsubscribe = session.subscribe(render);
+    return () => {
+        button.removeEventListener('click', onClick);
+        unsubscribe();
+    };
+}
+//# sourceMappingURL=vanilla.js.map