@garuhq/node 0.1.0 → 0.2.0

package/dist/index.d.cts

@@ -181,6 +181,84 @@ interface RefundChargeParams {
     reason?: string;
     idempotencyKey?: string;
 }
+interface ListChargesParams {
+    /** Page number (1-based). Default: 1. */
+    page?: number;
+    /** Items per page (1–100). Default: 20. */
+    limit?: number;
+    /** Filter by status (e.g. `paid`, `pending`). */
+    status?: string;
+    /** Search by customer name, email, or document. */
+    search?: string;
+    /** Filter by payment method (`pix`, `creditcard`, `boleto`). */
+    paymentMethod?: string;
+}
+interface PaginatedList<T> {
+    data: T[];
+    meta: {
+        page: number;
+        limit: number;
+        total: number;
+        totalPages: number;
+    };
+}
+type ChargeList = PaginatedList<Charge>;
+interface CustomerRecord {
+    id: number;
+    name: string;
+    email: string;
+    document: string;
+    phone: string;
+    personType: string;
+    zipCode?: string | null;
+    street?: string | null;
+    number?: string | null;
+    complement?: string | null;
+    neighborhood?: string | null;
+    city?: string | null;
+    state?: string | null;
+    createdAt: string;
+    updatedAt: string;
+    [key: string]: unknown;
+}
+type CustomerList = PaginatedList<CustomerRecord>;
+interface CreateCustomerParams {
+    name: string;
+    email: string;
+    /** CPF (11 digits) or CNPJ (14 digits), digits only. */
+    document: string;
+    /** 10 or 11 digits with area code. */
+    phone: string;
+    /** `fisica` or `juridica`. */
+    personType: 'fisica' | 'juridica';
+    zipCode?: string;
+    street?: string;
+    number?: string;
+    complement?: string;
+    neighborhood?: string;
+    city?: string;
+    /** 2-letter uppercase state code, e.g. `SP`. */
+    state?: string;
+}
+interface UpdateCustomerParams {
+    name?: string;
+    email?: string;
+    document?: string;
+    phone?: string;
+    personType?: 'fisica' | 'juridica';
+    zipCode?: string;
+    street?: string;
+    number?: string;
+    complement?: string;
+    neighborhood?: string;
+    city?: string;
+    state?: string;
+}
+interface ListCustomersParams {
+    page?: number;
+    limit?: number;
+    search?: string;
+}
 interface MetaFeatures {
     subscriptions: boolean;
     checkout_sessions: boolean;
@@ -233,7 +311,7 @@ declare class Charges {
      *     phone: '11987654321'
      *   }
      * });
-     * console.log(charge.id, charge.status);
+     * // charge.id, charge.status
      *
      * @example
      * // Credit card charge, 3 installments
@@ -251,6 +329,14 @@ declare class Charges {
      * });
      */
     create(params: CreateChargeParams): Promise<Charge>;
