@puul/partner-sdk 1.2.0 → 1.4.0

package/dist/index.d.mts

@@ -63,6 +63,10 @@ interface PlacePredictionParams {
     stakeAmount: number;
     stakeCurrency: Currency;
     idempotencyKey: string;
+    /** Linked Puul user UUID (provide userId or userExternalId) */
+    userId?: string;
+    /** Your linked external user ID (provide userId or userExternalId) */
+    userExternalId?: string;
     /** Optional quote ID for slippage protection */
     quoteId?: string;
     /** Optional FX quote ID */
@@ -75,6 +79,10 @@ interface CreateQuoteParams {
     outcomeId: string;
     stakeAmount: number;
     stakeCurrency: Currency;
+    /** Linked Puul user UUID (provide userId or userExternalId) */
+    userId?: string;
+    /** Your linked external user ID (provide userId or userExternalId) */
+    userExternalId?: string;
 }
 interface QuoteResponse {
     quoteId: string;
@@ -153,6 +161,10 @@ interface DepositParams {
     currency?: string;
     idempotency_key: string;
     reference?: string;
+    /** Linked Puul user UUID (provide userId or userExternalId) */
+    userId?: string;
+    /** Your linked external user ID (provide userId or userExternalId) */
+    userExternalId?: string;
 }
 type WithdrawMethod = 'bank' | 'crypto';
 interface WithdrawParams {
@@ -172,7 +184,85 @@ interface WithdrawResult {
     payoutReference: string | null;
     status: string;
 }
-type WebhookEventType = 'user.created' | 'prediction.placed' | 'prediction.settled' | 'prediction.voided' | 'market.closed' | 'market.settled' | 'deposit.confirmed' | 'withdrawal.completed' | 'withdrawal.failed';
+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 UUID (provide userId or userExternalId) */
+    userId?: string;
+    /** Unique key to prevent duplicate purchases */
+    idempotencyKey: string;
+    /** Number of tickets (default: 1) */
+    quantity?: number;
+    /** Your linked external user ID (provide userId or userExternalId) */
+    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;
@@ -284,6 +374,30 @@ interface WithdrawalFailedData {
     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[];
@@ -335,6 +449,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>;
@@ -370,6 +485,8 @@ declare class PredictionsAPI {
     list(options?: {
         status?: PredictionStatus;
         limit?: number;
+        userId?: string;
+        userExternalId?: string;
     }): Promise<PredictionListResponse>;
     /** Create a pending prediction (JIT funding flow) */
     createPending(params: CreatePendingPredictionParams): Promise<PendingPrediction>;
@@ -404,6 +521,41 @@ declare class WalletAPI {
      */
     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>;
+}
 
 /**
  * Verify a webhook signature from Puul.
@@ -469,6 +621,10 @@ declare function isDepositConfirmedEvent(event: WebhookEvent): event is WebhookE
 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`.
@@ -479,5 +635,15 @@ declare function asPredictionSettledData(event: WebhookEvent): PredictionSettled
  * 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 DepositConfirmedData, type DepositParams, type LinkTokenResponse, 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 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, asMarketSettledData, asPredictionSettledData, isDepositConfirmedEvent, isMarketClosedEvent, isMarketSettledEvent, isPredictionPlacedEvent, isPredictionSettledEvent, isPredictionVoidedEvent, isWithdrawalCompletedEvent, isWithdrawalFailedEvent, 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

@@ -63,6 +63,10 @@ interface PlacePredictionParams {
     stakeAmount: number;
     stakeCurrency: Currency;
     idempotencyKey: string;
+    /** Linked Puul user UUID (provide userId or userExternalId) */
+    userId?: string;
+    /** Your linked external user ID (provide userId or userExternalId) */
+    userExternalId?: string;
     /** Optional quote ID for slippage protection */
     quoteId?: string;
     /** Optional FX quote ID */
@@ -75,6 +79,10 @@ interface CreateQuoteParams {
     outcomeId: string;
     stakeAmount: number;
     stakeCurrency: Currency;
+    /** Linked Puul user UUID (provide userId or userExternalId) */
+    userId?: string;
+    /** Your linked external user ID (provide userId or userExternalId) */
+    userExternalId?: string;
 }
 interface QuoteResponse {
     quoteId: string;
@@ -153,6 +161,10 @@ interface DepositParams {
     currency?: string;
     idempotency_key: string;
     reference?: string;
+    /** Linked Puul user UUID (provide userId or userExternalId) */
+    userId?: string;
+    /** Your linked external user ID (provide userId or userExternalId) */
+    userExternalId?: string;
 }
 type WithdrawMethod = 'bank' | 'crypto';
 interface WithdrawParams {
@@ -172,7 +184,85 @@ interface WithdrawResult {
     payoutReference: string | null;
     status: string;
 }
-type WebhookEventType = 'user.created' | 'prediction.placed' | 'prediction.settled' | 'prediction.voided' | 'market.closed' | 'market.settled' | 'deposit.confirmed' | 'withdrawal.completed' | 'withdrawal.failed';
+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 UUID (provide userId or userExternalId) */
+    userId?: string;
+    /** Unique key to prevent duplicate purchases */
+    idempotencyKey: string;
+    /** Number of tickets (default: 1) */
+    quantity?: number;
+    /** Your linked external user ID (provide userId or userExternalId) */
+    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;
@@ -284,6 +374,30 @@ interface WithdrawalFailedData {
     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[];
@@ -335,6 +449,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>;
@@ -370,6 +485,8 @@ declare class PredictionsAPI {
     list(options?: {
         status?: PredictionStatus;
         limit?: number;
+        userId?: string;
+        userExternalId?: string;
     }): Promise<PredictionListResponse>;
     /** Create a pending prediction (JIT funding flow) */
     createPending(params: CreatePendingPredictionParams): Promise<PendingPrediction>;
@@ -404,6 +521,41 @@ declare class WalletAPI {
      */
     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>;
+}
 
 /**
  * Verify a webhook signature from Puul.
@@ -469,6 +621,10 @@ declare function isDepositConfirmedEvent(event: WebhookEvent): event is WebhookE
 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`.
@@ -479,5 +635,15 @@ declare function asPredictionSettledData(event: WebhookEvent): PredictionSettled
  * 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 DepositConfirmedData, type DepositParams, type LinkTokenResponse, 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 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, asMarketSettledData, asPredictionSettledData, isDepositConfirmedEvent, isMarketClosedEvent, isMarketSettledEvent, isPredictionPlacedEvent, isPredictionSettledEvent, isPredictionVoidedEvent, isWithdrawalCompletedEvent, isWithdrawalFailedEvent, 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,9 +22,13 @@ 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,
@@ -67,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
@@ -185,11 +190,21 @@ var PredictionsAPI = class {
   }
   /** Create a binding quote for slippage protection (expires in 10s) */
   async createQuote(params) {
-    return this.client.request("POST", "/partner/predictions/quote", params);
+    const { userId, userExternalId, ...rest } = params;
+    return this.client.request("POST", "/partner/predictions/quote", {
+      ...rest,
+      user_id: userId,
+      user_external_id: userExternalId
+    });
   }
   /** Place a prediction on a market outcome */
   async place(params) {
-    return this.client.request("POST", "/partner/predictions", params);
+    const { userId, userExternalId, ...rest } = params;
+    return this.client.request("POST", "/partner/predictions", {
+      ...rest,
+      user_id: userId,
+      user_external_id: userExternalId
+    });
   }
   /** Get a specific prediction by ID */
   async get(predictionId) {
@@ -200,6 +215,8 @@ var PredictionsAPI = class {
     const params = new URLSearchParams();
     if (options?.status) params.set("status", options.status);
     if (options?.limit) params.set("limit", String(options.limit));
+    if (options?.userId) params.set("user_id", options.userId);
+    if (options?.userExternalId) params.set("user_external_id", options.userExternalId);
     const query = params.toString() ? `?${params.toString()}` : "";
     return this.client.request("GET", `/partner/predictions${query}`);
   }
@@ -231,7 +248,12 @@ var WalletAPI = class {
   }
   /** Deposit funds to a linked user wallet */
   async deposit(params) {
-    return this.client.request("POST", "/partner/wallet/deposit", params);
+    const { userId, userExternalId, ...rest } = params;
+    return this.client.request("POST", "/partner/wallet/deposit", {
+      ...rest,
+      user_id: userId,
+      user_external_id: userExternalId
+    });
   }
   /** Get withdrawal fee estimate */
   async getWithdrawalFees(currency, amount) {
@@ -254,21 +276,76 @@ var WalletAPI = class {
     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;
   }
@@ -279,7 +356,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,
@@ -311,19 +388,35 @@ function isWithdrawalCompletedEvent(event) {
 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,

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
@@ -146,11 +147,21 @@ var PredictionsAPI = class {
   }
   /** Create a binding quote for slippage protection (expires in 10s) */
   async createQuote(params) {
-    return this.client.request("POST", "/partner/predictions/quote", params);
+    const { userId, userExternalId, ...rest } = params;
+    return this.client.request("POST", "/partner/predictions/quote", {
+      ...rest,
+      user_id: userId,
+      user_external_id: userExternalId
+    });
   }
   /** Place a prediction on a market outcome */
   async place(params) {
-    return this.client.request("POST", "/partner/predictions", params);
+    const { userId, userExternalId, ...rest } = params;
+    return this.client.request("POST", "/partner/predictions", {
+      ...rest,
+      user_id: userId,
+      user_external_id: userExternalId
+    });
   }
   /** Get a specific prediction by ID */
   async get(predictionId) {
@@ -161,6 +172,8 @@ var PredictionsAPI = class {
     const params = new URLSearchParams();
     if (options?.status) params.set("status", options.status);
     if (options?.limit) params.set("limit", String(options.limit));
+    if (options?.userId) params.set("user_id", options.userId);
+    if (options?.userExternalId) params.set("user_external_id", options.userExternalId);
     const query = params.toString() ? `?${params.toString()}` : "";
     return this.client.request("GET", `/partner/predictions${query}`);
   }
@@ -192,7 +205,12 @@ var WalletAPI = class {
   }
   /** Deposit funds to a linked user wallet */
   async deposit(params) {
-    return this.client.request("POST", "/partner/wallet/deposit", params);
+    const { userId, userExternalId, ...rest } = params;
+    return this.client.request("POST", "/partner/wallet/deposit", {
+      ...rest,
+      user_id: userId,
+      user_external_id: userExternalId
+    });
   }
   /** Get withdrawal fee estimate */
   async getWithdrawalFees(currency, amount) {
@@ -215,6 +233,61 @@ var WalletAPI = class {
     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
 import { createHmac, timingSafeEqual } from "crypto";
@@ -240,7 +313,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,
@@ -272,18 +345,34 @@ function isWithdrawalCompletedEvent(event) {
 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,

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@puul/partner-sdk",
-    "version": "1.2.0",
+    "version": "1.4.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"
     }
-}
+}