four-flap-meme-sdk 1.5.55 → 1.5.56

package/dist/sol/dex/jup/send.js

@@ -0,0 +1,295 @@
+/**
+ * Jupiter Send API V1
+ * @module sol/dex/jup/send
+ *
+ * Send API 提供代币发送邀请链接功能
+ * 允许创建邀请链接让他人领取代币
+ */
+import { jupGet, jupPost } from './client.js';
+// ============================================================================
+// Craft Send - 创建发送邀请
+// ============================================================================
+/**
+ * 创建发送邀请交易
+ *
+ * 创建一个邀请链接，让他人可以领取指定数量的代币。
+ *
+ * @param params 创建参数
+ * @param config Jupiter 配置
+ * @returns 创建响应
+ *
+ * @example
+ * ```typescript
+ * import { Sol } from 'four-flap-meme-sdk'
+ * import { Keypair } from '@solana/web3.js'
+ * import crypto from 'crypto'
+ *
+ * Sol.setJupiterConfig({ apiKey: 'your-api-key' })
+ *
+ * // 生成邀请码（客户端生成，安全保管）
+ * const inviteCode = crypto.randomBytes(32).toString('hex')
+ * const inviteHash = crypto.createHash('sha256').update(inviteCode).digest()
+ * const inviteKeypair = Keypair.fromSeed(inviteHash)
+ *
+ * // 创建发送邀请
+ * const result = await Sol.craftSend({
+ *   inviteSigner: inviteKeypair.publicKey.toBase58(),
+ *   sender: wallet.publicKey.toBase58(),
+ *   amount: '1000000', // 1 USDC
+ *   mint: 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v',
+ * })
+ *
+ * console.log(`过期时间: ${new Date(parseInt(result.expiry) * 1000)}`)
+ * console.log(`费用: ${result.totalFeeLamports} lamports`)
+ *
+ * // 签名交易
+ * const tx = VersionedTransaction.deserialize(Buffer.from(result.tx, 'base64'))
+ * tx.sign([wallet, inviteKeypair])
+ *
+ * // 发送交易...
+ * // 保存 inviteCode 分享给接收者
+ * ```
+ */
+export async function craftSend(params, config) {
+    return jupPost('/send/v1/craft-send', params, config);
+}
+/**
+ * 创建 SOL 发送邀请
+ *
+ * @param inviteSigner 邀请签名者公钥
+ * @param sender 发送者地址
+ * @param amountLamports SOL 数量 (lamports)
+ * @param config Jupiter 配置
+ * @returns 创建响应
+ */
+export async function craftSendSol(inviteSigner, sender, amountLamports, config) {
+    return craftSend({
+        inviteSigner,
+        sender,
+        amount: amountLamports.toString(),
+        // 不传 mint 默认为 WSOL
+    }, config);
+}
+/**
+ * 创建 USDC 发送邀请
+ *
+ * @param inviteSigner 邀请签名者公钥
+ * @param sender 发送者地址
+ * @param amountUsdc USDC 数量（原子单位，6位小数）
+ * @param config Jupiter 配置
+ * @returns 创建响应
+ */
+export async function craftSendUsdc(inviteSigner, sender, amountUsdc, config) {
+    return craftSend({
+        inviteSigner,
+        sender,
+        amount: amountUsdc.toString(),
+        mint: 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v',
+    }, config);
+}
+// ============================================================================
+// Craft Clawback - 撤回邀请
+// ============================================================================
+/**
+ * 撤回/取消邀请
+ *
+ * 撤回未领取的邀请，资金返还给发送者。
+ *
+ * @param params 撤回参数
+ * @param config Jupiter 配置
+ * @returns 撤回响应
+ *
+ * @example
+ * ```typescript
+ * // 撤回邀请
+ * const result = await Sol.craftClawback({
+ *   invitePDA: 'invitePDAAddress...',
+ *   sender: wallet.publicKey.toBase58(),
+ * })
+ *
+ * // 签名并发送交易
+ * const tx = VersionedTransaction.deserialize(Buffer.from(result.tx, 'base64'))
+ * tx.sign([wallet])
+ * // 发送交易...
+ * ```
+ */
+export async function craftClawback(params, config) {
+    return jupPost('/send/v1/craft-clawback', params, config);
+}
+// ============================================================================
+// Pending Invites - 待处理邀请
+// ============================================================================
+/**
+ * 获取待处理的邀请
+ *
+ * 获取发送者创建的尚未被领取或撤回的邀请。
+ *
+ * @param address 发送者地址
+ * @param page 页码（默认 1）
+ * @param config Jupiter 配置
+ * @returns 邀请列表响应
+ *
+ * @example
+ * ```typescript
+ * const pending = await Sol.getPendingInvites(
+ *   wallet.publicKey.toBase58(),
+ *   1,
+ * )
+ *
+ * console.log(`待处理邀请: ${pending.invites.length}`)
+ * pending.invites.forEach(invite => {
+ *   console.log(`金额: ${invite.amount}`)
+ *   console.log(`过期: ${new Date(parseInt(invite.expiry) * 1000)}`)
+ * })
+ * ```
+ */
+export async function getPendingInvites(address, page = 1, config) {
+    return jupGet('/send/v1/pending-invites', { address, page }, config);
+}
+/**
+ * 获取所有待处理邀请（自动分页）
+ *
+ * @param address 发送者地址
+ * @param config Jupiter 配置
+ * @returns 所有待处理邀请
+ */
+export async function getAllPendingInvites(address, config) {
+    const allInvites = [];
+    let page = 1;
+    while (true) {
+        const response = await getPendingInvites(address, page, config);
+        allInvites.push(...response.invites);
+        if (!response.hasMoreData)
+            break;
+        page++;
+    }
+    return allInvites;
+}
+// ============================================================================
+// Invite History - 邀请历史
+// ============================================================================
+/**
+ * 获取邀请历史
+ *
+ * 获取地址相关的所有邀请历史（作为发送者或接收者）。
+ *
+ * @param address 地址（发送者或接收者）
+ * @param page 页码（默认 1）
+ * @param config Jupiter 配置
+ * @returns 邀请列表响应
+ *
+ * @example
+ * ```typescript
+ * const history = await Sol.getInviteHistory(
+ *   wallet.publicKey.toBase58(),
+ *   1,
+ * )
+ *
+ * console.log(`邀请历史: ${history.invites.length}`)
+ * history.invites.forEach(invite => {
+ *   console.log(`${invite.action}: ${invite.amount}`)
+ *   console.log(`  发送者: ${invite.sender}`)
+ *   console.log(`  接收者: ${invite.receiver}`)
+ * })
+ * ```
+ */
+export async function getInviteHistory(address, page = 1, config) {
+    return jupGet('/send/v1/invite-history', { address, page }, config);
+}
+/**
+ * 获取所有邀请历史（自动分页）
+ *
+ * @param address 地址
+ * @param config Jupiter 配置
+ * @returns 所有邀请历史
+ */
+export async function getAllInviteHistory(address, config) {
+    const allInvites = [];
+    let page = 1;
+    while (true) {
+        const response = await getInviteHistory(address, page, config);
+        allInvites.push(...response.invites);
+        if (!response.hasMoreData)
+            break;
+        page++;
+    }
+    return allInvites;
+}
+// ============================================================================
+// 便捷方法
+// ============================================================================
+/**
+ * 获取待处理邀请总金额
+ *
+ * @param address 发送者地址
+ * @param config Jupiter 配置
+ * @returns 总金额（按 mint 分组）
+ */
+export async function getPendingInvitesTotal(address, config) {
+    const invites = await getAllPendingInvites(address, config);
+    const totals = new Map();
+    invites.forEach(invite => {
+        const mint = invite.mint || 'So11111111111111111111111111111111111111112';
+        const current = totals.get(mint) || BigInt(0);
+        totals.set(mint, current + BigInt(invite.amount));
+    });
+    return totals;
+}
+/**
+ * 获取即将过期的邀请
+ *
+ * @param address 发送者地址
+ * @param withinHours 在多少小时内过期（默认 24）
+ * @param config Jupiter 配置
+ * @returns 即将过期的邀请
+ */
+export async function getExpiringInvites(address, withinHours = 24, config) {
+    const invites = await getAllPendingInvites(address, config);
+    const now = Math.floor(Date.now() / 1000);
+    const cutoff = now + (withinHours * 3600);
+    return invites.filter(invite => {
+        const expiry = parseInt(invite.expiry);
+        return expiry <= cutoff && expiry > now;
+    });
+}
+/**
+ * 检查邀请是否已过期
+ *
+ * @param invite 邀请信息
+ * @returns 是否已过期
+ */
+export function isInviteExpired(invite) {
+    const now = Math.floor(Date.now() / 1000);
+    return parseInt(invite.expiry) <= now;
+}
+/**
+ * 获取邀请剩余时间（秒）
+ *
+ * @param invite 邀请信息
+ * @returns 剩余秒数（已过期返回 0）
+ */
+export function getInviteTimeRemaining(invite) {
+    const now = Math.floor(Date.now() / 1000);
+    const expiry = parseInt(invite.expiry);
+    return Math.max(0, expiry - now);
+}
+/**
+ * 筛选发送的邀请
+ *
+ * @param invites 邀请列表
+ * @param sender 发送者地址
+ * @returns 发送的邀请
+ */
+export function filterSentInvites(invites, sender) {
+    return invites.filter(i => i.sender === sender);
+}
+/**
+ * 筛选接收的邀请
+ *
+ * @param invites 邀请列表
+ * @param receiver 接收者地址
+ * @returns 接收的邀请
+ */
+export function filterReceivedInvites(invites, receiver) {
+    return invites.filter(i => i.receiver === receiver);
+}