@meteorwallet/connect-shared

Shared schemas, types, errors, and action/realm definitions for Meteor Wallet Connect.

This package is the common layer between @meteorwallet/connect (the client) and the Meteor Connect backend. It contains the valibot schemas, the typed @nice-code/action channel and runtime definitions, the bridge realm definition, and the shared error domain — everything both sides of a connection must agree on.

Client applications install @meteorwallet/connect and this package: the client carries the two session clients, the storage adapters, the helpers and the wire payload types, while this package carries the protocol enums, the action implementations you build requests and results with, and the typed error catalogue. Those two are the whole integration surface.

Installation

npm install @meteorwallet/connect-shared
# or
bun add @meteorwallet/connect-shared

What app consumers import

The main entry point is a curated consumer barrel — 156 symbols, not the package's full internals. Everything on it is meant for app code:

• Enums: EMeteorAppId, EPartnerOrigin, ESessionPhase, ESessionResourceProfile, ESessionAuthorizationMode, ESessionAuthorizationLevel, EBridgeInteractionMode, EWalletProtocolCapability, ERuntimeEnvironment, ESessionNotifyWalletReason
• Action implementations: act_impl_meteor_wallet_core, act_impl_near, act_impl_meteor_connect_demo, plus the account-transfer / new-key-transfer domain types and helpers (TNewKeyTransferStartInputV1, buildAccountsTransferRequestData, …)
• Error domains: merr_bridge_session, merr_bridge, EErr_Bridge_Session, EErr_Bridge
• Session types: TSessionFacts, TSessionRequestEnvelopeV1, TSessionClaimPushPayload, TSessionTurnWakePushPayload, TSession_Create_Input, TSession_Complete_Input
• D33 host obligations: createAddKeyJournalRunner, createAddKeyJournalStore, prepareAccountImport, commitPreparedAccountImport, AddKeyJournalError
• Fenced-transfer reconciliation: buildNewKeyTransferReconciliationReport, newKeyTransferProtectedOperations, newKeyTransferSupportReference, INewKeyTransferFencedOperation — the evidence and state machine that turn an orphaned signed AddKey into a resolvable state instead of a permanent fence (see docs/consumer/d33-host-obligations.md)
• Crypto/key types: TSerializedCryptoKeyData_Ed25519_Raw, TSerializedCryptoKeyData_X25519_Raw, ClientKeySerialization
• Realm: TSessionRealmState, ESessionRealmAvatar

Wire valibot schemas, challenge builders, session/action policy tables, durable-object state shapes, the D33 recovery contract, and observability types are not on this barrel — they live on the ./internal subpath, which is published so the backend can resolve it but is not the consumer API and may change without a SemVer-major bump. Needing something that is only on ./internal is worth raising: it usually means a helper is missing here.

Usage

import {
  act_impl_meteor_wallet_core,
  EErr_Bridge_Session,
  ESessionPhase,
  merr_bridge_session,
} from "@meteorwallet/connect-shared";

// Build the wire request a partner installs as a session turn. `.request(input)` type-checks the
// input against the action's schema; `.toJsonObject()` produces what the client's
// `createSession({ initialActionRequest })` takes.
const actionRequest = act_impl_meteor_wallet_core.action.transfer_accounts
  .request(transferAccountsInput)
  .toJsonObject();

// Classify a protocol rejection by its typed id rather than by message text.
try {
  await installTurn(actionRequest);
} catch (error) {
  if (merr_bridge_session.isExact(error) && error.hasId(EErr_Bridge_Session.phase_mismatch)) {
    render(`re-read the session facts — the phase moved past ${ESessionPhase.wallet_action}`);
  }
}

The package ships both ESM and CommonJS builds with full type declarations for each.

One session per process

Each client instance binds at most one bridge session at a time. Claiming a new session while one is live throws — disconnect the current session first. This is a protocol invariant, not a configuration choice: the bridge enforces one claimed wallet per session, and the SDK's mutation locks, event hub, and turn iterators are all scoped to the bound session.

Acknowledgement is receipt, not acceptance

acknowledgeResult tells the backend "I received this result" — it is transport receipt, never acceptance of the result's content. A declined result (signed typed-error) is still acknowledged so the session is not parked in result_ready; the partner then decides whether to close, replay, or advance. acknowledgeAndClose is the final receipt-and-close; advance is receipt-plus-next-turn.

Protocol lifecycle

The shared schemas define the signed bridge-creation proof, versioned bridge lease, absolute expiry and bridge_gone terminal outcome, persisted behavior/cohort fields, wallet account/link incarnations, fresh idempotent destructive operations, relationship bounds, and push notification deduplication ID. Protocol implementers must preserve canonical serialization and validate bounds before Durable Object lookup or durable writes. See the resource lifecycle protocol for the cross-package contract and rollout rules.

Session protocol

The session contracts support one claimed bridge, a fixed wallet and authorization ceiling, and one or more strictly ordered signed action turns. One-action workflows use the same protocol with the bounded single_turn_v1 resource profile; interactive and external-work profiles permit only their server-approved turn/deadline budgets. Every operation uses a domain-separated canonical challenge, exact-retry idempotency, and the action input's signed D33 recovery-contract hash.

The package exposes only the session_v1 protocol. The session/, session / session_create, sb1 / sc1, and bridge_session_realm identifiers are its canonical first-release surface. The exact protocol is specified in multiple-actions bridge protocol.

License

MIT