@puul/partner-sdk 1.0.0 → 1.3.0

package/README.md

@@ -139,8 +139,20 @@ await puul.wallet.deposit({
   currency: 'USDC',
   idempotency_key: 'dep_unique_123',
 });
+
+// Withdraw from omnibus to configured bank/crypto destination
+const withdrawal = await puul.wallet.withdraw({
+  amount: 500000,       // $5,000 in minor units
+  currency: 'USDC',
+  method: 'bank',       // or 'crypto'
+});
+// withdrawal.withdrawalId, withdrawal.status
 ```
 
+> **Auto-Settlement:** If your `payout_method` is configured (via the admin dashboard),
+> revenue share is automatically paid out after each market settlement. You don't need
+> to call `withdraw()` manually — it happens at settlement time.
+
 ### Webhook Verification
 
 ```typescript
@@ -163,9 +175,16 @@ app.post('/webhooks/puul', express.raw({ type: '*/*' }), (req, res) => {
     case 'prediction.settled':
       console.log('Prediction settled:', event.data);
       break;
+    case 'prediction.voided':
+      console.log('Prediction voided:', event.data);
+      // Handle refund — user gets full stake back
+      break;
     case 'deposit.confirmed':
       console.log('Deposit confirmed:', event.data);
       break;
+    case 'withdrawal.completed':
+      console.log('Withdrawal completed:', event.data);
+      break;
   }
 
   res.status(200).send('OK');

package/dist/index.d.mts

@@ -33,22 +33,27 @@ interface MarketOutcome {
     id: string;
     slug: string;
     label: string;
-    pool: {
-        pool_amount: string;
-        total_bets: number;
-    };
+    display_order: number;
+    pool_amount: string;
+    predictor_count: number;
+    prediction_count: number;
 }
 interface Market {
     id: string;
     question: string;
-    description: string;
     category: string;
+    image_url: string;
+    market_type: string;
     status: string;
     currency: string;
     close_time: string;
     freeze_at: string | null;
-    target_countries: string[];
     outcomes: MarketOutcome[];
+    volume: number;
+    volume_currency: string;
+    predictor_count: number;
+    prediction_count: number;
+    created_at: string;
 }
 type PredictionStatus = 'OPEN' | 'WON' | 'LOST' | 'VOIDED';
 type Currency = 'NGN' | 'USDC' | 'USDT' | 'KES' | 'GHS' | 'ZAR';
@@ -149,26 +154,238 @@ interface DepositParams {
     idempotency_key: string;
     reference?: string;
 }
-type WebhookEventType = 'prediction.settled' | 'deposit.confirmed' | 'withdrawal.completed';
-interface WebhookEvent<T = {
-    [key: string]: unknown;
-}> {
+type WithdrawMethod = 'bank' | 'crypto';
+interface WithdrawParams {
+    /** Amount to withdraw in minor units (cents) */
+    amount: number;
+    /** Currency to withdraw. Defaults to USDC */
+    currency?: Currency;
+    /** Payout method: 'bank' for fiat, 'crypto' for on-chain */
+    method?: WithdrawMethod;
+}
+interface WithdrawResult {
+    withdrawalId: string;
+    partnerId: string;
+    amount: number;
+    currency: string;
+    method: WithdrawMethod;
+    payoutReference: string | null;
+    status: string;
+}
+type LotteryPoolType = 'winner_takes_all' | 'tiered';
+type LotteryPoolFrequency = 'daily' | 'weekly' | 'monthly' | 'quarterly';
+type LotteryPoolStatus = 'upcoming' | 'open' | 'drawing' | 'settled' | 'cancelled';
+type LotteryEntryStatus = 'active' | 'won' | 'lost' | 'refunded';
+interface PrizeTier {
+    /** 1-based rank (1 = first place) */
+    rank: number;
+    /** Percentage of distributable pool in basis points (5000 = 50%) */
+    pct: number;
+}
+interface LotteryPool {
+    id: string;
+    title: string;
+    description: string | null;
+    type: LotteryPoolType;
+    frequency: LotteryPoolFrequency;
+    status: LotteryPoolStatus;
+    ticket_price: string;
+    currency: string;
+    max_tickets: number | null;
+    max_tickets_per_user: number | null;
+    total_entries: number;
+    total_pool_amount: string;
+    opens_at: string;
+    draws_at: string;
+    drawn_at: string | null;
+    winning_numbers: number[];
+    prize_tiers: PrizeTier[];
+    takeout_rate_bps: number;
+}
+interface LotteryEntry {
+    id: string;
+    pool_id: string;
+    user_id: string | null;
+    user_external_id: string | null;
+    ticket_number: number;
+    amount_paid: string;
+    currency: string;
+    status: LotteryEntryStatus;
+    prize_amount: string | null;
+    prize_tier: number | null;
+    purchased_at: string;
+}
+interface LotteryEntriesResponse {
+    entries: LotteryEntry[];
+    total: number;
+}
+interface BuyTicketParams {
+    /** Puul user ID of the linked user */
+    userId: string;
+    /** Unique key to prevent duplicate purchases */
+    idempotencyKey: string;
+    /** Number of tickets (default: 1) */
+    quantity?: number;
+    /** Your external user ID (for tracking) */
+    userExternalId?: string;
+}
+interface BuyTicketResponse {
+    entries: LotteryEntry[];
+}
+interface LotteryDrawResult {
+    pool_id: string;
+    status: string;
+    drawn_at: string | null;
+    winning_numbers: number[];
+    total_pool_amount: string;
+    your_entries: Array<{
+        id: string;
+        ticket_number: number;
+        user_id: string | null;
+        user_external_id: string | null;
+        status: string;
+        prize_amount: string | null;
+        prize_tier: number | null;
+    }>;
+    your_winners: number;
+    your_total_winnings: number;
+}
+type WebhookEventType = 'user.created' | 'prediction.placed' | 'prediction.settled' | 'prediction.voided' | 'market.closed' | 'market.settled' | 'deposit.confirmed' | 'withdrawal.completed' | 'withdrawal.failed' | 'lottery.pool.drawn' | 'lottery.ticket.won';
+interface WebhookEvent<T = unknown> {
     event: WebhookEventType;
     timestamp: string;
     data: T;
 }
-interface PredictionSettledData {
+interface UserCreatedData {
+    puul_user_id: string;
+    external_user_id: string;
+    email: string;
+    phone: string;
+    country_code: string;
+    created_at: string;
+}
+interface PredictionPlacedData {
     prediction_id: string;
+    user_id: string;
+    user_external_id: string;
     market_id: string;
+    market_question: string;
     outcome_id: string;
     outcome_slug: string;
+    outcome_label: string;
+    stake_amount: number;
+    stake_currency: string;
+    estimated_return: string;
+    idempotency_key: string;
+    placed_at: string;
+}
+interface PredictionSettledData {
+    prediction_id: string;
+    user_id: string;
     user_external_id: string;
-    status: 'WON' | 'LOST' | 'VOIDED';
+    market_id: string;
+    market_question: string;
+    outcome_id: string;
+    outcome_slug: string;
+    outcome_label: string;
+    stake_amount: string;
+    stake_currency: string;
+    status: 'WON' | 'LOST';
+    payout: string;
+    multiplier: string;
+    settled_at: string;
+}
+interface PredictionVoidedData {
+    prediction_id: string;
+    user_id: string;
+    user_external_id: string | null;
+    market_id: string;
+    market_question: string | null;
+    outcome_label: string | null;
     stake_amount: string;
     stake_currency: string;
-    final_return: string;
+    refund_amount: string;
+    voided_at: string;
+    reason: string;
+}
+interface MarketClosedData {
+    market_id: string;
+    market_question: string;
+    market_type: string;
+    close_time: string;
+    closed_at: string;
+    currency: string;
+    volume: number;
+    prediction_count: number;
+}
+interface MarketSettledData {
+    market_id: string;
+    market_question: string;
+    market_type: string;
+    winning_outcome_id: string;
+    winning_outcome_slug: string | null;
+    winning_outcome_label: string | null;
+    currency: string;
+    total_pool: number;
+    winners_count: number;
+    total_payout: number;
     settled_at: string;
 }
+interface DepositConfirmedData {
+    deposit_id: string;
+    user_id: string;
+    external_user_id: string;
+    amount: number;
+    currency: string;
+    amount_usd: number;
+    tx_hash: string;
+    status: string;
+    confirmed_at: string;
+}
+interface WithdrawalCompletedData {
+    withdrawal_id: string;
+    partner_id: string;
+    external_user_id: string;
+    amount: number;
+    currency: string;
+    method: string;
+    payout_reference: string | null;
+    completed_at: string;
+}
+interface WithdrawalFailedData {
+    withdrawal_id: string;
+    partner_id: string;
+    external_user_id: string;
+    amount: number;
+    currency: string;
+    method: string;
+    reason: string;
+    failed_at: string;
+}
+interface LotteryPoolDrawnData {
+    pool_id: string;
+    pool_title: string;
+    drawn_at: string;
+    winning_numbers: number[];
+    total_pool_amount: number;
+    total_entries: number;
+    takeout_amount: number;
+    total_payout: number;
+    your_entries: number;
+    your_winners: number;
+    your_total_winnings: number;
+}
+interface LotteryTicketWonData {
+    entry_id: string;
+    pool_id: string;
+    pool_title: string;
+    user_id: string;
+    user_external_id: string | null;
+    ticket_number: number;
+    prize_amount: number;
+    prize_tier: number;
+    drawn_at: string;
+}
 interface PuulApiError {
     statusCode: number;
     message: string | string[];
@@ -220,6 +437,7 @@ declare class PuulPartner {
     readonly markets: MarketsAPI;
     readonly predictions: PredictionsAPI;
     readonly wallet: WalletAPI;
+    readonly lottery: LotteryAPI;
     constructor(config: PuulPartnerConfig);
     /** Get a valid access token, refreshing if needed */
     getAccessToken(): Promise<string>;
@@ -274,6 +492,55 @@ declare class WalletAPI {
     deposit(params: DepositParams): Promise<unknown>;
     /** Get withdrawal fee estimate */
     getWithdrawalFees(currency: string, amount: number): Promise<unknown>;
+    /**
+     * Withdraw from omnibus balance.
+     * Initiates a payout to the partner's configured bank account or crypto wallet.
+     *
+     * @example
+     * ```typescript
+     * const result = await puul.wallet.withdraw({
+     *   amount: 500000, // $5,000 in cents
+     *   currency: 'USDC',
+     *   method: 'bank', // or 'crypto'
+     * });
+     * ```
+     */
+    withdraw(params: WithdrawParams): Promise<WithdrawResult>;
+}
+declare class LotteryAPI {
+    private readonly client;
+    constructor(client: PuulPartner);
+    /** List lottery pools, optionally filtered by status and frequency */
+    listPools(options?: {
+        status?: LotteryPoolStatus;
+        frequency?: string;
+        limit?: number;
+    }): Promise<LotteryPool[]>;
+    /** Get a specific pool by ID */
+    getPool(poolId: string): Promise<LotteryPool>;
+    /**
+     * Buy ticket(s) for a linked user.
+     *
+     * @example
+     * ```typescript
+     * const result = await puul.lottery.buyTicket('pool-uuid', {
+     *   userId: 'puul-user-uuid',
+     *   idempotencyKey: 'lottery-user456-pool1-001',
+     *   quantity: 3,
+     * });
+     * ```
+     */
+    buyTicket(poolId: string, params: BuyTicketParams): Promise<BuyTicketResponse>;
+    /** List lottery entries for your partner account */
+    listEntries(options?: {
+        poolId?: string;
+        status?: LotteryEntryStatus;
+        limit?: number;
+    }): Promise<LotteryEntriesResponse>;
+    /** Get a single lottery entry by ID */
+    getEntry(entryId: string): Promise<LotteryEntry>;
+    /** Get draw results for a completed pool */
+    getDrawResults(poolId: string): Promise<LotteryDrawResult>;
 }
 
 /**
@@ -318,22 +585,51 @@ declare function verifyWebhookSignature(payload: string, signature: string, secr
  * const event = parseWebhookEvent(req.body);
  *
  * if (event.event === 'prediction.settled') {
- *   const { prediction_id, status, final_return } = event.data;
+ *   const { prediction_id, status, payout } = event.data;
  *   // Handle settlement...
  * }
  * ```
  */
 declare function parseWebhookEvent(body: unknown): WebhookEvent;
-/**
- * Type guard for prediction.settled events.
- * Returns true if the event type is 'prediction.settled'.
- * Use this to narrow the type before accessing `.data` as PredictionSettledData.
- */
-declare function isPredictionSettledEvent(event: WebhookEvent): boolean;
+/** Type guard for prediction.placed events. */
+declare function isPredictionPlacedEvent(event: WebhookEvent): event is WebhookEvent<PredictionPlacedData>;
+/** Type guard for prediction.settled events. */
+declare function isPredictionSettledEvent(event: WebhookEvent): event is WebhookEvent<PredictionSettledData>;
+/** Type guard for prediction.voided events. */
+declare function isPredictionVoidedEvent(event: WebhookEvent): event is WebhookEvent<PredictionVoidedData>;
+/** Type guard for market.closed events. */
+declare function isMarketClosedEvent(event: WebhookEvent): event is WebhookEvent<MarketClosedData>;
+/** Type guard for market.settled events. */
+declare function isMarketSettledEvent(event: WebhookEvent): event is WebhookEvent<MarketSettledData>;
+/** Type guard for deposit.confirmed events. */
+declare function isDepositConfirmedEvent(event: WebhookEvent): event is WebhookEvent<DepositConfirmedData>;
+/** Type guard for withdrawal.completed events. */
+declare function isWithdrawalCompletedEvent(event: WebhookEvent): event is WebhookEvent<WithdrawalCompletedData>;
+/** Type guard for withdrawal.failed events. */
+declare function isWithdrawalFailedEvent(event: WebhookEvent): event is WebhookEvent<WithdrawalFailedData>;
+/** Type guard for lottery.pool.drawn events. */
+declare function isLotteryPoolDrawnEvent(event: WebhookEvent): event is WebhookEvent<LotteryPoolDrawnData>;
+/** Type guard for lottery.ticket.won events. */
+declare function isLotteryTicketWonEvent(event: WebhookEvent): event is WebhookEvent<LotteryTicketWonData>;
 /**
  * Convenience cast for prediction.settled event data.
  * Call after verifying with `isPredictionSettledEvent`.
  */
 declare function asPredictionSettledData(event: WebhookEvent): PredictionSettledData;
+/**
+ * Convenience cast for market.settled event data.
+ * Call after verifying with `isMarketSettledEvent`.
+ */
+declare function asMarketSettledData(event: WebhookEvent): MarketSettledData;
+/**
+ * Convenience cast for lottery.pool.drawn event data.
+ * Call after verifying with `isLotteryPoolDrawnEvent`.
+ */
+declare function asLotteryPoolDrawnData(event: WebhookEvent): LotteryPoolDrawnData;
+/**
+ * Convenience cast for lottery.ticket.won event data.
+ * Call after verifying with `isLotteryTicketWonEvent`.
+ */
+declare function asLotteryTicketWonData(event: WebhookEvent): LotteryTicketWonData;
 
-export { type AccessTokenResponse, type CreateLinkTokenParams, type CreatePendingPredictionParams, type CreateQuoteParams, type Currency, type DepositAccountInfo, type DepositParams, type LinkTokenResponse, type Market, type MarketOutcome, type PendingPrediction, type PlacePredictionParams, type Prediction, type PredictionListResponse, type PredictionSettledData, type PredictionStatus, type PuulApiError, PuulError, PuulPartner, type PuulPartnerConfig, type QuoteResponse, type SessionResponse, type WalletBalance, type WebhookEvent, type WebhookEventType, asPredictionSettledData, isPredictionSettledEvent, parseWebhookEvent, verifyWebhookSignature };
+export { type AccessTokenResponse, type BuyTicketParams, type BuyTicketResponse, type CreateLinkTokenParams, type CreatePendingPredictionParams, type CreateQuoteParams, type Currency, type DepositAccountInfo, type DepositConfirmedData, type DepositParams, type LinkTokenResponse, type LotteryDrawResult, type LotteryEntriesResponse, type LotteryEntry, type LotteryEntryStatus, type LotteryPool, type LotteryPoolDrawnData, type LotteryPoolFrequency, type LotteryPoolStatus, type LotteryPoolType, type LotteryTicketWonData, type Market, type MarketClosedData, type MarketOutcome, type MarketSettledData, type PendingPrediction, type PlacePredictionParams, type Prediction, type PredictionListResponse, type PredictionPlacedData, type PredictionSettledData, type PredictionStatus, type PredictionVoidedData, type PrizeTier, type PuulApiError, PuulError, PuulPartner, type PuulPartnerConfig, type QuoteResponse, type SessionResponse, type UserCreatedData, type WalletBalance, type WebhookEvent, type WebhookEventType, type WithdrawMethod, type WithdrawParams, type WithdrawResult, type WithdrawalCompletedData, type WithdrawalFailedData, asLotteryPoolDrawnData, asLotteryTicketWonData, asMarketSettledData, asPredictionSettledData, isDepositConfirmedEvent, isLotteryPoolDrawnEvent, isLotteryTicketWonEvent, isMarketClosedEvent, isMarketSettledEvent, isPredictionPlacedEvent, isPredictionSettledEvent, isPredictionVoidedEvent, isWithdrawalCompletedEvent, isWithdrawalFailedEvent, parseWebhookEvent, verifyWebhookSignature };

package/dist/index.d.ts

@@ -33,22 +33,27 @@ interface MarketOutcome {
     id: string;
     slug: string;
     label: string;
-    pool: {
-        pool_amount: string;
-        total_bets: number;
-    };
+    display_order: number;
+    pool_amount: string;
+    predictor_count: number;
+    prediction_count: number;
 }
 interface Market {
     id: string;
     question: string;
-    description: string;
     category: string;
+    image_url: string;
+    market_type: string;
     status: string;
     currency: string;
     close_time: string;
     freeze_at: string | null;
-    target_countries: string[];
     outcomes: MarketOutcome[];
+    volume: number;
+    volume_currency: string;
+    predictor_count: number;
+    prediction_count: number;
+    created_at: string;
 }
 type PredictionStatus = 'OPEN' | 'WON' | 'LOST' | 'VOIDED';
 type Currency = 'NGN' | 'USDC' | 'USDT' | 'KES' | 'GHS' | 'ZAR';
@@ -149,26 +154,238 @@ interface DepositParams {
     idempotency_key: string;
     reference?: string;
 }
-type WebhookEventType = 'prediction.settled' | 'deposit.confirmed' | 'withdrawal.completed';
-interface WebhookEvent<T = {
-    [key: string]: unknown;
-}> {
+type WithdrawMethod = 'bank' | 'crypto';
+interface WithdrawParams {
+    /** Amount to withdraw in minor units (cents) */
+    amount: number;
+    /** Currency to withdraw. Defaults to USDC */
+    currency?: Currency;
+    /** Payout method: 'bank' for fiat, 'crypto' for on-chain */
+    method?: WithdrawMethod;
+}
+interface WithdrawResult {
+    withdrawalId: string;
+    partnerId: string;
+    amount: number;
+    currency: string;
+    method: WithdrawMethod;
+    payoutReference: string | null;
+    status: string;
+}
+type LotteryPoolType = 'winner_takes_all' | 'tiered';
+type LotteryPoolFrequency = 'daily' | 'weekly' | 'monthly' | 'quarterly';
+type LotteryPoolStatus = 'upcoming' | 'open' | 'drawing' | 'settled' | 'cancelled';
+type LotteryEntryStatus = 'active' | 'won' | 'lost' | 'refunded';
+interface PrizeTier {
+    /** 1-based rank (1 = first place) */
+    rank: number;
+    /** Percentage of distributable pool in basis points (5000 = 50%) */
+    pct: number;
+}
+interface LotteryPool {
+    id: string;
+    title: string;
+    description: string | null;
+    type: LotteryPoolType;
+    frequency: LotteryPoolFrequency;
+    status: LotteryPoolStatus;
+    ticket_price: string;
+    currency: string;
+    max_tickets: number | null;
+    max_tickets_per_user: number | null;
+    total_entries: number;
+    total_pool_amount: string;
+    opens_at: string;
+    draws_at: string;
+    drawn_at: string | null;
+    winning_numbers: number[];
+    prize_tiers: PrizeTier[];
+    takeout_rate_bps: number;
+}
+interface LotteryEntry {
+    id: string;
+    pool_id: string;
+    user_id: string | null;
+    user_external_id: string | null;
+    ticket_number: number;
+    amount_paid: string;
+    currency: string;
+    status: LotteryEntryStatus;
+    prize_amount: string | null;
+    prize_tier: number | null;
+    purchased_at: string;
+}
+interface LotteryEntriesResponse {
+    entries: LotteryEntry[];
+    total: number;
+}
+interface BuyTicketParams {
+    /** Puul user ID of the linked user */
+    userId: string;
+    /** Unique key to prevent duplicate purchases */
+    idempotencyKey: string;
+    /** Number of tickets (default: 1) */
+    quantity?: number;
+    /** Your external user ID (for tracking) */
+    userExternalId?: string;
+}
+interface BuyTicketResponse {
+    entries: LotteryEntry[];
+}
+interface LotteryDrawResult {
+    pool_id: string;
+    status: string;
+    drawn_at: string | null;
+    winning_numbers: number[];
+    total_pool_amount: string;
+    your_entries: Array<{
+        id: string;
+        ticket_number: number;
+        user_id: string | null;
+        user_external_id: string | null;
+        status: string;
+        prize_amount: string | null;
+        prize_tier: number | null;
+    }>;
+    your_winners: number;
+    your_total_winnings: number;
+}
+type WebhookEventType = 'user.created' | 'prediction.placed' | 'prediction.settled' | 'prediction.voided' | 'market.closed' | 'market.settled' | 'deposit.confirmed' | 'withdrawal.completed' | 'withdrawal.failed' | 'lottery.pool.drawn' | 'lottery.ticket.won';
+interface WebhookEvent<T = unknown> {
     event: WebhookEventType;
     timestamp: string;
     data: T;
 }
-interface PredictionSettledData {
+interface UserCreatedData {
+    puul_user_id: string;
+    external_user_id: string;
+    email: string;
+    phone: string;
+    country_code: string;
+    created_at: string;
+}
+interface PredictionPlacedData {
     prediction_id: string;
+    user_id: string;
+    user_external_id: string;
     market_id: string;
+    market_question: string;
     outcome_id: string;
     outcome_slug: string;
+    outcome_label: string;
+    stake_amount: number;
+    stake_currency: string;
+    estimated_return: string;
+    idempotency_key: string;
+    placed_at: string;
+}
+interface PredictionSettledData {
+    prediction_id: string;
+    user_id: string;
     user_external_id: string;
-    status: 'WON' | 'LOST' | 'VOIDED';
+    market_id: string;
+    market_question: string;
+    outcome_id: string;
+    outcome_slug: string;
+    outcome_label: string;
+    stake_amount: string;
+    stake_currency: string;
+    status: 'WON' | 'LOST';
+    payout: string;
+    multiplier: string;
+    settled_at: string;
+}
+interface PredictionVoidedData {
+    prediction_id: string;
+    user_id: string;
+    user_external_id: string | null;
+    market_id: string;
+    market_question: string | null;
+    outcome_label: string | null;
     stake_amount: string;
     stake_currency: string;
-    final_return: string;
+    refund_amount: string;
+    voided_at: string;
+    reason: string;
+}
+interface MarketClosedData {
+    market_id: string;
+    market_question: string;
+    market_type: string;
+    close_time: string;
+    closed_at: string;
+    currency: string;
+    volume: number;
+    prediction_count: number;
+}
+interface MarketSettledData {
+    market_id: string;
+    market_question: string;
+    market_type: string;
+    winning_outcome_id: string;
+    winning_outcome_slug: string | null;
+    winning_outcome_label: string | null;
+    currency: string;
+    total_pool: number;
+    winners_count: number;
+    total_payout: number;
     settled_at: string;
 }
+interface DepositConfirmedData {
+    deposit_id: string;
+    user_id: string;
+    external_user_id: string;
+    amount: number;
+    currency: string;
+    amount_usd: number;
+    tx_hash: string;
+    status: string;
+    confirmed_at: string;
+}
+interface WithdrawalCompletedData {
+    withdrawal_id: string;
+    partner_id: string;
+    external_user_id: string;
+    amount: number;
+    currency: string;
+    method: string;
+    payout_reference: string | null;
+    completed_at: string;
+}
+interface WithdrawalFailedData {
+    withdrawal_id: string;
+    partner_id: string;
+    external_user_id: string;
+    amount: number;
+    currency: string;
+    method: string;
+    reason: string;
+    failed_at: string;
+}
+interface LotteryPoolDrawnData {
+    pool_id: string;
+    pool_title: string;
+    drawn_at: string;
+    winning_numbers: number[];
+    total_pool_amount: number;
+    total_entries: number;
+    takeout_amount: number;
+    total_payout: number;
+    your_entries: number;
+    your_winners: number;
+    your_total_winnings: number;
+}
+interface LotteryTicketWonData {
+    entry_id: string;
+    pool_id: string;
+    pool_title: string;
+    user_id: string;
+    user_external_id: string | null;
+    ticket_number: number;
+    prize_amount: number;
+    prize_tier: number;
+    drawn_at: string;
+}
 interface PuulApiError {
     statusCode: number;
     message: string | string[];
@@ -220,6 +437,7 @@ declare class PuulPartner {
     readonly markets: MarketsAPI;
     readonly predictions: PredictionsAPI;
     readonly wallet: WalletAPI;
+    readonly lottery: LotteryAPI;
     constructor(config: PuulPartnerConfig);
     /** Get a valid access token, refreshing if needed */
     getAccessToken(): Promise<string>;
@@ -274,6 +492,55 @@ declare class WalletAPI {
     deposit(params: DepositParams): Promise<unknown>;
     /** Get withdrawal fee estimate */
     getWithdrawalFees(currency: string, amount: number): Promise<unknown>;
+    /**
+     * Withdraw from omnibus balance.
+     * Initiates a payout to the partner's configured bank account or crypto wallet.
+     *
+     * @example
+     * ```typescript
+     * const result = await puul.wallet.withdraw({
+     *   amount: 500000, // $5,000 in cents
+     *   currency: 'USDC',
+     *   method: 'bank', // or 'crypto'
+     * });
+     * ```
+     */
+    withdraw(params: WithdrawParams): Promise<WithdrawResult>;
+}
+declare class LotteryAPI {
+    private readonly client;
+    constructor(client: PuulPartner);
+    /** List lottery pools, optionally filtered by status and frequency */
+    listPools(options?: {
+        status?: LotteryPoolStatus;
+        frequency?: string;
+        limit?: number;
+    }): Promise<LotteryPool[]>;
+    /** Get a specific pool by ID */
+    getPool(poolId: string): Promise<LotteryPool>;
+    /**
+     * Buy ticket(s) for a linked user.
+     *
+     * @example
+     * ```typescript
+     * const result = await puul.lottery.buyTicket('pool-uuid', {
+     *   userId: 'puul-user-uuid',
+     *   idempotencyKey: 'lottery-user456-pool1-001',
+     *   quantity: 3,
+     * });
+     * ```
+     */
+    buyTicket(poolId: string, params: BuyTicketParams): Promise<BuyTicketResponse>;
+    /** List lottery entries for your partner account */
+    listEntries(options?: {
+        poolId?: string;
+        status?: LotteryEntryStatus;
+        limit?: number;
+    }): Promise<LotteryEntriesResponse>;
+    /** Get a single lottery entry by ID */
+    getEntry(entryId: string): Promise<LotteryEntry>;
+    /** Get draw results for a completed pool */
+    getDrawResults(poolId: string): Promise<LotteryDrawResult>;
 }
 
 /**
@@ -318,22 +585,51 @@ declare function verifyWebhookSignature(payload: string, signature: string, secr
  * const event = parseWebhookEvent(req.body);
  *
  * if (event.event === 'prediction.settled') {
- *   const { prediction_id, status, final_return } = event.data;
+ *   const { prediction_id, status, payout } = event.data;
  *   // Handle settlement...
  * }
  * ```
  */
 declare function parseWebhookEvent(body: unknown): WebhookEvent;
-/**
- * Type guard for prediction.settled events.
- * Returns true if the event type is 'prediction.settled'.
- * Use this to narrow the type before accessing `.data` as PredictionSettledData.
- */
-declare function isPredictionSettledEvent(event: WebhookEvent): boolean;
+/** Type guard for prediction.placed events. */
+declare function isPredictionPlacedEvent(event: WebhookEvent): event is WebhookEvent<PredictionPlacedData>;
+/** Type guard for prediction.settled events. */
+declare function isPredictionSettledEvent(event: WebhookEvent): event is WebhookEvent<PredictionSettledData>;
+/** Type guard for prediction.voided events. */
+declare function isPredictionVoidedEvent(event: WebhookEvent): event is WebhookEvent<PredictionVoidedData>;
+/** Type guard for market.closed events. */
+declare function isMarketClosedEvent(event: WebhookEvent): event is WebhookEvent<MarketClosedData>;
+/** Type guard for market.settled events. */
+declare function isMarketSettledEvent(event: WebhookEvent): event is WebhookEvent<MarketSettledData>;
+/** Type guard for deposit.confirmed events. */
+declare function isDepositConfirmedEvent(event: WebhookEvent): event is WebhookEvent<DepositConfirmedData>;
+/** Type guard for withdrawal.completed events. */
+declare function isWithdrawalCompletedEvent(event: WebhookEvent): event is WebhookEvent<WithdrawalCompletedData>;
+/** Type guard for withdrawal.failed events. */
+declare function isWithdrawalFailedEvent(event: WebhookEvent): event is WebhookEvent<WithdrawalFailedData>;
+/** Type guard for lottery.pool.drawn events. */
+declare function isLotteryPoolDrawnEvent(event: WebhookEvent): event is WebhookEvent<LotteryPoolDrawnData>;
+/** Type guard for lottery.ticket.won events. */
+declare function isLotteryTicketWonEvent(event: WebhookEvent): event is WebhookEvent<LotteryTicketWonData>;
 /**
  * Convenience cast for prediction.settled event data.
  * Call after verifying with `isPredictionSettledEvent`.
  */
 declare function asPredictionSettledData(event: WebhookEvent): PredictionSettledData;
+/**
+ * Convenience cast for market.settled event data.
+ * Call after verifying with `isMarketSettledEvent`.
+ */
+declare function asMarketSettledData(event: WebhookEvent): MarketSettledData;
+/**
+ * Convenience cast for lottery.pool.drawn event data.
+ * Call after verifying with `isLotteryPoolDrawnEvent`.
+ */
+declare function asLotteryPoolDrawnData(event: WebhookEvent): LotteryPoolDrawnData;
+/**
+ * Convenience cast for lottery.ticket.won event data.
+ * Call after verifying with `isLotteryTicketWonEvent`.
+ */
+declare function asLotteryTicketWonData(event: WebhookEvent): LotteryTicketWonData;
 
-export { type AccessTokenResponse, type CreateLinkTokenParams, type CreatePendingPredictionParams, type CreateQuoteParams, type Currency, type DepositAccountInfo, type DepositParams, type LinkTokenResponse, type Market, type MarketOutcome, type PendingPrediction, type PlacePredictionParams, type Prediction, type PredictionListResponse, type PredictionSettledData, type PredictionStatus, type PuulApiError, PuulError, PuulPartner, type PuulPartnerConfig, type QuoteResponse, type SessionResponse, type WalletBalance, type WebhookEvent, type WebhookEventType, asPredictionSettledData, isPredictionSettledEvent, parseWebhookEvent, verifyWebhookSignature };
+export { type AccessTokenResponse, type BuyTicketParams, type BuyTicketResponse, type CreateLinkTokenParams, type CreatePendingPredictionParams, type CreateQuoteParams, type Currency, type DepositAccountInfo, type DepositConfirmedData, type DepositParams, type LinkTokenResponse, type LotteryDrawResult, type LotteryEntriesResponse, type LotteryEntry, type LotteryEntryStatus, type LotteryPool, type LotteryPoolDrawnData, type LotteryPoolFrequency, type LotteryPoolStatus, type LotteryPoolType, type LotteryTicketWonData, type Market, type MarketClosedData, type MarketOutcome, type MarketSettledData, type PendingPrediction, type PlacePredictionParams, type Prediction, type PredictionListResponse, type PredictionPlacedData, type PredictionSettledData, type PredictionStatus, type PredictionVoidedData, type PrizeTier, type PuulApiError, PuulError, PuulPartner, type PuulPartnerConfig, type QuoteResponse, type SessionResponse, type UserCreatedData, type WalletBalance, type WebhookEvent, type WebhookEventType, type WithdrawMethod, type WithdrawParams, type WithdrawResult, type WithdrawalCompletedData, type WithdrawalFailedData, asLotteryPoolDrawnData, asLotteryTicketWonData, asMarketSettledData, asPredictionSettledData, isDepositConfirmedEvent, isLotteryPoolDrawnEvent, isLotteryTicketWonEvent, isMarketClosedEvent, isMarketSettledEvent, isPredictionPlacedEvent, isPredictionSettledEvent, isPredictionVoidedEvent, isWithdrawalCompletedEvent, isWithdrawalFailedEvent, parseWebhookEvent, verifyWebhookSignature };

package/dist/index.js

@@ -22,8 +22,20 @@ var index_exports = {};
 __export(index_exports, {
   PuulError: () => PuulError,
   PuulPartner: () => PuulPartner,
+  asLotteryPoolDrawnData: () => asLotteryPoolDrawnData,
+  asLotteryTicketWonData: () => asLotteryTicketWonData,
+  asMarketSettledData: () => asMarketSettledData,
   asPredictionSettledData: () => asPredictionSettledData,
+  isDepositConfirmedEvent: () => isDepositConfirmedEvent,
+  isLotteryPoolDrawnEvent: () => isLotteryPoolDrawnEvent,
+  isLotteryTicketWonEvent: () => isLotteryTicketWonEvent,
+  isMarketClosedEvent: () => isMarketClosedEvent,
+  isMarketSettledEvent: () => isMarketSettledEvent,
+  isPredictionPlacedEvent: () => isPredictionPlacedEvent,
   isPredictionSettledEvent: () => isPredictionSettledEvent,
+  isPredictionVoidedEvent: () => isPredictionVoidedEvent,
+  isWithdrawalCompletedEvent: () => isWithdrawalCompletedEvent,
+  isWithdrawalFailedEvent: () => isWithdrawalFailedEvent,
   parseWebhookEvent: () => parseWebhookEvent,
   verifyWebhookSignature: () => verifyWebhookSignature
 });
@@ -59,6 +71,7 @@ var PuulPartner = class {
     this.markets = new MarketsAPI(this);
     this.predictions = new PredictionsAPI(this);
     this.wallet = new WalletAPI(this);
+    this.lottery = new LotteryAPI(this);
   }
   // ==========================================================
   // Internal HTTP layer
@@ -229,22 +242,93 @@ var WalletAPI = class {
   async getWithdrawalFees(currency, amount) {
     return this.client.request("GET", `/partner/wallet/withdrawal-fees?currency=${currency}&amount=${amount}`);
   }
+  /**
+   * Withdraw from omnibus balance.
+   * Initiates a payout to the partner's configured bank account or crypto wallet.
+   *
+   * @example
+   * ```typescript
+   * const result = await puul.wallet.withdraw({
+   *   amount: 500000, // $5,000 in cents
+   *   currency: 'USDC',
+   *   method: 'bank', // or 'crypto'
+   * });
+   * ```
+   */
+  async withdraw(params) {
+    return this.client.request("POST", "/partner/wallet/withdraw", params);
+  }
+};
+var LotteryAPI = class {
+  constructor(client) {
+    this.client = client;
+  }
+  /** List lottery pools, optionally filtered by status and frequency */
+  async listPools(options) {
+    const params = new URLSearchParams();
+    if (options?.status) params.set("status", options.status);
+    if (options?.frequency) params.set("frequency", options.frequency);
+    if (options?.limit) params.set("limit", String(options.limit));
+    const query = params.toString() ? `?${params.toString()}` : "";
+    return this.client.request("GET", `/partner/lottery/pools${query}`);
+  }
+  /** Get a specific pool by ID */
+  async getPool(poolId) {
+    return this.client.request("GET", `/partner/lottery/pools/${poolId}`);
+  }
+  /**
+   * Buy ticket(s) for a linked user.
+   *
+   * @example
+   * ```typescript
+   * const result = await puul.lottery.buyTicket('pool-uuid', {
+   *   userId: 'puul-user-uuid',
+   *   idempotencyKey: 'lottery-user456-pool1-001',
+   *   quantity: 3,
+   * });
+   * ```
+   */
+  async buyTicket(poolId, params) {
+    return this.client.request("POST", `/partner/lottery/pools/${poolId}/buy`, {
+      user_id: params.userId,
+      idempotency_key: params.idempotencyKey,
+      quantity: params.quantity,
+      user_external_id: params.userExternalId
+    });
+  }
+  /** List lottery entries for your partner account */
+  async listEntries(options) {
+    const params = new URLSearchParams();
+    if (options?.poolId) params.set("pool_id", options.poolId);
+    if (options?.status) params.set("status", options.status);
+    if (options?.limit) params.set("limit", String(options.limit));
+    const query = params.toString() ? `?${params.toString()}` : "";
+    return this.client.request("GET", `/partner/lottery/entries${query}`);
+  }
+  /** Get a single lottery entry by ID */
+  async getEntry(entryId) {
+    return this.client.request("GET", `/partner/lottery/entries/${entryId}`);
+  }
+  /** Get draw results for a completed pool */
+  async getDrawResults(poolId) {
+    return this.client.request("GET", `/partner/lottery/pools/${poolId}/results`);
+  }
 };
 
 // src/webhooks.ts
-var import_crypto = require("crypto");
+var import_node_crypto = require("crypto");
 function verifyWebhookSignature(payload, signature, secret) {
   if (!payload || !signature || !secret) {
     return false;
   }
-  const expectedSignature = (0, import_crypto.createHmac)("sha256", secret).update(payload).digest("hex");
+  const expectedSignature = (0, import_node_crypto.createHmac)("sha256", secret).update(payload).digest("hex");
   try {
     const sigBuffer = Buffer.from(signature, "hex");
     const expectedBuffer = Buffer.from(expectedSignature, "hex");
     if (sigBuffer.length !== expectedBuffer.length) {
       return false;
     }
-    return (0, import_crypto.timingSafeEqual)(sigBuffer, expectedBuffer);
+    return (0, import_node_crypto.timingSafeEqual)(sigBuffer, expectedBuffer);
   } catch {
     return false;
   }
@@ -255,7 +339,7 @@ function parseWebhookEvent(body) {
   }
   const event = body;
   if (typeof event.event !== "string") {
-    throw new Error('Invalid webhook body: missing "event" field');
+    throw new TypeError('Invalid webhook body: missing "event" field');
   }
   return {
     event: event.event,
@@ -263,18 +347,66 @@ function parseWebhookEvent(body) {
     data: event.data || {}
   };
 }
+function isPredictionPlacedEvent(event) {
+  return event.event === "prediction.placed";
+}
 function isPredictionSettledEvent(event) {
   return event.event === "prediction.settled";
 }
+function isPredictionVoidedEvent(event) {
+  return event.event === "prediction.voided";
+}
+function isMarketClosedEvent(event) {
+  return event.event === "market.closed";
+}
+function isMarketSettledEvent(event) {
+  return event.event === "market.settled";
+}
+function isDepositConfirmedEvent(event) {
+  return event.event === "deposit.confirmed";
+}
+function isWithdrawalCompletedEvent(event) {
+  return event.event === "withdrawal.completed";
+}
+function isWithdrawalFailedEvent(event) {
+  return event.event === "withdrawal.failed";
+}
+function isLotteryPoolDrawnEvent(event) {
+  return event.event === "lottery.pool.drawn";
+}
+function isLotteryTicketWonEvent(event) {
+  return event.event === "lottery.ticket.won";
+}
 function asPredictionSettledData(event) {
   return event.data;
 }
+function asMarketSettledData(event) {
+  return event.data;
+}
+function asLotteryPoolDrawnData(event) {
+  return event.data;
+}
+function asLotteryTicketWonData(event) {
+  return event.data;
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   PuulError,
   PuulPartner,
+  asLotteryPoolDrawnData,
+  asLotteryTicketWonData,
+  asMarketSettledData,
   asPredictionSettledData,
+  isDepositConfirmedEvent,
+  isLotteryPoolDrawnEvent,
+  isLotteryTicketWonEvent,
+  isMarketClosedEvent,
+  isMarketSettledEvent,
+  isPredictionPlacedEvent,
   isPredictionSettledEvent,
+  isPredictionVoidedEvent,
+  isWithdrawalCompletedEvent,
+  isWithdrawalFailedEvent,
   parseWebhookEvent,
   verifyWebhookSignature
 });

package/dist/index.mjs

@@ -28,6 +28,7 @@ var PuulPartner = class {
     this.markets = new MarketsAPI(this);
     this.predictions = new PredictionsAPI(this);
     this.wallet = new WalletAPI(this);
+    this.lottery = new LotteryAPI(this);
   }
   // ==========================================================
   // Internal HTTP layer
@@ -198,6 +199,77 @@ var WalletAPI = class {
   async getWithdrawalFees(currency, amount) {
     return this.client.request("GET", `/partner/wallet/withdrawal-fees?currency=${currency}&amount=${amount}`);
   }
+  /**
+   * Withdraw from omnibus balance.
+   * Initiates a payout to the partner's configured bank account or crypto wallet.
+   *
+   * @example
+   * ```typescript
+   * const result = await puul.wallet.withdraw({
+   *   amount: 500000, // $5,000 in cents
+   *   currency: 'USDC',
+   *   method: 'bank', // or 'crypto'
+   * });
+   * ```
+   */
+  async withdraw(params) {
+    return this.client.request("POST", "/partner/wallet/withdraw", params);
+  }
+};
+var LotteryAPI = class {
+  constructor(client) {
+    this.client = client;
+  }
+  /** List lottery pools, optionally filtered by status and frequency */
+  async listPools(options) {
+    const params = new URLSearchParams();
+    if (options?.status) params.set("status", options.status);
+    if (options?.frequency) params.set("frequency", options.frequency);
+    if (options?.limit) params.set("limit", String(options.limit));
+    const query = params.toString() ? `?${params.toString()}` : "";
+    return this.client.request("GET", `/partner/lottery/pools${query}`);
+  }
+  /** Get a specific pool by ID */
+  async getPool(poolId) {
+    return this.client.request("GET", `/partner/lottery/pools/${poolId}`);
+  }
+  /**
+   * Buy ticket(s) for a linked user.
+   *
+   * @example
+   * ```typescript
+   * const result = await puul.lottery.buyTicket('pool-uuid', {
+   *   userId: 'puul-user-uuid',
+   *   idempotencyKey: 'lottery-user456-pool1-001',
+   *   quantity: 3,
+   * });
+   * ```
+   */
+  async buyTicket(poolId, params) {
+    return this.client.request("POST", `/partner/lottery/pools/${poolId}/buy`, {
+      user_id: params.userId,
+      idempotency_key: params.idempotencyKey,
+      quantity: params.quantity,
+      user_external_id: params.userExternalId
+    });
+  }
+  /** List lottery entries for your partner account */
+  async listEntries(options) {
+    const params = new URLSearchParams();
+    if (options?.poolId) params.set("pool_id", options.poolId);
+    if (options?.status) params.set("status", options.status);
+    if (options?.limit) params.set("limit", String(options.limit));
+    const query = params.toString() ? `?${params.toString()}` : "";
+    return this.client.request("GET", `/partner/lottery/entries${query}`);
+  }
+  /** Get a single lottery entry by ID */
+  async getEntry(entryId) {
+    return this.client.request("GET", `/partner/lottery/entries/${entryId}`);
+  }
+  /** Get draw results for a completed pool */
+  async getDrawResults(poolId) {
+    return this.client.request("GET", `/partner/lottery/pools/${poolId}/results`);
+  }
 };
 
 // src/webhooks.ts
@@ -224,7 +296,7 @@ function parseWebhookEvent(body) {
   }
   const event = body;
   if (typeof event.event !== "string") {
-    throw new Error('Invalid webhook body: missing "event" field');
+    throw new TypeError('Invalid webhook body: missing "event" field');
   }
   return {
     event: event.event,
@@ -232,17 +304,65 @@ function parseWebhookEvent(body) {
     data: event.data || {}
   };
 }
+function isPredictionPlacedEvent(event) {
+  return event.event === "prediction.placed";
+}
 function isPredictionSettledEvent(event) {
   return event.event === "prediction.settled";
 }
+function isPredictionVoidedEvent(event) {
+  return event.event === "prediction.voided";
+}
+function isMarketClosedEvent(event) {
+  return event.event === "market.closed";
+}
+function isMarketSettledEvent(event) {
+  return event.event === "market.settled";
+}
+function isDepositConfirmedEvent(event) {
+  return event.event === "deposit.confirmed";
+}
+function isWithdrawalCompletedEvent(event) {
+  return event.event === "withdrawal.completed";
+}
+function isWithdrawalFailedEvent(event) {
+  return event.event === "withdrawal.failed";
+}
+function isLotteryPoolDrawnEvent(event) {
+  return event.event === "lottery.pool.drawn";
+}
+function isLotteryTicketWonEvent(event) {
+  return event.event === "lottery.ticket.won";
+}
 function asPredictionSettledData(event) {
   return event.data;
 }
+function asMarketSettledData(event) {
+  return event.data;
+}
+function asLotteryPoolDrawnData(event) {
+  return event.data;
+}
+function asLotteryTicketWonData(event) {
+  return event.data;
+}
 export {
   PuulError,
   PuulPartner,
+  asLotteryPoolDrawnData,
+  asLotteryTicketWonData,
+  asMarketSettledData,
   asPredictionSettledData,
+  isDepositConfirmedEvent,
+  isLotteryPoolDrawnEvent,
+  isLotteryTicketWonEvent,
+  isMarketClosedEvent,
+  isMarketSettledEvent,
+  isPredictionPlacedEvent,
   isPredictionSettledEvent,
+  isPredictionVoidedEvent,
+  isWithdrawalCompletedEvent,
+  isWithdrawalFailedEvent,
   parseWebhookEvent,
   verifyWebhookSignature
 };

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@puul/partner-sdk",
-    "version": "1.0.0",
+    "version": "1.3.0",
     "description": "Official TypeScript SDK for the Puul Partner API — integrate prediction markets into your platform",
     "main": "dist/index.js",
     "module": "dist/index.mjs",
@@ -42,4 +42,4 @@
     "engines": {
         "node": ">=18.0.0"
     }
-}
+}