@puul/partner-sdk 1.0.0

package/README.md

@@ -0,0 +1,208 @@
+# @puul/partner-sdk
+
+Official TypeScript SDK for the **Puul Partner API** — integrate prediction markets into your platform with type safety and zero configuration.
+
+## Features
+
+- 🔐 **Auto-authentication** — OAuth2 token management handled for you
+- 📦 **Zero runtime dependencies** — uses native `fetch` (Node 18+)
+- 🎯 **Fully typed** — complete TypeScript definitions for all API shapes
+- 🪝 **Webhook helpers** — signature verification & typed event parsing
+- ⚡ **Dual output** — ESM + CommonJS builds
+
+## Installation
+
+```bash
+npm install @puul/partner-sdk
+```
+
+## Quick Start
+
+```typescript
+import { PuulPartner } from '@puul/partner-sdk';
+
+const puul = new PuulPartner({
+  clientId: 'pk_live_abc123',
+  clientSecret: 'sk_live_secret789',
+});
+
+// List live markets
+const markets = await puul.markets.list();
+console.log(markets[0].question);
+// → "Will Bitcoin reach $100k by March?"
+
+// Place a prediction
+const prediction = await puul.predictions.place({
+  marketId: markets[0].id,
+  outcomeId: markets[0].outcomes[0].id,
+  stakeAmount: 100000,  // ₦1,000 (minor units)
+  stakeCurrency: 'NGN',
+  idempotencyKey: `pred_${Date.now()}`,
+});
+```
+
+## API Reference
+
+### Authentication
+
+The SDK automatically manages OAuth2 tokens. You never need to call the auth endpoint directly.
+
+```typescript
+const puul = new PuulPartner({
+  clientId: 'pk_live_abc123',
+  clientSecret: 'sk_live_secret789',
+  baseUrl: 'https://api.joinpuul.com/api/v1', // optional
+  timeoutMs: 30000, // optional
+});
+```
+
+### User Linking
+
+```typescript
+// 1. Create a link token (server-side)
+const linkToken = await puul.sessions.createLinkToken({
+  externalUserId: 'your-user-id-123',
+  email: 'user@example.com',     // optional
+  countryCode: 'NG',             // optional
+});
+
+// 2. Exchange link token for a session
+const session = await puul.sessions.create(linkToken.linkToken);
+// session.access_token is scoped to the linked user
+```
+
+### Markets
+
+```typescript
+// All live markets
+const markets = await puul.markets.list();
+
+// Filter by country
+const ngMarkets = await puul.markets.list(['NG', 'GH']);
+```
+
+### Predictions
+
+```typescript
+// Optional: Lock in odds with a quote (10s expiry)
+const quote = await puul.predictions.createQuote({
+  marketId: 'market-uuid',
+  outcomeId: 'outcome-uuid',
+  stakeAmount: 50000,
+  stakeCurrency: 'NGN',
+});
+
+// Place prediction (with or without quote)
+const prediction = await puul.predictions.place({
+  marketId: 'market-uuid',
+  outcomeId: 'outcome-uuid',
+  stakeAmount: 50000,
+  stakeCurrency: 'NGN',
+  idempotencyKey: 'unique-key',
+  quoteId: quote.quoteId, // optional
+});
+
+// Get prediction details
+const details = await puul.predictions.get(prediction.id);
+
+// List user predictions
+const history = await puul.predictions.list({ status: 'OPEN', limit: 20 });
+```
+
+### Pending Predictions (JIT Funding)
+
+```typescript
+// Create a pending prediction — returns bank payment details
+const pending = await puul.predictions.createPending({
+  marketId: 'market-uuid',
+  outcomeId: 'outcome-uuid',
+  stakeAmount: 500000,
+  stakeCurrency: 'NGN',
+  userExternalId: 'your-user-id',
+  idempotencyKey: 'unique-key',
+});
+// pending.paymentReference — use this in the bank transfer
+
+// Check status
+const status = await puul.predictions.getPending(pending.id);
+// status.status: 'pending' → 'funded' → 'placed'
+```
+
+### Wallet
+
+```typescript
+const balance = await puul.wallet.getBalance();
+const omnibus = await puul.wallet.getOmnibusBalance('USDC');
+
+await puul.wallet.deposit({
+  amount: 5000,         // $50.00 in minor units
+  currency: 'USDC',
+  idempotency_key: 'dep_unique_123',
+});
+```
+
+### Webhook Verification
+
+```typescript
+import { verifyWebhookSignature, parseWebhookEvent } from '@puul/partner-sdk';
+
+app.post('/webhooks/puul', express.raw({ type: '*/*' }), (req, res) => {
+  const isValid = verifyWebhookSignature(
+    req.body.toString(),
+    req.headers['x-puul-signature'] as string,
+    process.env.PUUL_WEBHOOK_SECRET!,
+  );
+
+  if (!isValid) {
+    return res.status(401).send('Invalid signature');
+  }
+
+  const event = parseWebhookEvent(JSON.parse(req.body.toString()));
+
+  switch (event.event) {
+    case 'prediction.settled':
+      console.log('Prediction settled:', event.data);
+      break;
+    case 'deposit.confirmed':
+      console.log('Deposit confirmed:', event.data);
+      break;
+  }
+
+  res.status(200).send('OK');
+});
+```
+
+## Error Handling
+
+All API errors throw a `PuulError` with structured details:
+
+```typescript
+import { PuulError } from '@puul/partner-sdk';
+
+try {
+  await puul.predictions.place(params);
+} catch (error) {
+  if (error instanceof PuulError) {
+    console.error(error.code);       // 'INSUFFICIENT_BALANCE'
+    console.error(error.message);    // 'Insufficient wallet balance'
+    console.error(error.statusCode); // 400
+    console.error(error.requestId);  // 'req_abc123'
+    console.error(error.retryable);  // false
+  }
+}
+```
+
+## Supported Currencies
+
+| Code | Currency |
+|------|----------|
+| `NGN` | Nigerian Naira |
+| `USDC` | USD Coin |
+| `USDT` | Tether |
+| `KES` | Kenyan Shilling |
+| `GHS` | Ghanaian Cedi |
+| `ZAR` | South African Rand |
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,339 @@
+interface PuulPartnerConfig {
+    /** Your partner client ID */
+    clientId: string;
+    /** Your partner client secret */
+    clientSecret: string;
+    /** Base URL for the Puul API. Defaults to https://api.joinpuul.com/api/v1 */
+    baseUrl?: string;
+    /** Request timeout in ms. Defaults to 30000 */
+    timeoutMs?: number;
+}
+interface AccessTokenResponse {
+    access_token: string;
+    token_type: string;
+    expires_in: number;
+}
+interface CreateLinkTokenParams {
+    externalUserId: string;
+    email?: string;
+    phone?: string;
+    countryCode?: string;
+}
+interface LinkTokenResponse {
+    linkToken: string;
+    expiresAt: string;
+}
+interface SessionResponse {
+    access_token: string;
+    token_type: string;
+    expires_in: number;
+    user_id: string;
+}
+interface MarketOutcome {
+    id: string;
+    slug: string;
+    label: string;
+    pool: {
+        pool_amount: string;
+        total_bets: number;
+    };
+}
+interface Market {
+    id: string;
+    question: string;
+    description: string;
+    category: string;
+    status: string;
+    currency: string;
+    close_time: string;
+    freeze_at: string | null;
+    target_countries: string[];
+    outcomes: MarketOutcome[];
+}
+type PredictionStatus = 'OPEN' | 'WON' | 'LOST' | 'VOIDED';
+type Currency = 'NGN' | 'USDC' | 'USDT' | 'KES' | 'GHS' | 'ZAR';
+interface PlacePredictionParams {
+    marketId: string;
+    outcomeId: string;
+    stakeAmount: number;
+    stakeCurrency: Currency;
+    idempotencyKey: string;
+    /** Optional quote ID for slippage protection */
+    quoteId?: string;
+    /** Optional FX quote ID */
+    fxQuoteId?: string;
+    /** Max slippage in basis points (100 = 1%) */
+    maxSlippageBps?: number;
+}
+interface CreateQuoteParams {
+    marketId: string;
+    outcomeId: string;
+    stakeAmount: number;
+    stakeCurrency: Currency;
+}
+interface QuoteResponse {
+    quoteId: string;
+    estimatedReturn: number;
+    multiplier: string;
+    expiresAt: string;
+}
+interface Prediction {
+    id: string;
+    market_id: string;
+    market_question: string | null;
+    market_close_time: string | null;
+    market_freeze_at: string | null;
+    outcome_id: string;
+    outcome_slug: string | null;
+    outcome_label: string | null;
+    user_external_id: string | null;
+    stake_amount: string;
+    stake_currency: string;
+    status: PredictionStatus;
+    estimated_return: string;
+    live_estimated_return: string | number;
+    estimated_multiplier: string;
+    final_return: string | null;
+    final_multiplier: string | null;
+    placed_at: string;
+    idempotency_key: string;
+}
+interface PredictionListResponse {
+    predictions: Prediction[];
+    total: number;
+    limit: number;
+}
+interface CreatePendingPredictionParams {
+    marketId: string;
+    outcomeId?: string;
+    /** @deprecated Use outcomeId for multi-outcome markets */
+    side?: 'YES' | 'NO';
+    stakeAmount: number;
+    stakeCurrency: Currency;
+    userExternalId: string;
+    idempotencyKey: string;
+    maxSlippageBps?: number;
+    /** TTL in seconds. Default: 300 */
+    ttlSeconds?: number;
+}
+interface PendingPrediction {
+    id: string;
+    status: string;
+    userExternalId: string;
+    marketId: string;
+    outcomeId: string | null;
+    side: string | null;
+    stakeAmount: number;
+    stakeCurrency: string;
+    paymentReference: string;
+    expiresAt: string;
+    predictionId: string | null;
+    createdAt: string;
+    fundedAt: string | null;
+    placedAt: string | null;
+    errorMessage: string | null;
+}
+interface WalletBalance {
+    balance: number;
+    currency: string;
+}
+interface DepositAccountInfo {
+    accountNumber: string;
+    accountName: string;
+    bankName: string;
+    currency: string;
+}
+interface DepositParams {
+    amount: number;
+    currency?: string;
+    idempotency_key: string;
+    reference?: string;
+}
+type WebhookEventType = 'prediction.settled' | 'deposit.confirmed' | 'withdrawal.completed';
+interface WebhookEvent<T = {
+    [key: string]: unknown;
+}> {
+    event: WebhookEventType;
+    timestamp: string;
+    data: T;
+}
+interface PredictionSettledData {
+    prediction_id: string;
+    market_id: string;
+    outcome_id: string;
+    outcome_slug: string;
+    user_external_id: string;
+    status: 'WON' | 'LOST' | 'VOIDED';
+    stake_amount: string;
+    stake_currency: string;
+    final_return: string;
+    settled_at: string;
+}
+interface PuulApiError {
+    statusCode: number;
+    message: string | string[];
+    code: string;
+    requestId?: string;
+    details?: unknown;
+    retryable?: boolean;
+}
+declare class PuulError extends Error {
+    readonly statusCode: number;
+    readonly code: string;
+    readonly requestId?: string;
+    readonly details?: unknown;
+    readonly retryable: boolean;
+    constructor(apiError: PuulApiError);
+}
+
+/**
+ * Official Puul Partner SDK client.
+ *
+ * Zero runtime dependencies — uses native `fetch` (Node 18+).
+ *
+ * @example
+ * ```typescript
+ * import { PuulPartner } from '@puul/partner-sdk';
+ *
+ * const puul = new PuulPartner({
+ *   clientId: 'pk_live_abc123',
+ *   clientSecret: 'sk_live_secret789',
+ * });
+ *
+ * // List markets
+ * const markets = await puul.markets.list();
+ *
+ * // Place a prediction
+ * const prediction = await puul.predictions.place({
+ *   marketId: markets[0].id,
+ *   outcomeId: markets[0].outcomes[0].id,
+ *   stakeAmount: 100000,
+ *   stakeCurrency: 'NGN',
+ *   idempotencyKey: 'unique-key-123',
+ * });
+ * ```
+ */
+declare class PuulPartner {
+    private readonly config;
+    private tokenCache;
+    readonly sessions: SessionsAPI;
+    readonly markets: MarketsAPI;
+    readonly predictions: PredictionsAPI;
+    readonly wallet: WalletAPI;
+    constructor(config: PuulPartnerConfig);
+    /** Get a valid access token, refreshing if needed */
+    getAccessToken(): Promise<string>;
+    /** Authenticated request */
+    request<T>(method: string, path: string, body?: unknown): Promise<T>;
+    /** Raw HTTP request */
+    private rawRequest;
+}
+declare class SessionsAPI {
+    private readonly client;
+    constructor(client: PuulPartner);
+    /** Create a link token for user linking */
+    createLinkToken(params: CreateLinkTokenParams): Promise<LinkTokenResponse>;
+    /** Exchange a link token for a user session */
+    create(linkToken: string): Promise<SessionResponse>;
+}
+declare class MarketsAPI {
+    private readonly client;
+    constructor(client: PuulPartner);
+    /** List all live markets, optionally filtered by country */
+    list(countries?: string[]): Promise<Market[]>;
+}
+declare class PredictionsAPI {
+    private readonly client;
+    constructor(client: PuulPartner);
+    /** Create a binding quote for slippage protection (expires in 10s) */
+    createQuote(params: CreateQuoteParams): Promise<QuoteResponse>;
+    /** Place a prediction on a market outcome */
+    place(params: PlacePredictionParams): Promise<Prediction>;
+    /** Get a specific prediction by ID */
+    get(predictionId: string): Promise<Prediction>;
+    /** List user predictions with optional filters */
+    list(options?: {
+        status?: PredictionStatus;
+        limit?: number;
+    }): Promise<PredictionListResponse>;
+    /** Create a pending prediction (JIT funding flow) */
+    createPending(params: CreatePendingPredictionParams): Promise<PendingPrediction>;
+    /** Get pending prediction status */
+    getPending(pendingId: string): Promise<PendingPrediction>;
+}
+declare class WalletAPI {
+    private readonly client;
+    constructor(client: PuulPartner);
+    /** Get partner deposit account details */
+    getDepositAccount(): Promise<DepositAccountInfo>;
+    /** Get user wallet balance */
+    getBalance(): Promise<WalletBalance>;
+    /** Get omnibus wallet balance */
+    getOmnibusBalance(currency?: string): Promise<WalletBalance>;
+    /** Deposit funds to a linked user wallet */
+    deposit(params: DepositParams): Promise<unknown>;
+    /** Get withdrawal fee estimate */
+    getWithdrawalFees(currency: string, amount: number): Promise<unknown>;
+}
+
+/**
+ * Verify a webhook signature from Puul.
+ *
+ * @param payload - The raw request body as a string
+ * @param signature - The value of the X-Puul-Signature header
+ * @param secret - Your webhook secret
+ * @returns true if the signature is valid
+ *
+ * @example
+ * ```typescript
+ * import { verifyWebhookSignature } from '@puul/partner-sdk';
+ *
+ * app.post('/webhooks/puul', (req, res) => {
+ *   const isValid = verifyWebhookSignature(
+ *     req.body, // raw string body
+ *     req.headers['x-puul-signature'],
+ *     process.env.PUUL_WEBHOOK_SECRET,
+ *   );
+ *
+ *   if (!isValid) {
+ *     return res.status(401).send('Invalid signature');
+ *   }
+ *
+ *   // Process the event...
+ *   res.status(200).send('OK');
+ * });
+ * ```
+ */
+declare function verifyWebhookSignature(payload: string, signature: string, secret: string): boolean;
+/**
+ * Parse and type a webhook event body.
+ *
+ * @param body - The parsed JSON body of the webhook request
+ * @returns A typed WebhookEvent object
+ *
+ * @example
+ * ```typescript
+ * import { parseWebhookEvent } from '@puul/partner-sdk';
+ *
+ * const event = parseWebhookEvent(req.body);
+ *
+ * if (event.event === 'prediction.settled') {
+ *   const { prediction_id, status, final_return } = 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;
+/**
+ * Convenience cast for prediction.settled event data.
+ * Call after verifying with `isPredictionSettledEvent`.
+ */
+declare function asPredictionSettledData(event: WebhookEvent): PredictionSettledData;
+
+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 };