@geekapps/billing-fastify 0.13.0 → 0.16.1

package/README.md

@@ -47,7 +47,20 @@ const client = new BillingClient({
 await client.customers.create({ name: "...", email: "..." });
 ```
 
-O `mode` (dev/prod) é configurado uma única vez ao instanciar o cliente — nenhum método individual precisa recebê-lo novamente.
+O `mode` (dev/prod) é configurado uma única vez ao instanciar o cliente e vale para todas as chamadas (default: `"prod"`).
+
+### Override de modo por chamada
+
+Todo método aceita, no último parâmetro, `{ mode }` para sobrescrever o modo geral só naquela chamada — útil para testar algo novo em dev com o app inteiro em prod:
+
+```ts
+await client.charges.create({ customer_id, amount: 5000, method: "PIX" }, { mode: "dev" });
+await client.customers.list({}, { mode: "dev" });
+
+// várias chamadas seguidas no mesmo modo
+const dev = client.withMode("dev");
+await dev.items.list();
+```
 
 ## Cobrança avulsa simples (sempre cartão)
 

package/dist/index.d.ts

@@ -12,14 +12,30 @@ interface HttpClientOptions {
      */
     mode?: string | (() => string | Promise<string>);
 }
+/** Opções por chamada — sobrescrevem a configuração geral do cliente só naquela requisição. */
+interface RequestOptions {
+    /**
+     * Override do ambiente (dev/prod) apenas para esta chamada. Ex.: app inteiro em "prod"
+     * e uma cobrança de teste com `charges.create(input, { mode: "dev" })`.
+     */
+    mode?: "dev" | "prod" | (string & {});
+}
 declare class HttpClient {
     private readonly baseUrl;
     private readonly token;
     private readonly organizationId?;
     private readonly mode;
+    private readonly options;
     constructor(options: HttpClientOptions);
+    /**
+     * Cliente com as mesmas credenciais e o modo sobrescrito por `opts.mode` — sem override,
+     * devolve a própria instância (modo geral).
+     */
+    with(opts?: RequestOptions): HttpClient;
     private resolveToken;
     private resolveOrgId;
+    /** Modo efetivo desta instância (geral ou sobrescrito via `with`). */
+    currentMode(): Promise<string>;
     private resolveMode;
     request<T = unknown>(method: string, path: string, body?: unknown): Promise<T>;
     get<T>(path: string): Promise<T>;
@@ -131,9 +147,23 @@ interface CustomerInput {
     address_state?: string;
     address_postal_code?: string;
     address_country?: string;
-    /** Para CNPJ, completa com os dados da Receita Federal os campos não informados. Default: true. */
+    /**
+     * Para CNPJ, razão social e endereço vêm sempre da Receita Federal (o que for enviado é
+     * ignorado). Default: true.
+     */
     autofill?: boolean;
+    /**
+     * Obrigatório (`true`) quando a Receita não pôde ser consultada e os dados da empresa
+     * foram informados à mão: aceite da declaração de que as informações são verdadeiras e de
+     * que quem as forneceu responde por elas. Sem isso a API responde 422
+     * `{ code: "manual_declaration_required", declaration }`.
+     */
+    manual_declaration?: boolean;
 }
+/**
+ * Em empresa verificada (`registry_synced_at` preenchido), razão social e endereço não podem
+ * ser alterados (409) — use `customers.refreshRegistry(id)`.
+ */
 type CustomerUpdateInput = Partial<Omit<CustomerInput, "autofill" | "external_ref">> & {
     /** `null` remove a referência. */
     external_ref?: string | null;
@@ -164,6 +194,11 @@ interface Customer {
     /** Pessoa física: "***" quando presente. Empresa: completo. */
     address_line2: string | null;
     address_district: string | null;
+    /** Empresa: data da última sincronização de razão social/endereço com a Receita Federal
+     * (null = não verificada, dados declarados manualmente). */
+    registry_synced_at?: string | null;
+    /** Empresa não verificada: quando a declaração de veracidade foi aceita. */
+    registry_declared_at?: string | null;
     address_city: string | null;
     address_state: string | null;
     /** Mascarado, mantém só o prefixo (ex: "01310***"). */
@@ -215,8 +250,11 @@ interface CreateBillingPlanInput {
      * criar um plano avulso, sem página pública, usado no fluxo simplificado de
      * checkout/confirmação (`checkoutPlan`/`confirmPlanSubscription`). */
     plan_page_id?: string;
-    /** Item de catálogo (BillingItem) do qual nome/preço são copiados na criação. */
-    item_id: string;
+    /**
+     * Item de catálogo (BillingItem) do qual nome/preço são copiados na criação. Opcional:
+     * sem ele, informe `name` e `amount` — o plano é manual e um item é criado para ele.
+     */
+    item_id?: string;
     name?: string;
     description?: string;
     amount?: number;
@@ -314,6 +352,8 @@ interface CompanyTaxIdData {
     legal_nature: string | null;
     email: string | null;
     phone: string | null;
+    /** Inscrição estadual (quando a fonte informa). */
+    state_registration: string | null;
     address_line1: string | null;
     address_number: string | null;
     address_line2: string | null;
@@ -322,6 +362,8 @@ interface CompanyTaxIdData {
     address_state: string | null;
     address_postal_code: string | null;
     address_country: string;
+    /** Base que respondeu: "minhareceita" | "brasilapi" | "cnpja" | "cnpjws" | "receitaws". */
+    source: string;
 }
 interface TaxIdLookupResult {
     tax_id: string;
@@ -603,20 +645,30 @@ interface CreateOrderResult {
     payment_ref: string;
     stripe_publishable_key: string | null;
 }
+interface CepLookupResult {
+    postal_code: string;
+    address_line1: string | null;
+    address_district: string | null;
+    address_city: string;
+    address_state: string;
+    address_country: "BR";
+    /** Base que respondeu: "viacep" | "brasilapi" | "opencep" | "awesomeapi" | "apicep". */
+    source: string;
+}
 
 declare class ChargesResource {
     private readonly http;
     constructor(http: HttpClient);
     list(params?: {
         installment_group_id?: string;
-    }): Promise<Charge[]>;
+    }, opts?: RequestOptions): Promise<Charge[]>;
     /**
      * Cria uma cobrança (PIX, boleto ou cartão). A geração de fato acontece de forma
      * assíncrona no backend — a resposta volta com a charge em PENDING, sem os campos
      * do método (QR code, boleto, etc) ainda preenchidos. Use `get`/`getStatus` para
      * acompanhar até que estejam prontos.
      */
-    create(input: CreateChargeInput): Promise<CreateChargeResult>;
+    create(input: CreateChargeInput, opts?: RequestOptions): Promise<CreateChargeResult>;
     /**
      * Cobrança avulsa simples, sempre em cartão — cobra direto no cartão padrão já
      * salvo do cliente (sem fricção nenhuma). Se ele ainda não tiver um cartão salvo,
@@ -630,16 +682,16 @@ declare class ChargesResource {
      * }
      * ```
      */
-    charge(customerId: string, amountCents: number, options?: Omit<QuickChargeInput, "customer_id" | "amount">): Promise<QuickChargeResult>;
-    get(id: string): Promise<Charge>;
-    getStatus(id: string): Promise<{
+    charge(customerId: string, amountCents: number, options?: Omit<QuickChargeInput, "customer_id" | "amount">, opts?: RequestOptions): Promise<QuickChargeResult>;
+    get(id: string, opts?: RequestOptions): Promise<Charge>;
+    getStatus(id: string, opts?: RequestOptions): Promise<{
         status: Charge["status"];
     }>;
-    cancel(id: string): Promise<Charge>;
-    refund(id: string): Promise<Charge>;
+    cancel(id: string, opts?: RequestOptions): Promise<Charge>;
+    refund(id: string, opts?: RequestOptions): Promise<Charge>;
 }
 
-interface WaitUntilPaidOptions {
+interface WaitUntilPaidOptions extends RequestOptions {
     /** Intervalo entre tentativas, em ms. Default: 2000. */
     intervalMs?: number;
     /** Tempo máximo de espera antes de desistir, em ms. Default: 5 minutos. */
@@ -651,7 +703,7 @@ declare class CheckoutResource {
     /** Consulta o status atual de uma cobrança/checkout pelo `checkout_token` retornado
      * por `plans.checkout()` (ou qualquer outro fluxo de cobrança do SDK). Sincroniza com
      * o provedor de pagamento sob o capô quando ainda está PENDING. */
-    getStatus(checkoutToken: string): Promise<CheckoutStatusResult>;
+    getStatus(checkoutToken: string, opts?: RequestOptions): Promise<CheckoutStatusResult>;
     /**
      * Faz polling de `getStatus` até o pagamento ser confirmado (ou falhar/expirar) — é
      * a forma recomendada de confirmar, depois de redirecionar o cliente para a
@@ -666,11 +718,11 @@ declare class CheckoutResource {
 declare class CouponsResource {
     private readonly http;
     constructor(http: HttpClient);
-    list(): Promise<Coupon[]>;
+    list(opts?: RequestOptions): Promise<Coupon[]>;
     /** `idOrCode` aceita tanto o id interno (`coupon.id`) quanto o `code` legível que você
      * escolheu na criação (ex: `"BEMVINDO20"`) — normalmente é mais prático guardar/usar o
      * `code`, já que é você quem o define e é o que aparece para o cliente final. */
-    get(idOrCode: string): Promise<Coupon>;
+    get(idOrCode: string, opts?: RequestOptions): Promise<Coupon>;
     /**
      * Cria um cupom de desconto — o `code` é o que o cliente final informa no checkout
      * (`plans.checkout(planId, { coupon_code })`).
@@ -685,33 +737,35 @@ declare class CouponsResource {
      * });
      * ```
      */
-    create(input: CreateCouponInput): Promise<Coupon>;
+    create(input: CreateCouponInput, opts?: RequestOptions): Promise<Coupon>;
     /** Só permite editar limites/validade/ativação — o desconto em si (type/value/duration)
      * de um cupom já criado é imutável; crie um novo código para mudar o valor do desconto.
      * `idOrCode` aceita id interno ou `code` (ver `get`). */
     update(idOrCode: string, input: Partial<Pick<CreateCouponInput, "max_redemptions" | "expires_at">> & {
         active?: boolean;
-    }): Promise<Coupon>;
+    }, opts?: RequestOptions): Promise<Coupon>;
     /** Desativa o cupom (soft-delete) — códigos já resgatados continuam no histórico.
      * `idOrCode` aceita id interno ou `code` (ver `get`). */
-    remove(idOrCode: string): Promise<void>;
+    remove(idOrCode: string, opts?: RequestOptions): Promise<void>;
 }
 
 declare class CustomersResource {
     private readonly http;
     constructor(http: HttpClient);
     /** Lista clientes — opcionalmente filtrando por `external_ref`, `tax_id` ou `customer_type`. */
-    list(filters?: CustomerListFilters): Promise<Customer[]>;
+    list(filters?: CustomerListFilters, opts?: RequestOptions): Promise<Customer[]>;
     /**
      * Busca o cliente de cobrança pela referência do seu app (ex: `"company:456"`). Use ao
      * trocar de conta (pessoal ↔ empresa) para operar nos cartões da conta ativa.
      */
-    findByExternalRef(externalRef: string): Promise<Customer | null>;
+    findByExternalRef(externalRef: string, opts?: RequestOptions): Promise<Customer | null>;
     /**
      * Valida um CPF/CNPJ e, para CNPJ, retorna razão social, nome fantasia e endereço da
      * Receita Federal — use para pré-preencher o cadastro assim que o usuário digitar.
+     * Consulta em cascata (Minha Receita → BrasilAPI → CNPJá → CNPJ.ws → ReceitaWS); 404
+     * quando nenhuma base encontra o CNPJ, 502 quando todas falham.
      */
-    lookupTaxId(taxId: string): Promise<TaxIdLookupResult>;
+    lookupTaxId(taxId: string, opts?: RequestOptions): Promise<TaxIdLookupResult>;
     /**
      * Cria um cliente pessoa física (CPF) ou empresa (CNPJ). Para CNPJ, os campos não
      * informados (razão social, endereço...) são completados com os dados da Receita.
@@ -721,15 +775,27 @@ declare class CustomersResource {
      * await client.customers.create({ tax_id: "11.222.333/0001-81", email: "fin@acme.com", external_ref: "company:456" });
      * ```
      */
-    create(input: CustomerInput): Promise<Customer>;
-    get(id: string): Promise<Customer>;
+    /**
+     * Busca o endereço de um CEP (ViaCEP → BrasilAPI → OpenCEP → AwesomeAPI → ApiCEP, em
+     * cascata). 404 quando nenhuma base conhece o CEP, 502 quando todas falham.
+     */
+    lookupCep(cep: string, opts?: RequestOptions): Promise<CepLookupResult>;
+    /**
+     * Ressincroniza razão social, nome fantasia e endereço de um cliente empresa com o
+     * registro atual da Receita Federal — único jeito de alterar esses campos.
+     */
+    refreshRegistry(id: string, opts?: RequestOptions): Promise<Customer & {
+        registry_source: string;
+    }>;
+    create(input: CustomerInput, opts?: RequestOptions): Promise<Customer>;
+    get(id: string, opts?: RequestOptions): Promise<Customer>;
     /** Atualiza dados de cobrança do cliente (nome, e-mail, endereço, CPF/CNPJ, razão social...). */
-    update(id: string, input: CustomerUpdateInput): Promise<Customer>;
+    update(id: string, input: CustomerUpdateInput, opts?: RequestOptions): Promise<Customer>;
     /**
      * Lista os métodos de pagamento salvos do cliente — nunca expõe o número completo do
      * cartão, só os 4 últimos dígitos, bandeira e validade.
      */
-    listPaymentMethods(id: string): Promise<PaymentMethodSummary[]>;
+    listPaymentMethods(id: string, opts?: RequestOptions): Promise<PaymentMethodSummary[]>;
     /**
      * Cria um SetupIntent para o cliente cadastrar um novo cartão — use o `clientSecret`
      * retornado com Stripe.js/Elements no frontend do seu app para coletar e confirmar o
@@ -740,11 +806,11 @@ declare class CustomersResource {
      * // no frontend: stripe.confirmCardSetup(clientSecret, { payment_method: {...} })
      * ```
      */
-    createPaymentMethodSetupIntent(id: string): Promise<PaymentMethodSetupIntent>;
+    createPaymentMethodSetupIntent(id: string, opts?: RequestOptions): Promise<PaymentMethodSetupIntent>;
     /** Define um método de pagamento salvo como o padrão do cliente (usado em cobranças off-session). */
-    setDefaultPaymentMethod(id: string, paymentMethodId: string): Promise<void>;
+    setDefaultPaymentMethod(id: string, paymentMethodId: string, opts?: RequestOptions): Promise<void>;
     /** Remove um método de pagamento salvo do cliente. */
-    deletePaymentMethod(id: string, paymentMethodId: string): Promise<void>;
+    deletePaymentMethod(id: string, paymentMethodId: string, opts?: RequestOptions): Promise<void>;
 }
 
 interface ItemInput {
@@ -756,10 +822,10 @@ interface ItemInput {
 declare class ItemsResource {
     private readonly http;
     constructor(http: HttpClient);
-    list(): Promise<BillingItem[]>;
-    create(input: ItemInput): Promise<BillingItem>;
-    get(id: string): Promise<BillingItem>;
-    update(id: string, input: Partial<ItemInput>): Promise<BillingItem>;
+    list(opts?: RequestOptions): Promise<BillingItem[]>;
+    create(input: ItemInput, opts?: RequestOptions): Promise<BillingItem>;
+    get(id: string, opts?: RequestOptions): Promise<BillingItem>;
+    update(id: string, input: Partial<ItemInput>, opts?: RequestOptions): Promise<BillingItem>;
 }
 
 declare class OrdersResource {
@@ -771,27 +837,27 @@ declare class OrdersResource {
      * confirmar via Stripe Elements — as parcelas seguintes são cobradas
      * automaticamente pelo backend no cartão salvo.
      */
-    create(input: CreateOrderInput): Promise<CreateOrderResult>;
-    list(): Promise<unknown[]>;
-    get(id: string): Promise<unknown>;
+    create(input: CreateOrderInput, opts?: RequestOptions): Promise<CreateOrderResult>;
+    list(opts?: RequestOptions): Promise<unknown[]>;
+    get(id: string, opts?: RequestOptions): Promise<unknown>;
 }
 
 declare class PlansResource {
     private readonly http;
     constructor(http: HttpClient);
-    list(): Promise<BillingPlanSummary[]>;
-    get(id: string): Promise<BillingPlanSummary>;
-    create(input: CreateBillingPlanInput): Promise<BillingPlanSummary>;
+    list(opts?: RequestOptions): Promise<BillingPlanSummary[]>;
+    get(id: string, opts?: RequestOptions): Promise<BillingPlanSummary>;
+    create(input: CreateBillingPlanInput, opts?: RequestOptions): Promise<BillingPlanSummary>;
     update(id: string, input: Partial<CreateBillingPlanInput> & {
         active?: boolean;
-    }): Promise<BillingPlanSummary>;
+    }, opts?: RequestOptions): Promise<BillingPlanSummary>;
     /** Não há hard-delete de planos (assinaturas existentes ainda referenciam) — para
      * remover um plano do catálogo público, arquive-o. */
-    archive(id: string): Promise<BillingPlanSummary>;
+    archive(id: string, opts?: RequestOptions): Promise<BillingPlanSummary>;
     /** Vincula um plano avulso a uma página de planos existente (mesma org). */
-    attachToPage(planId: string, pageId: string): Promise<BillingPlanSummary>;
+    attachToPage(planId: string, pageId: string, opts?: RequestOptions): Promise<BillingPlanSummary>;
     /** Desvincula um plano da sua página, tornando-o avulso (sem página pública). */
-    detachFromPage(planId: string): Promise<BillingPlanSummary>;
+    detachFromPage(planId: string, opts?: RequestOptions): Promise<BillingPlanSummary>;
     /**
      * Fluxo simplificado de assinatura para um `Customer` já cadastrado na sua org
      * (autenticado, sem formulário de nome/e-mail): cria a assinatura + cobrança inicial e
@@ -810,15 +876,15 @@ declare class PlansResource {
      * }
      * ```
      */
-    checkoutPlan(planId: string, customerId: string, input?: CheckoutForCustomerInput): Promise<CheckoutForCustomerResult>;
+    checkoutPlan(planId: string, customerId: string, input?: CheckoutForCustomerInput, opts?: RequestOptions): Promise<CheckoutForCustomerResult>;
     /** Verifica se um `Customer` tem uma assinatura ativa deste plano (a mais recente),
      * contraparte de `checkoutPlan` no fluxo simplificado autenticado. */
-    confirmPlanSubscription(planId: string, customerId: string): Promise<PlanSubscriptionStatusResult>;
+    confirmPlanSubscription(planId: string, customerId: string, opts?: RequestOptions): Promise<PlanSubscriptionStatusResult>;
     /** Lista os planos ativos de uma org pelo slug público — página fixa legada, sem
      * suporte a múltiplas páginas. Prefira `getPublicPage` para orgs com várias páginas. */
-    listPublic(orgSlug: string): Promise<ListPublicPlansResult>;
+    listPublic(orgSlug: string, opts?: RequestOptions): Promise<ListPublicPlansResult>;
     /** Busca uma página de planos pública específica pelo slug da org + slug da página. */
-    getPublicPage(orgSlug: string, pageSlug: string): Promise<GetPublicPlanPageResult>;
+    getPublicPage(orgSlug: string, pageSlug: string, opts?: RequestOptions): Promise<GetPublicPlanPageResult>;
     /**
      * Inicia a assinatura de um plano para um cliente final: cria (ou reaproveita) o
      * `Customer` pelo e-mail, cria a `Subscription` e retorna uma URL de checkout hospedada
@@ -841,14 +907,14 @@ declare class PlansResource {
      * Não requer autenticação — pode ser chamado a partir do backend do dev sem token de
      * service account, ou do próprio SDK server-side usando qualquer token válido.
      */
-    checkout(planId: string, input: PlanCheckoutInput): Promise<PlanCheckoutResult>;
+    checkout(planId: string, input: PlanCheckoutInput, opts?: RequestOptions): Promise<PlanCheckoutResult>;
 }
 
 declare class SubscriptionsResource {
     private readonly http;
     constructor(http: HttpClient);
     /** Requer autenticação (service account) — lista todas as assinaturas da sua org. */
-    list(): Promise<Subscription[]>;
+    list(opts?: RequestOptions): Promise<Subscription[]>;
     /**
      * Fluxo legado de assinatura por `BillingItem` avulso (sem `BillingPlan`) — requer
      * autenticação (service account) e que `customer_id`/`item_id` já existam na sua org.
@@ -860,9 +926,9 @@ declare class SubscriptionsResource {
      * });
      * ```
      */
-    create(input: CreateSubscriptionInput): Promise<CreateSubscriptionResult>;
+    create(input: CreateSubscriptionInput, opts?: RequestOptions): Promise<CreateSubscriptionResult>;
     /** Requer autenticação (service account). */
-    get(id: string): Promise<Subscription>;
+    get(id: string, opts?: RequestOptions): Promise<Subscription>;
     /**
      * Cancela uma assinatura — requer autenticação (service account). Cancela no provedor
      * (Stripe) quando aplicável, marca cobranças pendentes como CANCELLED, e notifica o
@@ -876,7 +942,7 @@ declare class SubscriptionsResource {
      * await client.subscriptions.cancel(subId, { policy: "END_OF_PERIOD" });
      * ```
      */
-    cancel(id: string, input: CancelSubscriptionInput): Promise<Subscription>;
+    cancel(id: string, input: CancelSubscriptionInput, opts?: RequestOptions): Promise<Subscription>;
     /**
      * Reverte um cancelamento agendado (cancel_at_period_end) — requer autenticação
      * (service account). Só se aplica enquanto a assinatura ainda está ACTIVE com o
@@ -884,7 +950,7 @@ declare class SubscriptionsResource {
      * uma vez CANCELLED de fato, a Subscription já foi encerrada no Stripe e não há o que
      * reverter — chame `cancel`/checkout novamente para recomeçar.
      */
-    resume(id: string): Promise<Subscription>;
+    resume(id: string, opts?: RequestOptions): Promise<Subscription>;
     /**
      * Calcula o preview de uma troca de plano (não muta nada) — requer autenticação
      * (service account). Use para mostrar ao dono da org o valor devido/estimado antes de
@@ -896,7 +962,7 @@ declare class SubscriptionsResource {
      * });
      * ```
      */
-    previewPlanSwap(id: string, input: SwapPlanInput): Promise<SwapPlanPreviewResult>;
+    previewPlanSwap(id: string, input: SwapPlanInput, opts?: RequestOptions): Promise<SwapPlanPreviewResult>;
     /**
      * Executa a troca de plano/item de uma assinatura já existente (upgrade/downgrade de
      * tier) — requer autenticação (service account). Executa a troca diretamente, sem
@@ -929,7 +995,7 @@ declare class SubscriptionsResource {
      * }
      * ```
      */
-    swapPlan(id: string, input: SwapPlanInput): Promise<SwapPlanResult>;
+    swapPlan(id: string, input: SwapPlanInput, opts?: RequestOptions): Promise<SwapPlanResult>;
     /**
      * Cancela uma troca de plano ainda pendente (aguardando confirmação de pagamento ou
      * renovação — `policy: "AT_RENEWAL"` ou upgrade IMMEDIATE com proration nativa) — requer
@@ -942,7 +1008,7 @@ declare class SubscriptionsResource {
      * await client.subscriptions.cancelPendingPlanSwap(subId);
      * ```
      */
-    cancelPendingPlanSwap(id: string): Promise<Subscription>;
+    cancelPendingPlanSwap(id: string, opts?: RequestOptions): Promise<Subscription>;
     /**
      * Verifica se uma assinatura está ativa e qual item ela cobre, usando o
      * `management_token` retornado por `plans.checkout()` — rota pública, sem
@@ -956,7 +1022,7 @@ declare class SubscriptionsResource {
      * }
      * ```
      */
-    checkByToken(managementToken: string): Promise<SubscriptionStatusResult>;
+    checkByToken(managementToken: string, opts?: RequestOptions): Promise<SubscriptionStatusResult>;
 }
 
 type OutboundWebhookEventType = "SUBSCRIPTION_CREATED" | "SUBSCRIPTION_ACTIVATED" | "SUBSCRIPTION_RENEWED" | "SUBSCRIPTION_PLAN_SWAPPED" | "SUBSCRIPTION_PAST_DUE" | "SUBSCRIPTION_CANCELLED" | "SUBSCRIPTION_CANCEL_SCHEDULE" | "SUBSCRIPTION_RESUMED" | "CHARGE_PAID" | "CHARGE_FAILED" | "CHARGE_EXPIRED" | "CHARGE_REFUNDED";
@@ -1084,7 +1150,7 @@ declare class WebhooksResource {
     private readonly http;
     constructor(http: HttpClient);
     /** Lista os webhooks outbound cadastrados na sua org (secret sempre mascarado). */
-    list(): Promise<WebhookEndpointSummary[]>;
+    list(opts?: RequestOptions): Promise<WebhookEndpointSummary[]>;
     /**
      * Registra um webhook outbound — idempotente por (org, url): chamar de novo com a
      * mesma URL apenas atualiza os `eventTypes`, sem criar duplicata. Guarde o `secret`
@@ -1092,14 +1158,14 @@ declare class WebhooksResource {
      * `X-Geekapps-Signature` nas entregas recebidas. Passe `secret` para definir o seu
      * próprio signing secret; se omitido, um valor aleatório é gerado automaticamente.
      */
-    register(input: WebhookEndpointInput): Promise<WebhookEndpointSummary>;
+    register(input: WebhookEndpointInput, opts?: RequestOptions): Promise<WebhookEndpointSummary>;
     /** Edita um webhook existente — URL, eventos assinados e/ou status ativo/inativo. */
     update(id: string, input: Partial<WebhookEndpointInput> & {
         active?: boolean;
-    }): Promise<WebhookEndpointSummary>;
+    }, opts?: RequestOptions): Promise<WebhookEndpointSummary>;
     /** Gera um novo secret e substitui o atual — a versão antiga deixa de validar imediatamente. */
-    rotateSecret(id: string): Promise<WebhookEndpointSummary>;
-    remove(id: string): Promise<void>;
+    rotateSecret(id: string, opts?: RequestOptions): Promise<WebhookEndpointSummary>;
+    remove(id: string, opts?: RequestOptions): Promise<void>;
 }
 
 interface BillingClientOptions extends Omit<HttpClientOptions, "baseUrl"> {
@@ -1116,7 +1182,24 @@ declare class BillingClient {
     readonly plans: PlansResource;
     readonly subscriptions: SubscriptionsResource;
     readonly webhooks: WebhooksResource;
+    private readonly options;
+    /**
+     * O `mode` passado aqui é o modo geral (default "prod"). Qualquer método aceita um
+     * override por chamada no último parâmetro — ex.: `charges.create(input, { mode: "dev" })`
+     * — ou use `withMode("dev")` para um bloco inteiro de chamadas.
+     */
     constructor(options: HttpClientOptions);
+    /**
+     * Cópia do cliente com outro modo (mesmas credenciais) — útil para várias chamadas
+     * seguidas em dev sem repetir `{ mode: "dev" }` em cada uma.
+     *
+     * ```ts
+     * const dev = billing.withMode("dev");
+     * const customer = await dev.customers.create({ ... });
+     * await dev.charges.create({ customer_id: customer.id, ... });
+     * ```
+     */
+    withMode(mode: NonNullable<RequestOptions["mode"]>): BillingClient;
 }
 
 declare class BillingApiError extends Error {
@@ -1189,4 +1272,4 @@ type ExpirationUnit = "seconds" | "minutes" | "hours" | "days";
  */
 declare function expiresIn(value: number, unit: ExpirationUnit): number;
 
-export { type AppliedDiscount, BillingApiError, BillingClient, type BillingClientOptions, type BillingItem, type BillingPeriod, type BillingPlanSummary, type BillingPluginOptions, type BillingRecurringInterval, type BillingRecurringStatus, type BillingSubscriptionCancelReason, type CancelSubscriptionInput, type CancellationPolicy, type Charge, type ChargeEventData, type ChargeStatus, ChargesResource, type CheckoutForCustomerInput, type CheckoutForCustomerResult, CheckoutResource, type CheckoutSessionStatus, type CheckoutStatusResult, type CompanyTaxIdData, type Coupon, type CouponDuration, type CouponType, CouponsResource, type CreateBillingPlanInput, type CreateChargeInput, type CreateChargeResult, type CreateCouponInput, type CreateOrderInput, type CreateOrderResult, type CreateSubscriptionInput, type CreateSubscriptionResult, type Customer, type CustomerInput, type CustomerListFilters, type CustomerType, type CustomerUpdateInput, CustomersResource, type ExpirationUnit, type GetPublicPlanPageResult, HttpClient, type HttpClientOptions, type ItemInput, ItemsResource, type ListPublicPlansResult, OrdersResource, type OutboundWebhookEventType, type PaymentMethod, type PaymentMethodSetupIntent, type PaymentMethodSummary, type PlanCheckoutCustomerInput, type PlanCheckoutInput, type PlanCheckoutResult, type PlanSubscriptionStatusResult, PlansResource, type ProrationPolicy, type PublicBillingPlan, type PublicOrganization, type PublicPlanBranding, type QuickChargeInput, type QuickChargeResult, type ServiceAccountOptions, ServiceAccountTokenProvider, type Subscription, type SubscriptionItemSummary, type SubscriptionPlanSummary, type SubscriptionStatusResult, SubscriptionsResource, type SwapMode, type SwapPlanInput, type SwapPlanPreviewResult, type SwapPlanResult, type SwapPolicy, type TaxIdLookupResult, type TokenResolver, type WaitUntilPaidOptions, type WebhookEndpointInput, type WebhookEndpointSummary, type WebhookEvent, WebhooksResource, _default as billingPlugin, createServiceAccountToken, expiresIn };
+export { type AppliedDiscount, BillingApiError, BillingClient, type BillingClientOptions, type BillingItem, type BillingPeriod, type BillingPlanSummary, type BillingPluginOptions, type BillingRecurringInterval, type BillingRecurringStatus, type BillingSubscriptionCancelReason, type CancelSubscriptionInput, type CancellationPolicy, type CepLookupResult, type Charge, type ChargeEventData, type ChargeStatus, ChargesResource, type CheckoutForCustomerInput, type CheckoutForCustomerResult, CheckoutResource, type CheckoutSessionStatus, type CheckoutStatusResult, type CompanyTaxIdData, type Coupon, type CouponDuration, type CouponType, CouponsResource, type CreateBillingPlanInput, type CreateChargeInput, type CreateChargeResult, type CreateCouponInput, type CreateOrderInput, type CreateOrderResult, type CreateSubscriptionInput, type CreateSubscriptionResult, type Customer, type CustomerInput, type CustomerListFilters, type CustomerType, type CustomerUpdateInput, CustomersResource, type ExpirationUnit, type GetPublicPlanPageResult, HttpClient, type HttpClientOptions, type ItemInput, ItemsResource, type ListPublicPlansResult, OrdersResource, type OutboundWebhookEventType, type PaymentMethod, type PaymentMethodSetupIntent, type PaymentMethodSummary, type PlanCheckoutCustomerInput, type PlanCheckoutInput, type PlanCheckoutResult, type PlanSubscriptionStatusResult, PlansResource, type ProrationPolicy, type PublicBillingPlan, type PublicOrganization, type PublicPlanBranding, type QuickChargeInput, type QuickChargeResult, type RequestOptions, type ServiceAccountOptions, ServiceAccountTokenProvider, type Subscription, type SubscriptionItemSummary, type SubscriptionPlanSummary, type SubscriptionStatusResult, SubscriptionsResource, type SwapMode, type SwapPlanInput, type SwapPlanPreviewResult, type SwapPlanResult, type SwapPolicy, type TaxIdLookupResult, type TokenResolver, type WaitUntilPaidOptions, type WebhookEndpointInput, type WebhookEndpointSummary, type WebhookEvent, WebhooksResource, _default as billingPlugin, createServiceAccountToken, expiresIn };