@garuhq/node 0.15.0 → 1.0.0

package/dist/index.d.ts

@@ -98,15 +98,13 @@ declare class HttpClient {
  * The resource layer maps friendly → wire at the edge.
  */
 
-type PaymentMethod = 'pix' | 'credit_card' | 'boleto';
 /**
- * Payment-method identifier as it appears on the wire. `pix_automatic`
- * (Pix Automático auto-debit) surfaces here on transactions/charges read
- * back from Pix Automático recurring cycles. It is never produced by
- * `toWirePaymentMethod`, since one-off charges can't use it.
+ * Stable, friendly charge status. Mirrors what /api/v1/charges returns — the
+ * raw processor statuses (payedPix, pendingBoleto, …) are normalized server-side
+ * and never surface here. Act on `paid`; `authorized` is card money held but not
+ * captured, `refund_pending` is a Pix devolução requested but not yet settled.
  */
-type WirePaymentMethodId = 'pix' | 'creditcard' | 'boleto' | 'pix_automatic';
-type ChargeStatus = 'pending' | 'authorized' | 'paid' | 'failed' | 'refunded' | 'cancelled' | 'expired';
+type ChargeStatus = 'pending' | 'authorized' | 'paid' | 'failed' | 'expired' | 'canceled' | 'refund_pending' | 'refunded' | 'chargeback';
 interface Customer {
     /** Full legal name. 3–255 chars. */
     name: string;
@@ -125,78 +123,122 @@ interface Customer {
     /** 2-letter uppercase state code, e.g. `SP`. */
     state?: string;
 }
-interface CardInfo {
-    /** 13–19 digits, no spaces or hyphens. */
-    cardNumber: string;
-    /** 3 or 4 digits. */
-    cvv: string;
-    /** `YYYY-MM`. */
-    expirationDate: string;
-    /** As printed on the card. */
+interface CardInput {
+    /** PAN, 13-19 digits, no spaces. Server-to-server only (PCI scope). */
+    number: string;
+    /** Holder name exactly as printed. */
     holderName: string;
-    /** 1–12. */
+    /** Expiry as `YYYY-MM`. */
+    expirationDate: string;
+    /** 3 or 4 digits. Never stored by Garu. */
+    cvv: string;
+    /** 1-12. */
     installments: number;
 }
 interface CreateChargeParams {
-    /** Customer buying the product. */
-    customer: Customer;
     /** UUID of the product being charged. */
     productId: string;
     /** Payment method. */
-    paymentMethod: PaymentMethod;
-    /** Required when `paymentMethod` is `credit_card`. */
-    cardInfo?: CardInfo;
-    /** Free-form metadata attached to the charge. */
-    additionalInfo?: string;
-    /** Original checkout link, if any. */
-    link?: string | null;
-    /** Associated affiliate ID, if any. */
-    affiliateId?: number | null;
-    /** Subscription price ID (`price_*`), for subscription charges only. */
-    priceId?: string | null;
-    /** Optional pre-created checkout session token. */
-    checkoutSessionToken?: string;
+    paymentMethod: ChargePaymentMethod;
+    /** Customer buying the product. */
+    customer: Customer;
     /**
-     * Idempotency key. If omitted, the SDK generates a UUIDv4.
-     * Keys are valid for 24h on the backend.
+     * Required when `paymentMethod` is `creditCard`. This is a raw PAN + CVV, so
+     * call the SDK only from your server, never a browser or app — it puts you in
+     * PCI DSS scope.
      */
+    card?: CardInput;
+    /** Optional pre-created checkout session token, for attribution. */
+    checkoutSessionToken?: string;
+    /** Free-form metadata attached to the charge. */
+    additionalInfo?: string;
+    /** Idempotency key. If omitted, the SDK generates a UUIDv4. Valid 24h. */
     idempotencyKey?: string;
 }
+type ChargePaymentMethod = 'pix' | 'boleto' | 'creditCard';
 interface Charge {
-    id: number;
+    /** Public identifier. Use this everywhere; there is no numeric id. */
+    uuid: string;
     status: ChargeStatus;
+    paymentMethod: ChargePaymentMethod;
+    /** Product base price, in decimal BRL / reais. */
     amount: number;
-    paymentMethodId: WirePaymentMethodId;
-    /** ISO-8601. */
-    date: string;
+    /**
+     * What the customer is actually charged, in reais. Equals `amount` for PIX,
+     * boleto and 1x card; higher for installment card sales (fator markup). Use
+     * this to reconcile, not `amount`.
+     */
+    chargedTotal: number;
+    installments: number;
+    product: {
+        uuid: string;
+        name: string;
+    } | null;
+    /** `document` is partially masked. */
+    customer: {
+        name: string;
+        email: string;
+        document: string;
+    } | null;
+    /** Present for PIX: the copy-paste EMV code to render as a QR. */
+    pix: {
+        code: string;
+    } | null;
+    /** Present for boleto: the barcode line and a Garu-hosted PDF URL. */
+    boleto: {
+        barcodeLine: string;
+        pdfUrl: string;
+    } | null;
+    /** Present for card: only brand, last4 and the authorization code. */
+    card: {
+        brand: string | null;
+        last4: string | null;
+        authorizationCode: string | null;
+    } | null;
+    /** Set once refunded. `refundedAt` is null while a Pix devolução is unsettled. */
+    refund: {
+        amount: number;
+        reason: string | null;
+        refundedAt: string | null;
+    } | null;
     /** ISO-8601. */
-    deadline?: string;
-    /** Product this charge belongs to. */
-    product?: {
-        id: number;
-        uuid?: string;
-        name?: string;
-    };
-    [key: string]: unknown;
+    createdAt: string;
+    /** ISO-8601. Only set for boleto (due date); null for PIX and card. */
+    expiresAt: string | null;
 }
 interface RefundChargeParams {
-    /** Partial refund in centavos. Omit for full refund. */
+    /**
+     * Partial refund in **decimal BRL / reais** (e.g. `10.00`) — NOT centavos.
+     * Omit for a full refund. Passing `1000` for "R$ 10,00" refunds a thousand
+     * reais.
+     *
+     * For a Pix Automático charge this starts an asynchronous devolução: the
+     * charge moves to `refund_pending` and only reaches `refunded` once the
+     * transfer settles.
+     */
     amount?: number;
     /** Free-form reason stored on the refund. */
     reason?: string;
-    idempotencyKey?: string;
 }
 interface ListChargesParams {
     /** Page number (1-based). Default: 1. */
     page?: number;
-    /** Items per page (1–100). Default: 20. */
+    /** Items per page (1-100). Default: 20. */
     limit?: number;
-    /** Filter by status (e.g. `paid`, `pending`). */
-    status?: string;
+    /** Filter by friendly status (e.g. `paid`, `pending`). */
+    status?: ChargeStatus;
+    /** Filter by payment method. */
+    paymentMethod?: ChargePaymentMethod;
+    /** Filter by product UUID. */
+    productId?: string;
+    /** Charges created at or after this ISO-8601 instant. */
+    createdAfter?: string;
+    /** Charges created at or before this ISO-8601 instant. */
+    createdBefore?: string;
     /** Search by customer name, email, or document. */
     search?: string;
-    /** Filter by payment method (`pix`, `creditcard`, `boleto`). */
-    paymentMethod?: string;
+    /** Sort order. Default `-createdAt` (newest first). */
+    sort?: 'createdAt' | '-createdAt' | 'amount' | '-amount';
 }
 interface PaginatedList<T> {
     data: T[];
@@ -207,7 +249,18 @@ interface PaginatedList<T> {
         totalPages: number;
     };
 }
-type ChargeList = PaginatedList<Charge>;
+interface ChargeList {
+    data: Charge[];
+    /** Items on this page. */
+    count: number;
+    /** Total matches across all pages. */
+    totalCount: number;
+    totalPages: number;
+}
+/** Result of cancelling a charge. */
+interface CancelChargeResult {
+    canceled: boolean;
+}
 interface CustomerRecord {
     id: number;
     name: string;
@@ -509,12 +562,17 @@ interface ChargeNowResult {
     message: string;
 }
 interface Product {
-    id: number;
+    /**
+     * @deprecated The v1 API no longer returns a numeric id — use `uuid` to
+     * address a product. Present only on legacy `/api/products/*` responses;
+     * `undefined` on v1.
+     */
+    id?: number;
     uuid: string;
     name: string;
     description: string;
     image: string;
-    /** Price in centavos (BRL × 100). */
+    /** Price in decimal BRL / reais (e.g. `297.50`) — NOT centavos. */
     value: number;
     sellerId: number;
     sellerName?: string;
@@ -528,7 +586,8 @@ interface Product {
      * checkout mode reads this flag. See {@link ScheduledPaymentMethod}.
      */
     pixAutomatic: boolean;
-    installments: number[];
+    /** Per-parcela credit-card breakdown (the amount charged per installment). */
+    installments: Installment[];
     tags?: string[];
     isSubscription?: boolean;
     subscriptionType?: string;
@@ -541,18 +600,36 @@ interface Product {
     updatedAt: string;
     [key: string]: unknown;
 }
-type ProductList = PaginatedList<Product>;
+/** One entry in a product's credit-card installment breakdown. */
+interface Installment {
+    /** Number of parcelas. */
+    quantity: number;
+    /** Amount charged per installment, in reais (BRL), with the fator markup applied. */
+    value: number;
+}
+/**
+ * List envelope returned by `products.list()`. Flat (not `{ data, meta }`) —
+ * matches the `/api/v1/products` response.
+ */
+interface ProductList {
+    data: Product[];
+    /** Items returned on this page. */
+    count: number;
+    /** Total products matching the filter across all pages. */
+    totalCount: number;
+    totalPages: number;
+}
 interface ListProductsParams {
     page?: number;
     limit?: number;
     /** Search by product name. */
     search?: string;
-    /** Backend tab filter (e.g. `active`, `archived`). Backend default is used when omitted. */
+    /** @deprecated Not supported by the v1 API (ignored). `list()` returns the seller's own products. */
     tab?: string;
 }
 interface CreateProductParams {
     name: string;
-    /** Price in centavos (BRL × 100). */
+    /** Price in decimal BRL / reais (e.g. `297.50`) — NOT centavos. */
     value?: number;
     description?: string;
     /** HTTPS URL of the product cover image. */
@@ -585,6 +662,7 @@ interface CreateProductParams {
 }
 interface UpdateProductParams {
     name?: string;
+    /** Price in decimal BRL / reais (e.g. `297.50`) — NOT centavos. */
     value?: number;
     description?: string;
     image?: string;
@@ -789,27 +867,27 @@ interface SetProductPortalConfigParams {
 }
 
 /**
- * Charges — the core of the Garu API.
+ * Charges — create and manage payments against a product.
  *
- * A charge represents a single payment attempt against a product. The SDK
- * surfaces charges under `garu.charges` even though the backend route is
- * `/api/transactions` — this matches Stripe convention and is the name every
- * other Garu surface (MCP, CLI, docs) uses.
+ * Backed by `/api/v1/charges`, the versioned public contract. A charge is keyed
+ * by `uuid`; there is no numeric id. Create returns everything needed to render
+ * a transparent checkout: the PIX EMV (`pix.code`), the boleto line and a
+ * Garu-hosted PDF (`boleto`), or the card authorization (`card`).
  */
 declare class Charges {
     private readonly http;
     constructor(http: HttpClient);
     /**
-     * Create a charge (PIX, credit card, or boleto).
+     * Create a charge (PIX, boleto, or credit card).
      *
-     * Automatically attaches an `X-Idempotency-Key` header — if you don't pass
-     * `idempotencyKey`, the SDK generates a UUIDv4. Safe to retry: the backend
-     * caches the first response for 24h.
+     * Attaches an `X-Idempotency-Key` header automatically — if you don't pass
+     * `idempotencyKey`, the SDK generates a UUIDv4. Safe to retry: the same key
+     * returns the original charge for 24h.
      *
      * @example
-     * // PIX charge
+     * // PIX — render charge.pix.code as a QR in your own checkout
      * const charge = await garu.charges.create({
-     *   productId: 'b3f2c1e8-6e4a-4b9f-9d1c-2a1f6c3d4e5f',
+     *   productId: 'a1b2c3d4-e5f6-7890-abcd-ef1234567890',
      *   paymentMethod: 'pix',
      *   customer: {
      *     name: 'Maria Silva',
@@ -818,53 +896,62 @@ declare class Charges {
      *     phone: '11987654321'
      *   }
      * });
-     * // charge.id, charge.status
+     * console.log(charge.uuid, charge.pix?.code);
      *
      * @example
-     * // Credit card charge, 3 installments
+     * // Credit card, 2 installments. Server-to-server only (PCI scope).
      * const charge = await garu.charges.create({
-     *   productId: 'b3f2c1e8-6e4a-4b9f-9d1c-2a1f6c3d4e5f',
-     *   paymentMethod: 'credit_card',
+     *   productId: 'a1b2c3d4-e5f6-7890-abcd-ef1234567890',
+     *   paymentMethod: 'creditCard',
      *   customer: { name: 'Maria Silva', email: 'maria@exemplo.com.br', document: '12345678909', phone: '11987654321' },
-     *   cardInfo: {
-     *     cardNumber: '4111111111111111',
-     *     cvv: '123',
-     *     expirationDate: '2030-12',
+     *   card: {
+     *     number: '4111111111111111',
      *     holderName: 'MARIA SILVA',
-     *     installments: 3
+     *     expirationDate: '2030-12',
+     *     cvv: '123',
+     *     installments: 2
      *   }
      * });
+     * // charge.amount is the base price; charge.chargedTotal is what was charged.
      */
     create(params: CreateChargeParams): Promise<Charge>;
     /**
-     * List charges for the authenticated seller, with pagination and filters.
+     * Retrieve a charge by uuid.
      *
      * @example
-     * const { data, meta } = await garu.charges.list({ status: 'paid', limit: 10 });
-     * // meta.total paid charges
+     * const charge = await garu.charges.retrieve('6f1c9b2e-4a7d-4f0b-9a3e-1d2c3b4a5e6f');
+     * if (charge.status === 'paid') fulfil(charge);
      */
-    list(params?: ListChargesParams): Promise<ChargeList>;
+    retrieve(uuid: string): Promise<Charge>;
     /**
-     * Fetch a single charge by numeric ID.
+     * List charges for the authenticated account, newest first by default.
      *
      * @example
-     * const charge = await garu.charges.get(4472);
-     * if (charge.status === 'paid') { ... }
+     * const { data, totalCount } = await garu.charges.list({ status: 'paid', limit: 50 });
+     * console.log(`${data.length} of ${totalCount} paid charges`);
      */
-    get(id: number): Promise<Charge>;
+    list(params?: ListChargesParams): Promise<ChargeList>;
     /**
-     * Refund a charge — fully, or partially by passing `amount` in centavos.
+     * Refund a charge, fully or partially. `amount` is in reais.
+     *
+     * For a Pix Automático charge the refund is a devolução: it returns with the
+     * charge in `refund_pending`, reaching `refunded` only once the transfer
+     * settles.
      *
      * @example
-     * // Full refund
-     * await garu.charges.refund(4472);
+     * await garu.charges.refund('6f1c9b2e-...');                       // full
+     * await garu.charges.refund('6f1c9b2e-...', { amount: 10.0 });     // R$10,00
+     */
+    refund(uuid: string, params?: RefundChargeParams): Promise<Charge>;
+    /**
+     * Cancel an unpaid charge.
      *
      * @example
-     * // Partial refund of R$ 10,00
-     * await garu.charges.refund(4472, { amount: 1000, reason: 'customer_request' });
+     * const { canceled } = await garu.charges.cancel('6f1c9b2e-...');
      */
-    refund(id: number, params?: RefundChargeParams): Promise<Charge>;
-    private buildCreateBody;
+    cancel(uuid: string): Promise<CancelChargeResult>;
+    private get;
+    private post;
 }
 
 /**
@@ -1023,7 +1110,7 @@ declare class Products {
      * List products for the authenticated seller, with pagination and search.
      *
      * @example
-     * const { data, meta } = await garu.products.list({ search: 'curso', limit: 10 });
+     * const { data, totalCount } = await garu.products.list({ search: 'curso', limit: 10 });
      */
     list(params?: ListProductsParams): Promise<ProductList>;
     /**
@@ -1047,7 +1134,7 @@ declare class Products {
      * @example
      * const product = await garu.products.create({
      *   name: 'Plano Mensal',
-     *   value: 4990, // R$ 49,90 in centavos
+     *   value: 49.90, // R$ 49,90 in reais (decimal BRL), NOT centavos
      *   description: 'Acesso completo à plataforma',
      *   pix: true,
      *   creditCard: true,
@@ -1061,13 +1148,13 @@ declare class Products {
      * Update a product (partial PATCH — only the fields you pass are changed).
      * Returns the updated product.
      *
-     * `id` accepts the numeric id or the product UUID — the same identifiers
-     * accepted elsewhere on the `/api/products/:id` path (see
+     * `id` accepts the product UUID (recommended) or the legacy numeric id —
+     * both resolve on the `/api/v1/products/:id` path (see
      * {@link ProductPortalConfigResource}).
      *
      * @example
      * const updated = await garu.products.update('b3f2c1e8-6e4a-4b9f-9d1c-2a1f6c3d4e5f', {
-     *   value: 5990,
+     *   value: 59.90, // reais (decimal BRL), NOT centavos
      *   pixAutomatic: true // turn on Pix Automático for this product
      * });
      */
@@ -1480,4 +1567,4 @@ declare class GaruServerError extends GaruAPIError {
     constructor(message: string, status: number, requestId: string | null, body: unknown);
 }
 
-export { type CancelAtPeriodEndScheduledChargeParams, type CancelRecurrenceScheduledChargeParams, type CardInfo, type ChangePaymentMethodScheduledChargeParams, type Charge, type ChargeList, type ChargeNowOutcome, type ChargeNowReason, type ChargeNowResult, type ChargeStatus, type CreateChargeParams, type CreateCustomerParams, type CreateProductParams, type CreateScheduledChargeParams, type Customer, type CustomerList, type CustomerRecord, type FailurePayload, Garu, GaruAPIError, GaruAuthenticationError, GaruConnectionError, GaruError, type GaruErrorCode, type GaruFailureCode, GaruNotFoundError, type GaruOptions, GaruPermissionError, GaruRateLimitError, GaruServerError, GaruSignatureVerificationError, GaruValidationError, type ListChargesParams, type ListCustomersParams, type ListProductsParams, type ListScheduledChargeAttemptsParams, type ListScheduledChargesParams, type ListWebhookEventsParams, type MarkPaidScheduledChargeParams, type MetaFeatures, type MetaResponse, type PaginatedList, type PauseScheduledChargeParams, type PaymentMethod, type PaymentMethodExpiredPayload, type PaymentMethodExpiringPayload, type PostponeScheduledChargeParams, type Product, type ProductList, type ProductPortalConfig, type RecurrenceConfig, type RecurrenceInterval, type RefundChargeParams, type ResendWebhookEventParams, type ScheduledChargeActor, type ScheduledChargeAttempt, type ScheduledChargeAttemptList, type ScheduledChargeAttemptSource, type ScheduledChargeAttemptStatus, type ScheduledChargeDetail, type ScheduledChargeEvent, type ScheduledChargeEventType, type ScheduledChargeLinkedTransaction, type ScheduledChargeList, type ScheduledChargeRecord, type ScheduledChargeStatus, type ScheduledChargeType, type ScheduledPaymentMethod, type SetProductPortalConfigParams, type UpdateCustomerParams, type UpdateProductParams, type VerifiedWebhook, type VerifyWebhookParams, type WebhookEvent, type WebhookEventEndpoint, type WebhookEventList, type WebhookEventStatus, type WirePaymentMethodId, webhooks };
+export { type CancelAtPeriodEndScheduledChargeParams, type CancelChargeResult, type CancelRecurrenceScheduledChargeParams, type CardInput, type ChangePaymentMethodScheduledChargeParams, type Charge, type ChargeList, type ChargeNowOutcome, type ChargeNowReason, type ChargeNowResult, type ChargePaymentMethod, type ChargeStatus, type CreateChargeParams, type CreateCustomerParams, type CreateProductParams, type CreateScheduledChargeParams, type Customer, type CustomerList, type CustomerRecord, type FailurePayload, Garu, GaruAPIError, GaruAuthenticationError, GaruConnectionError, GaruError, type GaruErrorCode, type GaruFailureCode, GaruNotFoundError, type GaruOptions, GaruPermissionError, GaruRateLimitError, GaruServerError, GaruSignatureVerificationError, GaruValidationError, type ListChargesParams, type ListCustomersParams, type ListProductsParams, type ListScheduledChargeAttemptsParams, type ListScheduledChargesParams, type ListWebhookEventsParams, type MarkPaidScheduledChargeParams, type MetaFeatures, type MetaResponse, type PaginatedList, type PauseScheduledChargeParams, type PaymentMethodExpiredPayload, type PaymentMethodExpiringPayload, type PostponeScheduledChargeParams, type Product, type ProductList, type ProductPortalConfig, type RecurrenceConfig, type RecurrenceInterval, type RefundChargeParams, type ResendWebhookEventParams, type ScheduledChargeActor, type ScheduledChargeAttempt, type ScheduledChargeAttemptList, type ScheduledChargeAttemptSource, type ScheduledChargeAttemptStatus, type ScheduledChargeDetail, type ScheduledChargeEvent, type ScheduledChargeEventType, type ScheduledChargeLinkedTransaction, type ScheduledChargeList, type ScheduledChargeRecord, type ScheduledChargeStatus, type ScheduledChargeType, type ScheduledPaymentMethod, type SetProductPortalConfigParams, type UpdateCustomerParams, type UpdateProductParams, type VerifiedWebhook, type VerifyWebhookParams, type WebhookEvent, type WebhookEventEndpoint, type WebhookEventList, type WebhookEventStatus, webhooks };