@sphoq/payments 0.1.0 → 0.2.0

package/dist/client.d.ts

@@ -1,13 +1,152 @@
 import type { SphoqPaymentsOptions, CreateChargeOptions, Charge, GetChargeOptions, CancelChargeOptions, CancelChargeResult, VerifyWebhookOptions } from "./types.js";
+/**
+ * Sphoq Payments SDK client.
+ *
+ * Provides methods for creating and managing PIX charges, and verifying webhook signatures.
+ * Zero dependencies — uses native `fetch` and Web Crypto API.
+ *
+ * @example Basic setup
+ * ```ts
+ * import { SphoqPayments } from "@sphoq/payments";
+ *
+ * const sphoq = new SphoqPayments({
+ *   apiKey: "spk_live_abc123...",
+ *   baseUrl: "https://your-deployment.convex.site",
+ * });
+ * ```
+ *
+ * @example Create a PIX charge and display QR code
+ * ```ts
+ * const charge = await sphoq.charges.create({
+ *   amount: 49.90,
+ *   description: "Premium Plan",
+ *   externalId: "order_123",
+ *   customer: { name: "João Silva", cpf: "12345678900" },
+ * });
+ *
+ * // Show QR code to user (base64 PNG)
+ * document.getElementById("qr").src = `data:image/png;base64,${charge.qrCode}`;
+ *
+ * // Or show the copy-paste PIX string
+ * console.log(charge.pixCopiaECola);
+ * ```
+ *
+ * @example Convex integration — reactive payment status
+ * ```ts
+ * // convex/http.ts — Receive Sphoq webhooks
+ * import { SphoqPayments, type WebhookPayload } from "@sphoq/payments";
+ *
+ * http.route({
+ *   path: "/webhooks/sphoq",
+ *   method: "POST",
+ *   handler: httpAction(async (ctx, req) => {
+ *     const body = await req.text();
+ *     const signature = req.headers.get("x-sphoq-signature")!;
+ *
+ *     const isValid = await SphoqPayments.verifyWebhookSignature({
+ *       payload: body,
+ *       signature,
+ *       secret: process.env.SPHOQ_WEBHOOK_SECRET!,
+ *     });
+ *     if (!isValid) return new Response("Invalid signature", { status: 401 });
+ *
+ *     const event: WebhookPayload = JSON.parse(body);
+ *     if (event.type === "charge.paid") {
+ *       await ctx.runMutation(internal.orders.markAsPaid, {
+ *         orderId: event.data.externalId,
+ *       });
+ *     }
+ *     return new Response("OK");
+ *   }),
+ * });
+ *
+ * // React component — auto-updates when webhook triggers the mutation
+ * function CheckoutPage({ orderId }: { orderId: string }) {
+ *   const order = useQuery(api.orders.get, { orderId });
+ *   // order.status reactively updates from "pending" to "paid"
+ *   // when the Sphoq webhook triggers markAsPaid mutation
+ * }
+ * ```
+ */
 export declare class SphoqPayments {
     private readonly apiKey;
     private readonly baseUrl;
+    /**
+     * Client for creating, querying, and cancelling PIX charges.
+     *
+     * @example
+     * ```ts
+     * // Create a charge
+     * const charge = await sphoq.charges.create({
+     *   amount: 29.90,
+     *   description: "Monthly subscription",
+     * });
+     *
+     * // Query a charge
+     * const status = await sphoq.charges.get({ id: charge.id });
+     *
+     * // Cancel a pending charge
+     * await sphoq.charges.cancel({ id: charge.id });
+     * ```
+     */
     readonly charges: ChargesClient;
+    /**
+     * Creates a new Sphoq Payments client.
+     *
+     * @param options - Client configuration (API key and base URL).
+     *
+     * @example
+     * ```ts
+     * const sphoq = new SphoqPayments({
+     *   apiKey: process.env.SPHOQ_API_KEY!,
+     *   baseUrl: process.env.SPHOQ_BASE_URL!,
+     * });
+     * ```
+     */
     constructor(options: SphoqPaymentsOptions);
     /**
-     * Verify a webhook signature to ensure it came from Sphoq.
+     * Verify a webhook signature to ensure the request came from Sphoq.
+     *
+     * Uses HMAC-SHA256 with constant-time comparison to prevent timing attacks.
+     * Works in all JavaScript runtimes: Node.js 18+, Deno, Cloudflare Workers,
+     * Vercel Edge, and Convex.
+     *
+     * **Important:** Always verify signatures before processing webhook payloads.
+     * Use the raw request body string — do not parse it before verification.
+     *
+     * @param options - The raw payload, signature header, and your webhook secret.
+     * @returns `true` if the signature is valid, `false` otherwise.
      *
-     * Works in both Node.js (using crypto module) and edge runtimes (using Web Crypto API).
+     * @example Node.js / Express
+     * ```ts
+     * app.post("/webhooks/sphoq", express.raw({ type: "*\/*" }), async (req, res) => {
+     *   const isValid = await SphoqPayments.verifyWebhookSignature({
+     *     payload: req.body.toString(),
+     *     signature: req.headers["x-sphoq-signature"] as string,
+     *     secret: process.env.SPHOQ_WEBHOOK_SECRET!,
+     *   });
+     *
+     *   if (!isValid) return res.status(401).send("Invalid signature");
+     *
+     *   const event = JSON.parse(req.body.toString());
+     *   // Handle event...
+     *   res.sendStatus(200);
+     * });
+     * ```
+     *
+     * @example Convex httpAction
+     * ```ts
+     * const handler = httpAction(async (ctx, req) => {
+     *   const body = await req.text();
+     *   const isValid = await SphoqPayments.verifyWebhookSignature({
+     *     payload: body,
+     *     signature: req.headers.get("x-sphoq-signature")!,
+     *     secret: process.env.SPHOQ_WEBHOOK_SECRET!,
+     *   });
+     *   if (!isValid) return new Response("Invalid", { status: 401 });
+     *   // Process the webhook...
+     * });
+     * ```
      */
     static verifyWebhookSignature(options: VerifyWebhookOptions): Promise<boolean>;
 }
