@sphoq/payments 0.5.0 → 0.6.0

package/dist/client.d.ts

@@ -1,4 +1,4 @@
-import type { SphoqPaymentsOptions, CreateChargeOptions, Charge, GetChargeOptions, CancelChargeOptions, CancelChargeResult, VerifyWebhookOptions } from "./types.js";
+import type { SphoqPaymentsOptions, CreateChargeOptions, Charge, GetChargeOptions, CancelChargeOptions, CancelChargeResult, CreateRefundOptions, Refund, GetRefundOptions, VerifyWebhookOptions } from "./types.js";
 /**
  * Sphoq Payments SDK client.
  *
@@ -90,6 +90,22 @@ export declare class SphoqPayments {
      * ```
      */
     readonly charges: ChargesClient;
+    /**
+     * Client for creating and querying refunds.
+     *
+     * @example
+     * ```ts
+     * // Create a refund for a paid charge
+     * const refund = await sphoq.refunds.create({
+     *   id: charge.id,
+     *   reason: "Customer requested cancellation",
+     * });
+     *
+     * // Query a refund
+     * const status = await sphoq.refunds.get({ id: refund.id });
+     * ```
+     */
+    readonly refunds: RefundsClient;
     /**
      * Creates a new Sphoq Payments client.
      *
@@ -233,4 +249,55 @@ declare class ChargesClient {
     cancel(options: CancelChargeOptions): Promise<CancelChargeResult>;
     private request;
 }
+declare class RefundsClient {
+    private readonly apiKey;
+    private readonly baseUrl;
+    constructor(apiKey: string, baseUrl: string);
+    /**
+     * Create a refund for a paid charge.
+     *
+     * Only charges with `status: "paid"` can be refunded. If `amount` is omitted,
+     * the full charge amount is refunded. Partial refunds are supported.
+     *
+     * @param options - Refund details (charge ID, optional amount and reason).
+     * @returns The created refund with initial status.
+     * @throws {@link SphoqApiError} with status 400 if the charge is not paid or amount exceeds refundable balance.
+     * @throws {@link SphoqApiError} with status 404 if the charge is not found.
+     *
+     * @example Full refund
+     * ```ts
+     * const refund = await sphoq.refunds.create({
+     *   id: charge.id,
+     *   reason: "Order cancelled",
+     * });
+     * ```
+     *
+     * @example Partial refund
+     * ```ts
+     * const refund = await sphoq.refunds.create({
+     *   id: charge.id,
+     *   amount: 15.00,
+     *   reason: "Partial return",
+     * });
+     * ```
+     */
+    create(options: CreateRefundOptions): Promise<Refund>;
+    /**
+     * Retrieve an existing refund by its ID.
+     *
+     * @param options - Lookup criteria (refund ID).
+     * @returns The refund object with current status.
+     * @throws {@link SphoqApiError} with status 404 if the refund is not found.
+     *
+     * @example
+     * ```ts
+     * const refund = await sphoq.refunds.get({ id: "ref_abc123" });
+     * if (refund.status === "completed") {
+     *   console.log("Refund completed at", new Date(refund.completedAt!));
+     * }
+     * ```
+     */
+    get(options: GetRefundOptions): Promise<Refund>;
+    private request;
+}
 export {};

package/dist/client.js

