@puul/partner-sdk 1.0.0

package/dist/index.d.ts

@@ -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 };

package/dist/index.js

@@ -0,0 +1,280 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  PuulError: () => PuulError,
+  PuulPartner: () => PuulPartner,
+  asPredictionSettledData: () => asPredictionSettledData,
+  isPredictionSettledEvent: () => isPredictionSettledEvent,
+  parseWebhookEvent: () => parseWebhookEvent,
+  verifyWebhookSignature: () => verifyWebhookSignature
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/types.ts
+var PuulError = class extends Error {
+  constructor(apiError) {
+    const msg = Array.isArray(apiError.message) ? apiError.message.join(", ") : apiError.message;
+    super(msg);
+    this.name = "PuulError";
+    this.statusCode = apiError.statusCode;
+    this.code = apiError.code;
+    this.requestId = apiError.requestId;
+    this.details = apiError.details;
+    this.retryable = apiError.retryable ?? false;
+  }
+};
+
+// src/client.ts
+var DEFAULT_BASE_URL = "https://api.joinpuul.com/api/v1";
+var DEFAULT_TIMEOUT_MS = 3e4;
+var PuulPartner = class {
+  constructor(config) {
+    this.tokenCache = null;
+    this.config = {
+      clientId: config.clientId,
+      clientSecret: config.clientSecret,
+      baseUrl: (config.baseUrl || DEFAULT_BASE_URL).replace(/\/$/, ""),
+      timeoutMs: config.timeoutMs ?? DEFAULT_TIMEOUT_MS
+    };
+    this.sessions = new SessionsAPI(this);
+    this.markets = new MarketsAPI(this);
+    this.predictions = new PredictionsAPI(this);
+    this.wallet = new WalletAPI(this);
+  }
+  // ==========================================================
+  // Internal HTTP layer
+  // ==========================================================
+  /** Get a valid access token, refreshing if needed */
+  async getAccessToken() {
+    if (this.tokenCache && Date.now() < this.tokenCache.expiresAt - 3e4) {
+      return this.tokenCache.accessToken;
+    }
+    const response = await this.rawRequest(
+      "POST",
+      "/partner/oauth/token",
+      {
+        client_id: this.config.clientId,
+        client_secret: this.config.clientSecret,
+        grant_type: "client_credentials"
+      },
+      false
+      // Don't use auth for the auth endpoint itself
+    );
+    this.tokenCache = {
+      accessToken: response.access_token,
+      expiresAt: Date.now() + response.expires_in * 1e3
+    };
+    return this.tokenCache.accessToken;
+  }
+  /** Authenticated request */
+  async request(method, path, body) {
+    return this.rawRequest(method, path, body, true);
+  }
+  /** Raw HTTP request */
+  async rawRequest(method, path, body, authenticate = true) {
+    const url = `${this.config.baseUrl}${path}`;
+    const headers = {
+      "Content-Type": "application/json",
+      "Accept": "application/json"
+    };
+    if (authenticate) {
+      const token = await this.getAccessToken();
+      headers["Authorization"] = `Bearer ${token}`;
+    }
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), this.config.timeoutMs);
+    try {
+      const response = await fetch(url, {
+        method,
+        headers,
+        body: body ? JSON.stringify(body) : void 0,
+        signal: controller.signal
+      });
+      const responseBody = await response.text();
+      let parsed;
+      try {
+        parsed = JSON.parse(responseBody);
+      } catch {
+        if (!response.ok) {
+          throw new PuulError({
+            statusCode: response.status,
+            message: responseBody || response.statusText,
+            code: "UNKNOWN_ERROR"
+          });
+        }
+        return responseBody;
+      }
+      if (!response.ok) {
+        throw new PuulError(parsed);
+      }
+      return parsed;
+    } catch (error) {
+      if (error instanceof PuulError) throw error;
+      if (error instanceof Error && error.name === "AbortError") {
+        throw new PuulError({
+          statusCode: 0,
+          message: `Request timed out after ${this.config.timeoutMs}ms`,
+          code: "REQUEST_TIMEOUT",
+          retryable: true
+        });
+      }
+      throw new PuulError({
+        statusCode: 0,
+        message: error instanceof Error ? error.message : "Unknown network error",
+        code: "NETWORK_ERROR",
+        retryable: true
+      });
+    } finally {
+      clearTimeout(timeout);
+    }
+  }
+};
+var SessionsAPI = class {
+  constructor(client) {
+    this.client = client;
+  }
+  /** Create a link token for user linking */
+  async createLinkToken(params) {
+    return this.client.request("POST", "/partner/link-tokens", params);
+  }
+  /** Exchange a link token for a user session */
+  async create(linkToken) {
+    return this.client.request("POST", "/partner/sessions", { linkToken });
+  }
+};
+var MarketsAPI = class {
+  constructor(client) {
+    this.client = client;
+  }
+  /** List all live markets, optionally filtered by country */
+  async list(countries) {
+    const query = countries?.length ? `?countries=${countries.join(",")}` : "";
+    return this.client.request("GET", `/partner/markets${query}`);
+  }
+};
+var PredictionsAPI = class {
+  constructor(client) {
+    this.client = client;
+  }
+  /** Create a binding quote for slippage protection (expires in 10s) */
+  async createQuote(params) {
+    return this.client.request("POST", "/partner/predictions/quote", params);
+  }
+  /** Place a prediction on a market outcome */
+  async place(params) {
+    return this.client.request("POST", "/partner/predictions", params);
+  }
+  /** Get a specific prediction by ID */
+  async get(predictionId) {
+    return this.client.request("GET", `/partner/predictions/${predictionId}`);
+  }
+  /** List user predictions with optional filters */
+  async list(options) {
+    const params = new URLSearchParams();
+    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/predictions${query}`);
+  }
+  /** Create a pending prediction (JIT funding flow) */
+  async createPending(params) {
+    return this.client.request("POST", "/partner/predictions/pending", params);
+  }
+  /** Get pending prediction status */
+  async getPending(pendingId) {
+    return this.client.request("GET", `/partner/predictions/pending/${pendingId}`);
+  }
+};
+var WalletAPI = class {
+  constructor(client) {
+    this.client = client;
+  }
+  /** Get partner deposit account details */
+  async getDepositAccount() {
+    return this.client.request("GET", "/partner/wallet/deposit-account");
+  }
+  /** Get user wallet balance */
+  async getBalance() {
+    return this.client.request("GET", "/partner/wallet/balance");
+  }
+  /** Get omnibus wallet balance */
+  async getOmnibusBalance(currency) {
+    const query = currency ? `?currency=${currency}` : "";
+    return this.client.request("GET", `/partner/wallet/omnibus-balance${query}`);
+  }
+  /** Deposit funds to a linked user wallet */
+  async deposit(params) {
+    return this.client.request("POST", "/partner/wallet/deposit", params);
+  }
+  /** Get withdrawal fee estimate */
+  async getWithdrawalFees(currency, amount) {
+    return this.client.request("GET", `/partner/wallet/withdrawal-fees?currency=${currency}&amount=${amount}`);
+  }
+};
+
+// src/webhooks.ts
+var import_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");
+  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);
+  } catch {
+    return false;
+  }
+}
+function parseWebhookEvent(body) {
+  if (!body || typeof body !== "object") {
+    throw new Error("Invalid webhook body: expected an object");
+  }
+  const event = body;
+  if (typeof event.event !== "string") {
+    throw new Error('Invalid webhook body: missing "event" field');
+  }
+  return {
+    event: event.event,
+    timestamp: event.timestamp || (/* @__PURE__ */ new Date()).toISOString(),
+    data: event.data || {}
+  };
+}
+function isPredictionSettledEvent(event) {
+  return event.event === "prediction.settled";
+}
+function asPredictionSettledData(event) {
+  return event.data;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  PuulError,
+  PuulPartner,
+  asPredictionSettledData,
+  isPredictionSettledEvent,
+  parseWebhookEvent,
+  verifyWebhookSignature
+});