+    /**
+     * List charges for the authenticated seller, with pagination and filters.
+     *
+     * @example
+     * const { data, meta } = await garu.charges.list({ status: 'paid', limit: 10 });
+     * // meta.total paid charges
+     */
+    list(params?: ListChargesParams): Promise<ChargeList>;
     /**
      * Fetch a single charge by numeric ID.
      *
@@ -274,6 +360,59 @@ declare class Charges {
     private buildCreateBody;
 }
 
+/**
+ * Customers — manage your customer base.
+ *
+ * Customers are scoped to the seller identified by the API key. The backend
+ * uses a junction table (`customer_seller_profile`) so the same person can
+ * exist across multiple sellers without duplication.
+ */
+declare class Customers {
+    private readonly http;
+    constructor(http: HttpClient);
+    /**
+     * Create a customer and link it to the current seller.
+     *
+     * @example
+     * const customer = await garu.customers.create({
+     *   name: 'Maria Silva',
+     *   email: 'maria@exemplo.com.br',
+     *   document: '12345678909',
+     *   phone: '11987654321',
+     *   personType: 'fisica'
+     * });
+     */
+    create(params: CreateCustomerParams): Promise<CustomerRecord>;
+    /**
+     * List customers for the authenticated seller, with pagination and search.
+     *
+     * @example
+     * const { data, meta } = await garu.customers.list({ search: 'maria', limit: 10 });
+     */
+    list(params?: ListCustomersParams): Promise<CustomerList>;
+    /**
+     * Fetch a single customer by numeric ID.
+     *
+     * @example
+     * const customer = await garu.customers.get(42);
+     */
+    get(id: number): Promise<CustomerRecord>;
+    /**
+     * Update a customer's profile for the current seller.
+     *
+     * @example
+     * const updated = await garu.customers.update(42, { name: 'Maria Santos' });
+     */
+    update(id: number, params: UpdateCustomerParams): Promise<CustomerRecord>;
+    /**
+     * Remove a customer from the current seller.
+     *
+     * @example
+     * await garu.customers.delete(42);
+     */
+    delete(id: number): Promise<void>;
+}
+
 /**
  * Meta — capability introspection.
  *
@@ -331,6 +470,7 @@ interface GaruOptions {
  */
 declare class Garu {
     readonly charges: Charges;
+    readonly customers: Customers;
     readonly meta: Meta;
     /**
      * Webhook helpers. Available both as an instance member and as a static —
@@ -390,4 +530,4 @@ declare class GaruServerError extends GaruAPIError {
     constructor(message: string, status: number, requestId: string | null, body: unknown);
 }
 
-export { type CardInfo, type Charge, type ChargeStatus, type CreateChargeParams, type Customer, Garu, GaruAPIError, GaruAuthenticationError, GaruConnectionError, GaruError, type GaruErrorCode, GaruNotFoundError, type GaruOptions, GaruPermissionError, GaruRateLimitError, GaruServerError, GaruSignatureVerificationError, GaruValidationError, type MetaFeatures, type MetaResponse, type PaymentMethod, type RefundChargeParams, type VerifiedWebhook, type VerifyWebhookParams, type WirePaymentMethodId, webhooks };
+export { type CardInfo, type Charge, type ChargeList, type ChargeStatus, type CreateChargeParams, type CreateCustomerParams, type Customer, type CustomerList, type CustomerRecord, Garu, GaruAPIError, GaruAuthenticationError, GaruConnectionError, GaruError, type GaruErrorCode, GaruNotFoundError, type GaruOptions, GaruPermissionError, GaruRateLimitError, GaruServerError, GaruSignatureVerificationError, GaruValidationError, type ListChargesParams, type ListCustomersParams, type MetaFeatures, type MetaResponse, type PaginatedList, type PaymentMethod, type RefundChargeParams, type UpdateCustomerParams, type VerifiedWebhook, type VerifyWebhookParams, type WirePaymentMethodId, webhooks };

package/dist/index.d.ts

@@ -181,6 +181,84 @@ interface RefundChargeParams {
     reason?: string;
     idempotencyKey?: string;
 }
+interface ListChargesParams {
+    /** Page number (1-based). Default: 1. */
+    page?: number;
+    /** Items per page (1–100). Default: 20. */
+    limit?: number;
+    /** Filter by status (e.g. `paid`, `pending`). */
+    status?: string;
+    /** Search by customer name, email, or document. */
+    search?: string;
+    /** Filter by payment method (`pix`, `creditcard`, `boleto`). */
+    paymentMethod?: string;
+}
+interface PaginatedList<T> {
+    data: T[];
+    meta: {
+        page: number;
+        limit: number;
+        total: number;
+        totalPages: number;
+    };
+}
+type ChargeList = PaginatedList<Charge>;
+interface CustomerRecord {
+    id: number;
+    name: string;
+    email: string;
+    document: string;
+    phone: string;
+    personType: string;
+    zipCode?: string | null;
+    street?: string | null;
+    number?: string | null;
+    complement?: string | null;
+    neighborhood?: string | null;
+    city?: string | null;
+    state?: string | null;
+    createdAt: string;
+    updatedAt: string;
+    [key: string]: unknown;
+}
+type CustomerList = PaginatedList<CustomerRecord>;
+interface CreateCustomerParams {
+    name: string;
+    email: string;
+    /** CPF (11 digits) or CNPJ (14 digits), digits only. */
+    document: string;
+    /** 10 or 11 digits with area code. */
+    phone: string;
+    /** `fisica` or `juridica`. */
+    personType: 'fisica' | 'juridica';
+    zipCode?: string;
+    street?: string;
+    number?: string;
+    complement?: string;
+    neighborhood?: string;
+    city?: string;
+    /** 2-letter uppercase state code, e.g. `SP`. */
+    state?: string;
+}
+interface UpdateCustomerParams {
+    name?: string;
+    email?: string;
+    document?: string;
+    phone?: string;
+    personType?: 'fisica' | 'juridica';
+    zipCode?: string;
+    street?: string;
+    number?: string;
+    complement?: string;
+    neighborhood?: string;
+    city?: string;
+    state?: string;
+}
+interface ListCustomersParams {
+    page?: number;
+    limit?: number;
+    search?: string;
+}
 interface MetaFeatures {
     subscriptions: boolean;
     checkout_sessions: boolean;
@@ -233,7 +311,7 @@ declare class Charges {
      *     phone: '11987654321'
      *   }
      * });