@@ -91,6 +91,22 @@ export class SphoqPayments {
      * ```
      */
     charges;
+    /**
+     * Client for creating and querying refunds.
+     *
+     * @example
+     * ```ts
+     * // Create a refund for a paid charge
+     * const refund = await sphoq.refunds.create({
+     *   id: charge.id,
+     *   reason: "Customer requested cancellation",
+     * });
+     *
+     * // Query a refund
+     * const status = await sphoq.refunds.get({ id: refund.id });
+     * ```
+     */
+    refunds;
     /**
      * Creates a new Sphoq Payments client.
      *
@@ -108,6 +124,7 @@ export class SphoqPayments {
         this.apiKey = options.apiKey;
         this.baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\/$/, "");
         this.charges = new ChargesClient(this.apiKey, this.baseUrl);
+        this.refunds = new RefundsClient(this.apiKey, this.baseUrl);
     }
     /**
      * Verify a webhook signature to ensure the request came from Sphoq.
@@ -304,3 +321,82 @@ class ChargesClient {
         return data;
     }
 }
+class RefundsClient {
+    apiKey;
+    baseUrl;
+    constructor(apiKey, baseUrl) {
+        this.apiKey = apiKey;
+        this.baseUrl = baseUrl;
+    }
+    /**
+     * Create a refund for a paid charge.
+     *
+     * Only charges with `status: "paid"` can be refunded. If `amount` is omitted,
+     * the full charge amount is refunded. Partial refunds are supported.
+     *
+     * @param options - Refund details (charge ID, optional amount and reason).
+     * @returns The created refund with initial status.
+     * @throws {@link SphoqApiError} with status 400 if the charge is not paid or amount exceeds refundable balance.
+     * @throws {@link SphoqApiError} with status 404 if the charge is not found.
+     *
+     * @example Full refund
+     * ```ts
+     * const refund = await sphoq.refunds.create({
+     *   id: charge.id,
+     *   reason: "Order cancelled",
+     * });
+     * ```
+     *
+     * @example Partial refund
+     * ```ts
+     * const refund = await sphoq.refunds.create({
+     *   id: charge.id,
+     *   amount: 15.00,
+     *   reason: "Partial return",
+     * });
+     * ```
+     */
+    async create(options) {
+        const body = {
+            id: options.id,
+        };
+        if (options.amount !== undefined)
+            body.amount = options.amount;
+        if (options.reason)
+            body.reason = options.reason;
+        return this.request("/v1/refunds", body);
+    }
+    /**
+     * Retrieve an existing refund by its ID.
+     *
+     * @param options - Lookup criteria (refund ID).
+     * @returns The refund object with current status.
+     * @throws {@link SphoqApiError} with status 404 if the refund is not found.
+     *
+     * @example
+     * ```ts
+     * const refund = await sphoq.refunds.get({ id: "ref_abc123" });
+     * if (refund.status === "completed") {
+     *   console.log("Refund completed at", new Date(refund.completedAt!));
+     * }
+     * ```
+     */
+    async get(options) {
+        return this.request("/v1/refunds/get", { id: options.id });
+    }
+    async request(path, body) {
+        const response = await fetch(`${this.baseUrl}${path}`, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                Authorization: `Bearer ${this.apiKey}`,
+            },
+            body: JSON.stringify(body),
+        });
+        const data = await response.json();
+        if (!response.ok) {
+            throw new SphoqApiError(data.error ?? "Request failed", response.status, data);
+        }
+        return data;
+    }
+}

package/dist/index.d.ts

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

package/dist/types.d.ts

@@ -425,6 +425,91 @@ export interface VerifyWebhookOptions {
     /** Your webhook endpoint secret from the Sphoq dashboard. */
     secret: string;
 }
+/**
+ * Options for creating a refund for a charge.
+ *
+ * @example Full refund
+ * ```ts
+ * const refund = await sphoq.refunds.create({
+ *   id: "ch_abc123", // Sphoq charge ID
+ *   reason: "Customer requested cancellation",
+ * });
+ * console.log(refund.status); // "pending"
+ * ```
+ *
+ * @example Partial refund
+ * ```ts
+ * const refund = await sphoq.refunds.create({
+ *   id: "ch_abc123",
+ *   amount: 15.00, // Partial refund amount
+ *   reason: "Partial return",
+ * });
+ * ```
+ */
+export interface CreateRefundOptions {
+    /** Sphoq charge ID to refund. The charge must have `status: "paid"`. */
+    id: string;
+    /**
+     * Refund amount. If omitted, defaults to the full charge amount.
+     * Must be greater than 0 and less than or equal to the refundable amount.
+     */
+    amount?: number;
+    /** Reason for the refund. */
+    reason?: string;
+}
+/**
+ * A refund object returned by the Sphoq API.
+ *
+ * Refunds are processed asynchronously by the payment provider.
+ * Use webhooks or poll the refund status to track completion.
+ *
+ * @example
+ * ```ts
+ * const refund = await sphoq.refunds.create({ id: chargeId });
+ * console.log(refund.id);     // Sphoq refund ID
+ * console.log(refund.status); // "pending" | "processing" | "completed" | "failed"
+ * ```
+ */
+export interface Refund {
+    /** Unique Sphoq refund ID. */
+    id: string;
+    /** The charge ID this refund belongs to. */
+    chargeId: string;
+    /** Refund amount. */
+    amount: number;
+    /** Currency code (e.g., `"BRL"`). */
+    currency: string;
+    /**
+     * Current status of the refund.
+     *
+     * - `"pending"` — Refund created, waiting to be sent to the provider.
+     * - `"processing"` — Sent to the provider, awaiting confirmation.
+     * - `"completed"` — Refund confirmed by the provider.
+     * - `"failed"` — Refund failed (see `failureReason`).
+     */
+    status: "pending" | "processing" | "completed" | "failed";
+    /** Reason the refund failed, if `status` is `"failed"`. */
+    failureReason?: string;
+    /** Reason for the refund, if provided. */
+    reason?: string;
+    /** Unix timestamp (milliseconds) when the refund was created. */
+    createdAt: number;
+    /** Unix timestamp (milliseconds) when the refund was completed. */
+    completedAt?: number;
+}
+/**
+ * Options for retrieving an existing refund.
+ *
+ * @example
+ * ```ts
+ * const refund = await sphoq.refunds.get({ id: "ref_abc123" });
+ * console.log(refund.status); // "completed"
+ * ```
+ */
+export interface GetRefundOptions {
+    /** Sphoq refund ID. */
+    id: string;
+}
 /**
  * Error thrown when the Sphoq API returns a non-2xx response.
  *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sphoq/payments",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Sphoq Payments SDK — integrate payment processing into your app",
   "type": "module",
   "main": "dist/index.js",
@@ -11,12 +11,21 @@
       "import": "./dist/index.js"
     }
   },
-  "files": ["dist"],
+  "files": [
+    "dist"
+  ],
   "scripts": {
     "build": "tsc",
     "dev": "tsc --watch"
   },
-  "keywords": ["sphoq", "pix", "payments", "brazil", "efibank", "convex"],
+  "keywords": [
+    "sphoq",
+    "pix",
+    "payments",
+    "brazil",
+    "efibank",
+    "convex"
+  ],
   "license": "MIT",
   "devDependencies": {
     "typescript": "^5.9.0"