@sphoq/payments 0.1.1 → 0.3.0

package/dist/client.js

@@ -228,6 +228,8 @@ 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);

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,20 +1,34 @@
 /**
  * Configuration options for the {@link SphoqPayments} client.
  *
+ * The API key prefix determines the environment:
+ * - `spq_live_*` — Production (real PIX charges)
+ * - `spq_test_*` — Development/Sandbox (EfiBank sandbox, no real money)
+ *
  * @example
  * ```ts
  * import { SphoqPayments } from "@sphoq/payments";
  *
+ * // Production
  * const sphoq = new SphoqPayments({
- *   apiKey: "spk_live_abc123...",
+ *   apiKey: "spq_live_abc123...",
+ *   baseUrl: "https://your-deployment.convex.site",
+ * });
+ *
+ * // Sandbox / Testing
+ * const sphoqTest = new SphoqPayments({
+ *   apiKey: "spq_test_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.
+     * Your Sphoq API key.
+     * - `spq_live_*` keys target the **production** EfiBank environment (real charges).
+     * - `spq_test_*` keys target the **sandbox** EfiBank environment (test charges).
+     *
+     * Generate keys from the Plugin page in your Sphoq store dashboard.
      */
     apiKey: string;
     /**
@@ -26,10 +40,49 @@ export interface SphoqPaymentsOptions {
     baseUrl?: string;
 }
 /**
- * Options for creating a new PIX charge.
+ * 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",
@@ -43,6 +96,18 @@ export interface SphoqPaymentsOptions {
  *   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 {
     /**
@@ -76,6 +141,27 @@ export interface CreateChargeOptions {
      * @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.
@@ -156,11 +242,22 @@ export interface Charge {
      * 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>;
+    /**
+     * The environment this charge was created in.
+     * - `"production"` — Real PIX charge.
+     * - `"development"` — EfiBank sandbox charge (no real money).
+     */
+    environment?: "production" | "development";
     /** Unix timestamp (milliseconds) when the charge was created. */
     createdAt: number;
     /** Unix timestamp (milliseconds) when the PIX QR code expires. */

package/package.json

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