Frontend

Typescript

Typescript types to allow easy use of the Frontend

Setup TypeScript Definitions

To get proper TypeScript support for SuperQi's mobile API, you need to create a type definition file in your project.

Create Type Definition File

Create a file named superqi-v1.d.ts in your src directory:

// filepath: src/superqi-v1.d.ts
/**
 * Auth scopes for SuperQi integration
 * Silent = true: auth_base, USER_ID, USER_LOGIN_ID, HASH_LOGIN_ID
 * Silent = false: auth_user, USER_NAME, USER_AVATAR, USER_GENDER, USER_BIRTHDAY, USER_NATIONALITY, USER_CONTACTINFO, NOTIFICATION_INBOX, AGREEMENT_PAY, CARD_LIST
 */
type AuthScope =
    | "auth_base" // Authorized to obtain the unique user ID. Silent: Yes
    | "USER_ID" // Authorized to obtain the unique user ID. Silent: Yes
    | "USER_LOGIN_ID" // Authorized to obtain the user's login ID. Silent: Yes
    | "HASH_LOGIN_ID" // Authorized to obtain the hash user login ID. Silent: Yes
    | "auth_user" // Authorized to obtain the basic user information. Silent: No
    | "USER_NAME" // Authorized to obtain the user name. Silent: No
    | "USER_AVATAR" // Authorized to obtain the user avatar. Silent: No
    | "USER_GENDER" // Authorized to obtain the user's gender. Silent: No
    | "USER_BIRTHDAY" // Authorized to obtain the user's birthday. Silent: No
    | "USER_NATIONALITY" // Authorized to obtain the user's nationality. Silent: No
    | "USER_CONTACTINFO" // Authorized to obtain the user's contact information. Silent: No
    | "NOTIFICATION_INBOX" // Authorized to send notification to user's notification in app inbox. Silent: No
    | "AGREEMENT_PAY" // Authorized to debit payment from user's balance or card. Silent: No
    | "CARD_LIST"; // Authorized to fetch the user's cards list. Silent: No;

interface MyApi {
    getAuthCode: (options: {
        scopes: AuthScope[];
        success: (res: { authCode: string }) => void;
        fail: (res: { authErrorScopes: string }) => void;
    }) => void;
    alert: (options: { content: string }) => void;
    tradePay: (options: {
        paymentUrl: string;
        success: (res: any) => void;
        fail: (res: any) => void;
    }) => void;
    // Add other methods as needed
}

// Super Qi Mobile API v1
declare global {
    var my: MyApi;
}

export {};

Auth Scopes

SuperQi provides two types of authorization scopes:

Silent Scopes

These scopes don't require user interaction and are granted automatically:

auth_base - Basic authorization
USER_ID - Unique user identifier
USER_LOGIN_ID - User's login ID
HASH_LOGIN_ID - Hashed user login ID

Interactive Scopes

These scopes require explicit user consent:

auth_user - Basic user information
USER_NAME - User's display name
USER_AVATAR - User's profile picture
USER_GENDER - User's gender
USER_BIRTHDAY - User's birth date
USER_NATIONALITY - User's nationality
USER_CONTACTINFO - Contact information
NOTIFICATION_INBOX - Send notifications
AGREEMENT_PAY - Payment authorization
CARD_LIST - Access to user's payment cards

Usage Example

With the type definitions in place, you can use the SuperQi API with full TypeScript support:

// Request authorization with proper typing
my.getAuthCode({
  scopes: ['USER_ID', 'USER_NAME', 'USER_AVATAR'],
  success: (res) => {
    console.log('Auth code:', res.authCode);
  },
  fail: (res) => {
    console.error('Auth failed:', res.authErrorScopes);
  }
});

// Show alert
my.alert({
  content: 'Hello from your mini-app!'
});

// Handle payment
my.tradePay({
  paymentUrl: 'https://your-backend-payment.url',
  success: (res) => {
    console.log('Payment successful:', res);
  },
  fail: (res) => {
    console.error('Payment failed:', res);
  }
});

Benefits

Type Safety: Get compile-time checks for API calls
IntelliSense: Full autocomplete support in your IDE
Documentation: Inline comments explain each scope's purpose
Error Prevention: Catch typos and invalid scope combinations early

This setup ensures you have proper TypeScript support when developing SuperQi mini-apps.