@sphoq/payments 0.2.0 → 0.4.0

package/dist/index.d.ts

@@ -1,3 +1,3 @@
 export { SphoqPayments } from "./client.js";
 export { SphoqApiError } from "./types.js";
-export type { SphoqPaymentsOptions, ChargeItem, CreateChargeOptions, Charge, GetChargeOptions, CancelChargeOptions, CancelChargeResult, WebhookPayload, VerifyWebhookOptions, } from "./types.js";
+export type { SphoqPaymentsOptions, ChargeItem, ChargeFee, 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;
     /**
@@ -157,6 +171,35 @@ export interface CreateChargeOptions {
      */
     metadata?: Record<string, unknown>;
 }
+/**
+ * A fee applied to a charge.
+ *
+ * Fees are calculated at charge creation and included in every charge response
+ * and webhook payload.
+ *
+ * @example
+ * ```ts
+ * const charge = await sphoq.charges.create({ amount: 100, description: "Test" });
+ * for (const fee of charge.fees) {
+ *   console.log(`${fee.type} (${fee.provider}): ${fee.rate}% = R$ ${fee.amount}`);
+ * }
+ * console.log(`Net amount: R$ ${charge.netAmount}`);
+ * ```
+ */
+export interface ChargeFee {
+    /**
+     * The category of this fee.
+     * - `"platform"` — Sphoq platform fee
+     * - `"processor"` — Payment processor fee (e.g., EfiBank PIX)
+     */
+    type: "platform" | "processor";
+    /** Who charges this fee (e.g., `"sphoq"`, `"efibank"`). */
+    provider: string;
+    /** Fee percentage (e.g., `5` for 5%). */
+    rate: number;
+    /** Calculated fee amount in BRL. */
+    amount: number;
+}
 /**
  * A PIX charge object returned by the Sphoq API.
  *
@@ -238,6 +281,27 @@ export interface Charge {
      * Returned as-is from the API.
      */
     metadata?: Record<string, unknown>;
+    /**
+     * Fees applied to this charge.
+     * Calculated at creation time based on the store's tax settings.
+     */
+    fees: ChargeFee[];
+    /**
+     * Sum of all fee amounts in BRL.
+     * Equal to `fees.reduce((sum, f) => sum + f.amount, 0)`.
+     */
+    totalFees: number;
+    /**
+     * Amount after fees in BRL.
+     * Equal to `amount - totalFees`.
+     */
+    netAmount: number;
+    /**
+     * 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.2.0",
+  "version": "0.4.0",
   "description": "Sphoq Payments SDK — integrate PIX payment processing into your app",
   "type": "module",
   "main": "dist/index.js",