npm package: @near-mobile/connector
Description: Public client for the Near Mobile Connector: create requests, poll for responses, build deep-link URLs, and generate QR codes for wallet connections.
Author: Peersyst
Latest version: 0.0.4

# @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

```bash
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

```ts
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):

```ts
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:

```ts
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](https://github.com/kozakdenys/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