@youidian/sdk 3.0.0

package/dist/server.d.cts

@@ -0,0 +1,385 @@
+/**
+ * Youidian Payment SDK - Server Module
+ * 用于服务端集成，包含签名、订单创建、回调解密等功能
+ */
+/**
+ * Order status response
+ */
+interface OrderStatus {
+    orderId: string;
+    status: "PENDING" | "PAID" | "CANCELLED" | "REFUNDED" | "FAILED";
+    paidAt?: string;
+    channelTransactionId?: string;
+}
+/**
+ * Order details response (full order information)
+ */
+interface OrderDetails {
+    orderId: string;
+    internalId: string;
+    status: "PENDING" | "PAID" | "CANCELLED" | "REFUNDED" | "FAILED";
+    amount: number;
+    currency: string;
+    description?: string;
+    paidAt?: string;
+    createdAt: string;
+    channel?: string;
+    product?: {
+        code: string;
+        type: string;
+        name: string;
+        description?: string;
+        entitlements: ProductEntitlements;
+        metadata?: ProductMetadata | null;
+    };
+}
+/**
+ * Product Entitlements
+ */
+interface ProductEntitlements {
+    [key: string]: any;
+}
+/**
+ * Product Price
+ */
+interface ProductPrice {
+    id: string;
+    currency: string;
+    amount: number;
+    displayAmount: string;
+    locale: string | null;
+    isDefault: boolean;
+}
+interface ProductSubscriptionPeriod {
+    value: number;
+    unit: "days" | "months" | "years";
+}
+interface ProductResetRule {
+    resetInterval: "month";
+}
+interface ProductMetadata {
+    subscriptionPeriod?: ProductSubscriptionPeriod;
+    expiringEntitlements?: string[];
+    resetEntitlements?: Record<string, ProductResetRule>;
+    autoAssignOnNewUser?: boolean;
+    trialDurationDays?: number;
+}
+/**
+ * Product Data
+ */
+interface Product {
+    id: string;
+    code: string;
+    type: string;
+    name: string;
+    description?: string;
+    entitlements: ProductEntitlements;
+    prices: ProductPrice[];
+    metadata?: ProductMetadata | null;
+}
+/**
+ * WeChat JSAPI Payment Parameters (for wx.requestPayment)
+ */
+interface WechatJsapiPayParams {
+    appId: string;
+    timeStamp: string;
+    nonceStr: string;
+    package: string;
+    signType: "RSA";
+    paySign: string;
+}
+/**
+ * Verified hosted login token payload.
+ */
+interface VerifiedLoginToken {
+    appId: string;
+    userId: string;
+    legacyCasdoorId?: string | null;
+    channel: string;
+    email?: string | null;
+    name?: string | null;
+    avatar?: string | null;
+    wechatOpenId?: string | null;
+    wechatUnionId?: string | null;
+    expiresAt: string;
+}
+/**
+ * SDK Client Options
+ */
+interface PaymentClientOptions {
+    /** Application ID (Required) */
+    appId: string;
+    /** Application Secret (Required for server-side operations) */
+    appSecret: string;
+    /**
+     * @deprecated Use apiUrl and checkoutUrl instead
+     * API Base URL (e.g. https://pay.youidian.com)
+     * If apiUrl or checkoutUrl is not provided, this will be used as fallback
+     * Default: https://pay.imgto.link
+     */
+    baseUrl?: string;
+    /**
+     * API server URL for backend requests (e.g. https://api.youidian.com)
+     * Default: https://pay-api.imgto.link
+     */
+    apiUrl?: string;
+    /**
+     * Checkout page URL for client-side payment (e.g. https://pay.youidian.com)
+     * Default: https://pay.imgto.link
+     */
+    checkoutUrl?: string;
+}
+/**
+ * Create Order Parameters
+ */
+interface CreateOrderParams {
+    productId?: string;
+    priceId?: string;
+    channel?: string;
+    userId: string;
+    returnUrl?: string;
+    metadata?: Record<string, any>;
+    merchantOrderId?: string;
+    openid?: string;
+    locale?: string;
+}
+/**
+ * Create WeChat Mini Program Order Parameters
+ */
+type CreateMiniProgramOrderParams = {
+    userId: string;
+    openid: string;
+    merchantOrderId?: string;
+    priceId: string;
+};
+/**
+ * Create Order Response
+ */
+interface CreateOrderResponse {
+    orderId: string;
+    internalId: string;
+    amount: number;
+    currency: string;
+    payParams: any;
+}
+/**
+ * Payment Callback Notification
+ */
+interface PaymentNotification {
+    iv: string;
+    encryptedData: string;
+    authTag: string;
+}
+/**
+ * Decrypted Payment Callback Data
+ */
+interface PaymentCallbackData {
+    orderId: string;
+    merchantOrderId?: string;
+    status: "PAID" | "CANCELLED" | "REFUNDED" | "FAILED";
+    amount: number;
+    currency: string;
+    paidAt: string;
+    channelTransactionId?: string;
+    metadata?: Record<string, any>;
+}
+/**
+ * Get Orders Parameters
+ */
+interface GetOrdersParams {
+    page?: number;
+    pageSize?: number;
+    userId?: string;
+    status?: "PENDING" | "PAID" | "CANCELLED" | "REFUNDED" | "FAILED";
+    startDate?: string;
+    endDate?: string;
+}
+/**
+ * Order List Item
+ */
+interface OrderListItem {
+    orderId: string;
+    internalId: string;
+    merchantUserId: string;
+    status: "PENDING" | "PAID" | "CANCELLED" | "REFUNDED" | "FAILED";
+    amount: number;
+    currency: string;
+    channel?: string;
+    paidAt?: string;
+    createdAt: string;
+}
+/**
+ * Get Orders Response
+ */
+interface GetOrdersResponse {
+    orders: OrderListItem[];
+    pagination: {
+        total: number;
+        page: number;
+        pageSize: number;
+        totalPages: number;
+    };
+}
+/**
+ * Entitlement Detail Item
+ */
+interface EntitlementDetailItem {
+    type: string;
+    current: number | boolean;
+    limit?: number;
+    expiresAt?: string | null;
+    resetInterval?: string | null;
+    nextResetAt?: string | null;
+    sourceKind?: string | null;
+}
+/**
+ * Entitlement Detail - returned by getEntitlementsDetail
+ */
+type EntitlementDetail = Record<string, EntitlementDetailItem>;
+/**
+ * Ensure User With Trial Response
+ */
+interface EnsureUserWithTrialResponse {
+    isNew: boolean;
+    trialAssigned: boolean;
+    trialProductCode?: string;
+    entitlements: EntitlementDetail;
+}
+/**
+ * Server-side Payment Client
+ * 服务端支付客户端，用于创建订单、查询状态、解密回调
+ */
+declare class PaymentClient {
+    private readonly appId;
+    private readonly appSecret;
+    private readonly apiUrl;
+    private readonly checkoutUrl;
+    constructor(options: PaymentClientOptions);
+    /**
+     * Generate SHA256 signature for the request
+     * Logic: SHA256(appId + appSecret + timestamp)
+     */
+    private generateSignature;
+    /**
+     * Internal request helper for Gateway API
+     */
+    private request;
+    /**
+     * Decrypts the callback notification payload using AES-256-GCM.
+     * @param notification - The encrypted notification from payment webhook
+     * @returns Decrypted payment callback data
+     */
+    decryptCallback(notification: PaymentNotification): PaymentCallbackData;
+    /**
+     * Fetch products for the configured app.
+     */
+    getProducts(options?: {
+        locale?: string;
+        currency?: string;
+    }): Promise<Product[]>;
+    /**
+     * Create a new order
+     * @param params - Order creation parameters
+     * @returns Order details with payment parameters
+     */
+    createOrder(params: CreateOrderParams): Promise<CreateOrderResponse>;
+    /**
+     * Create a WeChat Mini Program order (channel fixed to WECHAT_MINI)
+     * @param params - Mini program order parameters
+     * @returns Order details with payment parameters
+     */
+    createMiniProgramOrder(params: CreateMiniProgramOrderParams): Promise<CreateOrderResponse>;
+    /**
+     * Pay for an existing order
+     * @param orderId - The order ID to pay
+     * @param params - Payment parameters including channel
+     */
+    payOrder(orderId: string, params: {
+        channel: string;
+        returnUrl?: string;
+        openid?: string;
+        [key: string]: any;
+    }): Promise<CreateOrderResponse>;
+    /**
+     * Query order status
+     * @param orderId - The order ID to query
+     */
+    getOrderStatus(orderId: string): Promise<OrderStatus>;
+    /**
+     * Get order details (full order information)
+     * @param orderId - The order ID to query
+     */
+    getOrderDetails(orderId: string): Promise<OrderDetails>;
+    /**
+     * Get orders list with pagination
+     * @param params - Query parameters (pagination, filters)
+     * @returns Orders list and pagination info
+     */
+    getOrders(params?: GetOrdersParams): Promise<GetOrdersResponse>;
+    /**
+     * Get user entitlements in the legacy flat shape.
+     * @param userId - User ID
+     */
+    getEntitlements(userId: string): Promise<Record<string, any>>;
+    /**
+     * Get user entitlements with full details (type, expiry, reset config, source)
+     * @param userId - User ID
+     */
+    getEntitlementsDetail(userId: string): Promise<EntitlementDetail>;
+    /**
+     * Ensure user exists and auto-assign trial product if new user
+     * This should be called when user first logs in or registers
+     * @param userId - User ID
+     */
+    ensureUserWithTrial(userId: string): Promise<EnsureUserWithTrialResponse>;
+    /**
+     * Get a single entitlement value
+     * @param userId - User ID
+     * @param key - Entitlement key
+     */
+    getEntitlementValue(userId: string, key: string): Promise<any>;
+    /**
+     * Consume numeric entitlement
+     * @param userId - User ID
+     * @param key - Entitlement key
+     * @param amount - Amount to consume
+     */
+    consumeEntitlement(userId: string, key: string, amount: number, options?: {
+        idempotencyKey?: string;
+        metadata?: Record<string, any>;
+    }): Promise<{
+        balance: number;
+    }>;
+    /**
+     * Add numeric entitlement (e.g. refund)
+     * @param userId - User ID
+     * @param key - Entitlement key
+     * @param amount - Amount to add
+     */
+    addEntitlement(userId: string, key: string, amount: number): Promise<{
+        balance: number;
+    }>;
+    /**
+     * Toggle boolean entitlement
+     * @param userId - User ID
+     * @param key - Entitlement key
+     * @param enabled - Whether to enable
+     */
+    toggleEntitlement(userId: string, key: string, enabled: boolean): Promise<{
+        isEnabled: boolean;
+    }>;
+    /**
+     * Generate checkout URL for client-side payment
+     * @param productId - Product ID
+     * @param priceId - Price ID
+     * @returns Checkout page URL
+     */
+    getCheckoutUrl(productId: string, priceId: string): string;
+    /**
+     * Verify a hosted login token and return the normalized login profile.
+     * This request is signed with your app credentials and routed through the worker API.
+     */
+    verifyLoginToken(token: string): Promise<VerifiedLoginToken>;
+}
+
+export { type CreateMiniProgramOrderParams, type CreateOrderParams, type CreateOrderResponse, type EnsureUserWithTrialResponse, type EntitlementDetail, type EntitlementDetailItem, type GetOrdersParams, type GetOrdersResponse, type OrderDetails, type OrderListItem, type OrderStatus, type PaymentCallbackData, PaymentClient, type PaymentClientOptions, type PaymentNotification, type Product, type ProductEntitlements, type ProductMetadata, type ProductPrice, type ProductResetRule, type ProductSubscriptionPeriod, type VerifiedLoginToken, type WechatJsapiPayParams };