@garuhq/node 0.1.1 → 0.3.0

package/dist/index.d.cts

@@ -181,6 +181,119 @@ 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 Product {
+    id: number;
+    uuid: string;
+    name: string;
+    description: string;
+    image: string;
+    /** Price in centavos (BRL × 100). */
+    value: number;
+    sellerId: number;
+    sellerName?: string;
+    pix: boolean;
+    boleto: boolean;
+    creditCard: boolean;
+    installments: number[];
+    tags?: string[];
+    isSubscription?: boolean;
+    subscriptionType?: string;
+    unitLabel?: string;
+    comission?: string;
+    valueWithComission?: number;
+    returnUrl?: string;
+    returnUrlButtonText?: string;
+    createdAt: string;
+    updatedAt: string;
+    [key: string]: unknown;
+}
+type ProductList = PaginatedList<Product>;
+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. */
+    tab?: string;
+}
 interface MetaFeatures {
     subscriptions: boolean;
     checkout_sessions: boolean;
@@ -191,7 +304,7 @@ interface MetaFeatures {
 interface MetaResponse {
     name: string;
     version: string;
-    environment: 'production' | 'staging' | 'development' | string;
+    environment: string;
     api_version: string;
     payment_methods: string[];
     currencies: string[];
@@ -233,7 +346,7 @@ declare class Charges {
      *     phone: '11987654321'
      *   }
      * });
-     * console.log(charge.id, charge.status);
+     * // charge.id, charge.status
      *
      * @example
      * // Credit card charge, 3 installments
@@ -251,6 +364,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 +395,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.
  *
@@ -295,6 +469,32 @@ declare class Meta {
     get(): Promise<MetaResponse>;
 }
 
+/**
+ * Products — discover products available to charge.
+ *
+ * Products are scoped to the seller identified by the API key. The UUID
+ * returned here is the same identifier accepted by `charges.create({ productId })`.
+ */
+declare class Products {
+    private readonly http;
+    constructor(http: HttpClient);
+    /**
+     * List products for the authenticated seller, with pagination and search.
+     *
+     * @example
+     * const { data, meta } = await garu.products.list({ search: 'curso', limit: 10 });
+     */
+    list(params?: ListProductsParams): Promise<ProductList>;
+    /**
+     * Fetch a single product by UUID — the same identifier used by
+     * `charges.create({ productId })`.
+     *
+     * @example
+     * const product = await garu.products.get('b3f2c1e8-6e4a-4b9f-9d1c-2a1f6c3d4e5f');
+     */
+    get(uuid: string): Promise<Product>;
+}
+
 interface GaruOptions {
     /**
      * Your Garu API key. `sk_live_…` for production, `sk_test_…` for test mode.
@@ -331,7 +531,9 @@ interface GaruOptions {
  */
 declare class Garu {
     readonly charges: Charges;
+    readonly customers: Customers;
     readonly meta: Meta;
+    readonly products: Products;
     /**
      * Webhook helpers. Available both as an instance member and as a static —
      * `Garu.webhooks.verify(...)` works without constructing a client.
@@ -390,4 +592,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 ListProductsParams, type MetaFeatures, type MetaResponse, type PaginatedList, type PaymentMethod, type Product, type ProductList, type RefundChargeParams, type UpdateCustomerParams, type VerifiedWebhook, type VerifyWebhookParams, type WirePaymentMethodId, webhooks };

package/dist/index.d.ts

@@ -181,6 +181,119 @@ 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 Product {
+    id: number;
+    uuid: string;
+    name: string;
+    description: string;
+    image: string;
+    /** Price in centavos (BRL × 100). */
+    value: number;
+    sellerId: number;
+    sellerName?: string;
+    pix: boolean;
+    boleto: boolean;
+    creditCard: boolean;
+    installments: number[];
+    tags?: string[];
+    isSubscription?: boolean;
+    subscriptionType?: string;
+    unitLabel?: string;
+    comission?: string;
+    valueWithComission?: number;
+    returnUrl?: string;
+    returnUrlButtonText?: string;
+    createdAt: string;
+    updatedAt: string;
+    [key: string]: unknown;
+}
+type ProductList = PaginatedList<Product>;
+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. */
+    tab?: string;
+}
 interface MetaFeatures {
     subscriptions: boolean;
     checkout_sessions: boolean;
@@ -191,7 +304,7 @@ interface MetaFeatures {
 interface MetaResponse {
     name: string;
     version: string;
-    environment: 'production' | 'staging' | 'development' | string;
+    environment: string;
     api_version: string;
     payment_methods: string[];
     currencies: string[];
@@ -233,7 +346,7 @@ declare class Charges {
      *     phone: '11987654321'
      *   }
      * });
-     * console.log(charge.id, charge.status);
+     * // charge.id, charge.status
      *
      * @example
      * // Credit card charge, 3 installments
@@ -251,6 +364,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 +395,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.
  *
@@ -295,6 +469,32 @@ declare class Meta {
     get(): Promise<MetaResponse>;
 }
 
+/**
+ * Products — discover products available to charge.
+ *
+ * Products are scoped to the seller identified by the API key. The UUID
+ * returned here is the same identifier accepted by `charges.create({ productId })`.
+ */
+declare class Products {
+    private readonly http;
+    constructor(http: HttpClient);
+    /**
+     * List products for the authenticated seller, with pagination and search.
+     *
+     * @example
+     * const { data, meta } = await garu.products.list({ search: 'curso', limit: 10 });
+     */
+    list(params?: ListProductsParams): Promise<ProductList>;
+    /**
+     * Fetch a single product by UUID — the same identifier used by
+     * `charges.create({ productId })`.
+     *
+     * @example
+     * const product = await garu.products.get('b3f2c1e8-6e4a-4b9f-9d1c-2a1f6c3d4e5f');
+     */
+    get(uuid: string): Promise<Product>;
+}
+
 interface GaruOptions {
     /**
      * Your Garu API key. `sk_live_…` for production, `sk_test_…` for test mode.
@@ -331,7 +531,9 @@ interface GaruOptions {
  */
 declare class Garu {
     readonly charges: Charges;
+    readonly customers: Customers;
     readonly meta: Meta;
+    readonly products: Products;
     /**
      * Webhook helpers. Available both as an instance member and as a static —
      * `Garu.webhooks.verify(...)` works without constructing a client.
@@ -390,4 +592,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 ListProductsParams, type MetaFeatures, type MetaResponse, type PaginatedList, type PaymentMethod, type Product, type ProductList, type RefundChargeParams, type UpdateCustomerParams, type VerifiedWebhook, type VerifyWebhookParams, type WirePaymentMethodId, webhooks };