@beeperbot/sdk 0.2.2 → 0.2.3

package/dist/core/index.d.cts

@@ -0,0 +1,376 @@
+type GoalType = 'max_reach' | 'lil_mission' | 'hard_mission';
+type SplitPreset = 'balanced' | 'more_reach' | 'more_action';
+type BonusDistributionType = 'lottery' | 'fcfs';
+interface MissionCTA {
+    type: 'follow_profile' | 'like_cast' | 'recast' | 'share_cast' | 'visit_link' | 'quiz' | 'external_verify' | 'x_follow' | 'x_like' | 'x_recast';
+    profileFid?: number;
+    profileUsername?: string;
+    castHash?: string;
+    castUrl?: string;
+    requirements?: {
+        textIncludes?: string[];
+        mentions?: string[];
+        embeds?: string[];
+    };
+    url?: string;
+    label?: string;
+    questions?: Array<{
+        question: string;
+        answers: string[];
+        correctAnswerIndex: number;
+    }>;
+    endpointUrl?: string;
+    appUrl?: string;
+    description?: string;
+    handle?: string;
+    profileUrl?: string;
+    tweetId?: string;
+    tweetUrl?: string;
+}
+interface BonusConfig {
+    type: BonusDistributionType;
+    ctas: MissionCTA[];
+    lotteryConfig?: {
+        prizeTiers: Array<{
+            prizeAmount: number;
+            winnerCount: number;
+        }>;
+        durationSeconds?: number;
+    };
+    fcfsConfig?: {
+        amountPerClaim: number;
+        maxClaims: number;
+        startDelaySeconds?: number;
+    };
+}
+interface BudgetSplit {
+    totalUsd: number;
+    payoutUsd: number;
+    bonusUsd: number;
+    platformFeeUsd: number;
+    userPaysUsd: number;
+    goalType: GoalType;
+    splitPreset: SplitPreset;
+    payoutPercent: number;
+    bonusPercent: number;
+}
+interface AgentUser {
+    id: string;
+    fid?: number;
+    username: string;
+    displayName?: string;
+    pfpUrl?: string;
+    platform: string;
+    walletAddress?: string;
+    attentionPriceUsd: string;
+    followerCount?: number;
+}
+interface AttentionPrice {
+    userId: string;
+    username: string;
+    priceUsd: string;
+    priceUsdc: string;
+}
+interface PaymentIntent {
+    intentId: string;
+    recipient: string;
+    amount: string;
+    amountFormatted: string;
+    tokenAddress: string;
+    tokenSymbol: string;
+    chainId: number;
+    chainName: string;
+    message: string;
+    recipientInfo: {
+        username: string;
+        displayName?: string;
+        fid?: number;
+    };
+    instruction: string;
+    expiresAt: string;
+    baseAmountUsd: string;
+    platformFeeUsd: string;
+    totalAmountUsd: string;
+    feePercentage: number;
+}
+interface PrepareBeepResult {
+    type: 'confirmation';
+    recipient: {
+        username: string;
+        displayName?: string;
+        pfpUrl?: string;
+        fid?: number;
+        walletAddress: string;
+    };
+    message: string;
+    baseAmountUsd: string;
+    platformFeeUsd: string;
+    totalAmountUsd: string;
+    feePercentage: number;
+    chainId: number;
+    chainName: string;
+    attentionPriceUsd: string;
+    hasMissions?: boolean;
+    budgetSplit?: BudgetSplit;
+    bonusConfig?: BonusConfig;
+}
+interface PrepareCampaignResult {
+    type: 'campaign_confirmation';
+    recipientCount: number;
+    budgetSplit: BudgetSplit;
+    bonusConfig?: BonusConfig;
+    missionSummary?: string;
+    payoutEstimate: {
+        recipientCount: number;
+        totalPayoutCostUsd: string;
+        avgPriceUsd: string;
+    };
+    platformFeeUsd: string;
+    userPaysUsd: string;
+    message?: string;
+    chainId: number;
+    chainName: string;
+}
+interface PrepareBeepError {
+    error: string;
+    message: string;
+    minimumUsd?: string;
+    requestedUsd?: string;
+}
+interface EstimateDiagnostics {
+    candidateCount: number;
+    budgetMicro: number;
+    appliedDefaults: string[];
+}
+interface EstimateResult {
+    recipientCount: number;
+    totalCostUsd: string;
+    avgPriceUsd: string;
+    minPriceUsd: string;
+    maxPriceUsd: string;
+    remainingBudgetUsd: string;
+    budgetSufficient: boolean;
+    diagnostics?: EstimateDiagnostics;
+}
+interface PreviewUser {
+    username: string;
+    displayName?: string;
+    fid?: number;
+    priceUsd: string;
+    followerCount?: number;
+    neynarScore?: number;
+    pfpUrl?: string;
+}
+interface PreviewResult {
+    users: PreviewUser[];
+    totalCount: number;
+    hasMore: boolean;
+}
+interface BulkIntentResult {
+    bulkIntentId: string;
+    recipientCount: number;
+    totalAmount: string;
+    totalAmountFormatted: string;
+    payments: Array<{
+        recipient: string;
+        amount: string;
+        username: string;
+    }>;
+    summary: string;
+    chainId: number;
+    chainName: string;
+    tokenAddress: string;
+    tokenSymbol: string;
+    expiresAt: string;
+}
+interface SimpleFilters {
+    platform?: 'all' | 'farcaster' | 'twitter';
+    activeInLastDays?: number;
+    minCastCount?: number;
+    neynarScoreMin?: number;
+    neynarScoreMax?: number;
+    quotientScoreMin?: number;
+    quotientScoreMax?: number;
+    spamLabel?: 'not_spam_only' | 'spam_only' | 'all';
+    verifiedOnly?: boolean;
+    minFollowers?: number;
+    maxFollowers?: number;
+    followersOf?: number;
+    mutualsWith?: number;
+    signalTokens?: string[];
+    tokenHolders?: Array<{
+        tokenAddress: string;
+        chainId: number;
+        minBalance?: string;
+    }>;
+    hasBaseWallet?: boolean;
+    hasVerifiedWallet?: boolean;
+    maxAttentionPriceUsd?: number;
+    minBatteryPercentage?: number;
+    hasRechargedInLastDays?: number;
+    excludePingedToday?: boolean;
+    countries?: string[];
+    timezones?: Array<{
+        offset: number;
+        range?: number;
+    }>;
+    fids?: number[];
+    userIds?: string[];
+    orderBy?: 'attention_price_asc' | 'attention_price_desc' | 'neynar_score_desc' | 'followers_desc' | 'followers_asc' | 'recent_activity' | 'battery_desc' | 'random';
+}
+type OrderByOption = NonNullable<SimpleFilters['orderBy']>;
+interface AgentQueryPlan {
+    inputFilters: SimpleFilters;
+    filters: SimpleFilters;
+    orderBy: OrderByOption;
+    defaultsApplied: string[];
+}
+interface CoreUserRecord {
+    id: string;
+    username: string;
+    displayName?: string;
+    pfpUrl?: string;
+    platform: string;
+    followerCount?: number;
+    attentionPriceMicroUsd: bigint | number | string;
+}
+interface CoreResolvedUser extends CoreUserRecord {
+    fid?: number;
+    walletAddress?: string;
+}
+interface CoreCandidateUser extends CoreUserRecord {
+    neynarScore?: number;
+}
+interface BeepHistoryRecord {
+    id: string;
+    toUsername: string;
+    message: string | null;
+    value: number;
+    status: string;
+    createdAt: Date;
+}
+interface AgentCoreAdapter {
+    resolveUser(query: string | number): Promise<CoreResolvedUser | null>;
+    getFidForUser(userId: string): Promise<number | null>;
+    getBulkFidsForUsers(userIds: string[]): Promise<Map<string, number>>;
+    getPrimaryWalletAddress(userId: string): Promise<string | null>;
+    getBulkPrimaryWalletAddresses(userIds: string[]): Promise<Map<string, string>>;
+    findUsers(params: {
+        filters: SimpleFilters;
+        orderBy: OrderByOption;
+        limit: number;
+        includeProfile?: boolean;
+        includeReputation?: boolean;
+    }): Promise<CoreCandidateUser[]>;
+    countUsers(filters: SimpleFilters): Promise<number>;
+    getBeepHistory(params: {
+        fromFid?: number;
+        fromUserId?: string;
+        limit?: number;
+        offset?: number;
+    }): Promise<{
+        beeps: BeepHistoryRecord[];
+        total: number;
+    }>;
+}
+interface AgentCoreConfig {
+    defaultChainId?: number;
+    platformFeeRate?: number;
+    estimateMaxUsers?: number;
+    bulkMaxUsers?: number;
+    microUsdPerUsd?: number;
+    chainInfo?: Record<number, {
+        name: string;
+        usdcAddress: string;
+    }>;
+}
+
+interface NormalizedFiltersResult {
+    filters: SimpleFilters;
+    defaultsApplied: string[];
+}
+declare function normalizeAgentFilters(filters: SimpleFilters): NormalizedFiltersResult;
+declare function getOrderByOrDefault(filters: SimpleFilters): OrderByOption;
+declare function buildAgentQueryPlan(filters: SimpleFilters): AgentQueryPlan;
+
+declare class AgentCore {
+    private readonly adapter;
+    private readonly defaultChainId;
+    private readonly platformFeeRate;
+    private readonly estimateMaxUsers;
+    private readonly bulkMaxUsers;
+    private readonly microUsdPerUsd;
+    private readonly chainInfo;
+    constructor(adapter: AgentCoreAdapter, config?: AgentCoreConfig);
+    buildQueryPlan(filters: SimpleFilters): AgentQueryPlan;
+    normalizeFilters(filters: SimpleFilters): NormalizedFiltersResult;
+    computeBudgetSplit(totalUsd: number, goalType?: GoalType, splitPreset?: SplitPreset): BudgetSplit;
+    lookup(query: string | number): Promise<AgentUser | null>;
+    getPrice(query: string | number): Promise<AttentionPrice | null>;
+    prepareBeep(params: {
+        to: string | number;
+        amountUsd: string;
+        message: string;
+        chainId?: number;
+        goalType?: GoalType;
+        splitPreset?: SplitPreset;
+        bonusConfig?: BonusConfig;
+    }): Promise<PrepareBeepResult | PrepareBeepError>;
+    createIntent(params: {
+        to: string | number;
+        amountUsd: string;
+        message?: string;
+        chainId?: number;
+    }): Promise<PaymentIntent | null>;
+    estimate(params: {
+        filters: SimpleFilters;
+        budgetUsd: string;
+        message?: string;
+    }): Promise<EstimateResult>;
+    preview(params: {
+        filters: SimpleFilters;
+        limit: number;
+    }): Promise<PreviewResult>;
+    createBulkIntent(params: {
+        filters: SimpleFilters;
+        budgetUsd: string;
+        message?: string;
+        chainId?: number;
+    }): Promise<BulkIntentResult>;
+    prepareCampaign(params: {
+        filters: SimpleFilters;
+        budgetUsd: string;
+        message?: string;
+        goalType?: GoalType;
+        splitPreset?: SplitPreset;
+        bonusConfig?: BonusConfig;
+        chainId?: number;
+    }): Promise<PrepareCampaignResult>;
+    getBeepHistory(params: {
+        fromFid?: number;
+        fromUserId?: string;
+        limit?: number;
+        offset?: number;
+    }): Promise<{
+        beeps: BeepHistoryRecord[];
+        total: number;
+    }>;
+}
+declare function createAgentCore(adapter: AgentCoreAdapter, config?: AgentCoreConfig): AgentCore;
+declare function normalizeFilters(filters: SimpleFilters): NormalizedFiltersResult;
+declare function buildQueryPlan(filters: SimpleFilters): AgentQueryPlan;
+declare function getDefaultOrderBy(filters: SimpleFilters): OrderByOption;
+
+type AgentCoreErrorCode = 'VALIDATION_ERROR' | 'NOT_FOUND' | 'UNSUPPORTED_CHAIN' | 'NO_RECIPIENTS' | 'INTERNAL_ERROR';
+declare class AgentCoreError extends Error {
+    readonly code: AgentCoreErrorCode;
+    constructor(code: AgentCoreErrorCode, message: string);
+    static validation(message: string): AgentCoreError;
+    static notFound(message: string): AgentCoreError;
+    static unsupportedChain(chainId: number): AgentCoreError;
+    static noRecipients(message: string): AgentCoreError;
+}
+
+declare function computeBudgetSplit(totalUsd: number, goalType?: GoalType, splitPreset?: SplitPreset, platformFeeRate?: number): BudgetSplit;
+
+export { AgentCore, type AgentCoreAdapter, type AgentCoreConfig, AgentCoreError, type AgentCoreErrorCode, type AgentQueryPlan, type AgentUser, type AttentionPrice, type BeepHistoryRecord, type BonusConfig, type BonusDistributionType, type BudgetSplit, type BulkIntentResult, type CoreCandidateUser, type CoreResolvedUser, type CoreUserRecord, type EstimateDiagnostics, type EstimateResult, type GoalType, type MissionCTA, type OrderByOption, type PaymentIntent, type PrepareBeepError, type PrepareBeepResult, type PrepareCampaignResult, type PreviewResult, type PreviewUser, type SimpleFilters, type SplitPreset, buildAgentQueryPlan, buildQueryPlan, computeBudgetSplit, createAgentCore, getDefaultOrderBy, getOrderByOrDefault, normalizeAgentFilters, normalizeFilters };