@vitrindigital/node 0.1.0 → 0.3.0

package/README.md

@@ -24,6 +24,16 @@ const vitrin = new Vitrin({
 
 Use a chave `vd_test_*` em desenvolvimento e `vd_live_*` em produção.
 
+## Organizações LLC (US)
+
+Se a org é uma **US LLC** (`entity_type: "llc"`), os valores são em **USD**
+(campo `currency` nas transações); os métodos default são **cartão** e **Pix
+cross-border** (o cliente paga em BRL, a LLC recebe em USD). A liquidação é
+**automática**: os endpoints de saldo/recebíveis/transferências retornam
+`{ auto_payout: true }` em vez de saldo retido (não há saque/antecipação
+manual). O onboarding inclui verificação de identidade (KYC), hospedada ou
+embedded. Veja `docs/api/onboarding-llc.md` e `docs/api/differences-cnpj-llc.md`.
+
 ## Recursos
 
 ### Clientes

package/dist/index.cjs

@@ -214,6 +214,19 @@ var Charges = class {
       idempotencyKey
     });
   }
+  /**
+   * One-click buy: cobra usando o cartão preferido salvo do cliente.
+   * O cliente precisa ter um saved card (vide `customers.savedCard.create`).
+   * Retorna 422 `no_saved_card` se não houver cartão; 422 `card_expired` se vencido.
+   */
+  createWithSavedCard(params) {
+    const { idempotencyKey, ...body } = params;
+    return this.client.request("/charges/charge-saved/", {
+      method: "POST",
+      body,
+      idempotencyKey
+    });
+  }
   retrieve(id) {
     return this.client.request(`/transactions/${id}/`);
   }
@@ -243,11 +256,42 @@ var Charges = class {
 };
 
 // src/resources/customers.ts