-     * console.log(charge.id, charge.status);
+     * // charge.id, charge.status
      *
      * @example
      * // Credit card charge, 3 installments
@@ -251,6 +329,14 @@ declare class Charges {
      * });
      */
     create(params: CreateChargeParams): Promise<Charge>;
+    /**
+     * List charges for the authenticated seller, with pagination and filters.
+     *
+     * @example
+     * const { data, meta } = await garu.charges.list({ status: 'paid', limit: 10 });
+     * // meta.total paid charges
+     */
+    list(params?: ListChargesParams): Promise<ChargeList>;
     /**
      * Fetch a single charge by numeric ID.
      *
@@ -274,6 +360,59 @@ declare class Charges {
     private buildCreateBody;
 }
 
+/**
+ * Customers — manage your customer base.
+ *
+ * Customers are scoped to the seller identified by the API key. The backend
+ * uses a junction table (`customer_seller_profile`) so the same person can
+ * exist across multiple sellers without duplication.
+ */
+declare class Customers {
+    private readonly http;
+    constructor(http: HttpClient);
+    /**
+     * Create a customer and link it to the current seller.
+     *
+     * @example
+     * const customer = await garu.customers.create({
+     *   name: 'Maria Silva',
+     *   email: 'maria@exemplo.com.br',
+     *   document: '12345678909',
+     *   phone: '11987654321',
+     *   personType: 'fisica'
+     * });
+     */
+    create(params: CreateCustomerParams): Promise<CustomerRecord>;
+    /**
+     * List customers for the authenticated seller, with pagination and search.
+     *
+     * @example
+     * const { data, meta } = await garu.customers.list({ search: 'maria', limit: 10 });
+     */
+    list(params?: ListCustomersParams): Promise<CustomerList>;
+    /**
+     * Fetch a single customer by numeric ID.
+     *
+     * @example
+     * const customer = await garu.customers.get(42);
+     */
+    get(id: number): Promise<CustomerRecord>;
+    /**
+     * Update a customer's profile for the current seller.
+     *
+     * @example
+     * const updated = await garu.customers.update(42, { name: 'Maria Santos' });
+     */
+    update(id: number, params: UpdateCustomerParams): Promise<CustomerRecord>;
+    /**
+     * Remove a customer from the current seller.
+     *
+     * @example
+     * await garu.customers.delete(42);
+     */
+    delete(id: number): Promise<void>;
+}
+
 /**
  * Meta — capability introspection.
  *
@@ -331,6 +470,7 @@ interface GaruOptions {
  */
 declare class Garu {
     readonly charges: Charges;
+    readonly customers: Customers;
     readonly meta: Meta;
     /**
      * Webhook helpers. Available both as an instance member and as a static —
@@ -390,4 +530,4 @@ declare class GaruServerError extends GaruAPIError {
     constructor(message: string, status: number, requestId: string | null, body: unknown);
 }
 
-export { type CardInfo, type Charge, type ChargeStatus, type CreateChargeParams, type Customer, Garu, GaruAPIError, GaruAuthenticationError, GaruConnectionError, GaruError, type GaruErrorCode, GaruNotFoundError, type GaruOptions, GaruPermissionError, GaruRateLimitError, GaruServerError, GaruSignatureVerificationError, GaruValidationError, type MetaFeatures, type MetaResponse, type PaymentMethod, type RefundChargeParams, type VerifiedWebhook, type VerifyWebhookParams, type WirePaymentMethodId, webhooks };
+export { type CardInfo, type Charge, type ChargeList, type ChargeStatus, type CreateChargeParams, type CreateCustomerParams, type Customer, type CustomerList, type CustomerRecord, Garu, GaruAPIError, GaruAuthenticationError, GaruConnectionError, GaruError, type GaruErrorCode, GaruNotFoundError, type GaruOptions, GaruPermissionError, GaruRateLimitError, GaruServerError, GaruSignatureVerificationError, GaruValidationError, type ListChargesParams, type ListCustomersParams, type MetaFeatures, type MetaResponse, type PaginatedList, type PaymentMethod, type RefundChargeParams, type UpdateCustomerParams, type VerifiedWebhook, type VerifyWebhookParams, type WirePaymentMethodId, webhooks };

package/dist/index.js

@@ -78,31 +78,24 @@ var GaruServerError = class extends GaruAPIError {
 };
 function mapApiError(status, body, requestId, retryAfterSec) {
   const message = extractMessage(body) ?? `Garu API returned HTTP ${status}`;
-  if (status === 401)
-    return new GaruAuthenticationError(message, status, requestId, body);
-  if (status === 403)
-    return new GaruPermissionError(message, status, requestId, body);
-  if (status === 404)
-    return new GaruNotFoundError(message, status, requestId, body);
+  if (status === 401) return new GaruAuthenticationError(message, status, requestId, body);
+  if (status === 403) return new GaruPermissionError(message, status, requestId, body);
+  if (status === 404) return new GaruNotFoundError(message, status, requestId, body);
   if (status === 400 || status === 422) {
     return new GaruValidationError(message, status, requestId, body);
   }
   if (status === 429) {
     return new GaruRateLimitError(message, status, requestId, body, retryAfterSec);
   }
-  if (status >= 500)
-    return new GaruServerError(message, status, requestId, body);
+  if (status >= 500) return new GaruServerError(message, status, requestId, body);
   return new GaruAPIError("api_error", message, status, requestId, body);
 }
 function extractMessage(body) {
-  if (typeof body === "string")
-    return body;
+  if (typeof body === "string") return body;
   if (body && typeof body === "object") {
     const m = body.message;
-    if (typeof m === "string")
-      return m;
-    if (Array.isArray(m) && m.every((x) => typeof x === "string"))
-      return m.join("; ");
+    if (typeof m === "string") return m;
+    if (Array.isArray(m) && m.every((x) => typeof x === "string")) return m.join("; ");
   }
   return null;
 }
@@ -124,8 +117,7 @@ var HttpClient = class {
       Accept: "application/json",
       "User-Agent": cfg.userAgent
     };
-    if (cfg.apiKey)
-      headers.Authorization = `Bearer ${cfg.apiKey}`;
+    if (cfg.apiKey) headers.Authorization = `Bearer ${cfg.apiKey}`;
     this.client = createClient({
       baseUrl: cfg.baseUrl.replace(/\/+$/, ""),
       fetch: fetchImpl,
@@ -160,12 +152,10 @@ var HttpClient = class {
         continue;
       } catch (err) {
         clearTimeout(timer);
-        if (isGaruApiError(err))
-          throw err;
+        if (isGaruApiError(err)) throw err;
         const connErr = err instanceof Error && err.name === "AbortError" ? new GaruConnectionError(`Request timed out after ${this.cfg.timeoutMs}ms`, err) : new GaruConnectionError(err instanceof Error ? err.message : "Network error", err);
         lastError = connErr;
-        if (attempt === this.cfg.maxRetries)
-          throw connErr;
+        if (attempt === this.cfg.maxRetries) throw connErr;
         await sleep(backoffDelay(attempt, null));
         continue;
       }
@@ -177,8 +167,7 @@ function isGaruApiError(err) {
   return err instanceof Error && err.name.startsWith("Garu") && err.name.endsWith("Error");
 }
 function parseRetryAfter(value) {
-  if (!value)
-    return null;
+  if (!value) return null;
   const n = Number(value);
   return Number.isFinite(n) && n >= 0 ? n : null;
 }
@@ -207,6 +196,7 @@ var Charges = class {
   constructor(http) {
     this.http = http;
   }
+  http;
   /**
    * Create a charge (PIX, credit card, or boleto).
    *
@@ -226,7 +216,7 @@ var Charges = class {
    *     phone: '11987654321'
    *   }
    * });
-   * console.log(charge.id, charge.status);
+   * // charge.id, charge.status
    *
    * @example
    * // Credit card charge, 3 installments
@@ -254,6 +244,28 @@ var Charges = class {
       })
     );
   }
+  /**
+   * List charges for the authenticated seller, with pagination and filters.
+   *
+   * @example
+   * const { data, meta } = await garu.charges.list({ status: 'paid', limit: 10 });
+   * // meta.total paid charges
+   */
+  async list(params = {}) {
+    const query = {};
+    if (params.page !== void 0) query.page = String(params.page);
+    if (params.limit !== void 0) query.limit = String(params.limit);
+    if (params.status) query.status = params.status;
+    if (params.search) query.search = params.search;
+    if (params.paymentMethod) query.paymentMethod = params.paymentMethod;
+    const qs = new URLSearchParams(query).toString();
+    const url = `/api/transactions${qs ? `?${qs}` : ""}`;
+    return this.http.call(
+      (signal) => this.http.client.GET(url, { signal }).then(
+        (r) => r
+      )
+    );
+  }
   /**
    * Fetch a single charge by numeric ID.
    *
@@ -283,10 +295,8 @@ var Charges = class {
   async refund(id, params = {}) {
     const idempotencyKey = params.idempotencyKey ?? generateIdempotencyKey();
     const body = {};
-    if (params.amount !== void 0)
-      body.amount = params.amount;
-    if (params.reason !== void 0)
-      body.reason = params.reason;
+    if (params.amount !== void 0) body.amount = params.amount;
+    if (params.reason !== void 0) body.reason = params.reason;
     return this.http.call(
       (signal) => this.http.client.POST("/api/transactions/{id}/refund", {
         params: { path: { id } },
@@ -304,24 +314,109 @@ var Charges = class {
       link: params.link ?? null,
       affiliateId: params.affiliateId ?? null
     };
-    if (params.additionalInfo !== void 0)
-      body.additionalInfo = params.additionalInfo;
-    if (params.priceId !== void 0)
-      body.priceId = params.priceId;
+    if (params.additionalInfo !== void 0) body.additionalInfo = params.additionalInfo;
+    if (params.priceId !== void 0) body.priceId = params.priceId;
     if (params.checkoutSessionToken !== void 0) {
       body.checkoutSessionToken = params.checkoutSessionToken;
     }
-    if (params.cardInfo)
-      body.CardInfo = params.cardInfo;
+    if (params.cardInfo) body.CardInfo = params.cardInfo;
     return body;
   }
 };
 
+// src/resources/customers.ts
+var Customers = class {
+  constructor(http) {
+    this.http = http;
+  }
+  http;
+  /**
+   * Create a customer and link it to the current seller.
+   *
+   * @example
+   * const customer = await garu.customers.create({
+   *   name: 'Maria Silva',
+   *   email: 'maria@exemplo.com.br',
+   *   document: '12345678909',
+   *   phone: '11987654321',
+   *   personType: 'fisica'
+   * });
+   */
+  async create(params) {
+    return this.http.call(
+      (signal) => this.http.client.POST("/api/customers", {
+        body: params,
+        signal
+      }).then((r) => r)
+    );
+  }
+  /**
+   * List customers for the authenticated seller, with pagination and search.
+   *
+   * @example
+   * const { data, meta } = await garu.customers.list({ search: 'maria', limit: 10 });
+   */
+  async list(params = {}) {
+    const query = {};
+    if (params.page !== void 0) query.page = String(params.page);
+    if (params.limit !== void 0) query.limit = String(params.limit);
+    if (params.search) query.search = params.search;
+    const qs = new URLSearchParams(query).toString();
+    const url = `/api/customers${qs ? `?${qs}` : ""}`;
+    return this.http.call(
+      (signal) => this.http.client.GET(url, { signal }).then(
+        (r) => r
+      )
+    );
+  }
+  /**
+   * Fetch a single customer by numeric ID.
+   *
+   * @example
+   * const customer = await garu.customers.get(42);
+   */
+  async get(id) {
+    return this.http.call(
+      (signal) => this.http.client.GET(`/api/customers/${id}`, { signal }).then(
+        (r) => r
+      )
+    );
+  }
+  /**
+   * Update a customer's profile for the current seller.
+   *
+   * @example
+   * const updated = await garu.customers.update(42, { name: 'Maria Santos' });
+   */
+  async update(id, params) {
+    return this.http.call(
+      (signal) => this.http.client.PUT(`/api/customers/${id}`, {
+        body: params,
+        signal
+      }).then((r) => r)
+    );
+  }
+  /**
+   * Remove a customer from the current seller.
+   *
+   * @example
+   * await garu.customers.delete(42);
+   */
+  async delete(id) {
+    await this.http.call(
+      (signal) => this.http.client.DELETE(`/api/customers/${id}`, { signal }).then(
+        (r) => r
+      )
+    );
+  }
+};
+
 // src/resources/meta.ts
 var Meta = class {
   constructor(http) {
     this.http = http;
   }
+  http;
   /**
    * Fetch the API's current capability payload.
    *
@@ -377,21 +472,17 @@ function parseSignatureHeader(header) {
   const fields = {};
   for (const part of header.split(",")) {
     const idx = part.indexOf("=");
-    if (idx === -1)
-      return null;
+    if (idx === -1) return null;
     const key = part.slice(0, idx).trim();
     const value = part.slice(idx + 1).trim();
-    if (!key || !value)
-      return null;
+    if (!key || !value) return null;
     fields[key] = value;
   }
   const t = fields.t;
   const v1 = fields.v1;
-  if (!t || !v1)
-    return null;
+  if (!t || !v1) return null;
   const timestamp = Number(t);
-  if (!Number.isFinite(timestamp) || !/^[a-f0-9]+$/i.test(v1))
-    return null;
+  if (!Number.isFinite(timestamp) || !/^[a-f0-9]+$/i.test(v1)) return null;
   return { timestamp, v1 };
 }
 
@@ -399,9 +490,10 @@ function parseSignatureHeader(header) {
 var DEFAULT_BASE_URL = "https://garu.com.br";
 var DEFAULT_TIMEOUT_MS = 3e4;
 var DEFAULT_MAX_RETRIES = 2;
-var SDK_VERSION = "0.1.0";
+var SDK_VERSION = "0.2.0";
 var Garu = class {
   charges;
+  customers;
   meta;
   /**
    * Webhook helpers. Available both as an instance member and as a static —
@@ -419,10 +511,11 @@ var Garu = class {
       fetch: options.fetch
     });
     this.charges = new Charges(http);
+    this.customers = new Customers(http);
     this.meta = new Meta(http);
   }
 };
 
 export { Garu, GaruAPIError, GaruAuthenticationError, GaruConnectionError, GaruError, GaruNotFoundError, GaruPermissionError, GaruRateLimitError, GaruServerError, GaruSignatureVerificationError, GaruValidationError, webhooks };
-//# sourceMappingURL=out.js.map
+//# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map