@near-mobile/connector

Public client library for the Near Mobile Connector: create requests, poll for responses, build deep-link URLs, and generate QR codes for wallet connections.

Installation

npm install @near-mobile/connector
yarn add @near-mobile/connector
pnpm install @near-mobile/connector
bun add @near-mobile/connector

Overview

This package lets you:

• Create and poll requests against the Near Mobile Connector API
• Build URLs for opening the Near Mobile Wallet (mobile deep-link or universal link)
• Generate QR codes that encode the request URL for wallet scanning (optional strategy)

Usage

Creating and polling a request

import { NearMobileConnector } from "@near-mobile/connector";

// Create a new connector request (payload depends on your API)
const request = await NearMobileConnector.createRequest({
    // ... your request body
});

const id = request.id;

// Poll until the user completes the action in the wallet
const completedRequest = await NearMobileConnector.pollResponse(id);

// Use completedRequest.status and response data

Building request URLs

Use these URLs to open the wallet (e.g. in a “Open in app” button or redirect):

import { buildNearMobileAppRequestUrl, buildNearMobileUniversalRequestUrl } from "@near-mobile/connector";

const requestId = "your-request-id";

// Mobile deep-link (near-mobile-wallet://request?id=...)
const mobileUrl = buildNearMobileAppRequestUrl(requestId);

// Universal URL (works on web and can redirect to app when installed)
const universalUrl = buildNearMobileUniversalRequestUrl(requestId);

QR code strategy

Generate a QR code that encodes the mobile request URL so users can scan it with the wallet app:

import { NearMobileQrCode } from "@near-mobile/connector/strategies/qr-code";

const qr = new NearMobileQrCode({
    requestId: "your-request-id",
    // ... other qr-code-styling options (except data, image, imageOptions)
});

// Append SVG to DOM
const container = document.getElementById("qr-container");
qr.append(container);

// Or get as blob for download
const blob = await qr.download({ name: "qr", extension: "png" });

NearMobileQrCode extends qr-code-styling; you can pass any of its options (except data, image, and imageOptions, which are set from the package config).

API

| Export | Description | | ------------------------------------------------ | ----------------------------------------------- | | NearMobileConnector.createRequest(body) | Create a new connector request. | | NearMobileConnector.getRequest(id) | Fetch a request by ID. | | NearMobileConnector.pollResponse(id, options?) | Poll a request until it is no longer pending. | | buildNearMobileAppRequestUrl(id) | Build the mobile deep-link URL for a request. | | buildNearMobileUniversalRequestUrl(id) | Build the universal request URL. |

QR Code Strategy

| Export | Description | | --------------------------------------------------------------------- | -------------------------------------------------- | | NearMobileQrCode (from @near-mobile/connector/strategies/qr-code) | QR code class that encodes the mobile request URL. |

License

MIT © Peersyst