+var SavedCardResource = class {
+  constructor(client) {
+    this.client = client;
+  }
+  client;
+  /** Tokeniza + persiste o cartão preferido do cliente (substitui o anterior). */
+  create(customerId, params) {
+    return this.client.request(`/customers/${customerId}/saved-card/`, {
+      method: "POST",
+      body: params
+    });
+  }
+  /** Retorna brand/last4/exp/holder — nunca o token. */
+  retrieve(customerId) {
+    return this.client.request(`/customers/${customerId}/saved-card/`);
+  }
+  delete(customerId) {
+    return this.client.request(`/customers/${customerId}/saved-card/`, {
+      method: "DELETE"
+    });
+  }
+  /** Gera URL assinada (JWT 24h) pro cliente final ver/remover o próprio cartão. */
+  createManagementLink(customerId) {
+    return this.client.request(
+      `/customers/${customerId}/saved-card/management-link/`,
+      { method: "POST" }
+    );
+  }
+};
 var Customers = class {
   constructor(client) {
     this.client = client;
+    this.savedCard = new SavedCardResource(client);
   }
   client;
+  savedCard;
   create(params) {
     return this.client.request("/customers/", {
       method: "POST",
@@ -271,6 +315,13 @@ var Customers = class {
   delete(id) {
     return this.client.request(`/customers/${id}/`, { method: "DELETE" });
   }
+  /** Gera link assinado de recompra one-click (JWT 15min, uso único). */
+  oneClickLink(customerId, params) {
+    return this.client.request(
+      `/customers/${customerId}/one-click-link/`,
+      { method: "POST", body: params }
+    );
+  }
 };
 
 // src/resources/plans.ts

package/dist/index.d.cts

@@ -43,8 +43,42 @@ declare class VitrinClient {
  * Mantidos como interfaces genéricas (em vez de unions super-precisas) pra
  * que mudanças não-quebra-API no backend não exijam major bump no SDK.
  */
-type PaymentMethod = 'PIX' | 'PIX_AUTOMATIC' | 'BOLETO' | 'CREDIT_CARD';
+/** ISO 4217. BRL é o default histórico; USD/EUR/GBP habilitados com orgs LLC. */
+type Currency = 'BRL' | 'USD' | 'EUR' | 'GBP';
+/** Tipo jurídico da organização. CNPJ = subconta Safe2Pay (Brasil),
+ *  LLC = Stripe Connect (US/internacional). */
+type EntityType = 'cnpj' | 'llc';
+/**
+ * Métodos de pagamento suportados pela plataforma.
+ *
+ * A disponibilidade por org é dinâmica — sempre cheque
+ * `Organization.enabled_payment_methods`. Por tipo de entidade:
+ *
+ * - CNPJ (BR): PIX, PIX_AUTOMATIC, BOLETO, CREDIT_CARD (default).
+ * - LLC (US): CREDIT_CARD por default. PIX está disponível cross-border
+ *   (o cliente paga em BRL, a liquidação é em USD) como opt-in habilitado
+ *   pela Vitrin. BOLETO NÃO se aplica a LLC (é Brasil-only). Os demais
+ *   métodos abaixo (cartão internacional / ACH / wallets / Klarna /
+ *   Afterpay) são reservados para evolução e podem não estar habilitados.
+ */
+type PaymentMethod = 'PIX' | 'PIX_AUTOMATIC' | 'BOLETO' | 'CREDIT_CARD' | 'CARD_INTERNATIONAL' | 'ACH_DEBIT' | 'SEPA_DEBIT' | 'APPLE_PAY' | 'GOOGLE_PAY' | 'KLARNA' | 'AFTERPAY';
 type TransactionStatus = 'pending' | 'confirmed' | 'received' | 'overdue' | 'refunded' | 'chargeback' | 'failed' | 'canceled';
+/**
+ * Representa a organização (subconta) dona da API key em uso.
+ *
+ * Nota: `default_currency` é derivado de `entity_type` no backend e pode
+ * ainda não estar exposto pelo serializer — a declaração aqui é
+ * forward-compatible para quando o backend passar a emiti-lo.
+ */
+interface Organization {
+    id: string;
+    name: string;
+    entity_type: EntityType;
+    default_currency: Currency;
+    enabled_payment_methods?: PaymentMethod[];
+    created_at: string;
+    updated_at: string;
+}
 interface Customer {
     id: string;
     name: string;
@@ -94,6 +128,11 @@ interface Subscription {
     canceled_at: string | null;
     created_at: string;
     updated_at: string;
+    /** LLC: moeda da assinatura (USD). Ausente/BRL para CNPJ. */
+    currency?: Currency;
+    /** LLC: secret de confirmação da 1ª cobrança — quando presente, confirme
+     *  com Stripe.js (cartão/SCA) antes da assinatura ficar ativa. */
+    client_secret?: string | null;
 }
 interface Transaction {
     id: string;
@@ -106,6 +145,16 @@ interface Transaction {
     platform_fee: string;
     provider_fee: string;
     billing_type: PaymentMethod;
+    /** ISO 4217. Default herdado de `Organization.default_currency` na criação. */
+    currency: Currency;
+    /** LLC: secret de confirmação — cartão (SCA/3DS) ou PIX (QR); confirme com
+     *  Stripe.js quando presente. Ausente para cobranças síncronas/CNPJ. */
+    client_secret?: string | null;
+    /** PIX-LLC cross-currency: o cliente vê BRL (`presentment_*`) e a LLC escritura
+     *  em USD (`currency`/`amount`); `exchange_rate` é o câmbio aplicado. */
+    presentment_currency?: Currency | null;
+    presentment_amount?: string | null;
+    exchange_rate?: string | null;
     installments: number;
     status: TransactionStatus;
     pix_qr_code?: string;
@@ -126,6 +175,27 @@ interface PaginatedList<T> {
     previous: string | null;
     results: T[];
 }
+/** Metadados do cartão salvo de um Customer (one-click buy). Nunca inclui o token. */
+interface SavedCard {
+    brand: string;
+    last4: string;
+    exp_month: number | null;
+    exp_year: number | null;
+    holder_name: string;
+    consent_at: string | null;
+}
+/** Resposta de POST /customers/{id}/saved-card/management-link/. */
+interface SavedCardManagementLink {
+    url: string;
+    token: string;
+    expires_at: string;
+}
+/** Resposta de POST /customers/{id}/one-click-link/. */
+interface OneClickLink {
+    url: string;
+    token: string;
+    expires_at: string;
+}
 /** Response do GET /balance/. */
 interface Balance {
     available: number;
@@ -168,6 +238,15 @@ interface CreateChargeParams {
     /** Idempotency-Key (header) — recomendado pra evitar duplo-débito em retry. */
     idempotencyKey?: string;
 }
+interface CreateChargeWithSavedCardParams {
+    customer_id: string;
+    amount: number | string;
+    description?: string;
+    installments?: number;
+    external_reference?: string;
+    /** Idempotency-Key (header) — recomendado pra evitar duplo-débito em retry. */
+    idempotencyKey?: string;
+}
 interface RefundParams {
     /** Valor parcial em reais. Omitir = reembolso total. */
     amount?: number | string;
@@ -188,6 +267,12 @@ declare class Charges {
     constructor(client: VitrinClient);
     /** Cria uma cobrança avulsa (PIX/Boleto/Cartão). */
     create(params: CreateChargeParams): Promise<Transaction>;
+    /**
+     * One-click buy: cobra usando o cartão preferido salvo do cliente.
+     * O cliente precisa ter um saved card (vide `customers.savedCard.create`).
+     * Retorna 422 `no_saved_card` se não houver cartão; 422 `card_expired` se vencido.
+     */
+    createWithSavedCard(params: CreateChargeWithSavedCardParams): Promise<Transaction>;
     retrieve(id: string): Promise<Transaction>;
     list(params?: ListChargesParams): Promise<PaginatedList<Transaction>>;
     refund(id: string, params: RefundParams): Promise<Transaction>;
@@ -214,8 +299,33 @@ interface CreateCustomerParams {
     state?: string;
 }
 type UpdateCustomerParams = Partial<CreateCustomerParams>;
+interface SaveCardParams {
+    credit_card: {
+        holder_name: string;
+        number: string;
+        expiry_month: string;
+        expiry_year: string;
+        cvv: string;
+    };
+    consent: {
+        accepted_at: string;
+        ip: string;
+    };
+}
+declare class SavedCardResource {
+    private client;
+    constructor(client: VitrinClient);
+    /** Tokeniza + persiste o cartão preferido do cliente (substitui o anterior). */
+    create(customerId: string, params: SaveCardParams): Promise<SavedCard>;
+    /** Retorna brand/last4/exp/holder — nunca o token. */
+    retrieve(customerId: string): Promise<SavedCard>;
+    delete(customerId: string): Promise<void>;
+    /** Gera URL assinada (JWT 24h) pro cliente final ver/remover o próprio cartão. */
+    createManagementLink(customerId: string): Promise<SavedCardManagementLink>;
+}
 declare class Customers {
     private client;
+    readonly savedCard: SavedCardResource;
     constructor(client: VitrinClient);
     create(params: CreateCustomerParams): Promise<Customer>;
     retrieve(id: string): Promise<Customer>;
@@ -225,6 +335,16 @@ declare class Customers {
     }): Promise<PaginatedList<Customer>>;
     update(id: string, params: UpdateCustomerParams): Promise<Customer>;
     delete(id: string): Promise<void>;
+    /** Gera link assinado de recompra one-click (JWT 15min, uso único). */
+    oneClickLink(customerId: string, params: {
+        product_id?: string;
+        plan_id?: string;
+        amount?: string;
+        installments?: number;
+        coupon_code?: string;
+        bump_ids?: string[];
+        expires_in?: number;
+    }): Promise<OneClickLink>;
 }
 
 interface CreatePlanParams {
@@ -425,4 +545,4 @@ declare class Vitrin {
     request<T = unknown>(path: string, options?: Parameters<VitrinClient['request']>[1]): Promise<T>;
 }
 
-export { type Balance, type ConstructEventOptions, type Customer, type PaginatedList, type PaymentMethod, type Plan, type Product, type RequestOptions, type ScheduledReceivable, type ScheduledReceivablesResponse, type Subscription, type Transaction, type TransactionStatus, Vitrin, VitrinAuthError, type VitrinClientOptions, VitrinError, VitrinNetworkError, VitrinNotFoundError, VitrinRateLimitError, VitrinServerError, VitrinValidationError, type WebhookEvent, Webhooks };
+export { type Balance, type ConstructEventOptions, type Currency, type Customer, type EntityType, type Organization, type PaginatedList, type PaymentMethod, type Plan, type Product, type RequestOptions, type ScheduledReceivable, type ScheduledReceivablesResponse, type Subscription, type Transaction, type TransactionStatus, Vitrin, VitrinAuthError, type VitrinClientOptions, VitrinError, VitrinNetworkError, VitrinNotFoundError, VitrinRateLimitError, VitrinServerError, VitrinValidationError, type WebhookEvent, Webhooks };

package/dist/index.d.ts

@@ -43,8 +43,42 @@ declare class VitrinClient {
  * Mantidos como interfaces genéricas (em vez de unions super-precisas) pra
  * que mudanças não-quebra-API no backend não exijam major bump no SDK.
  */
-type PaymentMethod = 'PIX' | 'PIX_AUTOMATIC' | 'BOLETO' | 'CREDIT_CARD';
+/** ISO 4217. BRL é o default histórico; USD/EUR/GBP habilitados com orgs LLC. */
+type Currency = 'BRL' | 'USD' | 'EUR' | 'GBP';
+/** Tipo jurídico da organização. CNPJ = subconta Safe2Pay (Brasil),
+ *  LLC = Stripe Connect (US/internacional). */
+type EntityType = 'cnpj' | 'llc';
+/**
+ * Métodos de pagamento suportados pela plataforma.
+ *
+ * A disponibilidade por org é dinâmica — sempre cheque
+ * `Organization.enabled_payment_methods`. Por tipo de entidade:
+ *
+ * - CNPJ (BR): PIX, PIX_AUTOMATIC, BOLETO, CREDIT_CARD (default).
+ * - LLC (US): CREDIT_CARD por default. PIX está disponível cross-border
+ *   (o cliente paga em BRL, a liquidação é em USD) como opt-in habilitado
+ *   pela Vitrin. BOLETO NÃO se aplica a LLC (é Brasil-only). Os demais
+ *   métodos abaixo (cartão internacional / ACH / wallets / Klarna /
+ *   Afterpay) são reservados para evolução e podem não estar habilitados.
+ */
+type PaymentMethod = 'PIX' | 'PIX_AUTOMATIC' | 'BOLETO' | 'CREDIT_CARD' | 'CARD_INTERNATIONAL' | 'ACH_DEBIT' | 'SEPA_DEBIT' | 'APPLE_PAY' | 'GOOGLE_PAY' | 'KLARNA' | 'AFTERPAY';
 type TransactionStatus = 'pending' | 'confirmed' | 'received' | 'overdue' | 'refunded' | 'chargeback' | 'failed' | 'canceled';
+/**
+ * Representa a organização (subconta) dona da API key em uso.
+ *
+ * Nota: `default_currency` é derivado de `entity_type` no backend e pode
+ * ainda não estar exposto pelo serializer — a declaração aqui é
+ * forward-compatible para quando o backend passar a emiti-lo.
+ */
+interface Organization {
+    id: string;
+    name: string;
+    entity_type: EntityType;
+    default_currency: Currency;
+    enabled_payment_methods?: PaymentMethod[];
+    created_at: string;
+    updated_at: string;
+}
 interface Customer {
     id: string;
     name: string;
@@ -94,6 +128,11 @@ interface Subscription {
     canceled_at: string | null;
     created_at: string;
     updated_at: string;
+    /** LLC: moeda da assinatura (USD). Ausente/BRL para CNPJ. */
+    currency?: Currency;
+    /** LLC: secret de confirmação da 1ª cobrança — quando presente, confirme
+     *  com Stripe.js (cartão/SCA) antes da assinatura ficar ativa. */
+    client_secret?: string | null;
 }
 interface Transaction {
     id: string;
@@ -106,6 +145,16 @@ interface Transaction {
     platform_fee: string;
     provider_fee: string;
     billing_type: PaymentMethod;
+    /** ISO 4217. Default herdado de `Organization.default_currency` na criação. */
+    currency: Currency;
+    /** LLC: secret de confirmação — cartão (SCA/3DS) ou PIX (QR); confirme com
+     *  Stripe.js quando presente. Ausente para cobranças síncronas/CNPJ. */
+    client_secret?: string | null;
+    /** PIX-LLC cross-currency: o cliente vê BRL (`presentment_*`) e a LLC escritura
+     *  em USD (`currency`/`amount`); `exchange_rate` é o câmbio aplicado. */
+    presentment_currency?: Currency | null;
+    presentment_amount?: string | null;
+    exchange_rate?: string | null;
     installments: number;
     status: TransactionStatus;
     pix_qr_code?: string;
@@ -126,6 +175,27 @@ interface PaginatedList<T> {
     previous: string | null;
     results: T[];
 }
+/** Metadados do cartão salvo de um Customer (one-click buy). Nunca inclui o token. */
+interface SavedCard {
+    brand: string;
+    last4: string;
+    exp_month: number | null;
+    exp_year: number | null;
+    holder_name: string;
+    consent_at: string | null;
+}
+/** Resposta de POST /customers/{id}/saved-card/management-link/. */
+interface SavedCardManagementLink {
+    url: string;
+    token: string;
+    expires_at: string;
+}
+/** Resposta de POST /customers/{id}/one-click-link/. */
+interface OneClickLink {
+    url: string;
+    token: string;
+    expires_at: string;
+}
 /** Response do GET /balance/. */
 interface Balance {
     available: number;
@@ -168,6 +238,15 @@ interface CreateChargeParams {
     /** Idempotency-Key (header) — recomendado pra evitar duplo-débito em retry. */
     idempotencyKey?: string;
 }
+interface CreateChargeWithSavedCardParams {
+    customer_id: string;
+    amount: number | string;
+    description?: string;
+    installments?: number;
+    external_reference?: string;
+    /** Idempotency-Key (header) — recomendado pra evitar duplo-débito em retry. */
+    idempotencyKey?: string;
+}
 interface RefundParams {
     /** Valor parcial em reais. Omitir = reembolso total. */
     amount?: number | string;
@@ -188,6 +267,12 @@ declare class Charges {
     constructor(client: VitrinClient);
     /** Cria uma cobrança avulsa (PIX/Boleto/Cartão). */
     create(params: CreateChargeParams): Promise<Transaction>;
+    /**
+     * One-click buy: cobra usando o cartão preferido salvo do cliente.
+     * O cliente precisa ter um saved card (vide `customers.savedCard.create`).
+     * Retorna 422 `no_saved_card` se não houver cartão; 422 `card_expired` se vencido.
+     */
+    createWithSavedCard(params: CreateChargeWithSavedCardParams): Promise<Transaction>;
     retrieve(id: string): Promise<Transaction>;
     list(params?: ListChargesParams): Promise<PaginatedList<Transaction>>;
     refund(id: string, params: RefundParams): Promise<Transaction>;
@@ -214,8 +299,33 @@ interface CreateCustomerParams {
     state?: string;
 }
 type UpdateCustomerParams = Partial<CreateCustomerParams>;
+interface SaveCardParams {
+    credit_card: {
+        holder_name: string;
+        number: string;
+        expiry_month: string;
+        expiry_year: string;
+        cvv: string;
+    };
+    consent: {
+        accepted_at: string;
+        ip: string;
+    };
+}
+declare class SavedCardResource {
+    private client;
+    constructor(client: VitrinClient);
+    /** Tokeniza + persiste o cartão preferido do cliente (substitui o anterior). */
+    create(customerId: string, params: SaveCardParams): Promise<SavedCard>;
+    /** Retorna brand/last4/exp/holder — nunca o token. */
+    retrieve(customerId: string): Promise<SavedCard>;
+    delete(customerId: string): Promise<void>;
+    /** Gera URL assinada (JWT 24h) pro cliente final ver/remover o próprio cartão. */
+    createManagementLink(customerId: string): Promise<SavedCardManagementLink>;
+}
 declare class Customers {
     private client;
+    readonly savedCard: SavedCardResource;
     constructor(client: VitrinClient);
     create(params: CreateCustomerParams): Promise<Customer>;
     retrieve(id: string): Promise<Customer>;
@@ -225,6 +335,16 @@ declare class Customers {
     }): Promise<PaginatedList<Customer>>;
     update(id: string, params: UpdateCustomerParams): Promise<Customer>;
     delete(id: string): Promise<void>;
+    /** Gera link assinado de recompra one-click (JWT 15min, uso único). */
+    oneClickLink(customerId: string, params: {
+        product_id?: string;
+        plan_id?: string;
+        amount?: string;
+        installments?: number;
+        coupon_code?: string;
+        bump_ids?: string[];
+        expires_in?: number;
+    }): Promise<OneClickLink>;
 }
 
 interface CreatePlanParams {
@@ -425,4 +545,4 @@ declare class Vitrin {
     request<T = unknown>(path: string, options?: Parameters<VitrinClient['request']>[1]): Promise<T>;
 }
 
-export { type Balance, type ConstructEventOptions, type Customer, type PaginatedList, type PaymentMethod, type Plan, type Product, type RequestOptions, type ScheduledReceivable, type ScheduledReceivablesResponse, type Subscription, type Transaction, type TransactionStatus, Vitrin, VitrinAuthError, type VitrinClientOptions, VitrinError, VitrinNetworkError, VitrinNotFoundError, VitrinRateLimitError, VitrinServerError, VitrinValidationError, type WebhookEvent, Webhooks };
+export { type Balance, type ConstructEventOptions, type Currency, type Customer, type EntityType, type Organization, type PaginatedList, type PaymentMethod, type Plan, type Product, type RequestOptions, type ScheduledReceivable, type ScheduledReceivablesResponse, type Subscription, type Transaction, type TransactionStatus, Vitrin, VitrinAuthError, type VitrinClientOptions, VitrinError, VitrinNetworkError, VitrinNotFoundError, VitrinRateLimitError, VitrinServerError, VitrinValidationError, type WebhookEvent, Webhooks };

package/dist/index.js

@@ -180,6 +180,19 @@ var Charges = class {
       idempotencyKey
     });
   }
+  /**
+   * One-click buy: cobra usando o cartão preferido salvo do cliente.
+   * O cliente precisa ter um saved card (vide `customers.savedCard.create`).
+   * Retorna 422 `no_saved_card` se não houver cartão; 422 `card_expired` se vencido.
+   */
+  createWithSavedCard(params) {
+    const { idempotencyKey, ...body } = params;
+    return this.client.request("/charges/charge-saved/", {
+      method: "POST",
+      body,
+      idempotencyKey
+    });
+  }
   retrieve(id) {
     return this.client.request(`/transactions/${id}/`);
   }
@@ -209,11 +222,42 @@ var Charges = class {
 };
 
 // src/resources/customers.ts
+var SavedCardResource = class {
+  constructor(client) {
+    this.client = client;
+  }
+  client;
+  /** Tokeniza + persiste o cartão preferido do cliente (substitui o anterior). */
+  create(customerId, params) {
+    return this.client.request(`/customers/${customerId}/saved-card/`, {
+      method: "POST",
+      body: params
+    });
+  }
+  /** Retorna brand/last4/exp/holder — nunca o token. */
+  retrieve(customerId) {
+    return this.client.request(`/customers/${customerId}/saved-card/`);
+  }
+  delete(customerId) {
+    return this.client.request(`/customers/${customerId}/saved-card/`, {
+      method: "DELETE"
+    });
+  }
+  /** Gera URL assinada (JWT 24h) pro cliente final ver/remover o próprio cartão. */
+  createManagementLink(customerId) {
+    return this.client.request(
+      `/customers/${customerId}/saved-card/management-link/`,
+      { method: "POST" }
+    );
+  }
+};
 var Customers = class {
   constructor(client) {
     this.client = client;
+    this.savedCard = new SavedCardResource(client);
   }
   client;
+  savedCard;
   create(params) {
     return this.client.request("/customers/", {
       method: "POST",
@@ -237,6 +281,13 @@ var Customers = class {
   delete(id) {
     return this.client.request(`/customers/${id}/`, { method: "DELETE" });
   }
+  /** Gera link assinado de recompra one-click (JWT 15min, uso único). */
+  oneClickLink(customerId, params) {
+    return this.client.request(
+      `/customers/${customerId}/one-click-link/`,
+      { method: "POST", body: params }
+    );
+  }
 };
 
 // src/resources/plans.ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vitrindigital/node",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "SDK oficial Node.js para a API da Vitrin Digital",
   "type": "module",
   "main": "./dist/index.cjs",