superqi

Promise-based wrappers for the Alipay mini-app my bridge API.

What it does

Alipay mini-app platform APIs use a callback style (success/fail). superqi wraps them so you can use async/await instead:

// Without superqi
my.getAuthCode({
  scopes: ['auth_base'],
  success: (res) => console.log(res.authCode),
  fail: (res) => console.error(res.authErrorScopes),
});

// With superqi
const code = await getAuthCode(['auth_base']);

Requirements

• Must run inside an Alipay mini-app environment (the my global must be present at runtime)
• Load the hylid-bridge script before calling any function

Installation

npm install superqi
# or
bun add superqi
# or
yarn add superqi

Setup

Load the bridge script in your HTML entry point:

<script src="https://cdn.marmot-cloud.com/npm/hylid-bridge/2.10.0/index.js"></script>

This injects the my global that all superqi functions rely on.

Usage

getAuthCode

Request an authorization code for one or more scopes. Used for OAuth-style authentication flows.

import { getAuthCode } from 'superqi';

const code = await getAuthCode(['auth_base', 'auth_user']);
// send `code` to your backend to exchange for an access token

Rejects with an Error whose message is the authErrorScopes string returned by the platform.

chooseImage

Open the device image picker or camera so the user can select one or more images.

import { chooseImage } from 'superqi';

const { apFilePaths } = await chooseImage({
  sizeType: ['original', 'compressed'],
  sourceType: ['album', 'camera'],
});

console.log(apFilePaths); // ['apfile://...', ...]

Both options are optional. Rejects with an Error whose message is the platform errorMessage.

tradePay

Initiate an Alipay payment. Takes the payment URL returned by your server.

import { tradePay } from 'superqi';

const result = await tradePay('https://your-server.com/pay?orderStr=...');
// result shape is platform-specific

Returns Promise<any> because the platform response shape varies by payment method. Rejects with the raw platform error object.

alert

Display a native alert dialog. Synchronous — no await needed.

import { alert } from 'superqi';

alert('Payment successful');

setClipboard

Copy text to the device clipboard. Synchronous — no await needed.

import { setClipboard } from 'superqi';

setClipboard('text to copy');

canIUse

Check whether a platform feature is available before calling it. Returns boolean.

import { canIUse, chooseImage } from 'superqi';

if (canIUse('chooseImage')) {
  const { apFilePaths } = await chooseImage();
}

getLocation

Get the user's current GPS coordinates.

import { getLocation } from 'superqi';

const { longitude, latitude, accuracy } = await getLocation();
// accuracy is in meters

Pass cacheTimeout (seconds) to reuse a recent fix instead of re-acquiring:

const loc = await getLocation({ cacheTimeout: 60 });

Rejects with an Error whose message is the platform errorMessage.

openLocation

Open the map to display a specific coordinate. longitude and latitude are required.

import { openLocation } from 'superqi';

await openLocation({
  longitude: '120.126293',
  latitude: '30.274653',
  name: 'West Lake',
  address: 'Xihu District, Hangzhou',
  scale: 15, // zoom 3–19, default 15
});

Rejects with an Error whose message is the platform errorMessage.

scan

Open the built-in QR / barcode scanner.

import { scan } from 'superqi';

const result = await scan({ type: 'qr' }); // 'qr' (default) or 'bar'
console.log(result.code); // scanned value

Set hideAlbum: true to force camera-only scanning (no image picker):

const result = await scan({ hideAlbum: true });

Rejects with an Error whose message is the platform errorMessage.

makePhoneCall

Open the system dialer with a pre-filled number.

import { makePhoneCall } from 'superqi';

await makePhoneCall('+966500000000');

Note: Not supported in the Mini Program Studio simulator — test on a real device.

Rejects with an Error whose message is the platform errorMessage.

API Reference

| Function | Signature | Returns | Description | | --------------- | ---------------------------------------------------------------------- | ----------------------------------- | --------------------------- | | getAuthCode | (scopes: AuthScope[]) => Promise<string> | Auth code string | Request user authorization | | chooseImage | (options?: ChooseImageOptions) => Promise<{ apFilePaths: string[] }> | File paths | Open image picker | | tradePay | (paymentUrl: string) => Promise<any> | Platform response | Initiate Alipay payment | | getLocation | (options?: GetLocationOptions) => Promise<GetLocationResult> | { longitude, latitude, accuracy } | Get current GPS coordinates | | openLocation | (options: OpenLocationOptions) => Promise<void> | — | Open map at coordinates | | scan | (options?: ScanOptions) => Promise<ScanResult> | { code, qrCode, barCode } | Scan QR code or barcode | | makePhoneCall | (number: string) => Promise<void> | — | Open dialer with number | | alert | (content: string) => void | — | Show native alert | | setClipboard | (text: string) => void | — | Copy to clipboard | | canIUse | (feature: string) => boolean | true if available | Check feature support |

Types

AuthScope

type AuthScope =
  | 'auth_base' // Basic authentication (no user info)
  | 'auth_user' // Basic user profile
  | 'USER_ID' // User's unique ID
  | 'USER_LOGIN_ID' // User's login ID
  | 'HASH_LOGIN_ID' // Hashed login ID
  | 'USER_NAME' // Display name
  | 'USER_AVATAR' // Avatar image URL
  | 'USER_GENDER' // Gender
  | 'USER_BIRTHDAY' // Date of birth
  | 'USER_NATIONALITY' // Nationality
  | 'USER_CONTACTINFO' // Contact information
  | 'NOTIFICATION_INBOX' // Inbox notification access
  | 'AGREEMENT_PAY'; // Agreement-based payment

ChooseImageOptions

interface ChooseImageOptions {
  sizeType?: string[]; // e.g. ['original', 'compressed']
  sourceType?: string[]; // e.g. ['album', 'camera']
}

Both fields are optional. When omitted the platform uses its own defaults.

GetLocationOptions

interface GetLocationOptions {
  cacheTimeout?: number; // seconds to reuse a cached fix, default 30
  type?: number; // 0 = longitude/latitude (default)
}

GetLocationResult

interface GetLocationResult {
  longitude: string;
  latitude: string;
  accuracy: string; // metres
}

OpenLocationOptions

interface OpenLocationOptions {
  longitude: string; // required
  latitude: string; // required
  name: string; // required
  address: string; // required
  scale?: number; // map zoom 3–19, default 15
}

ScanOptions

interface ScanOptions {
  type?: 'qr' | 'bar'; // default 'qr'
  hideAlbum?: boolean; // true = camera only, default false
}

ScanResult

interface ScanResult {
  code: string; // generic scanned value
  qrCode: string; // set when type is 'qr'
  barCode: string; // set when type is 'bar'
}

Error Handling

All promise-based functions reject with an Error whose message is the platform errorMessage, except tradePay which rejects with the raw platform error object.

| Function | Rejection value | | --------------- | --------------------------------------------- | | getAuthCode | Error with authErrorScopes as the message | | chooseImage | Error with the platform errorMessage | | tradePay | Raw platform error object | | getLocation | Error with the platform errorMessage | | openLocation | Error with the platform errorMessage | | scan | Error with the platform errorMessage | | makePhoneCall | Error with the platform errorMessage |

Recommended pattern:

try {
  const code = await getAuthCode(['auth_base']);
  // use code
} catch (err) {
  console.error('Auth failed:', err);
}