@@ -15,8 +154,82 @@ declare class ChargesClient {
     private readonly apiKey;
     private readonly baseUrl;
     constructor(apiKey: string, baseUrl: string);
+    /**
+     * Create a new PIX charge.
+     *
+     * Generates a PIX QR code and copy-paste string that the customer can use to pay.
+     * The charge starts with `status: "pending"` and transitions to `"paid"` when
+     * the customer completes the payment.
+     *
+     * @param options - Charge details (amount, description, customer info, etc.).
+     * @returns The created charge with QR code data.
+     * @throws {@link SphoqApiError} if the API returns an error (invalid params, rate limit, etc.).
+     *
+     * @example Simple charge
+     * ```ts
+     * const charge = await sphoq.charges.create({
+     *   amount: 29.90,
+     *   description: "Monthly subscription",
+     * });
+     * console.log(charge.pixCopiaECola); // PIX copy-paste string
+     * ```
+     *
+     * @example Full options
+     * ```ts
+     * const charge = await sphoq.charges.create({
+     *   amount: 149.90,
+     *   description: "Annual Plan",
+     *   externalId: "order_abc123",
+     *   customer: {
+     *     name: "Maria Santos",
+     *     email: "maria@example.com",
+     *     cpf: "12345678900",
+     *   },
+     *   expirationSeconds: 1800, // 30 minutes
+     *   metadata: { planId: "annual", coupon: "SAVE20" },
+     * });
+     * ```
+     */
     create(options: CreateChargeOptions): Promise<Charge>;
+    /**
+     * Retrieve an existing charge by Sphoq ID or your external ID.
+     *
+     * At least one of `id` or `externalId` must be provided.
+     *
+     * @param options - Lookup criteria (Sphoq ID or external ID).
+     * @returns The charge object with current status.
+     * @throws {@link SphoqApiError} with status 404 if the charge is not found.
+     *
+     * @example By Sphoq ID
+     * ```ts
+     * const charge = await sphoq.charges.get({ id: "ch_abc123" });
+     * console.log(charge.status); // "pending" | "paid" | "expired" | "cancelled"
+     * ```
+     *
+     * @example By external ID
+     * ```ts
+     * const charge = await sphoq.charges.get({ externalId: "order_456" });
+     * ```
+     */
     get(options: GetChargeOptions): Promise<Charge>;
+    /**
+     * Cancel a pending PIX charge.
+     *
+     * Only charges with `status: "pending"` can be cancelled.
+     * After cancellation, the QR code is invalidated and the charge
+     * cannot be paid.
+     *
+     * @param options - The charge ID to cancel.
+     * @returns Confirmation with the cancelled charge ID and status.
+     * @throws {@link SphoqApiError} with status 400 if the charge is not pending.
+     * @throws {@link SphoqApiError} with status 404 if the charge is not found.
+     *
+     * @example
+     * ```ts
+     * const result = await sphoq.charges.cancel({ id: "ch_abc123" });
+     * console.log(result.status); // "cancelled"
+     * ```
+     */
     cancel(options: CancelChargeOptions): Promise<CancelChargeResult>;
     private request;
 }

