YOP TypeScript SDK (@yeepay/yop-typescript-sdk)

阅读中文文档

A TypeScript SDK designed for seamless interaction with the YOP (YeePay Open Platform) API. This SDK is built using modern JavaScript features, leveraging ES Modules and the native fetch API for optimal performance and compatibility.

Overview

This SDK provides a convenient way to integrate YeePay payment and other services into your TypeScript or JavaScript applications. It handles request signing, signature verification, and API communication, allowing you to focus on your application logic.

Key Features:

• TypeScript First: Fully typed for better developer experience and safety.
• ES Modules: Modern module system for better tree-shaking and compatibility.
• Native fetch: Uses the standard Fetch API, available in Node.js (v18+) and modern browsers.
• Secure: Implements YOP API's RSA signature requirements with UTF-8 support for international characters.
• Flexible: Supports both application/x-www-form-urlencoded and application/json request types.

Installation

Install the package using your preferred package manager:

npm install @yeepay/yop-typescript-sdk
# or
yarn add @yeepay/yop-typescript-sdk
# or
pnpm add @yeepay/yop-typescript-sdk

Configuration

The YopClient can be configured in two ways:

1. Via Environment Variables (Recommended for simplicity): If no configuration object is passed to the constructor, the SDK will automatically attempt to load the required configuration from the following environment variables:

   • YOP_APP_KEY: (Required) Your YeePay Application Key.
   • YOP_APP_PRIVATE_KEY: (Required) Your application's private key (raw string, PEM format PKCS#1 or PKCS#8). The SDK will automatically format the key if it's not already in PEM format. Keep this secure!
   • YOP_PUBLIC_KEY: (Required) The YeePay platform's public key (raw string, PEM format). This is the key content, not a file path. Download from the YeePay developer portal.
   • YOP_API_BASE_URL: (Optional) The base URL for the YeePay API. Defaults to production (https://openapi.yeepay.com).

   Example .env file:

   YOP_APP_KEY=your_app_key
   YOP_APP_PRIVATE_KEY='-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----'
   YOP_PUBLIC_KEY='-----BEGIN PUBLIC KEY-----\n...\n-----END PUBLIC KEY-----'
   # YOP_API_BASE_URL=https://sandbox.yeepay.com # Optional for sandbox

   Example Initialization:

   import { YopClient } from '@yeepay/yop-typescript-sdk';
   import dotenv from 'dotenv';
   
   // Load environment variables (e.g., from a .env file)
   dotenv.config();
   
   // Initialize YopClient using environment variables
   try {
     // No config object passed, SDK uses environment variables
     const yopClient = new YopClient();
     console.log('YopClient initialized successfully using environment variables!');
     // Use yopClient for API calls...
   } catch (error) {
     console.error('Failed to initialize YopClient from environment variables:', error);
     // Ensure all required environment variables (YOP_APP_KEY, YOP_APP_PRIVATE_KEY, YOP_PUBLIC_KEY) are set.
   }

2. Via Explicit YopConfig Object: You can explicitly pass a configuration object to the YopClient constructor. This method takes precedence if both environment variables and a config object are provided (values in the object override corresponding environment variables).

   Example Initialization:

   import { YopClient } from '@yeepay/yop-typescript-sdk';
   import type { YopConfig } from '@yeepay/yop-typescript-sdk';
   import dotenv from 'dotenv'; // Still useful for loading parts of the config
   
   dotenv.config(); // Load any potential fallbacks or other env vars
   
   // Prepare the configuration object explicitly
   const yopConfig: YopConfig = {
     appKey: process.env.MY_CUSTOM_APP_KEY || 'defaultAppKey', // Example: Using different env var or default
     appPrivateKey: process.env.MY_SECRET_KEY!, // Example: Sourcing from a specific variable
     yopPublicKey: process.env.YOP_PUBLIC_KEY!, // Can still load from standard env var if desired
     // yeepayApiBaseUrl: 'https://sandbox.yeepay.com' // Example: Overriding the base URL
   };
   
   // Create a YopClient instance with the explicit config
   const yopClient = new YopClient(yopConfig);
   
   console.log('YopClient initialized successfully with explicit config!');

Configuration Options (when using YopConfig object):

These options are used when you pass a configuration object to the YopClient constructor. If an option is omitted from the object, the SDK will attempt to fall back to the corresponding environment variable.

• appKey (string, required): Your unique application identifier provided by YeePay. (Falls back to process.env.YOP_APP_KEY).
• appPrivateKey (string, required): Your application's private key (in PEM format, as a raw string). The SDK will automatically format the key if it's not already in PEM format. Keep this secure! (Falls back to process.env.YOP_APP_PRIVATE_KEY).
• yopPublicKey (string, required): The YeePay platform's public key (in PEM format, as a raw string) used to verify responses. This must be the key content, not a file path. (Falls back to process.env.YOP_PUBLIC_KEY).
• yeepayApiBaseUrl (string, optional): The base URL for the YeePay API. (Falls back to process.env.YOP_API_BASE_URL, then defaults to https://openapi.yeepay.com).

Usage / Quick Start

Once the YopClient is configured, you can make API calls using its methods.

Example: Creating a Pre-payment Order

import type { YopResponse } from "@yeepay/yop-typescript-sdk";
// Assuming yopClient is already configured and initialized as shown above

async function createPayment() {
  const paymentData = {
    parentMerchantNo: process.env.YOP_PARENT_MERCHANT_NO!, // Your parent merchant number
    merchantNo: process.env.YOP_MERCHANT_NO!, // Your merchant number
    orderId: `SDK_TEST_${Date.now()}`, // Unique order ID
    orderAmount: "0.01", // Amount as string
    goodsName: "SDK Test Product", // Supports UTF-8 characters (e.g., Chinese)
    notifyUrl: process.env.YOP_NOTIFY_URL!, // URL for receiving payment notifications
    userIp: "127.0.0.1", // End-user's IP address
    scene: "ONLINE", // Transaction scene
    channel: "WECHAT", // Payment channel
    // ... include any other necessary fields required by the specific API endpoint
  };

  try {
    console.log("Sending pre-pay request:", paymentData);
    // Use post() for default 'application/x-www-form-urlencoded' requests
    const response = await yopClient.post<YopResponse>(
      "/rest/v1.0/aggpay/pre-pay",
      paymentData
    );
    console.log("Received pre-pay response:", response);

    if (response.state === "SUCCESS" && response.result?.code === "00000") {
      console.log("Pre-pay successful:", response.result);
      // Process successful response: extract prePayTn, orderId, etc.
      // const prePayTn = response.result.prePayTn;
    } else {
      // Handle API errors or unsuccessful states
      const errorInfo =
        response.state === "FAILURE" ? response.error : response.result;
      console.error("Pre-pay failed:", errorInfo);
    }
  } catch (error) {
    // Handle network errors or issues during the request/response process
    console.error("Error during pre-pay request execution:", error);
  }
}

createPayment();

Example: Querying a Payment Order

import type { YopResponse } from "@yeepay/yop-typescript-sdk";
// Assuming yopClient is already configured and initialized

async function queryPayment(orderId: string) {
  const queryData = {
    parentMerchantNo: process.env.YOP_PARENT_MERCHANT_NO!,
    merchantNo: process.env.YOP_MERCHANT_NO!,
    orderId: orderId, // The ID of the order you want to query
    // queryType: 'PAYMENT', // Example: Specify query type if needed
  };

  try {
    console.log("Sending query request for order:", orderId);
    // Use get() for GET requests
    const response = await yopClient.get<YopResponse>(
      "/rest/v1.0/trade/order/query",
      queryData
    );
    console.log("Received query response:", response);

    if (response.state === "SUCCESS" && response.result?.code === "00000") {
      console.log("Query successful:", response.result);
      // Process the order details: response.result.status, response.result.orderAmount etc.
    } else {
      const errorInfo =
        response.state === "FAILURE" ? response.error : response.result;
      console.error("Query failed:", errorInfo);
    }
  } catch (error) {
    console.error("Error during query request execution:", error);
  }
}

// Example call: Replace with an actual order ID
// queryPayment('SDK_TEST_1678886400000');

API Reference

new YopClient(config: YopConfig)

Creates and initializes a new YOP client instance.

• config: A YopConfig object containing your credentials and settings. See Configuration and src/types.ts.

yopClient.get<T>(apiUrl: string, params: Record<string, any>, timeout?: number): Promise<T>

Sends an HTTP GET request to the specified YOP API endpoint.

• apiUrl: The API path relative to the yeepayApiBaseUrl (e.g., /rest/v1.0/trade/order/query).
• params: An object containing the query parameters for the request.
• timeout (optional): Request timeout in milliseconds.
• Returns: A Promise that resolves with the parsed API response of type T.

yopClient.post<T>(apiUrl: string, body: Record<string, any>, contentType?: ContentType, timeout?: number): Promise<T>

Sends an HTTP POST request to the specified YOP API endpoint. Defaults to application/x-www-form-urlencoded content type.

• apiUrl: The API path relative to the yeepayApiBaseUrl.
• body: An object containing the data to be sent in the request body.
• contentType (optional): The content type of the request. Defaults to ContentType.FORM_URLENCODED. Use ContentType.JSON for JSON payloads (or use postJson).
• timeout (optional): Request timeout in milliseconds.
• Returns: A Promise that resolves with the parsed API response of type T.

yopClient.postJson<T>(apiUrl: string, body: Record<string, any>, timeout?: number): Promise<T>

A convenience method for sending an HTTP POST request with application/json content type.

• apiUrl: The API path relative to the yeepayApiBaseUrl.
• body: An object containing the data to be sent as JSON in the request body.
• timeout (optional): Request timeout in milliseconds.
• Returns: A Promise that resolves with the parsed API response of type T.

Types

Detailed type definitions for configuration (YopConfig), responses (YopResponse), errors, and content types can be found in src/types.ts.

Contributing

Contributions are highly welcome! We appreciate your help in improving the SDK. Here's how you can contribute:

Reporting Bugs:

• If you find a bug, please check the Issues section to see if it has already been reported.
• If not, open a new issue. Provide a clear title, a detailed description of the bug, steps to reproduce it, and the expected vs. actual behavior. Include relevant code snippets or error messages if possible.

Suggesting Enhancements:

• If you have an idea for a new feature or an improvement to an existing one, open a new issue.
• Clearly describe the proposed enhancement, its use case, and why it would be beneficial.

Pull Requests:

1. Fork the repository: Click the "Fork" button on the top right of the repository page.
2. Clone your fork: git clone https://github.com/yop-platform/yop-typescript-sdk.git
3. Create a branch: git checkout -b feature/your-feature-name or bugfix/issue-number.
4. Make your changes: Implement your feature or fix the bug.
5. Add/Update Tests: Ensure your changes are covered by tests. Add new tests if necessary.
6. Run Tests: Make sure all tests pass: npm test
7. Lint Code: Ensure your code adheres to the project's style guidelines: npm run lint (fix any reported issues).
8. Commit your changes: git commit -m "feat: Describe your feature" -m "Detailed description..." (Follow conventional commit messages if applicable).
9. Push to your fork: git push origin feature/your-feature-name
10. Open a Pull Request: Go to the original repository and click "New pull request". Compare your branch with the main branch of the original repository.
11. Describe your PR: Provide a clear title and description of your changes in the Pull Request. Link to any relevant issues (e.g., "Closes #123").

We will review your contribution as soon as possible. Thank you for contributing!

License

This project is licensed under the MIT License.