package/dist/client.js

@@ -1,25 +1,163 @@
 import { SphoqApiError } from "./types.js";
 const DEFAULT_BASE_URL = "https://your-convex-deployment.convex.site";
+/**
+ * Sphoq Payments SDK client.
+ *
+ * Provides methods for creating and managing PIX charges, and verifying webhook signatures.
+ * Zero dependencies — uses native `fetch` and Web Crypto API.
+ *
+ * @example Basic setup
+ * ```ts
+ * import { SphoqPayments } from "@sphoq/payments";
+ *
+ * const sphoq = new SphoqPayments({
+ *   apiKey: "spk_live_abc123...",
+ *   baseUrl: "https://your-deployment.convex.site",
+ * });
+ * ```
+ *
+ * @example Create a PIX charge and display QR code
+ * ```ts
+ * const charge = await sphoq.charges.create({
+ *   amount: 49.90,
+ *   description: "Premium Plan",
+ *   externalId: "order_123",
+ *   customer: { name: "João Silva", cpf: "12345678900" },
+ * });
+ *
+ * // Show QR code to user (base64 PNG)
+ * document.getElementById("qr").src = `data:image/png;base64,${charge.qrCode}`;
+ *
+ * // Or show the copy-paste PIX string
+ * console.log(charge.pixCopiaECola);
+ * ```
+ *
+ * @example Convex integration — reactive payment status
+ * ```ts
+ * // convex/http.ts — Receive Sphoq webhooks
+ * import { SphoqPayments, type WebhookPayload } from "@sphoq/payments";
+ *
+ * http.route({
+ *   path: "/webhooks/sphoq",
+ *   method: "POST",
+ *   handler: httpAction(async (ctx, req) => {
+ *     const body = await req.text();
+ *     const signature = req.headers.get("x-sphoq-signature")!;
+ *
+ *     const isValid = await SphoqPayments.verifyWebhookSignature({
+ *       payload: body,
+ *       signature,
+ *       secret: process.env.SPHOQ_WEBHOOK_SECRET!,
+ *     });
+ *     if (!isValid) return new Response("Invalid signature", { status: 401 });
+ *
+ *     const event: WebhookPayload = JSON.parse(body);
+ *     if (event.type === "charge.paid") {
+ *       await ctx.runMutation(internal.orders.markAsPaid, {
+ *         orderId: event.data.externalId,
+ *       });
+ *     }
+ *     return new Response("OK");
+ *   }),
+ * });
+ *
+ * // React component — auto-updates when webhook triggers the mutation
+ * function CheckoutPage({ orderId }: { orderId: string }) {
+ *   const order = useQuery(api.orders.get, { orderId });
+ *   // order.status reactively updates from "pending" to "paid"
+ *   // when the Sphoq webhook triggers markAsPaid mutation
+ * }
+ * ```
+ */
 export class SphoqPayments {
     apiKey;
     baseUrl;
+    /**
+     * Client for creating, querying, and cancelling PIX charges.
+     *
+     * @example
+     * ```ts
+     * // Create a charge
+     * const charge = await sphoq.charges.create({
+     *   amount: 29.90,
+     *   description: "Monthly subscription",
+     * });
+     *
+     * // Query a charge
+     * const status = await sphoq.charges.get({ id: charge.id });
+     *
+     * // Cancel a pending charge
+     * await sphoq.charges.cancel({ id: charge.id });
+     * ```
+     */
     charges;
+    /**
+     * Creates a new Sphoq Payments client.
+     *
+     * @param options - Client configuration (API key and base URL).
+     *
+     * @example
+     * ```ts
+     * const sphoq = new SphoqPayments({
+     *   apiKey: process.env.SPHOQ_API_KEY!,
+     *   baseUrl: process.env.SPHOQ_BASE_URL!,
+     * });
+     * ```
+     */
     constructor(options) {
         this.apiKey = options.apiKey;
         this.baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\/$/, "");
         this.charges = new ChargesClient(this.apiKey, this.baseUrl);
     }
     /**
-     * Verify a webhook signature to ensure it came from Sphoq.
+     * Verify a webhook signature to ensure the request came from Sphoq.
+     *
+     * Uses HMAC-SHA256 with constant-time comparison to prevent timing attacks.
+     * Works in all JavaScript runtimes: Node.js 18+, Deno, Cloudflare Workers,
+     * Vercel Edge, and Convex.
+     *
+     * **Important:** Always verify signatures before processing webhook payloads.
+     * Use the raw request body string — do not parse it before verification.
+     *
+     * @param options - The raw payload, signature header, and your webhook secret.
+     * @returns `true` if the signature is valid, `false` otherwise.
      *
-     * Works in both Node.js (using crypto module) and edge runtimes (using Web Crypto API).
+     * @example Node.js / Express
+     * ```ts
+     * app.post("/webhooks/sphoq", express.raw({ type: "*\/*" }), async (req, res) => {
+     *   const isValid = await SphoqPayments.verifyWebhookSignature({
+     *     payload: req.body.toString(),
+     *     signature: req.headers["x-sphoq-signature"] as string,
+     *     secret: process.env.SPHOQ_WEBHOOK_SECRET!,
+     *   });
+     *
+     *   if (!isValid) return res.status(401).send("Invalid signature");
+     *
+     *   const event = JSON.parse(req.body.toString());
+     *   // Handle event...
+     *   res.sendStatus(200);
+     * });
+     * ```
+     *
+     * @example Convex httpAction
+     * ```ts
+     * const handler = httpAction(async (ctx, req) => {
+     *   const body = await req.text();
+     *   const isValid = await SphoqPayments.verifyWebhookSignature({
+     *     payload: body,
+     *     signature: req.headers.get("x-sphoq-signature")!,
+     *     secret: process.env.SPHOQ_WEBHOOK_SECRET!,
+     *   });
+     *   if (!isValid) return new Response("Invalid", { status: 401 });
+     *   // Process the webhook...
+     * });
+     * ```
      */
     static async verifyWebhookSignature(options) {
         const { payload, signature, secret } = options;
         if (!signature.startsWith("sha256="))
             return false;
         const expectedHex = signature.slice(7);
-        // Use Web Crypto API (works in Node 18+, Deno, Cloudflare Workers, Vercel Edge)
         const encoder = new TextEncoder();
         const key = await globalThis.crypto.subtle.importKey("raw", encoder.encode(secret), { name: "HMAC", hash: "SHA-256" }, false, ["sign"]);
         const signatureBuffer = await globalThis.crypto.subtle.sign("HMAC", key, encoder.encode(payload));
@@ -43,6 +181,42 @@ class ChargesClient {
         this.apiKey = apiKey;
         this.baseUrl = baseUrl;
     }
+    /**
+     * Create a new PIX charge.
+     *
+     * Generates a PIX QR code and copy-paste string that the customer can use to pay.
+     * The charge starts with `status: "pending"` and transitions to `"paid"` when
+     * the customer completes the payment.
+     *
+     * @param options - Charge details (amount, description, customer info, etc.).
+     * @returns The created charge with QR code data.
+     * @throws {@link SphoqApiError} if the API returns an error (invalid params, rate limit, etc.).
+     *
+     * @example Simple charge
+     * ```ts
+     * const charge = await sphoq.charges.create({
+     *   amount: 29.90,
+     *   description: "Monthly subscription",
+     * });
+     * console.log(charge.pixCopiaECola); // PIX copy-paste string
+     * ```
+     *
+     * @example Full options
+     * ```ts
+     * const charge = await sphoq.charges.create({
+     *   amount: 149.90,
+     *   description: "Annual Plan",
+     *   externalId: "order_abc123",
+     *   customer: {
+     *     name: "Maria Santos",
+     *     email: "maria@example.com",
+     *     cpf: "12345678900",
+     *   },
+     *   expirationSeconds: 1800, // 30 minutes
+     *   metadata: { planId: "annual", coupon: "SAVE20" },
+     * });
+     * ```
+     */
     async create(options) {
         const body = {
             amount: options.amount,
@@ -54,10 +228,32 @@ class ChargesClient {
             body.customer = options.customer;
         if (options.expirationSeconds)
             body.expirationSeconds = options.expirationSeconds;
+        if (options.items)
+            body.items = options.items;
         if (options.metadata)
             body.metadata = options.metadata;
         return this.request("/v1/charges", body);
     }
+    /**
+     * Retrieve an existing charge by Sphoq ID or your external ID.
+     *
+     * At least one of `id` or `externalId` must be provided.
+     *
+     * @param options - Lookup criteria (Sphoq ID or external ID).
+     * @returns The charge object with current status.
+     * @throws {@link SphoqApiError} with status 404 if the charge is not found.
+     *
+     * @example By Sphoq ID
+     * ```ts
+     * const charge = await sphoq.charges.get({ id: "ch_abc123" });
+     * console.log(charge.status); // "pending" | "paid" | "expired" | "cancelled"
+     * ```
+     *
+     * @example By external ID
+     * ```ts
+     * const charge = await sphoq.charges.get({ externalId: "order_456" });
+     * ```
+     */
     async get(options) {
         if (!options.id && !options.externalId) {
             throw new Error("Either id or externalId is required");
@@ -69,6 +265,24 @@ class ChargesClient {
             body.externalId = options.externalId;
         return this.request("/v1/charges/get", body);
     }
+    /**
+     * Cancel a pending PIX charge.
+     *
+     * Only charges with `status: "pending"` can be cancelled.
+     * After cancellation, the QR code is invalidated and the charge
+     * cannot be paid.
+     *
+     * @param options - The charge ID to cancel.
+     * @returns Confirmation with the cancelled charge ID and status.
+     * @throws {@link SphoqApiError} with status 400 if the charge is not pending.
+     * @throws {@link SphoqApiError} with status 404 if the charge is not found.
+     *
+     * @example
+     * ```ts
+     * const result = await sphoq.charges.cancel({ id: "ch_abc123" });
+     * console.log(result.status); // "cancelled"
+     * ```
+     */
     async cancel(options) {
         return this.request("/v1/charges/cancel", {
             id: options.id,

package/dist/index.d.ts

@@ -1,3 +1,3 @@
 export { SphoqPayments } from "./client.js";
 export { SphoqApiError } from "./types.js";
-export type { SphoqPaymentsOptions, CreateChargeOptions, Charge, GetChargeOptions, CancelChargeOptions, CancelChargeResult, WebhookPayload, VerifyWebhookOptions, } from "./types.js";
+export type { SphoqPaymentsOptions, ChargeItem, CreateChargeOptions, Charge, GetChargeOptions, CancelChargeOptions, CancelChargeResult, WebhookPayload, VerifyWebhookOptions, } from "./types.js";

package/dist/types.d.ts

@@ -1,60 +1,377 @@
+/**
+ * Configuration options for the {@link SphoqPayments} client.
+ *
+ * @example
+ * ```ts
+ * import { SphoqPayments } from "@sphoq/payments";
+ *
+ * const sphoq = new SphoqPayments({
+ *   apiKey: "spk_live_abc123...",
+ *   baseUrl: "https://your-deployment.convex.site",
+ * });
+ * ```
+ */
 export interface SphoqPaymentsOptions {
+    /**
+     * Your Sphoq API key. Starts with `spk_`.
+     * Generate one from the Plugin page in your Sphoq store dashboard.
+     */
     apiKey: string;
+    /**
+     * The base URL of your Sphoq Convex deployment.
+     * This is the HTTP Actions URL from your Convex dashboard (ends in `.convex.site`).
+     *
+     * @example "https://your-deployment.convex.site"
+     */
     baseUrl?: string;
 }
+/**
+ * A line item included in a charge.
+ *
+ * When `items` are provided, the sum of `quantity * unitPrice` for all items
+ * **must** equal the charge `amount`. The API will reject the request otherwise.
+ *
+ * @example
+ * ```ts
+ * const items: ChargeItem[] = [
+ *   { name: "Premium Sword", quantity: 2, unitPrice: 29.90 },
+ *   { name: "Health Potion", quantity: 1, unitPrice: 10.00, externalId: "sku_hp_01" },
+ * ];
+ * // Total: (2 * 29.90) + (1 * 10.00) = 69.80
+ * const charge = await sphoq.charges.create({
+ *   amount: 69.80,
+ *   description: "3 items from GameStore",
+ *   items,
+ * });
+ * ```
+ */
+export interface ChargeItem {
+    /** Product or item name. */
+    name: string;
+    /** Quantity purchased. Must be a positive integer. */
+    quantity: number;
+    /** Price per unit in BRL. Must be greater than 0. */
+    unitPrice: number;
+    /** Optional item description or variant info. */
+    description?: string;
+    /**
+     * Your own identifier for this product (SKU, product ID, etc.).
+     * Useful for reconciling items with your catalog.
+     *
+     * @example "sku_sword_01"
+     */
+    externalId?: string;
+    /** URL to an image of the product. */
+    imageUrl?: string;
+}
+/**
+ * Options for creating a new PIX charge.
+ *
+ * @example Simple charge
+ * ```ts
+ * const charge = await sphoq.charges.create({
+ *   amount: 49.90,
+ *   description: "Premium Plan - Monthly",
+ *   externalId: "order_123",
+ *   customer: {
+ *     name: "João Silva",
+ *     email: "joao@example.com",
+ *     cpf: "12345678900",
+ *   },
+ *   expirationSeconds: 3600, // 1 hour
+ *   metadata: { planId: "premium", userId: "usr_abc" },
+ * });
+ * ```
+ *
+ * @example Charge with itemized products
+ * ```ts
+ * const charge = await sphoq.charges.create({
+ *   amount: 69.80, // Must equal sum of items: (2 * 29.90) + (1 * 10.00)
+ *   description: "3 items from GameStore",
+ *   items: [
+ *     { name: "Premium Sword", quantity: 2, unitPrice: 29.90, externalId: "sku_sword" },
+ *     { name: "Health Potion", quantity: 1, unitPrice: 10.00, externalId: "sku_hp" },
+ *   ],
+ * });
+ * ```
+ */
 export interface CreateChargeOptions {
+    /**
+     * Charge amount in BRL (Brazilian Real).
+     * Must be greater than 0. Use decimal notation (e.g., `29.90` for R$ 29,90).
+     */
     amount: number;
+    /** Human-readable description shown to the customer. */
     description: string;
+    /**
+     * Your own unique identifier for this charge.
+     * Useful for correlating Sphoq charges with records in your database.
+     * Must be unique per store.
+     *
+     * @example "order_abc123"
+     */
     externalId?: string;
+    /** Customer information attached to the charge. */
     customer?: {
+        /** Customer's full name. */
         name?: string;
+        /** Customer's email address. */
         email?: string;
+        /** Customer's CPF (Brazilian tax ID, 11 digits, no formatting). */
         cpf?: string;
     };
+    /**
+     * Time in seconds until the PIX charge expires.
+     * After expiration, the QR code can no longer be paid.
+     *
+     * @default 3600 (1 hour)
+     */
     expirationSeconds?: number;
+    /**
+     * Line items included in this charge.
+     *
+     * When provided, the sum of `quantity * unitPrice` across all items **must**
+     * exactly equal the `amount` field (within R$ 0.01 tolerance). The API rejects
+     * the request if the totals don't match.
+     *
+     * Items are stored with the charge and included in webhook payloads,
+     * making them available for order fulfillment and reconciliation.
+     *
+     * Maximum 100 items per charge.
+     *
+     * @example
+     * ```ts
+     * items: [
+     *   { name: "Gamepass: VIP", quantity: 1, unitPrice: 19.90, externalId: "gp_vip" },
+     *   { name: "Robux 1000", quantity: 2, unitPrice: 15.00 },
+     * ]
+     * ```
+     */
+    items?: ChargeItem[];
+    /**
+     * Arbitrary key-value data attached to the charge.
+     * Returned in webhook payloads and charge queries.
+     * Useful for storing your application context (plan IDs, user IDs, etc.).
+     *
+     * @example { planId: "premium", userId: "usr_abc" }
+     */
     metadata?: Record<string, unknown>;
 }
+/**
+ * A PIX charge object returned by the Sphoq API.
+ *
+ * @example
+ * ```ts
+ * const charge = await sphoq.charges.create({
+ *   amount: 29.90,
+ *   description: "Monthly subscription",
+ * });
+ *
+ * // Display QR code to user
+ * console.log(charge.qrCode);        // Base64-encoded QR code image
+ * console.log(charge.pixCopiaECola); // PIX copy-paste string
+ * console.log(charge.status);        // "pending"
+ *
+ * // After payment, query the charge
+ * const paid = await sphoq.charges.get({ id: charge.id });
+ * console.log(paid.status);      // "paid"
+ * console.log(paid.paidAt);      // Unix timestamp in ms
+ * console.log(paid.endToEndId);  // Central Bank end-to-end ID
+ * ```
+ */
 export interface Charge {
+    /** Unique Sphoq charge ID. Use this to query or cancel the charge. */
     id: string;
+    /** Your external ID, if provided when creating the charge. */
     externalId?: string;
+    /** Charge amount in BRL. */
     amount: number;
+    /**
+     * Currency code. Always `"BRL"` (Brazilian Real).
+     */
     currency: string;
+    /** Human-readable description of the charge. */
     description: string;
+    /**
+     * Current status of the charge.
+     *
+     * - `"pending"` — Awaiting payment. QR code is active.
+     * - `"paid"` — Payment confirmed by the bank.
+     * - `"expired"` — QR code expired before payment.
+     * - `"cancelled"` — Charge was cancelled via the API.
+     */
     status: "pending" | "paid" | "expired" | "cancelled";
+    /** PIX transaction ID (txid). Unique identifier in the Brazilian PIX system. */
     txid: string;
+    /**
+     * PIX "copia e cola" (copy-paste) string.
+     * The customer can paste this into their banking app to pay.
+     */
     pixCopiaECola?: string;
+    /**
+     * Base64-encoded PNG image of the PIX QR code.
+     * Display this to the customer for scanning.
+     */
     qrCode?: string;
+    /** Customer name, if provided. */
     customerName?: string;
+    /** Customer email, if provided. */
     customerEmail?: string;
+    /**
+     * Unix timestamp (milliseconds) when the payment was confirmed.
+     * Only present when `status` is `"paid"`.
+     */
     paidAt?: number;
+    /**
+     * Central Bank end-to-end ID for the PIX transaction.
+     * Only present when `status` is `"paid"`.
+     * Can be used for reconciliation with bank statements.
+     */
     endToEndId?: string;
+    /**
+     * Line items included in the charge, if provided at creation.
+     * Returned as-is from the API. Useful for order fulfillment.
+     */
+    items?: ChargeItem[];
+    /**
+     * Arbitrary metadata attached when the charge was created.
+     * Returned as-is from the API.
+     */
     metadata?: Record<string, unknown>;
+    /** Unix timestamp (milliseconds) when the charge was created. */
     createdAt: number;
+    /** Unix timestamp (milliseconds) when the PIX QR code expires. */
     expiresAt: number;
 }
+/**
+ * Options for retrieving an existing charge.
+ * Provide either `id` (Sphoq charge ID) or `externalId` (your own ID) — at least one is required.
+ *
+ * @example
+ * ```ts
+ * // By Sphoq ID
+ * const charge = await sphoq.charges.get({ id: "ch_abc123" });
+ *
+ * // By your external ID
+ * const charge = await sphoq.charges.get({ externalId: "order_456" });
+ * ```
+ */
 export interface GetChargeOptions {
+    /** Sphoq charge ID. */
     id?: string;
+    /** Your external ID provided when the charge was created. */
     externalId?: string;
 }
+/**
+ * Options for cancelling a pending charge.
+ *
+ * @example
+ * ```ts
+ * const result = await sphoq.charges.cancel({ id: "ch_abc123" });
+ * console.log(result.status); // "cancelled"
+ * ```
+ */
 export interface CancelChargeOptions {
+    /** Sphoq charge ID to cancel. The charge must have `status: "pending"`. */
     id: string;
 }
+/**
+ * Result of a successful charge cancellation.
+ */
 export interface CancelChargeResult {
+    /** The cancelled charge's ID. */
     id: string;
+    /** Always `"cancelled"`. */
     status: "cancelled";
 }
+/**
+ * Webhook event payload sent by Sphoq to your endpoint.
+ *
+ * Sphoq sends webhooks for payment lifecycle events. Each payload includes
+ * the event type, the full charge data, and a timestamp.
+ *
+ * Always verify the webhook signature before processing:
+ *
+ * @example
+ * ```ts
+ * // Convex HTTP endpoint (httpAction)
+ * const handler = httpAction(async (ctx, req) => {
+ *   const body = await req.text();
+ *   const signature = req.headers.get("x-sphoq-signature")!;
+ *
+ *   const isValid = await SphoqPayments.verifyWebhookSignature({
+ *     payload: body,
+ *     signature,
+ *     secret: process.env.SPHOQ_WEBHOOK_SECRET!,
+ *   });
+ *
+ *   if (!isValid) {
+ *     return new Response("Invalid signature", { status: 401 });
+ *   }
+ *
+ *   const event: WebhookPayload = JSON.parse(body);
+ *
+ *   if (event.type === "charge.paid") {
+ *     // Update your database — the charge has been paid
+ *     await ctx.runMutation(internal.orders.markAsPaid, {
+ *       externalId: event.data.externalId,
+ *       paidAt: event.data.paidAt,
+ *     });
+ *   }
+ *
+ *   return new Response("OK", { status: 200 });
+ * });
+ * ```
+ */
 export interface WebhookPayload {
+    /**
+     * The event type.
+     *
+     * - `"charge.paid"` — Customer completed the PIX payment.
+     * - `"charge.expired"` — QR code expired before payment.
+     * - `"charge.cancelled"` — Charge was cancelled via the API.
+     */
     type: "charge.paid" | "charge.expired" | "charge.cancelled";
+    /** Full charge data at the time of the event. */
     data: Charge;
+    /** Unix timestamp (milliseconds) when the event was created. */
     createdAt: number;
 }
+/**
+ * Options for verifying a webhook signature.
+ *
+ * @see {@link SphoqPayments.verifyWebhookSignature}
+ */
 export interface VerifyWebhookOptions {
+    /** The raw request body as a string (do NOT parse it before verifying). */
     payload: string;
+    /** The `x-sphoq-signature` header value from the webhook request. */
     signature: string;
+    /** Your webhook endpoint secret from the Sphoq dashboard. */
     secret: string;
 }
+/**
+ * Error thrown when the Sphoq API returns a non-2xx response.
+ *
+ * @example
+ * ```ts
+ * import { SphoqApiError } from "@sphoq/payments";
+ *
+ * try {
+ *   await sphoq.charges.cancel({ id: "invalid_id" });
+ * } catch (error) {
+ *   if (error instanceof SphoqApiError) {
+ *     console.error(error.message);    // "Charge not found"
+ *     console.error(error.statusCode); // 404
+ *     console.error(error.body);       // Raw API response body
+ *   }
+ * }
+ * ```
+ */
 export declare class SphoqApiError extends Error {
+    /** HTTP status code from the API response (e.g., 400, 401, 404, 500). */
     readonly statusCode: number;
+    /** Raw response body from the API. May contain additional error details. */
     readonly body: unknown;
     constructor(message: string, statusCode: number, body?: unknown);
 }

package/dist/types.js

@@ -1,5 +1,25 @@
+/**
+ * Error thrown when the Sphoq API returns a non-2xx response.
+ *
+ * @example
+ * ```ts
+ * import { SphoqApiError } from "@sphoq/payments";
+ *
+ * try {
+ *   await sphoq.charges.cancel({ id: "invalid_id" });
+ * } catch (error) {
+ *   if (error instanceof SphoqApiError) {
+ *     console.error(error.message);    // "Charge not found"
+ *     console.error(error.statusCode); // 404
+ *     console.error(error.body);       // Raw API response body
+ *   }
+ * }
+ * ```
+ */
 export class SphoqApiError extends Error {
+    /** HTTP status code from the API response (e.g., 400, 401, 404, 500). */
     statusCode;
+    /** Raw response body from the API. May contain additional error details. */
     body;
     constructor(message, statusCode, body) {
         super(message);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sphoq/payments",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Sphoq Payments SDK — integrate PIX payment processing into your app",
   "type": "module",
   "main": "dist/index.js",